MCP Hello World - MCP Server Mock for Testing

MCP Hello World - テスト用 MCP サーバーモック

これは TypeScript で実装された最小構成の Model Context Protocol（MCP）サーバーで、主にテストダブル／モックサーバーとして使用することを目的としています。

主な目的：MCP サーバーと連携するクライアントコードのユニットテストや統合テストに使用できる、軽量で制御しやすく、予測可能な MCP サーバー環境を提供します。

**注意：**このプロジェクトは、本番環境や汎用 MCP サーバーとしてのデプロイには適していません。

テストで mcp-hello-world を使用する理由

MCP クライアントに関連するコードをテストする際、通常は複雑で、応答が予測できず、実際の利用可能性にも左右される AI バックエンドサービスに依存したくないものです。テストダブルとして mcp-hello-world を使用すると、次のような利点があります。

1. 分離：ネットワークの問題や実際のサーバーの利用可能性を気にせず、クライアントのロジックに集中してテストできます。
2. 予測可能性：提供される echo と debug ツールはシンプルで固定された動作をするため、アサーションを簡単に記述できます。
3. 速度：起動と応答が速く、ユニットテストで頻繁に使用するのに適しています。
4. 軽量：依存関係が少なく、テスト環境に簡単に統合できます。
5. プロトコル対応：STDIO と HTTP/SSE の両方の MCP トランスポートプロトコルに対応しているため、接続方法ごとのクライアントの動作をテストできます。

インストール

このパッケージをプロジェクトの開発用依存関係として追加します。

# Using pnpm
pnpm add --save-dev mcp-hello-world

# Or using bun
bun add --dev mcp-hello-world

手動実行（テストのデバッグ用）

テストやクライアントの動作をデバッグするために、サーバーを手動で実行したい場合があります。

STDIO モード

特にローカル開発やデバッグ時に、最も簡単に実行できる方法です。

# Ensure it's installed (globally or in the project)
# Using npx (universal)
npx mcp-hello-world

# Or using pnpm dlx
pnpm dlx mcp-hello-world

# Or using bunx
bunx mcp-hello-world

サーバーは標準入力をリッスンし、MCP の応答を標準出力に出力します。MCP Inspector などのツールを使用してプロセスに接続できます。

このサーバーを MCP クライアントで設定するには、次の内容を設定に追加します。

{
  "mcpServers": {
    "mcp-hello-world": {
      "command": "npx",
      "args": ["mcp-hello-world"]
    }
  }
}

HTTP/SSE モード

ネットワークインターフェース経由でデバッグする場合や、HTTP ベースの MCP クライアントをテストする場合に使用します。

# 1. Clone the repository (if not already installed in the project)
# git clone https://github.com/lobehub/mcp-hello-world.git
# cd mcp-hello-world
# pnpm install / bun install

# 2. Build the project
# Using pnpm
pnpm build
# Or using bun
bun run build

# 3. Start the HTTP server
# Using pnpm
pnpm start:http
# Or using bun
bun run start:http

サーバーは http://localhost:3000 で起動し、次のエンドポイントを提供します。

• SSE エンドポイント：/sse
• メッセージエンドポイント：/messages

テストでの使用方法

Jest、Vitest、Mocha などのテストフレームワーク内で mcp-hello-world サーバーをプログラムから起動・停止し、自動テストを実行できます。

例：STDIO モードでのテスト（Node.js）

// test/my-mcp-client.test.ts (Example using Jest)
import { spawn } from 'child_process';
import { MCPClient } from '../src/my-mcp-client'; // Assuming this is your client code

describe('My MCP Client (STDIO)', () => {
  let mcpServerProcess;
  let client: MCPClient;

  beforeAll(() => {
    // Start the mcp-hello-world process before tests
    // Using npx (or pnpm dlx / bunx) ensures the command is found and executed
    mcpServerProcess = spawn('npx', ['mcp-hello-world']);

    // Instantiate your client and connect to the subprocess's stdio
    client = new MCPClient(mcpServerProcess.stdin, mcpServerProcess.stdout);
  });

  afterAll(() => {
    // Shut down the mcp-hello-world process after tests
    mcpServerProcess.kill();
  });

  it('should receive echo response', async () => {
    const request = {
      jsonrpc: '2.0',
      id: 1,
      method: 'tools/invoke',
      params: { name: 'echo', parameters: { message: 'test message' } },
    };

    const response = await client.sendRequest(request); // Assuming your client has this method

    expect(response).toEqual({
      jsonrpc: '2.0',
      id: 1,
      result: { content: [{ type: 'text', text: 'Hello test message' }] },
    });
  });

  it('should get greeting resource', async () => {
    const request = {
      jsonrpc: '2.0',
      id: 2,
      method: 'resources/get',
      params: { uri: 'greeting://Alice' },
    };
    const response = await client.sendRequest(request);
    expect(response).toEqual({
      jsonrpc: '2.0',
      id: 2,
      result: { data: 'Hello Alice!' }, // Confirm return format based on actual implementation
    });
  });

  // ... other test cases
});

例：HTTP/SSE モードでのテスト

HTTP/SSE の場合は、次の手順が必要になることがあります。

1. beforeAll で exec または spawn を使って、pnpm start:http または bun run start:http を起動します。
2. HTTP クライアント（axios、node-fetch、またはテストフレームワークに組み込まれたクライアントなど）を使って、テスト用に http://localhost:3000/sse と /messages に接続します。
3. afterAll で起動したサーバープロセスを終了してください。

提供される MCP の機能（テストのアサーション用）

mcp-hello-world は、テストでの操作とアサーションに使用する以下の固定機能を提供します。

リソース

• hello://world
  • 説明：静的な Hello World リソースです。
  • メソッド：resources/get
  • パラメーター：なし
  • 戻り値：{ data: 'Hello World!' }
• greeting://{name}
  • 説明：動的な挨拶リソースです。
  • メソッド：resources/get
  • パラメーター：URI に含まれる name。例：greeting://Bob。
  • 戻り値：{ data: 'Hello {name}!' }（例：{ data: 'Hello Bob!' }）

ツール

• echo
  • 説明：入力メッセージの先頭に「Hello 」を付けて返します。
  • メソッド：tools/invoke
  • パラメーター：{ name: 'echo', parameters: { message: string } }
  • 戻り値：{ content: [{ type: 'text', text: 'Hello {message}' }] }（例：{ content: [{ type: 'text', text: 'Hello test' }] }）
• debug
  • 説明：サーバー上で利用可能なすべての MCP メソッド定義を一覧表示します。
  • メソッド：tools/invoke
  • パラメーター：{ name: 'debug', parameters: {} }
  • 戻り値：登録済みのすべてのリソース、ツール、プロンプトの定義を含む JSON 構造です。

プロンプト

• helpful-assistant
  • 説明：基本的なアシスタントのプロンプト定義です。
  • メソッド：prompts/get
  • パラメーター：なし
  • 戻り値：事前定義された system および user ロールを含む、プロンプトの JSON 構造です。

ライセンス

MIT