# 1C MCP RAG Agent — ИИ-помощник по коду, метаданным и данным 1С:Предприятия

**MCP-сервер для 1С**: подключает Claude Desktop, Cursor, LM Studio или Open WebUI к **вашей** конфигурации 1С. ИИ ищет по коду и метаданным, объясняет логику проведения и заполнения полей, строит цепочки вызовов, разбирает внешние обработки, а при подключённом HTTP-сервисе отвечает и по **данным** базы: отчёты, списки, Excel.

*MCP server + RAG for 1C:Enterprise (1С:Предприятие 8.3). Semantic and keyword search over your configuration code and metadata (Qdrant + fastembed), 24 tools for AI clients (Claude Desktop, Cursor, LM Studio, Open WebUI), optional live data via the 1C HTTP service. Works with any configuration: УТ, УПП, ERP, БП, ЗУП, custom.*

![Панель управления: мастер первого запуска](docs/panel.jpg)

- **Любая конфигурация.** Привязки к типовой нет: имена объектов агент берёт из вашей выгрузки, а не из встроенного словаря.
- **Только чтение.** Агент не меняет базу и конфигурацию; правки кода выдаёт как рекомендации.
- **Локально.** Индекс, модель поиска и сервер работают на вашем ПК. Код конфигурации наружу не уходит, если вы сами не выберете облачную модель в ИИ-клиенте.
- **Панель настроек.** Установка и первый запуск проходят мастером из 4 шагов, править YAML вручную не нужно.

> Код и метаданные 1С, справка платформы и материалы ИТС в репозиторий не входят — это материалы фирмы 1С и владельцев конфигураций. Вы индексируете собственную выгрузку.

## Содержание

- [Возможности](#возможности)
- [Инструменты агента (MCP tools)](#инструменты-агента-mcp-tools)
- [Требования](#требования)
- [Быстрый старт](#быстрый-старт)
- [Панель управления](#панель-управления)
- [Подключение ИИ-клиента](#подключение-ии-клиента)
- [Подключение к данным 1С](#подключение-к-данным-1с-необязательно)
- [Командная строка и скрипты](#командная-строка-и-скрипты)
- [Как это устроено](#как-это-устроено)
- [Настройки](#настройки)
- [Безопасность](#безопасность)
- [Частые проблемы](#частые-проблемы)
- [Документация](#документация)

## Возможности

| Что спросить | Что делает агент |
|---|---|
| Как работает код | Находит модуль и процедуры, объясняет логику проведения, записи, заполнения на основании, расчёта; по тексту ошибки находит место в коде |
| Кто вызывает и что вызывает | Где объявлена процедура, откуда вызывается, дерево вызовов вглубь |
| Почему поле не заполнилось | Разбирает обработчики заполнения и проведения, объясняет, откуда берётся значение и почему пусто |
| Движения документа | По каким регистрам проводится документ, что пишется в каждый, какие документы пишут в регистр |
| Структура объектов | Реквизиты, табличные части, формы, макеты, значения перечислений, измерения и ресурсы регистров |
| Кнопки и формы | Что делает кнопка, почему поле недоступно или скрыто (функциональные опции, код Видимость/Доступность) |
| Качество кода | Запросы в цикле, обращение через точку, медленные места, управляемые блокировки |
| Права доступа | Какие роли дают доступ к объекту, RLS, кто может удалять или изменять |
| Прочие разделы конфигурации | Подписки на события, регламентные задания, HTTP-сервисы, планы обмена, общие реквизиты, запрос СКД, печатные формы, опасный код (Выполнить/Вычислить) |
| Внешние обработки | Разбор `.epf` / `.erf` / `.cfe`: формы, модули, запросы, совместимость с вашей конфигурацией |
| Создание обработок | Собирает готовый файл `.epf` (модуль, реквизиты, табличные части, обычная форма) или внешний отчёт `.erf` на СКД |
| Справка платформы | Синтаксис встроенного языка и языка запросов, методы платформы, стандарты разработки (если подключена справка) |
| Данные базы\* | Суммы, количества, топы, сравнение периодов, маржа, ABC, долги и остатки, графики, выгрузка в Excel |
| Документы по условиям\* | Списки документов и элементов по реквизитам шапки: не проведены, пустое поле, статус |
| Журнал регистрации\* | Ошибки за период, кто изменил или удалил документ, кто сейчас в базе |

\* Нужен опубликованный HTTP-сервис 1С из папки `onec_http/` (см. [ниже](#подключение-к-данным-1с-необязательно)). Без него агент работает с кодом и метаданными.

## Инструменты агента (MCP tools)

Клиент видит 24 инструмента. Модель выбирает их сама; кроме того, встроенный роутер по формулировке вопроса сразу направляет запрос в нужный узкий инструмент. Сокращать фразу не нужно: передавайте вопрос целиком.

### Код и логика

| Инструмент | Назначение | Пример вопроса |
|---|---|---|
| `inspect_code` | Логика в коде по вопросу: где и как рассчитывается, что происходит при записи или проведении, место ошибки по её тексту | «Как рассчитывается скидка в заказе?» |
| `search_code` | Поиск по коду по словам или идентификатору (запасной к `inspect_code`) | «Где используется ЗапросОстатков?» |
| `read_code` | Прочитать фрагмент модуля по пути и строке из результатов других инструментов | — |
| `proc_index` | Где объявлена процедура или функция и откуда она вызывается; похожие имена, если точной нет | «Кто вызывает ОбщегоНазначения.ЗначениеРеквизитаОбъекта?» |
| `trace_calls` | Дерево вызовов от процедуры вглубь | «Проследи вызовы из ОбработкаПроведения документа X» |
| `explain_fill` | Почему поле пустое или заполнено не тем; почему документ не проводится | «Почему в реализации пустой склад?» |
| `analyze_object_movements` | По каким регистрам проводится документ и что меняется в учёте | «В какие регистры пишет ПеремещениеТоваров?» |
| `explain_command` | Что делает кнопка формы; почему кнопка или поле недоступны или скрыты | «Почему поле Склад недоступно?» |
| `audit_query_code` | Проверка качества: запросы в цикле, обращение через точку, медленные места | «Найди запросы в цикле в модуле ЗаказКлиента» |
| `analyze_locks` | Управляемые блокировки: где стоят, ожидания и конфликты, какие добавить | «Какие блокировки нужны в проведении X?» |

### Объекты и структура конфигурации

| Инструмент | Назначение | Пример вопроса |
|---|---|---|
| `resolve_object` | Найти объект по описанию своими словами | «Каким документом оформляется возврат от покупателя?» |
| `list_objects` | Перечень объектов одного класса | «Какие регистры накопления есть?» |
| `describe_object` | Реквизиты, табличные части, формы, макеты, значения перечисления, регистраторы регистра, состав подсистемы | «Какие документы пишут в регистр ТоварыНаСкладах?» |
| `explain_config` | Подписки на события, регламентные задания, RLS, HTTP-сервисы, планы обмена, общие реквизиты, события форм, печатные формы, запрос СКД, опасный код | «Кто подписан на ПередЗаписью документа X?» |
| `access_overview` | Роли, права, пользователи, RLS | «Какие роли могут удалять документы?» |

### Данные базы (нужен HTTP-сервис 1С)

| Инструмент | Назначение | Пример вопроса |
|---|---|---|
| `build_report` | Суммы, количества, списки, топы, сравнение периодов, маржа, ABC и отток, долги и остатки, Excel и графики | «Продажи по клиентам за 2024, выгрузи в Excel» |
| `query_by_attributes` | Список объектов по реквизитам шапки: статус, пустое поле, пометка удаления, проведён ли | «Какие реализации не проведены?» |
| `document_by_number` | Найти документ по номеру в любом формате; вид документа можно не знать | «Покажи заказ ТД-000012» |
| `execute_query` | Выполнить готовый запрос 1С (только ВЫБРАТЬ) — для программиста | — |
| `analyze_event_log` | Журнал регистрации и сеансы | «Кто удалил документ?», «Кто сейчас в базе?» |

### Файлы, справка и прочее

| Инструмент | Назначение | Пример вопроса |
|---|---|---|
| `inspect_external_processing` | Разбор `.epf` / `.erf` / `.cfe` и совместимость с вашей конфигурацией; файл находится по имени | «Подойдёт ли Загрузка цен.epf к нашей базе?» |
| `build_external_processing` | Собрать внешнюю обработку `.epf` или внешний отчёт `.erf` на СКД без запуска 1С | «Сделай обработку для загрузки цен из Excel» |
| `code_help` | Справка платформы и ИТС: синтаксис, методы, язык запросов, стандарты | «Как в запросе сделать левое соединение?» |
| `agent_capabilities` | Что умеет помощник, примеры вопросов | «Что ты умеешь?» |

## Требования

- Windows 10/11 или Windows Server, **Python 3.10+** (при установке отметьте «Add python.exe to PATH").
- **Docker Desktop** — желательно: Qdrant в контейнере быстрее на крупных конфигурациях. Без Docker работает встроенный режим.
- 8 ГБ ОЗУ и около 5 ГБ на диске (модель поиска ~1 ГБ, индекс зависит от конфигурации).
- 1С:Предприятие 8.3 — только чтобы выгрузить конфигурацию в файлы (Конфигуратор) и, по желанию, опубликовать HTTP-сервис для данных.
- ИИ-клиент с поддержкой MCP: Claude Desktop, Cursor, LM Studio, Open WebUI или другой.

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

1. Скачайте репозиторий (**Code → Download ZIP**) или клонируйте:
   ```bash
   git clone https://github.com/malsem32/1c-mcp-rag-agent.git
   ```
2. Запустите **`deploy.bat`** двойным щелчком. Он создаст окружение `.venv`, установит зависимости, создаст `config.yaml` и `.env` из шаблонов, поднимет Qdrant в Docker (если Docker есть) и откроет панель <http://127.0.0.1:8765>.
3. В Конфигураторе: **Конфигурация → Выгрузить конфигурацию в файлы** в пустую папку.
4. В панели на вкладке **«Первый запуск»** пройдите 4 шага:
   1. укажите папку выгрузки;
   2. запустите Qdrant в Docker одной кнопкой или включите встроенный режим без Docker;
   3. запустите индексацию: от 20 минут до нескольких часов в зависимости от размера конфигурации, при первом запуске скачивается модель поиска;
   4. скопируйте готовую настройку для своего ИИ-клиента.
5. Перезапустите ИИ-клиент и спросите, например: «По каким регистрам проводится документ РеализацияТоваровУслуг?» (подставьте имя из своей конфигурации).

Позже панель открывается через **`panel.bat`**. После новой выгрузки конфигурации повторите шаг 3 или используйте вкладку «Запуск и проверки → Переиндексация».

## Панель управления

Локальный веб-интерфейс на `http://127.0.0.1:8765`, доступен только с этого ПК.

| Раздел | Что там |
|---|---|
| **Первый запуск** | Мастер из 4 шагов со статусами: папка выгрузки → Qdrant → индексация → подключение клиента |
| **Запуск и проверки → Переиндексация** | Заменить индекс новой выгрузкой, обновить только изменённое или удалить индекс; прогресс по этапам с оценкой времени |
| **→ Проверка и сервисы** | «Проверить всё»: 11 проверок от пакетов Python до MCP-сервера, с подсказкой, что делать; установка зависимостей, запуск Qdrant, починка векторов, запуск и остановка MCP-сервера |
| **→ Индексация вручную** | Индексация с параметрами, подбор модели и размера фрагментов под вашу конфигурацию, оценка качества поиска на вопросах из выгрузки |
| **→ Другие конфигурации** | Подключить вторую конфигурацию в отдельную коллекцию, не трогая рабочую |
| **→ Журнал** | Вывод задач и лог MCP-сервера |
| **Подключение к 1С** | Режим `none` / `http` / `com`, адрес HTTP-сервиса, пользователь, пароль |
| **Хранилище индекса (Qdrant)** | Docker или встроенная папка, режим поиска (смысл + слова / только смысл / точный) |
| **MCP-сервер** | Кому доступен сервер (этот ПК или сеть), порт, токен доступа |
| **Расширенные** | Нарезка выгрузки, модель поиска с пресетами, расчёт векторов, LLM для встроенного CLI, лимиты агента |

Настройки сохраняются в `config.yaml` (с резервной копией `config.yaml.bak`), а пароли, ключи и токены — в `.env`.

## Подключение ИИ-клиента

Готовые значения с вашими путями показывает панель: «Первый запуск», шаг 4.

**Claude Desktop, Cursor, LM Studio (stdio).** Клиент сам запускает сервер. Добавьте в его конфиг блок:

```json
{
  "mcpServers": {
    "rag_agent": {
      "command": "C:\\путь\\к\\проекту\\.venv\\Scripts\\python.exe",
      "args": ["C:\\путь\\к\\проекту\\main.py"]
    }
  }
}
```

- Claude Desktop: Settings → Developer → Edit Config (`claude_desktop_config.json`).
- Cursor: Settings → MCP → Add new MCP server (`mcp.json`).
- LM Studio: Program → Install → Edit `mcp.json`.

**Open WebUI и другие HTTP-клиенты.** Запустите MCP-сервер кнопкой в панели (или `python main.py --transport http`). В Open WebUI: Admin Panel → Settings → External Tools → «+» → тип **MCP (Streamable HTTP)**, адрес `http://host.docker.internal:8100/mcp`. Если сервер открыт в сеть, укажите Bearer-токен из панели.

LLM в панели настраивать не нужно: при работе через MCP модель даёт сам клиент. Раздел «LLM для CLI» нужен только для встроенного консольного агента `cli.py`.

## Подключение к данным 1С (необязательно)

По умолчанию `backend: none`: агент отвечает по коду и метаданным из индекса. Чтобы он отвечал и по данным:

1. Создайте в расширении конфигурации HTTP-сервис с корневым URL `ai` и модулем из `onec_http/Module.bsl`. Сама конфигурация при этом не меняется.
2. Опубликуйте его на веб-сервере (Конфигуратор → Администрирование → Публикация на веб-сервере).
3. В панели, раздел «Подключение к 1С»: режим `http`, адрес вида `http://localhost/ИмяБазы/hs/ai`, пользователь с правами на чтение, пароль.
4. «Запуск и проверки → Проверка и сервисы → Проверить всё» — строка «Связь с 1С» должна быть зелёной.

Подробно — в [ИНСТРУКЦИЯ_РАЗВЕРТЫВАНИЕ.md](ИНСТРУКЦИЯ_РАЗВЕРТЫВАНИЕ.md), примеры запросов — в `onec_http/Примеры_запросов.http`. Вместо HTTP можно использовать COM-соединение (`backend: com`, только Windows, медленнее).

## Командная строка и скрипты

```powershell
.\.venv\Scripts\Activate.ps1

# MCP-сервер
python main.py                                  # stdio (так его запускают Claude Desktop / Cursor / LM Studio)
python main.py --transport http                 # HTTP для Open WebUI: 127.0.0.1:8100/mcp

# Консольный агент (нужна LLM из раздела «LLM для CLI»)
python cli.py "по каким регистрам проводится документ …"
python cli.py "почему не заполнился склад в …"
python cli.py "проследи цепочку вызовов из …"

# Индексация без панели
docker compose up -d qdrant                     # Qdrant в Docker
python scripts/full_qdrant_pipeline.py          # нарезка + индексация
python scripts/index_qdrant.py --recreate       # пересоздать индекс (после смены модели или размера фрагмента)
python scripts/index_qdrant.py --repair-vectors # найти и пересчитать нулевые векторы

# Панель на другом порту, без открытия браузера
python panel/server.py --port 9000 --no-browser
```

Полный прогон Qdrant описан в [scripts/ПОЛНЫЙ_ПРОГОН_QDRANT.md](scripts/ПОЛНЫЙ_ПРОГОН_QDRANT.md).

Параметры HTTP-режима MCP задаются в `.env` или в панели: `RAG_MCP_HOST` (по умолчанию `127.0.0.1`), `RAG_MCP_PORT` (`8100`), `RAG_MCP_TOKEN` (Bearer-токен).

## Как это устроено

```
выгрузка конфигурации (XML + BSL)
        |
        v  нарезка и чистка: модули по процедурам, карточки объектов, форм и макетов
фрагменты (JSONL)
        |
        v  эмбеддинги fastembed (локально, на CPU) -> Qdrant
коллекции: код, процедуры, файлы выгрузки, справка
        |
        v  гибридный поиск: по смыслу + по словам (RRF)
роутер вопроса -> 24 инструмента -> MCP-сервер -> ИИ-клиент
                                     \-> HTTP-сервис 1С (данные, по желанию)
```

- **Поиск.** Гибридный: векторный (multilingual mpnet / MiniLM / e5, модель выбирается в панели) плюс лексический по идентификаторам 1С.
- **Роутинг.** Вопрос классифицируется по структуре фразы (имена в PascalCase, «почему не заполнился», «сколько / сумма / в Excel»), а не по словарю типовой конфигурации.
- **Имена объектов.** Берутся из каталога вашей выгрузки, поэтому работает на любой конфигурации.
- **Во время работы** агент читает только Qdrant; папку выгрузки он открывает лишь при индексации.

## Настройки

Все настройки — в `config.yaml` (создаётся из `config.example.yaml`); секреты — в `.env` (шаблон `.env.example`). Удобнее менять их в панели.

| Секция | Что настраивается |
|---|---|
| `backend`, `http`, `com` | Режим работы с базой 1С и параметры подключения |
| `paths` | Папка выгрузки, файлы нарезки |
| `qdrant` | Docker или встроенный режим, коллекции, режим поиска |
| `embedding` | Модель поиска (`fastembed` локально или `openai`-совместимый API) |
| `prepare` | Нарезка: размер фрагмента, карточки объектов и форм, чистка, удаление дублей |
| `llm`, `providers` | Модель для встроенного CLI (LM Studio, Ollama, OpenAI, OpenRouter, Gemini, xAI) |
| `agent` | Для кого отвечает агент (программист / пользователь), лимиты строк в отчётах |

## Безопасность

- Агент только читает (`agent.read_only: true`): не пишет в базу и не меняет конфигурацию.
- Панель слушает только `127.0.0.1` и защищена от запросов с чужих страниц.
- MCP-сервер по умолчанию доступен только с этого ПК. Если открыть его в сеть (`0.0.0.0`), он без токена не запустится.
- `config.yaml`, `.env`, выгрузка конфигурации и индекс в репозиторий не попадают (`.gitignore`). Не публикуйте их.

## Частые проблемы

| Симптом | Что делать |
|---|---|
| «Qdrant не отвечает» | Запустите Docker Desktop и нажмите «Запустить Qdrant в Docker», или включите встроенный режим («Первый запуск», шаг 2) |
| Qdrant отвечает 502 при работающем Docker | Системный прокси перехватывает localhost. Начиная с этой версии агент обходит прокси для локального Qdrant сам; в старых версиях добавьте `NO_PROXY=localhost,127.0.0.1` |
| «Папка индекса занята» во встроенном режиме | Встроенный Qdrant открывается одним процессом: остановите MCP-сервер или ИИ-клиент на время индексации (мастер делает это сам) |
| Смысловой поиск ничего не находит | «Проверка и сервисы → Починить векторы», затем «Проверить всё» |
| Сменили модель поиска | Нужна индексация заново: «Переиндексация → Заменить на новую конфигурацию» |
| Клиент не видит новых данных после индексации | Перезапустите MCP-сервер и ИИ-клиент |

Остальное — в [ИНСТРУКЦИЯ_РАЗВЕРТЫВАНИЕ.md](ИНСТРУКЦИЯ_РАЗВЕРТЫВАНИЕ.md).

## Документация

- [ИНСТРУКЦИЯ_РАЗВЕРТЫВАНИЕ.md](ИНСТРУКЦИЯ_РАЗВЕРТЫВАНИЕ.md) — установка, панель, индексация, подбор настроек, HTTP-сервис 1С, проблемы.
- [ИНСТРУКЦИЯ.md](ИНСТРУКЦИЯ.md) — работа с агентом: вопросы, инструменты, режимы ответов.
- [knowledge/README.md](knowledge/README.md) — словари, правила и заметки, которые можно дополнять без программирования.
- [onec_http/README.md](onec_http/README.md) — HTTP-сервис 1С для доступа к данным.
- [AGENTS.md](AGENTS.md) — правила для разработчиков и ИИ-ассистентов, которые меняют код проекта.

## Лицензия

Код распространяется по лицензии [MIT](LICENSE). Лицензия не распространяется на конфигурации 1С, справку платформы и материалы ИТС, которые вы индексируете: они принадлежат их правообладателям.