---
name: ai-edt-tools
description: "EDT-based 1C:Enterprise (1С:Предприятие 8.3+) development via the EDT MCP server - BSL code analysis and editing, metadata inspection and construction, module navigation, query validation, managed forms, error checking, debugging, infobase update. Use when the project is an EDT workspace: 1C/BSL modules, .mdo metadata, 1C queries, managed forms. Not for 1C 7.7 (.1s/.ert/1Cv7.MD) and not for Configurator-format sources without an EDT project - those have their own skills."
---

# AI-EDT MCP Tools

MCP-сервер **ai-edt** дает прямой доступ к семантическому индексу EDT (BM model), платформенной
документации, проверкам, отладке и конструкторам метаданных. Работает через живой экземпляр EDT. Semantic-
операции (ссылки, определения, иерархия вызовов, структура модуля) идут по BM-модели и AST, а не по
текстовому совпадению; текстовый и regex-поиск в каталоге тоже есть (`code_search operation=text_search`).

Каталог инструментов вынесен в `references/` - читай нужный файл по ситуации, а не весь набор.

> **Навык написан под [AI-EDT](https://github.com/Desko77/ai-edt)** - MCP-сервер работает плагином
> внутри запущенной 1C:EDT (update site: https://desko77.github.io/ai-edt/). Весь каталог в
> `references/` описывает именно его: больше сотни операций, свернутых в **фасады** с маршрутизацией
> через `operation=`.
>
> Если подключен ДРУГОЙ MCP-плагин для EDT, этот каталог к нему неприменим: там свой набор
> инструментов, свои имена и фасадов может не быть вовсе - вызов вида
> `diagnostics operation=get_project_errors` вернет ошибку. Ключ сервера тоже свой. Порядок в этом
> случае: взять фактические имена из `tools/list` сессии и работать по документации своего плагина;
> общие принципы навыка (что проверять после правки, чего не подменять ручной правкой файлов)
> остаются в силе.

## When to Use

- Анализ и правка BSL: модули, методы, ссылки, вызовы, рефакторинг.
- Метаданные: чтение, создание, изменение, удаление, переименование с каскадом.
- Формы: структура, скриншот из WYSIWYG-редактора, правка без ручного XML.
- Запросы 1С: валидация синтаксиса и семантики до запуска.
- Ошибки проекта, обновление ИБ, юнит-тесты YAxUnit, отладка и профилирование.

Для BSL и метаданных 1С этот сервер приоритетнее Grep/Read и точнее любого текстового поиска.

## Когда НЕ использовать

- **1С 7.7** (`.1s`, `.ert`, `1Cv7.MD`) - скил `1c77-dev` и сервер `1c77-metadata`: инструменты EDT к 7.7
  неприменимы.
- **Обычные (неуправляемые) формы и проект в формате Конфигуратора без EDT-проекта** - каталог рассчитан на
  управляемые формы и EDT-модель; для XML-выгрузки Конфигуратора есть отдельные скилы `1c-*` (cf/epf/erf).
- **Данные живой базы вне отладочной сессии** - скил `1c-mcp-toolkit` по HTTP.
- **EDT не запущена** - инструменты недоступны; сообщить пользователю, а не переходить на ручную правку
  файлов проекта.

## Prerequisites

`get_edt_version` - проба. Не ответил - корректный вывод "ai-edt недоступен", а НЕ "EDT не запущена": та же
картина бывает при недоступном MCP-сервере, зависшей очереди вызовов и несовместимом плагине. При ошибке
связи или timeout `self_status` НЕ вызывать - он на том же сервере; он полезен только когда сервер отвечает,
но операция не проходит. Разбор случаев и что делать в каждом - `rules/mcp-tool-priority.md`, раздел "Когда
инструменты недоступны". Коротко: анализировать без MCP можно, писать в проект вслепую - нельзя.

## Ключевые фасады - точки входа

Фасад заменяет набор родственных standalone-инструментов: одна точка входа, действие выбирается параметром
`operation` (у отладчика - `action`). У большинства есть встроенная справка: `operation=help`, детали
конкретной операции - `operation=help topic=<операция>`.

| Фасад | Когда брать |
|---|---|
| `code_search` | исследовать код и модель: поиск, ссылки, определения, иерархия вызовов, символы. Только чтение |
| `edit_metadata` | создавать и менять метаданные и формы; массовые правки - `batch=true` |
| `diagnostics` | ошибки проекта, сводки, перевалидация, проверка перед экспортом |
| `launch_debugger` | отладка целиком: запуск и attach, точки останова, шаги, переменные, evaluate, профилирование |
| `project_admin` | проекты, конфигурации, подсистемы, resync на диск, перезапуск EDT |
| `infobase_admin` | ИБ и запуск: приложения, создание и удаление ИБ, учетные данные, обновление, `sync_control` |
| `config_io` | импорт и экспорт конфигурации и отдельных артефактов |
| `insights` | метрики, графы зависимостей, сравнение конфигураций, анализ влияния |
| `security_audit` | роли, RLS, чувствительные данные |
| `docs_lookup` | документация платформы и встроенная справка объектов |
| `workspace_marks` | теги, объекты по тегам, закладки, задачи |
| `yaxunit_tests` | юнит-тесты YAxUnit |

**Данных информационной базы у плагина нет.** `browse_data`, `execute_query` и фасад `data_access` из него
удалены - звать их бесполезно. Запрос или чтение данных живой базы - скил `1c-mcp-toolkit` (обработка по HTTP). Отладка отдает только состояние исполнения текущего кадра
(`get_variables`, `evaluate_expression`), а не таблицы базы.

Состав операций каждого фасада - `references/facades.md`, здесь только маршрут: перечни операций намеренно
не дублируются, иначе два списка расходятся.

Не фасады, вызываются напрямую: `vanessa` (сценарии Vanessa Automation - в каталоге описана одной строкой,
параметры уточнять встроенной справкой сервера), `self_status`, конструкторы `dcs_workshop` (СКД),
`mxl_workshop` (табличные документы), `xdto_workshop` (XDTO-пакеты), `extension_workshop` (расширения и
заимствование), `external_object_workshop` (внешние обработки и отчеты), `external_data_source_workshop`.

Часть standalone-инструментов поглощена фасадами и остается backward-compat алиасами (примеры):
`get_project_errors` / `clean_project` / `revalidate_objects` -> `diagnostics`; `debug_launch` /
`set_breakpoint` / `step` / `resume` -> `launch_debugger`; `get_tags` / `get_objects_by_tags` /
`get_bookmarks` / `get_tasks` -> `workspace_marks`.

**Под пресетом Canonical поглощенные имена скрыты из `tools/list`** (оставаясь вызываемыми), поэтому
канонический вызов - через фасад: `diagnostics operation=get_project_errors`, `launch_debugger action=launch`.
Ниже и в references имена операций пишутся короткой формой для узнаваемости.

Поглощены НЕ все. Самостоятельными остаются, в частности, `write_module_source`, `validate_query`,
`get_edt_version`, `read_module_source`, `read_method_source`, `get_module_structure`, `list_modules`,
`ai_context`, `diff_module`, `get_form_structure`, `get_form_screenshot`, `code_review`. Список не
исчерпывающий - сверяться с `tools/list` и `references/facades.md`. Записи BSL в `code_search` нет вовсе:
он только читает.

## Навигация по references

| Нужно | Файл |
|---|---|
| Что за фасад, какие операции, режим доступа (чтение / изменение / опасно) | `references/facades.md` |
| Чтение и навигация по BSL, структура модулей, поиск, запись кода | `references/code-and-model.md` |
| Создание и правка метаданных, формы, макеты, конструкторы | `references/metadata-forms-constructors.md` |
| ИБ, запуск, обновление, отладка, профилирование, тесты | `references/infobase-debug-tests.md` |
| Ошибки проекта, валидация, метрики, графы, безопасность | `references/diagnostics-analysis-security.md` |
| Проект и воркспейс, метки, задачи, композитные агентские инструменты, пресеты видимости | `references/project-tags-agent-helpers.md` |
| Готовый порядок вызовов под конкретную задачу | `references/workflows.md` |
| Теги ошибок, троттлинг, грабли, большие конфигурации, sync_control | `references/gotchas-and-errors.md` |

Каталог в `references/` - снимок docs AI-EDT на ревизии `4fb31770` (28.07.2026), 118 имен сверены с
реестром групп `ToolCategory.java`. **Снимок отстает от рабочего дерева форка**: там уже появляются
инструменты, которых нет ни в реестре групп, ни в docs (например `find_dead_code`), а число 118 полноты не
доказывает.

Инструмент не нашелся в каталоге - не считать, что его нет, и не уходить в ручной обход. Порядок поиска:
`tools/list` текущей сессии (там актуальный набор с учетом пресета) -> `operation=help` у профильного фасада
(каталог операций) -> `edit_metadata operation=help topic=availability` (что доступно на этом runtime).
`self_status` для этого НЕ годится: он показывает состояние сервера, служб EDT и очереди, а не каталог
инструментов. Каталог устарел - пересобрать снимок из docs проекта, а не дописывать по памяти: именно так в
скил попадали инструменты из старых версий.

## Критические запреты и проверки

Полный список обязательных проверок с лимитами - `rules/mcp-tool-priority.md`, раздел "Обязательные
проверки" (единственный источник). Здесь только то, без чего скил применять нельзя.

1. **BSL пишется через `write_module_source`**, а не Edit/Write по `.bsl`: иначе EDT не увидит правку до
   refresh, теряется авто-валидация и подсчет строк. Перед первой записью в модуль -
   `rules/edt-bsl-write-safety.md`: там безопасные режимы (`replaceMethod`, `replaceLines` с
   `expectedText`, вставки `insertBefore` / `insertAfter`) и почему голый `replace` затирает модуль.
2. **Формы правятся form-операциями `edit_metadata`**, а не ручным XML в `.form`.
3. **`validate_query` после каждого написанного или измененного запроса**, не копя до конца; для СКД -
   `dcsMode=true`.
4. **`validate_for_export` перед любой записью конфигурации в ИБ и перед сборкой артефактов**, включая
   неявную запись у `yaxunit_tests`. Findings блокируют операцию.

Остальные обязательные проверки (`ask_1c_ai` с обязательной верификацией его замечаний, порядок
`revalidate_objects` -> `get_project_errors`, лимиты итераций, поведение при отказе сервера) не
перечисляются здесь во избежание расхождений - они в `rules/mcp-tool-priority.md`, раздел "Обязательные
проверки", пункты 1-6.

## Экономия контекста

- `ai_context` с `target=<FQN>` и `depth=standard` - один вызов вместо metadata + modules + structure.
- `get_module_structure` -> `read_method_source` вместо чтения модуля целиком: работает и на модулях 25k+
  строк, отдает точные границы методов дешево по токенам.
- Крупные карты (`list_modules`, каталог FQN, структура большого модуля) кэшировать один раз в
  gitignored-файл проекта, а не перезапрашивать.
- Тяжелые выборки уводить в субагента, чтобы сырье не оседало в основном контексте. Детали и запреты -
  `references/gotchas-and-errors.md`.

## Обработка ошибок

Не ретраить вслепую: сигналы `Pending`/`runKey`, `propertyMismatch`, `requiresCascadeForms`,
`*ApiNotFound`, `BSL model is not available` требуют разных действий. Полная таблица - 
`references/gotchas-and-errors.md`. Лимиты повторов и правило остановки (сменить подход, а не бросить
задачу) заданы в `rules/mcp-tool-priority.md`, раздел "Троттлинг и ошибки" - там единственный источник.