1c-mcp-toolkit · git:20260828.2b87e3e · 2026-08-28 · sha256 0540190b431ab888
1c-mcp-toolkit git:20260828.2b87e3eA
Immutable. This exact content is served forever at /api/v1/blob/0540190b431ab888.
---
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. **Карта портов проекта.** Сначала взять карту "среда/ИБ -> порт" из 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-цикл:
```sh
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](bin/MCP_Toolkit.epf) - x64 (основная)
- [bin/MCP_Toolkit_x86.epf](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`):
> ```sh
> '/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):
```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](scripts/start-1c.ps1).
Пример:
```powershell
& "$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. Проверка готовности
```sh
curl http://localhost:6003/health
```
`200 OK` - сервер на 6003 работает, можно делать запросы.
### 3. Закрытие 1С (например, для deploy через EDT)
```sh
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](scripts/stop-1c.ps1).
`execution_context: "client"` обязателен - `ЗавершитьРаботуСистемы` доступна
только на клиенте.
## Когда использовать MCP Toolkit
- Проверка реальных данных в живой БД (полнота тестовых данных, корректность
миграции, количество записей)
- Прямой вызов экспортных функций модулей выгрузки/обмена без UI
- Поиск конкретных проводок/документов для воспроизведения багов
- Чтение метаданных из живой БД (когда нет открытого EDT-проекта)
- Чтение журнала регистрации с фильтрацией
- Поиск ссылок на объект ("где используется этот контрагент")
- Диагностика прав доступа
## Когда НЕ использовать (есть альтернатива получше)
| Задача | Лучше использовать |
|--------|--------------------|
| Чтение BSL-кода, навигация по модулям | `mcp__ai-edt__read_method_source`, `get_module_structure` |
| Валидация запроса до запуска | `mcp__ai-edt__validate_query` |
| Метаданные в режиме разработки (XML) | `mcp__ai-edt__get_metadata_objects/get_metadata_details` |
| Семантический поиск по коду | `mcp__ai-edt__search_in_code`, `find_references` |
| Запрос без живой БД (только EDT) | `mcp__ai-edt__execute_query` (если доступен) |
| Проверка качества BSL | `mcp__1c-naparnik__ask_1c_ai` |
MCP Toolkit заточен под **живую запущенную базу**, EDT - под dev-режим с
исходниками. Не дублируй вызовы.
## Базовые запросы
### Health
```sh
curl http://localhost:6003/health
```
### execute_query (минимум)
```sh
curl -sS -X POST "http://localhost:6003/api/execute_query" \
-H "Content-Type: application/json" \
-d '{"query":"ВЫБРАТЬ ПЕРВЫЕ 5 Наименование ИЗ Справочник.Контрагенты"}'
```
### execute_code (минимум)
```sh
curl -sS -X POST "http://localhost:6003/api/execute_code" \
-H "Content-Type: application/json" \
-d '{"code":"Результат = ТекущаяДата();"}'
```
### get_metadata (root summary)
```sh
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](references/tools-full-reference.md).
## Формат ответов: TOON по умолчанию
Внешняя обертка всегда JSON:
```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` поля ссылочного типа возвращаются как:
```json
{
"_objectRef": true,
"УникальныйИдентификатор": "ba7e5a3d-1234-5678-9abc-def012345678",
"ТипОбъекта": "СправочникСсылка.Контрагенты",
"Представление": "ООО Рога и Копыта"
}
```
Эта структура - input для `get_link_of_object`, `find_references_to_object`,
`get_event_log` (фильтр по объекту), а также передается в `params` для
`execute_query`:
```json
{
"query": "ВЫБРАТЬ ... ИЗ Документ.Реализация ГДЕ Контрагент = &К",
"params": {
"К": {
"_objectRef": true,
"УникальныйИдентификатор": "ba7e5a3d-...",
"ТипОбъекта": "СправочникСсылка.Контрагенты"
}
}
}
```
Полная спецификация - [references/object-description-format.md](references/object-description-format.md).
## Правила экранирования curl
При сборке curl-команд с JSON-payload, содержащим BSL-код и запросы 1С, участвует
несколько уровней кавычек. Правила ниже - для bash/sh (Bash tool). В PowerShell
экранирование иное: одинарные кавычки тоже литерал, но `!` не раскрывается, а `$` в
двойных кавычках подставляется.
### Правило 1: одинарные кавычки для payload `-d` (рекомендуется)
Одинарные кавычки запрещают bash интерпретировать `$`, `!`, `&`, обратные кавычки и
прочие спецсимволы внутри payload. Двойные кавычки тоже работают, но требуют
аккуратности.
```sh
# Рекомендуется - одинарные кавычки, bash ничего внутри не трогает:
curl ... -d '{"query":"ВЫБРАТЬ 1"}'
# Тоже работает, но bash интерпретирует спецсимволы - осторожно:
curl ... -d "{\"query\":\"ВЫБРАТЬ 1\"}"
```
### Правило 2: строковые значения в запросах - всегда через параметры
Вместо встраивания строковых литералов прямо в текст запроса (что требует сложного
экранирования) - всегда передавать их как параметры. Это полностью устраняет
вложенные кавычки.
```sh
# ХОРОШО - значение передано параметром, без вложенных кавычек:
curl ... -d '{"query":"ВЫБРАТЬ Ссылка ИЗ Справочник.Контрагенты ГДЕ Статус = &Статус", "params":{"Статус":"Активный"}}'
# ХОРОШО - то же для execute_code:
curl ... -d '{"code":"Запрос = Новый Запрос;\nЗапрос.Текст = \"ВЫБРАТЬ Ссылка ИЗ Справочник.Контрагенты ГДЕ Статус = &Статус\";\nЗапрос.УстановитьПараметр(\"Статус\", \"Активный\");\nРезультат = Запрос.Выполнить().Выгрузить();"}'
```
### Правило 3: избегать `!` в строковых значениях
Bash интерпретирует `!` как history expansion даже внутри некоторых контекстов
кавычек. Никогда не использовать `!` в строковых литералах - заменять безопасными
альтернативами.
```sh
# ПЛОХО - ! запускает history expansion:
-d '{"code":"...ТОГДА \"!!! ВЫСОКАЯ\"..."}'
# ХОРОШО - без восклицательных знаков:
-d '{"code":"...ТОГДА \"ВЫСОКАЯ\"..."}'
```
### Правило 4: строковые литералы внутри запроса (edge-case)
Если литерал в тексте запроса без параметра неизбежен, экранирование зависит от
контекста:
execute_query - один уровень JSON-экранирования (`\"`):
```sh
curl ... -d '{"query":"ВЫБРАТЬ Ссылка ИЗ Справочник.Контрагенты ГДЕ Наименование ПОДОБНО \"%Рога%\""}'
```
execute_code - экранирование строки 1С `""` плюс JSON-экранирование (`\"\"`):
```sh
curl ... -d '{"code":"Запрос.Текст = \"ВЫБРАТЬ Ссылка ИЗ Справочник.Контрагенты ГДЕ Наименование ПОДОБНО \"\"%Рога%\"\"\";"}'
```
По возможности всегда предпочитать Правило 2 (параметры).
### Краткая справка
| Символ | Проблема | Решение |
|--------|----------|---------|
| `"` внутри строки запроса | Вложенное экранирование | Передать значение параметром (Правило 2) |
| `!` | Bash history expansion | Избегать полностью |
| `&` | Bash интерпретирует в двойных кавычках | Безопасно внутри payload в одинарных кавычках |
| `\n` | Перенос строки в JSON-строке | Для разделения операторов 1С, НЕ внутри текста запроса |
## Типичные ошибки и обходы
### "Не задано значение параметра"
В `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` внутри литерала ломает парсер.
Правильно:
```bsl
Запрос.Текст = "ВЫБРАТЬ Ссылка, Наименование ИЗ Справочник.Контрагенты ГДЕ НЕ ПометкаУдаления";
```
### execute_code: запрещенные ключевые слова
По умолчанию блокируются: `Удалить`, `Записать`, `УстановитьПривилегированныйРежим`,
`COMОбъект`, `УдалитьФайлы` и др. Список настраивается в обработке. Для тестов на
запись - либо снять защиту в форме, либо использовать API объектов в обход
ключевого слова (например, `Объект = Документ.СоздатьДокумент(); Объект.Записать()`
не пройдет из-за `Записать`).
## Типичные паттерны
### Открытие формы в сеансе 1С (execution_context=client)
Отдельного эндпоинта `open_form` НЕТ (проверено по ROCTUP, 27.07.2026: 12 эндпоинтов без
него). Форму открывает `ОткрытьФорму(...)` в КЛИЕНТСКОМ контексте - проверено рабочим:
```sh
curl -sS -X POST "http://localhost:6003/api/execute_code" -d '{"code":"ОткрытьФорму(\"Документ.Х.ФормаСписка\"); Результат=\"OK\";","execution_context":"client"}'
```
Форма откроется в окне ЗАПУЩЕННОГО сеанса 1С (не headless - пользователь видит ее на
экране). Список: `.ФормаСписка` (или без указания формы - автоформа списка); объект:
`ОткрытьФорму("Документ.Х.ФормаОбъекта", Новый Структура("Ключ", СсылкаНаОбъект))`.
Для АГЕНТА картинку формы дает EDT MCP `get_form_screenshot` (сам toolkit возвращает
только текст/данные, не изображение).
### Прямой вызов экспортной функции модуля выгрузки
```sh
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
```sql
ВЫБРАТЬ Сторона.КодСчета, СУММА(Сторона.СуммаДт), СУММА(Сторона.СуммаКт)
ИЗ (
ВЫБРАТЬ ПСД.Код КАК КодСчета, Х.Сумма КАК СуммаДт, 0 КАК СуммаКт
ИЗ РегистрБухгалтерии.Хозрасчетный КАК Х
ВНУТРЕННЕЕ СОЕДИНЕНИЕ ПланСчетов.Хозрасчетный КАК ПСД ПО Х.СчетДт = ПСД.Ссылка
ГДЕ Х.Период МЕЖДУ &Д1 И &Д2
ОБЪЕДИНИТЬ ВСЕ
ВЫБРАТЬ ПСК.Код, 0, Х.Сумма
ИЗ РегистрБухгалтерии.Хозрасчетный КАК Х
ВНУТРЕННЕЕ СОЕДИНЕНИЕ ПланСчетов.Хозрасчетный КАК ПСК ПО Х.СчетКт = ПСК.Ссылка
ГДЕ Х.Период МЕЖДУ &Д1 И &Д2
) КАК Сторона
СГРУППИРОВАТЬ ПО Сторона.КодСчета
```
### Передача параметра-ссылки в запрос
```sh
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](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:
```sh
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:
```sh
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](references/tools-full-reference.md) -
полная справка по всем 12 эндпоинтам: параметры, ответы, граничные случаи
- [references/object-description-format.md](references/object-description-format.md) -
спецификация формата `object_description`
- [references/workflow-examples.md](references/workflow-examples.md) -
готовые многошаговые сценарии с полным curl-выводом
## Источник
Репозиторий: https://github.com/ROCTUP/1c-mcp-toolkit
Этот скилл собран на основе родного скилла `calling-1c-rest-api-via-curl` из
репо MCP-toolkit с дополнениями: раздел запуска 1С, готовые PowerShell-скрипты,
EPF в `bin/`, типичные ошибки и паттерны.