odata1c-gate

Claude работает с живой базой 1С и не видит персональных данных. odata1c-gate — локальный MCP-шлюз между Claude Code и стандартным OData-интерфейсом 1С:Предприятие 8.3. Модель читает справочники, документы и регистры и может записывать в базу с вашего подтверждения, а ИНН, счета, паспорта, телефоны и, на выбранном уровне, названия организаций и ФИО заменяются токенами до того, как ответ попадёт к модели и к её провайдеру. Реальные значения остаются на вашей машине.

Обезличивать выгрузку заранее неудобно: модели нужны свежие данные и возможность дозапросить их. Инструкция «не показывай ИНН» — не механизм, а провайдер модели в любом случае получает всё, что попало в её контекст. Шлюз делает подмену на границе, до контекста модели.

Один пользователь, одна машина, несколько сессий агентов и несколько баз 1С одновременно. Основной клиент — Claude Code; как работают другие клиенты MCP, сказано в разделе «Ограничения».

English. A local MCP gateway between Claude Code and the standard OData interface of 1C:Enterprise 8.3. The model reads catalogs, documents and registers, and can write to the database after human confirmation, while personal data (tax IDs, bank accounts, passports, phone numbers and, optionally, company and person names) is replaced with deterministic tokens before it reaches the model or its provider. Tokens still work for search, filtering and joins; only the machine owner can reveal a real value, from the terminal. Ships as a Claude Code plugin with ready-made query recipes for typical 1C configurations (Trade, Accounting, Payroll). Docs and messages are in Russian.

Как это выглядит

Вопрос в Claude Code и ответ модели. Данные вымышлены; номера, даты и суммы приходят как есть, название контрагента и его ИНН — токенами:

Вы:      Кто поставщик последнего поступления и какие у него ещё документы за сентябрь?

Claude:  Последнее поступление — № 0000-000412 от 14.09.2026 от [[org:16]]
         (ИНН [[inn:M4T2Q9XZ7K]]). У этого контрагента за сентябрь ещё два документа:
           № 0000-000388 от 03.09.2026    184 500,00 ₽
           № 0000-000401 от 09.09.2026     42 120,00 ₽

Токен работает как значение: на просьбу «покажи все документы [[org:16]] за год» шлюз сам подставит в запрос к 1С реальное название, а ответ снова придёт в токенах. Реальное значение за токеном видите только вы, в своём терминале:

$ odata1c reveal "[[inn:M4T2Q9XZ7K]]"
7701234567

Возможности

🔒 Модель не видит персональные данные

ИНН, КПП, счета, карты, СНИЛС, паспорта, телефоны, почта и адреса физических лиц заменяются токенами вида [[inn:M4T2Q9XZ7K]] до того, как ответ 1С попадёт к модели и к её провайдеру. На рабочей базе токенами приходят и названия организаций с ФИО — в полях и в свободном тексте комментариев. Для типовых УТ, БП и ЗУП ничего настраивать не нужно: при подключении базы шлюз сам определяет по её метаданным, какие поля скрывать.

Как включить. Защита включена сразу; её уровень задаёт роль базы или ключ --gate команды odata1c base add. Что именно скрыто в базе, показывает odata1c policy show <база>. Подробнее — в разделе «Что видит модель, а что нет».

🔎 Защита не мешает работе

Одно значение всегда даёт один и тот же токен. Поэтому модель находит контрагента по токену его ИНН, отбирает его документы, связывает записи из разных справочников и ведёт разговор, так и не узнав реального значения: шлюз подставляет его сам, внутри, перед запросом к 1С. Реальное значение за токеном можете увидеть только вы, в своём терминале.

Как пользоваться. Ничего включать не нужно. Раскрыть токен — odata1c reveal "[[inn:M4T2Q9XZ7K]]".

✍️ Безопасная запись в 1С

Модель может создавать и изменять объекты, проводить и распроводить документы, ставить пометку удаления и записывать независимые регистры сведений. Сама она при этом ничего не пишет: готовит изменение и показывает превью, а в 1С оно уходит только после вашего подтверждения в диалоге Claude Code — реплика «да» в чате подтверждением не считается. Каждую запись можно откатить, а история хранится в журнале.

Как включить. Умолчания задаёт роль базы — таблица ролей. У отдельной базы запись включает или выключает поле write в bases.yaml, а что именно разрешено — раздел permissions той же записи (образец — bases.example.yaml).

🎚️ Свои правила для каждой базы

Рабочая база закрыта полностью и доступна только для чтения, тестовая скрывает реквизиты, база разработки открыта — уровень защиты и права на запись у каждой базы свои. Внутри базы можно скрыть от модели объект целиком, открыть поле, которое не нужно прятать, или закрыть то, что шлюз пропустил. Изменения действуют со следующего запроса, перезапуск не нужен.

Как настроить. Роль задаётся при подключении (--role prod|test|dev, что она означает — таблица ролей). Правила внутри базы — командами odata1c policy hide | open | set (раздел «Командная строка»); они пишут файл policy.yaml (образец — policy.example.yaml).

📋 Готовые ответы на типовые вопросы

Остатки на складе, задолженность покупателей, оборотно-сальдовая ведомость, работающие сотрудники, задолженность по зарплате — на такие вопросы модель отвечает одним вызовом готового рецепта, запрос в котором уже сверен с конфигурацией. Удачный запрос из разговора можно сохранить фразой «сохрани как рецепт» — он станет доступен всем базам той же конфигурации.

Как включить. Укажите конфигурацию при подключении: odata1c base add <база> --recipes ut (или bp, zup). У уже подключённой базы — поле config её записи в bases.yaml. Подробнее — в разделе «Рецепты».

🔌 Подключение базы одной командой

От вас — одна команда в терминале, где вы вводите пароль 1С; всё остальное модель делает сама. Пароль она не видит.

Как начать. Скажите в Claude Code «подключи базу 1С». Что произойдёт дальше и как то же сделать вручную — в разделе «Подключение базы».

🧩 Доработанная конфигурация под защитой

Шлюз знает типовые объекты УТ, БП и ЗУП. Если в вашей конфигурации есть свои справочники, регистры или реквизиты с персональными данными, опишите их — и шлюз будет скрывать их так же, как типовые. Одно описание действует на всех базах, где есть названные объекты.

Как включить. Создайте в каталоге ~/.claude/odata1c/gate/ файл, например my-config.yaml, по образцу common.yaml и назначьте полям классы защиты. Затем выполните odata1c reindex <база>.

version: 1
fields:
  Catalog_МойСправочник.НомерПаспорта: doc   # поле одной сущности
names:
  ФИОКлиента: person                          # поле с таким именем в любой сущности

Кроме того:

• несколько баз в одном разговоре — рабочие, тестовые, разных конфигураций;
• поиск справочника, документа или регистра по примерному названию среди тысяч объектов конфигурации;
• текст из полей 1С модель считает данными, а не командами, — запись всё равно требует вашего подтверждения;
• проверка окружения одной командой odata1c doctor, без вывода паролей;
• чтение из других клиентов MCP (Cursor, VS Code, Claude Desktop), запись в них по умолчанию выключена.

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

Что нужно

• uv — он сам поставит подходящий Python — и Claude Code;
• база 1С:Предприятие 8.3, опубликованная на веб-сервере со стандартным интерфейсом OData (см. ниже);
• отдельный пользователь 1С с правами только на нужные данные — например odata_user.

Подготовка 1С. Стандартный интерфейс OData по умолчанию выключен, и включают его в два шага.

1. Опубликовать интерфейс. При публикации базы на веб-сервере (в конфигураторе: «Администрирование» → «Публикация на веб-сервере») отметьте «Публиковать стандартный интерфейс OData».
2. Включить объекты в его состав. Шлюз видит только объекты, включённые в состав стандартного интерфейса OData. В типовых конфигурациях на БСП для этого есть форма «Настройка стандартного интерфейса OData» в разделе «Администрирование»; в любой конфигурации то же делает метод платформы УстановитьСоставСтандартногоИнтерфейсаOData(). Если состав потом изменится, выполните odata1c reindex <база>.

Проверка: откройте в браузере https://server/base/odata/standard.odata/ под пользователем 1С — должен прийти перечень сущностей.

Установка

Три команды в терминале:

claude plugin marketplace add Romandredan/odata1c-gate
claude plugin install odata1c@odata1c-gate
uv tool install odata1c-gate

Первые две ставят плагин Claude Code: MCP-сервер шлюза, четыре навыка, хук подтверждения записи и агента-следователя. Версия пакета закреплена в plugin/.mcp.json, поэтому claude plugin update odata1c обновляет и плагин, и шлюз.

Третья ставит отдельно командную строку — она нужна владельцу базы, а не модели (описать базу, собрать индекс, раскрыть токен, править политику гейта). После неё команда odata1c доступна в терминале; без установки то же самое запускается как uvx --from odata1c-gate odata1c <команда>.

Подробности, Linux, обновление и разбор типовых сбоев — docs/install.md.

Подключение базы

Откройте Claude Code и скажите: «подключи базу 1С». Навык odata1c-setup спросит, как назвать базу и какая у неё роль, и даст одну команду для вашего терминала. Команда запросит адрес публикации, пользователя 1С и пароль. Пароль вводится только там, модель его не видит. После этого Claude сам построит индекс метаданных, проверит, что база отвечает, и расскажет, что в ней защищено.

То же самое можно сделать вручную:

odata1c base add ut_test --role test --recipes ut   # спросит адрес, подпись, пользователя, пароль
odata1c reindex ut_test                             # построить индекс метаданных

Первая команда сама создаёт домашний каталог шлюза, отдельный odata1c init не нужен. Если что-то не работает, odata1c doctor покажет, где именно: uv, настройки, базы, шлюз, Claude Code.

Адрес базы — это адрес публикации 1С, тот же, по которому открывается веб-клиент (например https://server/base); окончание /odata/standard.odata/ шлюз допишет сам. Пароль вводится в терминале и на экране не отображается; он ложится в bases.yaml домашнего каталога открытым текстом под правами владельца — сознательное решение: файл не покидает диск владельца, это не сетевой секрет.

Первый реиндекс долгий: у типовой УТ $metadata — это около 17 МБ описания и больше семи тысяч сущностей. Дальше индекс пересобирается, только если у публикации изменилась контрольная сумма $metadata.

Первые вопросы

• «какие базы 1С мне доступны?» — модель вызовет odata1c_bases;
• «найди справочник контрагентов и покажи состав его полей» — odata1c_find_entity, затем odata1c_describe_entity с классами гейта у каждого поля;
• «возьми любого контрагента и покажи его пять последних заказов клиента» — odata1c_query; название контрагента придёт токеном, номера и суммы документов — как есть.

Что модель видит и в каком порядке ходит — навык odata1c из плагина; справочные темы об устройстве OData 1С, токенах, политике и протоколе записи — тул odata1c_info.

Настройка

Роли баз

Роль базы задаёт умолчания записи и гейта:

Роль — только набор умолчаний: любое поле записи базы его перекрывает (например, role: prod + write: true — боевая база с разрешённой записью). Флаги записи из последних четырёх столбцов действуют, только когда запись включена (write: true) — у базы без записи они значения не имеют. Все эти поля, включая уровень гейта, задаются для каждой базы отдельно: у боевой и тестовой базы уровни могут быть разными. Уровень при подключении задаёт ключ odata1c base add --gate, а действующие роль и уровень каждой базы показывает odata1c base list.

Готовая запись базы выглядит так (адрес, пользователь и пароль — плейсхолдеры):

bases:
  ut_test:
    label: УТ 11, тестовая
    url: https://server/base
    user: odata_user
    password: qwerty123
    role: test
    config: ut

Файлы настроек

Все настройки шлюза хранятся в домашнем каталоге ~/.claude/odata1c/. Создавать эти файлы вручную не нужно: каждый появляется при выполнении соответствующей команды и уже содержит закомментированный образец всех допустимых полей с пояснениями. Те же образцы лежат в репозитории, в каталоге src/odata1c/templates/, и по ним удобно заранее посмотреть, что и как настраивается.

Чаще всего правится bases.yaml. В записи базы меняют подпись (label), по которой модель выбирает базу, роль (role), разрешение записи (write), уровень защиты (gate.mode), состав разрешённых операций (permissions) и конфигурацию 1С (config), от которой зависит библиотека рецептов. Изменения в bases.yaml и policy.yaml действуют со следующего запроса модели, перезапуск шлюза не требуется. Политику защиты надёжнее менять не в редакторе, а командами odata1c policy: они проверяют имена сущностей и полей по метаданным базы.

Остальное содержимое домашнего каталога служебное, и править его не следует. Это policy.auto.yaml (разметка защищаемых полей, которую шлюз строит сам по метаданным базы), launcher.key, файлы *.sqlite (индекс метаданных, словарь токенов, журнал записей) и каталог logs/.

Файлы правит владелец, не модель. Модель их штатно не читает и не правит — хук плагина PreToolUse перехватывает такие обращения к домашнему каталогу шлюза и требует решения человека. Это дополнительная защита, а не единственная: реальные значения и пароль 1С не выходят через MCP ни при каком обращении. Подробнее — docs/install.md.

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

Что видит модель, а что нет

Что уходит модели. Структура базы (сущности, поля, ключи, навигация) и данные, прошедшие гейт. Номера и даты документов, суммы, количества, коды, GUID, значения перечислений не защищаются ни на одном уровне — без них работа с базой теряет смысл. Названия организаций и ФИО (классы org и person) и защищаемые реквизиты — ИНН, КПП, ОГРН, счета, БИК, карты, СНИЛС, регистрационные номера в СФР, документы, телефоны, почта, даты рождения, адреса — приходят токенами [[type:tail]] по правилам политики базы. Уровень задаётся на базу: off — гейт выключен, identifiers — реквизиты, identifiers+names — реквизиты плюс названия и ФИО.

Что не уходит никогда. Реальные значения защищаемых классов не выходят через MCP ни в одном ответе: ни в данных, ни в текстах ошибок 1С, ни в превью записи, ни в журнале, ни в odata1c_raw_get, ни в вопросах подтверждения. Это инвариант, а не тест: последний проход по готовому ответу делает страж утечек — он ищет в сериализованном ответе известные словарю значения и заменяет их токенами, если что-то прошло мимо гейта. Учётные данные 1С модель не получает: пароль не покидает домашнего каталога вовсе, имя пользователя 1С не попадает ни в один ответ, а адрес публикации базы не возвращает ни один тул. О самой базе модель узнаёт ровно то, что перечисляет odata1c_bases: имя, подпись, роль, уровень гейта, разрешена ли запись, состояние индекса (собран ли, когда, сколько сущностей) и конфигурацию 1С, к которой база отнесена. Единственное исключение по адресу — текст сетевого сбоя, в который его может вписать HTTP-клиент. Раскрыть токен может только владелец машины, командой odata1c reveal в своём терминале.

Архитектура

Два процесса из одного пакета: демон (odata1c daemon) — единственный на машину, в нём работают все компоненты из таблицы ниже; лаунчер (odata1c mcp) — тонкий stdio-процесс на сессию, который поднимает демон при необходимости и проксирует ему вызовы. Собственной логики у лаунчера нет.

Гейт стоит в демоне между тулами и клиентом 1С: всё, что левее пунктирной границы, видит только токены, реальные значения живут правее неё и в словаре. Настройки и учётные данные лежат в домашнем каталоге шлюза; их правит владелец из своего терминала, а модель к этим файлам не допускается.

Базы SQLite работают в режиме WAL: несколько сессий читают и пишут одновременно.

Тулы чтения

Тулы записи

Пишущие тулы ничего не пишут сами: каждый готовит операцию, показывает превью в токенах и возвращает pending_id. В 1С пишет только odata1c_commit — и только после подтверждения человека механизмом клиента: в Claude Code это диалог разрешения, у клиентов с elicitation — вопрос шлюза. Любую выполненную запись можно откатить тулом odata1c_undo.

Командная строка

Команды odata1c — для владельца машины, не для модели. Общий ключ --home <путь> (или переменная окружения ODATA1C_HOME) у любой команды меняет домашний каталог шлюза.

Базы

Политика гейта

Рецепты

Служебные

Рецепты

Рецепт — это заранее составленный и проверенный запрос к базе, которому дано имя и у которого объявлены параметры. Остатки товаров на складе, задолженность покупателей, выручка за период: всё это типовые вопросы, и ответ на каждый из них в 1С требует знать, в каком регистре лежат данные, как называется его виртуальная таблица и какие у неё поля. Рецепт хранит это знание в готовом виде.

Без рецептов модель каждый раз заново исследует структуру базы и собирает запрос с нуля. Это занимает несколько обращений к 1С и не защищает от ошибки в имени регистра или поля. С рецептом тот же вопрос решается одним вызовом, и каждый раз одинаково, потому что запрос уже сверен с метаданными конфигурации.

От пользователя рецепты ничего не требуют. Достаточно спросить обычными словами, например «покажи остатки по основному складу на сегодня». Модель запрашивает у шлюза перечень рецептов базы, выбирает подходящий и выполняет его со своими параметрами, в этом примере с датой и складом. Для этого служит один инструмент, odata1c_recipe: вызов без имени возвращает перечень с описаниями и параметрами, вызов с именем выполняет рецепт.

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

1. Рецепты базы лежат в файле bases/<база>/recipes.yaml и действуют только для неё. Здесь уместны запросы, которые учитывают доработки конкретной базы.
2. Библиотека конфигурации лежит в каталоге ~/.claude/odata1c/recipes/<конфигурация>/, по одному файлу на рецепт, и общая для всех баз этой конфигурации. К какой конфигурации относится база, определяет поле config в её настройках: ut, bp, zup или собственное обозначение.
3. Стартовый набор из поставки — для «Управления торговлей», «Бухгалтерии предприятия» и «Зарплаты и управления персоналом». Его видит любая база, у которой задана конфигурация (config); ключ --recipes команды odata1c base add задаёт её и заодно копирует набор в файл рецептов базы.

Библиотека пополняется в ходе обычной работы. Когда запрос, найденный в разговоре, дал нужный результат и пригодится снова, достаточно попросить модель сохранить его как рецепт. Навык плагина odata1c-recipe заменит конкретные значения параметрами и запишет файл в библиотеку конфигурации. Команда odata1c recipe check <конфигурация> сверяет рецепты библиотеки с метаданными базы, а odata1c recipe list <база> показывает все рецепты базы с указанием источника каждого.

Рецепт записывается обычным файлом YAML. В нём есть описание, сущность 1С, параметры и сам запрос. Данных базы в нём нет: ни значений, ни токенов.

title: Остатки по складу
description: Количество в наличии на указанный момент.
entity: AccumulationRegister_ТоварыНаСкладах_Balance
params:
  period: { type: datetime, required: true, description: момент остатков }
  warehouse: { type: guid, required: false, description: Ref_Key склада }
virtual:
  Period: "{period}"
  Condition:
    - Склад_Key eq {warehouse}
select: [Номенклатура_Key, ВНаличииBalance]
filter: ВНаличииBalance gt 0
top: 200

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

Ограничения

• Физического удаления объектов нет. «Удаление» для объектов и подчинённых регистров — только пометка удаления (DeletionMark = true). Из тулов записи физически удаляет только odata1c_delete_record, и только записи независимых регистров сведений.
• Через odata1c_update нельзя вписать открытым текстом телефон, почту, адрес или дату рождения — только токеном или при создании объекта (odata1c_create): иначе ответ «изменений нет» позволял бы подбирать чужие данные перебором значений.
• Сокращённое название в свободном тексте проходит открытым. Словарь знает полные написания названия; если в комментарии документа человек написал узнаваемое сокращение, которого нет в справочнике, гейт его не заменит. Ловить «ядро» названия отвергнуто: ядра — обычные слова, их замена портила бы данные ложными срабатываниями.
• Одиночное название или имя в свободном тексте без кавычек проходит открытым. Короткое название организации или имя человека, встретившееся в тексте одним словом без кавычек и без организационно-правовой формы (Мост вместо ООО «Мост», Мария вместо полного ФИО), гейт не отличает от обычного слова того же написания и не заменяет: иначе обычные слова в комментариях и именах объектов базы заменялись бы токенами по ошибке. Название с формой собственности (в том числе вплотную через точку или дефис, латиницей и полной записью: «ООО-Мост», «OOO Мост», «Общество с ограниченной ответственностью Мост»), в кавычках или апострофах, из нескольких слов, как и полное ФИО, закрывается как прежде. Открытыми остаются и редкие написания: угловые кавычки (‹Мост›, <<Мост>>) и чужая форма собственности (АО Мост при ООО «Мост»).
• Аутентификации у демона нет. Он слушает только 127.0.0.1; модель угроз — диск и машина владельца. Публикации по сети с аутентификацией и TLS пока нет.
• Записи в регистры, подчинённые регистратору, нет ни при каком разрешении: их пишет проведение документа, а не прямая запись.
• Шаблоны рецептов — только для типовых УТ, БП и ЗУП. Имена в них сверены с реальными базами этих конфигураций; у доработанной конфигурации рецепт, чьей сущности в базе нет, помечается неприменимым, и его правят в собственном файле рецептов базы.
• Проверен шлюз только с Claude Code. Другие клиенты MCP по stdio (Cursor, VS Code, Claude Desktop) подключаются и читают; там, где нет диалога разрешения Claude Code или elicitation, запись по умолчанию выключена (write_confirm_fallback: deny). Навыки, хук и агент — часть плагина Claude Code, в других клиентах их нет. Cowork запускает MCP-серверы в изолированной среде без доступа к демону на 127.0.0.1 — с ним шлюз не работает.

Документы

Лицензия

MIT.