1c MCP Toolkit

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. Карта портов проекта. Сначала взять карту "среда/ИБ -> порт" из CLAUDE.md ТЕКУЩЕГО проекта (секция "MCP Toolkit") или памяти проекта. Есть карта - работать с нужным портом, probe пропустить. Нет карты - после probe предложить пользователю добавить ее в CLAUDE.md.

2. Health-probe вместо вопросов. Не спрашивать "toolkit запущен? какой порт?": pwsh scripts/health-probe.ps1 (обход типовых 6003/6004/6005/6010/6013/6023/6033/7003) или bash-цикл:

   for p in 6003 6004 6005 6010 6013 6023 6033 7003; do
     curl -sS -m 2 "http://localhost:$p/health" >/dev/null 2>&1 && echo "порт $p жив"
   done
   

3. Ничего не живо - запустить самому. scripts/start-1c.ps1 -AutoStart, если параметры базы (платформа, путь, пользователь) известны из карты/памяти. Спрашивать пользователя только при неизвестных параметрах.

4. Полный цикл - самостоятельно. Обновить ИБ и проверить данные = один заход без ручного handoff: stop-1c.ps1 (или execute_code ЗавершитьРаботуСистемы) -> update_database (EDT MCP) -> start-1c.ps1 -AutoStart -> health -> запросы. Пользователя дергать только если неизвестны платформа/база/учетка ИЛИ он явно просил паузу (демо, живой показ).

5. Ошибка "функция не определена" / connection refused - чаще всего toolkit просто не запущен: сначала health-probe и перезапуск, потом разбор кода.

6. Не предлагать рестарт rphost/rmngr при обычном обновлении конфигурации - это не нужно (зона администраторов).

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

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

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

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

Запускать .ps1-скрипты ниже строго через PowerShell 7 (pwsh), НЕ через powershell.exe (5.1). PS 5.1 спотыкается на кириллице в JSON-телах toolkit (stop-1c.ps1 со ЗавершитьРаботуСистемы и т.п. - "не смог распарсить stop-скрипт"). Инструмент PowerShell агента уже работает на pwsh 7 - используй его. Из Bash tool вызывай pwsh явно (не powershell.exe):

'/c/Program Files/PowerShell/7/pwsh.exe' -NoProfile -ExecutionPolicy Bypass -Command '& "$HOME\.claude\skills\1c-mcp-toolkit\scripts\start-1c.ps1" -Platform "8.3.27.2074" -Database "..." -User "..." -Password "..."'

Минимальная PowerShell-команда (в pwsh 7):

& "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 "C:\Bases\MyDB" `
    -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.

Правила экранирования curl

При сборке curl-команд с JSON-payload, содержащим BSL-код и запросы 1С, участвует несколько уровней кавычек. Правила ниже - для bash/sh (Bash tool). В PowerShell экранирование иное: одинарные кавычки тоже литерал, но ! не раскрывается, а $ в двойных кавычках подставляется.

Правило 1: одинарные кавычки для payload -d (рекомендуется)

Одинарные кавычки запрещают bash интерпретировать $, !, &, обратные кавычки и прочие спецсимволы внутри payload. Двойные кавычки тоже работают, но требуют аккуратности.

# Рекомендуется - одинарные кавычки, bash ничего внутри не трогает:
curl ... -d '{"query":"ВЫБРАТЬ 1"}'

# Тоже работает, но bash интерпретирует спецсимволы - осторожно:
curl ... -d "{\"query\":\"ВЫБРАТЬ 1\"}"

Правило 2: строковые значения в запросах - всегда через параметры

Вместо встраивания строковых литералов прямо в текст запроса (что требует сложного экранирования) - всегда передавать их как параметры. Это полностью устраняет вложенные кавычки.

# ХОРОШО - значение передано параметром, без вложенных кавычек:
curl ... -d '{"query":"ВЫБРАТЬ Ссылка ИЗ Справочник.Контрагенты ГДЕ Статус = &Статус", "params":{"Статус":"Активный"}}'

# ХОРОШО - то же для execute_code:
curl ... -d '{"code":"Запрос = Новый Запрос;\nЗапрос.Текст = \"ВЫБРАТЬ Ссылка ИЗ Справочник.Контрагенты ГДЕ Статус = &Статус\";\nЗапрос.УстановитьПараметр(\"Статус\", \"Активный\");\nРезультат = Запрос.Выполнить().Выгрузить();"}'

Правило 3: избегать ! в строковых значениях

Bash интерпретирует ! как history expansion даже внутри некоторых контекстов кавычек. Никогда не использовать ! в строковых литералах - заменять безопасными альтернативами.

# ПЛОХО - ! запускает history expansion:
-d '{"code":"...ТОГДА \"!!! ВЫСОКАЯ\"..."}'

# ХОРОШО - без восклицательных знаков:
-d '{"code":"...ТОГДА \"ВЫСОКАЯ\"..."}'

Правило 4: строковые литералы внутри запроса (edge-case)

Если литерал в тексте запроса без параметра неизбежен, экранирование зависит от контекста:

execute_query - один уровень JSON-экранирования (\"):

curl ... -d '{"query":"ВЫБРАТЬ Ссылка ИЗ Справочник.Контрагенты ГДЕ Наименование ПОДОБНО \"%Рога%\""}'

execute_code - экранирование строки 1С "" плюс JSON-экранирование (\"\"):

curl ... -d '{"code":"Запрос.Текст = \"ВЫБРАТЬ Ссылка ИЗ Справочник.Контрагенты ГДЕ Наименование ПОДОБНО \"\"%Рога%\"\"\";"}'

По возможности всегда предпочитать Правило 2 (параметры).

Краткая справка

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

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

В 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 объектов в обход ключевого слова (например, Объект = Документ.СоздатьДокумент(); Объект.Записать() не пройдет из-за Записать).

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

Открытие формы в сеансе 1С (execution_context=client)

Отдельного эндпоинта open_form НЕТ (проверено по ROCTUP, 27.07.2026: 12 эндпоинтов без него). Форму открывает ОткрытьФорму(...) в КЛИЕНТСКОМ контексте - проверено рабочим:

curl -sS -X POST "http://localhost:6003/api/execute_code"   -d '{"code":"ОткрытьФорму(\"Документ.Х.ФормаСписка\"); Результат=\"OK\";","execution_context":"client"}'

Форма откроется в окне ЗАПУЩЕННОГО сеанса 1С (не headless - пользователь видит ее на экране). Список: .ФормаСписка (или без указания формы - автоформа списка); объект: ОткрытьФорму("Документ.Х.ФормаОбъекта", Новый Структура("Ключ", СсылкаНаОбъект)). Для АГЕНТА картинку формы дает EDT MCP get_form_screenshot (сам toolkit возвращает только текст/данные, не изображение).

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

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,
        "УникальныйИдентификатор": "ba7e5a3d-1234-5678-9abc-def012345678",
        "ТипОбъекта": "СправочникСсылка.Организации"
      }
    }
  }'

Готовые 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__ai-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__ai-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/, типичные ошибки и паттерны.