| 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 лежит прямо в скилле:
Минимальная 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:
- Explore an unfamiliar database - разведка БД (health → metadata summary →
list → detail → sample query)
- Investigate object dependencies - проверка зависимостей объекта
(execute_query → find_references → access_rights → event_log)
- Diagnose event log errors - диагностика ошибок из журнала
(get_event_log с пагинацией → execute_query вокруг ошибочных объектов)
Цикл deploy через MCP Toolkit + EDT
Типичный цикл "правка кода - проверка в живой базе":
- Внести изменения в код в EDT, запустить
mcp__1c-edt__validate_query для
запросов
- Закрыть 1С через MCP Toolkit:
curl -sS -X POST "http://localhost:6003/api/execute_code" \
-H "Content-Type: application/json" \
-d '{"code":"ЗавершитьРаботуСистемы(Ложь, Ложь);","execution_context":"client"}'
- Обновить конфигурацию:
mcp__1c-edt__update_database
- Запустить 1С с MCP Toolkit:
scripts/start-1c.ps1 ...
- Дождаться поднятия: polling
curl http://localhost:6003/health до 200
- Прогнать тестовые запросы через
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
Источник
Репозиторий: https://github.com/ROCTUP/1c-mcp-toolkit
Этот скилл собран на основе родного скилла calling-1c-rest-api-via-curl из
репо MCP-toolkit с дополнениями: раздел запуска 1С, готовые PowerShell-скрипты,
EPF в bin/, типичные ошибки и паттерны.
