1C Syntax Helper MCP (mcp-1c-helper)

Read-only MCP-сервер справки по синтаксису 1С:Предприятие 8.3. Ищет по индексу документации в общем Elasticsearch и отдаёт результат ИИ-агентам через MCP.

• Краткий запуск — QUICKSTART.md.

• Полный пошаговый мануал по Docker — docs/DEPLOYMENT.md.

Состав

src/
  server.py          FastMCP, 5 tools, streamable-http
  formatting.py      форматирование текстовых ответов
  search/            построение и ранжирование запросов
  parsers/           парсер .hbk + индексатор в Elasticsearch
  models/            pydantic-модели документации
  core/              конфиг, клиент ES, логирование, утилиты
scripts/
  index_hbk.py       standalone-индексатор .hbk
tests/               parser / search / ES
data/
  hbk/               сюда кладётся .hbk для индексации
compose.yml          один сервис + внешний ES

Related MCP server: mcp-1c-syntax-assistant

Окружение

• Elasticsearch: внешний сервис в сети — ELASTICSEARCH_URL (по умолчанию http://192.168.31.31:9200).

• Индекс задаётся в конфиге: ELASTICSEARCH_INDEX (по умолчанию help1c_docs_v2, семантический; help1c_docs — прежний лексический).

• Эмбеддинги: внешний сервис EMBEDDING_URL (http://192.168.31.32:8081/v1). Если пусто — поиск только лексический (BM25).

• MCP наружу публикуется на 8002: http://<host>:8002/mcp.

• Логи пишутся в /app/logs (том ./logs), уровень — LOG_LEVEL.

Поиск

• find_1c_help работает гибридно: BM25 + kNN по эмбеддингам, слияние через RRF.

• Остальные tools — по точному имени/объекту, лексический поиск.

• Eval качества (description-запросы): python -m scripts.eval_search. Ориентир на индексе help1c_docs_v2: Recall@3 ≈ 46%, Recall@5 ≈ 50%.

Запуск

cp .env.example .env      # при необходимости поправить URL/индекс
docker compose up -d --build

Проверка:

curl -s -X POST http://localhost:8002/mcp \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}'

MCP tools

• find_1c_help(query, limit=10) — поиск по имени, описанию или ключевым словам.

• get_quick_reference(element_name, object_name?) — краткий синтаксис и описание.

• get_syntax_info(element_name, object_name?, include_examples=true) — полная справка.

• list_object_members(object_name, member_type="all", limit=50) — методы/свойства/события объекта.

• search_by_context(query, context, object_name?, limit=10) — поиск с фильтром global|object|all.

Индексация .hbk

Автоиндексации при старте нет — индекс наполняется вручную.

# в контейнере (использует .env)
docker compose run --rm mcp-server python -m scripts.index_hbk --hbk data/hbk/shcntx_ru.hbk --reindex

# локально
pip install -r requirements.txt
python -m scripts.index_hbk --hbk data/hbk/shcntx_ru.hbk --reindex

Без --reindex индексация выполняется только если индекс пуст. Для извлечения .hbk нужен 7z (в образе ставится p7zip-full).

Семантический индекс (эмбеддинги)

Отдельный скрипт читает готовый индекс, считает векторы через EMBEDDING_URL и пишет в новый индекс с полем embedding. Исходный индекс не меняется.

docker run --rm \
  -e ELASTICSEARCH_URL=http://192.168.31.31:9200 \
  -e EMBEDDING_URL=http://192.168.31.32:8081/v1 \
  mcp-1c-helper:local \
  python -m scripts.build_semantic_index \
    --source help1c_docs --target help1c_docs_v2 --recreate

После сборки укажи ELASTICSEARCH_INDEX=help1c_docs_v2 в .env — find_1c_help включит kNN+RRF автоматически (при заданном EMBEDDING_URL).

Подключение opencode

{
  "mcp": {
    "mcp-1c-helper": {
      "type": "remote",
      "url": "http://192.168.31.31:8002/mcp",
      "enabled": true
    }
  }
}

Разработка

pip install -r requirements-dev.txt
python -m src.server                 # запуск FastMCP локально
python -m pytest tests/ -m unit      # unit тесты