OpenAPI MCP Server

Ein Model Context Protocol (MCP)-Server, der OpenAPI-Endpunkte als MCP-Tools bereitstellt, mit optionaler Unterstützung für MCP-Prompts und -Ressourcen. Dieser Server ermöglicht es großen Sprachmodellen, REST-APIs, die durch OpenAPI-Spezifikationen definiert sind, über das MCP-Protokoll zu entdecken und mit ihnen zu interagieren.

📖 Dokumentation

• Benutzerhandbuch - Für Benutzer, die diesen MCP-Server mit Claude Desktop, Cursor oder anderen MCP-Clients verwenden möchten

• Verwendung als Bibliothek - Für Entwickler, die mit diesem Paket als Bibliothek eigene MCP-Server erstellen

• Entwicklerhandbuch - Für Mitwirkende und Entwickler, die an der Codebasis arbeiten

• AuthProvider-Leitfaden - Detaillierte Authentifizierungsmuster und Beispiele

Benutzerhandbuch

Dieser Abschnitt erläutert, wie Sie den MCP-Server als Endbenutzer mit Claude Desktop, Cursor oder anderen MCP-kompatiblen Tools verwenden.

Übersicht

Dieser MCP-Server kann auf zwei Arten verwendet werden:

1. CLI-Tool: Verwenden Sie npx @ivotoby/openapi-mcp-server direkt mit Befehlszeilenargumenten für eine schnelle Einrichtung.

2. Bibliothek: Importieren und verwenden Sie die Klasse OpenAPIServer in Ihren eigenen Node.js-Anwendungen für individuelle Implementierungen.

Der Server unterstützt zwei Transportmethoden:

1. Stdio-Transport (Standard): Für die direkte Integration in KI-Systeme wie Claude Desktop, die MCP-Verbindungen über Standardeingabe/-ausgabe verwalten.

2. Streamable HTTP-Transport: Zum Verbinden mit dem Server über HTTP, sodass Web-Clients und andere HTTP-fähige Systeme das MCP-Protokoll nutzen können.

Schnellstart für Benutzer

Option 1: Verwendung mit Claude Desktop (Stdio-Transport)

Sie müssen dieses Repository nicht klonen. Konfigurieren Sie einfach Claude Desktop für die Verwendung dieses MCP-Servers:

1. Suchen oder erstellen Sie Ihre Claude-Desktop-Konfigurationsdatei:

   • Unter macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

2. Fügen Sie die folgende Konfiguration hinzu:

{
  "mcpServers": {
    "openapi": {
      "command": "npx",
      "args": ["-y", "@ivotoby/openapi-mcp-server"],
      "env": {
        "API_BASE_URL": "https://api.example.com",
        "OPENAPI_SPEC_PATH": "https://api.example.com/openapi.json",
        "API_HEADERS": "Authorization:Bearer token123,X-API-Key:your-api-key"
      }
    }
  }
}

3. Ersetzen Sie die Umgebungsvariablen durch Ihre tatsächliche API-Konfiguration:

   • API_BASE_URL: Die Basis-URL Ihrer API

   • OPENAPI_SPEC_PATH: URL oder Pfad zu Ihrer OpenAPI-Spezifikation

   • API_HEADERS: Durch Kommas getrennte key:value-Paare für API-Authentifizierungs-Header

Option 2: Verwendung mit HTTP-Clients (HTTP-Transport)

Um den Server mit HTTP-Clients zu verwenden:

1. Keine Installation erforderlich! Verwenden Sie npx, um das Paket direkt auszuführen:

npx @ivotoby/openapi-mcp-server \
  --api-base-url https://api.example.com \
  --openapi-spec https://api.example.com/openapi.json \
  --headers "Authorization:Bearer token123" \
  --transport http \
  --port 3000

2. Interagieren Sie über HTTP-Anfragen mit dem Server:

# Initialize a session (first request)
curl -X POST http://localhost:3000/mcp \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":0,"method":"initialize","params":{"protocolVersion":"2025-03-26","capabilities":{},"clientInfo":{"name":"curl-client","version":"1.0.0"}}}'

# The response includes a Mcp-Session-Id header that you must use for subsequent requests
# and the InitializeResult directly in the POST response body.

# Send a request to list tools
# This also receives its response directly on this POST request.
curl -X POST http://localhost:3000/mcp \
  -H "Content-Type: application/json" \
  -H "Mcp-Session-Id: your-session-id" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

# Open a streaming connection for other server responses (e.g., tool execution results)
# This uses Server-Sent Events (SSE).
curl -N http://localhost:3000/mcp -H "Mcp-Session-Id: your-session-id"

# Example: Execute a tool (response will arrive on the GET stream)
# curl -X POST http://localhost:3000/mcp \
#  -H "Content-Type: application/json" \
#  -H "Mcp-Session-Id: your-session-id" \
#  -d '{"jsonrpc":"2.0","id":2,"method":"tools/execute","params":{"name":"yourToolName", "arguments": {}}}'

# Terminate the session when done
curl -X DELETE http://localhost:3000/mcp -H "Mcp-Session-Id: your-session-id"

Konfigurationsoptionen

Der Server kann über Umgebungsvariablen oder Befehlszeilenargumente konfiguriert werden:

Umgebungsvariablen

• API_BASE_URL - Basis-URL für die API-Endpunkte

• OPENAPI_SPEC_PATH - Pfad oder URL zur OpenAPI-Spezifikation

• OPENAPI_SPEC_FROM_STDIN - Auf "true" setzen, um die OpenAPI-Spezifikation von der Standardeingabe zu lesen

• OPENAPI_SPEC_INLINE - Inhalt der OpenAPI-Spezifikation direkt als Zeichenfolge bereitstellen

• API_HEADERS - Durch Kommas getrennte key:value-Paare für API-Header

• CLIENT_CERT_PATH - Pfad zur PEM-Datei des Client-Zertifikats für gegenseitiges TLS

• CLIENT_KEY_PATH - Pfad zur PEM-Datei des privaten Clientschlüssels für gegenseitiges TLS

• CA_CERT_PATH - Pfad zur benutzerdefinierten PEM-Datei des CA-Zertifikats für private/interne Zertifizierungsstellen

• CLIENT_KEY_PASSPHRASE - Passphrase für einen verschlüsselten privaten Clientschlüssel

• REJECT_UNAUTHORIZED - Gibt an, ob nicht vertrauenswürdige Serverzertifikate abgelehnt werden sollen (Standard: true)

• SERVER_NAME - Name für den MCP-Server (Standard: "mcp-openapi-server")

• SERVER_VERSION - Version des Servers (Standard: "1.0.0")

• TRANSPORT_TYPE - Zu verwendender Transporttyp: "stdio" oder "http" (Standard: "stdio")

• HTTP_PORT - Port für den HTTP-Transport (Standard: 3000)

• HTTP_HOST - Host für den HTTP-Transport (Standard: "127.0.0.1")

• ENDPOINT_PATH - Endpunktpfad für den HTTP-Transport (Standard: "/mcp")

• TOOLS_MODE - Lademodus für Tools: "all" (alle endpunktbasierten Tools laden), "dynamic" (nur Meta-Tools laden) oder "explicit" (nur die in includeTools angegebenen Tools laden) (Standard: "all")

• DISABLE_ABBREVIATION - Namensoptimierung deaktivieren (dies kann Fehler verursachen, wenn der Name länger als 64 Zeichen ist)

• VERBOSE - Betriebsprotokollierung aktivieren (standardmäßig true; auf false setzen, um nicht unbedingt erforderliche Protokolle zu unterdrücken)

• PROMPTS_PATH - Pfad oder URL zur JSON/YAML-Datei für Prompts

• PROMPTS_INLINE - Prompts direkt als JSON-Zeichenfolge bereitstellen

• RESOURCES_PATH - Pfad oder URL zur JSON/YAML-Datei für Ressourcen

• RESOURCES_INLINE - Ressourcen direkt als JSON-Zeichenfolge bereitstellen

Befehlszeilenargumente

npx @ivotoby/openapi-mcp-server \
  --api-base-url https://api.example.com \
  --openapi-spec https://api.example.com/openapi.json \
  --headers "Authorization:Bearer token123,X-API-Key:your-api-key" \
  --exclude-tag admin \
  --client-cert ./certs/client.pem \
  --client-key ./certs/client-key.pem \
  --name "my-mcp-server" \
  --server-version "1.0.0" \
  --transport http \
  --port 3000 \
  --host 127.0.0.1 \
  --path /mcp \
  --disable-abbreviation true \
  --verbose false

Gegenseitiges TLS (mTLS)

Wenn Ihre vorgelagerte API eine Client-Zertifikatsauthentifizierung erfordert, können Sie TLS-Anmeldeinformationen direkt an ausgehende Anfragen anhängen.

npx @ivotoby/openapi-mcp-server \
  --api-base-url https://secure-api.example.com \
  --openapi-spec https://secure-api.example.com/openapi.json \
  --client-cert ./certs/client.pem \
  --client-key ./certs/client-key.pem \
  --headers "Authorization:Bearer token123"

Dies ist orthogonal zur Authentifizierung auf HTTP-Ebene, sodass mTLS mit statischen Headern oder einem AuthProvider kombiniert werden kann.

TLS-bezogene Optionen gelten nur, wenn --api-base-url https:// verwendet.

Für private Zertifizierungsstellen oder verschlüsselte Schlüssel:

npx @ivotoby/openapi-mcp-server \
  --api-base-url https://internal-api.example.com \
  --openapi-spec ./openapi.yaml \
  --client-cert ./certs/client.pem \
  --client-key ./certs/client-key.pem \
  --client-key-passphrase "$CLIENT_KEY_PASSPHRASE" \
  --ca-cert ./certs/internal-ca.pem \
  --reject-unauthorized false

• --client-cert / CLIENT_CERT_PATH: PEM-Datei des Client-Zertifikats

• --client-key / CLIENT_KEY_PATH: PEM-Datei des privaten Clientschlüssels

• --client-key-passphrase / CLIENT_KEY_PASSPHRASE: Passphrase für verschlüsselte private Schlüssel

• --ca-cert / CA_CERT_PATH: Benutzerdefiniertes CA-Bündel für private/interne Zertifizierungsstellen

• --reject-unauthorized / REJECT_UNAUTHORIZED: Nur auf false setzen, wenn Sie absichtlich selbstsignierte oder anderweitig nicht vertrauenswürdige Serverzertifikate zulassen möchten

Setzen Sie --verbose false oder VERBOSE=false, wenn der Server in Skripten oder eingebetteten Umgebungen still bleiben soll.

Laden der OpenAPI-Spezifikation

Der MCP-Server unterstützt mehrere Methoden zum Laden von OpenAPI-Spezifikationen und bietet so Flexibilität für verschiedene Bereitstellungsszenarien:

1. Laden per URL (Standard)

Laden Sie die OpenAPI-Spezifikation von einer entfernten URL:

npx @ivotoby/openapi-mcp-server \
  --api-base-url https://api.example.com \
  --openapi-spec https://api.example.com/openapi.json

2. Laden aus lokaler Datei

Laden Sie die OpenAPI-Spezifikation aus einer lokalen Datei:

npx @ivotoby/openapi-mcp-server \
  --api-base-url https://api.example.com \
  --openapi-spec ./path/to/openapi.yaml

3. Laden über die Standardeingabe

Lesen Sie die OpenAPI-Spezifikation von der Standardeingabe (nützlich für Piping oder containerisierte Umgebungen):

# Pipe from file
cat openapi.json | npx @ivotoby/openapi-mcp-server \
  --api-base-url https://api.example.com \
  --spec-from-stdin

# Pipe from curl
curl -s https://api.example.com/openapi.json | npx @ivotoby/openapi-mcp-server \
  --api-base-url https://api.example.com \
  --spec-from-stdin

# Using environment variable
export OPENAPI_SPEC_FROM_STDIN=true
echo '{"openapi": "3.0.0", ...}' | npx @ivotoby/openapi-mcp-server \
  --api-base-url https://api.example.com

4. Inline-Spezifikation

Stellen Sie den Inhalt der OpenAPI-Spezifikation direkt als Befehlszeilenargument bereit:

npx @ivotoby/openapi-mcp-server \
  --api-base-url https://api.example.com \
  --spec-inline '{"openapi": "3.0.0", "info": {"title": "My API", "version": "1.0.0"}, "paths": {}}'

# Using environment variable
export OPENAPI_SPEC_INLINE='{"openapi": "3.0.0", ...}'
npx @ivotoby/openapi-mcp-server --api-base-url https://api.example.com

Unterstützte Formate

Alle Lademethoden unterstützen sowohl JSON- als auch YAML-Formate. Der Server erkennt das Format automatisch und parst entsprechend.

Docker- und Container-Nutzung

Für containerisierte Bereitstellungen können Sie OpenAPI-Spezifikationen einhängen oder stdin verwenden:

# Mount local file
docker run -v /path/to/spec:/app/spec.json your-mcp-server \
  --api-base-url https://api.example.com \
  --openapi-spec /app/spec.json

# Use stdin with docker
cat openapi.json | docker run -i your-mcp-server \
  --api-base-url https://api.example.com \
  --spec-from-stdin

Fehlerbehandlung

Der Server liefert detaillierte Fehlermeldungen für Fehler beim Laden der Spezifikation:

• Laden per URL: HTTP-Statuscodes und Netzwerkfehler

• Laden aus Datei: Dateisystemfehler (nicht gefunden, Berechtigungen usw.)

• Laden über stdin: Leere Eingabe oder Lesefehler

• Inline-Laden: Fehler bei fehlendem Inhalt

• Parsing-Fehler: Detaillierte JSON/YAML-Syntaxfehlermeldungen

Validierung

Es kann jeweils nur eine Spezifikationsquelle verwendet werden. Der Server validiert, dass genau eine der folgenden Optionen angegeben ist:

• --openapi-spec (URL oder Dateipfad)

• --spec-from-stdin

• --spec-inline

Wenn mehrere Quellen angegeben werden, beendet sich der Server mit einer Fehlermeldung.

Tool-Laden & Filteroptionen

Basierend auf dem Stainless-Artikel „What We Learned Converting Complex OpenAPI Specs to MCP Servers" (https://www.stainless.com/blog/what-we-learned-converting-complex-openapi-specs-to-mcp-servers) wurden die folgenden Flags hinzugefügt, um zu steuern, welche API-Endpunkte (Tools) geladen werden:

• --tools <all|dynamic|explicit>: Wählen Sie den Modus zum Laden der Tools:

  • all (Standard): Lädt alle Tools aus der OpenAPI-Spezifikation und wendet alle angegebenen Filter an.

  • dynamic: Lädt nur dynamische Meta-Tools (list-api-endpoints, get-api-endpoint-schema, invoke-api-endpoint). --exclude-tag gilt weiterhin für die dynamische Endpunkt-Erkennung und -Aufrufung.

  • explicit: Lädt nur Tools, die explizit in --tool-Optionen aufgeführt sind, und ignoriert Include-Filter. --exclude-tag gilt weiterhin als Deny-Filter.

• --tool <toolId>: Importiert nur angegebene Tool-IDs oder -Namen. Kann mehrfach verwendet werden. Im Modus all umgeht dies --tag, --resource und --operation, nicht jedoch --exclude-tag.

• --tag <tag>: Importiert nur Tools mit dem angegebenen OpenAPI-Tag. Kann mehrfach verwendet werden.

• --exclude-tag <tag>: Schließt Tools mit dem angegebenen OpenAPI-Tag aus. Kann mehrfach verwendet werden. Ausgeschlossene Tags haben Vorrang vor --tool.

• --resource <resource>: Importiert nur Tools unter den angegebenen Ressourcenpfad-Präfixen. Kann mehrfach verwendet werden.

• --operation <method>: Importiert nur Tools für die angegebenen HTTP-Methoden (get, post usw.). Kann mehrfach verwendet werden.

Tag-Filter sind Kontrollen auf Tool-Ebene, keine Autorisierung. Schützen Sie sensible Endpunkte weiterhin mit dem Authentifizierungsmodell der vorgelagerten API. Endpunkte ohne Tag werden von --exclude-tag nicht beeinflusst.

Beispiele:

# Load only dynamic meta-tools
npx @ivotoby/openapi-mcp-server --api-base-url https://api.example.com --openapi-spec https://api.example.com/openapi.json --tools dynamic

# Load only explicitly specified tools (ignores other filters)
npx @ivotoby/openapi-mcp-server --api-base-url https://api.example.com --openapi-spec https://api.example.com/openapi.json --tools explicit --tool GET::users --tool POST::users

# Load only the GET /users endpoint tool (using all mode with filtering)
npx @ivotoby/openapi-mcp-server --api-base-url https://api.example.com --openapi-spec https://api.example.com/openapi.json --tool GET-users

# Load tools tagged with "user" under the "/users" resource
npx @ivotoby/openapi-mcp-server --api-base-url https://api.example.com --openapi-spec https://api.example.com/openapi.json --tag user --resource users

# Exclude admin and internal endpoints from any tool loading mode
npx @ivotoby/openapi-mcp-server --api-base-url https://api.example.com --openapi-spec https://api.example.com/openapi.json --exclude-tag admin --exclude-tag internal

# Load only POST operations
npx @ivotoby/openapi-mcp-server --api-base-url https://api.example.com --openapi-spec https://api.example.com/openapi.json --operation post

Prompts und Ressourcen

Zusätzlich zur Bereitstellung von OpenAPI-Endpunkten als Tools kann dieser Server über das MCP-Protokoll auch Prompts (wiederverwendbare Vorlagen) und Ressourcen (statische Inhalte) bereitstellen.

Was sind Prompts und Ressourcen?

Laden von Prompts

Prompts können aus Dateien, URLs oder Inline-JSON geladen werden:

# Load from local file
npx @ivotoby/openapi-mcp-server \
  --api-base-url https://api.example.com \
  --openapi-spec https://api.example.com/openapi.json \
  --prompts ./prompts.json

# Load from URL
npx @ivotoby/openapi-mcp-server \
  --api-base-url https://api.example.com \
  --openapi-spec https://api.example.com/openapi.json \
  --prompts https://example.com/mcp/prompts.json

# Inline JSON
npx @ivotoby/openapi-mcp-server \
  --api-base-url https://api.example.com \
  --openapi-spec https://api.example.com/openapi.json \
  --prompts-inline '[{"name":"greet","title":"Greeting","template":"Hello {{name}}!"}]'

Prompts-Dateiformat (JSON):

[
  {
    "name": "api_request",
    "title": "API Request Helper",
    "description": "Helps generate API request templates",
    "arguments": [
      { "name": "endpoint", "description": "API endpoint path", "required": true },
      { "name": "method", "description": "HTTP method", "required": false }
    ],
    "template": "Create a {{method}} request to {{endpoint}} with proper parameters."
  }
]

Laden von Ressourcen

Ressourcen können aus Dateien, URLs oder Inline-JSON geladen werden:

# Load from local file
npx @ivotoby/openapi-mcp-server \
  --api-base-url https://api.example.com \
  --openapi-spec https://api.example.com/openapi.json \
  --mcp-resources ./resources.json

# Load from URL
npx @ivotoby/openapi-mcp-server \
  --api-base-url https://api.example.com \
  --openapi-spec https://api.example.com/openapi.json \
  --mcp-resources https://example.com/mcp/resources.json

# Inline JSON
npx @ivotoby/openapi-mcp-server \
  --api-base-url https://api.example.com \
  --openapi-spec https://api.example.com/openapi.json \
  --mcp-resources-inline '[{"uri":"docs://readme","name":"readme","text":"# Welcome"}]'

Ressourcen-Dateiformat (JSON):

[
  {
    "uri": "docs://api/overview",
    "name": "api-overview",
    "title": "API Overview",
    "description": "Overview of the API",
    "mimeType": "text/markdown",
    "text": "# API Overview\n\nThis API provides..."
  }
]

Kombinieren von Tools, Prompts und Ressourcen

npx @ivotoby/openapi-mcp-server \
  --api-base-url https://api.example.com \
  --openapi-spec https://api.example.com/openapi.json \
  --prompts ./prompts.json \
  --mcp-resources ./resources.json \
  --transport http \
  --port 3000

Mit dieser Konfiguration macht der Server Fähigkeiten für alle drei bekannt:

{
  "capabilities": {
    "tools": { "list": true, "execute": true },
    "prompts": {},
    "resources": {}
  }
}

Transportarten

Stdio-Transport (Standard)

Der Stdio-Transport ist für die direkte Integration in KI-Systeme wie Claude Desktop konzipiert, die MCP-Verbindungen über Standardeingabe/-ausgabe verwalten. Dies ist die einfachste Einrichtung und erfordert keine Netzwerkkonfiguration.

Wann verwenden: Bei der Integration mit Claude Desktop oder anderen Systemen, die stdio-basierte MCP-Kommunikation unterstützen.

Streamable HTTP-Transport

Der HTTP-Transport ermöglicht den Zugriff auf den MCP-Server über HTTP, sodass Webanwendungen und andere HTTP-fähige Clients mit dem MCP-Protokoll interagieren können. Er unterstützt Sitzungsverwaltung, Streaming-Antworten und Standard-HTTP-Methoden.

Hauptmerkmale:

• Sitzungsverwaltung mit Mcp-Session-Id-Header

• HTTP-Antworten auf initialize- und tools/list-Anfragen werden synchron über die POST-Anfrage gesendet.

• Andere Server-zu-Client-Nachrichten (z. B. tools/execute-Ergebnisse, Benachrichtigungen) werden über eine GET-Verbindung mit Server-Sent Events (SSE) gestreamt.

• Unterstützung für POST/GET/DELETE-Methoden

Wann verwenden: Wenn Sie den MCP-Server für Web-Clients oder Systeme bereitstellen müssen, die über HTTP statt über stdio kommunizieren.

Health-Check-Endpunkt

Bei Verwendung des HTTP-Transports ist unter /health ein Health-Check-Endpunkt für Überwachung und Service-Discovery verfügbar:

# Check server health
curl http://localhost:3000/health

# Response:
# {
#   "status": "healthy",
#   "activeSessions": 2,
#   "uptime": 3600
# }

Felder der Health-Antwort:

• status: Gibt immer "healthy" zurück, wenn der Server läuft

• activeSessions: Anzahl der aktiven MCP-Sitzungen

• uptime: Uptime des Servers in Sekunden

Hauptmerkmale:

• Keine Authentifizierung erforderlich

• Funktioniert mit jeder HTTP-Methode (GET, POST usw.)

• Ideal für Load Balancer, Kubernetes-Probes und Überwachungssysteme

Integrationsbeispiele:

# Kubernetes liveness probe
livenessProbe:
  httpGet:
    path: /health
    port: 3000
  initialDelaySeconds: 3
  periodSeconds: 10

# Docker healthcheck
HEALTHCHECK --interval=30s --timeout=3s \
  CMD curl -f http://localhost:3000/health || exit 1

Sicherheitshinweise

• Der HTTP-Transport validiert Origin-Header, um DNS-Rebinding-Angriffe zu verhindern

• Standardmäßig bindet der HTTP-Transport nur an localhost (127.0.0.1)

• Wenn Sie den Zugriff auf andere Hosts ermöglichen, sollten Sie eine zusätzliche Authentifizierung implementieren

Debugging

So zeigen Sie Debug-Protokolle an:

1. Bei Verwendung des Stdio-Transports mit Claude Desktop:

   • Die Protokolle erscheinen in den Claude-Desktop-Protokollen

2. Bei Verwendung des HTTP-Transports:

   npx @ivotoby/openapi-mcp-server --transport http &2>debug.log

Verwendung als Bibliothek

Dieser Abschnitt richtet sich an Entwickler, die dieses Paket als Bibliothek verwenden möchten, um eigene MCP-Server zu erstellen.

🚀 Verwendung als Bibliothek

Erstellen Sie dedizierte MCP-Server für spezifische APIs, indem Sie die OpenAPIServer-Klasse importieren und konfigurieren. Dieser Ansatz ist ideal für:

• Benutzerdefinierte Authentifizierung: Implementieren Sie komplexe Authentifizierungsmuster mit dem AuthProvider-Interface

• API-spezifische Optimierungen: Filtern Sie Endpunkte, passen Sie die Fehlerbehandlung an und optimieren Sie für bestimmte Anwendungsfälle

• Verteilung: Verpacken Sie Ihren Server als eigenständiges npm-Modul zum einfachen Teilen

• Integration: Betten Sie den Server in größere Anwendungen ein oder fügen Sie benutzerdefinierte Middleware hinzu

Grundlegende Verwendung der Bibliothek

import { OpenAPIServer } from "@ivotoby/openapi-mcp-server"
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js"

const config = {
  name: "my-api-server",
  version: "1.0.0",
  apiBaseUrl: "https://api.example.com",
  openApiSpec: "https://api.example.com/openapi.json",
  specInputMethod: "url" as const,
  headers: {
    Authorization: "Bearer your-token",
    "X-API-Key": "your-api-key",
  },
  transportType: "stdio" as const,
  toolsMode: "all" as const, // Options: "all", "dynamic", "explicit"
}

const server = new OpenAPIServer(config)
const transport = new StdioServerTransport()
await server.start(transport)

Lademodi für Tools

Die Konfigurationsoption toolsMode steuert, welche Tools aus Ihrer OpenAPI-Spezifikation geladen werden:

// Load all tools from the spec (default)
const config = {
  // ... other config
  toolsMode: "all" as const,
  // Optional: Apply filters to control which tools are loaded
  includeTools: ["GET::users", "POST::users"], // Only these tools
  includeTags: ["public"], // Only tools with these tags
  excludeTags: ["admin", "internal"], // Never expose tools with these tags
  includeResources: ["users"], // Only tools under these resources
  includeOperations: ["get", "post"], // Only these HTTP methods
}

// Load only dynamic meta-tools for API exploration
const config = {
  // ... other config
  toolsMode: "dynamic" as const,
  // Provides: list-api-endpoints, get-api-endpoint-schema, invoke-api-endpoint
  // excludeTags still hides matching operations from discovery and invocation
}

// Load only explicitly specified tools (include filters are ignored)
const config = {
  // ... other config
  toolsMode: "explicit" as const,
  includeTools: ["GET::users", "POST::users"], // Only these exact tools
  excludeTags: ["admin"], // Still applied as a deny filter
  // includeTags, includeResources, includeOperations are ignored in explicit mode
}

Konfiguration von Prompts und Ressourcen

Stellen Sie neben Ihren API-Tools wiederverwendbare Prompts und statische Ressourcen bereit:

import { OpenAPIServer } from "@ivotoby/openapi-mcp-server"

const config = {
  name: "my-api-server",
  version: "1.0.0",
  apiBaseUrl: "https://api.example.com",
  openApiSpec: "https://api.example.com/openapi.json",
  specInputMethod: "url" as const,
  transportType: "stdio" as const,
  toolsMode: "all" as const,

  // Define prompts with argument templates
  prompts: [
    {
      name: "api_request",
      title: "API Request Helper",
      description: "Helps generate API request templates",
      arguments: [
        { name: "endpoint", description: "API endpoint path", required: true },
        { name: "method", description: "HTTP method", required: false },
      ],
      template: "Create a {{method}} request to {{endpoint}} with proper parameters.",
    },
  ],

  // Define resources with static content
  resources: [
    {
      uri: "docs://api/overview",
      name: "api-overview",
      title: "API Overview",
      description: "Overview of the API capabilities",
      mimeType: "text/markdown",
      text: "# API Overview\n\nThis API provides...",
    },
  ],
}

const server = new OpenAPIServer(config)

Hinzufügen zusätzlicher benutzerdefinierter Tools

Sie können neben den aus Ihrer OpenAPI-Spezifikation generierten Tools auch einige handgeschriebene MCP-Tools bereitstellen:

import { OpenAPIServer } from "@ivotoby/openapi-mcp-server"

const extraTools = [
  {
    id: "add",
    tool: {
      name: "add",
      description: "Add two numbers",
      inputSchema: {
        type: "object",
        properties: {
          a: { type: "number" },
          b: { type: "number" },
        },
        required: ["a", "b"],
      },
    },
    handler: async (args) => {
      const a = Number(args.a)
      const b = Number(args.b)
      const result = a + b
      return {
        content: [{ type: "text", text: JSON.stringify({ result }) }],
        structuredContent: { result },
      }
    },
  },
]

const server = new OpenAPIServer({
  name: "my-api-server",
  version: "1.0.0",
  apiBaseUrl: "https://api.example.com",
  openApiSpec: "https://api.example.com/openapi.json",
  specInputMethod: "url",
  transportType: "stdio",
  toolsMode: "all",
  extraTools,
})

Hinweise:

• extraTools gibt es in dieser ersten Version nur für die Bibliothek; es gibt kein CLI-Format für Funktions-Handler

• Die IDs der zusätzlichen Tools und die MCP-Toolnamen müssen sowohl bei benutzerdefinierten als auch bei OpenAPI-generierten Tools eindeutig sein

• Handler für zusätzliche Tools müssen ein normales MCP-tools/call-Ergebnisobjekt zurückgeben

Dynamische Verwaltung von Prompts und Ressourcen

Sie können auch nach der Servererstellung dynamisch Prompts und Ressourcen hinzufügen:

const server = new OpenAPIServer(config)

// Add prompts dynamically
const promptsManager = server.getPromptsManager()
if (promptsManager) {
  promptsManager.addPrompt({
    name: "debug_error",
    title: "Error Debugger",
    template: "Debug this API error: {{error_message}}",
  })
}

// Add resources dynamically
const resourcesManager = server.getResourcesManager()
if (resourcesManager) {
  resourcesManager.addResource({
    uri: "docs://changelog",
    name: "changelog",
    title: "API Changelog",
    mimeType: "text/markdown",
    text: "# Changelog\n\n## v1.0.0\n- Initial release",
  })
}

Format für Prompt-Definitionen

interface PromptDefinition {
  name: string // Unique identifier
  title?: string // Human-readable display title
  description?: string // Description of the prompt
  arguments?: {
    // Template arguments
    name: string
    description?: string
    required?: boolean
  }[]
  template: string // Template with {{argName}} placeholders
}

Format für Ressourcendefinitionen

interface ResourceDefinition {
  uri: string // Unique URI identifier
  name: string // Resource name
  title?: string // Human-readable display title
  description?: string // Description of the resource
  mimeType?: string // Content MIME type
  text?: string // Static text content
  blob?: string // Static binary content (base64)
  contentProvider?: () => Promise<string | { blob: string }> // Dynamic content
}

Erweiterte Authentifizierung mit AuthProvider

Für APIs mit Token-Ablauf, Aktualisierungsanforderungen oder komplexer Authentifizierung:

import { OpenAPIServer, AuthProvider } from "@ivotoby/openapi-mcp-server"
import { AxiosError } from "axios"

class MyAuthProvider implements AuthProvider {
  async getAuthHeaders(): Promise<Record<string, string>> {
    // Called before each request - return fresh headers
    if (this.isTokenExpired()) {
      await this.refreshToken()
    }
    return { Authorization: `Bearer ${this.token}` }
  }

  async handleAuthError(error: AxiosError): Promise<boolean> {
    // Called on 401/403 errors - return true to retry
    if (error.response?.status === 401) {
      await this.refreshToken()
      return true // Retry the request
    }
    return false
  }
}

const authProvider = new MyAuthProvider()
const config = {
  // ... other config
  authProvider: authProvider, // Use AuthProvider instead of static headers
}

**📚 Siehe das Verzeichnis examples/ für vollständige funktionsfähige Beispiele, **:

• Einfache Bibliotheksnutzung mit statischer Authentifizierung

• AuthProvider-Implementierungen für verschiedene Szenarien

• Integration der realen Beatport-API

• Produktionsreife Verpackungsmuster

🔐 Dynamische Authentifizierung mit AuthProvider

Das AuthProvider-Interface ermöglicht komplexe Authentifizierungsszenarien, die statische Header nicht unterstützen können:

Key-Funktionen

• Dynamische Headers: Für jede Anfrage frische Auth-Header

• Behandlung von Token-Abläufen: Automatische Erkennung und Fehlerbehandlung

• Wiederherstellung bei Authentifizierungsfehlern: Wiederholungslogik für behebbare Fehler

• Benutzerdefinierte Fehlermeldungen: Klare und hilfreiche Anweisungen für Benutzer

Das AuthProvider-Interface

interface AuthProvider {
  /**
   * Get authentication headers for the current request
   * Called before each API request to get fresh headers
   */
  getAuthHeaders(): Promise<Record<string, string>>

  /**
   * Handle authentication errors from API responses
   * Called when the API returns 401 or 403 errors
   * Return true to retry the request, false otherwise
   */
  handleAuthError(error: AxiosError): Promise<boolean>
}

Häufige Muster

Automatische Token-Aktualisierung

class RefreshableAuthProvider implements AuthProvider {
  async getAuthHeaders(): Promise<Record<string, string>> {
    if (this.isTokenExpired()) {
      await this.refreshToken()
    }
    return { Authorization: `Bearer ${this.accessToken}` }
  }

  async handleAuthError(error: AxiosError): Promise<boolean> {
    if (error.response?.status === 401) {
      await this.refreshToken()
      return true // Retry with fresh token
    }
    return false
  }
}

Manuelle Token-Verwaltung (z. B. Beatport)

class ManualTokenAuthProvider implements AuthProvider {
  async getAuthHeaders(): Promise<Record<string, string>> {
    if (!this.token || this.isTokenExpired()) {
      throw new Error(
        "Token expired. Please get a new token from your browser:\n" +
          "1. Go to the API website and log in\n" +
          "2. Open browser dev tools (F12)\n" +
          "3. Copy the Authorization header from any API request\n" +
          "4. Update your token using updateToken()",
      )
    }
    return { Authorization: `Bearer ${this.token}` }
  }

  updateToken(token: string): void {
    this.token = token
    this.tokenExpiry = new Date(Date.now() + 3600000) // 1 hour
  }
}

API-Schlüssel-Authentifizierung

class ApiKeyAuthProvider implements AuthProvider {
  constructor(private apiKey: string) {}

  async getAuthHeaders(): Promise<Record<string, string>> {
    return { "X-API-Key": this.apiKey }
  }

  async handleAuthError(error: AxiosError): Promise<boolean> {
    throw new Error("API key authentication failed. Please check your key.")
  }
}

📖 You can find this documentation and examples in docs/auth-provider-guide.md

Verarbeitung von OpenAPI-Schemata

Referenzauflösung

Der MCP-Server unterstützt eine robuste $ref-Auflösung von OpenAPI-Referenzen, um API-Schemata genau darzustellen:

• Parameterreferenzen: Löst $ref-Referenzen auf Parameter-Komponenten in der OpenAPI-Spec vollständig auf

• Schemareferenzen: Verarbeitet verschachtelte Schema-Referenzen in den Param-/Body-Dateien

• Rekursive Referenzen: Verhindert Endlosschleifen durch automatische Zirkular-Erkennung

• Verschachtelte Eigenschaften: Enthält komplexe Objekt- und Array-Strukturen inklusive ihrer Attribute

Zusammensetzung des Eingabeschemas

Der Server kombiniert Parameter und Request-Bodies und ein zusammengesetztes Schema für jedes Tool:

• Parameter & Request-Body-Combining: Gleichschaltung von Path-, Query- und Body-Parametern in einem einzigen Schema

• Konfliktbehandlung: Löst Name-Konflikte auf, indem kollidierende Properties mit body_ www.

• Typenerhalt: Behält die ursprünglichen Typinformationen für alle Schema-Elemente

• Erhalt der Metadaten: Diese und weitere Attribute, Formate, Defaults und Enum-Werte werden nicht angetastet

Unterstützung komplexer Schemata

Der MCP-Server verfügt über aller lassen Sie uns umgehen. Mit Satz OpenAPI`-Schemata:

• Primitive-Bodys: Nicht-Objekt-Bodys werden in die "body"-Property eingeklappt

• Objekt-Bodys: Objekteigenschaften werden in dasTool-Eingabeschema eingefügt

• Array-Bodys: Arrays werden mit ihren verschachtelten Elementen korrekt verarbeitet

• Required-Felder-Auszeichnung: Speichert und behandelt Pflichtfelder

Informationen für Entwickler

Für Entwickler

Entwicklungs-Tools

• npm run build – Buildet den TypeScript-Quellcode

• npm run clean – Entfernt Build-Artefakte

• npm test – Startet die Vitest-Testsuite

• npm run typecheck – Führt Type-Typ Überprüfung

• npm run lint – Lint src/**/*.ts type-aware

• npm run dev – Watch-Quelldateien und baut bei Änderungen neu

• npm run inspect-watch – Startet den Inspector mit Auto-Reload automatisch

Vorbereitung für Pull Requests

Führen Sie die vollständigen lokalen Verifikations-Suites aus, bevor Sie Ihr PR stellen:

npm run build
npm test
npm run typecheck
npm run lint

npm run build regeneriert dist/ so, dass die CLI-Tests mit dem aktuellen Code laufen npm run lint ist bewusst type-aware und sollte für alle Quell-Dateien fehlerfrei sein.

Entwicklungsworkflow

1. Klonen Sie das Repository

2. Installieren Sie die Abhängigkeiten: npm install

3. Starten Sie die Entwicklungsumgebung: npm run inspect-watch

4. Ändern Sie die TypeScript-Dateien in src/

5. Der Server wird automatisch neu gebaut und neu gestartet

Beiträge

1. Erstellen Sie einen Fork des Repos

2. Erstellen Sie einen Feature-branch

3. Nehmen Sie Ihre Änderungen vor

4. Führen Sie Build, Tests, Typecheck und Lint aus: npm run build && npm test && npm run typecheck && npm run lint

5. Erstellen Sie einen Pull-Request

📖 Für die komplette Entwickler-Doku siehe docs/developer-guide.md

FAQ

F: Was ist ein „Tool”? A: Ein „Tool“ ist in diesem Zusammenhang ein API-Endpunkt, der aus Ihrer OpenAPI-Spezifikation kommt und als MCP-Ressource verfügbar gemacht wird.

F: Wie verwende ich das Paket in meinem Projekt? A: Importieren Sie die OpenAPIServer-Klasse und verwenden Sie sie als Bibliothek in Ihrer Node.js-Anwendung. Das erlaubt Ihnen dedizierte MCP-Server für eine API mit eigener Auth, Filterung und Fehlerbehandlung zu bauen. Siehe examples/ für Komplettlösungen.

F: Was ist der Unterschied zwischen der CLI und der Bibliotheknutzung? A: Die CLI ist ideal für Quick-Setup und Test. Im Library-Modus können Sie eigene Pakete für bestimmte APIs anlegen, benutzerdefinierte Auth (mit AuthProvider) implementieren, eigene Logik hinzufügen und Ihren Server als npm-Modul mit anderen teilen.

F: Wie handle ich APIs mit ablaufenden Tokens? A: Verwenden Sie das AuthProvider-Interface statt statischer Header. Der Provider kann Sie verwenden und Ihnen frische Token-Entity bereitstellen: track expiry, refresh and during falls. Und lesen die AuthProvider-Doku für Muster.

F: Was ist AuthProvider und wann nutze ich sie? A: AuthProvider ist eine Schnittstelle für dynamische Authentifizierung, die die neuen Header before jedem Request liefert und Auth-Fehler behandelt. Nutzen Sie ihn, wenn Token ablaufen, ein automatisches Refresh nötig ist, also eine Api mit complex Auth, die static header nicht liefert.

F: Wie filtere ich, welche Tools geladen werden? A: Filtern über die Flags --tool, --tag, --exclude-tag, --resource und --operation mit --tools all (Standard). Setzen Sie --tools dynamic für nur Agenten-System oder --tools explicit für in --to. Mit --exclude-tag` gilt dynamisch/in.

F: Wann sollte ich den dynamischen Modus verwenden? A: dynamische Modus hat Tool-Metadaten (list-api-endpoints, get-api-endpoint-schema, invoke-api-endpoint) zum Anzeigen und Aufrufen von Endpunkten – ohne dass alle Sensoren im Voraus geladen sind; empfohlen bei großen oder API-Variablen.

F: Was sind Prompts and Ressources? A: Prompts sind wiederverwendbare Nachrichtenvorlagen mit Platzhaltern wie {{name}}, die über MCP prompts/get and die Resources are static oder dynamic Inhalte (Textieren / Binär), die mit resources/read aus Engelesen werden können. Beide sind optional, zusätzlich conf.

F: Wie man sie über die CLI Pin A: Aufruf --prompts <path|url> für Prompts (idd) oder --resource. Sie können außerdem --prompts-inline and --resources-json verwenden. Details im Abschnitt „Prompts und Resources“ im Benutzerhandbuch.

F: Wo gebe ich Custom Header für den Request an? A: CLI: --headers oder API_HEADERS umgeben mit key:value, Komma. Bei einiger Bibliothek-Option headers Option verwenden oder einen eigenen AuthProvider implementieren, der dynamisch Headers.

F: Welche Transport-Arten gibt es? A: Server unterstützt Stdio (Standard) für AI und HTTP (mit SSE-Streaming) für Browser.

F: Wie werden schwierige Schemas behandelt? A: Sie vollständige $ref- und Schema Attributes auf und behält zirkulares. Sehen OpenAPI Schema Processing für die Details.

F: Bei Namenskonflikten zwischen Parametri und Body? A: Der Server erkennt sie und versieht body-Eigenschaften automatisch mit body_, so dass alle zugreifbar bleiben.

F: Kann ich meinen Server weiter verteilen? A: Ja! Der Bibliothekansatz ist ideal. Erstellen Sie ein natürlich oder npm-Paket gemäß dem „Beatport“-Beispiel, verpacken Sie in robuste npx your-api-mcp-server zu verbereiten und auszuliefern.

F: Wo gibt's Entwicklungs- und Mitwirkungs Guideline? A: Im Entwicklerleitfaden für Architektur besonders, Konzepte, den Entwicklungsworkflow und viele Beitragsleitfaden.

License

MIT