1c-templates-mcp

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

Возможности

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

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

git clone https://github.com/<your-username>/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-инструменты

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

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

Архитектура

                     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

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

Первый запуск с новой моделью качает её с 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 строк. Что внутри:

В конце — секция "Ключевые нюансы" с частыми граблями: 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