swapi_mcp

可観測な AI エージェントを構築するための、小規模なエンドツーエンドのリファレンスプロジェクトです。Star Wars API をラップする MCP サーバー、それを操作する Claude エージェント、そして Web チャット UI で構成され、すべて OpenTelemetry と Grafana Cloud（分散トレース、RED メトリクス、フロントエンド RUM、AI／エージェント可観測性）で計装されています。

このプロジェクトは、1つの実行可能なコードベースで各構成要素がどのように組み合わさるかを示すために存在します。すなわち、MCP ツール境界、エージェントのツール使用ループ、そしてブラウザのクリックから上流の HTTP 呼び出しに到達して再び戻ってくるまでのフルスタックトレーシングです。

このリポジトリの内容

MCP（stdio）を介して相互に通信する2つの部分で構成されています：

MCP サーバー（src/index.ts、src/tools/）— Star Wars API を6つのリソース（people、planets、films、species、vehicles、starships）にわたる18のツールとしてラップします。各リソースにつき search_、get-all、get-by-id を1つずつ提供します。これは単純なツールプロバイダーであり、意思決定は行いません。

エージェント（src/agent/）— 意思決定を行う側です：

• mcpClient.ts — ビルド済みサーバーを stdio 経由で起動し、MCP クライアントとして接続します。

• agent.ts — 手動のツール使用ループです。質問とサーバーのツールを Claude に送信し、要求された各ツールを MCP 経由で実行して結果をフィードバックし、完了するまで繰り返します。

• main.ts — CLI エントリーポイントです。

• server.ts + public/index.html — HTTP サーバーとシングルページのチャット UI です。

Related MCP server: SWAPI MCP Server

可観測性

以下はすべてオプションであり、環境変数によって有効化されます。これらがなくてもエージェントは問題なく動作します。

• 分散トレーシング（OpenTelemetry → Tempo）：1つのトレースが browser → POST /ask → agent.turn → llm.request / tool.call → tool.execute → swapi.fetch という一連の流れを3つのサービス（swapi-web、swapi-agent、swapi-mcp-server）にわたってカバーします。トレースコンテキストは、リクエストの _meta を介して MCP 境界を越えて伝播されます。

• RED メトリクス（→ Mimir）：ツールごと・LLM 呼び出しごとの rate／errors／duration ヒストグラムに加え、コスト用のトークン使用量カウンターを提供し、model、error、error.type のタグが付きます。

• フロントエンド RUM（Grafana Faro）：Web Vitals、JS エラー、ブラウザ→バックエンドのトレース伝播。

• AI／エージェント可観測性（@grafana/agent-o11y）：正規化された LLM ジェネレーションとツール実行。

• デモ用フォールトインジェクション（src/chaos.ts）：オプションで、1つのリソースにシミュレートされた 503 を返させ、別のリソースの実行を50%遅くします。これにより、ダッシュボードに実際のエラーとレイテンシのシグナルが表示されます。

前提条件

• Node.js 22+（--env-file を使用）

• Yarn 4（Corepack 経由）

• Anthropic API キー（エージェント用）

• Grafana Cloud アカウント（オプション — 可観測性機能のみに必要）

セットアップ

yarn install
yarn build

MCP サーバーを直接使用する（例：Claude Desktop）

ビルド済みサーバーを MCP クライアントに指定します：

{
  "mcpServers": {
    "swapi": { "command": "node", "args": ["/absolute/path/to/swapi_mcp/build/index.js"] }
  }
}

エージェントを実行する

.env ファイル（git で無視されます）を作成し、少なくとも Anthropic のキーを設定します：

ANTHROPIC_API_KEY=sk-ant-...

次に：

yarn dev                              # build + serve the web UI at http://localhost:8787
yarn ask "Who is Luke's homeworld?"   # one-shot CLI

環境変数

注記

これは学習用／デモ用のプロジェクトです。データは SWAPI の静的ミラーから取得しています。SWAPI はアクションではなく関連（キャラクターが映画に「登場する」など）をモデル化しているため、回答もそれに合わせた表現になっています。

ライセンス

MIT