MCP Server Template

MCP サーバーテンプレート

TypeScript で Model Context Protocol（MCP）サーバーを作成するためのテンプレートです。このテンプレートは、適切なツール、型安全性、ベストプラクティスを備えた、MCP 互換サーバーを構築するための確かな基盤を提供します。

特長

• 🚀 TypeScript を全面的にサポート
• 🏗️ コンテナーベースの依存性注入
• 📦 DataProcessor インターフェースを備えたサービスベースのアーキテクチャ
• 🛠️ テスト付きのツール実装例
• 🧪 Vitest テストフレームワーク
• 📝 型定義
• 🔌 MCP SDK との統合

はじめに

開発

1. 依存関係をインストールします：

   npm install
   

2. ホットリロードで開発サーバーを起動します：

   npm run dev
   

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

   npm run build
   

4. テストを実行します：

   npm test
   

5. 本番サーバーを起動します：

   npm start
   

プロジェクト構成

src/
├── index.ts          # Entry point
├── interfaces/       # Interface definitions
│   └── tool.ts      # DataProcessor interface
└── tools/           # Tool implementations
    └── example.ts   # Example tool

ツールの作成

1. src/tools/example.ts の例に従って、ツールとハンドラーをエクスポートします：

   // In your-tool.ts
   export const YOUR_TOOLS = [
     {
       name: "your-tool-name",
       description: "Your tool description",
       parameters: {
         // Your tool parameters schema
       },
     },
   ];
   
   export const YOUR_HANDLERS = {
     "your-tool-name": async (request) => {
       // Your tool handler implementation
       return {
         toolResult: {
           content: [{ type: "text", text: "Result" }],
         },
       };
     },
   };
   

2. src/index.ts の ALL_TOOLS および ALL_HANDLERS 定数にツールを登録します：

   // In src/index.ts
   import { YOUR_TOOLS, YOUR_HANDLERS } from "./tools/your-tool.js";
   
   // Combine all tools
   const ALL_TOOLS = [...EXAMPLE_TOOLS, ...YOUR_TOOLS];
   const ALL_HANDLERS = { ...EXAMPLE_HANDLERS, ...YOUR_HANDLERS };
   

サーバーは次の処理を自動的に行います：

• 利用可能なツールの一覧にツールを追加します
• 入力を検証します
• ツールへのリクエストを処理します
• MCP プロトコルに従ってレスポンスをフォーマットします

テスト

このテンプレートには、ローカルテスト用の TestClient と、視覚的なデバッグ用の MCP Inspector が組み込まれています。

TestClient の使用

TestClient を使うと、ツールを簡単にテストできます：

import { TestClient } from "./utils/TestClient";

describe("YourTool", () => {
  const client = new TestClient();

  it("should process data correctly", async () => {
    await client.assertToolCall(
      "your-tool-name",
      { input: "test" },
      (result) => {
        expect(result.toolResult.content).toBeDefined();
      }
    );
  });
});

MCP Inspector の使用

このテンプレートには、ツールを視覚的にデバッグするための MCP Inspector が組み込まれています：

1. Inspector を起動します：

   npx @modelcontextprotocol/inspector node dist/index.js
   

2. http://localhost:5173 で Inspector の UI を開きます

Inspector では次のことができます：

• ツールをテストするための視覚的なインターフェース
• リクエストとレスポンスのリアルタイム監視
• ツールのメタデータの確認
• 対話型テスト環境

Cursor を使ったローカルテスト

Cursor で MCP サーバーをローカルにテストするには：

1. パッケージをビルドしてリンクします：

   npm run build
   npm run link
   

2. バイナリが動作することを確認します：

   npx example-mcp-tool
   

3. Cursor にサーバーを追加します：

   • Cursor の設定を開きます
   • Features タブに移動します
   • MCP Servers セクションまでスクロールします
   • 「Add Server」をクリックします
   • 「Command」タイプを選択します
   • 名前を付けます（例：「Local Example Tool」）
   • コマンドを入力します：npx example-mcp-tool
   • 「Confirm」をクリックします

4. MCP Servers セクションでサーバーが実行中と表示されていることを確認し、Cursor でサーバーが正しく起動したことを確認します。

注：コードを変更した場合は、忘れずに再ビルドして再リンクしてください：

npm run build
npm run link

テストが終わったら、パッケージのリンクを解除できます：

npm run unlink

これにより、開発中に作成されたグローバルシンボリックリンクが削除されます。