MCP 1C Local Bridge

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

Статья о проекте на Инфостарте: https://infostart.ru/1c/articles/2831401/

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

 MCP-клиент с ИИ-агентом
        | 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: 1c-mcp

Требования

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

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

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

• Python 3.11+ и uv. MCP-сервер запускается на том же компьютере, что и клиент 1С: в Windows или в WSL.

Установка

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

Сервер работает по stdio. Зарегистрируйте его в своём MCP-клиенте: команда запуска - <каталог клона>\.venv\Scripts\mcp-1c-local-bridge.exe, аргументов нет (если сервер запускается в WSL - <каталог клона>/.venv/bin/mcp-1c-local-bridge). Формат настроек у клиентов разный, во многих это JSON такого вида:

{
  "mcpServers": {
    "1c-local-bridge": {
      "command": "C:\\tools\\mcp-1c-local-bridge\\.venv\\Scripts\\mcp-1c-local-bridge.exe"
    }
  }
}

После регистрации перезапустите клиент, чтобы он подхватил сервер.

Каталог обмена по умолчанию - %TEMP%\mcp-1c-local-bridge пользователя Windows, MCP-сервер находит его сам. Другой каталог задаётся переменной окружения MCP_1C_BRIDGE_DIR - см. Свой каталог обмена.

Работа

1. Откройте dist/MCPLocalBridge.epf в нужной базе: «Файл - Открыть» (Ctrl+O). Форма - HTML-страница: состояние моста, база и пользователь, режим выдачи результатов, разрешения агенту и журнал команд. В толстом клиенте обычного приложения открывается обычная форма с тем же составом (см. «Обычное приложение и старые конфигурации»).

2. Агент вызывает sessions, видит сеанс и шлёт команды. Пока форма открыта, сеанс жив; закрыли форму - каталог сеанса удаляется, команды больше не принимаются. Если мост открыт в нескольких сеансах (например, одна база в двух клиентах), подскажите агенту нужный по идентификатору сеанса: его копирует в буфер обмена ссылка «скопировать» в шапке формы, в обычной форме - кнопка «Копировать идентификатор».

3. В журнале по каждой команде видны время, вид, текст, итог, краткий результат и длительность. Строка раскрывается щелчком прямо в списке: полный текст команды, параметры, результат, сообщения и ошибка. Раскрытые строки и прокрутка не сбрасываются, когда приходят новые команды.

4. «Приостановить» останавливает выполнение: команды ждут в очереди. При открытии формы «Запись в базу» выключена, «Код на клиенте» включён; оба переключаются тумблерами на форме.

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

• Автоматически (по умолчанию) - ответ уходит агенту сразу после выполнения команды.

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

  К решению можно приложить комментарий агенту: при отказе - почему результат не отдан и что исправить в запросе, при выдаче - что учесть в результате. Агент получает комментарий вместе с ответом и может сразу прислать исправленный запрос. Разрешений на форме комментарий не меняет.

Свой каталог обмена

По умолчанию обработка и MCP-сервер работают в %TEMP%\mcp-1c-local-bridge пользователя Windows, и настраивать ничего не нужно. Другой каталог можно задать, например, если %TEMP% чистится или его проверяет антивирус. Сами стороны каталог не согласуют, поэтому он задаётся в двух местах:

1. В обработке: в строке «Каталог обмена» нажмите «Изменить» и выберите каталог. Сеанс сразу переезжает в него с новым идентификатором, а выбор запоминается для пользователя 1С в этой базе и действует при следующих открытиях. Пока каталог не стандартный, форма напоминает, что MCP-серверу нужен тот же. «По умолчанию» возвращает стандартный каталог.

2. MCP-серверу: тот же каталог в переменной окружения MCP_1C_BRIDGE_DIR - путём, под которым каталог виден процессу MCP-сервера. Переменную задают в настройках сервера в MCP-клиенте, обычно в поле env:

   "1c-local-bridge": {
     "command": "C:\\tools\\mcp-1c-local-bridge\\.venv\\Scripts\\mcp-1c-local-bridge.exe",
     "env": {"MCP_1C_BRIDGE_DIR": "D:\\mcp\\exchange"}
   }

   После изменения перезапустите клиент. Проверка - инструмент sessions: в нём виден сеанс, а если сеансов нет - каталог, где их ищет MCP-сервер.

Чтобы вернуться к стандартному каталогу, нажмите «По умолчанию» в обработке и уберите переменную из настроек MCP-сервера.

Клиент 1С на терминальном сервере (RDP): %TEMP% там серверный, и MCP-сервер на вашем компьютере его не видит. Выберите в обработке каталог на диске своего компьютера, проброшенном в сеанс RDP («Локальные ресурсы - Диски» в настройках подключения), например \\tsclient\C\mcp-exchange, а в MCP_1C_BRIDGE_DIR - тот же каталог локально: C:\mcp-exchange. Код агента с side=client выполняется при этом на терминальном сервере: файлы, которые он пишет, остаются там, а не на вашем компьютере.

• MCP-сервер смотрит в один каталог. Если в разных базах выбраны разные каталоги, агент видит сеансы только из каталога MCP-сервера.

• Каталог должен быть доступен и клиенту 1С, и MCP-серверу.

• В каталоге обмена MCP-сервер трогает только папки сеансов (имя из 8 шестнадцатеричных символов) и пишет файл .clock, остальное содержимое не меняет.

Инструменты

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

Обычное приложение и старые конфигурации

Конфигурации на обычных формах (УТ 10.3, БП 2.0, УПП, КА 1.1) подключаются двумя способами:

• В тонком клиенте: конфигурация открывается в режиме управляемого приложения, и мост работает как обычно, в том числе в режиме совместимости 8.2.

• В толстом клиенте обычного приложения - в том же сеансе, где работает пользователь. Толстый клиент открывает у обработки её обычную форму: тот же мост на стандартных элементах - состояние, кнопки, флажки режима выдачи и разрешений, журнал команд таблицей и под ним подробности выбранной команды. Команды, выдача с подтверждением и комментарием, свой каталог обмена и индекс метаданных работают так же, как в управляемой форме; sessions показывает у такого сеанса «обычное приложение». Серверный код агента выполняет модуль объекта обработки в том же процессе толстого клиента, с тем же откатом транзакции. Отличия от тонкого клиента:

  • сообщения Сообщить() толстый клиент сразу выводит в окно сообщений 1С, агенту в ответе они не приходят;

  • код на клиенте (side=client) работает в толстом клиенте с полным доступом к базе, без транзакции и отката: запись из него флажок «Запись в базу» не останавливает, её держит только «Код на клиенте»;

  • выбор каталога обмена и предупреждения - модальные окна: пока такое окно открыто, команды не выполняются.

Индекс метаданных

find и usages работают по индексу метаданных сеанса: объекты конфигурации и активных расширений, их поля с типами, движения, подписки, регламентные задания, составы планов обмена, подсистем, функциональных опций, общих реквизитов. Первый вызов в сеансе моста просит индекс у обработки, дальше поиск идёт в памяти MCP-сервера и окно 1С не занимает.

Обработка хранит индекс в настройках пользователя этой базы и отдаёт оттуда, пока метаданные те же: версия конфигурации и расширения, состав объектов и число их полей. Иначе индекс строится заново - порциями до секунды, между которыми окно 1С отвечает; на форме виден процент. Построение дольше timeout не теряется: вызов сообщает, что индекс строится, повторный ждёт ту же команду. Смену типа или переименование поля без изменения их числа обработка не замечает: после загрузки таких изменений в базу передайте refresh=true.

Кода модулей в индексе нет: из режима Предприятия тексты модулей недоступны, обращения из кода ищутся по выгрузке конфигурации.

Значения

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

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

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

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

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

• Код агента выполняется в живом сеансе пользователя и с его правами. Пока команда идёт, окно 1С не отвечает; ошибка платформы в такой команде может уронить сеанс пользователя. Поэтому долгую операцию (обмен, массовую обработку) агенту подсказано запускать не одним execute, а фоновым заданием через экспортный метод общего модуля конфигурации и опрашивать его состояние короткими командами. Фоновое задание идёт в своём сеансе, вне транзакции моста: его запись не откатывается и разрешением «Запись в базу» не ограничена, поэтому агенту велено запускать его только с allow_write=true и с вашего согласия.

• Серверный код eval и execute по умолчанию выполняется в транзакции, которая после выполнения откатывается: изменения в базе не сохраняются. Откат не отменяет внешних эффектов - файлов, HTTP-запросов, почты, запуска фоновых заданий, записей журнала регистрации. Сохранить изменения можно только с allow_write=true и при включённом на форме разрешении «Запись в базу». Пока оно выключено (так при открытии формы), запрос записи тоже выполняется с откатом, а в ответе агенту приходит предупреждение.

• Запись тоже идёт в транзакции: изменения фиксируются, только если код отработал без ошибок, а при ошибке откатываются целиком - так же, как в проверочном прогоне с откатом. Если код оставил незавершённую свою транзакцию или перехватил ошибку записи внутри неё, запись не фиксируется. transaction=false выполняет запись без транзакции моста: что код успел записать до ошибки, остаётся. Это нужно долгим операциям - транзакция держит блокировки всё время выполнения - и коду, который сам управляет транзакциями или ждёт фоновые задания.

• Код на клиенте (side=client) выполняется в модуле формы обработки, без транзакции, и только при разрешении «Код на клиенте». Разрешения и режим выдачи после такого кода восстанавливаются: сам себе код их не включит. В толстом клиенте обычного приложения такой код может читать и писать базу напрямую, и «Запись в базу» его не ограничивает.

• Каталог обмена лежит в профиле пользователя Windows (%TEMP%). Команду в него может положить любой процесс под этой учётной записью - тот же уровень доверия, что и у самого сеанса 1С. Свой каталог выбирайте с такими же правами: в общую папку команду сможет положить любой, у кого есть запись туда, и она выполнится в вашем сеансе.

• Если на экране модальное окно 1С (например, ошибка компиляции вызванного модуля), обработка не выполняет команды, пока окно не закроют. sessions показывает такой сеанс как неотвечающий.

• Если MCP-клиент умеет подтверждать вызовы инструментов, не разрешайте execute и eval без вопроса: пусть каждый их вызов подтверждается вручную.

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

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

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

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

Обычная форма ФормаОбычная в выгрузке - двоичный контейнер Form.bin. Её модуль и макет лежат текстом в epf/ordinary-form; после правки контейнер пересобирается командой python3 scripts/pack_ordinary_form.py, а тест проверяет, что Form.bin собран из текущих исходников.

Протокол

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

Разработка

uv run pytest

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

Лицензия

MIT