1C MCP Gateway

Read-only интеграция:

1C Agent (.epf) -> Gateway (FastAPI + FastMCP) -> Codex / ChatGPT / MCP client

Архитектура передачи исходников и инструкции по её диагностике сверены с кодом: 2026-09-03. Это не подтверждение обновления всех установленных экземпляров.

Размещение и передача исходников

Клиент 1С с EPF/helper, gateway и Codex/MCP могут работать на трёх разных машинах. Сервер базы 1С также может находиться отдельно. Helper выполняет локальную выгрузку, упаковывает исходники в ZIP и отправляет их частями по HTTP на gateway. Gateway хранит snapshot и обращается к своему приватному rlm-tools-bsl; Codex читает исходники через MCP gateway.

Общая папка между машинами не требуется. Путь Workspace относится к машине helper, а 127.0.0.1 — к машине, где выполняется команда. Live-чтение бизнес-данных идёт отдельно через WebSocket EPF.

Начать с актуальной архитектуры. Если исходники не видны, использовать диагностику snapshot: адрес и tenant/base → выгрузка → upload → публикация → индекс. Пустой legacy manifest и недоступный на машине Codex клиентский диск не устанавливают причину сбоя.

Текущий статус

Проект вышел за пределы первоначального skeleton. В коде уже реализованы:

• рабочая внешняя обработка OneCMcpAgent.epf с WebSocket handshake, heartbeat и маршрутизацией команд;
• gateway с явной read-only policy, ограничениями выборок, аудитом и маскированием чувствительных данных;
• чтение метаданных, модулей, документов, движений, регистров и объектов по ссылке;
• чтение журнала регистрации по периоду и, при необходимости, по конкретному документу;
• подготовка и загрузка source snapshot, а также gateway-wrapper для приватного rlm-tools-bsl;
• маршрутизация по session_id или однозначному infobase_id;
• локальная память успешных безопасных стратегий исследования 1С.

Собранный артефакт находится в build/OneCMcpAgent.epf. После последней сборки исходники и gateway-тесты проходили, но актуальная EPF с фильтром журнала по документу ещё требует ручной проверки в тестовой информационной базе 1С.

Активная схема портов

Рекомендуемый split-port профиль запускает два процесса на машине gateway:

Адрес	Назначение	Доступ
http://127.0.0.1:18081/mcp	MCP и внутренний API gateway	только localhost/private network
ws://<gateway-host>:18080/agent/ws	подключение OneCMcpAgent.epf	локальная или доверенная сеть
http://<gateway-host>:18080/api/source-snapshots/*	загрузка source snapshot	локальная или доверенная сеть

Публичный proxy на 18080 не должен отдавать /mcp. Полная схема и команды проверки описаны в docs/split_ports_gateway_runbook.md.

Быстрый старт

Шаги установки и запуска gateway выполняются на его машине. EPF/helper запускаются на машине клиента 1С, MCP настраивается на машине Codex. Примеры с 127.0.0.1 применимы на самом gateway или при настроенном локальном туннеле; удалённый клиент использует адрес gateway, доступный со своей машины. Подробности — в split-port runbook.

0. Клонировать приватный репозиторий

На новом компьютере сначала авторизуйте GitHub CLI под учётной записью с доступом к репозиторию, затем клонируйте проект:

gh auth login
gh repo clone AleksandrAkhunov/1c-mcp-project-v2.3
cd 1c-mcp-project-v2.3

Локальные gateway/.env, информационные базы, кеши, выгрузки и артефакты анализа намеренно не хранятся в Git. Создайте gateway/.env из подходящего *.example, а при необходимости скопируйте .v8-project.example.json в .v8-project.json и укажите путь к платформе 1С.

1. Установить Python-окружение

Требуется Python 3.11+.

cd gateway
python -m venv .venv
.\.venv\Scripts\Activate.ps1
pip install -e ".[dev]"
cd ..

2. Настроить gateway

Локальные параметры хранятся в gateway/.env. Реальные пароли и токены не должны попадать в Git или документацию.

Для транспорта EPF используются:

ONEC_MCP_AGENT_AUTH_ENABLED=true
ONEC_MCP_AGENT_AUTH_LOGIN=<local-agent-login>
ONEC_MCP_AGENT_AUTH_PASSWORD=<local-agent-password>

Это авторизация канала EPF и загрузки source snapshot. Она не превращает private MCP endpoint в публично защищённый сервис. До появления отдельной MCP/API-аутентификации порт 18081 должен оставаться на localhost или в доверенной приватной сети.

Privacy-профиль по умолчанию одинаков для всех подключённых баз:

ONEC_MCP_PRIVACY_ENABLED=true
ONEC_MCP_PRIVACY_BUSINESS_NAMES_VISIBLE=true

Наименования номенклатуры, складов и остальных бизнес-справочников возвращаются читаемо. Контрагенты, партнёры, клиенты/поставщики, физические лица, сотрудники и пользователи остаются обратимыми alias. ИНН, адреса, контакты, свободный текст и технические ссылки также продолжают маскироваться.

3. Запустить gateway

.\scripts\start_gateway_split_ports.ps1

Проверка:

Invoke-RestMethod http://127.0.0.1:18080/healthz
Invoke-WebRequest -UseBasicParsing http://127.0.0.1:18080/mcp
Invoke-RestMethod http://127.0.0.1:18081/healthz

Ожидается: оба /healthz отвечают успешно, а 18080/mcp возвращает 404.

Остановка:

.\scripts\stop_gateway_split_ports.ps1

4. Подключить Codex/MCP-клиент

Переносимый пример находится в .codex/config.toml.example. Скопируйте его в локальный .codex/config.toml и при необходимости измените адрес gateway:

[mcp_servers.onecGateway]
url = "http://127.0.0.1:18081/mcp"

Подробный порядок работы с инструментами: docs/codex_mcp_runbook.md.

5. Открыть EPF в тестовой 1С

1. Откройте build/OneCMcpAgent.epf в непроизводственной базе.
2. Укажите WebSocket-адрес ws://<gateway-host>:18080/agent/ws, доступный с машины клиента 1С. 127.0.0.1 подходит только если gateway запущен на ней же или есть локальный tunnel.
3. Заполните локальные логин и пароль gateway.
4. Нажмите Подключить.
5. Передавайте MCP-клиенту показанный формой Session ID или Infobase ID.
6. Для анализа исходников запустите команду выгрузки конфигурации в EPF: helper должен завершить экспорт и upload на gateway. Через «Проверить результат» проверьте текущий ответ загрузки, затем через MCP — snapshot нужной базы в tenant загрузки и готовность индекса. Подключение EPF само по себе исходники не загружает.

Не используйте производственные выгрузки или реальные секреты в тестовых сценариях.

Сборка и проверки

Сборка EPF из XML-исходников описана в docs/epf_manual_build_runbook.md.

Проверки gateway выполняются из gateway/:

.\.venv\Scripts\python.exe -m pytest -q
.\.venv\Scripts\python.exe -m compileall src

Границы безопасности

• Нельзя добавлять write-back в бизнес-данные 1С.
• Нельзя добавлять произвольный execute_code, unrestricted SQL или unrestricted query execution.
• Маскирование чувствительных данных должно оставаться включённым в примерах и пилотных потоках.
• Любое чтение должно иметь явный target и ограниченный объём результата.
• MCP 18081 и внутренний rlm-tools-bsl нельзя публиковать напрямую в интернет.

Что проверить вручную дальше

1. Подключение собранной EPF и heartbeat в реальной тестовой базе.
2. read_event_log по короткому периоду без ссылки на документ.
3. read_event_log по тому же периоду с document_ref и правильным document_type.
4. Отсутствие посторонних событий и наличие meta.scope.kind = "document_ref".
5. Поведение privacy masking и структурных ошибок на неверной ссылке/типе.

Runbook проверки журнала: docs/event_log_read_runbook.md.

Документация

• docs/README.md — полный индекс.
• docs/current_status_and_next_steps.md — подробный статус и очередь работ.
• docs/current_architecture_status.md — краткая карта текущей архитектуры.
• docs/source_snapshot_troubleshooting.md — проверка выгрузки, отправки, публикации и индекса без смешения машин и каталогов.
• docs/split_ports_gateway_runbook.md — запуск gateway на 18080/18081.
• docs/chatgpt_onec_gateway_mcp_connection.md — переносимая инструкция подключения MCP.
• mcp_onecGateway_limitations.md — наблюдаемые ограничения и безопасные обходные пути.

Структура репозитория

agent-1c/    XML/BSL-исходники OneCMcpAgent
build/       собранная EPF и временная база сборки
gateway/     FastAPI/FastMCP gateway и тесты
mock-agent/  транспортный mock-agent
scripts/     запуск gateway, mock-agent и workspace helper
schemas/     схемы протокола
docs/        архитектура, runbook и планы