TestMcpServer

TestMcpServer

はじめに

この MCP サーバーの実装例では、Anthropic のオープンソースである Model Context Protocol を使用しています。 既存のサンプルは見ていて耐え難く、ほとんどが非常に長い1行ファイルで、内容を読み進めるのもとても大変だと感じていました。 この扱いやすい構成によって、現在公開されているものより理解しやすく、取り組みやすいサンプルをユーザーに見つけてもらいたいと考えています。 次の MCP サーバープロジェクトの基盤としてご活用ください。

Node、npm、typescript が必要です。

機能

MCP サーバーは現在、以下のツールを提供しています。

数学ツール

• 加算：2つの数値を加算します
• 減算：ある数値から別の数値を減算します
• 乗算：2つの数値を乗算します
• 除算：ある数値を別の数値で除算します（ゼロ除算を防止します）
• 平方根：数値の平方根を計算します
• べき乗：ある数値を別の数値のべき乗にします
• 剰余：ある数値を別の数値で除算したときの余りを計算します
• 対数：指定した底で数値の対数を計算します
• 平均：2つの数値の算術平均を計算します

画像処理ツール

• 画像変換：画像を形式間で変換します（PNG/JPG から WebP/AVIF）。圧縮にも対応しています
• 画像リサイズ：画像のサイズを変更します。必要に応じて形式も変換できます

ファイルシステムツール

• ツリー：指定したパスのディレクトリツリー構造を取得します

Git ツール

• コミット履歴：最近の git コミットを表示します
• 差分：リビジョン間の差分を表示します

テキストユーティリティ

• 単語数：行数、単語数、文字数をカウントします
• 検索と置換：ファイル内の検索と置換を実行します

ネットワークツール

• HTTP リクエスト：簡単な HTTP リクエストを実行します
• Ping：ホストへの接続を確認します

日時ユーティリティ

• タイムスタンプ変換：タイムスタンプと日付を相互に変換します
• スケジュール：短い遅延の後にコマンドを実行します

セキュリティツール

• ハッシュ：テキストまたはファイルのハッシュを生成します
• チェックサム：ファイルのチェックサムを検証します

ブラウザツール

• コンソールキャプチャ：指定した URL からブラウザのコンソールログ（エラー、警告、情報、ログ）を取得します

すべてのツールには、堅牢に動作するよう、包括的なエラー処理と入力検証が含まれています。

インストール

リポジトリをクローンしたら、npm install を実行してください。 使用するスクリプトについては package.json を確認してください。

サーバーをビルドするには npm run build を実行してください。 サーバーを実行するには node build/index.js を実行してください。 ただし、次の方法をおすすめします。 npm run dev を実行すると、保存時に変更を監視して再ビルドし、インスペクターを再実行するため、localhost:5173 でテストできます。

Cursor で MCP サーバーを実行する前に、まずビルドする必要があります。

MCP ツールのテスト

このプロジェクトには、Jest を使用した MCP ツールの包括的なテストフレームワークが含まれています。テストでは、すべてのツールが正しく動作し、エッジケースを適切に処理することを確認します。

テストの実行

すべてのテストを実行するには：

npm test

カバレッジレポート付きですべてのテストを実行するには：

npm run test:coverage

特定のテストを実行するには：

npm test -- --testPathPattern=tests/maths/

テスト構成

• コントローラーテスト：コントローラーハンドラーメソッドを直接テストします（tests/maths/、tests/browser/ など）
• ファイルシステムテスト：一貫したテストのためにフィクスチャディレクトリを使用します
• ブラウザテスト：テスト用 HTML ページを使ってブラウザーの操作をテストします
• MCP シミュレーションテスト：MCP のリクエスト／レスポンスフローを通じてツールをテストします
• エッジケーステスト：検証とエラー処理に特化したテストです（tests/maths/validation-edge-cases.test.ts）

テスト方針

テストスイートでは、以下のような包括的なアプローチを採用しています。

1. 基本機能テスト - 有効な入力でツールが正しく動作することを確認します
2. エッジケーステスト - ゼロ値や負の数など、境界条件をテストします
3. エラー処理テスト - 無効な入力に対して適切なエラーレスポンスが返されることを確認します
4. 検証テスト - null／undefined 値や数値以外の入力などを使って入力検証をテストします
5. オーバーフローテスト - 極端に大きな値での動作をテストします

新しいテストの追加

1. tests/ 配下の適切なカテゴリフォルダーにテストファイルを作成します
2. MCP ツールの呼び出しをシミュレートするには、tests/utils/mcpTestHelper.ts のユーティリティを使用します
3. ファイルシステムのテストでは、tests/fixtures/ のフィクスチャを使用します
4. ブラウザのテストでは、テスト用の HTML ファイルを使用するか、作成します
5. バリデーションのエッジケースについては、専用のバリデーションテストファイルにテストを追加します

MCP サーバー - 新しいツールの追加

このガイドでは、MCP サーバーに新しいツールを追加する方法を説明します。このプロセスは、主に 4 つの要素で構成されます。

1. ツール定義（/src/definitions/）

まず、適切なカテゴリフォルダー（例：maths/）にツール定義を作成します。

// Example: src/definitions/maths/addition.ts
import { Tool } from "@modelcontextprotocol/sdk/types.js";

export const ADDITION: Tool = {
  name: "addition",
  description: "Add two numbers together",
  inputSchema: {
    type: "object",
    properties: {
      a: {
        type: "number",
        description: "First number to add",
      },
      b: {
        type: "number",
        description: "Second number to add",
      },
    },
    required: ["a", "b"],
  },
};

次に、カテゴリのメインファイルに追加します。

// src/definitions/maths/main.ts
import { ADDITION } from "./addition.js";
import { MULTIPLICATION } from "./multiplication.js";

const MATHS_TOOLS = [ADDITION, MULTIPLICATION] as const;

export default MATHS_TOOLS;

2. コントローラーの実装（/src/controllers/）

適切なコントローラーにハンドラーメソッドを追加します。

// src/controllers/MathsController.ts
class MathsController {
  async handleAddition(a: number, b: number) {
    try {
      const result = a + b;
      return {
        content: [
          {
            type: "text",
            text: `Sum: ${result}`,
          },
        ],
        isError: false,
      };
    } catch (error) {
      return {
        content: [
          {
            type: "text",
            text: `Error calculating sum: ${
              error instanceof Error ? error.message : String(error)
            }`,
          },
        ],
        isError: true,
      };
    }
  }
}

3. ツールレジストリ（/src/utils/toolRegistry.ts）

controllerMap にツールを登録します。

const controllerMap: ControllerMap = {
  // Math tools
  addition: {
    controller: MathsController,
    handlerMethod: "handleAddition",
  },
  multiplication: {
    controller: MathsController,
    handlerMethod: "handleMultiplication",
  },
};

レジストリは、主に 2 つの関数をエクスポートします。

// Get tool definitions for server registration
export function getToolDefinitions() {
  return {
    MATHS_TOOLS,
  };
}

// Get handler for tool execution
export function getToolHandler(toolName: string) {
  const mapping = controllerMap[toolName];
  if (!mapping) {
    return null;
  }

  const controllerInstance = new mapping.controller();
  return async (args: any) => {
    return await controllerInstance[mapping.handlerMethod](
      ...Object.values(args)
    );
  };
}

4. サーバー設定（/src/index.ts）

サーバーは、ツールレジストリを使用するように設定されています。

const tools = getToolDefinitions();

const server = new Server(
  {
    name: "mcp-server",
    version: "0.1.0",
  },
  {
    capabilities: {
      tools: getToolDefinitions(), // Register tools array
    },
  }
);

// List available tools
server.setRequestHandler(ListToolsRequestSchema, async () => ({
  tools: tools,
}));

// Handle tool calls
server.setRequestHandler(CallToolRequestSchema, async (request) => {
  try {
    const handler = getToolHandler(request.params.name);
    if (!handler) {
      return toolController.getUnknownToolResponse(request.params.name);
    }
    return await handler(request.params.arguments);
  } catch (error) {
    return toolController.getErrorResponse(error);
  }
});

規約

1. ツール名：小文字を使用します（例：addition、multiplication）
2. ハンドラーメソッド：ツール名をパスカルケースにした名前の前に handle を付けます（例：handleAddition、handleMultiplication）
3. ツールカテゴリ：関連するツールは、definitions/ 配下の専用ディレクトリにまとめます
4. コントローラー：関連するハンドラーは、カテゴリ名にちなんだコントローラークラスにまとめます（例：MathsController）

使用例

1. src/definitions/category/toolname.ts にツール定義を作成します
2. カテゴリの main.ts にツールを追加します
3. 適切なコントローラーにハンドラーメソッドを追加します
4. toolRegistry.ts の controllerMap にツールを登録します
5. 新しいツールをテストします

Cursor に MCP サーバーを追加

1. 設定を開きます
2. Features に移動します
3. MCP Servers までスクロールします
4. Add new MCP server をクリックします
5. 任意の name を MCP サーバーに付けます
6. type には command を使用します
7. ローカルで使用する場合のサーバー URL は node <absolute path to project>\build\index.js> です

緑色に点灯し、登録済みのツールが一覧表示されます。