MCP Simulator (Node.js MCP Server)

mcp simulator は、Node.js で構築された軽量な MCP サーバー (Model Context Protocol Server) です。本プロジェクトはゼロ外部依存設計（ネイティブの http モジュールのみを使用）を採用し、モジュール化された McpServer と McpRegistry を通じて、動的なツール登録と HTTP リモート呼び出し（RPC）機能を提供します。

🚀 コア機能

• ゼロ外部依存：Node.js ネイティブの http モジュールのみに依存し、express などのフレームワークは不要です。

• 新しい MCP コアアーキテクチャ：

  • McpRegistry：ツール一覧と実行ロジックの管理を担当（同期および非同期 async メソッドをサポート）。

  • McpServer：HTTP POST ベースの実行エントリポイントと統一された JSON レスポンスのラッピングを提供。

• シンプルな API 登録設計：チェーン呼び出しをサポートする register() インターフェースを提供し、「ツール定義」と「実行コールバック」の2つのパラメータを指定するだけで簡単に登録できます。

• 組み込みツールとリフレクション機構：

  • 組み込みの tool/list で登録済みの全ツールを動的に照会。

  • 同期計算、テキスト処理、および非同期 (async) の API リクエスト模擬（fetch-posts）などの完全なデモを提供。

Related MCP server: Swagger/Postman MCP Server

📁 ファイル構成

mcp-simulator/
├── mcp.core.js             # 伺服器核心引擎（定義 McpServer 與 McpRegistry 類別）
├── index.js                # 專案主入口（載入核心引擎並註冊具體工具）
├── index.http              # HTTP API 測試腳本（搭配 VS Code REST Client 使用）
├── package.json            # 專案配置文件
└── README.md               # 本專案說明文件

⚙️ クイックスタート

サーバーの起動

プロジェクトのルートディレクトリで以下のコマンドを実行してください：

node index.js

サーバーはデフォルトで 8889 ポート（または環境変数 PORT を読み取り）をリッスンします。起動後、コンソールに以下が表示されます：

Server running at 8889

🔌 API プロトコル仕様

すべての API 呼び出しは単一のエントリポイントを通じて行われます。

• リクエストメソッド：POST

• サーバーアドレス：http://localhost:8889

• リクエストヘッダー (Header)：Content-Type: application/json

• リクエストボディ形式 (Payload)：

  {
      "name": "要調用的工具名稱",
      "args": {
          "參數鍵": "參數值"
      }
  }

統一レスポンス構造 (Response)

すべてのリクエストが正常に処理された後、サーバーは統一された JSON 構造を返します：

{
    "code": 200,
    "message": "success",
    "data": {
        /* 工具回傳的原始結果 */
    }
}

サーバーエラーステータス一覧

🛠️ 組み込みメソッド呼び出し例

以下は localhost:8889 を例にした実際の呼び出しデータです：

1. 利用可能なツール一覧の取得 (tool/list)

サーバーに登録されているすべてのツール定義を一覧表示します。

• リクエスト Payload：{"name": "tool/list", "args": {}}

• レスポンス例：

  {
      "code": 200,
      "message": "success",
      "data": [
          { "name": "info", "description": "..." },
          {
              "name": "hello",
              "description": "just say hello to someone",
              "args": { "username": "string" }
          },
          {
              "name": "calculate",
              "description": "calculate sum of two numbers",
              "args": { "a": "number", "b": "number" }
          },
          {
              "name": "fetch-posts",
              "description": "fetch posts from https://jsonplaceholder.typicode.com/posts"
          }
      ]
  }

2. 2つの数値の合計を計算 (calculate)

• リクエスト Payload：{"name": "calculate", "args": {"a": 20, "b": 30}}

• レスポンス例：

  {
      "code": 200,
      "message": "success",
      "data": { "result": 50 }
  }

3. 非同期リクエストテスト (fetch-posts)

async コールバック関数の使用方法を示し、ユーザーのダミーデータ（配列）を返します。

• リクエスト Payload：{"name": "fetch-posts"}

• レスポンス例：

  {
      "code": 200,
      "message": "success",
      "data": [
          {
              "id": 1,
              "name": "Leanne Graham",
              "username": "Bret",
              "email": "Sincere@april.biz"
              // ... (其他資料略)
          }
      ]
  }

📝 カスタムツールの開発と拡張

index.js を変更し、チェーン呼び出しの .register() を使用してツールを追加できます。

API シグネチャ

server.register(toolDefinition, callback);

• toolDefinition (Object): name を必須とし、任意で description と args（パラメータ定義）を指定できます。

• callback (Function / Async Function): リクエスト受信時に実行されるコールバック。req.params.args からの単一のオブジェクトパラメータを受け取ります。

登録例

const { McpServer } = require("./mcp.core");

new McpServer(8889)
    // 註冊一個需要參數的非同步工具
    .register(
        {
            name: "get_user",
            description: "獲取特定使用者資料",
            args: { userId: "number" },
        },
        async ({ userId }) => {
            // ⚠️ 必須使用物件解構讀取參數
            const user = await database.find(userId);
            return { result: user };
        },
    )
    .start();

💡 開発時の重要な注意点：

1. パラメータの受け取り：クライアントから送信された args は単一のオブジェクトとしてコールバック関数に渡されるため、ツールが複数のパラメータを定義している場合は、コールバック関数内で { param1, param2 } を使用したオブジェクトの分割代入を必ず行ってください。

2. 非同期サポート：McpRegistry は内部で await を使用してツールを実行するため、コールバック関数内で async/await を使用したデータベースクエリやネットワークリクエストの送信を安心して行えます。

📄 ライセンス

本プロジェクトは MIT License の条項に基づきオープンソースとして公開されています。