incident-assistant — MCP "Hello World"

MCP（Model Context Protocol）サーバーのテスト用実装で、MCPの本/コースの「インシデントレスポンス」演習に沿って構築したものです。違いは、クライアントとしてGemini CLIではなくClaude Codeに接続している点です。

このサーバーは本番システムのアラートダッシュボードをシミュレートし、以下を公開します：

• アクティブなアラートの一覧（モックデータ）を持つリソース（resource://incidents/active）。

• アラートを解決するためにサービスを「再起動」するツール（resolve_incident）。成功率は80%にシミュレートされています（失敗パスも確認できます）。

ソース: src/index.ts

スタック

• @modelcontextprotocol/sdk — TypeScript/Node用の公式MCP SDK。

• stdioトランスポート（クライアントがサーバーをサブプロセスとして起動し、stdin/stdoutで通信します）。

• TypeScriptをdist/にコンパイル（tsconfig.jsonを参照）。

1. インストールとビルド

npm install
npx tsc

これによりsrc/index.tsがdist/index.js（サーバーを起動するエントリポイント）にコンパイルされます。

注: サーバー内のログ出力には意図的にconsole.errorを使用しています。stdoutはMCPのJSON-RPCプロトコル用に予約されているため、そこでconsole.logを使うとクライアントとの通信が壊れます。

2. Claude Codeにサーバーを登録する

本（Gemini CLIのsettings.jsonを使用）とは異なり、Claude CodeではローカルMCPサーバーをclaude mcp addコマンドで登録します：

cd /absolute/path/to/incident-assistant
claude mcp add --scope project incident-assistant -- node /absolute/path/to/incident-assistant/dist/index.js

重要なポイント:

• --はclaude mcp add自身のフラグと、サーバーを起動する実際のコマンドを区切ります。

• dist/index.jsへの絶対パスを使用します（相対パスだと、.mcp.jsonの場所ではなくclaudeを起動したディレクトリ基準で解決されます）。

• --scope projectはリポジトリルートの.mcp.jsonに設定を保存します（gitでバージョン管理可能）。代替: --scope local（自分だけにプライベート、共有されない）または--scope user（自分の全プロジェクトで利用可能、~/.claude.jsonに保存）。

これにより、あなたのマシンの絶対パスが埋め込まれたローカルの.mcp.jsonが生成されます。そのパスはあなたの環境固有のものなので、.mcp.json自体はgitignoreされています。代わりにリポジトリには.mcp.json.exampleが同梱されており、プレースホルダーパスを使った期待される形を示しています：

{
  "mcpServers": {
    "incident-assistant": {
      "type": "stdio",
      "command": "node",
      "args": ["/absolute/path/to/incident-assistant/dist/index.js"]
    }
  }
}

3. サーバーを承認する

.mcp.jsonはプロジェクトファイル（共有リポジトリから来る可能性がある）のため、Claude Codeは初回に明示的な承認を求めます：

claude

起動時にincident-assistantの信頼プロンプトが表示されるので、プロジェクトごとに一度承認してください（後でサーバーのコマンド/引数が変わらない限り）。

4. 確認

claude mcp list
claude mcp get incident-assistant

承認後に期待される出力:

incident-assistant: node /absolute/path/to/incident-assistant/dist/index.js - ✔ Connected

claudeセッション内で/mcpを実行すると、サーバーが利用可能なツール/リソースが一覧表示されます。

5. デモ — 実際の結果

エージェントへのプロンプト: 「重大なアラートはありますか？ あれば修正して結果を教えてください」

エージェントの動作:

1. 利用可能なMCPリソースを一覧表示し（listMcpResources）、resource://incidents/activeを見つけました。

2. そのリソースを読み取り（readMcpResource）、モックアラートを取得しました:

   ID	サービス	ステータス	メッセージ
   ALRT-001	auth-api	🔴 CRITICAL	Memory leak detected
   ALRT-002	payment-gateway	🟡 WARNING (not critical)	Latency > 500ms

3. 重大なのはALRT-001だけだと特定し、serviceName: "auth-api"を指定してresolve_incidentツールを呼び出しました。

4. 結果:

   ✅ 修正済み: auth-apiはメモリリークを解消するために正常に再起動されました（ALRT-001、 CRITICAL）。再起動は成功しました。

   ⚠️ 未対応: payment-gatewayは依然としてWARNING（レイテンシ > 500ms）を表示していますが、 重大ではないためそのままにされました。

   エージェントのメモ: 再起動は症状を解消するだけで、根本原因を必ずしも取り除くわけではありません。リークが再発しないことを確認するため、auth-apiのメモリを監視し続ける価値があります。

5. 明示的に*「payment-gatewayも再起動して」*と依頼すると、エージェントはserviceName: "payment-gateway"を指定して再度resolve_incidentを呼び出します（正確な結果はここでは記録されていません。80%のシミュレート成功率に依存するため、✅成功か❌ FAILUREのどちらかになります）。

これで完全なループが確認できます: MCPクライアント（Claude Code）→ リソース/ツールの発見 → リソースの読み取り → 判断 → ツール呼び出し → 結果。

クレジット

この演習はmaliksahil/mcp-incident-assistantに基づいています / から学んだものです。元のチュートリアルではMCPクライアントとしてGemini CLIを使用していますが、このリポジトリでは同じサーバーをClaude Codeで使用するように適合させています。

注意点 / 落とし穴

• サーバーはWSL上で動作します。このセットアップではClaude CodeもWSLターミナルから起動されるため、.mcp.json内のパスはネイティブのLinuxパス（例: /home/<user>/...）であり、WindowsのUNCパス（\\wsl.localhost\...）ではありません。

• src/index.tsを編集した場合は、変更を反映する前に再ビルド（npx tsc）が必要です。サーバーは.tsファイルから直接ではなくdist/index.jsから起動するためです。

• resolve_incidentは意図的に80%の成功率（Math.random() > 0.2）をシミュレートしているため、エージェントが成功と失敗（isError: true）の両方のケースをどう処理するかを観察できます。