Multi-MCP エンタープライズ運用コパイロット

プラントオペレーター向けのコパイロットです。目的に合わせて構築された MCP サーバー を介してアラーム管理 API を呼び出し、運用文書コーパスから関連するパッセージを取得し、両方を統合して引用と可視化された実行トレースを含む単一の根拠ある回答を生成することで、自然言語による質問に応答します。

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 エンタープライズ運用コパイロット。 コパイロットは、統合をハードコードするのではなく、2 つの MCP サーバー間でツールを発見および調整し、構造化データと非構造化文書エビデンスを 1 つのワークフローに結合します。

必須の受入シナリオ:

過去 90 日間の Boiler Feed Pump 101 に関する高重要度アラームの再発を調査し、考えられる要因を特定し、該当する運転手順を取得し、ソースエビデンスとともに推奨アクションを提供する。

このシナリオは自動テスト (tests/e2e/test_acceptance_scenario.py) として実行され、実際の HTTP サーフェス上で、5 つのステップが実行されること、ステップ 2 がステップ 1 で生成されたアセット ID を受け取ったこと、検索がステップ 1 で解決されたアセット名によって絞り込まれたこと、回答に [tool: …] と [source: …] の両方のマーカーが含まれていることをアサートします。

ソースシステムに関する注記

概要で説明されているアラーム管理 API は、実行中のサービスとしては存在しません。提供された Postman コレクションが その仕様 です。そのため、ここでも services/alarm-simulator/ として構築されています。15 のエンドポイント、ベアラー認証、トレースヘッダー、エラーエンベロープ、および提供されたコレクション内のすべての連鎖アサーションが空でない結果を返すように設計された決定論的なシードデータを備えています。make contract は、3 つのコレクションすべてをそれに対して実行します。CI もプッシュごとに同じことを行います。

2 · 主な機能

• ライブアラームデータと運用文書に対する自然言語チャット

• 2 つの MCP サーバーにわたるランタイムツール検出 — ハードコードされたツールリストなし

• 複数ステップのツールチェーン。あるツールの出力が次のツールの入力になります

• ハイブリッド文書検索 (BM25 + 密ベクトル、相互ランクで融合) とインライン引用

• 1 つ の回答に構造化ツール結果と非構造化文書エビデンスを結合

• 完全な実行トレース: どのサーバー、どのツール、どの引数、どのくらいの時間、どのような結果か

• 書き込み前の明示的な人間による確認。ツール契約で強制されます

• ツール障害、タイムアウト、無効なスキーマ、空の検索結果、モデルの拒否、API キーの欠落に対するグレースフルな劣化

3 · 技術スタック

4 · アーキテクチャ概要

5 つのサービス。GUI は REST と SSE を介して FastAPI オーケストレーターと通信します。オーケストレーターは、実行時に 2 つの MCP サーバーから検出したツールレジストリに対して一連のステップを計画し、各ステップの引数 (以前のステップで生成された値を含む) を解決し、ドキュメント検索をこれらのステップの 1 つとして実行し、1 つの引用付き回答を構成します。

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 を直接呼び出すことは決してありません。そのため、言語モデルにはベアラートークンへのコードパスがありません。つまり、トークンを読み取ったり、要求したり、プロンプトインジェクションによって漏洩させたりすることはできません。

• エンドツーエンドのリクエストフロー: docs/architecture.md

• コンポーネント、ADR、NFR、リスク、トレーサビリティ: docs/hld.md

• スキーマ、シグネチャ、アルゴリズム、ステートマシン: docs/lld.md

5 · MCP サーバーとツール

2 つの候補構築サーバー。完全な契約 — 入出力スキーマ、認証動作、エラー動作、タイムアウト、および 実際の リクエストとレスポンスの例を含む — は 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 個のマークダウンドキュメント (運転手順書、トラブルシューティングガイド、標準、安全指示、ベンダーブリーフィング) → 49 の見出しに沿ったチャンク → 埋め込み Chroma インデックス。

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

検索は BM25 と密ベクトルを融合し、以前のツール呼び出しで解決されたアセットによってフィルタリングし、弱い一致を飾る代わりに low_confidence を報告します。1 つのコーパスドキュメントには ライブプロンプトインジェクションペイロード が含まれているため、信頼境界は主張されるのではなくテストされます。

完全な設計 — チャンク化、メタデータ、融合、引用構築、信頼度、インジェクション防御、リフレッシュ: docs/rag-design.md。

7 · 設定

すべての値は環境変数です。.env.example は、安全なプレースホルダーを使用して各キーを文書化しています。シークレットはコミットされておらず、デモを実行するために必要もありません。

タイプ、デフォルト、利用サービスを含む完全なリファレンス: docs/lld.md §9。

8 · ビルドと実行

make が標準であり、CI で使用されるものです。make がない Windows では、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 を実行し、4 つの 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 — そして apps/frontend で npm run dev を実行します。

9 · テスト

make contract は newman (npm install -g newman) と実行中のシミュレーターを必要とします。

269 テスト、すべて合格、89% の行カバレッジ — 内訳は docs/coverage.md にあります。カバーしている内容:

LLM はエンドツーエンドを含むすべての場所でモックされているため、スイートは高速、無料、再現可能です。その意味については docs/known-limitations.md を参照してください。

10 · サンプルインタラクション

繰り返し発生するアラーム（受け入れシナリオ）。 5 つのステップ: アセットを解決 → その高重大度アラームを要約 → 同時発生ペアを相関 → 合理化候補を見つける → 解決したアセットでフィルタリングされた手順を取得。回答は、Discharge Pressure Low の後に Suction Strainer DP High が 31 回発生（リフト 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 の構造からの 2 つの文書化された逸脱:

• services/alarm-simulator/ — 概要は別途、候補者が構築するバックエンドを義務付けており、これは事前に命名されたフォルダの 1 つではありません。シミュレーター（統合対象システム）を connectors/（それに到達するクライアント）から分離しておくことは、両方を一緒に折りたたむよりも明確な分離です。

• docs/hld.md および docs/lld.md — 必須の docs/architecture.md（エントリポイントのまま）とともに追加されました。

ガイドラインは、明確に文書化されている場合、同等の構造を許可します。必須のディレクトリ名はハイフンで区切られているため、有効な Python パッケージ名ではないため、各ディレクトリは正しく名前が付けられたパッケージ（mcp-servers/alarm-management/alarm_mcp/）を保持し、pyproject.toml のトップレベルインポートにマッピングされます。

12 · 前提条件

1. Alarm Management API は存在しないため、Postman コレクションはその仕様として扱われ、シミュレーターはそれらを正確に満たすように構築されています。コレクションが沈黙していた場合（たとえば、チェーンコレクションにのみ表示されるフィルター）、コレクションのアサーションが権威となります。

2. アラーム ID、アセット ID、タイムスタンプは再現可能です。 シードは固定されているため、デモ、テスト、Postman 実行はすべて同じデータを参照します。

3. 相関とは、同じアセット上のラグウィンドウ内での同時発生を意味します。 統計的有意性テストは合成データの範囲外です。

4. 1 テナント、1 サイトエステート。 テナント識別子は検索やツール認証を通じてスレッド化されません。

5. GUI からバックエンドへのホップは認証されていません。これはローカルデモでは許容され、制限事項で指摘されています。

6. docker compose up がサポートされているパスです。 手動パスは §8 で文書化されていますが、CI が実行するのは compose ファイルです。

13 · 既知の制限事項と将来の改善点

正直なスコープ境界。それぞれについて、より多くの時間があれば異なる方法で行うことを示しています: docs/known-limitations.md。次に来るもの（私が行う順序）: docs/future-improvements.md。

14 · デモ

スクリーンショット

make screenshots によって実行中のスタックからキャプチャされているため、古くなることなく再生成できます: docs/screenshots/。

またキャプチャ: 空の状態 と 引用チップ付きの回答。

ビデオ

リンク: 追加予定 — 録画されたウォークスルースクリプトについては docs/demo.md を参照してください。

受け入れシナリオのエンドツーエンド、スキーマ検査付きツールディスカバリー、実行タイムライン、エビデンスに解決される引用チップ、書き込み確認ゲート、そして障害パス（シミュレーターがセッション途中で停止され、再試行、劣化した回答、正直なギャップを示す）をカバーしています。

ライセンス

MIT — LICENSE を参照。