> For the complete documentation index, see [llms.txt](https://docs.onerpa.ru/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.onerpa.ru/mcp-servery-1c/servery/code-metadata-search.md).

# CodeMetadataSearchServer

Поиск по метаданным, справке, коду, формам и зависимостям конфигурации 1С. Генерация и валидация XML.

## Назначение

CodeMetadataSearchServer — комплексный MCP-сервер для глубокой работы с конфигурацией 1С. Индексирует метаданные, код модулей, формы, HTML-справку и XML-определения. Предоставляет ИИ **28 инструментов** для:

* Семантического и структурного поиска по метаданным конфигурации
* Полнотекстового и векторного поиска по коду модулей
* Анализа структуры BSL-модулей, иерархии вызовов и зависимостей
* Поиска и анализа форм объектов конфигурации
* Поиска по HTML-справке конфигурации
* Генерации XSD-схем и валидации XML
* Чтения и обратной сборки двоичных обычных форм (`Form.bin`)

## Доступные инструменты MCP (28)

Инструменты сгруппированы по функциональным областям.

### Метаданные

| Инструмент             | Описание                                                                                                                                      |
| ---------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
| `metadatasearch`       | Поиск объектов конфигурации по имени или описанию                                                                                             |
| `get_metadata_details` | Детальная структура объекта: реквизиты, типы, табличные части, формы и команды, синонимы, стандартные реквизиты, виртуальные таблицы регистра |

### Код

| Инструмент                  | Описание                                                             |
| --------------------------- | -------------------------------------------------------------------- |
| `codesearch`                | Поиск по коду модулей объектов, форм и общих модулей                 |
| `search_function`           | Поиск процедуры или функции BSL по имени                             |
| `get_module_structure`      | Полная структура BSL-модуля: процедуры, функции, области, статистика |
| `get_method_call_hierarchy` | Иерархия вызовов метода: кто вызывает и что вызывается               |
| `search_forms`              | Поиск форм объектов конфигурации                                     |
| `inspect_form_layout`       | Детальная структура формы: элементы, реквизиты, команды, обработчики |
| `graph_dependencies`        | Граф зависимостей объекта конфигурации                               |
| `bsl_scope_members`         | Доступные методы, свойства и события для BSL-контекста               |

### Компактный API

| Инструмент         | Описание                                                                         |
| ------------------ | -------------------------------------------------------------------------------- |
| `compact_search`   | Ограниченный бюджетом поиск по символам и метаданным с курсорной пагинацией      |
| `compact_symbol`   | Получение BSL-символов и их точных позиций, опционально — тел процедур и функций |
| `compact_call`     | Ограниченный обход связей вызовов для BSL-символа                                |
| `compact_metadata` | Постраничное получение объектов метаданных с ограниченными списками реквизитов   |

### Справка

| Инструмент   | Описание                           |
| ------------ | ---------------------------------- |
| `helpsearch` | Поиск по HTML-справке конфигурации |

### XSD-схемы

| Инструмент       | Описание                                        |
| ---------------- | ----------------------------------------------- |
| `get_xsd_schema` | Получение XSD-схемы для типа объекта метаданных |
| `verify_xml`     | Валидация XML-содержимого по XSD-схеме          |

### Артефакты конфигурации

| Инструмент                      | Описание                                                                 |
| ------------------------------- | ------------------------------------------------------------------------ |
| `get_form_artifact`             | Чтение артефакта формы: дерево элементов, реквизиты, команды, provenance |
| `get_role_artifact`             | Объявленные права роли или роли, дающие права на объект                  |
| `get_report_artifact`           | Структура отчёта: формы, макеты, схема компоновки данных                 |
| `list_artifact_links`           | Ссылки артефакта на внешние результаты прогонов и тестов                 |
| `register_external_result_link` | Регистрация ссылки на неизменяемый внешний результат                     |

### Обычные формы

| Инструмент             | Описание                                                                                |
| ---------------------- | --------------------------------------------------------------------------------------- |
| `unpack_ordinary_form` | Распаковка двоичного `Form.bin` обычной формы в редактируемый рабочий каталог           |
| `build_ordinary_form`  | Обратная сборка рабочего каталога в `Form.bin` с проверкой логической полезной нагрузки |

### Служебные (всегда доступны)

| Инструмент      | Описание                                                                               |
| --------------- | -------------------------------------------------------------------------------------- |
| `reindex`       | Запуск переиндексации в фоновом режиме                                                 |
| `stats`         | Статистика индексов, модель эмбеддингов, аптайм                                        |
| `plugin_state`  | Состояние плагинов: файлы, хуки, таблицы, ошибки, эпоха, вклад в fingerprint поколения |
| `plugin_reload` | Атомарно перечитать каталог плагинов без перезапуска сервера                           |

У каждого инструмента есть аннотации MCP. Инструменты, которые ничего не меняют, — `readOnlyHint: true`. `reindex`, `register_external_result_link`, `unpack_ordinary_form`, `build_ordinary_form` и `plugin_reload` — `readOnlyHint: false`; из них `reindex` и оба инструмента обычных форм — `destructiveHint: true`, `register_external_result_link` — `idempotentHint: true`. Все инструменты — `openWorldHint: false`: ответ берётся из локального индекса и выгрузки. `initialize` сообщает `serverInfo.name` = `CodeMetadataSearchServer` и в `serverInfo.version` — версию сборки (короткую ревизию, из которой собран образ; ту же отдают `/live` и `stats`).

Неудачный вызов приходит клиенту как ошибка инструмента — `isError: true`, — а текст у него тот же JSON: `status: "error"`, `error`, `error_code`. Успешными ответами остаются типизированный `not_found`, `degraded` и вердикт `verify_xml` внутри `data` (например, `invalid`).

***

## Описание инструментов

### metadatasearch

Поиск объектов метаданных, реквизитов и типов в конфигурации 1С. Для поиска по имени используйте формат вида `Справочники.ИмяСправочника.Реквизиты`. Для поиска по описанию — текст на русском языке. Используйте точное имя конфигурации, если оно известно.

| Параметр      | Тип    | По умолчанию | Описание                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| ------------- | ------ | ------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `query`       | string | —            | Имя или описание объекта метаданных                                                                                                                                                                                                                                                                                                                                                                                                                  |
| `limit`       | int    | 5            | Количество результатов                                                                                                                                                                                                                                                                                                                                                                                                                               |
| `object_type` | string | `""`         | Фильтр по типу метаданных 1С (`Справочник`, `Документ`, `РегистрСведений` и т.д.)                                                                                                                                                                                                                                                                                                                                                                    |
| `names_only`  | bool   | `false`      | Компактный список имён объектов (full\_path, object\_type, synonym) вместо текстовых чанков. Используйте `names_only=true` для определения релевантных объектов конфигурации, затем получайте детали через `get_metadata_details`. Имя реквизита (в том числе реквизита табличной части) отвечает объектом, который его объявляет: такая строка несёт `matched_attributes` — имя, синоним, тип и табличную часть найденного реквизита (с 10.10.2026) |
| `origin`      | string | `""`         | Фильтр по происхождению определения: `base`, `extension`, имя конкретного расширения или `all`                                                                                                                                                                                                                                                                                                                                                       |

Объекты, которые добавляет расширение (его отчёты, справочники, документы), находятся по `origin="extension"` или по имени расширения, в том числе с `names_only=true`. Заимствованные расширением объекты описывает основная конфигурация, и они отвечают как `base`: `get_metadata_details` отдаёт карточку основной конфигурации — синоним, «Движения», основные формы и остальные свойства (с 20.10.2026; раньше карточку строила пустая запись заимствованного объекта из расширения: пустой синоним, `object_type` в единственном числе, в `properties` только «Синоним»). Индекс, построенный раньше, исправляется при открытии из уже сохранённых данных, без переиндексации. Реквизиты, табличные части, формы и команды, которые расширение добавляет к заимствованному объекту, тоже есть в его карточке, с `origin` расширения (с 21.10.2026, см. [get\_metadata\_details](#get_metadata_details)). В индексе, построенном раньше, их один раз дописывает первый прогон индексации после обновления: перечитываются только описания заимствованных объектов в выгрузках расширений, основная конфигурация, модули и эмбеддинги не перестраиваются (строка журнала `Extension members: N borrowed object(s) completed …`).

### Общие параметры бюджета ответа

Инструменты `metadatasearch`, `codesearch`, `search_function`, `get_module_structure`, `get_method_call_hierarchy`, `graph_dependencies`, `get_metadata_details`, `search_forms`, `inspect_form_layout`, `get_form_artifact` и `get_report_artifact` дополнительно принимают:

| Параметр             | Тип    | По умолчанию | Описание                                                                                                                                                                                                                                                                                        |
| -------------------- | ------ | ------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `max_chars`          | int    | `0`          | Максимальный размер сериализованного ответа в символах; `0` — серверный предел: 32768 или `RESPONSE_MAX_CHARS`                                                                                                                                                                                  |
| `max_items`          | int    | `0`          | Максимум элементов на странице; `0` использует серверный предел                                                                                                                                                                                                                                 |
| `detail_level`       | string | `""`         | `outline` для сокращённого ответа или `full` для полного                                                                                                                                                                                                                                        |
| `cursor`             | string | `""`         | Непрозрачный `next_cursor` из предыдущего усечённого ответа                                                                                                                                                                                                                                     |
| `include_provenance` | bool   | `false`      | Всегда добавлять `item_id`, `location` и `evidence_path`, в том числе когда у элемента нет реального диапазона `file:start:end`. У `get_form_artifact` и `get_report_artifact` этого параметра нет; принимают его также `compact_search`, `compact_symbol`, `compact_call` и `compact_metadata` |

`detail_level` (`""`, `outline`, `full`), а также `member_type` у `bsl_scope_members` и `include` у `unpack_ordinary_form` — закрытые перечисления (enum) в схеме инструмента, как `direction` и `restrictions`. Значение в другом регистре и с пробелами по краям принимается; неизвестное значение отклоняет проверка схемы до запуска инструмента, и в отказе перечислены допустимые значения.

`search_function`, `get_metadata_details` и `inspect_form_layout` принимают ещё два строковых параметра, по умолчанию пустых: `item_id` возвращает один элемент по стабильному идентификатору из прежнего ответа без повторного поиска, а `index_identity` называет состояние индекса, для которого этот идентификатор был выдан. Если индекс с тех пор сменился, ответ — ошибка `item_id_stale`: запрос нужно выполнить заново.

Ответ содержит `items_total`, `items_returned`, `truncated` и `next_cursor`. Если `search_function` или `codesearch` вернули столько результатов, сколько задано `limit`, полное число совпадений неизвестно: `items_total` равен `null`, `items_total_reason` — `candidate_cap_reached` (с 16.10.2026; раньше `items_total` был равен `limit`). Курсор листает только прочитанные `limit` результатов — чтобы увидеть больше, увеличьте `limit` или сузьте `module_path`. Элемент с реальным диапазоном исходника получает стабильный `item_id`, точную `location` и `evidence_path`; для элемента без такого диапазона эти поля появляются только при `include_provenance=true`. Блок `budget` возвращается только когда лимит действительно ограничил или усёк ответ. Инструменты `search_function`, `get_metadata_details` и `inspect_form_layout` также принимают `item_id` и `index_identity` для прямого получения одного элемента без повторного поиска. Если индекс изменился, сервер возвращает типизированную ошибку `item_id_stale`.

По умолчанию словари и списки публикуются как один JSON-блок `text content`, без повторной копии в `structuredContent`. Совместимый режим с дублирующим структурированным ответом включается переменной `MCP_STRUCTURED_CONTENT=true`.

### Провенанс расширений

Инструменты `metadatasearch`, `codesearch`, `search_function`, `get_module_structure`, `get_metadata_details`, `search_forms` и `inspect_form_layout` дополнительно принимают:

| Параметр | Тип    | По умолчанию | Описание                                                                                                                                                                                                      |
| -------- | ------ | ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `origin` | string | `""`         | Область поиска по происхождению определения: `base` — только основная конфигурация, `extension` — любое расширение конфигурации, имя конкретного расширения — только оно, `all` (значение по умолчанию) — всё |

Применённый фильтр возвращается в поле `origin_filter`, а каждый результат несёт блок `origin` с именем конфигурации, из которой он получен, и — для расширяющего определения — с режимом расширения и ссылкой на базовое определение.

Инструмент `search_function` дополнительно принимает:

| Параметр            | Тип  | По умолчанию | Описание                                                                                                                                                                                 |
| ------------------- | ---- | ------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `explain_effective` | bool | `true`       | Добавляет в ответ `effective_definition`: какое определение метода действует, конкурирующие определения с их происхождением и режимами, а также правило, по которому выбрано действующее |

Правила разрешения: `Вместо` замещает базовое определение (`instead_supersedes_base`), `ИзменениеИКонтроль` тоже замещает: выполняется изменённая копия метода из расширения (`change_and_control_supersedes_base`, с 20.10.2026; раньше такой метод отмечался как `adopting`, а действующим оставалось базовое определение). `Перед` и `После` оставляют базовое действующим и отмечаются как перехватывающие. Если один и тот же метод одного модуля изменяют два и более расширения и хотя бы одно из них замещает его (`Вместо` или `ИзменениеИКонтроль`), ответ возвращает `collision` со списком всех участников и **не** выбирает победителя: порядок загрузки расширений — свойство информационной базы, которого нет в файловой выгрузке. Несколько `Перед`/`После` из разных расширений — не коллизия: выполняются все, от порядка загрузки зависит только очерёдность, об этом говорит поле `order_note`.

Одноимённые процедуры разных объектов не конкурируют между собой (с 10.10.2026). Если имя определено в нескольких объектах, а объект в запросе не назван, `effective_definition` возвращает `rule: object_not_specified`, `effective: null` и список `objects` — по одному вердикту на объект (`Документы.РеализацияТоваровУслуг`, `ОбщиеМодули.ЗащитаПерсональныхДанных` и т. д.); у каждого определения в `definitions` указан его `object`. `Вместо` на процедуре одного документа замещает только её, а одноимённая процедура другого документа или общего модуля остаётся действующей и не отмечается как перехватывающая. Чтобы получить один вердикт, сузьте `module_path` до каталога объекта (например, `Documents/РеализацияТоваровУслуг`): объект берётся из этого пути; в `get_method_call_hierarchy` объект задаёт параметр `object_name`.

Вердикт выносится по модулю (с 20.10.2026): одноимённые обработчики разных форм одного объекта не конкурируют, а перехват в форме расширения сравнивается только с обработчиком той же формы основной конфигурации. Если `module_path` называет модуль (например, `Catalogs/Номенклатура/Forms/ФормаЭлемента/Ext/Form/Module.bsl`), `effective_definition` содержит только его определения и поле `module`. Если имя определено в нескольких модулях одного объекта, а модуль не назван, ответ возвращает `rule: module_not_specified` и вердикт на каждый модуль в `objects` (у вердикта и у определений есть `module`). Раньше определения группировались по объекту: действующим могло оказаться определение из другой формы, а перехваты разных форм давали ложную коллизию.

Одноимённые обработчики без аннотаций в разных модулях одного объекта (например, `ПередЗаписью` модуля объекта и двух форм документа) отмечаются как действующие, а не как перехватывающие: перехватывающими считаются только `Перед` и `После` расширений (с 16.10.2026).

### get\_metadata\_details

Возвращает детальную структуру объекта метаданных: реквизиты с типами, табличные части, синонимы и свойства.

| Параметр       | Тип    | По умолчанию | Описание                                                                                                                                                                      |
| -------------- | ------ | ------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `object_name`  | string | —            | Имя или полный путь объекта (`Номенклатура`, `Справочники.Номенклатура`, `Документ.РеализацияТоваровУслуг`)                                                                   |
| `sections`     | string | `""`         | Через запятую: `attributes`, `tabular_parts`, `forms`, `commands`, `properties`, `predefined`, `virtual_tables`, `standard_attributes`; пустое значение возвращает все секции |
| `tabular_part` | string | `""`         | Вернуть только названную табличную часть и её колонки; автоматически включает секцию `tabular_parts`                                                                          |

`tabular_part` позволяет не перелистывать все реквизиты большого документа ради одной табличной части. Неизвестная секция возвращает `sections_invalid`, отсутствующая табличная часть — типизированный ответ `not_found` со списком доступных имён. Курсор привязан к выбранной проекции. `attributes_total` продолжает считать собственные реквизиты объекта даже при проекции, а пустые `forms`, `commands`, `properties`, `predefined`, `based_on`, `print_forms`, `register_movements` и `register_writers` в ответ не добавляются.

**Формы и команды.** Секции `forms` и `commands` перечисляют формы и команды объекта по имени (`name`, `synonym`; с 21.10.2026).

**Что добавляет расширение.** Реквизиты, колонки табличных частей, формы и команды, которые расширение добавляет к заимствованному объекту, перечисляются в его карточке рядом с членами основной конфигурации. У каждого из них есть `origin`: `{"origin_kind": "extension", "origin_id": "ext:<ИмяРасширения>"}`; поле сохраняется и при `detail_level=outline` (с 21.10.2026; раньше добавленное расширением в карточку не попадало). Сама карточка — синоним, тип, свойства, `origin` объекта — остаётся карточкой основной конфигурации. Член, который есть и в основной конфигурации, описывает она, без `origin` расширения. У объекта, который есть только в расширении, `origin` указан один раз — у объекта.

Инкрементальный прогон пишет объект, который создало само расширение, с `origin` этого расширения, а не как объект основной конфигурации. Переименование или удаление файла-описателя снимает карточку старого имени и её реквизиты у той конфигурации, которой файл принадлежал; карточка заимствованного объекта, которую по-прежнему описывает основная конфигурация, остаётся. Соседнее имя, отличающееся только подчёркиванием, не затрагивается (с 26.10.2026). Индекс, который уже держит старую карточку, исправляется следующим инкрементальным прогоном.

**Предопределённые элементы.** Карточка справочника, плана видов характеристик, плана видов расчёта и плана счетов содержит `predefined` — предопределённые элементы из `Ext/Predefined.xml` выгрузки (`item_name`, `item_code`, `item_synonym`, `types`); карточка перечисления — его значения. Секция читается из выгрузки при запросе, на первой странице карточки, и переиндексации не требует (с 16.10.2026; раньше индекс её не хранил, и у карточки, найденной в индексе, `predefined` не было).

**Стандартные реквизиты.** Карточка справочника, документа и регистра содержит блок `standard_attributes` — стандартные поля, которые у объекта действительно есть: `{name, name_en, type}` и, если выгрузка их задаёт, `synonym`, `required` (проверка заполнения), `note`. Состав выводится из свойств объекта, а не из блока `StandardAttributes` выгрузки (он перечисляет и неприменимое): `Код` и `Наименование` — при ненулевой длине, `Владелец` — при заданных владельцах, `Родитель` — у иерархического справочника, `ЭтоГруппа` — при иерархии групп и элементов; `Номер` документа — по его свойствам или нумератору; у регистра сведений `Период` — только у периодического, `Регистратор`, `НомерСтроки`, `Активность` — только при подчинении регистратору; `ВидДвижения` — у регистра накопления вида «Остатки»; `Счет` или `СчетДт`/`СчетКт` — у регистра бухгалтерии по признаку корреспонденции. Планы видов характеристик, счетов, обмена, задачи и бизнес-процессы блока не получают.

**Виртуальные таблицы.** Карточка регистра содержит блок `virtual_tables`: основную таблицу (`table: ""`) и таблицы запроса — `Остатки`, `Обороты`, `ОстаткиИОбороты`, `СрезПервых`, `СрезПоследних`, `ДвиженияССубконто`, `ОборотыДтКт`, `Субконто`, `ФактическийПериодДействия`, `ДанныеГрафика`, `База<ИмяРегистра>`. Каждая таблица — `{table, full_name, parameters, dimensions, resources, attributes, service}`: `full_name` в форме запроса (`РегистрНакопления.Товары.Остатки`), параметры в позиционном порядке, поля — так, как они называются в запросе (`КоличествоОстаток`, `КоличествоПриход`, `СуммаОборотДт`, `ПодразделениеКор`, `Субконто1`). При `detail_level=outline` таблица содержит только `table`, `full_name` и `parameters`. Таблицы, которых у регистра нет, не выводятся: остатки и поля `Приход`/`Расход` — только у регистра накопления вида «Остатки», срезы — только у периодического регистра сведений, `ОборотыДтКт` и поля `Дт`/`Кт`/`Кор` — у регистра бухгалтерии с корреспонденцией (по признаку `Balance` измерения или ресурса), `Субконто1…N` — до `МаксКоличествоСубконто` плана счетов (если плана счетов нет в выгрузке, поле остаётся шаблоном `Субконто<Номер субконто>`), `ФактическийПериодДействия`, `ДанныеГрафика` и `База…` — по периоду действия, графику и базовым планам видов расчёта. Блок `virtual_tables_notes` поясняет, что опущено и почему, и напоминает: параметр `Условие` — один аргумент, несколько условий соединяются через `И`, а не запятой. Поля детализации `ПериодСекунда…ПериодГод` не перечисляются — они есть при указанной периодичности.

Шаблоны таблиц взяты из справки платформы 8.3.27.2130 (только имена). Оба блока строятся из XML-выгрузки при запросе и не требуют переиндексации; они приходят на первой странице карточки. При жёстком `max_chars` бюджет может их опустить (`elided_fields`) — тогда запросите `sections=virtual_tables` или `detail_level=outline`.

Разрешение `object_name`: префикс категории принимается в любом написании (`Справочник.`, `Справочники.`, `Catalog.`, `CatalogRef.`) и ищется по индексу как хранимое множественное; голое имя, общее для нескольких категорий (например, `Начисления` — регистр расчёта и план видов расчёта), возвращает `status: ambiguous` с обоими объектами — уточните префикс; текст, равный синониму объекта («Начисление зарплаты и взносов»), разрешается напрямую; нечёткий поиск по типизированной ссылке ограничен её категорией. Планы видов расчёта (`ПланВидовРасчета.Начисления`) индексируются наравне с остальными категориями.

### codesearch

Поиск по коду модулей объектов, форм и общих модулей. Принимает фрагменты кода, имена функций или комментарии.

| Параметр | Тип    | По умолчанию | Описание                                                 |
| -------- | ------ | ------------ | -------------------------------------------------------- |
| `query`  | string | —            | Код, имя функции, комментарий или описание искомого кода |
| `limit`  | int    | 5            | Количество результатов                                   |

Один модуль занимает на странице не больше `CODE_SEARCH_MAX_PER_MODULE` результатов (по умолчанию 3; `0` снимает ограничение): раньше большой общий модуль с сотнями подходящих процедур заполнял всю выдачу, а механизм основной конфигурации находился только с `origin="base"`. Первый результат такого модуля несёт `module_results_withheld` — сколько его находок не вошло на страницу (с 10.10.2026).

Признак `metadata.is_export` и директива `metadata.directive` фрагмента метода читаются из его объявления: `Экспорт` после скобки многострочного списка параметров учитывается, `&НаСервереБезКонтекста` не сокращается до `НаСервере` (с 16.10.2026). Индекс, построенный раньше, перестраивать не нужно.

Если в гибридном поиске (`metadatasearch`, `codesearch`, `helpsearch`, `search_forms`) отказала одна из двух стадий, ответ даёт другая и говорит об этом: `fallback_reason` = `vector_stage_failed` и `search_layer` = `fulltext`, когда провайдер не вернул эмбеддинг запроса, или `fallback_reason` = `fulltext_stage_failed` и `search_layer` = `vector`, когда отказала полнотекстовая стадия. Ошибкой вызов становится, только если отказали обе. Эмбеддинг запроса ждёт не дольше `EMBEDDING_QUERY_TIMEOUT` и повторяется один раз.

### search\_function

Поиск процедуры или функции BSL по имени. Поддерживает точный поиск с автоматическим переключением на нечёткий, а также префиксный поиск.

Если точный и полнотекстовый поиск не нашли результатов, ответ может содержать до пяти `suggestions`. Каждый вариант содержит каноническое `name`, `module_path`, `origin_id` и `next_call` с именем инструмента и аргументами повторного поиска. Например, запрос `Пересчтать` может предложить `Пересчитать`. Фильтры модуля и происхождения применяются до выбора вариантов; тела процедур для подсказок не читаются.

Это предложения исправить имя: основной `results` остаётся пустым, а счётчики и курсоры относятся только к основным результатам. Подбор ограничен 128 кандидатами из индекса и именами длиной до 128 символов; он не гарантирует исправление любой опечатки. При непустом поиске, чтении по `item_id` и незавершённой индексации подсказки не добавляются. Если они не помещаются в `max_chars`, поле убирается с отметкой в `trimmed.elided_fields`.

| Параметр         | Тип    | По умолчанию | Описание                                                                                                                                                                        |
| ---------------- | ------ | ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `name`           | string | —            | Имя процедуры/функции (`ОбработкаПроведения`, `ПриСозданииНаСервере`)                                                                                                           |
| `exact`          | bool   | `true`       | Точное совпадение (с автоматическим fallback на нечёткий поиск). `false` — префиксный/нечёткий поиск                                                                            |
| `limit`          | int    | 10           | Количество результатов                                                                                                                                                          |
| `include_body`   | bool   | `true`       | Возвращать тело процедуры или функции; при `false` возвращается только сигнатура — объявление до скобки, закрывающей список параметров, одной строкой (не длиннее 500 символов) |
| `max_body_chars` | int    | `0`          | Ограничить длину тела; `0` не ограничивает                                                                                                                                      |
| `module_path`    | string | `""`         | Фильтр по пути модуля до применения лимита                                                                                                                                      |

Успешный ответ структурного индекса несёт `search_layer="structural"`: поиск идёт по SQLite, а при неточном имени — по FTS5. Пока индекс строится, запасной проход по файлам помечается `grep`; сбой полнотекстовой дорожки — `fts5`. Метка `vector+bm25` этому инструменту не принадлежит: векторное хранилище он не запрашивает. Переиндексация не нужна (с 28.10.2026).

Точный поиск и поиск вызывающих в `get_method_call_hierarchy` идут по индексам имён структурного индекса. Индекс, построенный версией до 30.09.2026, сервер переводит на них сам при первом запуске новой версии: перестраивает два индекса на месте, без переиндексации и пересчёта эмбеддингов. На большой конфигурации (миллионы вызовов) с каталогом индекса на пробросе диска Windows это занимает несколько минут; сервер начинает отвечать после перестройки, и контейнер за это время может успеть получить статус `unhealthy`. В журнале перестройку отмечают строки `rebuilding idx_symbols_name …` / `idx_calls_callee … rebuilt with COLLATE NOCASE`. Не перезапускайте контейнер в это время: прерванная перестройка начнётся заново.

### get\_module\_structure

Возвращает полную структуру BSL-модуля: все процедуры, функции, области и статистику. Признак `is_export` и счётчик `stats.total_exports` учитывают `Экспорт` после скобки, закрывающей список параметров, и тогда, когда параметры объявлены на нескольких строках (с 14.10.2026; так же отвечает `search_function`, перестраивать индекс не нужно). Концом процедуры или функции считается и `КонецПроцедуры` с начала строки, и хвост той же строки — `Вызов(...);КонецПроцедуры`; так записаны однострочные обработчики в выгруженных модулях форм. Литерал `"КонецПроцедуры"` внутри строки концом не является.

Директива компиляции `execution_context` различает `НаСервереБезКонтекста` и `НаСервере`, `НаКлиентеНаСервереБезКонтекста` и `НаКлиентеНаСервере` (с 16.10.2026; раньше `&НаСервереБезКонтекста` возвращалась как `НаСервере`). Так же отвечают `search_function`, `compact_symbol` и чтение по `item_id`. В индексе, построенном раньше, директива дочитывается из исходного модуля, перестраивать индекс не нужно.

| Параметр      | Тип    | По умолчанию | Описание                                                     |
| ------------- | ------ | ------------ | ------------------------------------------------------------ |
| `module_path` | string | —            | Путь к BSL-модулю (полный или частичный)                     |
| `origin`      | string | `""`         | `base`, `extension` или `ext:<Имя>`, как у `search_function` |

Один и тот же относительный путь может быть и в основной конфигурации, и в расширении. Без `origin` такой вызов возвращает ошибку и список кандидатов (`module_path`, `origin_kind`, `origin_id`), а не модуль основной конфигурации. Полный путь по-прежнему указывает на один модуль (с 26.10.2026).

### get\_method\_call\_hierarchy

Возвращает иерархию вызовов для BSL-метода: кто вызывает этот метод (callers), что вызывает этот метод (callees), или оба направления.

Процедура, переданная платформе по имени, тоже считается вызванной. Такая связь помечена полем `via`: `notify_description` — `Новый ОписаниеОповещения("Имя", ЭтотОбъект)` (или `ЭтаФорма`, или общий модуль вторым параметром), `idle_handler` — `ПодключитьОбработчикОжидания("Имя", ...)`. `call_line` указывает строку с именем. Если второй параметр `ОписаниеОповещения` — переменная, параметр, путь вида `ЭтотОбъект.ВладелецФормы` или вызов функции, либо имя передано не строкой, связь не строится. У прямых вызовов поля `via` нет. Связи появляются после перестроения структурного индекса, которое сервер выполняет сам при первом запуске новой версии; эмбеддинги при этом не пересчитываются.

**Разрешение вызовов (с 01.11.2026).** Каждый вызов в `callers` и `callees` говорит, какую процедуру он достигает или почему это неизвестно. Словарь общий с Graph:

| Поле                                | Значения                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| ----------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `resolution_status`                 | `resolved` — адресат найден; `unresolved` — адресат не установлен; `nothing_to_resolve` — вызывать в конфигурации некого                                                                                                                                                                                                                                                                                                                                                              |
| `resolution` (при `resolved`)       | `local` — процедура того же модуля (в том числе через `ЭтотОбъект.`/`ЭтаФорма.`); `global_module` — экспорт глобального общего модуля или модуля приложения; `common_module` — `ОбщийМодуль.Метод()`; `object_manager` — `Документы.Заказ.Метод()` и другие коллекции; `borrowed_object` — процедура заимствованного модуля основной конфигурации из модуля расширения; `handler` — обработчик, переданный по имени (`via`). При нескольких подходящих процедурах — `ambiguous: true` |
| `reason` (при `unresolved`)         | `dynamic_name` — `Выполнить`/`Вычислить`, имя в строке; `receiver_unknown` — вызов через переменную или цепочку свойств (`Запрос.Выполнить()`, `Объект.Записать()`); `target_not_found` — процедуры нет; `not_exported` — процедура есть, но без `Экспорт`                                                                                                                                                                                                                            |
| `reason` (при `nothing_to_resolve`) | `platform_global` — глобальный метод платформы (`СтрНайти`); `platform_context` — метод объекта платформы в его модуле (`Закрыть()` в форме, `Записать()` в модуле объекта); `constructor` — `Новый Структура()`                                                                                                                                                                                                                                                                      |

Вызывающий показывается под той процедурой, которую он вызывает: поле `target_module` — модуль этой процедуры. Одноимённые процедуры разных модулей больше не смешиваются, а второй уровень строится от конкретной процедуры-вызывающего, а не от её имени. Вызов через неизвестный получатель с тем же именем (если процедура экспортная) и вызов неэкспортной процедуры не входят в `callers`: они перечислены в `unresolved_candidates` (`count`, до 20 мест в `items`, `omitted` — сколько мест не показано). У вызываемого разрешённого вызова есть `module`; дальше обход идёт только по разрешённым вызовам. Если запрошенное направление пусто, `empty_reason` объясняет почему: `no_calls` — вызовов нет, `unresolved_only` — вызовы есть, но ни один не разрешился, `limit_reached` — исчерпан бюджет или глубина. `call_counts` считает вызовы первого уровня по направлениям — `{"callers": {...}, "callees": {...}}`, в каждом `resolved` (число), `unresolved` и `nothing_to_resolve` (по `reason`); та же форма у Graph. Считается один раз на адресат в процедуре, динамический вызов — по строке; у `callers` в `unresolved` — кандидаты. Если процедуры с таким именем в конфигурации нет (метод платформы), перечисляются все его вызовы с их полями и `root_defined: false`. Поле `call_resolution` — `resolved`; `legacy_index` означает индекс прежней версии, который отвечает по имени, как раньше, до перестроения.

**ВНИМАНИЕ: ПРИ ПЕРВОМ СТАРТЕ ВЕРСИИ ОТ 01.11.2026 (ВЕЧЕР) ОДИН РАЗ ПЕРЕСОБИРАЮТСЯ СТРУКТУРНЫЙ ИНДЕКС, ГРАФ ЗАВИСИМОСТЕЙ И ИНДЕКС ФОРМ** (версия структурного разбора 4 → 5): форму вызова нельзя восстановить из старого индекса. На выгрузке ЗУП (10 185 модулей, индекс на томе Docker) это 8 минут, к модели эмбеддингов не уходит ничего. Пока идёт пересборка, сервер отвечает по прежнему индексу: `/ready` — 200, `get_method_call_hierarchy` — по имени, с `call_resolution: legacy_index`. Векторы кода, метаданных и справки не пересчитываются; векторы сводок форм с неизменённым текстом переносятся. Замеры — в разделе [«Выпуски»](https://docs.onerpa.ru/mcp-servery-1c/vypuski.md).

Пустой `callers` означает отсутствие найденных явных BSL-вызовов и сам по себе не доказывает, что процедура не используется. При завершённом поиске входящих связей с `depth > 0` сервер дополнительно возвращает `declarative_usage`: проверяет, назначена ли процедура обработчиком события конкретной формы. Подтверждённые `bindings` содержат `event`, `handler` и `element`; на уровне `declarative_usage` указаны `source_path` и `next_call` к `inspect_form_layout` с владельцем, именем формы и её `origin`.

Процедуры и функции с модификатором `Асинх`/`Async` (Code от 01.10.2026, вечер) видны `search_function`, `get_module_structure`, `get_method_call_hierarchy` и поиску определений; раньше такие объявления не распознавались. Версия структурного разбора 3 → 4: при первом старте один раз перестраиваются структурный индекс, граф зависимостей и индекс форм; векторы кода, метаданных и справки не пересчитываются.

Статус `found` подтверждает привязку; `not_found` означает, что в проверенной форме привязка не найдена. `ambiguous_symbol` требует уточнить `module_path`: одноимённые процедуры разных форм не объединяются. `symbol_not_found`, `not_form_module` и `form_not_indexed` различают отсутствие символа, иной вид модуля и отсутствие формы в индексе. `indexing_in_progress`, `form_index_unavailable`, `lookup_unavailable` и `lookup_limited` не являются выводом об отсутствии привязок. Читаются максимум 512 записей обработчиков конкретной формы, возвращаются до пяти совпадений; неполный просмотр отмечается `partial=true`.

Привязки платформы не добавляются в `callers` и не меняют его счётчики. При частичном обходе графа, нулевой глубине и направлении `callees` проверка формы не выполняется. Дополнительное поле подчиняется общему бюджету ответа и при необходимости убирается с отметкой в `trimmed.elided_fields`.

| Параметр      | Тип           | По умолчанию | Описание                                                                                                                                                                |
| ------------- | ------------- | ------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `method_name` | string        | —            | Имя процедуры/функции для трассировки                                                                                                                                   |
| `direction`   | string (enum) | `"both"`     | Направление: `callers`, `callees` или `both`                                                                                                                            |
| `depth`       | int           | 3            | Максимальная глубина обхода                                                                                                                                             |
| `max_nodes`   | int           | 2000         | Максимум раскрываемых узлов. Обход идёт по уровням (в ширину): исчерпанный бюджет обрезает самый глубокий уровень, а не прямых вызывающих (с 16.10.2026)                |
| `max_edges`   | int           | 20000        | Максимум обрабатываемых связей                                                                                                                                          |
| `timeout_ms`  | int           | 5000         | Временной бюджет обхода: по его истечении новые запросы не выполняются, а связи, уже найденные последним запросом, возвращаются с `partial=true`; `0` отключает таймаут |
| `module_path` | string        | `""`         | Фильтр начального метода и обхода по пути модуля                                                                                                                        |
| `object_name` | string        | `""`         | Фильтр по объекту конфигурации                                                                                                                                          |

У `get_method_call_hierarchy`, `graph_dependencies` и `compact_call` допустимые значения `direction` перечислены в JSON-схеме MCP (`tools/list`). Значения чувствительны к регистру. Например, `incoming` вместо `callers` отвергается MCP-валидацией до выполнения инструмента с указанием разрешённых вариантов. Если `direction` пропущен, используется значение по умолчанию из таблицы.

### search\_forms

Поиск форм объектов конфигурации (справочников, документов, регистров и т.д.) по имени объекта, имени формы или заголовку.

| Параметр | Тип    | По умолчанию | Описание                                                                             |
| -------- | ------ | ------------ | ------------------------------------------------------------------------------------ |
| `query`  | string | —            | Имя объекта, имя формы или заголовок (`Номенклатура`, `ФормаЭлемента`, `Реализация`) |
| `limit`  | int    | 10           | Количество результатов                                                               |

### inspect\_form\_layout

Возвращает полную структуру формы объекта конфигурации: иерархию элементов с типами и привязками данных, реквизиты формы, команды и обработчики событий.

Для XML-выгрузки Конфигуратора читаются события `Events/Event`: `name` сохраняется как исходное имя события, текст — как имя процедуры. У события вложенного элемента сохраняется ближайший элемент-владелец; у события самой формы `element` пустой. Сохраняется поддержка прежнего `Handler` и формата EDT, повторяющиеся привязки не дублируются.

Для индекса, построенного прежним парсером, эти сведения появятся после штатной переиндексации с новой версией сервера. Версия парсера форм входит в отпечаток поколения: старые данные не считаются результатом нового разбора. Запрос навигации сам переиндексацию не запускает.

**Реквизиты и команды форм, порядок разделов (Code от 01.10.2026, вечер).** Реквизиты (`<Attributes><Attribute>`) и команды (`<Commands><Command>`) форм из выгрузки Конфигуратора индексируются; раньше парсер искал теги, которых в выгрузке нет, и у каждой формы Designer их было ноль. `inspect_form_layout` отдаёт реквизиты, команды и обработчики первыми, дерево элементов — за ними: у большой формы, ответ которой не помещается в бюджет (`RESPONSE_MAX_CHARS`, по умолчанию 32 768 символов), первая страница содержит все реквизиты, команды и обработчики, а элементы продолжаются по `next_cursor`. `get_form_artifact` так же отдаёт реквизиты и команды раньше элементов. Раньше на первой странице большой формы `handlers`, `attributes` и `commands` были пустыми при `truncated: true`. Версия разбора форм 3 → 4: при первом старте структурный индекс, граф зависимостей и индекс форм один раз перестраиваются, описания форм векторизуются заново.

**Тело формы и командная панель (Code от 26.10.2026).** Читаются собственные `ChildItems` формы, а не первый `ChildItems` в документе. Кнопки `AutoCommandBar` (ОК, Отмена) по-прежнему есть в дереве элементов, и рядом с ними — поля самой формы. Раньше при командной панели, записанной выше тела, `inspect_form_layout` и `get_form_artifact` показывали только кнопки панели: реквизиты и обработчики при этом были на месте, а элемента вроде `АдресДоставки` не было. Версия разбора форм 4 → 5: при первом старте один раз перестраиваются структурный индекс, граф зависимостей и индекс форм; векторы кода, метаданных и справки не пересчитываются.

| Параметр      | Тип    | По умолчанию | Описание                                                                                                                                                       |
| ------------- | ------ | ------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `object_name` | string | —            | Имя объекта (`Справочник.Номенклатура`, `Документ.РеализацияТоваровУслуг` или краткое `Номенклатура`); общая форма — `ОбщаяФорма.<Имя>` или `ОбщиеФормы.<Имя>` |
| `form_name`   | string | `""`         | Имя конкретной формы. Пустое значение — форма по умолчанию                                                                                                     |

**Общие формы (Code от 13.10.2026, второй выпуск).** Общие формы (`CommonForms/<Имя>/Ext/Form.xml` выгрузки Конфигуратора, `src/CommonForms/<Имя>/Form.form` проекта EDT, в том числе в расширениях) попадают в индекс форм под именем объекта `ОбщиеФормы.<Имя>` с именем формы `<Имя>`. `inspect_form_layout` находит их по `ОбщаяФорма.<Имя>`, `ОбщиеФормы.<Имя>` или краткому имени, `search_forms` — по имени и заголовку. Раньше индекс форм хранил только формы объектов. Индекс, построенный прежними образами, переиндексации не требует: при первом старте сервер один раз собирает поколение, переносит все файлы как есть и читает только общие формы (в журнале — `The export holds N common form(s) the served form index does not`), эмбеддинги считаются только для их описаний.

### graph\_dependencies

Запрос графа зависимостей объекта конфигурации: какие объекты использует данный объект и кто ссылается на него.

| Параметр      | Тип           | По умолчанию | Описание                                                                       |
| ------------- | ------------- | ------------ | ------------------------------------------------------------------------------ |
| `object_name` | string        | —            | Имя объекта (`Номенклатура` или `Справочники.Номенклатура`)                    |
| `direction`   | string (enum) | `"both"`     | Направление: `forward` (что использует), `reverse` (кто использует) или `both` |
| `limit`       | int           | 50           | Максимальное количество связей на направление                                  |

Пока строится новое поколение индекса, `graph_dependencies`, `search_forms`, `inspect_form_layout`, `bsl_scope_members` и `get_metadata_details` отвечают из опубликованного поколения; `indexing_status: "in_progress"` с пустым ответом бывает только до первой публикации (с 16.10.2026; раньше эти инструменты отвечали так всё время, пока шла фаза индексации кода, а после прогона, продолженного с контрольной точки, — и после него). Связи `default_object_form` / `default_list_form` (`main_form`, `list_form`) ведут к самой форме — `Document.ПересчетТоваров.Form.ФормаДокумента`, а не к объекту-владельцу; общая форма — `CommonForm.<Имя>`.

Инкрементальный прогон дописывает в граф ссылки из изменённых XML-описателей и рёбра `HAS_FORM` объектов, чьи формы или описатели изменились. Первый прогон после обновления читает XML-описатели для графа заново; эмбеддинги при этом не пересчитываются (с 26.10.2026; раньше инкрементальный прогон обновлял только связи из BSL, и новый объект или новая форма оставались вне графа до полной пересборки).

### bsl\_scope\_members

Возвращает доступные методы, свойства и события для заданного BSL-контекста.

Для контекста, который называет объект конфигурации, в `methods` после членов платформенного типа идут экспортные процедуры и функции собственных модулей объекта: модуля менеджера и модуля объекта (у общего модуля — его модуля). Модули форм и команд объекта сюда не входят, неэкспортные методы и методы других модулей с похожими именами — тоже.

Контекстом может быть и тип платформы: `ТаблицаЗначений`, `Запрос`, `Массив`, `ValueTable`, системное перечисление (`ВидДвиженияНакопления` — его значения приходят в `properties` с `kind: "enum_value"`) или тип объекта конфигурации с именем объекта: `СправочникОбъект.Номенклатура`, `СправочникМенеджер.Номенклатура`, `СправочникСсылка.Номенклатура`, `РегистрСведенийНаборЗаписей.Цены`. У такого типа — его собственные члены: `СправочникОбъект.X` получает реквизиты, табличные части и экспорт модуля объекта, `СправочникМенеджер.X` — экспорт модуля менеджера, у ссылки модуля нет. Члены платформы (`source: "platform"`) берутся из синтакс-помощника платформы 8.3.27 — того же `shcntx_ru.hbk`, что у Help: у каждого есть `since` (с какой версии доступен) и краткое описание, у метода — строки синтаксиса `syntax`. Название типа справки возвращается в `platform_type`. Для `Глобальный` по-прежнему отдаётся выборочный список самых частых методов, полный глобальный контекст — в справке.

Контекст, который не называет ни объект конфигурации, ни тип платформы, возвращается без членов, с `resolved_type: null`, `reason: "unknown_context"` и списком близких имён типов в `suggestions` (для `ТаблицаЗначений.Найти` первым будет `ТаблицаЗначений`). С 15.11.2026; раньше любой незнакомый контекст — `ТаблицаЗначений`, `Запрос`, `СправочникОбъект.Сотрудники` — молча считался глобальным контекстом, и ответ содержал `Сообщить` и `ПоказатьПредупреждение`, а члены платформенных типов брались из рукописного списка на 16 типов.

| Параметр      | Тип    | По умолчанию | Описание                                                                                                                                                         |
| ------------- | ------ | ------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `context`     | string | —            | BSL-контекст (`Справочник.Номенклатура`, `Документ.РеализацияТоваровУслуг`, `Глобальный`) или тип платформы (`ТаблицаЗначений`, `СправочникОбъект.Номенклатура`) |
| `member_type` | string | `"all"`      | Фильтр: `all`, `methods`, `properties` или `events`                                                                                                              |

### helpsearch

Поиск по HTML-справке конфигурации. Полезен, когда точное имя объекта метаданных неизвестно.

| Параметр | Тип    | По умолчанию | Описание                                         |
| -------- | ------ | ------------ | ------------------------------------------------ |
| `query`  | string | —            | Описание объекта метаданных или функциональности |
| `limit`  | int    | 5            | Количество результатов                           |

### get\_xsd\_schema

Получение XSD-схемы для типа объекта метаданных или подтипа. Схема генерируется из реальных XML-файлов выгрузки конфигурации. Используйте перед генерацией XML, чтобы знать ожидаемую структуру.

Схема описывает вложенность на любой глубине: состав элемента определяется его именем и именем родителя, поэтому квалификаторы типов, элементы синонимов и вложенные группы форм проверяются так же, как верхние уровни. Порядок и количество дочерних элементов схема не ограничивает.

| Параметр      | Тип    | По умолчанию | Описание                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| ------------- | ------ | ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `object_type` | string | —            | Тип объекта метаданных, по-русски или по-английски: `Справочник`/`Catalog`, `Документ`/`Document`, `РегистрСведений`/`InformationRegister`, `РегистрНакопления`/`AccumulationRegister`, `Роль`/`Role`, `РегламентноеЗадание`/`ScheduledJob` и остальные типы выгрузки Конфигуратора (`ОбщийМодуль`, `Константа`, `Перечисление`, `Отчет`, `Обработка`, `ПланВидовХарактеристик`, `ПланОбмена`, `Подсистема`, `ПодпискаНаСобытие` и др.). Также `Конфигурация` (`Configuration.xml`), подтипы `Форма`, `СКД`, `Макет` и части из каталога `Ext`: `ПраваРоли` (`Rights.xml`), `ПредопределенныеДанные` (`Predefined.xml`), `КомандныйИнтерфейс` (`CommandInterface.xml`), `РасписаниеРегламентногоЗадания` (`Schedule.xml`), `СоставПланаОбмена` (`Content.xml`), `КартаМаршрута` (`Flowchart.xml`) |

### verify\_xml

Валидация XML-содержимого по XSD-схеме для типа метаданных 1С. Возвращает статус и список ошибок: `valid`, `invalid`, `error` (XML не проверен или не разбирается) или `not_found` (неизвестный тип). Схема строится из той же выгрузки, поэтому файл, записанный платформой, проходит проверку со статусом `valid`.

Если XML проверить не по чему, ответ со статусом `error` несёт поле `reason`, а в `errors` написано, что делать:

| `reason`                        | Когда                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| ------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `xsd_pending`                   | Индексация ещё идёт, схемы строит фаза справки после неё; повторите проверку, когда индексация закончится. В ответе также `indexing_status: "in_progress"`                                                                                                                                                                                                                                                                              |
| `xsd_disabled`                  | Генерация схем выключена: `INDEX_HELP=false` или `INDEX_XSD_SCHEMAS=false` (в тексте названа та переменная, что выключена)                                                                                                                                                                                                                                                                                                              |
| `schema_not_generated`          | В выгрузке нет объектов этого типа, например каталога `DataProcessors`, — схему не из чего вывести. Поле `schema` называет файл схемы                                                                                                                                                                                                                                                                                                   |
| `external_object_not_supported` | XML внешней обработки или внешнего отчёта (корень `ExternalDataProcessor` / `ExternalReport`, или `object_type` `ВнешняяОбработка`, `ExternalDataProcessor`, `ВнешнийОтчет`, `ExternalReport`). Внешние объекты не входят в выгрузку конфигурации, схемы для их корневого файла нет. Формы внешней обработки проверяются с `object_type="Форма"`, корневой файл — загрузкой в платформу (`/LoadExternalDataProcessorOrReportFromFiles`) |

Поле `reason` и проверка внешних объектов — с образа 21.11.2026. До него XML внешней обработки с `object_type="Обработка"` получал ошибку «схема не сгенерирована» или ложный `invalid`.

| Параметр      | Тип    | По умолчанию | Описание                           |
| ------------- | ------ | ------------ | ---------------------------------- |
| `xml_content` | string | —            | XML-строка для валидации           |
| `object_type` | string | —            | Те же типы, что у `get_xsd_schema` |

### compact\_search

Поиск по символам и метаданным с единым ограниченным ответом. Идентификаторы из результата можно передать в `compact_symbol` или `compact_metadata`.

| Параметр         | Тип    | По умолчанию | Описание                                                             |
| ---------------- | ------ | ------------ | -------------------------------------------------------------------- |
| `query`          | string | —            | Поисковый запрос                                                     |
| `kinds`          | string | `""`         | `symbol`, `metadata` или оба вида при пустом значении                |
| `cursor`         | string | `""`         | Непрозрачный токен следующей страницы                                |
| `max_items`      | int    | `0`          | Максимум элементов; `0` использует серверный предел                  |
| `max_bytes`      | int    | `0`          | Максимальный размер ответа в байтах; `0` использует серверный предел |
| `max_candidates` | int    | `0`          | Максимум кандидатов для объединения поисковых каналов                |

### compact\_symbol

| Параметр       | Тип    | По умолчанию | Описание                                                                                                                                                                                          |
| -------------- | ------ | ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `name`         | string | `""`         | Имя процедуры или функции                                                                                                                                                                         |
| `module_path`  | string | `""`         | Фильтр по каноническому пути модуля (подстрока). Модули расширений из `EXTENSION_PATHS` тоже находятся — по их пути в поле `module` (с 20.10.2026; раньше любой `module_path` отсекал их целиком) |
| `item_id`      | string | `""`         | Стабильный идентификатор из компактного ответа                                                                                                                                                    |
| `include_body` | bool   | `false`      | Включить тело BSL-символа                                                                                                                                                                         |
| `cursor`       | string | `""`         | Токен следующей страницы                                                                                                                                                                          |
| `max_items`    | int    | `0`          | Максимум элементов                                                                                                                                                                                |
| `max_bytes`    | int    | `0`          | Максимальный размер ответа в байтах                                                                                                                                                               |

### compact\_call

| Параметр                  | Тип           | По умолчанию | Описание                                                                               |
| ------------------------- | ------------- | ------------ | -------------------------------------------------------------------------------------- |
| `symbol`                  | string        | `""`         | Имя начального BSL-символа                                                             |
| `item_id`                 | string        | `""`         | Стабильный идентификатор символа                                                       |
| `direction`               | string (enum) | `"callees"`  | `callees`, `callers` или `both`                                                        |
| `depth`                   | int           | 1            | Глубина обхода                                                                         |
| `module_path`             | string        | `""`         | Фильтр по каноническому пути модуля, как у `compact_symbol`, включая модули расширений |
| `cursor`                  | string        | `""`         | Токен следующей страницы                                                               |
| `max_items` / `max_bytes` | int           | `0`          | Бюджет размера ответа                                                                  |
| `max_nodes` / `max_edges` | int           | `0`          | Бюджет узлов и связей; `0` использует серверный предел                                 |
| `timeout_ms`              | int           | `0`          | Временной бюджет; `0` использует серверный предел                                      |

Связь с обработчиком, переданным по имени, содержит поле `via` с тем же значением, что и в `get_method_call_hierarchy`.

С 01.11.2026 у связи есть поля разрешения `resolution_status`, `resolution` или `reason` и `ambiguous` — те же, что в `get_method_call_hierarchy`. `callee_id` теперь берётся из разрешения конкретного вызова: вызов локальной процедуры получает её идентификатор, даже если процедура с таким именем есть и в других модулях; вызов через переменную — `callee_resolution: unresolved` с `reason: receiver_unknown`, а не идентификатор единственной процедуры с этим именем.

### compact\_metadata

| Параметр                  | Тип    | По умолчанию | Описание                                      |
| ------------------------- | ------ | ------------ | --------------------------------------------- |
| `query`                   | string | `""`         | Поиск объекта метаданных                      |
| `object_type`             | string | `""`         | Фильтр по типу метаданных                     |
| `item_id`                 | string | `""`         | Стабильный идентификатор объекта              |
| `cursor`                  | string | `""`         | Токен следующей страницы                      |
| `max_items` / `max_bytes` | int    | `0`          | Бюджет размера ответа                         |
| `max_members`             | int    | `0`          | Максимум реквизитов и других членов на объект |

Члены объекта идут в порядке чтения: сначала собственные реквизиты, измерения и ресурсы, затем табличные части, затем их колонки, сгруппированные по табличной части. Идентификатор колонки включает имя табличной части (`…:ТабличныеЧасти.Начисления.Сотрудник`), поэтому одноимённые колонки разных частей различимы и по `item_id` возвращается ровно одна.

Все компактные инструменты возвращают общий конверт с `items`, `items_total`, `items_returned`, `truncated`, `next_cursor` и `provenance`. Курсор привязан к состоянию индекса: после переиндексации возвращается `cursor_stale`, а для повреждённого токена — `cursor_invalid`.

### get\_form\_artifact

Читает один артефакт формы конфигурации или один его элемент. Возвращает стабильный идентификатор формы, владельца в канонической форме, имя и вид формы, дерево элементов с именами, типами и вложенностью, объявленные реквизиты и команды, состояние жизненного цикла и запись provenance — откуда и каким маршрутом получен ответ.

| Параметр         | Тип    | По умолчанию | Описание                                                                                                                                                                          |
| ---------------- | ------ | ------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `object_name`    | string | `""`         | Объект-владелец; принимаются обе формы записи (`Документ.ЗаявкаНаРемонт` и `Документы.ЗаявкаНаРемонт`), в идентификаторе всегда возвращается каноническая множественная форма     |
| `form_name`      | string | `""`         | Имя формы                                                                                                                                                                         |
| `artifact_id`    | string | `""`         | Идентификатор из любого инструмента артефактов, в том числе идентификатор элемента (`<project>:form:<object>.<form>:Элементы.<element>`) — тогда возвращается только этот элемент |
| `include_ranges` | bool   | `true`       | Возвращать диапазоны позиций                                                                                                                                                      |
| `operation`      | string | `"read"`     | Зарезервировано; принимается только `read`                                                                                                                                        |
| `max_chars`      | int    | `0`          | Предел размера ответа в символах; `0` — серверный предел 32768 или `RESPONSE_MAX_CHARS`. Форма, которая не помещается, приходит страницами                                        |
| `max_items`      | int    | `0`          | Максимум элементов, реквизитов и команд на странице                                                                                                                               |
| `detail_level`   | string | `""`         | `outline` — элементы без `data_path` и диапазонов                                                                                                                                 |
| `cursor`         | string | `""`         | `next_cursor` предыдущей страницы; элемент, запрошенный по своему идентификатору, возвращается целиком                                                                            |

{% hint style="info" %}
Инструмент только читает. Он не открывает, не отрисовывает и не выполняет форму и никогда не пишет в выгрузку конфигурации.
{% endhint %}

### get\_role\_artifact

Возвращает **объявленные в конфигурации** права роли — либо, в обратном направлении, роли, которые объявляют права на указанный объект.

| Параметр          | Тип    | По умолчанию | Описание                                                                                                                                                                       |
| ----------------- | ------ | ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `role_name`       | string | `""`         | Имя роли                                                                                                                                                                       |
| `artifact_id`     | string | `""`         | Идентификатор артефакта роли                                                                                                                                                   |
| `object_name`     | string | `""`         | Только этот параметр — обратное направление: роли, объявляющие права на объект и его реквизиты                                                                                 |
| `operation`       | string | `"read"`     | Зарезервировано; принимается только `read`                                                                                                                                     |
| `restrictions`    | string | `""`         | `conditions`, `templates` или `all` — вместо списка прав вернуть тексты условий ограничения доступа (RLS) и/или шаблоны ограничений роли                                       |
| `restriction_ref` | string | `""`         | Текст условия одного права по его `restriction_ref`; без `restrictions` означает `conditions`                                                                                  |
| `max_chars`       | int    | `0`          | Размер страницы в символах — и списка прав, и текстов ограничений; `0` — серверный предел 32 768 или `RESPONSE_MAX_CHARS` (от 2 048 до 262 144)                                |
| `cursor`          | string | `""`         | `next_cursor` предыдущей страницы; курсор продолжает тот вид ответа, который его выдал: для текстов ограничений передаётся вместе с теми же `restrictions` и `restriction_ref` |
| `max_items`       | int    | `0`          | Максимум прав (или ролей в обратном направлении) на странице                                                                                                                   |
| `detail_level`    | string | `""`         | `outline` или `full`; у записи права сокращать нечего, поле нужно для единообразия с другими инструментами                                                                     |

С `role_name` или `artifact_id` возвращаются идентификатор, имя, синоним и объявленные права — каждое с объектом метаданных в канонической форме, самим правом и признаком выдачи, с provenance на `Roles/<Name>/Ext/Rights.xml`.

* Право на реквизит, табличную часть, её колонку, измерение, ресурс или команду сохраняет свой путь (`Справочники.Номенклатура.Реквизиты.Вес`, `Документы.Заказ.ТабличныеЧасти.Товары.Реквизиты.Цена`) и `owner_path` — объект-владелец; оно не выдаётся за право на объект.
* У права три состояния: `granted: true` — выдано, `granted: false` — явно запрещено в `Rights.xml`, права нет в списке — роль его не объявляет.
* Выданное право несёт `conditional`: `true` — право ограничено условием (RLS), тогда есть и `restriction_ref`, например `Справочники.ВариантыОтчетов#Read`. Сам текст условия в список прав не входит.
* Права на саму конфигурацию (`MainWindowModeNormal`, `ThinClient`, `AnalyticsSystemClient` и др.) объявлены на `Конфигурация.<Имя>` и входят в список и в `rights_total` (с 16.10.2026).
* `rights_total` — число всех объявленных прав роли; список обрезается на 5 000 записей и листается страницами по `max_chars` с `truncated`, `next_cursor`, `items_total` и `items_returned` — так же в обратном направлении листается список ролей. `restriction_template_names` — имена шаблонов ограничений роли.

С `restrictions` или `restriction_ref` ответ вместо списка прав содержит блок `restrictions` в компактном конверте (`items`, `items_total`, `items_returned`, `truncated`, `next_cursor`): элементы `{kind: "condition", restriction_ref, object_path, right, fields?, text}` и `{kind: "template", name, text}`. Текст длиннее страницы (шаблон БСП бывает в сотни килобайт) продолжается на следующей: `text_offset` — позиция куска, `text_length` — полная длина текста в символах.

{% hint style="warning" %}
Это объявленные права конфигурации, а не эффективные права пользователя, сеанса или профиля: для их вычисления нужна работающая информационная база, которой у сервера нет.
{% endhint %}

### get\_report\_artifact

Возвращает структуру отчёта: стабильный идентификатор и канонический путь, имя и синоним, формы и макеты как ссылки, объявленные реквизиты и табличные части, а при наличии схемы компоновки данных — её расположение вместе с именами наборов данных и полей.

| Параметр       | Тип    | По умолчанию | Описание                                                                                |
| -------------- | ------ | ------------ | --------------------------------------------------------------------------------------- |
| `report_name`  | string | `""`         | Имя отчёта                                                                              |
| `artifact_id`  | string | `""`         | Идентификатор артефакта отчёта                                                          |
| `operation`    | string | `"read"`     | Зарезервировано; принимается только `read`                                              |
| `max_chars`    | int    | `0`          | Предел размера ответа в символах; `0` — серверный предел 32768 или `RESPONSE_MAX_CHARS` |
| `max_items`    | int    | `0`          | Максимум форм, макетов, реквизитов, табличных частей, наборов и полей схемы на странице |
| `detail_level` | string | `""`         | `outline` — без синонимов и путей                                                       |
| `cursor`       | string | `""`         | `next_cursor` предыдущей страницы                                                       |

Ничего не выполняется и результат не компонуется. Если схема есть в выгрузке, но не разобрана этой сборкой, ответ говорит об этом явно, а не опускает поле.

### list\_artifact\_links

Разрешает ссылки артефакта на внешние результаты прогонов и тестов. Обход в обе стороны: по `artifact_id` — результаты, связанные с артефактом; по `result_uri` — артефакты, связанные с результатом. Оба направления обслуживаются одной и той же сохранённой записью.

| Параметр          | Тип    | По умолчанию | Описание                                                  |
| ----------------- | ------ | ------------ | --------------------------------------------------------- |
| `artifact_id`     | string | `""`         | Артефакт, чьи ссылки нужны                                |
| `result_uri`      | string | `""`         | Результат, чьи артефакты нужны                            |
| `expected_digest` | string | `""`         | Ожидаемый content digest; расхождение даёт статус `stale` |
| `operation`       | string | `"read"`     | Зарезервировано; принимается только `read`                |

Каждая ссылка возвращается с вычисленным статусом: `resolved`, `dangling` (артефакт-конец больше не существует), `stale` (`expected_digest` не совпадает с записанным) или `out_of_scope` (конец принадлежит другому проекту). Ссылка, которая больше не разрешается, возвращается **со своим статусом**, а не опускается. Указанный URI никогда не запрашивается, не открывается и не выполняется.

### register\_external\_result\_link

Записывает ссылку на неизменяемый результат, произведённый снаружи — соседним MCP, CI-задачей или другим элементом конвейера. Сервер хранит только *ссылку*: стабильный URI, content digest, производящую систему и время записи. Он никогда не производит, не запускает, не перезапускает, не загружает, не изменяет и не удаляет результат.

| Параметр        | Тип    | По умолчанию | Описание                                                                      |
| --------------- | ------ | ------------ | ----------------------------------------------------------------------------- |
| `artifact_id`   | string | —            | Артефакт, к которому привязывается результат                                  |
| `result_uri`    | string | —            | Стабильный URI результата                                                     |
| `result_digest` | string | —            | Content digest результата; без него ссылка отклоняется с кодом `link_invalid` |
| `producer`      | string | —            | Производящая система                                                          |
| `operation`     | string | `"read"`     | Зарезервировано; принимается только `read`                                    |

Ссылка на артефакт другого проекта отклоняется с кодом `out_of_scope`. Это единственная запись на поверхности артефактов, и она пишет одну строку в собственное хранилище метаданных сервера — никогда в выгрузку конфигурации и никогда в сам результат.

### unpack\_ordinary\_form

Обычная форма в выгрузке Конфигуратора — это `Forms/<Имя>/Ext/Form.bin`, двоичный контейнер, а не XML. Индекс форм и артефактные модели читают `Ext/Form.xml`, которого у обычной формы нет; эта пара инструментов — единственный путь сервера к ней.

Правьте не `Form.bin`, а распакованный рабочий каталог: `payload/` — записи контейнера как есть (только их читает обратная сборка), `decoded/` — производные представления для чтения (`form.json` — раскладка как JSON-совместимые данные, `module.bsl` — модуль формы). Правка производного представления отклоняется сборкой, а не теряется молча.

Дерево раскладки позиционное: оно структурно разбирается, но не именует элементы. Именованные деревья элементов (`*.elem.json`) появляются только при высокоуровневом разборе целого CF/CFE/EPF, где имена даёт окружающая метаданная.

| Параметр         | Тип    | По умолчанию | Описание                                                                                                                                                                          |
| ---------------- | ------ | ------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `form_path`      | string | —            | Абсолютный путь к читаемому `Form.bin`; кириллица допустима                                                                                                                       |
| `workspace_path` | string | —            | Куда развернуть рабочий каталог. Каталог должен быть новым, пустым или ранее записанным этим же инструментом (тогда нужен `overwrite`). Непустой чужой каталог отклоняется всегда |
| `overwrite`      | bool   | `false`      | Заменить существующий рабочий каталог этого контракта                                                                                                                             |
| `include`        | string | `summary`    | Какую ограниченную выдержку вернуть: `summary` (только пути), `structure`, `module` или `all`                                                                                     |
| `max_chars`      | int    | `4000`       | Предел размера каждой выдержки; ограничивается потолком сервера                                                                                                                   |

**Возврат**: полезная нагрузка контракта `ordinary-form/1` — `status`, `entries` (имя, вид, размер, sha256, кодировка, пути записи и производного представления), `source`, `manifest_path` и запрошенные выдержки. Отказ приходит как `status="error"` с `error_code` и подсказкой. Полные производные представления всегда лежат на диске, независимо от того, что попало в ответ.

### build\_ordinary\_form

Записывает рабочий каталог обратно в `Form.bin` и проверяет результат.

Проверка перечитывает записанное тем же кодом, что читает оригинал, и сравнивает **логическую полезную нагрузку** — имена записей, размеры и SHA-256 их байтов. Итоговые двоичные файлы намеренно не сравниваются: записи контейнера несут отметки времени записи, поэтому пересобранный `Form.bin` отличается от исходного побайтно даже когда ничего не менялось. Этот факт сообщает `binary_identical`, а выжила ли форма — говорит `verification.status`.

Записи контейнера всегда пишутся в открытом виде, без Deflate, что бы ни говорил флаг `deflated` в манифесте (он фиксирует, как запись хранилась в исходнике). Платформа читает потоки `form` и `module` отдельного `Form.bin` только как открытый текст UTF-8 с BOM: сжатый поток — «Ошибка формата потока» и аварийное завершение толстого клиента (наблюдалось на 8.3.27.2074). Если исходник хранил записи сжатыми, `unpack_ordinary_form` сообщает об этом в `warnings`, а сборка — в `notes`; логическая полезная нагрузка при этом не меняется.

| Параметр         | Тип    | По умолчанию | Описание                                                               |
| ---------------- | ------ | ------------ | ---------------------------------------------------------------------- |
| `workspace_path` | string | —            | Рабочий каталог, записанный `unpack_ordinary_form`                     |
| `output_path`    | string | —            | Куда записать `Form.bin`. Никогда не заменяется молча                  |
| `overwrite`      | bool   | `false`      | Заменить существующий файл по `output_path`                            |
| `verify`         | bool   | `true`       | Перечитать результат и сравнить полезную нагрузку. Оставьте включённым |

**Возврат**: `output` (путь, размер, sha256), `source` (оригинал, записанный при распаковке), `binary_identical`, `verified`, `verification` (`match` / `mismatch` / `skipped` с хешами по записям) и `changed_entries` — записи полезной нагрузки, изменённые после распаковки. Неудавшаяся сборка оставляет прежний файл на месте.

### reindex

Запуск переиндексации всех настроенных источников данных. Выполняется в фоновом потоке, возвращает статус немедленно.

| Параметр | Тип    | По умолчанию | Описание                                                                                                                                                                                                                                                                                                                                                                                    |
| -------- | ------ | ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `force`  | bool   | `false`      | Если `false` — обновляются только изменённые файлы, а дорожку с несовместимым FTS (`rebuild_required`) прогон восстанавливает из документов, которые в ней сохранены, без разбора исходников и без эмбеддингов. Если `true` и такая дорожка есть, повреждённые дорожки пересобираются из исходников, здоровые переносятся. Если повреждённых нет — полная переиндексация с нуля             |
| `origin` | string | `""`         | Только вместе с `force=true`: `extension` — заново прочитать файлы всех расширений, `ext:<Имя>` — одного расширения. Основная конфигурация и остальные расширения переносятся, как при обычном обновлении, эмбеддинги неизменившегося текста берутся из журнала. Без `force`, со значением `base` и с именем, которого нет среди проиндексированных расширений, вызов отклоняется с ошибкой |

### stats

Состояние сервера одним вызовом. Параметров не принимает. Разделы ответа:

| Раздел                | Что в нём                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| --------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `collections`         | Количество документов по коллекциям (`metadata`, `code`, `help`, `forms`)                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| `embedding_provider`  | Типизированное состояние провайдера эмбеддингов: `provider` (`remote`/`local`), `status` (`ok`, `unreachable`, `unauthorized`, `model_not_found`, `budget_exceeded`, `not_configured`, `unknown`), причина выбора, модель, хост эндпоинта; для локального — бюджет и оценка памяти. Ключ API не содержится ни в каком виде                                                                                                                                                                                  |
| `generation`          | Жизненный цикл поколений индекса: опубликованное поколение и время публикации, состояние каждой дорожки и счётчики `new`/`changed`/`deleted`/`unchanged`, строящееся поколение (`in_flight`), `last_failed` с типизированной причиной, сохранённые для отката (`retained`), удерживаемые читателями (`pinned`), аренда писателя и статус манифеста                                                                                                                                                          |
| `indexing`            | Ход индексации, время последней, статус следующей плановой. `last_outcome` бывает `completed`, `failed`, `cancelled` или `degraded`: `degraded` значит, что прогон завершился, но векторная дорожка не принимает запись (обычно `fts_index_incompatible`). Поиск по опубликованному поколению продолжает отвечать; в `indexing.error` названы дорожки. Следующий обычный прогон восстанавливает такую дорожку из сохранённых в ней документов; если `degraded` остался и после него — `reindex(force=true)` |
| `vector_store_health` | Состояние оптимизации и целостности хранилища по дорожкам, счётчики ошибок записи, признак карантина                                                                                                                                                                                                                                                                                                                                                                                                        |
| `release`             | Идентичность сборки: версия, digest, диапазон поддерживаемых раскладок индекса                                                                                                                                                                                                                                                                                                                                                                                                                              |
| `sessions`            | Границы и счётчики транспортных сессий                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| `stale`               | Есть, только когда опубликованный индекс заведомо отстаёт от исходников: `files` — сколько изменённых файлов он не содержит, `reason` — `build_in_progress` (идёт прогон, который их нашёл), `last_build_failed` или `last_build_cancelled` (прогон их нашёл, но не опубликовал), `index_checked_at` — когда исходники последний раз сверялись с индексом. У свежего индекса раздела нет                                                                                                                    |

Раздел `generation` читается **без аренды писателя**: чтение статистики не блокирует сборку индекса и не блокируется ею.

В `indexing` с 15.11.2026 есть ещё `source_checked_at` — время начала последнего завершившегося прогона, с которого опубликованный индекс совпадал с исходниками (`null`, пока в этом процессе такого прогона не было), и `unindexed_changes` — сколько изменённых файлов нашёл неудавшийся или прерванный прогон (`0` после успешного).

**Устаревшие файлы в ответе.** Сервер не следит за выгрузкой между прогонами индексации (события файловой системы через bind mount ненадёжны), а обходить все файлы на каждый запрос дорого. Поэтому ответ инструмента с бюджетом проверяет только те файлы, на которые сам ссылается (`evidence_path` своих элементов). Если какой-то из них изменён после `index_checked_at`, в ответе появляется `data.stale`: `files`, до 10 путей в `paths`, `index_checked_at` и пояснение. Такие файлы стоит прочитать напрямую: следующий прогон — `reindex()` или плановый раз в `REINDEX_INTERVAL_SEC` — их проиндексирует. Если все файлы ответа старше проверки, поля нет. С 15.11.2026.

***

## Поколения индекса

Индекс неизменяем по поколениям: сборка пишет новое поколение рядом с обслуживающим и становится опубликованной только целиком и только после проверки.

* **Неудавшаяся сборка никогда не публикуется.** Если во время сборки пропал провайдер эмбеддингов, поколение завершается состоянием `failed` с причиной `provider_failure`, указатель публикации продолжает называть прежнее поколение, а инструменты поиска продолжают отвечать из него. Причина видна в `stats().generation.last_failed` — пустой индекс и «успех» в такой ситуации невозможны.
* **Удалённые объекты действительно исчезают.** Объект, пропавший из выгрузки, снимается с обслуживания и при инкрементальном обновлении, и при полной пересборке (`reindex(force=true)`): он не появляется в списках и результатах поиска, а запрос по его идентификатору возвращает типизированный результат `removed` с последней индексной идентичностью, в которой он существовал, — а не «артефакт не найден».
* **Откат возможен.** Прошлые поколения хранятся в количестве `GENERATION_RETENTION_COUNT` и доступны для отката; поколение, которое ещё удерживает читатель, не удаляется.
* **Контрольные точки не переносятся в новое поколение.** Новая сборка копирует уже посчитанные данные предыдущего поколения, но не его отметки «дорожка завершена». Продолжение новой сборки поэтому не публикует предыдущий источник под видом свежего прогона (с 26.10.2026). Отметки, которые записала сама эта сборка, при её продолжении сохраняются.

***

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

ИИ получает инструменты для:

* **Метаданные** — поиск объектов конфигурации, получение детальной структуры реквизитов и типов
* **Код** — семантический поиск по коду, точный поиск функций/процедур, анализ структуры модулей, иерархия вызовов
* **Формы** — поиск форм объектов, получение полной структуры формы (элементы, реквизиты, команды, обработчики)
* **Зависимости** — граф зависимостей между объектами конфигурации
* **BSL-контекст** — доступные методы, свойства и события для контекстов 1С
* **Справка** — поиск по HTML-справке конфигурации
* **XSD и валидация** — генерация XSD-схем из конфигурации и валидация XML

## Примеры использования

* "Какие реквизиты есть у документа РеализацияТоваров?" → `metadatasearch` + `get_metadata_details`
* "Найди все обработки, связанные с печатью" → `metadatasearch`
* "Где в конфигурации используется регистр ОстаткиТоваров?" → `graph_dependencies`
* "Покажи структуру справочника Номенклатура" → `get_metadata_details`
* "Найди функцию ОбработкаПроведения" → `search_function`
* "Покажи иерархию вызовов метода РассчитатьСумму" → `get_method_call_hierarchy`
* "Какие формы есть у документа Реализация?" → `search_forms`
* "Покажи структуру формы элемента Номенклатуры" → `inspect_form_layout`
* "Какие методы доступны у объекта Справочник.Номенклатура?" → `bsl_scope_members`
* "Получи XSD-схему для справочника" → `get_xsd_schema`
* "Проверь этот XML на соответствие схеме документа" → `verify_xml`

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

* Docker Engine или Docker Desktop с поддержкой Linux-контейнеров
* Лицензионный ключ
* Embedding модель (LM Studio или CPU)
* **Выгрузка конфигурации** из Конфигуратора

## Порт

**8000**

MCP endpoint: `/mcp`. По умолчанию используется `streamable-http`; для SSE установите `USESSE=true`. `/live` проверяет процесс и транспорт, `/ready` — готовность обязательных индексов и embedding-провайдера. `/health` временно сохранён как устаревший алиас `/live`. Успешные ответы на `/live`, `/ready` и `/health` (статус ниже 400) не пишутся в access-лог; проба с ответом 400 и выше и каждый запрос к `/mcp` пишутся как раньше.

## Образ Docker

```
comol/1c_code_metadata_mcp:latest
```

### Варианты образа

| Тег      | Архитектура | Размер             | Описание                                                                                   |
| -------- | ----------- | ------------------ | ------------------------------------------------------------------------------------------ |
| `latest` | amd64       | \~2.9 GB           | Полная версия с PyTorch (локальные embedding + API)                                        |
| `light`  | amd64       | \~290 MB           | Без PyTorch (embedding только через API — LM Studio, OpenRouter и т.д.)                    |
| `arm64`  | arm64       | \~1.45 GB (сжатый) | Для Apple Silicon / ARM серверов: PyTorch CPU, без CUDA (локальные embedding на CPU + API) |

{% hint style="info" %}
Используйте `light`, если embedding модель работает через внешний API (LM Studio, OpenRouter). Образ в 10 раз легче. См. [Теги и ключи образов](https://docs.onerpa.ru/mcp-servery-1c/kanaly-obrazov.md).
{% endhint %}

## Подготовка данных

Требуется один основной источник:

1. **Designer XML-выгрузка в файлы** из Конфигуратора (рекомендуется), либо проект **1C:EDT**.
2. Текстовый отчёт по метаданным нужен только для совместимого режима `METADATA_SOURCE=report`.

Подробнее: [Подготовка данных](https://docs.onerpa.ru/mcp-servery-1c/servery/code-metadata-search/podgotovka-dannyh.md)

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

```powershell
docker run -d -p 8000:8000 `
  --name 1c_code_metadata_mcp `
  -e LICENSE_KEY=YOUR_LICENSE_KEY `
  -e CODE_PATH="/app/code" `
  -e METADATA_SOURCE=xml `
  -e SOURCE_FORMAT=auto `
  -v "E:/1C_Export/Files:/app/code" `
  -v "E:/bases/mcp_codemetadata:/app/chroma_db" `
  comol/1c_code_metadata_mcp:latest
```

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

```json
{
  "mcpServers": {
    "1c-code-metadata-mcp": {
      "url": "http://localhost:8000/mcp",
      "connection_id": "1c_metadata_service_001"
    }
  }
}
```

## Дополнительно: rlm-tools-bsl (RLM-подход)

CodeMetadataSearchServer использует RAG-подход — предварительно индексирует код и метаданные для семантического поиска. Для дополнительного анализа без предварительной индексации можно использовать [rlm-tools-bsl](https://github.com/Dach-Coin/rlm-tools-bsl) — MCP-сервер для токен-эффективного анализа кодовых баз 1С (BSL).

|                        | CodeMetadataSearchServer (RAG)                  | rlm-tools-bsl (RLM)                   |
| ---------------------- | ----------------------------------------------- | ------------------------------------- |
| **Подход**             | Предварительная индексация, семантический поиск | Анализ файлов на лету, без индексации |
| **Время старта**       | Часы на индексацию                              | 0 секунд                              |
| **Качество поиска**    | Высокое (эмбеддинги + BM25 + реранкер)          | Высокое (для точечных запросов)       |
| **Экономия контекста** | Чанки релевантного кода                         | До 95% за счёт серверных хелперов     |
| **Инфраструктура**     | Docker + embedding модель                       | pip install (Python 3.10+)            |

{% hint style="success" %}
Лучший результат достигается при совместном использовании обоих подходов: CodeMetadataSearchServer для семантического поиска и навигации по архитектуре, rlm-tools-bsl для быстрого точечного анализа кода и экономии контекста.
{% endhint %}

## Структура раздела

* [Установка](https://docs.onerpa.ru/mcp-servery-1c/servery/code-metadata-search/ustanovka.md) — команды запуска
* [Подготовка данных](https://docs.onerpa.ru/mcp-servery-1c/servery/code-metadata-search/podgotovka-dannyh.md) — выгрузка из Конфигуратора
* [Конфигурация](https://docs.onerpa.ru/mcp-servery-1c/servery/code-metadata-search/konfiguraciya.md) — все параметры

## Доработка

Сервер поддерживает [систему плагинов](https://docs.onerpa.ru/mcp-servery-1c/sistema-pluginov.md): каталог `/app/plugins` (`PLUGIN_DIR`) читается при каждом старте, отдельного флага включения нет. Доступны хуки `on_startup`, `on_request`, `on_search_candidates`, `on_result` (call-scoped), `on_source_file`, `on_chunk`, `on_metadata_object` (derived-state) и таблицы `QUERY_ALIASES`, `TOOL_PRESETS`. Текущее состояние показывает `plugin_state`, перечитывает каталог `plugin_reload`.

Полный справочник контракта лежит в образе: `/app/src/plugin_api.py`, короткая версия — `/app/plugins/AGENTS.md`, закомментированный пример со всеми хуками — `/app/plugins/example.py`. Проверить плагин без сборки индекса и запуска сервера: `python src/plugin_dry_run.py plugins/10_my_plugin.py`.

Без плагинов сервер настраивается составом индексируемых данных и параметрами поиска — см. [Конфигурация](https://docs.onerpa.ru/mcp-servery-1c/servery/code-metadata-search/konfiguraciya.md).
