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С до компьютера пользователя не достаёт, поэтому каталог - на этом компьютере, и данные дальше него не уходят.

• Несколько сессий агента и несколько открытых баз работают одновременно: у каждой открытой формы свой каталог сеанса, у каждой команды - свой идентификатор.

Related MCP server: local-assistant-mcp

Требования

• Windows с клиентом 1С:Предприятие 8.3 (тонкий клиент). Обработка рассчитана на режим совместимости конфигурации от 8.3.14 и не использует Асинх/Ждать.

• В конфигурации разрешены синхронные вызовы: свойство «Режим использования синхронных вызовов расширений платформы и внешних компонент» - «Использовать» или «Использовать с предупреждениями». Обработка работает с файлами на клиенте синхронными методами.

• У пользователя есть право открывать внешние обработки.

• Python 3.11+ и uv. MCP-сервер запускается в WSL или в Windows.

Установка

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

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

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.

Инструменты

У команд есть 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 - объект «имя: значение». Простые значения передаются как есть, массив - списком для В (&Список), особые значения - объектами:

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

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

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

• Код агента выполняется в живом сеансе пользователя и с его правами. Пока команда идёт, окно 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 -NoProfile -ExecutionPolicy Bypass -File scripts\build-epf.ps1 -Server <сервер> -Ref <база>

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

Протокол

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

Разработка

uv run pytest

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

Лицензия

MIT