1c-templates-mcp

MCP-сервер с семантическим поиском по шаблонам кода 1С (BSL). 2262+ шаблонов из сообщества, CRUD веб-интерфейс с Monaco Editor, ChromaDB + embeddings для поиска по смыслу.

<!-- screenshot -->

Возможности

• Семантический поиск - гибридный (vector + full-text) поиск шаблонов кода на русском языке
• 6 MCP-инструментов - поиск, просмотр, создание, редактирование, удаление шаблонов
• Веб-интерфейс - полный CRUD с Monaco Editor и подсветкой BSL-синтаксиса
• 2262+ шаблонов - предустановленная база шаблонов кода 1С в seed_templates.jsonl
• Гибкие embeddings - OpenAI-совместимый API или локальная модель SentenceTransformer
• Docker - готовый docker-compose для быстрого запуска

Установка из готового образа (рекомендуется)

Для обычного использования - без клонирования репозитория и без сборки. Готовый образ публикуется на Docker Hub: desko77/1c-templates-mcp.

Скачайте папку deploy/ (три файла: docker-compose.yml, .env.example, README.md) и запустите:

cd deploy
docker compose up -d              # CPU-режим
docker compose --profile gpu up -d  # GPU-режим (NVIDIA)

Подробная инструкция по настройке и обновлению - в deploy/README.md.

Быстрый старт (сборка из исходников)

Подходит для разработки и контрибуций. Собирает образ локально из текущего состояния репозитория.

git clone https://github.com/Desko77/1c-templates-mcp.git
cd 1c-templates-mcp

# CPU (универсально, без требований к GPU)
docker compose --profile cpu up -d

# ИЛИ GPU (NVIDIA, значительно быстрее индексация + поиск)
docker compose --profile gpu up -d

Сервер доступен:

• Веб-интерфейс: http://localhost:8004
• MCP endpoint: http://localhost:8004/mcp (POST, Streamable HTTP)

Разница между профилями:

• cpu — контейнер template_search_mcp, без GPU-проброса. Первая индексация RoSBERTa на CPU ~5-10 мин. Работает везде.
• gpu — контейнер template_search_mcp_gpu, проброс NVIDIA GPU через deploy.resources.reservations.devices. Индексация под минуту. Требует nvidia-container-toolkit (см. ниже).

Требования для GPU-профиля

1. NVIDIA GPU с установленными драйверами (проверка: nvidia-smi на хосте).
2. nvidia-container-toolkit — пакет для проброса GPU в Docker-контейнеры.
   • Установка: https://docs.nvidia.com/datacenter/cloud-native/container-toolkit/install-guide.html
   • На Windows работает через Docker Desktop с WSL2 + установленным nvidia-container-toolkit в WSL2.
   • После установки: docker run --rm --gpus all nvidia/cuda:12.0.0-base-ubuntu22.04 nvidia-smi должно показать вашу GPU.
3. torch с поддержкой CUDA — уже в requirements.txt (torch>=2.8.0 подтягивает CUDA-wheel автоматически).

Если GPU недоступен или nvidia-container-toolkit не установлен — docker compose --profile gpu up упадёт с ошибкой о нехватке nvidia runtime. В этом случае используйте --profile cpu.

Подключение к Claude Code

{
  "mcpServers": {
    "1c-templates-mcp": {
      "type": "url",
      "url": "http://localhost:8004/mcp"
    }
  }
}

MCP-инструменты

Инструмент	Параметры	Описание
templatesearch	query: str	Гибридный семантический + полнотекстовый поиск шаблонов
list_templates	offset?, limit?	Список шаблонов с пагинацией (по умолчанию 50, макс 200). Для поиска используйте templatesearch
get_template	template_id: int	Получить полный шаблон с кодом по ID
add_template	name, description, code, tags?	Добавить новый шаблон
update_template	template_id, name?, description?, code?, tags?	Обновить существующий шаблон
delete_template	template_id: int	Удалить шаблон по ID

Веб-интерфейс

Маршрут	Описание
GET /	Список шаблонов с поиском
GET /new	Форма создания шаблона (Monaco Editor)
GET /{id}	Просмотр шаблона
GET /{id}/edit	Редактирование шаблона
POST /{id}/delete	Удаление шаблона

Конфигурация

Переменная	По умолчанию	Описание
HTTP_PORT	8004	Порт сервера
EMBEDDING_PROVIDER	auto	Провайдер embeddings: auto / local / openai (см. ниже)
EMBEDDING_MODEL	intfloat/multilingual-e5-small	HuggingFace-идентификатор модели для локальных embeddings
OPENAI_API_BASE	http://localhost:1234	URL OpenAI-совместимого API для embeddings
OPENAI_API_KEY	lm-studio	API-ключ
OPENAI_MODEL	-	Имя модели на API-сервере (для LM Studio - внутреннее имя, не HF-id)
RESET_CHROMA	false	Пересоздать ChromaDB-индекс при старте
RESET_CACHE	false	Очистить кеш модели при старте
USESSE	false	Использовать SSE-транспорт вместо Streamable HTTP
DATA_DIR	/app/data	Директория для runtime-данных (SQLite, ChromaDB)

Архитектура

                     MCP Clients (Claude Code, Cursor, ...)
                              |
                         POST /mcp
                              |
                    +---------+---------+
                    |    FastAPI app     |
                    |                   |
                    |  /mcp -> FastMCP  |  6 MCP tools
                    |  /    -> Web UI   |  CRUD + Monaco Editor
                    +----+--------+----+
                         |        |
                    +----+--+  +--+------+
                    | SQLite |  | ChromaDB |
                    | (SoT)  |  | (index)  |
                    +--------+  +----+-----+
                                     |
                              +------+------+
                              | Embeddings  |
                              | OpenAI API  |
                              | or local ST |
                              +-------------+

• seed_templates.jsonl - источник истины для контрибуций (один JSON-объект на строку). При Docker-билде из него генерируется templates.db.
• SQLite (templates.db) - runtime-хранилище шаблонов (в Docker-volume). Производное от JSONL на этапе билда.
• ChromaDB - векторный индекс для семантического поиска, производный от SQLite (перестраивается при первом старте).
• Embeddings - OpenAI-совместимый API (LM Studio, Ollama) или локальный SentenceTransformer.

Embedding-модели

Доступны три режима выбора бэкенда через EMBEDDING_PROVIDER:

Режим auto (по умолчанию)

Сначала пробует OpenAI-совместимый API (LM Studio, Ollama, vLLM). При недоступности автоматически откатывается на локальную SentenceTransformer-модель.

environment:
  - EMBEDDING_PROVIDER=auto
  - OPENAI_API_BASE=http://host.docker.internal:1234
  - OPENAI_MODEL=text-embedding-multilingual-e5-large-instruct
  - EMBEDDING_MODEL=intfloat/multilingual-e5-small   # fallback

Режим local — только локальная SentenceTransformer

API не дергается вообще. Подходит если нет LM Studio / Ollama, или хочется гарантированно детерминированное поведение без зависимостей от внешних сервисов.

environment:
  - EMBEDDING_PROVIDER=local
  - EMBEDDING_MODEL=intfloat/multilingual-e5-small   # или ai-forever/ru-en-RoSBERTa

Режим openai — только API

Падает с ошибкой если API недоступен (без фоллбэка). Подходит для production-деплоев, где API-сервис обязателен.

environment:
  - EMBEDDING_PROVIDER=openai
  - OPENAI_API_BASE=https://api.openai.com
  - OPENAI_API_KEY=sk-...
  - OPENAI_MODEL=text-embedding-3-small

Рекомендации по локальным моделям

Модель	Размер	Dim	Скорость на CPU	Когда брать
intfloat/multilingual-e5-small	118M / ~450 МБ	384	Быстро	Default - работает везде, включая слабое железо
ai-forever/ru-en-RoSBERTa	404M / ~1.6 ГБ	1024	Медленно (5-10 мин на индекс 2262 шаблонов)	Есть GPU или готов ждать - лучшее качество на русском
intfloat/multilingual-e5-large	560M / ~2.2 ГБ	1024	Очень медленно на CPU	Есть GPU - универсальная мультиязычная

Первый запуск с новой моделью качает её с HuggingFace (кешируется в model_cache/). Последующие старты читают из кеша.

Проверка качества embedding-модели

Если подозреваете что API-модель (особенно сторонняя GGUF в LM Studio) возвращает дефектные эмбеддинги, см. ../plans/1c-templates-mcp/test_lmstudio_embeddings.py - скрипт проверяет все доступные в LM Studio модели на коллапс (max cos_sim для несвязанных текстов).

Локальный запуск (без Docker)

pip install -r requirements.txt
python -m app.main

Переменные окружения читаются из .env (см. .env.example). Для GPU - установить torch с CUDA-wheel (pip install torch --index-url https://download.pytorch.org/whl/cu121).

Для подсветки BSL в веб-интерфейсе клонировать bsl_console рядом с проектом:

git clone --depth 1 https://github.com/salexdv/bsl_console.git

Как добавить свой шаблон

Источник правды - seed_templates.jsonl в корне проекта. Каждая строка файла - один шаблон в формате JSON: {"name": "...", "description": "...", "tags": ["..."], "code": "..."}. Поля name, description, code обязательны, tags опционально.

Путь 1: напрямую через JSONL (рекомендуется для PR)

1. Добавить строку с шаблоном в конец seed_templates.jsonl.
2. Проверить валидность: python scripts/build_db_from_jsonl.py --jsonl seed_templates.jsonl --output ./check.db - должно завершиться без ошибок. Удалить check.db.
3. Закоммитить изменение и открыть PR.

Путь 2: локально через Web UI + экспорт

1. Запустить сервер (docker compose up -d), добавить шаблон через Web UI (http://localhost:8004/new). Шаблон попадает в runtime-БД в Docker-volume.
2. Обязательно выгрузить runtime-БД на хост и экспортировать в JSONL:

   docker cp template_search_mcp:/app/data/templates.db ./runtime_dump.db
   python scripts/export_to_jsonl.py --db ./runtime_dump.db --output seed_templates.jsonl
   rm ./runtime_dump.db
   

3. git add seed_templates.jsonl, коммит, PR.

ВАЖНО: если выполнить docker compose up -d --build или docker volume rm до шага 2 - добавленный через Web UI шаблон будет потерян (runtime-БД пересоздается из seed_templates.jsonl).

Пересборка образа после изменений JSONL

docker compose build --no-cache
docker volume rm 1c-templates-mcp_app_data  # удалит прежнюю runtime-БД
docker compose up -d

Companion-правила для AI-агентов

В docs/rules/ лежат справочники по доменам, из которых дистиллированы тематические шаблоны базы. Это не замена самим шаблонам, а companion-знания для глубокого контекста: шаблоны показывают как делать конкретные операции, справочник даёт полную картину API домена. Агент с подключенным справочником намного лучше ориентируется в большом API, выбирает правильные методы и не путает близкие по смыслу модули.

Доступные справочники

docs/rules/zup-hr-api-reference.md — 1С:ЗУП 3.1 (кадровый учёт)

Полный reference по типовым механизмам конфигурации 1С:Зарплата и управление персоналом 3.1 (базовая / ПРОФ / КОРП). Применяется при любой разработке на ЗУП 3.1.

22 раздела, ~620 строк. Что внутри:

Раздел	Содержание
1. Архитектура	Ключевое различие Справочник.Сотрудники (рабочее место) vs Справочник.ФизическиеЛица (персональные данные). Правило выбора.
2. Иерархия модулей	КадровыйУчет / КадровыйУчетРасширенный / КадровыйУчетПовтИсп / ЗарплатаКадры — что публичное, что внутреннее, когда какой использовать.
3-4. КадровыеДанные	Главные методы КадровыеДанныеСотрудников / КадровыеДанныеФизическихЛиц — массовые и единичные. Параметры, RLS, производительность.
5. Справочник полей	Все поля, доступные через КадровыеДанные: периодические (Должность, Подразделение, Оклад, График, ~50 полей) и постоянные (ДатаПриема, ТабельныйНомер, СНИЛС, ~80 полей). Объяснён нюанс "Текущий*" префикса.
6. Приём/увольнение	ПериодыРаботыСотрудников, ДатаПриемаФизическогоЛица, ЭтоНачалоТрудовойДеятельности.
7. Стажи	Все виды стажа (общий, страховой, северный, непрерывный), представление, расчёт продолжительности, нормализация.
8. Связь Сотрудник ↔ ФизЛицо	ОсновнойСотрудникФизическогоЛица, СотрудникиФизическихЛиц, НеоформленныеСотрудникиФизическихЛиц — массовые и кешируемые варианты.
9. Списки сотрудников организации	СотрудникиОрганизации с параметрами отбора (подразделение, виды договоров, включая уволенных).
10-11. Временные таблицы	СоздатьВТ* для пакетных запросов. СоздатьВТРабочиеМестаСотрудников для интервалов работы.
12. Архив сотрудников	ПоместитьСотрудникаВАрхив, ИзвлечьСотрудникаИзАрхива (нюанс с пометкой удаления).
13. Создание	Новое физлицо и новый сотрудник.
14. ФИО	Инициалы, склонение по падежам, определение пола, склонение должностей (веб-сервис Морфер).
15. Вспомогательные методы	ГоловнаяОрганизация, ДоступныеОрганизации, ответственные лица на дату.
16. Вызовы с клиента	КадровыйУчетВызовСервера — безопасный публичный API.
17. Текущие начисления	ТекущиеНачисленияСотрудника, плановые начисления через ВТ.
18. Остатки отпусков	ОстаткиОтпусковСотрудниковНаДату.
19. Графики / производственный календарь	РасписанияРаботыНаПериод, РазностьДатПоКалендарю, БлижайшиеРабочиеДаты.
20. Печатные формы	ТабельныйНомерНаПечать, ТарифнаяСтавкаНаПечать, ФормаМножественногоЧисла.
21. Паспортные данные	ДокументыФизическихЛиц, ДокументУдостоверяющийЛичностьФизлица.
22. Штатное расписание	ДанныеПозицииШтатногоРасписания.

В конце — секция "Ключевые нюансы" с частыми граблями: RLS, ДатаПолученияДанных='00010101', массовые vs единичные методы, кеширование ПовтИсп.

Связанные шаблоны в базе (найти через templatesearch("ЗУП <тема>")):

• ЗУП: Механизм представлений СКД (Представления_) — виртуальные таблицы для СКД-отчётов
• ЗУП: Периодические регистры через ЗарплатаКадрыПериодическиеРегистры — срезы через МВТ
• ЗУП: Менеджер расчета зарплаты МенеджерРасчетаЗарплаты — программный расчёт
• ЗУП: Средний заработок и остатки отпусков — УчетСреднегоЗаработка
• ЗУП: Учет рабочего времени и производственный календарь — УчетРабочегоВремениРасширенный + КалендарныеГрафики

Как подключить справочник к AI-агенту

Claude Code — два варианта:

1. Глобально (для всех проектов): скопировать файл в ~/.claude/rules/ (Windows: C:\Users\<user>\.claude\rules\). Все правила из этой папки автоматически включаются в контекст каждой сессии.
2. Для конкретного проекта: добавить ссылку в CLAUDE.md проекта: См. companion-справочник: <путь к файлу>.

Cursor / другие IDE: подключить файл в настройках правил проекта (Rules / Instructions). Формат Markdown - универсальный.

Через MCP-клиент без IDE: скачать файл и давать агенту как system prompt или attached document при работе с ЗУП-темами.

Контрибуция справочника

Справочники покрывают домены с большим API, в которых AI-агенту без контекста сложно выбрать правильный метод. Если у вас есть такой reference по другой конфигурации / подсистеме (Бухгалтерия, ERP, УТ, БСП-подсистема и т.п.) — открывайте PR в docs/rules/. Формат свободный, главное структура: оглавление, секции по темам API, в конце — ключевые нюансы/грабли.

Благодарности

• alonehobo/1c_templates_mcp - оригинальный MCP-сервер с базой шаблонов
• salexdv/bsl_console - Monaco Editor с подсветкой BSL-синтаксиса

Лицензия

MIT