ArchMapДокументация

Подключить своего агента через MCP-сервер

Бета-версия

Документирование с помощью ИИ-агента пока работает в режиме бета-версии. Перед применением проверьте, что предлагает агент, а после применения при необходимости поправьте результат вручную.

Примечание

ИИ-агент, подключённый к ArchMap по MCP, не только отвечает на вопросы по документации, но и пишет её сам: строит схему по коду, обновляет её, описывает схемы логики, структуру баз данных, каналы и конфигурацию, привязывает шаги процессов. Переносить YAML и пакеты от агента в окна ArchMap вручную не нужно. Как подключить агента, см. Подключить ИИ-агента к ArchMap.

Поручить агенту документирование#

Чтобы агент изменил документацию в ArchMap, выполните следующие действия:

  1. Подключите агента с токеном без флажка Только чтение (см. Подключить ИИ-агента к ArchMap).
  2. Запустите агента в папке репозитория системы.
  3. Опишите задачу своими словами и назовите проект. Например:
    • «Построй схему системы по этому репозиторию и создай проект «Ярмарка»»;
    • «Обнови схему проекта «Ярмарка» по свежему коду»;
    • «Опиши логику операций Catalog API в проекте «Ярмарка»»;
    • «Опиши структуру БД каталога в проекте «Ярмарка»».
  4. Просмотрите план изменений, который покажет агент. В плане перечислено, что будет создано, изменено или помечено устаревшим.
  5. Подтвердите план. Агент запишет изменения в проект.
  6. Проверьте результат в ArchMap и разберите рекомендации, если они появились (см. Разобрать рекомендации к схеме).

Примечание

Перед любой записью агент получает от ArchMap план изменений и только потом применяет его. Если агент не показал план, попросите показать его перед применением.

Примечание

Правила оформления агент берёт у самого ArchMap: это те же промпты, что выдают окна Новый проект, Обновить из репозитория и окна описания логики и фактов. Поэтому результат получается таким же, как при переносе файлов вручную (см. Импортировать схему, собранную агентом из кода, Документировать систему с помощью ИИ-агента).

Примечание

Агент правит только проекты, где вы владелец или редактор, а создать новый проект может, только если у вас общая роль «Архитектор». Удалять агент не может ничего: то, что пропало из кода, он помечает статусом Выводится, а удалить такие объекты можно кнопкой Принять переход (см. Описать планируемые изменения системы). Управлять проектом и его участниками агент тоже не может.

Примечание

Агенту доступны те же рекомендации, которые показывает панель Рекомендации. Можно попросить его найти и исправить пробелы (например, «найди в проекте «Ярмарка» обращения к неописанным таблицам и опиши их»).

Подключить локальный MCP-сервер для архивов#

Примечание

Агенту, подключённому по адресу, недоступен диск: скачать архив проекта, создать проект из архива или догрузить архив в проект он не может. Для таких задач подключите локальный MCP-сервер ArchMap: он работает на компьютере агента и читает и пишет архивы на его диске. В остальном он работает так же, как сервер по адресу.

Чтобы подключить локальный MCP-сервер, выполните следующие действия:

  1. Убедитесь, что на компьютере установлены Python 3.11 или новее и git.

  2. Скачайте исходный код ArchMap и установите MCP-сервер:

    git clone https://github.com/eidunyushkinhse/archmap.git
cd archmap/mcp
python3 -m venv venv
./venv/bin/pip install -r requirements.txt

  3. Создайте файл настроек mcp/.env из шаблона:

    cp .env.example .env

  4. В файле mcp/.env укажите адрес ArchMap и токен (см. Выпустить токен):

    ARCHMAP_URL=https://archmap.example.com
ARCHMAP_TOKEN=archmap_...

  5. Добавьте сервер в файл настроек MCP-серверов агента, указав полный путь к папке mcp:

    {
  "mcpServers": {
    "archmap": {
      "command": "/полный/путь/archmap/mcp/venv/bin/python",
      "args": ["-m", "archmap_mcp.server"],
      "env": {
        "PYTHONPATH": "/полный/путь/archmap/mcp"
      }
    }
  }
}

  6. Перезапустите агента и попросите его показать список проектов ArchMap.

Примечание

Токен храните только в файле mcp/.env, потому что этот файл не попадает в git. В файл настроек агента токен не вписывайте, если этот файл лежит в репозитории.

Примечание

Если ArchMap открывается по HTTPS с сертификатом внутреннего центра сертификации, укажите файл корневых сертификатов в переменной SSL_CERT_FILE в блоке env настроек агента (например, /etc/ssl/certs/ca-certificates.crt).

Примечание

Чтобы агент сохранял архивы только в одной папке, укажите её в mcp/.env в переменной ARCHMAP_EXPORT_DIR (например, ARCHMAP_EXPORT_DIR=~/archmap-exports).