1c-mcp-toolkit

name	1c-mcp-toolkit
description	>

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-проекта)
• Чтение журнала регистрации с фильтрацией
• Поиск ссылок на объект ("где используется этот контрагент")
• Диагностика прав доступа

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

Задача	Лучше использовать
Чтение BSL-кода, навигация по модулям	mcp__1c-edt__read_method_source, get_module_structure
Валидация запроса до запуска	mcp__1c-edt__validate_query
Метаданные в режиме разработки (XML)	mcp__1c-edt__get_metadata_objects/get_metadata_details
Семантический поиск по коду	mcp__1c-edt__search_in_code, find_references
Запрос без живой БД (только EDT)	mcp__1c-edt__execute_query (если доступен)
Проверка качества BSL	mcp__1c-naparnik__ask_1c_ai

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 эндпоинтов

#	Эндпоинт	Метод	Назначение
1	get_metadata	GET/POST	Метаданные: типы, объекты, реквизиты, поиск по атрибуту
2	execute_query	POST	Выполнить запрос 1С, вернуть набор записей
3	execute_code	POST	Выполнить BSL-код, вернуть значение Результат
4	get_object_by_link	POST	Получить объект по navigation link
5	get_link_of_object	POST	Сформировать navigation link из object_description
6	find_references_to_object	POST	Найти все ссылки на объект в БД
7	get_access_rights	POST	Права на объект для роли/пользователя
8	get_event_log	POST	Журнал регистрации с фильтрацией и пагинацией
9	get_bsl_syntax_help	POST	Встроенная справка платформы 1С
10	submit_for_deanonymization	POST	Деанонимизация ответа (если анонимизация включена)
11	restart_1c_session	POST	Перезапуск сессии (подхват изменений конфигурации)
12	close_1c_session	POST	Закрытие сессии (для эксклюзивного доступа к БД)

Полная справка по всем параметрам, ответам, граничным случаям, всем вариантам 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/, типичные ошибки и паттерны.