MCP Simulator (Node.js MCP Server)

mcp simulator ist ein leichtgewichtiger MCP-Server (Model Context Protocol Server), der auf Node.js basiert. Dieses Projekt verwendet ein Design ohne externe Abhängigkeiten (nur das native http-Modul) und bietet über die modularen McpServer- und McpRegistry-Komponenten dynamische Tool-Registrierung und HTTP-Fernaufrufe (RPC).

🚀 Kernfunktionen

• Keine externen Abhängigkeiten: Verlässt sich vollständig auf das native http-Modul von Node.js, ohne Frameworks wie express.

• Neue MCP-Kernarchitektur:

  • McpRegistry: Verwaltet die Tool-Liste und Ausführungslogik (unterstützt synchrone und asynchrone async-Methoden).

  • McpServer: Bietet einen HTTP-POST-basierten Ausführungseinstiegspunkt und eine einheitliche JSON-Antwortkapselung.

• Einfaches API-Registrierungsdesign: Bietet eine register()-Schnittstelle mit Verkettungsunterstützung; es genügen zwei Parameter – „Tool-Definition" und „Ausführungs-Callback" – für eine einfache Registrierung.

• Integrierte Tools und Reflexionsmechanismus:

  • Integriertes tool/list zum dynamischen Abfragen aller registrierten Tools.

  • Bietet vollständige Beispiele für synchrone Berechnungen, Textverarbeitung sowie asynchrone (async) simulierte API-Anfragen (fetch-posts).

Related MCP server: Swagger/Postman MCP Server

📁 Dateistruktur

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

⚙️ Schnellstart

Server starten

Führen Sie im Projektstammverzeichnis den folgenden Befehl aus:

node index.js

Der Server lauscht standardmäßig auf Port 8889 (oder liest die Umgebungsvariable PORT). Nach dem Start zeigt die Konsole Folgendes an:

Server running at 8889

🔌 API-Protokollspezifikation

Alle API-Aufrufe erfolgen über einen einzigen Einstiegspunkt.

• Anfragemethode: POST

• Serveradresse: http://localhost:8889

• Anfrage-Header: Content-Type: application/json

• Anfrageformat (Payload):

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

Einheitliche Antwortstruktur (Response)

Nach erfolgreicher Verarbeitung aller Anfragen gibt der Server eine einheitlich gekapselte JSON-Struktur zurück:

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

Übersicht der Server-Fehlerstatus

🛠️ Beispiele für integrierte Methodenaufrufe

Im Folgenden finden Sie tatsächliche Aufrufdaten am Beispiel von localhost:8889:

1. Verfügbare Tool-Liste abrufen (tool/list)

Listet alle im Server registrierten Tool-Definitionen auf.

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

• Antwortbeispiel:

  {
      "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. Summe zweier Zahlen berechnen (calculate)

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

• Antwortbeispiel:

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

3. Asynchroner Anfragentest (fetch-posts)

Demonstriert die Verwendung von async-Callback-Funktionen und gibt eine Reihe von Beispieldaten von Benutzern zurück (Array).

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

• Antwortbeispiel:

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

📝 Entwicklung und Erweiterung benutzerdefinierter Tools

Sie können index.js ändern und Ihre Tools über verkettete .register()-Aufrufe hinzufügen.

API-Signatur

server.register(toolDefinition, callback);

• toolDefinition (Object): Muss name enthalten und kann optional description und args (Parameterdefinitionen) bereitstellen.

• callback (Function / Async Function): Der Callback, der beim Empfang einer Anfrage ausgeführt wird. Erhält ein einzelnes Objektargument aus req.params.args.

Registrierungsbeispiel

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

💡 Wichtige Hinweise für die Entwicklung:

1. Parameterempfang: Da die vom Client gesendeten args als einzelnes Objekt an die Callback-Funktion übergeben werden, müssen Sie bei mehreren definierten Parametern unbedingt Objektdestrukturierung mit { param1, param2 } in der Callback-Funktion verwenden.

2. Asynchrone Unterstützung: McpRegistry führt Tools intern mit await aus. Sie können in der Callback-Funktion bedenkenlos async/await für Datenbankabfragen oder Netzwerkanfragen verwenden.

📄 Lizenz

Dieses Projekt ist unter den Bedingungen der MIT License als Open Source lizenziert.