MCP Simulator (Servidor MCP de Node.js)

mcp simulator es un servidor MCP (Model Context Protocol Server) ligero construido con Node.js. Este proyecto está diseñado con cero dependencias externas (utilizando únicamente el módulo nativo http), y proporciona capacidades dinámicas de registro de herramientas e invocación remota (RPC) a través de HTTP mediante los módulos McpServer y McpRegistry.

🚀 Características principales

• Cero dependencias externas: depende completamente del módulo nativo http de Node.js, sin necesidad de frameworks como express.

• Nueva arquitectura central de MCP:

  • McpRegistry: se encarga de mantener la lista de herramientas y la lógica de ejecución (compatible con métodos síncronos y asíncronos async).

  • McpServer: proporciona un punto de entrada de ejecución basado en HTTP POST y un encapsulado de respuesta JSON unificado.

• Diseño de registro de API sencillo: ofrece una interfaz register() compatible con encadenamiento; solo necesita proporcionar dos parámetros: la "definición de la herramienta" y el "callback de ejecución".

• Herramientas integradas y mecanismo de reflexión:

  • Herramienta integrada tool/list para consultar dinámicamente todas las herramientas registradas.

  • Incluye demostraciones completas de cálculo síncrono, procesamiento de texto y simulación de solicitudes API asíncronas (async) (fetch-posts).

Related MCP server: Swagger/Postman MCP Server

📁 Estructura de archivos

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

⚙️ Inicio rápido

Iniciar el servidor

Ejecute el siguiente comando en el directorio raíz del proyecto:

node index.js

El servidor escuchará por defecto en el puerto 8889 (o leerá la variable de entorno PORT). Tras el inicio, la consola mostrará:

Server running at 8889

🔌 Especificación del protocolo API

Todas las llamadas API se realizan a través de un único punto de entrada.

• Método de solicitud: POST

• Dirección del servidor: http://localhost:8889

• Encabezado de solicitud (Header): Content-Type: application/json

• Formato del cuerpo de la solicitud (Payload):

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

Estructura de respuesta unificada (Response)

Después de procesar correctamente todas las solicitudes, el servidor devolverá una estructura JSON unificada encapsulada:

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

Tabla de estados de error del servidor

🛠️ Ejemplos de llamadas a métodos integrados

A continuación se muestran datos de llamadas reales usando localhost:8889 como ejemplo:

1. Obtener la lista de herramientas disponibles (tool/list)

Enumera todas las definiciones de herramientas registradas en el servidor.

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

• Ejemplo de respuesta:

  {
      "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. Calcular la suma de dos números (calculate)

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

• Ejemplo de respuesta:

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

3. Prueba de solicitud asíncrona (fetch-posts)

Demuestra el uso de funciones callback async, devolviendo un conjunto de datos falsos de usuarios (array).

• Payload de solicitud: {"name": "fetch-posts"}

• Ejemplo de respuesta:

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

📝 Desarrollo y extensión de herramientas personalizadas

Puede modificar index.js y añadir sus herramientas mediante llamadas encadenadas a .register().

Firma de la API

server.register(toolDefinition, callback);

• toolDefinition (Object): debe contener name, y opcionalmente puede proporcionar description y args (definición de parámetros).

• callback (Function / Async Function): el callback que se ejecuta al recibir una solicitud. Recibe un único parámetro de objeto proveniente de req.params.args.

Ejemplo de registro

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

💡 Recordatorios importantes para el desarrollo:

1. Recepción de parámetros: dado que el args enviado por el cliente se pasa como un único objeto a la función callback, si la herramienta define varios parámetros, asegúrese de utilizar desestructuración de objetos con { param1, param2 } en la función callback.

2. Compatibilidad asíncrona: McpRegistry ejecuta las herramientas internamente con await, por lo que puede usar async/await con confianza en las funciones callback para consultas a bases de datos o envío de solicitudes de red.

📄 Licencia

Este proyecto se publica bajo los términos de la Licencia MIT.