1c-mcp-toolkit

name: 1c-mcp-toolkit description: > Прямой HTTP API к живой запущенной базе 1С:Предприятие через обработку MCP_Toolkit.epf (REST на http://localhost:6003/api/*). 12 эндпоинтов: запросы (execute_query), BSL-код (execute_code), метаданные (get_metadata), ссылки и навигация (get_object_by_link, get_link_of_object), поиск ссылок на объект (find_references_to_object), права (get_access_rights), журнал регистрации (get_event_log), справка платформы (get_bsl_syntax_help), управление сессией (restart_1c_session, close_1c_session). EPF и скрипты запуска включены в скилл. Используй когда нужно проверить реальные данные в живой БД, выполнить exploratory-запрос, прямо вызвать экспортную функцию модуля выгрузки, прочитать журнал регистрации, диагностировать данные до или после доработки. Триггеры на русском: "выполни запрос в живой базе", "проверить данные в БД", "сколько записей в", "вызвать функцию модуля 1С", "что в журнале регистрации", "выполни BSL-код в живой 1С", "запусти 1С с MCP-toolkit". Триггеры на английском: "query live 1C database", "execute BSL in 1C", "check 1C data", "explore 1C metadata at runtime".

1C MCP Toolkit - прямой HTTP API к живой базе 1С

REST API на http://localhost:6003/api/* через обработку MCP_Toolkit.epf, запущенную в тонком (или толстом) клиенте 1С. Встроенный HTTP-сервер реализован нативной компонентой MCPHttpTransport. Без модификации конфигурации, без COM, без публикации через web-сервер.

Обработка MCP_Toolkit.epf - разработка ROCTUP, репозиторий: https://github.com/ROCTUP/1c-mcp-toolkit (там же исходники нативной компоненты и документация).

Используется когда LLM-агент работает с живой базой (тесты, диагностика, прямой вызов экспортных функций), и при этом классические EDT-инструменты не подходят (нет dev-проекта, нужны данные runtime, нужен реальный пользовательский контекст).

Быстрый старт

1. Запуск 1С с авто-открытием обработки

EPF лежит прямо в скилле:

• bin/MCP_Toolkit.epf - x64 (основная)
• bin/MCP_Toolkit_x86.epf - x86

Минимальная PowerShell-команда:

& "C:\Program Files\1cv8\<версия>\bin\1cv8c.exe" `
    /F"<путь к файловой базе>" `
    /N"<имя пользователя>" `
    /P"<пароль>" `
    /Execute"$HOME\.claude\skills\1c-mcp-toolkit\bin\MCP_Toolkit.epf"

Готовый параметризованный скрипт: scripts/start-1c.ps1.

Пример:

& "$HOME\.claude\skills\1c-mcp-toolkit\scripts\start-1c.ps1" `
    -Platform "8.3.27.2074" `
    -Database "E:\1C\MyDatabase" `
    -User "Admin" `
    -Password "<пароль>"

Без /N и /P 1С зависает на форме авторизации, HTTP-сервер не поднимается.

После запуска в обработке на вкладке "Подключение" выбрать "Встроенный сервер", порт 6003, формат TOON, нажать "Запустить сервер" (если не настроен автостарт).

2. Проверка готовности

curl http://localhost:6003/health

200 OK - сервер на 6003 работает, можно делать запросы.

3. Закрытие 1С (например, для deploy через EDT)

curl -sS -X POST "http://localhost:6003/api/execute_code" \
  -H "Content-Type: application/json" \
  -d '{"code":"ЗавершитьРаботуСистемы(Ложь, Ложь); Результат=\"OK\";","execution_context":"client"}'

Готовый скрипт: scripts/stop-1c.ps1.

execution_context: "client" обязателен - ЗавершитьРаботуСистемы доступна только на клиенте.

Когда использовать MCP Toolkit

• Проверка реальных данных в живой БД (полнота тестовых данных, корректность миграции, количество записей)
• Прямой вызов экспортных функций модулей выгрузки/обмена без UI
• Поиск конкретных проводок/документов для воспроизведения багов
• Чтение метаданных из живой БД (когда нет открытого EDT-проекта)
• Чтение журнала регистрации с фильтрацией
• Поиск ссылок на объект ("где используется этот контрагент")
• Диагностика прав доступа

Когда НЕ использовать (есть альтернатива получше)

MCP Toolkit заточен под живую запущенную базу, EDT - под dev-режим с исходниками. Не дублируй вызовы.

Базовые запросы

Health

curl http://localhost:6003/health

execute_query (минимум)

curl -sS -X POST "http://localhost:6003/api/execute_query" \
  -H "Content-Type: application/json" \
  -d '{"query":"ВЫБРАТЬ ПЕРВЫЕ 5 Наименование ИЗ Справочник.Контрагенты"}'

execute_code (минимум)

curl -sS -X POST "http://localhost:6003/api/execute_code" \
  -H "Content-Type: application/json" \
  -d '{"code":"Результат = ТекущаяДата();"}'

get_metadata (root summary)

curl http://localhost:6003/api/get_metadata

12 эндпоинтов

Полная справка по всем параметрам, ответам, граничным случаям, всем вариантам curl - references/tools-full-reference.md.

Формат ответов: TOON по умолчанию

Внешняя обёртка всегда JSON:

{"success": true, "data": <result>}
{"success": false, "error": "описание"}

Поле data по умолчанию закодировано в TOON (компактный текстовый формат, экономит 30-60% токенов по сравнению с JSON). Переключается через env RESPONSE_FORMAT=json на сервере или в форме обработки.

TOON-формат:

• [N] - массив длины N
• [N]{"Колонка1","Колонка2"}: ... - таблица с N строк и колонками
• Скаляры - как "ключ": значение

Передача ссылок: object_description

В ответах execute_query поля ссылочного типа возвращаются как:

{
  "_objectRef": true,
  "УникальныйИдентификатор": "ba7e5a3d-1234-5678-9abc-def012345678",
  "ТипОбъекта": "СправочникСсылка.Контрагенты",
  "Представление": "ООО Рога и Копыта"
}

Эта структура - input для get_link_of_object, find_references_to_object, get_event_log (фильтр по объекту), а также передаётся в params для execute_query:

{
  "query": "ВЫБРАТЬ ... ИЗ Документ.Реализация ГДЕ Контрагент = &К",
  "params": {
    "К": {
      "_objectRef": true,
      "УникальныйИдентификатор": "ba7e5a3d-...",
      "ТипОбъекта": "СправочникСсылка.Контрагенты"
    }
  }
}

Полная спецификация - references/object-description-format.md.

Типичные ошибки и обходы

"Не задано значение параметра"

В execute_query параметр запроса передан не как params. Использовать ключ params, не parameters.

Регистр бухгалтерии Хозрасчетный: "Поле не найдено X.Счет" / "X.Субконто1"

Регистр двусторонний (Корреспонденция=true). В физической таблице есть только СчетДт, СчетКт. Поля Счет, Субконто1..3 доступны только в виртуальных таблицах: ОборотыДтКт, ДвиженияССубконто, Обороты, Остатки.

"Поле не найдено Организация" в условии ОборотыДтКт

В виртуальных таблицах Хозрасчетного условие на Организация через 6-й параметр не всегда работает. Использовать ДвиженияССубконто (условие в 3-м параметре, на физические поля), либо отбор через КорСубконтоИзмерения.

"Неверные параметры РегистрБухгалтерии.Хозрасчетный.Обороты"

Параметры виртуальных таблиц регистра бухгалтерии (важна последовательность):

• .Остатки(): 3 параметра (Период, Субконто, Условие)
• .Обороты(): 6 параметров (НачП, КонП, Периодичность, Субконто, Условие, КорСубконто)
• .ОстаткиИОбороты(): 6 параметров
• .ОборотыДтКт(): 6 параметров (НачП, КонП, Периодичность, СубконтоДт, СубконтоКт, Условие)
• .ДвиженияССубконто(): 5 параметров (НачП, КонП, Условие, Порядок, Первые)

execute_code: "Процедура или функция с именем не определена (ДатаВремя)"

В BSL ДатаВремя - это токен языка запросов, не функция платформы. В коде использовать Дата(2026, 1, 1).

execute_code: запрос внутри Запрос.Текст должен быть однострочным

Внутри литерала Запрос.Текст = "..." текст запроса должен быть на одной строке. Многострочное форматирование через \n внутри литерала ломает парсер.

Правильно:

Запрос.Текст = "ВЫБРАТЬ Ссылка, Наименование ИЗ Справочник.Контрагенты ГДЕ НЕ ПометкаУдаления";

execute_code: запрещённые ключевые слова

По умолчанию блокируются: Удалить, Записать, УстановитьПривилегированныйРежим, COMОбъект, УдалитьФайлы и др. Список настраивается в обработке. Для тестов на запись - либо снять защиту в форме, либо использовать API объектов в обход ключевого слова (например, Объект = Документ.СоздатьДокумент(); Объект.Записать() не пройдёт из-за Записать).

Типичные паттерны

Прямой вызов экспортной функции модуля выгрузки

curl -sS -X POST "http://localhost:6003/api/execute_code" \
  -H "Content-Type: application/json" \
  -d '{"code":"Орг = Справочники.Организации.НайтиПоНаименованию(\"МояОрганизация\"); Дата1 = Дата(2026,1,1); Дата2 = Дата(2026,3,31,23,59,59); Рез = МойМодульВыгрузки.СформироватьДанные(Дата1, Дата2, Орг); Результат = Новый Структура(\"КоличествоСтрок,Ошибки\", Рез.Данные.Количество(), Рез.Ошибки);"}'

Сводка по проводкам двустороннего Хозрасчетного через UNION

ВЫБРАТЬ Сторона.КодСчета, СУММА(Сторона.СуммаДт), СУММА(Сторона.СуммаКт)
ИЗ (
    ВЫБРАТЬ ПСД.Код КАК КодСчета, Х.Сумма КАК СуммаДт, 0 КАК СуммаКт
    ИЗ РегистрБухгалтерии.Хозрасчетный КАК Х
    ВНУТРЕННЕЕ СОЕДИНЕНИЕ ПланСчетов.Хозрасчетный КАК ПСД ПО Х.СчетДт = ПСД.Ссылка
    ГДЕ Х.Период МЕЖДУ &Д1 И &Д2
    ОБЪЕДИНИТЬ ВСЕ
    ВЫБРАТЬ ПСК.Код, 0, Х.Сумма
    ИЗ РегистрБухгалтерии.Хозрасчетный КАК Х
    ВНУТРЕННЕЕ СОЕДИНЕНИЕ ПланСчетов.Хозрасчетный КАК ПСК ПО Х.СчетКт = ПСК.Ссылка
    ГДЕ Х.Период МЕЖДУ &Д1 И &Д2
) КАК Сторона
СГРУППИРОВАТЬ ПО Сторона.КодСчета

Передача параметра-ссылки в запрос

curl -sS -X POST "http://localhost:6003/api/execute_query" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "ВЫБРАТЬ КОЛИЧЕСТВО(*) КАК Кол ИЗ Документ.РеализацияТоваровУслуг ГДЕ Организация = &Орг",
    "params": {
      "Орг": {
        "_objectRef": true,
        "УникальныйИдентификатор": "6c8dc482-05c6-11f1-9096-bc2411e10804",
        "ТипОбъекта": "СправочникСсылка.Организации"
      }
    }
  }'

Готовые workflow

Полные многошаговые сценарии с командами и ответами - в references/workflow-examples.md:

1. Explore an unfamiliar database - разведка БД (health → metadata summary → list → detail → sample query)
2. Investigate object dependencies - проверка зависимостей объекта (execute_query → find_references → access_rights → event_log)
3. Diagnose event log errors - диагностика ошибок из журнала (get_event_log с пагинацией → execute_query вокруг ошибочных объектов)

Цикл deploy через MCP Toolkit + EDT

Типичный цикл "правка кода - проверка в живой базе":

1. Внести изменения в код в EDT, запустить mcp__1c-edt__validate_query для запросов
2. Закрыть 1С через MCP Toolkit:

   curl -sS -X POST "http://localhost:6003/api/execute_code" \
     -H "Content-Type: application/json" \
     -d '{"code":"ЗавершитьРаботуСистемы(Ложь, Ложь);","execution_context":"client"}'
   

3. Обновить конфигурацию: mcp__1c-edt__update_database
4. Запустить 1С с MCP Toolkit: scripts/start-1c.ps1 ...
5. Дождаться поднятия: polling curl http://localhost:6003/health до 200
6. Прогнать тестовые запросы через execute_query / execute_code

Совместимость

• Платформа 1С: 8.2.13+ и 8.3.25+ (включая 8.3.27)
• Архитектура: x64 (основной EPF) и x86 (отдельный EPF)
• Запуск только в тонком (1cv8c.exe) или толстом (1cv8.exe) клиенте. Через web-клиент нативная компонента не работает.

Channel routing (multi-database)

Если запущено несколько обработок MCP_Toolkit с разными channel - передавать ?channel=<name> в URL:

curl -sS "http://localhost:6003/api/execute_query?channel=dev" \
  -H "Content-Type: application/json" \
  -d '{"query":"ВЫБРАТЬ 1"}'

Regex для имени: ^[a-zA-Z0-9_-]{1,64}$. По умолчанию default.

Связанные скиллы

• composing-1c-queries - синтаксис языка запросов 1С (составление query для execute_query, виртуальные таблицы регистров, временные таблицы, JOIN-ы)

Ссылки на references

• references/tools-full-reference.md - полная справка по всем 12 эндпоинтам: параметры, ответы, граничные случаи
• references/object-description-format.md - спецификация формата object_description
• references/workflow-examples.md - готовые многошаговые сценарии с полным curl-выводом

Источник

Репозиторий: https://github.com/ROCTUP/1c-mcp-toolkit

Этот скилл собран на основе родного скилла calling-1c-rest-api-via-curl из репо MCP-toolkit с дополнениями: раздел запуска 1С, готовые PowerShell-скрипты, EPF в bin/, типичные ошибки и паттерны из практики работы с реальными ИБ.