Интеграция 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 (HTTP + SSE)
    ▼
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`	Публичный URL MCP-сервера (используется в URI перенаправления OAuth)
`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/mcp"
    }
  }
}

Двойное /mcp/mcp намеренное — первое /mcp/ — это путь прокси Nginx, второе — конечная точка протокола 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": "your@email.com",
        "TURBO_EA_PASSWORD": "your-password"
      }
    }
  }
}

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

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

MCP-сервер предоставляет 30 инструментов, разделённых на две группы: 25 инструментов чтения, которые запрашивают данные EA, и 5 инструментов записи, которые превращают артефакты, находящиеся в собственном контексте ИИ-инструмента (таблицы, BPMN XML, DrawIO XML, документы, изображения), в карточки, связи и диаграммы.

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

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

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

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

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

Инструмент	Описание
`search_cards`	Поиск и фильтрация карточек по типу, статусу или свободному тексту
`get_card`	Получение полных деталей карточки по UUID
`get_card_relations`	Получение всех связей карточки
`get_card_hierarchy`	Получение предков и потомков карточки
`list_card_types`	Список всех типов карточек в метамодели
`get_relation_types`	Список типов связей, опционально отфильтрованный по типу карточки

Панели

Инструмент	Описание
`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, не файлы)

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

Инструменты записи — загрузка артефактов¶

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

Инструмент	Описание
`create_cards_bulk`	Создаёт несколько карточек одним вызовом (например, строки таблицы). Поддерживает ссылки на родителя по имени внутри одного пакета с серверной топологической сортировкой.
`resolve_card_refs`	Предварительно проверяет ссылки на основе имени перед массовым импортом — полезно, чтобы показать пользователю неоднозначных или отсутствующих родителей.
`upsert_relations_bulk`	Создаёт или удаляет связи между карточками. Источник / цель / тип проверяются по метамодели.
`create_diagram`	Создаёт свободную DrawIO-диаграмму с опциональными ссылками на существующие карточки.
`import_bpmn`	Сохраняет BPMN 2.0 XML-диаграмму на существующей карточке Бизнес-процесса. Если карточка с указанным именем отсутствует, инструмент возвращает ошибку `card_not_found` и направляет агента к `create_cards_bulk` — это вынуждает сначала явно создать карточку с описанием, подтипом и атрибутами, а не идти по короткому пути, оставляющему скудную карточку.

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

Агент вызывает 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 отключает все пять инструментов записи без повторного развёртывания кода. 25 инструментов чтения продолжают работать.
Метка происхождения для аудита. Каждый запрос к бэкенду от MCP-сервера несёт заголовок X-Turbo-EA-Origin: mcp. События, эмитированные из этих запросов, помечаются origin: "mcp" в полезной нагрузке журнала аудита, чтобы администраторы могли фильтровать записи, инициированные MCP, в журнале отдельно от действий веб-интерфейса.
Нет инструментов массового разрушения. Набор инструментов намеренно не включает удаление, архивирование и массовое обновление карточек. Добавление любого такого инструмента потребует явного дизайн-обзора.

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

Переменная	По умолчанию	Эффект
`MCP_WRITES_ENABLED`	`true`	Главный переключатель инструментов записи. `false` → MCP только для чтения.
`MCP_MAX_CARDS_PER_CALL`	`200`	Жёсткое ограничение строк `create_cards_bulk` на запрос.
`MCP_MAX_RELATIONS_PER_CALL`	`500`	Жёсткое ограничение операций `upsert_relations_bulk` на запрос.
`MCP_ALLOW_RELATION_DELETE`	`false`	При `true` `upsert_relations_bulk` принимает операции `action: "delete"`.

Ресурсы¶

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` (карточки), `relations.manage` (связи), `diagrams.manage` (диаграммы), `bpm.edit` (BPMN).

Разрешение 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 час	ИИ-инструмент должен обрабатывать обновление токена автоматически. Если нет, переподключитесь.