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() 介面，僅需提供「工具定義」與「執行回呼」兩個參數即可輕鬆註冊。

• 內建工具與反射機制：

  • 內建 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. 計算兩數之和 (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 條款進行開源。