mcp-server-plus

Einführung

mcp-server-plus ist ein MCP-Server-Toolkit – ein kleines TypeScript-Framework zum Erstellen von Model Context Protocol-Servern, ohne sich wiederholenden Boilerplate-Code zu schreiben.

Hinweis zum Paketnamen: mcp-server-toolkit war auf npm bereits vergeben, daher wird dieses Paket als mcp-server-plus veröffentlicht.

Related MCP server: MCP Framework

Warum dieses Paket existiert

Entwickler, die MCP-Server erstellen, implementieren wiederholt Tool-Registrierung, Prompts, Ressourcen, Authentifizierung, Logging und Tests. Beliebte Bibliotheken wie Express und Hono sind erfolgreich, weil sie den Happy Path offensichtlich machen. mcp-server-plus zielt auf dieselbe DX auf Basis des offiziellen @modelcontextprotocol/sdk ab.

Installation

npm install mcp-server-plus zod

Erfordert Node.js 18+.

Funktionen

• Tool-Registrierung

• Prompt-Registrierung

• Ressourcen

• Authentifizierung / Autorisierung

• Protokollierung

• Metriken

• Streaming (über MCP-stdio-Transport)

• Middleware

• CLI-Scaffolder

• Testhilfen

Schnellstart

import { z } from "zod";
import { createServer, toolResult } from "mcp-server-plus";

const weatherTool = {
  description: "Get weather",
  inputSchema: { city: z.string() },
  async handler({ city }: { city: string }) {
    return toolResult(`Weather in ${city}: sunny`);
  },
};

const server = createServer({
  name: "demo",
  version: "1.0.0",
});

server.tool("weather", weatherTool);

await server.start(); // stdio

CLI

npx mcp-server-plus init my-weather-server
cd my-weather-server
npm install
npm start

API-Referenz

createServer(options) / createMcpServer(options)

Erstellt einen McpKitServer.

server.tool(name, definition)

Registriert ein Tool (auch in das MCP-SDK eingebunden).

server.prompt(name, definition)

Registriert eine Prompt-Vorlage.

server.resource(uri, definition)

Registriert eine Ressource.

server.use(middleware)

Fügt Middleware um Tool-Aufrufe hinzu.

server.start()

Verbindet einen MCP-stdio-Transport (Streaming wird vom SDK übernommen).

server.invokeTool(name, args, meta?)

In-Process-Aufruf für Tests/Skripte.

Testhilfen

import { callTool, expectText } from "mcp-server-plus/testing";

Beispiele

server.tool("weather", weatherTool);
server.prompt("greet", {
  description: "Greeting",
  arguments: [{ name: "name", required: true }],
  handler: async ({ name }) => ({
    messages: [
      { role: "user", content: { type: "text", text: `Hello ${name}` } },
    ],
  }),
});
server.resource("memo://hello", {
  mimeType: "text/plain",
  handler: async (uri) => ({
    contents: [{ uri: uri.href, text: "Hello", mimeType: "text/plain" }],
  }),
});

Fortgeschrittene Beispiele

Auth + RBAC

const server = createServer({
  name: "secure",
  version: "1.0.0",
  // MCP_API_KEY is the expected secret only. Callers must still send meta.apiKey.
  auth: { apiKey: process.env.MCP_API_KEY, required: true },
});

server.tool("deploy", {
  roles: ["admin"],
  scopes: ["deploy"],
  handler: async () => toolResult("deployed"),
});

Middleware + Metriken

server.use(async (ctx, next) => {
  const started = Date.now();
  try {
    return await next();
  } finally {
    ctx.log.info("tool timing", ctx.toolName, Date.now() - started);
  }
});

console.log(server.metricsSnapshot());

Framework-Integration

Funktioniert mit jedem MCP-Host, der stdio-Server unterstützt. Weisen Sie den Host auf Ihren node dist/index.js-Prozess (oder npm start) hin.

Beispiel für eine MCP-Host-Konfiguration:

{
  "mcpServers": {
    "demo": {
      "command": "node",
      "args": ["/path/to/server/src/index.js"]
    }
  }
}

TypeScript-Verwendung

TypeScript wird erstklassig unterstützt. Tool-Argumente werden aus dem Zod-inputSchema abgeleitet, wenn Sie den Handler explizit typisieren. Aktivieren Sie strict für beste Ergebnisse.

Fehlerbehandlung

Typisierte Fehler: McpKitError, AuthError, ForbiddenError.
Tool-Fehler geben { isError: true, content: [...] } zurück, damit Hosts sie sicher anzeigen können.

Leistung

• Dünner Wrapper über dem offiziellen SDK (keine zusätzlichen Netzwerk-Hops)

• Middleware nur bei Tool-Aufrufen

• Metriken verwenden einfache Zähler (geringer Overhead)

Bewährte Vorgehensweisen

• Halten Sie Tools klein und seitenwirkungsbewusst

• Validieren Sie Eingaben mit Zod-Schemata

• Verwenden Sie optional-Auth für lokal/Entwicklung, required für gemeinsam genutzte Hosts

• Bevorzugen Sie invokeTool in Unit-Tests; verwenden Sie stdio für Integrationstests

FAQ

Ist dies ein offizielles SDK?
Nein – es baut auf @modelcontextprotocol/sdk mit besserer DX auf.

Unterstützt es Streaming?
Ja, über den MCP-stdio-Transport, der von server.start() verwendet wird.

CJS oder ESM?
Doppelt veröffentlicht; ESM-first.

Migrationsleitfaden

Vom direkten SDK McpServer

Ersetzen Sie den registerTool-Boilerplate-Code durch server.tool(name, definition) und behalten Sie Zod-Schemata bei. Rufen Sie server.start() auf, anstatt StdioServerTransport manuell zu verdrahten.

SemVer

Breaking Changes erscheinen in Hauptversionen und werden in CHANGELOG.md dokumentiert.

Fehlerbehebung

Mitwirken

Siehe CONTRIBUTING.md.

Lizenz

MIT