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

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

cd xbsl-mcp-docs

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

mkdir -p data/uploads data/index

Создайте .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=

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

docker compose up --build -d

Откройте:

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

MCP Servers