# MCP 1C Local Bridge

MCP-сервер и внешняя обработка 1С, через которые ИИ-агент (Claude Code или другой MCP-клиент) выполняет
запросы, выражения и код в открытом сеансе 1С пользователя. Всё работает на компьютере разработчика:
команды и ответы передаются через каталог в профиле пользователя, промежуточного сервера нет.

## Как это устроено

```
 MCP-клиент (Claude Code)
        | stdio
 MCP-сервер mcp-1c-local-bridge (Python, запускается клиентом на время сессии)
        | файлы JSON
 %TEMP%\mcp-1c-local-bridge\<сеанс>\in, work, out, session.json
        | опрос раз в 0,5 с
 обработка MCPLocalBridge.epf, открытая в клиенте 1С
        | вызов сервера в том же сеансе
 сервер 1С
```

- MCP-сервер кладёт команду файлом в каталог сеанса и ждёт файл ответа.
- Форма обработки раз в полсекунды забирает команды, выполняет их на сервере 1С (или на клиенте) в сеансе
  пользователя и с его правами, пишет ответ и раз в 2 секунды обновляет `session.json` (сердцебиение).
- Обмен идёт на стороне клиента 1С: сервер 1С до компьютера пользователя не достаёт, поэтому каталог - на
  этом компьютере, и данные дальше него не уходят.
- Несколько сессий агента и несколько открытых баз работают одновременно: у каждой открытой формы свой
  каталог сеанса, у каждой команды - свой идентификатор.

## Требования

- Windows с клиентом 1С:Предприятие 8.3 (тонкий клиент). Обработка рассчитана на режим совместимости
  конфигурации от 8.3.14 и не использует `Асинх`/`Ждать`.
- В конфигурации разрешены синхронные вызовы: свойство «Режим использования синхронных вызовов расширений
  платформы и внешних компонент» - «Использовать» или «Использовать с предупреждениями». Обработка работает
  с файлами на клиенте синхронными методами.
- У пользователя есть право открывать внешние обработки.
- Python 3.11+ и [uv](https://docs.astral.sh/uv/). MCP-сервер запускается в WSL или в Windows.

## Установка

```bash
git clone https://github.com/ntappw/mcp-1c-local-bridge.git
cd mcp-1c-local-bridge
uv sync
```

Регистрация в Claude Code (уровень пользователя):

```bash
claude mcp add --scope user 1c-local-bridge -- "$PWD/.venv/bin/mcp-1c-local-bridge"
```

В Windows без WSL путь к запуску - `.venv\Scripts\mcp-1c-local-bridge.exe`. После регистрации
перезапустите сессию Claude Code (в VS Code - окно), чтобы клиент подхватил сервер.

Каталог обмена MCP-сервер находит сам: из WSL берёт `%TEMP%` пользователя Windows через PowerShell.
Переопределить можно переменной `MCP_1C_BRIDGE_DIR` (путь в той файловой системе, где запущен сервер).

## Работа

1. Откройте `dist/MCPLocalBridge.epf` в нужной базе: «Файл - Открыть» (Ctrl+O). Форма - HTML-страница:
   состояние моста, база и пользователь, режим выдачи результатов, разрешения агенту и журнал команд.
2. Агент вызывает `sessions`, видит сеанс и шлёт команды. Пока форма открыта, сеанс жив; закрыли форму -
   каталог сеанса удаляется, команды больше не принимаются.
3. В журнале по каждой команде видны время, вид, текст, итог, краткий результат и длительность. Строка
   раскрывается щелчком прямо в списке: полный текст команды, параметры, результат, сообщения и ошибка.
   Раскрытые строки и прокрутка не сбрасываются, когда приходят новые команды.
4. «Приостановить» останавливает выполнение: команды ждут в очереди. При открытии формы «Запись в базу»
   выключена, «Код на клиенте» включён; оба переключаются тумблерами на форме.

### Выдача результатов

- **Автоматически** (по умолчанию) - ответ уходит агенту сразу после выполнения команды.
- **С подтверждением** - выполненная команда показывается на форме вместе с результатом, и агент получает его
  только после кнопки «Отдать агенту». «Не отдавать» возвращает агенту статус `denied` без данных. Пока
  результат ждёт решения, следующие команды стоят в очереди. Вызов агента, не дождавшийся решения за
  `timeout`, сообщает, что результат ждёт пользователя, и забирает ответ позже инструментом `result`.

### Инструменты

| Инструмент | Что делает |
| --- | --- |
| `sessions` | Открытые сеансы моста: база, пользователь, конфигурация, режим совместимости, состояние, разрешения |
| `ping` | Проверка связи: время сервера 1С, номер сеанса, пользователь |
| `query` | Запрос 1С с параметрами; возвращает все результаты пакета, `row_limit` строк каждого |
| `eval` | `Вычислить(<выражение>)` на сервере или на клиенте |
| `execute` | `Выполнить(<код>)`; результат - значение переменной `Результат` |
| `metadata` | Состав конфигурации с отбором или описание объекта по полному имени, включая объекты расширений |
| `result` | Результат команды, не уложившейся в `timeout` |
| `cancel` | Снять команду, которую обработка ещё не начала |

У команд есть `session` (идентификатор или часть строки соединения; не нужен, если сеанс один) и `timeout`
(до 280 с). Команда, которую обработка не начала за `timeout`, снимается и уже не выполнится; начатая
выполняется дальше, а вызов возвращает её идентификатор для `result`. Ответ больше 20 000 символов
сохраняется в `~/.cache/mcp-1c-local-bridge/results/`, в ответ инструмента попадают начало и пути к файлам.

### Значения

Ответ обработки - JSON. Ссылка приходит объектом `{"_type": "Справочник.Контрагенты", "_uuid": "...",
"_presentation": "..."}`, значение перечисления - `{"_type": "Перечисление.X", "_name": "...", ...}`,
дата - строкой `2026-10-21T00:00:00`, `NULL` и `Неопределено` - `null`. Таблица значений, результат запроса
и набор записей регистра - колонками и строками (не больше `row_limit`, по умолчанию 1000), объект
справочника или документа - реквизитами и табличными частями. В формате `table` ссылки показываются
представлениями, в `json` - целиком.

Параметры `query` - объект «имя: значение». Простые значения передаются как есть, массив - списком для
`В (&Список)`, особые значения - объектами:

| Объект | Значение 1С |
| --- | --- |
| `{"_date": "2026-10-21"}` | дата (можно с временем) |
| `{"_type": "Справочник.Контрагенты", "_uuid": "..."}` | ссылка; ссылку из ответа можно передать целиком |
| `{"_type": "Перечисление.ВидыКонтрагентов", "_name": "ЮридическоеЛицо"}` | значение перечисления |
| `{"_predefined": "Справочник.Валюты.Рубль"}` | предопределённое значение |
| `{"_expr": "НачалоГода(ТекущаяДатаСеанса())"}` | выражение, вычисленное на сервере |

Пример кода для `execute`:

```bsl
Выборка = Справочники.Валюты.Выбрать();
Результат = Новый Массив;
Пока Выборка.Следующий() Цикл
	Результат.Добавить(Выборка.Ссылка);
КонецЦикла;
```

## Безопасность и ограничения

- Код агента выполняется в живом сеансе пользователя и с его правами. Пока команда идёт, окно 1С не
  отвечает; ошибка платформы в такой команде может уронить сеанс пользователя.
- Серверный код `eval` и `execute` по умолчанию выполняется в транзакции, которая после выполнения
  откатывается: изменения в базе не сохраняются. Откат не отменяет внешних эффектов - файлов, HTTP-запросов,
  почты, запуска фоновых заданий, записей журнала регистрации. Сохранить изменения можно только с
  `allow_write=true` и при включённом на форме разрешении «Запись в базу». Пока оно выключено (так при открытии
  формы), запрос записи тоже выполняется с откатом, а в ответе агенту приходит предупреждение.
- Код на клиенте (`side=client`) выполняется в модуле формы обработки, без транзакции, и только при
  разрешении «Код на клиенте». Разрешения и режим выдачи после такого кода восстанавливаются: сам себе код их
  не включит.
- Каталог обмена лежит в профиле пользователя Windows (`%TEMP%`). Команду в него может положить любой процесс
  под этой учётной записью - тот же уровень доверия, что и у самого сеанса 1С.
- Если на экране модальное окно 1С (например, ошибка компиляции вызванного модуля), обработка не выполняет
  команды, пока окно не закроют. `sessions` показывает такой сеанс как неотвечающий.
- В Claude Code не добавляйте `execute` и `eval` в список разрешённых без вопроса: тогда каждый вызов
  подтверждается вручную.

## Сборка обработки

Исходники обработки - XML-выгрузка в `epf/`, собранный файл - `dist/MCPLocalBridge.epf`. Сборке нужна
лицензия 1С, поэтому скрипт подключает конфигуратор к серверной базе (лучше тестовой или копии); в базу
ничего не загружается:

```powershell
powershell -NoProfile -ExecutionPolicy Bypass -File scripts\build-epf.ps1 -Server <сервер> -Ref <база>
```

Модули `.bsl` хранятся в UTF-8 с BOM и переводами строк CRLF, как их выгружает конфигуратор.

## Протокол

Формат каталога обмена, команд и ответов - [docs/protocol.md](docs/protocol.md).

## Разработка

```bash
uv run pytest
```

Тесты проверяют MCP-сторону с имитацией обработки в отдельном потоке. Обработку проверяют в 1С: открыть
собранный файл в тестовой базе и прогнать `ping`, `query`, `eval`, `execute`, `metadata`.

## Лицензия

[MIT](LICENSE)