Mcp Code Index

---
name: mcp-code-index
description: "Работа с индексом исходников 1С через MCP-сервер code-index: где в конфигурации и расширениях реализован функционал, кто вызывает процедуру и что вызывает она, цепочка и дерево вызовов, карта влияния перед изменением объекта — что ссылается на него в метаданных, коде и правах ролей, регистраторы регистра и движения документа, состав объекта со всеми расширениями, обработчики форм, подписки на события, права ролей, подсчёты по метаданным, перехватчики расширений. Используй, когда в сессии есть инструменты сервера code-index и задача звучит как «найди, где это сделано», «кто использует», «что затронет изменение», «сколько объектов», «покажи структуру объекта». Не для данных базы и применённого состояния метаданных и не для правки исходников. Здесь же ловушки индекса и подключение проекта."
---

# Работа с индексом исходников через MCP-сервер `code-index`

Описание и схема каждого инструмента приходят вместе с ним и сами говорят, когда его брать и как
дешевле — не копируй их отсюда. Нормы (приоритет, `repo`, проверка свежести, только чтение) —
в `.claude/rules/mcp.md`, секция «Сервер индекса исходников». Здесь — порядок типовых
исследований 1С, чего индекс не знает, и ловушки, которых из схем не видно.

## Что индекс знает и чего нет

Знает: тексты модулей BSL всех наборов из `src` (основная конфигурация и каждое расширение
в одном графе, модули расширений помечены `extension_name`); граф вызовов процедур; структуру
объектов, обработчики форм, подписки на события, состав движений, права ролей, связи по ссылочным
реквизитам — разобранные из XML метаданных.

Не знает: XML объектов как текст (структура — только через `get_object_structure`, искать XML
через `list_files`/`grep_text` бесполезно); компоновку форм, табличные макеты и настройки
вариантов СКД (саму схему СКД знает — `get_dcs_schema`); применённое состояние базы
(за ним — сервер базы). Индекс отвечает «где написано», не «что работает».

## Порядок типовых исследований

Снято с `tools/list` сервера; выпуски добавляют инструменты, полный перечень — в самом
`tools/list`. Вопрос → с чего начать → чем продолжить.

| Вопрос | Инструмент | Продолжение |
|---|---|---|
| Где реализован функционал X (точного имени нет) | `search_terms` — по словам, синонимам и комментариям | `get_function` по `proc_key` |
| Где определена процедура с известным именем | `find_symbol` (локации) или `get_function` (тело) | неуникальное имя — `path_glob` |
| Поиск по словам в именах функций | `search_function` | `get_function` |
| Строка или regex в коде | `grep_body` — показывает, в какой процедуре; `grep_code` — весь файл, включая `Перем` и литералы вне процедур | всегда с `path_glob` или `language` |
| Кто вызывает / что вызывает | `get_callers`, `get_callees` — весь список одним вызовом | цепочка — `find_path_bsl`, дерево — `get_call_tree` |
| Есть ли путь от A до B, через что | `find_path_bsl` (учитывает вид вызова); универсальный `find_path` | не собирай цепочку вручную |
| Дерево вызовов на N уровней | `get_call_tree` (`direction`: `callers`/`callees`) | сужай `max_depth`, `max_nodes` |
| Что затронет изменение объекта — карта влияния | `find_references` — реквизиты других объектов, обращения в коде, права ролей одним ответом | `get_data_links` `depth=1` за счётчиками по видам связи |
| Регистраторы регистра, движения документа | `get_register_writers` — оба направления одним вызовом | код проведения — `get_function` |
| Путь по данным между двумя объектами | `find_data_path` | — |
| Обзор объекта: реквизиты, формы, модули, связи | `get_object_profile` — счётчики и перечни | `sections=[…]` удешевляет |
| Полная структура объекта с типами, предопределённые, свойства | `get_object_structure` | применённое состояние — сервер базы (`mcp.md`) |
| Обработчики формы и её элементов | `get_form_handlers` (`owner_full_name`, без `form_name` — все формы) | `element` сужает |
| Подписки на событие | `get_event_subscriptions` (`event`, `source`, `handler_module`) | — |
| Схема отчёта на СКД: наборы, поля, параметры, итоги, какие объекты читает запрос | `get_dcs_schema` (макет, владелец или общий макет; `sections` сужает, `include_query=false` — только длины запросов) | настройки вариантов (группировки, отборы) не разобраны — `read_file` по `content_file` |
| Права ролей на объект / что разрешено роли | `get_role_rights` (`object` либо `role`) | срез сложнее — `bsl_sql` по `role_rights` |
| Сколько / какие / у кого — подсчёт, фильтр, join | `bsl_sql` (`SELECT`/`WITH`) | таблицы — в описании инструмента |
| Перехватчики расширений над методом | `bsl_sql`: `functions.override_type`, `override_target` | либо `grep_code` с `path_glob` каталога расширения |
| Оглавление большого модуля без тел | `get_file_summary` | тело — `get_function` или `read_file` по строкам |
| Фрагмент файла по пути | `read_file` (`line_start`/`line_end`) | oversize — `get_function`/`grep_body` |
| Список файлов, метаданные файла | `list_files`, `stat_file` | — |
| Текстовые файлы (md, yaml, json) | `search_text`, `grep_text` | — |
| Живость и состав индекса | `health` (все репо), `get_stats` (`repo` или все) | — |
| Классы, импорты (не про 1С) | `search_class`, `get_class`, `get_imports` | — |

## Паттерн: карта влияния перед правкой объекта

1. `find_references` по каноническому имени — `Document.РеализацияТоваровУслуг`,
   `Catalog.Контрагенты`, `AccumulationRegister.ТоварыНаСкладах`. Три секции: `data_refs`,
   `code_usages`, `role_rights`; у каждой `total` — сначала смотри счётчики, потом примеры.
2. Для документа и регистра — `get_register_writers`: состав движений декларативный, точнее
   разбора кода проведения.
3. Вглубь по данным — `get_data_links` с `depth=1` и одним направлением; страницы листай
   только когда счётчики по видам связи не ответили на вопрос.
4. Перехватчики расширений над затронутыми методами — по паттерну ниже. Норма о полноте
   анализа расширений — `1c-rules.md` (### Архитектура).

## Паттерн: перехватчики расширений

Один запрос вместо обхода каталогов:

```sql
SELECT f.name, f.override_type, f.override_target, fl.path
FROM functions f JOIN files fl ON fl.id = f.file_id
WHERE f.override_type IS NOT NULL AND f.override_target = 'ИмяМетода'
```

Путь в ответе начинается с каталога набора (`cfe_<Имя>/…`) — так видно, какое расширение
перехватывает. Перехват обработчика события формы описан не директивой в модуле, а секцией
`Events` в `Form.xml` расширения — его индекс не покажет, читай форму по `mcp.md` п. 3 протокола.

## Сужение одним набором

`path_glob` — по первому сегменту пути: `cfe_Имя/**` — одно расширение, `cf/**` — основная
конфигурация, `{cf,cfe_Имя}/**` — вместе. В таблицах метаданных объекты расширений помечены
`extension_name`. Имена объектов: для инструментов метаданных — `<MetaType>.<Имя>` в единственном
числе (`Document.ЗаказКлиента`); в таблицах `bsl_sql` папка во множественном (`Documents.ЗаказКлиента`).

## Ловушки

- **Ноль без `ready` ничего не доказывает.** После `build_dump`, переключения ветки или массовой
  замены исходников демон догоняет изменения: `health` показывает `initial_indexing`,
  `reindexing_batch` или `reindexing_extras` — дождись `ready`, потом делай выводы. Норма — `mcp.md`.
- **`ready` ещё не значит «всё собрано».** Полнотекст и данные 1С досчитываются после:
  ответ `{"status":"indexing","layer":"fts"}` или `"layer":"extras"` — повтори вызов позже,
  это не «ничего не найдено».
- **Распространённое имя даёт обрезанный ответ** (`truncated`): стандартные обработчики
  (`ПередЗаписью`, `ОбработкаПроведения`) есть у сотен объектов — сразу задавай `path_glob`.
- **`get_callees` без `callee_path`** у записи означает, что имя носят несколько процедур:
  спроси их одним `grep_code` с перечислением через `|`, а не вызовом на каждое имя.
- **`grep_code`/`grep_text` без `path_glob` или `language`** — полное сканирование, дорого.
- **`bsl_sql`:** `lower()` в SQLite не переводит кириллицу — фильтруй по `object_ref_key`
  (уже в нижнем регистре) или по точному `object_ref`; колонка `repo` во всех таблицах равна
  `default`, фильтровать по ней не нужно; blob-колонки приходят как `{_blob_bytes: N}` — текст
  бери через `get_function`/`read_file`.
- **Добавили репозиторий в `daemon.toml` — `serve` его не видит**: `daemon reload`
  демон принимает, а список репо у `serve` перечитывается только при старте. Признак —
  `unknown_repo` на новый алиас при живом демоне. Перезапусти только процесс `serve`, демон
  не трогай — он индексирует другие проекты; подробности — `/setup-code-index`.
- **Claude Code не подхватывает `tools/list_changed`**: после подключения нового репозитория
  инструменты появятся после `/mcp` → `Reconnect` или перезапуска сессии.
- **Oversize-модуль** `read_file` не отдаёт (`oversize=true`): бери `get_function`, `grep_body`,
  `get_file_summary`.

## Подключение

Один демон на машину индексирует все проекты; MCP-сервер `serve` отдаёт их по HTTP
(`http://127.0.0.1:8011/mcp`, запись `code-index` в `.mcp.json`), репозиторий выбирается
параметром `repo`. Установка на машину и подключение проекта — команда `/setup-code-index`:
она ставит индексатор штатным установщиком, регистрирует `src` проекта в демоне, задаёт
исключения (эталон поставщика в индекс не попадает) и заполняет секцию «Индекс исходников
(code-index)» паспорта. Режим stdio (`npx -y @regsorm/code-index-mcp serve --path src`)
не путь шаблона: ему нужны тот же демон и та же запись в `daemon.toml`, без них он отвечает
`daemon_offline`, а пакет npm содержит сборку без инструментов 1С.