MCP Chat with Claude

Claude との MCP チャット

Model Context Protocol（MCP）と Anthropic の Claude LLM の連携を実演するフルスタックアプリケーションです。MCP ツールを活用するインタラクティブなチャットインターフェースを提供します。

プロジェクトの概要

このプロジェクトは、次の3つの主要コンポーネントで構成されています。

1. 複数の MCP サーバー：LLM が利用できるさまざまな専門ツールを提供する、Model Context Protocol を実装した Node.js サーバーです。
2. ホストアプリ：ユーザー、Claude AI、MCP サーバー間の仲介役となる Express サーバーです。
3. ウェブクライアント：ホストアプリと通信する、ブラウザベースのチャットインターフェースです。

機能

• Claude AI と対話できるチャットインターフェース
• 会話とツールの実行内容を表示する2パネル UI
• 複数の MCP サーバーからツールを動的に検出
• 各サーバーの異なるパラメーターを持つ専門ツールに対応
• MCP を介した Claude のツール使用を適切に処理

プロジェクト構成

├── client/                 # Host app & web client
│   ├── dist/               # Compiled TypeScript
│   ├── host-app.ts         # Host application server
│   ├── chat.js             # Frontend chat interface logic
│   ├── index.html          # Main web interface
│   ├── styles.css          # Styling for web interface
│   ├── package.json        # Client dependencies
│   └── mcp-client-example.ts # Example MCP client for testing
│
├── server/                 # MCP servers
│   ├── dist/               # Compiled TypeScript
│   ├── mcp-server-todoplan.ts # TodoPlan MCP server implementation
│   ├── mcp-server-project.ts  # Project MCP server implementation
│   └── package.json        # Server dependencies
│
├── .gitignore              # Git ignore file
└── README.md               # Project documentation

前提条件

• Node.js 17 以降
• npm または yarn
• Anthropic API キー

インストール

1. リポジトリをクローンします。

   git clone https://github.com/jiangyan/typescript-mcp-demo.git
   cd typescript-mcp-demo
   

2. クライアントとサーバーの両方の依存関係をインストールします。

   cd server
   npm install
   cd ../client
   npm install
   

3. クライアントディレクトリに、Anthropic API キーを記述した .env ファイルを作成します。

   ANTHROPIC_API_KEY=your-api-key-here
   MCP_SERVER_TODOPLAN_URL=http://localhost:8000/sse
   MCP_SERVER_PROJECT_URL=http://localhost:8001/sse
   PORT=3000
   

4. サーバーディレクトリに .env ファイルを作成します。

   MCP_SERVER_TODOPLAN_PORT=8000
   MCP_SERVER_PROJECT_PORT=8001
   

セットアップと起動

ステップ1：MCP サーバーを起動する

# Terminal 1: Start the TodoPlan MCP server
cd server
npm run build:todoplan
npm run start:todoplan

# Terminal 2: Start the Project MCP server
cd server
npm run build:project
npm run start:project

TodoPlan MCP サーバーはデフォルトでポート8000、Project MCP サーバーはデフォルトでポート8001で起動します。

ステップ2：ホストアプリ（ウェブサーバー）を起動する

cd client
npm run build
npm start

ウェブサーバーはデフォルトでポート3000で起動します。

ステップ3：チャットインターフェースにアクセスする

ブラウザーを開き、次の場所にアクセスします。

http://localhost:3000

利用可能な MCP ツール

MCP サーバーは、Claude が利用できる次のツールを提供します。

1. todoplan-server_get-todo：指定したカテゴリーの ToDo 項目を取得します

   • パラメーター：
     • category：文字列（例："life"、"work"、"family"、"friends"）

2. todoplan-server_get-plan：全体の計画を取得します

   • パラメーター：なし

3. project-server_get-project-details：指定したプロジェクトの詳細を取得します

   • パラメーター：
     • project_name：文字列（例："Earth"、"Mars"、"Jupiter"、"Saturn"）

追加の例

このプロジェクトには、ウェブインターフェースを使わずにプログラムから MCP サーバーへ接続する方法を実演する、スタンドアロンの MCP クライアントの例（mcp-client-example.ts）が含まれています。

この例を実行するには：

cd client
npm run client

開発

MCP サーバーの開発

MCP サーバーに新しいツールを追加するには：

1. サーバーファイルを開きます（例：server/mcp-server-todoplan.ts）。
2. 既存のパターンに従って、新しいツール定義を追加します。

   server.tool("tool-name",
     { param1: z.string() },
     async ({ param1 }) => {
       // Tool implementation
       return {
         content: [{ type: "text", text: "Result" }]
       };
     }
   );
   

3. サーバーを再ビルドして再起動します。

ホストアプリの開発

ホストアプリは次の要素で構成されています。

• バックエンド（host-app.ts）：Claude および複数の MCP サーバーと通信する Express サーバー
• フロントエンド（chat.js、index.html、styles.css）：バックエンドと通信するチャットインターフェース

アーキテクチャ

┌─────────────┐       ┌────────────────┐       ┌───────────────┐
│             │       │                │       │               │
│  Web UI     │◄─────►│  Host App      │◄─────►│  MCP Servers  │
│  (Browser)  │       │  (Express)     │       │  (Node.js)    │
│             │       │                │       │               │
└─────────────┘       └───────┬────────┘       └───────────────┘
                              │
                              ▼
                      ┌───────────────┐
                      │               │
                      │  Claude API   │
                      │  (Anthropic)  │
                      │               │
                      └───────────────┘

複数の MCP サーバーの実装

このプロジェクトでは、Claude がさまざまな専門サーバーのツールにアクセスできる、マルチサーバー MCP アーキテクチャを実装しています。

サーバーの設定

このプロジェクトには、次の2つの異なる MCP サーバーが含まれています。

1. TodoPlan MCP サーバー（server/mcp-server-todoplan.ts）：ToDo と計画を管理するツールを提供します

   • get-todo：指定したカテゴリーの ToDo 項目を取得します
   • get-plan：全体の計画を取得します

2. Project MCP サーバー（server/mcp-server-project.ts）：プロジェクト情報にアクセスするツールを提供します

   • get-project-details：指定したプロジェクトの詳細を取得します

ホストアプリとの連携

ホストアプリ（client/host-app.ts）は、次の処理を行うよう実装されています。

1. 複数の MCP サーバーに同時に接続する
2. 名前の競合を避けるため、サーバー名をアンダースコアで区切ってツール名の先頭に付ける（例：todoplan-server_get-todo）
3. 先頭の名前に基づいて、ツール呼び出しを適切なサーバーに振り分ける
4. LLM に一元化されたツールセットを提示する

クエリの例

複数のサーバーとの連携をテストするには、次のクエリをお試しください。

• 「プロジェクト Earth について教えてください」
• 「仕事カテゴリの ToDo は何ですか？」
• 「仕事カテゴリの ToDo を見つけて、関連するプロジェクトを教えてください」
• 「私の予定は何ですか？」

トラブルシューティング

1. 接続の問題：両方の MCP サーバーとホストアプリが実行中であることを確認し、コンソールにエラーメッセージが表示されていないか確認してください。

2. ツールが見つからない：MCP サーバーが実行中であること、ツール名が完全に一致していることを確認してください。

3. API キーのエラー：クライアントの .env ファイルに Anthropic API キーが正しく設定されていることを確認してください。

4. ツールの使用エラー：詳細なエラー情報については、応答パネルを確認してください。

5. 無効なツール名の形式：ツール名が Anthropic の要件に沿った形式（英数字、アンダースコア、ハイフンのみ）であることを確認してください。

ライセンス

MIT

謝辞

• Model Context Protocol
• Anthropic Claude API