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. **Карта портов проекта.** Сначала взять карту "среда/ИБ -> порт" из 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/`, типичные ошибки и паттерны.