MCP Simulator (Node.js MCP Server)

mcp simulator — это легковесный MCP-сервер (Model Context Protocol Server), построенный на Node.js. Проект спроектирован с нулевыми внешними зависимостями (используется только встроенный модуль http) и предоставляет динамическую регистрацию инструментов и возможность удалённого вызова (RPC) через HTTP благодаря модульной архитектуре McpServer и McpRegistry.

🚀 Ключевые возможности

• Ноль внешних зависимостей: полностью полагается на встроенный модуль http из Node.js, не требуются такие фреймворки, как 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.