tiny1C MCP server

tiny1C

Правила разработки на 1С:Предприятии для ИИ-агентов и людей, с MCP-сервером.

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

Направления

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

Направление	Что покрывает	Правил	Терминов
core	язык, формы, метаданные, макеты, процесс — не зависит от конфигурации	133	12
greenfield	конфигурация с нуля: именование, языки, стиль, контур проверок, версии	5	—
unf	1С:УНФ — правила, термины, карта объектов	2	10
bp	1С:Бухгалтерия предприятия	открыто	—
zup	1С:Зарплата и управление персоналом	открыто	—
erp	1С:ERP Управление предприятием (типовая конфигурация «1С»)	открыто	—
maerp	maERP — собственная конфигурация на платформе 1С	открыто	—

Направление erp — это типовая конфигурация фирмы «1С». Проект maERP, на который ссылаются источники правил, — собственная конфигурация на платформе 1С и к 1С:ERP отношения не имеет.

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

Как подключить к агенту

Сервер работает по stdio: агент запускает его как обычный процесс у себя на машине. Хостинг, порты и сеть не нужны — нужен только Python 3.8+, никаких зависимостей.

Плагином Claude Code

claude plugin marketplace add bigsofter/tiny1C
claude plugin install 1c@tinycio

Клонировать вручную не нужно: набор приезжает вместе с плагином. Версии у плагина нет, поэтому версией служит коммит main: каждое слияние правил в main для Claude Code - новая версия. Обновляется набор так:

• один раз включить автообновление маркетплейса: /plugin - Marketplaces - tinycio - Enable auto-update (по умолчанию оно выключено у любого стороннего маркетплейса); новая версия подтянется в течение ~10 минут после начала сессии и применится в следующей сессии или после /reload-plugins;
• либо вручную: claude plugin update 1c@tinycio;
• администратору - в managed settings: extraKnownMarketplaces.tinycio.autoUpdate: true.

Какая версия набора запущена, видно в ответе сервера на initialize (serverInfo.version - короткий хеш manifest.json).

Плагин приносит MCP-сервер (включая where_is), скиллы /1c:1c (когда и как звать инструменты) и /1c:propose-rule (предложить новое правило или рецепт), а также мягкий хук-напоминание. Подробности и Windows - в INSTALL.md.

Клоном и путём в конфигурации

git clone https://github.com/bigsofter/tiny1C

{
  "mcpServers": {
    "tiny1c": {
      "command": "python3",
      "args": ["${TINY1C_HOME:-../tiny1C}/mcp/server.py"]
    }
  }
}

Для Claude Code это .mcp.json в корне проекта, для остальных агентов — их собственный файл конфигурации MCP. Переменная TINY1C_HOME позволяет не писать в общий репозиторий путь конкретной машины. Обновление — git pull.

Другие системы

Codex CLI, DeepSeek Harness, Cursor, VS Code и прочие MCP-клиенты — готовые куски конфигурации в INSTALL.md. Там же способ для систем без MCP: выгрузка правил одним файлом в системную подсказку или в проектные инструкции.

scripts/export.py --направление core,greenfield --выход dist/rules.md

Инструменты сервера

Инструмент	Зачем
list_tracks	какие направления есть и что в них лежит
lookup_rule	поиск по симптому: тексту ошибки (дословно), ключевому слову, id; учитывает словоформы и е/ё, ищет по заголовкам, ключам, разделу «Симптом» и по тексту правил
get_rule	полный текст правила
lookup_guide	поиск рецептов «как сделать»: по задаче, ключевому слову, id (how-001); для вопросов «как собрать/загрузить/проверить X», не для текста ошибки
get_guide	полный текст рецепта: задача, шаги, проверка результата, где ломается, ссылки на правила
rules_by_category	все правила категории (запросы, формы-xml, метаданные, расширения…)
rules_for_object	что известно про объект метаданных: правила и термины
checklist	что проверить перед правкой файла .bsl, .form, .mdo, .mxlx, .epf, .erf, .cfe; compact=true - только id, заголовок, серьёзность
glossary_lookup	термин предметной области → определение и объекты

Плюс ресурс tiny1c://manifest — сокращённый индекс набора (без глоссариев, симптомов и текстов правил; для отладки). Сервер отдаёт instructions («когда что звать») в ответе initialize; клиенты, которые их поддерживают, передают их модели.

Исполняемые инструменты

Кроме правил, сервер умеет разбирать XML-выгрузку конфигурации — локально, без базы и без платформы. Эти инструменты включаются явно: флагом --tools offline или переменной окружения TINY1C_TOOLS=offline (удобно, когда аргументы запуска задаёт плагин). Без них сервер отдаёт прежние девять.

Инструмент	Зачем
where_is	где объект в интерфейсе: раздел → подсистема → команда (в том числе собственная), группа панели, кому скрыт, функциональные опции, права, ссылка e1cib/…; по названию раздела — его состав

{"mcpServers": {"tiny1c": {"command": "python3",
  "args": ["${TINY1C_HOME:-../tiny1C}/mcp/server.py", "--tools", "offline"]}}}

Аргумент dump — каталог выгрузки конфигуратора «Выгрузить конфигурацию в файлы», формат «Иерархический» (в нём лежит Configuration.xml); за его пределы инструмент не читает, подменённый XML (DTD, сущности) отвергает. Каждый инструмент описан карточкой в tools/<группа>/<имя>.md: откуда идея, где исполняется, чем опасен, чем проверен и что пока не умеет. Инструмент без проверки на фикстуре в сервер не попадает.

Инструменты для помощника в базе 1С

Группа instructions — для ИИ-помощника, который работает не с кодом, а внутри базы 1С рядом с бухгалтером (в портале TinyCIO это «Татьяна»). Ему нужно одним вызовом получить всё, что набор знает про конфигурацию базы, и положить это в системный промпт. Включается так же, как offline: --tools instructions (можно вместе: --tools offline,instructions); сетевой режим включает её сам.

Инструмент	Зачем
match_config	по фактам базы (Метаданные.Имя, версия, поставщик, синоним) — направление набора по паспортам profile.json; отдельно говорит, совпал ли поставщик и не ниже ли версия минимальной
get_instructions	пакет направления для системного промпта: профиль, «где это в 1С» и особенности в сжатом виде, чипы (общие из core и свои); если направление расширяет другое (ka/erp поверх ut) — сначала общее, потом добавки; include_core=true добавляет шпаргалки. Поле текст — готовый markdown; потолок 24 КБ проверяет манифест
get_instructions_file	один файл пакета целиком, как справочник: objects.md (карта объектов), faq.md (типовые вопросы), where_is.md, notes.md без сжатия — по запросу, когда сжатого пакета мало; строки [проверить] в нём есть, с оговоркой
get_cheats	шпаргалки платформы из tracks/core/cheats/*.md (язык запросов, регистры)

Что лежит в пакете и как его завести — «Пакет инструкций по конфигурации».

Сетевой режим: сервис для портала

Кроме stdio у сервера есть режим streamable HTTP (mcp/httpd.py) — для сервисов, которые живут в одной внутренней сети с ним и не могут запускать локальный процесс. Тот же набор инструментов и тот же код обработки, плюс:

• один эндпоинт POST /mcp по спецификации MCP (ревизии 2024-11-05…2025-11-25): JSON-RPC запрос или батч, ответ одним JSON (SSE — только если клиент принимает лишь text/event-stream), уведомления — 202, сессий нет, GET/DELETE — 405;
• доступ только по сервис-токену: заголовок X-Service-Token должен совпасть с переменной TINY1C_SERVICE_TOKEN; без неё сервис не стартует. Наружу его не публикуют: это служба внутренней сети, не веб-API;
• GET /healthz без токена: ревизия знаний, время и итог последней синхронизации;
• знания подтягиваются из git сами: раз в TINY1C_SYNC_INTERVAL секунд (300) сервис смотрит ветку main репозитория, новую ревизию забирает в каталог данных TINY1C_DATA, проверяет своим scripts/manifest.py и подменяет снимок целиком; ревизию с ошибками не подключает и остаётся на прошлой (ошибка видна в /healthz). Код из git не исполняется никогда — он меняется только новым образом с закреплённой ревизией.

TINY1C_SERVICE_TOKEN=... python3 mcp/httpd.py --addr localhost:8111 --data /tmp/tiny1c-data
curl -s http://localhost:8111/healthz
curl -s http://localhost:8111/mcp -H 'X-Service-Token: ...' -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' -H 'MCP-Protocol-Version: 2025-11-25' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"match_config","arguments":{"name":"БухгалтерияПредприятия"}}}'

Контейнер — Dockerfile в корне: образ несёт код и встроенную копию набора на момент сборки, знания — в томе /data, порт 8111, пользователь nobody. Без --data сервис работает только на встроенной копии (режим для проверок).

Пакет инструкций по конфигурации

Направление может нести, помимо правил для программиста, пакет инструкций для помощника в базе: что знает набор про саму конфигурацию. Файлы лежат в tracks/<направление>/, заготовка — tracks/_PACK_TEMPLATE/:

файл	что внутри
profile.json	паспорт: как узнать конфигурацию и что в ней есть (ниже)
where_is.md	«что → раздел → путь → как открыть»: журналы, документы, отчёты, настройки
objects.md	карта объектов: документ → роль → чем закрывается; справочники; регистры (она же карта для программиста)
notes.md	особенности: чего в конфигурации нет, что считается иначе, что умеет только форма
faq.md	типовые вопросы пользователя и короткие ответы-маршруты
chips.json	подсказки-чипы: список записей id, заголовок, текст; необязательные тема, подсказка (что ввести), параметры (объект, как есть передаётся серверу), проверить: true (чип не отдаётся, пока не проверен). tracks/core/chips.json — общие чипы для всех конфигураций
cheats/*.md	шпаргалки платформы — только у core; первая строка # Заголовок; README.md в каталоге — происхождение, в набор не входит
sources.md	источники фактов (номера S-n, URL, даты) — для ревью; в пакет не входит и в промпт не попадает

Что уходит в промпт, а что нет. Файлы пакета пишутся как справочник, а помощнику уходит сжатая выжимка: get_instructions кладёт в текст профиль, where_is.md и notes.md, пропуская строки с пометкой [проверить] (неподтверждённый факт помощнику не даётся вовсе), разделы с заголовком … (подробно), колонки таблиц «статус» и «источник» и ссылки на источники в скобках — (S-5), (опыт), (из промпта); заголовок файла убирается, остальные опускаются на уровень. objects.md и faq.md в промпт не идут — их целиком отдаёт get_instructions_file. Правила сжатия — mcp/packtext.py, потолок сжатого текста на направление — 24 КБ, его считает scripts/manifest.py (ключ размер_промпта); сырые файлы — до 96 КБ, шпаргалки — 24 КБ. В notes.md удобно держать раздел «Коротко» (тезисы в промпт) и разделы «… (подробно)».

profile.json — объект с закрытым набором ключей (неизвестный ключ — ошибка манифеста):

ключ	обязателен	что
семейство	да	код семейства латиницей: bp, unf, ut…
имена	да	Метаданные.Имя конфигураций, без пробелов: ["БухгалтерияПредприятия", "БухгалтерияПредприятияКОРП"]
тема	да	о чём конфигурация: «учёт и налоги», «торговля и склад»
синоним_re	нет	регулярное выражение по синониму, если имя неизвестно
мин_версия	нет	минимальная версия вида 3.0.150
поставщики	нет	список поставщиков, с которыми пакет совпадает: ["Фирма \"1С\""]
признаки	нет	{"бухгалтерия": true, "накопление": true, "расчёт": false} — какие регистры есть
план_счетов, виды_субконто	нет	имена для подстановки в шпаргалки
без_кода	нет	объекты «настройка без программирования»
расширяет	нет	код направления, чей пакет берётся за основу (ka → ut): его части идут первыми, свои — добавками

Правила: пакет без profile.json — ошибка (конфигурацию не определить; objects.md и chips.json без профиля допускаются — карта для программиста и общие чипы core); расширяет — только на направление с пакетом, без циклов, не длиннее трёх. Чистая комната та же, что у правил: без имён клиентов, людей, баз и путей; факты из открытых источников — своими словами, URL только в sources.md. В manifest.json пакет виден ключом инструкции направления (профиль, файлы с sha и размером, размер_промпта, шпаргалки). Первый пакет — tracks/bp (Бухгалтерия предприятия 3.0): часть путей и имён помечена [проверить] и ждёт подтверждения по живой базе или руководству.

Устройство

tracks/<направление>/
  track.md      паспорт: конфигурации, платформы, статус
  rules/*.md    правила, одно правило — один файл
  guides/*.md   рецепты «как сделать»: задача, шаги, проверка результата, ссылки на правила
  glossary.md   термины: термин | синонимы | объекты | пояснение
  objects.md    карта объектов конфигурации (необязательно)
  profile.json, where_is.md, notes.md, faq.md, chips.json   пакет инструкций (необязательно); sources.md - его источники
  cheats/*.md   шпаргалки платформы (только core)
tracks/_PACK_TEMPLATE/    заготовка пакета инструкций (направлением не считается)
tools/<группа>/<имя>.md   карточки исполняемых инструментов
manifest.json   машинный индекс, собирается из всего перечисленного
mcp/server.py   MCP-сервер (stdio, без зависимостей); mcp/search.py - поиск правил
mcp/httpd.py    сетевой режим (streamable HTTP, токен, /healthz); mcp/knowledge.py - знания из git
mcp/instructions.py   группа instructions (match_config, get_instructions, get_instructions_file, get_cheats)
mcp/packtext.py       сжатие файлов пакета для промпта ([проверить], «(подробно)», колонки статуса)
mcp/snapshot.py       снимок набора: манифест + корень дерева
skills/         скиллы плагина Claude Code (1c, 1c-propose)
hooks/          мягкий хук плагина (напоминание, ничего не блокирует)
mcp/tools/      реализации инструментов (только stdlib)
fixtures/       синтетические выгрузки для проверки инструментов
tests/          проверки инструментов: golden-ответы на фикстурах; tests/fixtures/knowledge - набор для сетевого режима
scripts/        сборка манифеста, проверка гигиены, прогон инструментов
Dockerfile      образ сетевого режима

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

scripts/manifest.py              # пересобрать manifest.json
scripts/manifest.py --проверить  # проверить формат и актуальность (для CI)
scripts/manifest.py --корень ДИР # то же для другого дерева набора (так сервис проверяет свежую ревизию)
scripts/hygiene.py               # что не должно уехать в публичный репозиторий
scripts/hygiene.py --файл x.md   # проверить одно правило или рецепт вне дерева (черновик, конверт)
scripts/tools-check.py           # инструменты на фикстурах (golden-ответы), сетевой режим, подгрузка знаний

Формат правила

---
id: bsl-006
направление: core
категория: модули
серьёзность: критично
платформы: [8.3, 8.5]
заголовок: "ЕстьNULL — функция языка запросов, во встроенном языке её нет"
ключи: [ЕстьNULL, NULL, компиляция]
источник: "ошибка:maERP 2026-09-02, панель сведений в 19 формах списков"
check: ["checkconfig-ext:разбор модулей форм", "smoke-forms:форма не открывается"]
---

check пишется как «вид:описание». Виды: lint, checkconfig, checkconfig-ext, smoke-forms, smoke-samples, smoke-print, fixtures, refcheck, xml-audit, manual. Вид manual — честное признание, что правило ловится только человеком; таких сейчас 39 из 140, и это видно в манифесте.

Формат рецепта

Рецепт — файл tracks/<направление>/guides/how-NNN.md (шаблон — tracks/_GUIDE_TEMPLATE.md). Правило отвечает на «что нельзя и почему», рецепт — на «как сделать, по порядку».

---
id: how-001
направление: core
категория: расширения
платформы: [8.3, 8.5]
заголовок: "Собрать расширение из исходников и применить его в копии базы"
источник: "практика:проект 2026-10-12, цикл загрузки расширения в копию"
задача: "В файловой копии базы: расширение из каталога исходников загружено, применено и активно"
ключи: ["LoadConfigFromFiles", "-Extension", "UpdateDBCfg"]
check: ["manual:расширение в списке расширений копии активно"]
правила: [ext-002, ext-004]
---

Тело — три раздела: ## Шаги, ## Проверка результата, ## Где ломается (последний может быть пустым). Серьёзности у рецепта нет. Рецепт — порядок шагов; факты и запреты живут в правилах, на которые он ссылается полем правила, и при расхождении главнее правило. Вид источника практика — порядок, проверенный в деле.

Как добавить правило

scripts/new-rule.py core forms-011 "Короткий заголовок"   # заготовка из шаблона
# заполнить: категория, источник, check, текст
scripts/manifest.py && scripts/hygiene.py                 # пересобрать и проверить

Рецепт заводится так же: scripts/new-guide.py core how-007 "Короткий заголовок".

Подробнее — в CONTRIBUTING.md. Откуда что взялось и что сознательно не заимствовано — в PROVENANCE.md.

Лицензии

Тексты правил, глоссарии и карты объектов — CC BY 4.0. Код (сервер, скрипты) — MIT. Берите с указанием авторства.