MCP Server Implementation in TypeScript

TypeScript での MCP サーバー実装

これは、Model Context Protocol（MCP）サーバーの TypeScript 実装です。このサーバーは、データベースとのやり取りやウェブ検索を行うための一連のツールを提供します。

機能

• MCP プロトコルの実装
• SQLite データベースとの連携
• ウェブ検索機能
• RESTful API エンドポイント
• Swagger UI によるインタラクティブな API ドキュメント
• CORS サポート
• セッション管理
• リアルタイム更新のための Server-Sent Events（SSE）

前提条件

• Node.js（v14 以降）
• npm（v6 以降）

インストール

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

git clone https://github.com/yourusername/mcp-typescript-workshop.git
cd mcp-typescript-workshop

2. 依存関係をインストールします。

npm install

3. プロジェクトをビルドします。

npm run build

サーバーの起動

開発モード

npm run dev

本番モード

npm start

サーバーはデフォルトでポート 3000 で起動します。以下にアクセスできます。

• API ドキュメント：http://localhost:3000/api-docs
• MCP エンドポイント：http://localhost:3000/mcp

サーバーのテスト

curl コマンドを使用してサーバーをテストできます。すべての機能をテストする一連の手順を以下に示します。

1. 新しいセッションを初期化します。

curl -v -X POST http://localhost:3000/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","method":"initialize","params":{},"id":1}'

後続のリクエストで必要となるセッション ID が返されます。

2. 利用可能なツールを一覧表示します。

curl -v -X POST http://localhost:3000/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "mcp-session-id: YOUR_SESSION_ID" \
  -d '{"jsonrpc":"2.0","method":"list_tools","params":{},"id":2}'

3. すべての従業員を取得します。

curl -v -X POST http://localhost:3000/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "mcp-session-id: YOUR_SESSION_ID" \
  -d '{"jsonrpc":"2.0","method":"call_tool","params":{"name":"get_employees","arguments":{}},"id":3}'

4. 部門で従業員を検索します。

curl -v -X POST http://localhost:3000/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "mcp-session-id: YOUR_SESSION_ID" \
  -d '{"jsonrpc":"2.0","method":"call_tool","params":{"name":"search_employees","arguments":{"department":"Engineering"}},"id":4}'

5. ウェブ検索を実行します。

curl -v -X POST http://localhost:3000/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "mcp-session-id: YOUR_SESSION_ID" \
  -d '{"jsonrpc":"2.0","method":"call_tool","params":{"name":"web_search","arguments":{"query":"Model Context Protocol"}},"id":5}'

6. セッションを終了します。

curl -v -X DELETE http://localhost:3000/mcp \
  -H "mcp-session-id: YOUR_SESSION_ID"

注：YOUR_SESSION_ID を、初期化リクエストで受け取ったセッション ID に置き換えてください。

想定されるレスポンス

1. 初期化レスポンス：

{
  "jsonrpc": "2.0",
  "result": {
    "sessionId": "e6c389d7-e90a-4d09-a916-47bc5edd365e",
    "serverInfo": {
      "name": "workshop-typescript-server",
      "version": "1.0.0"
    }
  },
  "id": 1
}

2. 従業員の取得レスポンス：

{
  "jsonrpc": "2.0",
  "result": {
    "content": [{
      "type": "text",
      "text": "Employees:\nID: 1, Name: Alice Johnson, Department: Engineering, Salary: $85000\nID: 2, Name: Bob Smith, Department: Marketing, Salary: $62000\nID: 3, Name: Carol Davis, Department: Engineering, Salary: $92000\nID: 4, Name: David Wilson, Department: Sales, Salary: $58000\n"
    }]
  },
  "id": 3
}

API ドキュメント

サーバーの実行中は、API ドキュメントを http://localhost:3000/api-docs で確認できます。ドキュメントには以下が含まれます。

• 利用可能なすべてのエンドポイント
• リクエスト／レスポンスのスキーマ
• インタラクティブなテストインターフェース
• リクエストとレスポンスの例

利用可能なエンドポイント

POST /mcp

MCP 通信のメインエンドポイントです。以下を処理します。

• セッションの初期化
• ツールの一覧表示
• ツールの実行

GET /mcp

リアルタイム更新のための Server-Sent Events（SSE）エンドポイントです。

DELETE /mcp

MCP セッションを終了するためのエンドポイントです。

利用可能なツール

1. get_employees

   • 説明：データベースからすべての従業員を取得します
   • 入力パラメーターは不要です

2. web_search

   • 説明：ウェブ上の情報を検索します
   • 入力パラメーター：
     • query（string）：検索クエリ

3. search_employees

   • 説明：部門または名前で従業員を検索します
   • 入力パラメーター：
     • department（string、任意）：検索する部門
     • name（string、任意）：検索する名前

セッション管理

サーバーはセッション ID を使用して、リクエスト間の状態を維持します。セッション ID は以下のとおりです。

• 初期化時に生成されます
• 後続のリクエストでは mcp-session-id ヘッダーに指定する必要があります
• セッションの終了時に自動的にクリーンアップされます

エラー処理

サーバーは、以下の形式で詳細なエラーレスポンスを返します。

{
  "jsonrpc": "2.0",
  "error": {
    "code": -32000,
    "message": "Error description"
  },
  "id": null
}

開発

プロジェクト構成

src/
  ├── server.ts      # Main server implementation
  ├── swagger.ts     # API documentation configuration
  └── types/         # TypeScript type definitions

ビルド

npm run build

テスト

npm test

ライセンス

このプロジェクトは ISC License の下でライセンスされています。詳細については LICENSE ファイルを参照してください。

貢献

1. リポジトリをフォークします
2. 機能ブランチを作成します（git checkout -b feature/amazing-feature）
3. 変更をコミットします（git commit -m 'Add some amazing feature'）
4. ブランチにプッシュします（git push origin feature/amazing-feature）
5. Pull Request を作成します