Multi-MCP Enterprise Operations Copilot

Копилот для операторов промышленных установок. Он отвечает на вопросы на естественном языке, вызывая API управления аварийными сигналами через специально созданные MCP-серверы, извлекая релевантные фрагменты из корпуса эксплуатационной документации и объединяя их в единый обоснованный ответ, содержащий цитаты и видимый след выполнения.

git clone <repository-url> && cd senior-copilot-mcp-rag-assignment
cp .env.example .env
docker compose up --build

Затем откройте http://localhost:5173 и задайте приемочный вопрос. Ключ API не требуется — стек по умолчанию использует детерминированного провайдера, который выполняет тот же рабочий процесс без LLM. Установите LLM_PROVIDER=anthropic и ANTHROPIC_API_KEY для генерации текста.

1 · Выбранный вариант использования

Multi-MCP Enterprise Operations Copilot. Копилот обнаруживает и координирует инструменты на двух MCP-серверах вместо жестко заданных интеграций и объединяет эти структурированные данные с неструктурированными доказательствами из документов в одном рабочем процессе.

Обязательный приемочный сценарий:

Исследовать повторяющиеся аварийные сигналы высокой серьезности для питательного насоса котла 101 за последние 90 дней, выявить вероятные способствующие факторы, извлечь соответствующую рабочую процедуру и предоставить рекомендуемые действия с указанием источников.

Этот сценарий выполняется как автоматизированный тест (tests/e2e/test_acceptance_scenario.py), который проверяет через реальный HTTP-интерфейс, что выполняются пять шагов, что шаг 2 получил идентификатор актива, созданный на шаге 1, что поиск был сужен по имени актива, разрешенному на шаге 1, и что ответ содержит маркеры как [tool: …], так и [source: …].

Примечание об исходной системе

API управления аварийными сигналами, описанный в задании, не существует как работающий сервис — предоставленные коллекции Postman являются его спецификацией. Поэтому он также создан здесь, как services/alarm-simulator/: 15 конечных точек, аутентификация Bearer, заголовки трассировки, конверт ошибок и детерминированные начальные данные, спроектированные так, что каждое утверждение цепочки в предоставленных коллекциях возвращает непустые результаты. make contract запускает все три коллекции против него; CI делает то же самое при каждом пуше.

2 · Основные возможности

• Чат на естественном языке с живыми данными аварийных сигналов и эксплуатационными документами

• Обнаружение инструментов во время выполнения на двух MCP-серверах — без жестко заданного списка инструментов

• Многошаговое связывание инструментов, где вывод одного инструмента становится вводом для следующего

• Гибридный поиск документов (BM25 + плотные векторы, объединенные по взаимному рангу) со встроенными цитатами

• Один ответ, объединяющий структурированные результаты инструментов и неструктурированные доказательства из документов

• Полный след выполнения: какой сервер, какой инструмент, какие аргументы, сколько времени, какой результат

• Явное подтверждение человеком перед любой записью, обеспечиваемое контрактом инструмента

• Корректная деградация при сбое инструмента, тайм-ауте, неверной схеме, пустом результате поиска, отказе модели или отсутствии ключа API

3 · Технологический стек

4 · Краткое описание архитектуры

Пять сервисов. GUI взаимодействует с оркестратором FastAPI через REST и SSE. Оркестратор планирует последовательность шагов против реестра инструментов, который он обнаружил во время выполнения на двух MCP-серверах, разрешает аргументы каждого шага (включая значения, полученные на предыдущих шагах), выполняет поиск документов как один из этих шагов и составляет один ответ с цитатами.

Browser ──HTTP/SSE──▶ backend ──MCP──▶ mcp-alarm-management ──HTTPS+bearer──▶ alarm-simulator
                         │      └────▶ mcp-github-issues    ──────────────▶ GitHub (mocked)
                         └─embedded──▶ Chroma index over rag/documents

Только MCP-серверы хранят учетные данные для систем, стоящих за ними. Копилот никогда не вызывает API управления аварийными сигналами напрямую, поэтому у языковой модели нет пути кода к токену Bearer — она не может его прочитать, запросить или быть вынуждена раскрыть его с помощью инъекции подсказок.

• Поток запросов от начала до конца: docs/architecture.md

• Компоненты, ADR, NFR, риски, прослеживаемость: docs/hld.md

• Схемы, сигнатуры, алгоритмы, конечные автоматы: docs/lld.md

5 · MCP-серверы и инструменты

Два сервера, созданных кандидатом. Полные контракты — включая схемы ввода/вывода, поведение аутентификации, поведение при ошибках, тайм-ауты и реальные примеры запросов и ответов — находятся в docs/mcp-tool-catalog.md, который генерируется из живого вызова list_tools() и проверяется в CI, поэтому он не может отклониться от кода.

alarm-management — 14 инструментов

github-issues — 3 инструмента

Запуск одного сервера отдельно

python -m alarm_mcp                      # stdio, for a local MCP client
python -m alarm_mcp --transport http     # streamable HTTP, as in compose
python scripts/mcp_smoke.py              # chain two tools, no GUI and no LLM

6 · RAG-корпус и индексация

10 документов в формате Markdown (рабочие процедуры, руководства по устранению неисправностей, стандарты, инструкция по безопасности, бюллетень поставщика) → 49 фрагментов, выровненных по заголовкам → встроенный индекс Chroma.

python -m rag.ingestion.cli --docs ./rag/documents --reset

Поиск объединяет BM25 с плотными векторами, фильтрует по активу, разрешенному более ранним вызовом инструмента, и сообщает low_confidence, а не выдает слабое совпадение за достоверное. Один документ корпуса содержит живую полезную нагрузку для инъекции подсказок, чтобы граница доверия тестировалась, а не декларировалась.

Полный дизайн — фрагментация, метаданные, объединение, построение цитат, достоверность, защита от инъекций, обновление: docs/rag-design.md.

7 · Конфигурация

Каждое значение — это переменная окружения. .env.example документирует каждый ключ с безопасным заполнителем; ни один секрет не фиксируется, и ни один не требуется для запуска демо.

Полная справка с типами, значениями по умолчанию и потребляющим сервисом: docs/lld.md §9.

8 · Сборка и запуск

make является каноническим и используется CI. В Windows без make, tasks.ps1 предоставляет те же имена целей.

Порты: GUI 5173, бэкенд 8080, симулятор 8000 (открыт, чтобы коллекции Postman могли работать с ним), MCP-серверы 9000 / 9001 (внутренние).

Если один из них уже занят, переопределите сторону хоста в .env — порты контейнера никогда не меняются. Установите VITE_API_BASE_URL в соответствии с портом бэкенда, потому что Vite встраивает его в GUI во время сборки:

BACKEND_HOST_PORT=8090 VITE_API_BASE_URL=http://localhost:8090 docker compose up --build

Без Docker: make install, затем запустите четыре сервиса Python в отдельных терминалах — uvicorn alarm_simulator.main:app --port 8000, python -m alarm_mcp --transport http, python -m github_mcp --transport http, make ingest, uvicorn copilot_backend.api.app:app --port 8080 — и npm run dev в apps/frontend.

9 · Тесты

make contract требует newman (npm install -g newman) и работающий симулятор.

269 тестов, все проходят, 89% покрытие строк — разбивка в docs/coverage.md. Что они покрывают:

LLM замокан везде, включая сквозные тесты, поэтому набор быстрый, бесплатный и воспроизводимый. См. docs/known-limitations.md о том, что это значит.

10 · Примеры взаимодействий

Повторяющиеся аварийные сигналы (сценарий приёмки). Пять шагов: определить актив → обобщить его аварийные сигналы высокой серьёзности → коррелировать совместно встречающиеся пары → найти кандидатов на рационализацию → получить процедуру, отфильтрованную по только что определённому активу. В ответе сообщается, что Discharge Pressure Low сопровождается Suction Strainer DP High 31 раз (lift 2.29, среднее запаздывание 393 с) [tool: alarm-management/get_alarm_correlation] и связывается с шагами изоляции и осмотра из [source: OP-BFP-101#…].

Эффективность ответа оператора. generate_calculation → execute_calculation (связаны по calculation_id) → тренд задержки подтверждения → применимый стандарт из STD-OPRESP.

Эскалация. Активные аварийные сигналы → оценка приоритета для самого высокого → рекомендуемые действия с контекстом связанных аварийных сигналов → соответствующий раздел философии аварийных сигналов.

Создание задачи. Сводка аварийных сигналов → проверка на дубликаты → draft_issue. create_issue останавливает выполнение с confirmation.required; GUI показывает точные аргументы и продолжает только после одобрения. MCP сервер отказывается независимо от того, что делает UI.

Вопрос без подтверждающего документа. Поиск сообщает low_confidence; ответ прямо говорит, что подходящая процедура не найдена, вместо подстановки общих знаний.

11 · Структура репозитория

apps/backend/          FastAPI orchestrator, MCP client, LLM providers
apps/frontend/         React + TypeScript GUI
mcp-servers/           alarm-management (14 tools), github-issues (3 tools)
services/              alarm-simulator — the candidate-built source system
connectors/alarm_api/  Reusable HTTP client, deliberately separate from the MCP server
packages/schemas/      Shared Pydantic tool contracts
rag/                   documents, ingestion, retrieval, tests
tests/                 unit, integration, e2e
docs/                  architecture, HLD, LLD, tool catalog, RAG design, decisions, limits
postman/               The supplied collections — the Alarm API specification

Два задокументированных отклонения от структуры в руководстве по представлению §3:

• services/alarm-simulator/ — в задании отдельно требуется бэкенд, созданный кандидатом, который не входит в предопределённые папки. Хранение симулятора (интегрируемой системы) отдельно от connectors/ (клиента, который к нему обращается) — более чистое разделение, чем объединение обоих.

• docs/hld.md и docs/lld.md — добавлены вместе с обязательным docs/architecture.md, который остаётся точкой входа.

Руководство допускает эквивалентные структуры при чётком документировании. Поскольку обязательные имена каталогов содержат дефисы и поэтому не являются допустимыми именами пакетов Python, каждый содержит правильно названный пакет (mcp-servers/alarm-management/alarm_mcp/), сопоставленный с импортом верхнего уровня в pyproject.toml.

12 · Допущения

1. API управления аварийными сигналами не существует, поэтому коллекции Postman рассматриваются как его спецификация, а симулятор построен так, чтобы точно им соответствовать. Там, где коллекции умалчивали (например, фильтры, которые появляются только в коллекции цепочек), авторитетом являются утверждения коллекции.

2. Идентификаторы аварийных сигналов, идентификаторы активов и временные метки воспроизводимы. Зерно фиксировано, поэтому демо, тест и запуск Postman видят одни и те же данные.

3. Корреляция означает совместную встречаемость в окне запаздывания на одном активе. Проверка статистической значимости выходит за рамки синтетических данных.

4. Один арендатор, один объект. Идентификатор арендатора не передаётся через поиск или авторизацию инструментов.

5. Переход от GUI к бэкенду не аутентифицирован, что приемлемо для локального демо и отмечено в ограничениях.

6. docker compose up — поддерживаемый путь. Ручной путь описан в §8, но файл compose используется в CI.

13 · Известные ограничения и будущие улучшения

Честные границы объёма, для каждой указано, что было бы сделано иначе при большем времени: docs/known-limitations.md. Что дальше, в порядке, в котором я бы это делал: docs/future-improvements.md.

14 · Демо

Скриншоты

Сделаны из работающего стека командой make screenshots, поэтому их можно перегенерировать, а не устаревать: docs/screenshots/.

Также захвачены: пустое состояние и ответ с чипами цитирования.

Видео

Ссылка: будет добавлена — см. docs/demo.md для записанного сценария прохождения.

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

Лицензия

MIT — см. LICENSE.