MCP Simulator (Node.js MCP Server)

mcp simulator is a lightweight MCP server (Model Context Protocol Server) built on Node.js. This project adopts a zero-external-dependency design (using only the native http module), and provides dynamic tool registration and HTTP remote procedure call (RPC) capabilities through the modular McpServer and McpRegistry.

🚀 Core Features

• Zero external dependencies: Relies entirely on Node.js's native http module; no frameworks such as express are needed.

• Brand-new MCP core architecture:

  • McpRegistry: responsible for maintaining the tool list and execution logic (supports both synchronous and asynchronous async methods).

  • McpServer: provides an HTTP POST-based execution entry point and unified JSON response wrapping.

• Clean API registration design: Provides a chainable register() interface; you only need to supply two parameters, the "tool definition" and the "execution callback", to register easily.

• Built-in tools and reflection mechanism:

  • Built-in tool/list dynamically queries all registered tools.

  • Provides complete demonstrations including synchronous calculation, text processing, and asynchronous (async) simulated API requests (fetch-posts).

Related MCP server: Swagger/Postman MCP Server

📁 File Structure

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

⚙️ Quick Start

Starting the Server

Run the following command in the project root directory:

node index.js

The server listens on port 8889 by default (or reads the PORT environment variable). After startup, the console will display:

Server running at 8889

🔌 API Protocol Specification

All API calls go through a single entry point.

• Request method: POST

• Server address: http://localhost:8889

• Request header: Content-Type: application/json

• Request body format (Payload):

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

Unified Response Structure (Response)

After all requests are processed successfully, the server returns a uniformly wrapped JSON structure:

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

Server Error Status Overview

🛠️ Built-in Method Call Examples

The following are actual call data using localhost:8889 as an example:

1. Get the List of Available Tools (tool/list)

Lists all tool definitions registered in the server.

• Request Payload: {"name": "tool/list", "args": {}}

• Response Example:

  {
      "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 the Sum of Two Numbers (calculate)

• Request Payload: {"name": "calculate", "args": {"a": 20, "b": 30}}

• Response Example:

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

3. Asynchronous Request Test (fetch-posts)

Demonstrates the use of an async callback function, returning a set of fake user data (an array).

• Request Payload: {"name": "fetch-posts"}

• Response Example:

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

📝 Developing and Extending Custom Tools

You can modify index.js and add your tools through chainable .register() calls.

API Signature

server.register(toolDefinition, callback);

• toolDefinition (Object): must contain name, and may optionally provide description and args (parameter definitions).

• callback (Function / Async Function): the callback executed when a request is received. It receives a single object parameter from req.params.args.

Registration Example

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();

💡 Key Development Reminders:

1. Parameter reception: Because the args sent by the client are passed to the callback function as a single object, if your tool defines multiple parameters, be sure to use object destructuring with { param1, param2 } in the callback function.

2. Asynchronous support: McpRegistry internally uses await to execute tools, so you can safely use async/await in your callback functions for database queries or network requests.

📄 License

This project is open-sourced under the terms of the MIT License.