Интеграция MCP (доступ ИИ-инструментов)¶

Turbo EA включает встроенный MCP-сервер (Model Context Protocol), который позволяет ИИ-инструментам — таким как Claude Desktop, GitHub Copilot, Cursor и VS Code — запрашивать и обновлять данные вашей EA напрямую. ИИ-инструменты также могут загружать артефакты (таблицы, BPMN-диаграммы, DrawIO-диаграммы, свободные документы) и превращать их в карточки, связи и диаграммы, соответствующие существующей метамодели. Пользователи аутентифицируются через существующего SSO-провайдера, и каждое действие учитывает их индивидуальные разрешения.

Эта функция необязательна и не запускается автоматически. Она требует настройки SSO, активации профиля MCP в Docker Compose и включения администратором в интерфейсе настроек.

Как это работает¶

ИИ-инструмент (Claude, Copilot и т.д.)
    │
    │  Протокол MCP (streamable HTTP)
    ▼
MCP-сервер Turbo EA (:8001, внутренний)
    │
    │  OAuth 2.1 с PKCE
    │  делегирует вашему SSO-провайдеру
    ▼
Бэкенд Turbo EA (:8000)
    │
    │  RBAC для каждого пользователя
    ▼
PostgreSQL

Пользователь добавляет URL MCP-сервера в свой ИИ-инструмент.
При первом подключении ИИ-инструмент открывает окно браузера для SSO-аутентификации.
После входа MCP-сервер выдаёт собственный токен доступа (на основе JWT Turbo EA пользователя).
ИИ-инструмент использует этот токен для всех последующих запросов. Токены обновляются автоматически.
Каждый запрос проходит через обычную систему разрешений Turbo EA — пользователи видят только данные, к которым у них есть доступ.

Предварительные требования¶

Перед включением MCP у вас должно быть:

SSO настроен и работает — MCP делегирует аутентификацию вашему SSO-провайдеру (Microsoft Entra ID, Google Workspace, Okta или общий OIDC). См. руководство по Аутентификации и SSO.
HTTPS с публичным доменом — поток OAuth требует стабильного URI перенаправления. Разверните за обратным прокси с терминацией TLS (Caddy, Traefik, Cloudflare Tunnel и т.д.).

Настройка¶

Шаг 1: Запустите сервис MCP¶

MCP-сервер — это опциональный профиль Docker Compose. Добавьте --profile mcp к вашей команде запуска:

docker compose --profile mcp up --build -d

Это запускает легковесный Python-контейнер (порт 8001, только внутренний) рядом с бэкендом и фронтендом. Nginx автоматически проксирует запросы /mcp/ к нему.

Шаг 2: Настройте переменные окружения¶

Добавьте следующее в ваш файл .env:

TURBO_EA_PUBLIC_URL=https://your-domain.example.com
MCP_PUBLIC_URL=https://your-domain.example.com/mcp

Переменная	По умолчанию	Описание
`TURBO_EA_PUBLIC_URL`	`http://localhost:8920`	Публичный URL вашего экземпляра Turbo EA
`MCP_PUBLIC_URL`	`http://localhost:8920/mcp` (docker compose)	Публичный URL MCP-сервера (используется в URI перенаправления OAuth). При автономном запуске контейнера значение по умолчанию в коде — `http://localhost:8001`
`MCP_PORT`	`8001`	Внутренний порт MCP-контейнера (редко требует изменения)

Шаг 3: Добавьте URI перенаправления OAuth в ваше приложение SSO¶

В регистрации приложения вашего SSO-провайдера (том же, которое вы настроили для входа в Turbo EA) добавьте этот URI перенаправления:

https://your-domain.example.com/mcp/oauth/callback

Это необходимо для потока OAuth, который аутентифицирует пользователей при подключении из их ИИ-инструмента.

Шаг 4: Включите MCP в настройках администратора¶

Перейдите в Настройки в области администрирования и выберите вкладку ИИ.
Прокрутите до раздела Интеграция MCP (доступ ИИ-инструментов).
Переключите переключатель, чтобы включить MCP.
В интерфейсе отобразится URL MCP-сервера и инструкции по настройке, которыми можно поделиться с вашей командой.

Warning

Переключатель недоступен, если SSO не настроен. Сначала настройте SSO.

Подключение ИИ-инструментов¶

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

Claude Desktop¶

Откройте Настройки > Коннекторы > Добавить пользовательский коннектор.
Введите URL MCP-сервера: https://your-domain.example.com/mcp
Нажмите Подключить — откроется окно браузера для SSO-входа.
После аутентификации Claude может запрашивать данные вашей EA.

VS Code (GitHub Copilot / Cursor)¶

Добавьте в файл .vscode/mcp.json вашего рабочего пространства:

{
  "servers": {
    "turbo-ea": {
      "type": "http",
      "url": "https://your-domain.example.com/mcp"
    }
  }
}

Используйте https://your-domain.example.com/mcp в качестве конечной точки. Прежняя двойная форма https://your-domain.example.com/mcp/mcp по-прежнему работает, поэтому существующие коннекторы продолжают работать без изменений.

Локальное тестирование (режим stdio)¶

Для локальной разработки или тестирования без SSO/HTTPS вы можете запустить MCP-сервер в режиме stdio — Claude Desktop запускает его напрямую как локальный процесс.

1. Установите пакет MCP-сервера:

pip install ./mcp-server

2. Добавьте в конфигурацию Claude Desktop (claude_desktop_config.json):

{
  "mcpServers": {
    "turbo-ea": {
      "command": "python",
      "args": ["-m", "turbo_ea_mcp", "--stdio"],
      "env": {
        "TURBO_EA_URL": "http://localhost:8000",
        "TURBO_EA_EMAIL": "[email protected]",
        "TURBO_EA_PASSWORD": "your-password"
      }
    }
  }
}

В этом режиме сервер аутентифицируется с помощью email/пароля и автоматически обновляет токен в фоновом режиме.

Доступные возможности¶

MCP-сервер предоставляет 47 инструментов, разделённых на две группы: 30 инструментов чтения, которые запрашивают данные EA, и 17 инструментов записи (13 добавляющих, 4 разрушающих), которые создают и сопровождают карточки, связи, диаграммы, риски, ADR и многое другое — в том числе превращают артефакты, находящиеся в собственном контексте ИИ-инструмента (таблицы, BPMN XML, DrawIO XML, документы, изображения), в структурированные данные EA. Каждый инструмент несёт MCP-аннотации ToolAnnotations (подсказки «только чтение» / «разрушающий» / «идемпотентный»), чтобы коннекторы могли отображать степень разрушительности в своём интерфейсе.

Безопасность записи через сухой прогон¶

Каждый инструмент записи по умолчанию использует dry_run=true. В этом режиме бэкенд выполняет каждый валидатор и резолвер, формирует полный план и затем откатывает транзакцию, поэтому ничего не сохраняется. ИИ-инструмент возвращает предварительный просмотр пользователю; только после явного подтверждения он должен повторно вызвать инструмент с dry_run=false, чтобы зафиксировать изменения. Это не позволяет излишне ретивому агенту молча создать сотни карточек на основе неправильно интерпретированной таблицы.

Инструменты чтения¶

Сервер предоставляет 30 инструментов чтения, сгруппированных в восемь кластеров.

Карточки и метамодель

Инструмент	Описание
`search_cards`	Поиск и фильтрация карточек по типу, статусу или свободному тексту
`get_card`	Получение полных деталей карточки по UUID
`get_card_relations`	Получение всех связей карточки
`get_card_hierarchy`	Получение предков и потомков карточки
`list_card_types`	Список всех типов карточек в метамодели
`get_relation_types`	Список типов связей, опционально отфильтрованный по типу карточки
`resolve_card_refs`	Предварительная проверка ссылок на карточки по имени (имя → UUID) перед массовым импортом — только разрешает ссылки, никогда не записывает
`analyze_impact`	Анализ радиуса поражения зависимостей для предлагаемого изменения карточки

Панели

Инструмент	Описание
`get_dashboard`	Панель KPI (количество, качество данных, утверждения, активность)
`get_landscape`	Карточки одного типа, сгруппированные по связанному типу

GRC — Реестр рисков

Инструмент	Описание
`list_risks`	Постраничный фильтруемый список рисков EA (TOGAF Фаза G)
`get_risk`	Детали одного риска со связанными карточками и аудитом
`get_risk_metrics`	KPI + матрицы 4×4 начальная и остаточная
`get_card_risks`	Все риски, связанные в данный момент с карточкой

GRC — Соответствие

Инструмент	Описание
`list_compliance_findings`	Находки соответствия, сгруппированные по регулятиве
`get_compliance_overview`	Оценки соответствия + матрица статуса по регламенту + метаданные последнего сканирования

Управление и поставка

Инструмент	Описание
`list_principles`	Опубликованные принципы EA (формулировка, обоснование, последствия)
`list_adrs`	Architecture Decision Records, фильтр по инициативе / статусу
`get_adr`	Один ADR с разделами, связанными карточками и подписями
`list_soaws`	Statements of Architecture Work одной инициативы

Отчёты

Инструмент	Описание
`get_portfolio_report`	Данные пузырьковой диаграммы для типа карточек (по умолчанию: функциональный × технический fit)
`get_cost_treemap`	Treemap затрат, опционально сгруппированный по связанному типу
`get_capability_heatmap`	Иерархическая тепловая карта бизнес-возможностей
`get_data_quality_report`	Разбивка полноты по типам карточек

Контекст карточки

Инструмент	Описание
`get_card_stakeholders`	Пользователи + роли, назначенные на карточку
`get_card_comments`	Тред комментариев карточки
`get_card_documents`	Ссылки на документы, прикреплённые к карточке (URL, не файлы)

Диаграммы

Инструмент	Описание
`list_diagrams`	Список свободных (DrawIO) диаграмм, опционально отфильтрованный по одной карточке
`get_diagram`	Получение одной диаграммы по id, включая её DrawIO XML

Аудит и история изменений

Инструмент	Описание
`get_change_history`	Запрос к журналу пакетов мутаций (по id пакета, исполнителю, инструменту или происхождению) для точного восстановления того, что изменил предыдущий коммит MCP

Все инструменты соблюдают RBAC аутентифицированного пользователя — viewer просто получит пустой список (или 403) для того, что ему недоступно; на уровне MCP настраивать пер-инструментно ничего не нужно.

Инструменты записи¶

Сервер предоставляет 17 инструментов записи, каждый из которых аннотирован как добавляющий (создаёт или расширяет данные) или разрушающий (изменяет или удаляет существующие данные), чтобы коннекторы могли предупреждать соответствующим образом.

Добавляющие (13)

Инструмент	Описание
`create_cards_bulk`	Создаёт несколько карточек одним вызовом (например, строки таблицы). Поддерживает ссылки на родителя по имени внутри одного пакета с серверной топологической сортировкой.
`transition_card_lifecycle`	Переводит карточку по фазам утверждения или жизненного цикла.
`create_risks`	Создаёт записи в Реестре рисков EA.
`update_risks`	Обновляет записи Реестра рисков (поля, связанные карточки).
`add_card_comment`	Публикует комментарий на карточке — неразрушающая, доступная для рецензирования заметка вместо изменения полей.
`create_soaw`	Создаёт Statement of Architecture Work для инициативы.
`assign_stakeholders`	Назначает или удаляет роли заинтересованных лиц на карточках.
`update_cards_bulk`	Точечные изменения полей на многих карточках одним вызовом.
`create_adr`	Создаёт Architecture Decision Record.
`update_adr`	Обновляет ADR (заголовок, разделы, статус, связанные карточки).
`sign_adr`	Подписывает ADR (требует разрешения `adr.sign`; иначе возвращает глубокую ссылку на интерфейс для подписания в браузере).
`create_diagram`	Создаёт свободную DrawIO-диаграмму с опциональными ссылками на существующие карточки.
`import_bpmn`	Сохраняет BPMN 2.0 XML-диаграмму на существующей карточке Бизнес-процесса. Если карточка с указанным именем отсутствует, инструмент возвращает ошибку `card_not_found` и направляет агента к `create_cards_bulk` — это вынуждает сначала явно создать карточку с описанием, подтипом и атрибутами, а не идти по короткому пути, оставляющему скудную карточку.

Разрушающие (4)

Инструмент	Описание
`upsert_relations_bulk`	Создаёт или удаляет связи между карточками. Источник / цель / тип проверяются по метамодели. Удаление отклоняется, если оператор не включил его явно (см. защитные ограждения).
`archive_cards`	Мягкое удаление карточек. Обратимо — архивированные карточки можно восстановить в течение 30 дней до автоматической очистки.
`update_diagram`	Заменяет DrawIO XML, имя или связи с карточками у диаграммы.
`rollback_batch`	Откатывает записи, выполненные в рамках предыдущего пакета мутаций.

Загрузка артефактов¶

Подмножество инструментов записи (create_cards_bulk, upsert_relations_bulk, create_diagram, import_bpmn) позволяет ИИ-агенту превращать артефакты в структурированные данные EA. Агент читает исходный файл в собственном контексте (мультимодальное зрение, вложения), извлекает структурированные строки и вызывает эти инструменты. Сам MCP-сервер никогда не разбирает файлы — он ожидает уже структурированный ввод.

Типовой сценарий, когда пользователь делится таблицей с ИИ-агентом:

Агент вызывает list_card_types и get_relation_types, чтобы понять метамодель.
Агент разбирает таблицу (в собственном контексте, не в MCP) и формирует словари по строкам.
Агент вызывает create_cards_bulk(cards=…, dry_run=True) и показывает пользователю предварительный просмотр.
Пользователь подтверждает; агент вызывает снова с dry_run=False, чтобы зафиксировать.
Если присутствуют столбцы со связями, агент затем вызывает upsert_relations_bulk тем же циклом сухой прогон / подтверждение.

Защитные ограждения для инструментов записи¶

Эшелонированная защита поверх сухого прогона, чтобы ошибка LLM не могла нанести массовый ущерб:

Ограничение размера на вызов. Инструменты записи MCP применяют значительно меньший предел, чем у нижележащих эндпоинтов Excel-импортёра: 200 строк для create_cards_bulk, 500 операций для upsert_relations_bulk. Достаточно для любой реалистичной загрузки одного артефакта и достаточно мало, чтобы предварительный просмотр сухого прогона оставался обозримым.
По умолчанию запрет на удаление связей. upsert_relations_bulk отклоняет операции action: "delete" — для удаления связей используйте веб-интерфейс, где действие фиксируется под идентификатором пользователя. Операторы могут включить эту возможность, установив MCP_ALLOW_RELATION_DELETE=true.
Аварийный выключатель. MCP_WRITES_ENABLED=false отключает все 17 инструментов записи без повторного развёртывания кода. 30 инструментов чтения продолжают работать.
Метка происхождения для аудита. Каждый запрос к бэкенду от MCP-сервера несёт заголовок X-Turbo-EA-Origin: mcp. События, эмитированные из этих запросов, помечаются origin: "mcp" в полезной нагрузке журнала аудита, чтобы администраторы могли фильтровать записи, инициированные MCP, в журнале отдельно от действий веб-интерфейса.
Пакеты мутаций. Каждый вызов записи MCP открывает пакет мутаций до каких-либо записей; каждое событие, эмитированное во время вызова, помечается id пакета. Администраторы (или инструмент get_change_history) могут восстановить полный поэлементный дифф коммита по одному id, а rollback_batch может его откатить. Коммиты, затрагивающие больше строк, чем MCP_BATCH_CONFIRMATION_THRESHOLD, должны вернуть одноразовый confirm_token, выданный предшествующим сухим прогоном (TTL 15 минут), поэтому крупный коммит всегда следует за просмотренным предпросмотром.
Нет жёсткого удаления. Набор инструментов намеренно не включает необратимое удаление карточек. archive_cards и update_cards_bulk представлены, но архивирование — это обратимое мягкое удаление (окно восстановления 30 дней), и оба инструмента аннотированы как разрушающие и защищены сухим прогоном. Добавление любого инструмента, выполняющего необратимую мутацию (жёсткое удаление, принудительная очистка), потребует явного дизайн-обзора.

Шесть переменных окружения защитных ограждений на контейнере MCP:

Переменная	По умолчанию	Эффект
`MCP_WRITES_ENABLED`	`true`	Главный переключатель инструментов записи. `false` → MCP только для чтения.
`MCP_MAX_CARDS_PER_CALL`	`200`	Жёсткое ограничение строк `create_cards_bulk` / `update_cards_bulk` на запрос.
`MCP_MAX_RELATIONS_PER_CALL`	`500`	Жёсткое ограничение операций `upsert_relations_bulk` на запрос.
`MCP_ALLOW_RELATION_DELETE`	`false`	При `true` `upsert_relations_bulk` принимает операции `action: "delete"`.
`MCP_BATCH_CONFIRMATION_THRESHOLD`	`20`	Коммиты, затрагивающие больше строк, чем это значение, требуют `confirm_token` от предшествующего сухого прогона.
`MCP_REQUIRE_DRYRUN_FIRST`	`true`	Включает описанный выше механизм confirm-token. Устанавливайте `false` только для доверенных конвейеров автоматизации, которые сознательно пропускают этап предварительного просмотра.

Ресурсы¶

URI	Описание
`turbo-ea://types`	Все типы карточек в метамодели
`turbo-ea://relation-types`	Все типы связей
`turbo-ea://dashboard`	KPI панели управления и сводная статистика

Управляемые промпты¶

Промпт	Описание
`analyze_landscape`	Многоэтапный анализ: обзор панели, типы, связи
`find_card`	Поиск карточки по имени, получение деталей и связей
`explore_dependencies`	Картирование зависимостей карточки и того, что зависит от неё

Разрешения¶

Роль Доступ

Администратор Настройка параметров MCP (разрешение admin.mcp). Полный доступ на чтение + запись через MCP.

Все аутентифицированные пользователи Доступ на чтение управляется их существующим RBAC. Инструменты записи требуют соответствующих бэкенд-разрешений — inventory.create / inventory.edit / inventory.archive (карточки), relations.manage (связи), diagrams.manage (диаграммы), bpm.edit (BPMN), risks.manage (Реестр рисков), comments.create (комментарии), stakeholders.manage (заинтересованные лица), soaw.create (SoAW), adr.create / adr.sign (ADR).

Разрешение admin.mcp контролирует, кто может управлять настройками MCP. Оно доступно только роли «Администратор» по умолчанию. Пользовательским ролям можно предоставить это разрешение через страницу администрирования ролей.

Доступ к данным через MCP — для чтения или для записи — следует той же модели RBAC, что и веб-интерфейс. Если пользователь не может создавать карточки в интерфейсе инвентаря, он также не может создавать их через MCP; отдельных разрешений на данные, специфичных для MCP, не существует.

Безопасность¶

Аутентификация через SSO: пользователи аутентифицируются через корпоративного SSO-провайдера. MCP-сервер никогда не видит и не хранит пароли.
OAuth 2.1 с PKCE: поток аутентификации использует Proof Key for Code Exchange (S256) для предотвращения перехвата кода авторизации.
RBAC для каждого пользователя: каждое действие MCP — чтение или запись — выполняется с разрешениями аутентифицированного пользователя. Общие сервисные аккаунты не используются.
Сухой прогон по умолчанию при записи: инструменты записи по умолчанию предлагают предварительный просмотр в режиме проверки-и-отката. ИИ-инструмент должен явно вызвать ещё раз с dry_run=false, прежде чем какие-либо данные будут сохранены, и каждое изменение фиксируется в аудите под идентификатором пользователя.
Никакого разбора файлов в MCP: сам MCP-сервер не принимает PDF, файлы Excel, изображения или другие двоичные артефакты. Вызывающий ИИ-инструмент разбирает их в собственном контексте и отправляет структурированные строки. Это сохраняет узкую поверхность атаки и не подвергает сервер некорректным двоичным входам.
Ротация токенов: токены доступа истекают через 1 час. Токены обновления действуют 30 дней. Коды авторизации одноразовые и истекают через 10 минут.
Только внутренний порт: MCP-контейнер открывает порт 8001 только во внутренней сети Docker. Весь внешний доступ идёт через обратный прокси Nginx.

Устранение неполадок¶

Проблема	Решение
Переключатель MCP недоступен в настройках	Сначала необходимо настроить SSO. Перейдите в Настройки > вкладка «Аутентификация» и настройте SSO-провайдера.
«host not found» в логах Nginx	Сервис MCP не запущен. Запустите его с помощью `docker compose --profile mcp up -d`. Конфигурация Nginx обрабатывает это корректно (ответ 502, без сбоя).
Обратный вызов OAuth не проходит	Убедитесь, что вы добавили `https://your-domain.example.com/mcp/oauth/callback` как URI перенаправления в регистрации приложения SSO.
ИИ-инструмент не может подключиться	Проверьте, что `MCP_PUBLIC_URL` соответствует URL, доступному с машины пользователя. Убедитесь, что HTTPS работает.
Пользователь получает пустые результаты	MCP учитывает разрешения RBAC. Если у пользователя ограниченный доступ, он увидит только карточки, разрешённые его ролью.
Подключение обрывается через 1 час	ИИ-инструмент должен обрабатывать обновление токена автоматически. Если нет, переподключитесь.