MCP со справкой по платформе 1С

Локальный MCP-сервер для поиска по справке платформы 1С. Сервер не содержит саму справку: положите локальную выгрузку документации в kb/ или укажите путь через BIT_1C_HELP_ROOT.

Поддерживаемые форматы для индексации: .md, .mdx, .txt, .html, .htm, .xml, .bsl.

Запуск

У сервера два входа с одним и тем же набором инструментов: локальный (stdio) и сетевой (HTTP). Отвечают они одинаково — это проверяется дифференциальным прогоном npm run test:diff-entries.

Локальный вход (stdio)

Так сервер запускают MCP-клиенты на машине разработчика:

npm run start

Сетевой вход (HTTP)

Обслуживает POST /mcp по протоколу streamable HTTP без сессий:

$env:MCP_PORT = "8770"; node .\src\entry\http.js

Вход слушает только 127.0.0.1 — это не настраивается. Наружу сервис выставляет nginx площадки, и он же отвечает за TLS и доступ.

Переменные окружения:

Переменные справки (BIT_1C_HELP_ROOT, BIT_1C_HELP_INDEX_ROOT, BIT_1C_HELP_LOG_PATH) работают одинаково на обоих входах. Кроме них:

Состояние службы: /health и /status

У сетевого входа, кроме /mcp, есть два маршрута только на чтение. Оба проходят те же проверки Host и Origin, что и /mcp, — исключений нет ни для одного из них.

GET /health — машиночитаемое состояние, оно же критерий приёмки выкладки:

{
  "status": "ok",
  "service": "bit-1c-help",
  "product": "bit-1c-help",
  "version": "0.5.0",
  "gitCommit": "f4b4b669e33b11afbf6725268989de7b5626aa91",
  "docsVersion": "2026-08-21",
  "protocolVersions": ["2025-11-25", "2025-06-18", "2025-03-26"],
  "sources": [{ "source": "Platform/8.3.27.1989", "documents": 25541 }],
  "index": { "state": "ready", "documents": 81204, "builtAt": "2026-08-21T01:12:27.482Z" },
  "uptimeSec": 6,
  "problems": []
}

• version и gitCommit берутся из BUILD-INFO.json, который кладёт в каталог версии сборочный скрипт. Каталог кода на сервере не git-репозиторий, определить коммит на месте нечем — его приносят с собой. В клоне разработчика этого файла нет: тогда версия берётся из package.json, а коммит — из .git.

• docsVersion — содержимое KB-VERSION.txt в корне справки, его пишет сборщик артефакта справки.

• sources[].documents — число файлов во всём поддереве раздела.

• index.state — ready, warming или building, см. ниже.

• problems — причины, по которым status стал degraded. Абсолютных путей в них нет намеренно: путь выкладки может выдать наружу имя учётной записи, поэтому подробности с путями уходят только в локальный журнал.

Служба не падает ни при какой беде со справкой или индексом: она поднимается и отвечает degraded со списком причин. Падение недопустимо — диспетчер служб перезапускал бы процесс по кругу, и в журнале оказалась бы каша вместо диагноза.

Три состояния индекса.

Прогрев запускают оба входа сразу после старта, в фоне, и обслуживанию он не мешает. На реальном корпусе (294 МБ, 53 588 файлов, 81 204 раздела) /health начинает отвечать через ~1.8 с после запуска процесса, а ready наступает через ~6 с. Скрипт выкладки обязан опрашивать /health до готовности, а не один раз сразу после запуска службы: пока идёт прогрев, status честно равен degraded.

GET /status — та же картина для человека в браузере плюс статистика поиска из журнала: доля запросов без результатов, частые запросы, задержки p50/p95, распределение по источникам. Страница показывает, по каким запросам справка не находится, то есть какой источник пора добавить. Ничем не управляет и ничего не меняет.

Оба маршрута дёшевы намеренно: /health смотрит только в память процесса и в маленький файл агрегатов рядом со снимком индекса, /status читает ограниченный хвост журнала и запоминает разбор по времени изменения файла. Разворачивать снимок индекса в обработчике запроса нельзя — на реальном корпусе это 4.2 с и 2.4 ГБ памяти на один опрос.

Кого не пускает сетевой вход

Сервис доступен по сети внутри машины, поэтому до него может дотянуться страница, открытая в браузере сотрудника. От этого стоят две проверки, и по отдельности ни одна не работает:

• Origin. Запрос без этого заголовка проходит: его не шлют ни curl, ни клиенты MCP. Если заголовок есть — значит, запрос отправил браузер, и значение обязано быть в MCP_ALLOWED_ORIGINS. Список пуст по умолчанию, то есть браузерные запросы не проходят вовсе.

• Host. При перепривязке DNS страница на чужом домене, чьё имя перепривязано на 127.0.0.1, шлёт запрос как одноисточниковый — заголовка Origin в нём нет, и первая проверка его пропускает. Отличает такой запрос Host: там имя атакующего. Поэтому Host обязан быть 127.0.0.1, localhost (с портом или без) или тем, что перечислено в MCP_ALLOWED_HOSTS.

MCP_ALLOWED_HOSTS нужен, когда nginx площадки передаёт наверх исходный Host клиента (proxy_set_header Host $host), а не адрес upstream: тогда до сервиса доходит публичное имя, и его надо разрешить явно. Если nginx оставляет Host от upstream, переменная не нужна.

Значения MCP_ALLOWED_ORIGINS приводятся к виду, в котором источник шлёт браузер: схема, хост и порт, без пути и завершающего слэша. Запись, на источник не похожую, вход отвергает при запуске с объяснением, а не молча отвечает 403 на каждый запрос. То же самое — с MCP_ALLOWED_HOSTS: сравнение с заголовком Host идёт точным совпадением, а не шаблоном, поэтому, например, * по привычке из настроек CORS не сработает вовсе, и такую запись вход тоже отвергает при запуске.

Внесение источника в MCP_ALLOWED_ORIGINS снимает нашу защиту, но браузерный клиент от этого не заработает. Заголовков Access-Control-Allow-* сервис не отдаёт и предварительные запросы OPTIONS не обрабатывает, поэтому браузер отправит запрос, а прочитать ответ не даст. Чтобы браузерный клиент работал, CORS нужно настраивать отдельно — на nginx площадки либо в самом входе.

Related MCP server: onec-meta-mcp

Воспроизводимый запуск на новой машине

1. Установите Node.js 20 или новее.

2. Положите готовый очищенный архив mcp-docs-*.zip в проект и распакуйте его так, чтобы появился каталог kb/.

3. Если готового архива нет, соберите справку из источников: импортируйте raw HTML в build/raw, затем выполните очистку в kb.

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

npm run smoke

5. Запустите MCP-сервер:

npm run start

Для Codex укажите BIT_1C_HELP_ROOT на каталог kb. Сырые HTML-исходники держите вне kb, например в build/raw, иначе MCP будет индексировать шумную HTML-разметку.

Пример восстановления из готовых артефактов:

Expand-Archive -Path ".\build\artifacts\mcp-docs-2026-08-04.zip" -DestinationPath "." -Force
Expand-Archive -Path ".\build\artifacts\raw-html-2026-08-04.zip" -DestinationPath "." -Force

Первый архив нужен для работы MCP. Второй нужен только как воспроизводимый raw-слой для повторной очистки.

Как получить локальную справку

Если на машине установлена платформа 1С, в каталоге версии обычно есть индекс синтакс-помощника:

C:\Program Files\1cv8\<версия>\bin\devdocs_ru.bin

Импортируйте его в индексируемый Markdown:

npm run import:installed

Журнал изменений установленной платформы (docs\\ru\\V8Update.htm) импортируется отдельно. Он разбивается на файлы по версиям платформы, чтобы документы не превышали лимит индексатора:

npm run import:platform-updates

При необходимости исходный файл и каталог назначения можно указать явно:

node .\scripts\import-platform-updates.js "C:\Program Files\1cv8\8.3.27.1989\docs\ru\V8Update.htm" ".\kb\Platform\8.3.27.1989\PlatformUpdates"

Или укажите конкретный файл:

node .\scripts\import-installed-help.js "C:\Program Files\1cv8\8.3.15.1869\bin\devdocs_ru.bin"

Это импортирует оглавление встроенной справки: названия объектов, методов, свойств, областей доступности и v8help:// URI. Для полного текста статей нужен экспорт/извлечение содержимого страниц справки из поставки платформы или официальный онлайн-источник.

Для платформы 8.3.27.1989 полный текст страниц синтакс-помощника можно извлечь из shcntx_ru.hbk:

npm run extract:hbk -- "C:\Program Files\1cv8\8.3.27.1989\bin\shcntx_ru.hbk" ".\build\raw\Platform\8.3.27.1989\SyntaxHelperContext"
npm run clean:html-docs -- ".\build\raw\Platform\8.3.27.1989\SyntaxHelperContext" ".\kb\Platform\8.3.27.1989\SyntaxHelperContext"

После этого MCP будет индексировать очищенный Markdown из kb/Platform/8.3.27.1989.

Как добавить справку БСП

Документация поставки БСП лежит в каталоге шаблонов конфигураций. По умолчанию это %APPDATA%\1C\1cv8\tmplts; свой путь смотрите в параметре ConfigurationTemplatesLocation файла 1cestart.cfg. Например:

%APPDATA%\1C\1cv8\tmplts\1c\SSL\3_1_11_353\ExtFiles\docs

импортируйте HTML-документацию в небольшие фрагменты:

npm run import:ssl-docs -- "$env:APPDATA\1C\1cv8\tmplts\1c\SSL\3_1_11_353\ExtFiles\docs" ".\build\raw\SSL\3_1_11_353"
npm run clean:html-docs -- ".\build\raw\SSL" ".\kb\SSL"

Фрагменты будут сохранены как raw HTML в build/raw/SSL, затем очищенный Markdown попадет в kb/SSL и MCP-поиск.

Откуда берётся содержимое kb/

Репозиторий не содержит и не распространяет документацию — ни справку платформы, ни материалы ИТС, ни документацию БСП. Всё это принадлежит фирме «1С» и её партнёрам и распространяется по своим лицензиям. Сервер ищет по тому корпусу, который вы собрали сами из источников, к которым у вас есть законный доступ: установленная платформа, поставка БСП, ваша подписка ИТС.

Импортёры в scripts/ работают только с локальными файлами: .hbk установленной платформы, V8Update.htm из каталога платформы, HTML-документация из поставки БСП, клоны открытых репозиториев YAxUnit и Vanessa Automation. Инструментов, выкачивающих контент с сайтов фирмы «1С», здесь нет намеренно: массовый автоматический обход противоречит условиям использования ИТС и создаёт лишнюю нагрузку на чужие серверы.

Очистка HTML в слой для поиска

Сырые HTML-исходники можно сохранить отдельным артефактом:

New-Item -ItemType Directory -Force -Path .\build\artifacts
Compress-Archive -Path .\build\raw -DestinationPath .\build\artifacts\raw-html-2026-08-04.zip -CompressionLevel Optimal

Этот архив нужен как воспроизводимый raw-слой. Для качества MCP-поиска лучше держать в kb очищенный слой: убрать скрипты, стили, навигацию, служебные блоки, сохранить заголовки и основной текст в Markdown или компактный HTML.

Очищенный Markdown-слой для MCP можно построить так:

npm run clean:html-docs -- ".\build\raw\SSL" ".\kb\SSL"
npm run clean:html-docs -- ".\build\raw\Platform\8.3.27.1989\SyntaxHelperContext" ".\kb\Platform\8.3.27.1989\SyntaxHelperContext"

Конвертер разбирает HTML через DOM, сохраняет source URL, заголовки, anchors, внутренние ссылки, код и таблицы. Навигация, скрипты, стили и служебная разметка удаляются. Блоки «Смотри также» помечаются как [SEE_ALSO].

Вместе с Markdown создаётся IMPORT-MANIFEST.json со статистикой пустых документов, дублирующихся URL, повреждённой кодировки, отсутствующих заголовков и слишком больших файлов. В MCP-каталог kb кладите именно очищенный слой.

Как добавить справку YAxUnit

Если локально есть репозиторий YAxUnit:

<путь к репозиториям>\bia-technologies\yaxunit

импортируйте Markdown-документацию и BSL-комментарии API:

npm run import:yaxunit-docs -- "<путь к репозиториям>\bia-technologies\yaxunit"

Если репозиторий стоит на релизном теге, файлы будут сохранены в каталог версии, например kb/YAxUnit/25.12, и попадут в MCP-поиск. Каталог kb/ игнорируется Git.

Как добавить справку Vanessa Automation

Официальный репозиторий Vanessa Automation:

https://github.com/Pr-Mex/vanessa-automation.git

Его можно скачать в игнорируемый рабочий каталог:

git clone --depth 1 --filter=blob:none --sparse https://github.com/Pr-Mex/vanessa-automation.git .\build\external\vanessa-automation
git -C .\build\external\vanessa-automation sparse-checkout set docs features examples training VanessaAutomation

Если репозиторий уже скачан локально, импортируйте Markdown-документацию, Gherkin-сценарии и BSL-модули:

npm run import:vanessa-automation-docs -- ".\build\external\vanessa-automation"

Если репозиторий стоит на релизном теге, файлы будут сохранены в каталог версии, например kb/VanessaAutomation/1.2.043.23, и попадут в MCP-поиск. Каталог kb/ игнорируется Git.

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

Добавьте сервер в %USERPROFILE%\.codex\config.toml:

[mcp_servers.onec_platform_help]
command = "node"
args = ["<путь к репозиторию>\\bit-1c-help\\src\\server.js"]

[mcp_servers.onec_platform_help.env]
BIT_1C_HELP_ROOT = "<путь к репозиторию>\\bit-1c-help\\kb"

Если справка лежит в другой папке, замените BIT_1C_HELP_ROOT на путь к ней.

Инструменты MCP

• search_1c_platform_help — поиск по локальной справке.

• get_1c_platform_help_document — чтение найденного документа по относительному пути.

• get_1c_platform_help_section — чтение точного найденного раздела по стабильному id.

• reindex_1c_platform_help — инкрементальная переиндексация изменившихся файлов.

• list_1c_platform_help_sources — список доступных справок для фильтра source.

Markdown-документы индексируются по разделам. Поиск ранжирует заголовок, иерархию раздела, путь и основной текст отдельно, а в результате возвращает заголовок найденного раздела, breadcrumbs, исходный путь и релевантный фрагмент.

Индексы сохраняются в build/index в сжатом бинарном формате. Путь можно изменить через BIT_1C_HELP_INDEX_ROOT. Для каждого значения root/source создаётся отдельный индекс. Готовый снимок поднимается в память как есть, без обхода каталога справки: на реальном корпусе обход стоит 24 с против 5 с на загрузку снимка. Обход остаётся там, где его просят явно, — npm run build:index и инструмент reindex_1c_platform_help. При повторной индексации неизменённые файлы переиспользуются по размеру и времени изменения; если метаданные изменились, содержимое дополнительно сравнивается по SHA-256.

Для диагностики ранжирования передайте "explain": true в search_1c_platform_help. Инструмент вернёт вклад заголовка, breadcrumbs, пути, основного текста и специальных бонусов в итоговую оценку.

Если source не указан, сервер распознаёт характерные вопросы о платформе, стандартах, методиках, БСП, YAxUnit и Vanessa Automation и лениво ищет в подходящих источниках. Для остальных запросов сохраняется поиск по всему корпусу. В результатах автоматически маршрутизированного поиска возвращаются source, полный путь и стабильный id раздела.

reindex_1c_platform_help выполняет инкрементальную переиндексацию и возвращает статистику по обновлённым, переиспользованным, удалённым, слишком большим и ошибочным файлам. Полную пересборку он НЕ делает: на "force": true инструмент отвечает отказом и называет команду сборки. Пересборка всего корпуса не укладывается в таймаут запроса (60 с) — клиент отвалится, а процесс продолжит жечь память и процессор, и остановить его будет нечем. Для полной пересборки есть npm run build:index (см. «Сборка индекса»).

Логи поиска и статистика

Сервер записывает структурированный JSONL-журнал в build/logs/search.jsonl относительно каталога самого MCP-проекта, а не текущего рабочего каталога процесса. В журнал попадают события поиска, индексации и ошибки инструментов. Для поиска сохраняются запрос, его SHA-256-идентификатор, выбранные источники, термины, число кандидатов, задержка и первые пять результатов. Тексты документов и сниппеты не записываются.

Каждая запись содержит serverVersion, полный gitCommit и indexFormatVersion. При запуске записывается событие server_start, поэтому журнал можно однозначно связать с версией сервера и исходным коммитом.

Настройки:

• BIT_1C_HELP_LOG_PATH — другой путь к JSONL-журналу;

• BIT_1C_HELP_LOG_QUERIES=true — сохранять текст запросов для отладки; по умолчанию записывается только хеш;

• BIT_1C_HELP_GIT_COMMIT — явно заданный commit SHA для сборки вне Git-репозитория;

• BIT_1C_HELP_LOG_MAX_BYTES — размер файла перед ротацией, по умолчанию 20 МБ;

• BIT_1C_HELP_LOG_MAX_FILES — максимальное число файлов ротации, по умолчанию 5.

Сводный отчёт:

npm run stats:search

Можно передать путь к журналу и порог слабого результата:

npm run stats:search -- ".\build\logs\search.jsonl" 20

Отчёт содержит число и частоту запросов без результатов, слабые результаты, задержки p50/p95, среднее число кандидатов, популярные запросы и распределение по источникам.

В search_1c_platform_help, get_1c_platform_help_document и reindex_1c_platform_help можно передать source, чтобы ограничить область поиска конкретной справкой:

{
  "query": "ОбработкаЗаполнения",
  "source": "Platform/8.3.27.1989",
  "limit": 5
}

Большие документы читайте постранично через get_1c_platform_help_document: передайте offset: 0 и maxChars, затем используйте значение nextOffset из ответа как offset следующего вызова. Максимальный размер одной страницы — 30000 символов.

list_1c_platform_help_sources показывает не только путь, но и подсказку useWhen. Основные источники:

Сборка индекса

Индекс строится отдельной командой, вне обслуживания запросов:

npm run build:index

# только изменившиеся файлы вместо полной пересборки
node .\scripts\build-index.js --incremental

# отдельный индекс на каждый раздел: поиск с фильтром source использует именно их
node .\scripts\build-index.js --root kb --root kb\Platform\8.3.27.1989

Почему отдельной командой, а не инструментом MCP: полная пересборка реального корпуса не укладывается в таймаут запроса (60 с). Поэтому reindex_1c_platform_help переиндексирует только изменившиеся файлы, а на force: true отвечает отказом и называет эту команду. Выкладка на сервере строит индекс до запуска службы и дожидается конца.

Индексов несколько, и построить надо каждый. Поиск с фильтром по источнику работает по отдельному индексу этого источника. Одной сборки для всего корпуса не хватает: первый же запрос с фильтром будет строить свой индекс сам. Список корней берут из состава справки, а не задают руками, иначе новый источник молча останется непостроенным.

Служба поднимает в память только корневой индекс (прогрев при старте), индексы источников — по требованию. В памяти их держится не больше BIT_1C_HELP_INDEX_CACHE_LIMIT (по умолчанию 3, считая закреплённый корневой), давно не использовавшиеся вытесняются. Предел не декоративный: на реальном корпусе корневой индекс удерживает 1046 МБ, синтакс-помощник 8.3.27 — ещё 363 МБ, а источников всего девять.

Проверка

npm test

Единый прогон node --test: ядро (поиск, ранжирование, чтение разделов, фильтр по источнику), контракт обоих входов, /health, /status, отказ reindex при force, холодный старт и предел кеша индексов, а также золотой набор реальных запросов с ожидаемыми документами в выдаче. Золотой набор пропускается, если в клоне нет kb/. Тот же прогон выполняет GitHub Actions на каждый push и pull request.

Отдельные проверки:

npm run smoke                 # локальный прогон через вход stdio поверх настоящего kb/
npm run test:diff-entries     # stdio и сетевой вход отвечают одинаково
npm run test:diff-monolith    # ответы против прежнего монолита src/server.js
npm run test:source-filter    # фильтр по источнику
npm run test:clean-docs       # качество очистки справки
npm run test:platform-updates # импорт обновлений платформы

test:diff-monolith сравнивает текущий вход с монолитным src/server.js из истории git. Ревизия по умолчанию — 12ae917~1; при слиянии со сжатием истории такого коммита не станет, и тогда её надо задать явно:

$env:MONOLITH_REV = "<ревизия>"; npm run test:diff-monolith

Скрипт проверяет наличие ревизии до начала прогона и говорит об этом прямо, а не падает невнятной ошибкой git в середине.

Смоук работающей службы

Тот же smoke.js умеет проверять уже запущенный сетевой сервис по URL — initialize, tools/list и поисковый запрос с проверкой, что результат непустой:

node .\scripts\smoke.js --url http://127.0.0.1:4101/mcp
node .\scripts\smoke.js --url https://mcp.example.com/bit-1c-help/mcp --query "ОбработкаЗаполнения"

Ключи: --query <текст> (по умолчанию «платформа»), --host <значение> — заголовок Host, если служба за прокси и проверяет его, --timeout <мс>. Ненулевой код возврата при любой неудаче: это инструмент приёмки, скрипт выкладки смотрит на код, а не на текст. Он же выполняет прогревочный запрос, чтобы первое обращение после выкладки не досталось живому пользователю.

Манифест сервиса и сборка артефактов

Манифест mcp-service.json в корне репозитория — единственная точка стыка с площадкой, на которой служба работает. В нём имя службы, порт, точка входа, маршрут, переменные окружения и состав выкладки (payload). Состав перечислен пофайлово и читается сборочным скриптом по-настоящему: второго списка в скриптах нет. Значения {DataRoot}, {PublicHost} и {Port} в блоке env подставляет скрипт выкладки на площадке.

Почему состав пофайловый: в src лежит ssl_3_1_11_353 на 209 МБ, которому на сервере делать нечего, а в scripts — импортёры справки, нужные только на рабочей машине. На сервере из scripts нужны ровно три файла: сборка индекса, подсчёт статистики журнала и смоук для приёмки.

# артефакт кода: чистый npm ci --omit=dev, состав по манифесту, BUILD-INFO.json, zip + SHA-256
powershell -File tools\build-release.ps1

# артефакт справки: kb/ и KB-VERSION.txt внутри, zip + SHA-256
powershell -File tools\build-kb-artifact.ps1

Версии двух артефактов независимы: код — semver из package.json, справка — по дате сборки.

node_modules кладётся внутрь артефакта кода: на сервере не выполняется npm install, не нужен доступ к реестру npm и исключён риск получить набор зависимостей, отличный от протестированного.

Всё, что эти скрипты пишут для Node (BUILD-INFO.json, сводки сборки), пишется в UTF-8 без BOM. Это не оформление: Set-Content -Encoding UTF8 в Windows PowerShell 5.1 добавляет BOM, JSON.parse на нём падает, /health уходит в degraded с gitCommit: "unknown" — и приёмка откатывает исправную выкладку.