Все статьи

10 октября 2026 г.

Автоматическая документация модулей 1С с MCP и ИИ: практический гайд с Grafon

Почему документация модулей 1С плохо поддается ИИ

Типовая конфигурация 1С — это не «несколько файлов». ERP, УТ, ЗУП, КА содержат гигабайты XML-метаданных, сотни тысяч строк BSL, тысячи форм, подписок, общих модулей и запросов. Если попытаться скормить агенту Claude Code, Cursor или Windsurf всю выгрузку сразу, происходит предсказуемое:

  • контекстное окно переполняется;
  • агент тратит 10x токенов на нерелевантные модули;
  • теряются связи между процедурами;
  • появляются галлюцинации: выдуманные методы, несуществующие реквизиты, ложные вызовы;
  • документация быстро устаревает, потому что ее нельзя перегенерировать точечно.

Например, объектный модуль документа «РеализацияТоваровУслуг» может содержать 8–12 тысяч строк. Плюс вызовы общих модулей, подписки, формы, движения. Без графа зависимостей ИИ видит фрагмент, но не понимает, что именно вызывает ОбработкаПроведения и какие данные меняются.

Что такое MCP и зачем здесь Графон

MCP (Model Context Protocol) — открытый протокол, который позволяет ИИ-агенту вызывать внешние инструменты. Вместо того чтобы «заливать» всю конфигурацию в промпт, агент делает MCP-запрос: «дай карточку объекта», «покажи граф вызовов», «верни сигнатуры процедур».

Графон — локальный инструмент и MCP-сервер для 1С. Он анализирует XML-выгрузку и BSL, строит граф зависимостей метаданных, функций, процедур, подписок на события и запросов. Агент через MCP получает только точный срез связанных файлов. Это сокращает потребление токенов до 10 раз и убирает галлюцинации, потому что каждый факт берется из графа, а не из «памяти» модели.

Архитектура решения

Выгрузка 1С (XML + BSL)
        |
        v
Парсер Grafon: метаданные, модули, формы, запросы
        |
        v
Граф зависимостей: объекты, вызовы, подписки, роли
        |
        v
MCP-сервер Grafon (stdio/HTTP)
        |
        v
Claude Code / Cursor / Windsurf / Roo Code

Ключевые узлы графа:

| Узел | Что описывает | Пример |
|---|---|---|
| MetadataObject | Объект метаданных | Document.РеализацияТоваровУслуг |
| Module | Модуль объекта, менеджера, формы | ObjectModule, ManagerModule |
| Procedure | Процедура или функция BSL | ОбработкаПроведения |
| Call | Вызов из процедуры в процедуру | ОбработкаПроведения -> ПроверитьОстатки |
| Subscription | Подписка на событие | ПередЗаписью |
| Query | Запрос в BSL | ВЫБРАТЬ Товары... |
| Form | Форма и ее модуль | ФормаДокумента |

Графон не отправляет весь модуль. Он отдает ровно тот срез, который нужен для документации: сигнатуры, тела выбранных процедур, связи, запросы и события.

Практический сценарий: документация модуля проведения

Допустим, нужно автоматически описать модуль документа «РеализацияТоваровУслуг». В BSL есть типичный код:

Процедура ОбработкаПроведения(Отказ, РежимПроведения)
    ПроверитьЗаполнение();
    РассчитатьСебестоимость();
    СформироватьДвижения();
КонецПроцедуры


Процедура ПроверитьЗаполнение()
    Если НЕ ПроверитьРеквизиты() Тогда
        Сообщить("Документ заполнен неверно");
    КонецЕсли;
КонецПроцедуры



Процедура СформироватьДвижения()
    Запрос = Новый Запрос;
    Запрос.Текст =
        "ВЫБРАТЬ
        | Товары.Номенклатура,
        | Товары.Количество
        |ИЗ
        | Документ.РеализацияТоваровУслуг.Товары КАК Товары";
    Результат = Запрос.Выполнить();
КонецПроцедуры

ИИ-агент без Графона начнет читать весь объектный модуль, менеджерский модуль, формы и общие модули. С Графоном агент делает MCP-запрос:

{
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "name": "grafon.get_object_context",
    "arguments": {
      "metadata": "Document.РеализацияТоваровУслуг",
      "include": ["forms", "subscriptions", "call_graph"],
      "depth": 2
    }
  },
  "id": 1
}

Затем запрашивает срез конкретной процедуры:

{
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "name": "grafon.get_module_slice",
    "arguments": {
      "module": "Document.РеализацияТоваровУслуг.ObjectModule",
      "procedure": "ОбработкаПроведения",
      "with_callees": true,
      "max_depth": 2
    }
  },
  "id": 2
}

В ответ приходят только ОбработкаПроведения, ПроверитьЗаполнение, РассчитатьСебестоимость, СформироватьДвижения и их сигнатуры. Агент видит граф вызовов, но не тратит контекст на остальные 10 тысяч строк.

Генерация документации агентом

Промпт для Claude Code или Cursor может выглядеть так:

Сформируй Markdown-документацию для Document.РеализацияТоваровУслуг.
Используй MCP-сервер Grafon. Сначала получи карточку объекта.
Затем граф вызовов до 2 уровня. Опиши назначение, реквизиты,
табличные части, события, процедуры, запросы и побочные эффекты.
Не выдумывай методы, которых нет в ответе Grafon.

На выходе агент формирует структуру:

  • назначение документа;
  • табличные части и реквизиты;
  • события объекта;
  • процедуры и функции с сигнатурами;
  • граф вызовов;
  • используемые запросы и источники данных;
  • подписки и движения.

Так автоматическая документация модулей 1С с помощью MCP и ИИ становится не «пересказом кода», а трассируемым описанием, где каждое утверждение подтверждено графом.

Сравнение: без Графона vs с Графоном

Оценка для объекта ERP/УТ среднего размера, модуль 10 000 строк + связанные вызовы.

| Параметр | Без MCP и Графона | С Grafon MCP |
|---|---|---|
| Передаваемый контекст | Вся выгрузка или крупные модули | Точный срез: объект, вызовы, запросы |
| Токены на задачу | 300 000–400 000 | 25 000–40 000 |
| Время ответа агента | 10–15 минут | 2–4 минуты |
| Галлюцинации методов | Часто | Редко, есть проверка по графу |
| Актуальность | Зависит от промпта | Переиндексация XML/BSL |
| Стоимость API | Высокая | Ниже до 10 раз |
| Onboarding разработчика | Ручной поиск по модулям | Карточка объекта и граф вызовов |

Цифры зависят от глубины графа и размера конфигурации, но порядок экономии именно такой: Графон отсекает нерелевантные ветки до попадания в контекстное окно.

Сценарии применения

  • Документация доработок. После изменения модуля достаточно переиндексировать выгрузку и попросить ИИ обновить только затронутые объекты.
  • Onboarding. Новый разработчик получает описание объекта, цепочки вызовов и точки расширения без чтения сотен тысяч строк.
  • Аудит legacy. Графон показывает, какие процедуры вызывают запросы, подписки и движения. ИИ оформляет это в отчет.
  • Рефакторинг. Перед изменением ОбработкаПроведения агент видит всех вызываемых и вызывающих, включая подписки.
  • CI/CD документация. При сборке можно генерировать Markdown-карточки для ключевых объектов и хранить их рядом с кодом.

Как внедрить за 6 шагов

  1. Установите Графон локально или на dev-сервере.
  2. Укажите путь к XML-выгрузке конфигурации 1С.
  3. Запустите индексацию: Графон построит граф метаданных, вызовов, подписок и запросов.
  4. Подключите MCP-сервер к Claude Code, Cursor или Windsurf.
  5. Проверьте tools/list и вызовите grafon.get_object_context для тестового объекта.
  6. Дайте агенту шаблон документации и правило: «только факты из Grafon, без выдуманных методов».

Пример конфигурации MCP для клиента:

{
  "mcpServers": {
    "grafon": {
      "command": "grafon",
      "args": ["mcp", "--config", "C:/grafon/config.yaml"]
    }
  }
}

Лучшие практики

  • Индексируйте именно ту выгрузку, которая соответствует ветке разработки.
  • Ограничивайте depth графа: для документации обычно хватает 2–3 уровней.
  • Для форм запрашивайте отдельный срез, не смешивайте с объектным модулем.
  • Просите агента указывать полные имена процедур и модулей.
  • Храните сгенерированные Markdown-файлы в репозитории и обновляйте их при изменениях.
  • Проверяйте критичные места вручную: проведение, движения, права, RLS.

Итог

Автоматическая документация модулей 1С с помощью MCP и ИИ работает только тогда, когда агент получает структурированный контекст, а не сырой дамп конфигурации. Графон строит локальный граф зависимостей и через MCP отдает ИИ точные срезы: объекты, процедуры, вызовы, подписки, запросы и формы. Это снижает расход токенов до 10 раз, ускоряет генерацию документации и убирает галлюцинации. Для команд, которые поддерживают ERP, УТ, ЗУП или КА, это практический способ превратить legacy в управляемую документацию без ручного переписывания сотен тысяч строк BSL.

Попробовать Графон бесплатно