MCP Node.js Boilerplate

Boilerplate zum Erstellen von MCP-Clients und MCP-Servern mit Node.js + TypeScript. Auf der HTTP-Seite wird Express verwendet. Unterstützt werden:

• stdio — der Client startet den Server als Child-Process, geeignet für MCP-Hosts, die lokal laufen

• Streamable HTTP — der Endpoint liegt unter /mcp und kann per Cloudflare Tunnel als HTTPS bereitgestellt werden

• Mock-Tools für CRUD-Operationen auf Users

• Statische Resource users://all und Resource-Template users://{id}

• Prompt summarize-users

• CLI-Client für Discovery, Tool-Aufrufe, Resource-Auslesen und Prompt-Anfragen

Die Ausgangsdaten liegen in src/data/users.json und werden beim Start des Servers in den Speicher geladen. Änderungen über CRUD überschreiben die Datei nicht und werden beim Neustart des Prozesses zurückgesetzt.

Requirements

• Node.js 20 oder höher

• npm

• cloudflared nur für den HTTPS-Tunnel erforderlich

Related MCP server: MCP TypeScript Starter

Installation

npm install

Build und Test prüfen:

npm run check

Wichtige Struktur

src/
├── client/
│   └── client.ts          # MCP CLI client ใช้ได้ทั้ง stdio และ HTTP
├── data/
│   └── users.json         # mock seed data
├── lib/
│   └── api-client.ts      # shared Axios instance สำหรับ upstream APIs
├── services/
│   └── user-service.ts    # business logic กลางสำหรับ MCP capabilities
└── server/
    ├── mcp.ts             # ประกอบ server และ capability registrations
    ├── tools/
    │   └── user-tools.ts
    ├── resources/
    │   └── user-resources.ts
    ├── prompts/
    │   └── user-prompts.ts
    ├── schemas/
    │   └── user.ts        # shared MCP output schema
    ├── repository.ts      # in-memory CRUD repository
    ├── stdio.ts           # stdio entry point
    └── http.ts            # Express + Streamable HTTP entry point
scripts/
└── build.mjs              # compile TypeScript และ copy mock JSON ไป dist

Die Factory in mcp.ts wird von beiden Transports gemeinsam genutzt, sodass die Fähigkeiten des Servers identisch sind. Tools, Resources und Prompts rufen den zentralen UserService auf, statt direkt an ein Repository gebunden zu sein.

Externe API mit Axios aufrufen

Das Projekt enthält eine gemeinsame Axios-Instanz unter src/lib/api-client.ts mit Base-URL, Timeout und optionalem Bearer-Token. Sie kann in Tools oder Services importiert werden:

import { apiClient } from "../../lib/api-client.js";

const response = await apiClient.get("/users");
console.log(response.data);

Konfiguration beim Start des Servers:

API_BASE_URL=https://api.example.com \
API_TIMEOUT_MS=10000 \
API_TOKEN=your-token \
npm run server:http

Beispiel für die Verwendung in einem MCP-Tool:

server.registerTool(
  "list-upstream-users",
  {
    description: "List users from the configured upstream API",
    inputSchema: z.object({}),
  },
  async () => {
    const { data } = await apiClient.get("/users");
    return {
      content: [{ type: "text", text: JSON.stringify(data, null, 2) }],
      structuredContent: { users: data },
    };
  },
);

Wenn API_BASE_URL nicht gesetzt ist, kann Axios weiterhin direkt eine absolute URL übergeben werden. Vermeiden Sie das Protokollieren von API_TOKEN und bewahren Sie das Token in Production in einem Secret Manager auf.

Ausführung über stdio

Normalerweise muss der stdio-Server nicht separat gestartet werden, da der Client bzw. MCP-Host den Prozess selbst startet.

Demo-Client ausführen, der den Server startet, Capabilities ermittelt, Tools aufruft, Resources liest und einen Prompt anfordert:

npm run client:stdio -- demo

Server direkt starten, um auf einen MCP-Host zu warten:

npm run server:stdio

Wichtiger Hinweis: stdio verwendet stdout als JSON-RPC-Kanal. Server-Logs müssen daher ausschließlich über stderr geschrieben werden, z. B. mit console.error.

Beispielkonfiguration für einen MCP-Host – ersetzen Sie /absolute/path/to/mcp-boilerplate durch den tatsächlichen Pfad:

{
  "mcpServers": {
    "mock-users": {
      "command": "node",
      "args": [
        "--import",
        "tsx",
        "/absolute/path/to/mcp-boilerplate/src/server/stdio.ts"
      ],
      "cwd": "/absolute/path/to/mcp-boilerplate"
    }
  }
}

Oder vorher bauen und JavaScript verwenden, ohne zur Laufzeit auf tsx angewiesen zu sein:

npm run build
npm run start:stdio

Konfiguration nach dem Build:

{
  "mcpServers": {
    "mock-users": {
      "command": "node",
      "args": [
        "/absolute/path/to/mcp-boilerplate/dist/server/stdio.js"
      ],
      "cwd": "/absolute/path/to/mcp-boilerplate"
    }
  }
}

Ausführung über Express HTTP

Terminal 1 — Server starten:

npm run server:http

Standardwerte:

• MCP-Endpoint: http://127.0.0.1:3000/mcp

• Health Check: http://127.0.0.1:3000/health

Terminal 2 — HTTP-Client ausführen:

npm run client:http -- demo

Port oder Host können über Environment-Variablen geändert werden:

HOST=127.0.0.1 PORT=4000 npm run server:http
MCP_URL=http://127.0.0.1:4000/mcp npm run client:http -- demo

Für den Production-Build:

npm run build
npm run start:http

HTTPS mit Cloudflare Tunnel aktivieren

HTTPS wird in diesem Beispiel bei Cloudflare terminiert; der Express-Server lauscht weiterhin nur lokal auf HTTP.

macOS – cloudflared installieren:

brew install cloudflared

Terminal 1 — MCP-HTTP-Server starten:

npm run server:http

Terminal 2 — Quick Tunnel starten:

cloudflared tunnel --url http://127.0.0.1:3000

cloudflared zeigt eine temporäre URL an, z. B.:

https://random-words.trycloudflare.com

Der externe MCP-Endpoint lautet daher:

https://random-words.trycloudflare.com/mcp

Terminal 3 — Test über den HTTPS-Tunnel:

MCP_URL=https://random-words.trycloudflare.com/mcp npm run client:http -- demo

Quick Tunnel ist nur für die Entwicklung geeignet, und Cloudflare gibt an, dass SSE nicht unterstützt wird. Daher setzt dieses Boilerplate den Response-Modus auf auto – normale CRUD-/Discovery-Befehle antworten mit JSON, aber Streaming-Funktionen wie langfristige Subscriptions sollten nicht über Quick Tunnel getestet werden. Für Production verwenden Sie einen Named Tunnel, eine eigene Hostname, Authentifizierung und Autorisierung.

Bei Verwendung eines eigenen Hostnames fügen Sie diesen zur Allowlist hinzu:

ALLOWED_HOSTS=mcp.example.com npm run server:http

Mehrere Hostnames mit Komma trennen:

ALLOWED_HOSTS=mcp.example.com,mcp-staging.example.com npm run server:http

localhost, 127.0.0.1, ::1 und *.trycloudflare.com sind für die Entwicklung bereits erlaubt.

MCP-Client-Befehle

Die Syntax ist für client:stdio und client:http identisch – nur der Script-Name ändert sich.

Tools anzeigen:

npm run client:stdio -- list-tools
npm run client:http -- list-tools

Resources oder Prompts anzeigen:

npm run client:stdio -- list-resources
npm run client:stdio -- list-prompts

CRUD-Tools aufrufen:

npm run client:stdio -- call list-users '{}'
npm run client:stdio -- call get-user '{"id":"1"}'
npm run client:stdio -- call create-user '{"name":"Margaret Hamilton","email":"margaret@example.com","role":"developer"}'
npm run client:stdio -- call update-user '{"id":"1","role":"viewer"}'
npm run client:stdio -- call delete-user '{"id":"3"}'

Resources lesen:

npm run client:stdio -- read users://all
npm run client:stdio -- read users://1

Prompt anfordern:

npm run client:stdio -- prompt summarize-users '{"tone":"detailed"}'

Für eine andere HTTP-URL setzen Sie MCP_URL:

MCP_URL=https://mcp.example.com/mcp npm run client:http -- call list-users '{}'

Hinweis für stdio: Jeder CLI-Befehl startet einen neuen Server-Prozess und beginnt daher jedes Mal mit den ursprünglichen Mock-Daten. Wenn CRUD-Operationen zusammenhängend sein sollen, verwenden Sie einen MCP-Host, der die Verbindung hält, oder starten Sie den HTTP-Server und rufen Sie ihn über client:http auf.

Verfügbare Tools, Resources und Prompts

Environment-Variablen

Beispielwerte finden Sie in .env.example. Das Projekt lädt die Datei .env nicht automatisch; exportieren Sie die Variablen oder setzen Sie sie vor dem Befehl, wie in den Beispielen oben.

Sicherheitshinweise

• Dieses Beispiel enthält keine Authentifizierung und Autorisierung. Öffnen Sie niemals einen öffentlichen Endpoint mit echten Daten.

• Die Validierung von Host und Origin erlaubt nur localhost, TryCloudflare und Werte aus ALLOWED_HOSTS.

• Das Mock-Repository liegt im Speicher und persistiert bewusst keine Daten.

• Für Production sollten Sie Auth, Rate Limiting, Audit-Logging, eine persistente Datenbank sowie eine TLS-/Trust-Proxy-Konfiguration ergänzen, die zum realen System passt.

Alle Scripts

npm run dev:stdio       # stdio server พร้อม watch mode
npm run dev:http        # Express HTTP server พร้อม watch mode
npm run server:stdio    # stdio server จาก TypeScript
npm run server:http     # Express HTTP server จาก TypeScript
npm run client:stdio -- demo
npm run client:http -- demo
npm run build
npm run start:stdio     # รัน dist หลัง build
npm run start:http      # รัน dist หลัง build
npm test
npm run check

Referenzen: MCP TypeScript SDK, Cloudflare Quick Tunnels