rules-mcp — правила обмена 1С в чате

MCP-сервер, который разбирает боевые правила обмена 1С (Конвертация данных 2.0) и отвечает на вопросы о них прямо в чате Open WebUI: как работает конкретный обмен, что создаётся у приёмника, где расхождение с конфигурацией.

Правила обмена — это XML на десятки мегабайт со встроенным кодом обработчиков. Прочитать их целиком нельзя, искать по ним вслепую — терять каскады и протекающие ветки. Сервер разбирает их один раз в индекс и отвечает точечно.

Разбор — обычная программа, языковая модель в нём не участвует и токены на него не тратятся. Токены уходят только на то, что инструмент вернул в чат.

• Поддерживается КД 2.0 (ExchangeRules.xml + RegistrationRules.xml). Конвертация данных 3 (EnterpriseData) — другой формат, здесь не поддерживается.

• Только стандартная библиотека Python для разбора, одна зависимость для MCP.

• Индекс живёт в памяти, базы данных нет. 36 МБ правил разбираются за секунду.

Что умеет

Инструменты намеренно общие, а не готовые отчёты: пользователь спрашивает как угодно, а ответ складывает модель. Шесть штук — потолок, за которым модели начинают путаться в выборе.

Ради чего всё затевалось

Правила целиком состоят из ссылок на реквизиты и типы двух конфигураций. Проверить их в одиночку нельзя. Но если рядом подключён сервер, читающий конфигурации 1С (например rlm-tools-bsl), появляется проверка, которую иначе делают руками:

1. rules-mcp        → «правила пишут вот в эти реквизиты приёмника, вот их типы»
2. сервер конфигураций → «а вот что реально есть у этого объекта»
3. модель           → сравнивает и показывает расхождения

Реквизита нет, он переименован или сменил тип — обмен на этом не падает, он молча не переносит данные. Это самая дорогая и самая незаметная поломка обмена.

Серверы друг друга не знают и ничего друг о друге не предполагают — разворачиваются и чинятся независимо.

Как должны лежать правила

Папка на направление обмена, внутри выгрузка из Конвертации данных:

<корень или подкаталог репозитория>/
├── УПП_ERP/
│   ├── ExchangeRules.xml              правила выгрузки (ПВД) и конвертации (ПКО)
│   ├── RegistrationRules.xml          правила регистрации (ПРО)
│   └── CorrespondentExchangeRules.xml не читается
├── ERP_УПП/
│   └── …
└── Розница_ERP/
    └── …

Направление определяется по файлу ExchangeRules.xml; папка без него молча пропускается. Имена папок могут быть на кириллице или латиницей — стороны обмена берутся из самих правил, а не из имени папки, поэтому «УПП → ЕРП», «упп erp», «из розницы в ерп» и «УПП_ERP» распознаются одинаково.

Порядок сторон значим: УПП_ERP и ERP_УПП — разные направления с разными правилами, и сервер их не путает.

Установка

Вариант 1. Docker рядом с Open WebUI (рекомендуется)

Добавьте в ваш docker-compose.yml (или возьмите готовый фрагмент из docker-compose.yml):

services:
  rules-mcp:
    build: ./rules-mcp                     # или image: ghcr.io/…, если соберёте свой
    environment:
      GITLAB_REPO: https://gitlab.example.ru/exchange/rules.git
      GITLAB_TOKEN: ${GITLAB_TOKEN}
      GITLAB_BRANCH: main
      RULES_SUBDIR: ""
      REFRESH_INTERVAL: "3600"
      REFRESH_PASSWORD: ${RULES_REFRESH_PASSWORD}
    volumes:
      - rules-clone:/data                  # клон переживает перезапуск контейнера
    restart: unless-stopped
    networks: [ai]

  open-webui:
    # ваш существующий сервис; нужно добавить только это
    environment:
      WEBUI_SECRET_KEY: ${WEBUI_SECRET_KEY}
    networks: [ai]

volumes:
  rules-clone:

networks:
  ai:

git clone https://github.com/kopyshok/rules-mcp.git
cp rules-mcp/.env.example .env      # заполнить токен и пароль
docker compose up -d --build rules-mcp
docker compose logs -f rules-mcp

Секции ports намеренно нет: наружу сервис публиковать не надо, Open WebUI дотянется до него по внутренней сети. Это же снимает вопрос доступа извне.

Вариант 2. Без Docker

git clone https://github.com/kopyshok/rules-mcp.git && cd rules-mcp
python -m venv .venv && . .venv/bin/activate   # Windows: .venv\Scripts\activate
pip install -r requirements.txt

export RULES_DIR=/путь/к/каталогу/с/направлениями
export REFRESH_INTERVAL=0                      # работать с тем, что уже на диске
python server.py

Нужен Python 3.10+ и установленный git, если правила берутся из репозитория.

Настройки

Все настройки — через переменные окружения. Образец: .env.example.

Несмотря на имена, GITLAB_* работают с любым git-сервером — GitHub, Gitea, Bitbucket. Имена оставлены такими, потому что писалось под GitLab.

Подключение к GitLab

1. Токен на чтение

Лучше deploy-токен: он привязан к репозиторию, а не к человеку, и не отвалится, когда сотрудник уйдёт.

Settings → Repository → Deploy tokens → Add token

• Name: rules-mcp

• Expires: можно оставить пустым

• Scopes: только read_repository

GitLab покажет имя пользователя и сам токен один раз. Сервису нужен только токен — имя пользователя он подставляет сам.

Личный токен (Settings → Access Tokens, область read_repository) тоже подойдёт, если deploy-токены запрещены политикой.

2. Адрес репозитория

Только HTTPS. SSH не поддерживается — в контейнере нет ключей и известных хостов, и заводить их ради чтения одного репозитория не стоит.

GITLAB_REPO=https://gitlab.example.ru/exchange/rules.git
GITLAB_TOKEN=glpat-xxxxxxxxxxxxxxxxxxxx

Токен не надо вписывать в адрес — сервис подставит его сам при обращении. Так он не попадает ни в логи, ни в вывод команд.

Если GitLab на нестандартном порту, укажите его в адресе как обычно: https://gitlab.example.ru:8443/exchange/rules.git.

3. Ветка с правилами

GITLAB_BRANCH=main

Указывайте ветку явно. Если оставить пусто, берётся ветка по умолчанию — а она в репозиториях с правилами часто оказывается черновой. Аналитики будут читать не то, что стоит на продуктиве, и не узнают об этом.

Заведите отдельную ветку под боевые правила (prod, production, release) и укажите её. Сервис работает ровно с ней: git fetch и git reset идут по указанной ветке, изменения в других ветках его не трогают.

Ветка видна в ответе каждого инструмента — поле «версия правил»:

ветка prod, коммит d54877b от 08.09.2026

Так человек в чате всегда видит, на какой версии правил построен ответ.

4. Правила лежат не в корне

RULES_SUBDIR=exchange/rules

Клонируется репозиторий целиком, но папки направлений ищутся в этом подкаталоге. Путь указывается от корня репозитория, через /.

5. Проверка

docker compose logs rules-mcp        # клонирование и старт

Если токена не хватает или ветки нет, сервис не падает: он продолжает отвечать на прежнем индексе, а в каждый ответ добавляется поле «внимание» с текстом ошибки. Это видно прямо в чате — молчаливой рассинхронизации не будет.

Подключение к Open WebUI

Родная поддержка MCP появилась в Open WebUI 0.6.31. На версиях старее понадобится обновление либо прослойка mcpo.

Настройки → Админ → Интеграции → Внешние серверы инструментов → Добавить:

Три места, где спотыкаются:

1. Тип должен быть MCP, не OpenAPI. Если вписать MCP-настройки в подключение типа OpenAPI, интерфейс уходит в бесконечную загрузку. Лечится удалением подключения и повторным добавлением.

2. Адрес — имя контейнера, а не localhost. Глобальные подключения выполняются самим Open WebUI, и localhost внутри его контейнера означает его же, а не сервер.

3. Авторизация именно None. Выбранный «Bearer» с пустым ключом шлёт пустой заголовок, и соединение рвётся.

В Open WebUI должен быть задан WEBUI_SECRET_KEY, иначе подключения слетают при каждом пересоздании контейнера.

Чтобы люди не включали инструмент вручную

Глобальный инструмент в чате сам не появляется — каждому пришлось бы включать его в меню интеграций. Вместо этого соберите модель:

Рабочая область → Модели → Создать

• базовая модель — ваша обычная;

• системная подсказка — как читать правила, на что смотреть;

• знания — методичка, карта процессов, если они у вас есть;

• инструменты — rules-mcp и сервер конфигураций, включены принудительно;

• доступ — нужной группе.

Пользователь выбирает модель из списка, и у него уже всё настроено.

Обновление правил

Три пути, все работают вместе:

• Автоматически раз в REFRESH_INTERVAL секунд. Если коммит не сменился, индекс не пересобирается — проверка стоит несколько килобайт трафика.

• Из чата — инструмент refresh_rules с паролем. Нужен, когда только что выложили релиз и ждать час не хочется. Пароль спрашивается у человека, чтобы модель не запускала обновление сама.

• Перезапуском контейнера — индекс собирается заново при старте.

Индекс подменяется целиком и только после того, как новый успешно собран. Пока он строится, сервер продолжает отвечать на старом. Если забрать правила не удалось, старый индекс остаётся в работе.

Если что-то не работает

Посмотреть, что сервер вообще отдаёт:

docker compose exec rules-mcp python -c "
import asyncio
from fastmcp import Client
async def m():
    async with Client('http://127.0.0.1:8000/mcp') as c:
        for t in await c.list_tools(): print(t.name)
        print((await c.call_tool('exchange_overview', {})).data)
asyncio.run(m())"

Как устроено внутри

• rules_index.py — разбор XML и индекс. Только стандартная библиотека. Правила регистрации, ветки выгрузки, правила конвертации со всеми свойствами и табличными частями, каскады в подчинённые правила, функциональные блоки (процессы), которыми разработчики помечают ветки.

• server.py — шесть инструментов, работа с git, фоновое обновление.

Отбор регистрации разворачивается в читаемое дерево условий вместо XML:

(ИЛИ:
  (И:
    ВидОперации = ПокупкаКомиссия
    ВидПоступления = ПоОрдеру
    Контрагент.НеЯвляетсяРезидентом = Истина
  )
  …
)

Ответы по умолчанию сжатые: тексты обработчиков отдаются только по запросу (get_conversion_rule с verbose=true), состав справочников приёмника — отдельным вызовом. Иначе один ответ съедает контекст чата.

Проверка

python test_rules_index.py /путь/к/каталогу/с/направлениями

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

Лицензия

MIT — см. LICENSE.