xbsl-mcp-docs

xbsl-mcp-docs — MCP-сервер для локальной документации 1С:Элемент.

Сервер индексирует уже подготовленные каталоги документации topics и stdlib, принимает дополнительные пользовательские файлы в md и pdf, а затем отдает поиск и доступ к документам через MCP, браузерный UI и административное HTTP API.

Возможности

• полнотекстовый поиск на SQLite FTS5
• индексация html, md, pdf
• инкрементальная переиндексация только изменившихся файлов
• встроенный UI для поиска и администрирования
• загрузка md/pdf, включая кириллические имена файлов
• конфигурация источников через переменные окружения
• запуск локально или в Docker

Источники данных

Сервер работает с тремя типами источников:

• topics — основная документация
• stdlib — справочник по объектной модели и стандартной библиотеке
• uploads — пользовательские файлы в md и pdf

Быстрый запуск через Docker

1. Перейдите в каталог проекта:

cd xbsl-mcp-docs

2. Создайте каталоги для uploads и индекса:

mkdir -p data/uploads data/index

3. Создайте .env на основе .env.example и укажите пути к локальной документации:

HOST=0.0.0.0
PORT=8000
REINDEX_ON_STARTUP=false

TOPICS_HOST_PATH=/absolute/path/to/topics
STDLIB_HOST_PATH=/absolute/path/to/stdlib
UPLOADS_HOST_PATH=./data/uploads
INDEX_HOST_PATH=./data/index

ADMIN_USERNAME=
ADMIN_PASSWORD=

4. Запустите сервер:

docker compose up --build -d

5. Откройте:

• http://127.0.0.1:8000/
• http://127.0.0.1:8000/ui
• http://127.0.0.1:8000/ui/admin
• http://127.0.0.1:8000/health

Остановить сервер:

docker compose down

Локальный запуск без Docker

Требования:

• Python 3.12+
• uv

Установка зависимостей:

uv sync --group dev

Запуск:

export TOPICS_ROOT=/absolute/path/to/topics
export STDLIB_ROOT=/absolute/path/to/stdlib
export UPLOADS_ROOT=./data/uploads
export INDEX_DB_PATH=./data/index/docs.db

uv run xbsl-mcp-docs

Конфигурация

Основные переменные окружения:

• HOST — адрес привязки, по умолчанию 0.0.0.0
• PORT — HTTP-порт, по умолчанию 8000
• TOPICS_ROOT — путь к topics
• STDLIB_ROOT — путь к stdlib
• UPLOADS_ROOT — путь к пользовательским файлам
• INDEX_DB_PATH — путь к SQLite-индексу
• REINDEX_ON_STARTUP — запускать ли индексацию при старте
• ADMIN_USERNAME, ADMIN_PASSWORD — optional basic auth для admin-маршрутов

В Docker используются host mount-переменные:

• TOPICS_HOST_PATH
• STDLIB_HOST_PATH
• UPLOADS_HOST_PATH
• INDEX_HOST_PATH

Важно: пути к topics, stdlib и uploads задаются только через переменные окружения или .env. Если вы меняете их в Docker, обновите .env, перезапустите контейнер и выполните reindex.

Маршруты

MCP

• /mcp — Streamable HTTP endpoint для MCP-клиентов
• /ui/mcp — браузерная страница с пояснением по MCP endpoint

UI

• / — главная страница
• /ui — поиск по документации
• /ui/admin — администрирование индекса
• /ui/operations — обзор операций и endpoint’ов

Admin API

• GET /health
• GET /admin/index/status
• POST /admin/index/rebuild
• POST /admin/upload

Примеры запросов

Принудительная переиндексация:

curl -X POST http://127.0.0.1:8000/admin/index/rebuild \
  -H 'Content-Type: application/json' \
  -d '{"force": true}'

Загрузка markdown или PDF:

curl -X POST 'http://127.0.0.1:8000/admin/upload?reindex=true' \
  -F 'file=@notes.md'

Разработка

Проверка кода:

./.venv/bin/ruff check src tests
./.venv/bin/pytest -q

License

MIT