conf-doc

name	conf-doc
description	Семантический поиск и drill-down по документации конфигурации 1С через MCP 1c-conf-doc или HTTP API. Используй для метаданных (реквизиты, регистры, связи) и источников данных отчётов (запросы СКД) перед OData-запросами. Короткие keyword-запросы; odata_fields на top-1; финальные имена полей — из OData $metadata.

conf-doc — поиск по метаданным конфигурации 1С

Инструмент: 1c-conf-doc (HTTP :8050 или MCP conf_doc_*). Индекс SQLite + FAISS + markdown на сервере — не читай output/, metadata.db, CLI с диска клиента.

Связка с OData: conf-doc → объект, смысл полей, регистры из отчётов; OData $metadata / fetch → фактические имена полей и данные.

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

MCP	HTTP	Назначение
conf_doc_health	GET /health	Доступность
conf_doc_list_configurations	GET /configurations	Имена проиндексированных конфигураций
conf_doc_search	POST /search	Семантический поиск (+ odata_fields для top-1)
conf_doc_list_objects	GET /objects	Поиск по имени в SQLite
conf_doc_get_object	GET /objects/{type}/{name}	Карточка: счётчики, чанки, help
conf_doc_get_object_chunk	GET .../chunks/{N}	Полный текст фрагмента
conf_doc_query	POST /query	RAG (только если LLM включён на сервере)

OpenAPI: {CONF_DOC_API_URL}/docs

Переменные окружения MCP

Переменная	Описание
CONF_DOC_API_URL	URL backend без / (например http://localhost:8050)
CONF_DOC_CONFIGURATION	Поле name из /configurations (ЗУП 3.1: ЗарплатаИУправлениеПерсоналомКОРП)

См. mcp.example.json.

Двухшаговая модель

1. Обзор — conf_doc_search / POST /search: топ объектов, один лучший чанк на объект.
2. Детали — conf_doc_get_object → conf_doc_get_object_chunk или уточнённый search.

По умолчанию /search обрезает text до 800 символов. Передай "full": true для полного текста. Поле odata_fields не обрезается — для top-1 возвращается JSON реквизитов из индекса.

Как формулировать query (критично)

Семантический поиск плохо работает на длинных вопросах. Не передавай целиком: «Покажи 10 штатных сотрудников: ФИО, должность».

Делай	Не делай
Короткие ключевые слова: отпуск, увольнение, Сотрудники	Полный текст вопроса с глаголами и числами
Точное имя объекта: КадроваяИсторияСотрудников	Размытые фразы: Catalog Сотрудники
Несколько узких запросов + выбор лучшего	Один длинный запрос «на всё»
Фильтр object_type: Document, InformationRegister	Ожидать, что Role подскажет OData-entity

Доменные доп. запросы (ЗУП)

Тема	Дополнительные query
Сотрудники, ФИО, должность	Сотрудники, КадроваяИсторияСотрудников
Отпуск, остаток отпуска	отпуск, остатки отпусков, АналитикаОстатковОтпусков, ОстаткиОтпусков
Начисление зарплаты	НачислениеЗарплаты, начисление зарплаты
Увольнение	увольнение, Увольнение

Приоритет типов для OData-entity

Предпочитай: Catalog, Document, InformationRegister, AccumulationRegister, CalculationRegister. Report не даёт OData-entity, но его чанки «Запрос СКД» показывают реальные регистры-источники отчёта — читай их для выбора register entity.

Чанки объектов

chunk	Содержимое
0	Overview (справка, формы)
1+	Реквизиты шапки, табличные части

Report: дополнительно ## Модуль объекта (BSL) и ## Запрос СКД: {набор} — полный текст запроса из основной СКД. Для анализа источников данных читай чанки с «Запрос СКД», не только overview.

Пример (остатки отпусков):

1. search("остатки отпусков") → Report.ОстаткиОтпусков (семантика) + InformationRegister.АналитикаОстатковОтпусков (прямой OData)
2. get_object(Report, ОстаткиОтпусков) → список чанков
3. get_object_chunk(..., N) где в тексте Запрос СКД → регистры: НачальныеОстаткиОтпусков, ФактическиеОтпуска, …
4. OData: для готового остатка — InformationRegister_АналитикаОстатковОтпусков + поле ОстатокДней; имена — из $metadata

conf-doc + OData: два слоя правды

Слой	Источник	Что даёт
Объект и смысл полей	conf-doc	Document.Отпуск, реквизиты, запросы отчётов
Имена полей в запросе к базе	OData $metadata	Фактические Property публикации

odata_fields строится из XML конфигурации, не из OData-публикации. Перед $select / $filter сверяй с $metadata.

Workflow для агента

Структура конфигурации

- [ ] conf_doc_health
- [ ] conf_doc_list_configurations
- [ ] conf_doc_search — короткий query (+ odata_fields top-1)
- [ ] conf_doc_get_object_chunk — реквизиты / справка

Перед OData-запросом к данным

- [ ] conf_doc_search — keyword-запросы (см. таблицу ЗУП)
- [ ] Выбрать Catalog/Document/Register из top-k
- [ ] Для отчётных тем — drill-down Report → чанки «Запрос СКД»
- [ ] odata_fields или chunk с реквизитами
- [ ] OData $metadata — финальные имена полей
- [ ] fetch / OData

Маппинг типов → OData-префиксы

Тип conf-doc	Префикс OData	Пример
Catalog	Catalog_	Catalog_Сотрудники
Document	Document_	Document_Отпуск
InformationRegister	InformationRegister_	InformationRegister_АналитикаОстатковОтпусков
AccumulationRegister	AccumulationRegister_	AccumulationRegister_ФактическиеОтпуска
CalculationRegister	CalculationRegister_	CalculationRegister_...

Имя configuration — поле name из /configurations, не синоним «ЗУП».

Ограничения

• Нет прямого чтения .md / SQLite с клиента.
• odata_fields ≠ гарантия имён в OData публикации.
• Виртуальные таблицы OData (/Balance(), /Turnovers()) в conf-doc не описаны — см. OData skill.
• После обновления chunker (Report+СКД) нужен index на сервере conf-doc для ZUP.

Ошибки

Симптом	Действие
Connection refused	docker compose up -d в 1c-conf-doc
Report — только 1 короткий chunk	Переиндекс ZUP (index --force или смена CHUNKER_VERSION)
503 на conf_doc_query	LLM отключён — search + chunks
OData 400 code 6	Сверить с $metadata, не только conf-doc

Настройка

Backend: проект 1c-conf-doc, порт 8050. Оценка пользы: docs/conf-doc-evaluation-checklist.md.