Skip to content

Desko77/1c-templates-mcp

BranchesTags

Repository files navigation

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 для быстрого запуска

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

Для обычного использования - без клонирования репозитория и без сборки. Готовый образ публикуется на 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-контейнеры.
  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, в конце — ключевые нюансы/грабли.

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

Лицензия

MIT

About

MCP-сервер с семантическим поиском по шаблонам кода 1С (BSL). 2200+ шаблонов, CRUD веб-UI с Monaco Editor, ChromaDB + embeddings.

Topics

docker mcp embeddings monaco-editor semantic-search bsl 1c 1c-enterprise code-templates fastapi chromadb mcp-server

Resources

Readme
Activity

Stars

22 stars

Watchers

1 watching

Forks

1 fork
Report repository

Releases

No releases published

Packages

 
 
 

Contributors

Languages