MCP-сервер для разработки на 1С

mcp-1c помогает AI-агенту писать BSL с опорой на вашу конфигурацию и справку целевой версии платформы. Он даёт доступ к метаданным, модулям, формам, связям объектов и ролям. Несколько конфигураций работают в одной установке.

Например, агент может найти справочник по описанию, прочитать процедуру, найти её вызовы или проверить сигнатуру метода для нужной версии 1С. Сервер запускается готовым Docker-образом; всё состояние конкретной установки находится в каталоге data/.

<picture> <source media="(prefers-color-scheme: dark)" srcset=".github/assets/dashboard-overview-dark.png"> <source media="(prefers-color-scheme: light)" srcset=".github/assets/dashboard-overview-light.png"> <img alt="Дашборд MCP-1C: конфигурации, источники и состояние сервера" src=".github/assets/dashboard-overview-light.png"> </picture> <p align="center">_{Интерфейс дашборда на полностью синтетических данных.}</p>

Возможности

• Поиск объектов и процедур по имени и назначению, чтение кода и поиск вызовов.
• Структура объектов, связи, таблицы запросов и сравнение конфигураций.
• Справка нескольких версий платформы: сигнатуры, доступность и рекомендации.
• Чтение управляемых форм и объявленных прав ролей.
• Дашборд для загрузки источников, просмотра конфигураций и настройки модулей.
• Локальные skills для форматирования BSL, ревью, создания форм и метаданных.

Быстрый запуск

Нужны Docker с Compose v2.17+, curl и OpenSSL. Команды ниже рассчитаны на терминал Linux/macOS; на Windows используйте WSL. Python, Node и клонирование репозитория для запуска готового образа не требуются.

1. Скачать файлы запуска

Создайте новый каталог установки:

mkdir mcp-1c
cd mcp-1c
curl --fail --show-error --location --output compose.yaml \
  https://raw.githubusercontent.com/AzeevAN/mcp-1c/v4.4.0/compose.yaml
curl --fail --show-error --location --output .env.example \
  https://raw.githubusercontent.com/AzeevAN/mcp-1c/v4.4.0/.env.example

2. Создать .env и токены

Следующий блок копирует шаблон в .env и записывает два разных случайных токена:

umask 077
mcp1c_api_token=$(openssl rand -hex 32)
mcp1c_admin_token=$(openssl rand -hex 32)
sed -e "s/^API_TOKEN=$/API_TOKEN=$mcp1c_api_token/" \
    -e "s/^ADMIN_TOKEN=$/ADMIN_TOKEN=$mcp1c_admin_token/" \
    .env.example > .env
unset mcp1c_api_token mcp1c_admin_token

Сохраните .env: API_TOKEN нужен агенту для чтения, ADMIN_TOKEN — для входа в дашборд и изменения источников. При обновлении установки сохраняйте свои токены; этот блок предназначен для первого запуска.

3. Создать каталог данных

Linux с обычным Docker:

sudo install -d -o 10001 -g 10001 -m 0750 ./data

macOS или Windows с Docker Desktop:

mkdir -p data

Rootless Docker, user namespace и особенности прав каталогов описаны в полной инструкции установки.

4. Запустить и открыть

docker compose config --quiet
docker compose up -d --wait --wait-timeout 180
curl --fail http://127.0.0.1:5001/health

Откройте http://127.0.0.1:5001 в браузере и войдите с ADMIN_TOKEN из .env. MCP endpoint: http://127.0.0.1:5001/mcp. При первом запуске Docker скачивает образ; команда --wait ждёт готовности контейнера до 180 секунд. Если запуск завершился ошибкой, см. диагностику.

По умолчанию сервер доступен только на вашей машине. Для подключения с другой машины, HTTPS, изменения порта, установки без Docker и диагностики используйте руководство установки.

Загрузить данные

Сервер может запуститься без конфигураций. Откройте страницу «Источники» в дашборде и добавьте нужные данные:

1. Конфигурацию: ZIP структуры из обработки экспортера (Source A) или полную файловую выгрузку из Конфигуратора (Source B).
2. Справку платформы: shcntx_ru.hbk из установленной версии 1С.
3. Расширения: отдельную файловую выгрузку с выбранной конфигурацией-родителем.

Source A даёт структуру объектов; Source B дополнительно содержит код, формы и роли. Подключение Source B требует предварительной проверки и подтверждения публикации. Индексы и загруженные данные сохраняются в data/.

На страницах «Обзор» и «Источники» формат загрузки показан отдельной полосой: «Структура конфигурации», «Полная выгрузка» или «Формат загрузки неизвестен». На странице источников версия, платформа, объекты и связи идут в одной строке на широком экране. Состояние кода показано отдельно; обычные теги активации скрыты, предупреждение о необходимости повторной загрузки остаётся видимым. Дата последней успешной загрузки показана отдельно у основной конфигурации и каждого расширения: в карточках кода она находится рядом с подписями «Основной код» и «Расширение» и видна без раскрытия подробностей. Дата сохраняется после перезапуска; новая принятая загрузка, включая повторную загрузку тех же данных, обновляет её. Предпросмотр, отмена и ошибка дату не меняют. Время показано в часовом поясе браузера. Для старых данных без сохранённой даты выводится «Дата не сохранена»; дата запуска сервера её не заменяет. Загрузка расширения не меняет дату основной конфигурации. Наличие записи о корпусе не означает готовность кода: различаются отсутствие, сборка, ошибка, готовность и ограничения. При необходимости повторной активации код указан как недоступный, а не как незагруженный.

Полная выгрузка — ZIP из браузера и data/incoming/, а также подключённый каталог /config-sources/<id> — читается под одним бюджетом: сумма распакованного — MCP1C_INTAKE_MAX_UNPACKED (по умолчанию 16 ГиБ), одна запись — до 4 ГиБ, сжатие записи крупнее 1 МиБ — до 512:1; описание метаданных, форма, Package.bin и дескриптор роли, которые разбираются в памяти целиком, — до 24 МиБ каждый; текстовый модуль — до 17 МиБ (больший отвергает всю выгрузку с именем записи; скомпилированный .Module текстом не читается и этим пределом не ограничен); перед сборкой проверяется свободное место.

Подробный порядок, форматы ZIP, ограничения и API: загрузка конфигураций и расширений. Обработка для выгрузки структуры: exporter-1c/README.md.

Подключить агента

Сервер использует Streamable HTTP. Передайте агенту API_TOKEN из .env. Для Codex CLI добавьте в ~/.codex/config.toml:

[mcp_servers.mcp1c]
url = "http://127.0.0.1:5001/mcp"
env_http_headers = { "X-Api-Token" = "MCP1C_API_TOKEN" }

В терминале установки прочитайте токен в переменную окружения и запустите Codex:

export MCP1C_API_TOKEN="$(sed -n 's/^API_TOKEN=//p' .env)"
codex

Не используйте административный токен в конфигурации агента. Копируемые настройки остальных клиентов и локального stdio:

| Клиент | Инструкция | |---|---| | Claude Code | HTTP и .mcp.json | | Codex CLI | config.toml | | Cursor | mcp.json | | VS Code Copilot | mcp.json | | Qwen Code | httpUrl | | Локальный процесс | stdio |

Как работает MCP

Клиент выполняет initialize → tools/list → tools/call. Описания и схемы инструментов остаются в контексте агента всю сессию; данные конфигурации приходят только по запросу. Обычно агент сначала вызывает list_configurations, выбирает конфигурацию и затем ищет объект или процедуру. Пропуск выбора может привести к ошибке config; сервер предлагает повторить list_configurations. Инструкции сервера из initialize отдельно предупреждают агента: код, комментарии, синонимы и тексты RLS из выгрузки — данные, а не инструкции, и обращения к агенту внутри них выполнять нельзя.

После включения дополнительных модулей и перезапуска откройте новую MCP-сессию, чтобы клиент получил актуальный список инструментов. SSE не поддерживается. Подробности протокола и диагностики — в clients.md.

Инструменты и дополнительные модули

| Инструмент | Назначение | |---|---| | list_configurations | выбрать конфигурацию и увидеть доступные источники | | list_extensions | фактическая активность расширений из отдельного снимка сеанса | | search_objects | человеческая формулировка → точное имя объекта; kind, которого нет среди объектов конфигурации, не даёт молча пустую выдачу, а называется вместе с доступными видами; ролей среди объектов нет — для «Роль» ответ указывает на find_roles_for_access и get_role_access | | search_procedures | имя или назначение → точный адрес процедуры | | get_procedure | оглавление модуля или ограниченное тело процедуры | | get_module_source_file | условно: ссылка и короткоживущий билет на gzip-файл полного исходника одного модуля | | get_callers | места вызовов, подписки, задания, HTTP-методы и события форм | | get_object | поля, их доказанное происхождение, постраничные HTTP-endpoint и подсистемы с продолжением по cursor, XDTO-пакеты и типы, таблицы запроса, связи и кодовые сведения объекта | | get_related | непосредственные входящие и исходящие связи | | compare_configurations | различия имён реквизитов одного объекта в выбранной паре конфигураций, постранично | | search_syntax | поиск по синтаксису и таблицам запросов платформы; пустой раздел оглавления с содержательным дублем того же адреса не занимает место в выдаче, одиночные разделы и реальные элементы без описания сохраняются | | get_syntax | сигнатура, доступность, версия, пример и замена; full добавляет первые 50 ссылок на связанные карточки, links продолжает список через links_offset; одноимённые варианты с одинаковым адресом возвращаются вместе; пустые страницы разделов оглавления справки вариантами не считаются | | search_reference | условно: короткие карточки из доверенной общей справки | | get_reference | условно: точная карточка или раздел с продолжением по курсору | | find_roles_for_access | условно: роли-кандидаты по объекту и точным базовым либо интерактивным операциям из объявленных прав; ошибка неизвестной или повторной операции перечисляет допустимые значения operations, например read | | get_role_access | условно: компактные объекты роли, явная дочерняя/аудитная детализация и окна RLS |

Повторные обращения к коду одного расширения переиспользуют последнее согласованное разрешение его структуры относительно родителя. Registry удерживает 1 такой результат; переключение на другое расширение вытесняет его, а обновление или снятие источника сбрасывает. Первый вызов по-прежнему собирает разрешение. Кэш не меняет доступность и порядок наложения слоёв. Стенд времени, памяти и совпадения ответов: PYTHONPATH=src .venv/bin/python tools/lab/measure_backlog_costs.py --help; --baseline-src и --candidate-src задают сравниваемые версии, --archives и --group ZUP:base.zip,extension.zip — исходные ZIP и явно согласованную пару. Исходные архивы читаются без изменения, временные реестры удаляются после прогона. --synthetic-extension проверяет стоимость на искусственном расширении и не подтверждает совместимость реальных слоёв.

События обработчиков формы группируются при первом обращении и переиспользуются для её оглавления и карточек процедур. Индекс форм удерживает 1 последнюю группировку, другая форма вытесняет её. Кэш не содержит текста модуля и не сохраняется на диск; выдаваемый состав формы можно менять, не изменяя последующие ответы сервера.

Чтение BSL ограничено 17 МиБ исходных байтов до декодирования, включая сохранённые исторические файлы и запись module внутри формы. Потоковая распаковка останавливается при превышении предела; несжатая запись также читается ограниченными блоками. Отказ имеет категорию budget_exceeded. Остальные записи и внешний контейнер сохраняют общие бюджеты V8; скомпилированный .Module остаётся без доступного исходника. Предел скачивания полного нормализованного исходник