# 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`](https://hub.docker.com/r/desko77/1c-templates-mcp).

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

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

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

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

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

```bash
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

```json
{
  "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-модель.

```yaml
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, или хочется гарантированно детерминированное поведение без зависимостей от внешних сервисов.

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

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

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

```yaml
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)

```bash
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 рядом с проектом:

```bash
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:
   ```bash
   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

```bash
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`](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](https://github.com/alonehobo/1c_templates_mcp) - оригинальный MCP-сервер с базой шаблонов
- [salexdv/bsl_console](https://github.com/salexdv/bsl_console) - Monaco Editor с подсветкой BSL-синтаксиса

## Лицензия

MIT