MCP-DOC-MID: MCP-Server für OpenAPI und Generierung von Integrationen

Unternehmensreifer Server für das Model Context Protocol (MCP)-Ökosystem in Node.js (ES Modules), spezialisiert auf das Lernen, Dereferenzieren ($ref) und Ermöglichen, dass ein LLM OpenAPI/Swagger-Spezifikationen abfragt und produktionsreife Code-Integrationen generiert.

Verwendet @apidevtools/swagger-parser, um beim Start des Servers alle Verweise und Komponenten-Schemata im Speicher aufzulösen, und stellt einen Katalog von 8 MCP-Tools bereit, die für Suche, Inspektion, Validierung und Generierung von HTTP-Clients in mehreren Sprachen (TypeScript, Python, JavaScript, cURL, C#) entwickelt wurden.

📚 Detaillierte Dokumentation

Für spezialisierte Anleitungen und vollständige Diagramme siehe:

• 🏛️ Leitfaden zur Systemarchitektur (docs/ARCHITECTURE.md): Flussdiagramme, Session Binding, Beobachtbarkeit, atomare Information und Circuit Breaker.

• 🛠️ Referenz der MCP-Tools (docs/TOOLS_REFERENCE.md): Detaillierte Parameter, JSON-Schemata und Antwortbeispiele für jedes Tool.

• 📂 Leitfaden für Swagger-/Arquivo OpenAPI (docs/SWAGGER_GUIDE.md): Anweisungen zum Hinzufügen, Validieren und Organisieren von .yml- und .json-Spezifikationen.

• 📋 Strukturelle Spezifikation Doters API Internal (docs/MIDDLEWARE_API_SPEC.md): Analyse der 110 Endpoints, 221 DTOs, Response-Wrapper und 25 Domänen von middleware-api.json.

Related MCP server: mcp-swagger

🏛️ Hauptmerkmale

1. Automatisches Lesen und Dereferenzieren (swaggers/):

   • Rekursives Scannen von .yml, .yaml- und .json-Dateien.

   • Vollständige Auflösung von $ref-Referenzen in Komponenten, Parametern und Modellen.

2. Generierung von Code-Integrationen für LLMs:

   • generate_integration_code: Generiert Snippets und stark typisierte Clients für jeden Endpoint.

   • Unterstützung für TypeScript (fetch/axios), JavaScript, Python (httpx/requests), cURL und C#.

3. Validierung und Extraktion von Sicherheit:

   • validate_payload: Vorab-Validierung, ob ein JSON-Payload die erforderlichen Typen und Felder erfüllt.

   • get_security_schemes: Extraktion von Authentifizierungsschemata (Bearer-Tokens, API-Keys, OAuth2).

4. Dualer Transport:

   • STDIO: Standard-Integration mit Claude Desktop, Antigravity, Cursor und MCP-Erweiterungen.

   • SSE / HTTP: Express-Server mit Schreib-/sse, /messages, /metrics, /health und /dashboard.

5. Beobachtbarkeit und Sicherheit:

   • Logs ausschließlich über process.stderr mit Pino.

   • Prometheus-Metriken (prom-client) unter /metrics.

   • Session Binding und Schutz vor Session Hijacking unter /messages.

🛣️ Der Integrationsablauf in 3 Schritten (Zero-Code)

Damit die Integration neuer APIs 100 % Coco ist, bis zuletzt ohne Reibung und ohne eine einzige Zeile Code, implementiert der Server Automatische Erkennung und Laden per Konvention:

flowchart LR
    A["1. Copiar Archivo\n(swaggers/mi-api.json o .yml)"] --> B["2. Auto-Discovery & Caching\n(Hash SHA-256 + Dereference)"]
    B --> C["3. Auto-Diagnóstico\n(npm run self-test)"]
    C --> D["✅ Disponible en las 8 Tools MCP\n(search_docs, get_endpoint_doc, etc.)"]

1️⃣ Schritt 1: Datei in swaggers/ ablegen

Lege deine .json-, .yml- oder .yaml-Datei einfach im Verzeichnis swaggers/ ab.

📁 Empfohlene skalierbare Struktur (nach Domänen oder Microservices):

Der Scanner ist rekursiv, du kannst deine Dateien also in thematischen Unterordnern organisieren, während die Anzahl der APIs steigt:

swaggers/
├── middleware-api.json                # API Core Middleware
├── partners/
│   ├── avasa-car-rental.json          # Swagger de Avasa
│   └── iamsa-bus.json                 # Swagger de IAMSA
├── payments/
│   └── openpay-gateway.yml            # OpenAPI de Pasarelas de Pago
└── flights/
    └── viva-booking.yaml              # OpenAPI de Reservaciones Viva

[!TIP] Automatischer Identifikator (specId): Das System generiert die specId automatisch aus dem Basisnamen der Datei:

• avasa-car-ren tal.json $\rightarrow$ specId: "avasa-car-rental"

• openpay-gateway.yml $\rightarrow$ specId: "openpay-gateway"

2️⃣ Schritt 2: Integrität prüfen mit npm run self-test

Du musst keine MCP-Clients starten oder Server blind neu starten. Führe im Terminal aus:

npm run self-test

Was macht dieser Befehl in weniger als 15 ms?

1. Erkennt die neue Datei und berechnet ihren SHA-256-Hash.

2. Löst und dereferenziert automatisch alle $ref-Referenzen.

3. Bereinigt defekte oder fehlende Verweise, damit der Server nie kollabiert.

4. Generiert den leistungsstarken Snapshot in .cache/swaggers/.

5. Zeigt die Zusammenfassung in Echtzeit an:

{
  "status": "healthy",
  "checks": {
    "swaggers": {
      "status": "pass",
      "specsCount": 4,
      "endpointsCount": 285,
      "schemasCount": 412
    }
  }
}

3️⃣ Schritt 3: Bereit für Abfragen durch Agents und LLMs

Sofort erlernen die 8 MCP-Tools die neuen Endpunkte und Schemata, ohne dass eine zusätzliche Konfiguration nötig ist:

• Globale Suche: search_docs({ query: "rent a autos" }) durchsucht alle Swaggers gleichzeitig.

• Gefilterte Suche: search_docs({ query: "renta", specId: "avasa-car-rental" }) fragt ausschließlich diese API ab.

• Codegenerierung: generate_integration_code({ path: "/v1/cars/book", language: "typescript" }) erzeugt den typisierten Client.

• Payloadvalidierung: validate_payload({ schemaName: "CarBookingDto", payload: { ... } }) validiert gegen das neue Modell.

🏆 Bewährte Methoden für maximale Qualität im LLM

Damit die Sprachmodelle beim Lesen deiner neuen Swaggers den besten Code und die präzisesten Antworten generieren:

1. Basis-URL deklarieren (servers):

servers:
  - url: https://api.vivaaerobus.com/v1
    description: Ambiente de Producción

2. Beispiele in die Schemas aufnehmen (example / examples): Die Beispiele ermöglichen dem Tool generate_integration_code und dem LLM, automatisch realistische Test-Payloads zu erstellen.

3. Klare Tags verwenden (tags): Die Gruppierung in Tags (z.B. [ "CarRental", "Payments", "Security" ]) ermöglicht den Agenten, Endpunkt-Sammlungen schnell über search_docs({ tag: "Payments" }) zu filtern.

4. Sicherheit deklarieren (components.securitySchemes): Angeben, ob bearerFormat: JWT, ApiKey oder OAuth2 verwendet wird, damit das Tool get_security_schemes die benötigten Header bereitstellt.

🛠️ Vorhandene MCP-Tools

⚙️ Umgebungsvariablen (.env)

🚀 Schnellstart

# 1. Instalar dependencias
npm install

# 2. Autodiagnóstico en runtime (<5ms)
npm run self-test

# 3. Iniciar en modo STDIO (predeterminado)
npm start

# 4. Iniciar en modo SSE / HTTP (servidor web)
TRANSPORT_MODE=sse PORT=3000 npm start

📦 Tests und Benchmarks

Das Projekt verfügt über eine umfassende Testsuite mit 116 Tests bestanden (100%) und einer Abdeckung von über 93% der Anweisungen:

# 1. Ejecutar suite completa de pruebas unitarias y de integración
npm test

# 2. Reporte de cobertura detallado con Vitest y V8 (>93% Stmts)
npm run test:coverage

# 3. Pruebas de carga de alta concurrencia (100 agentes concurrentes)
npm run test:load

# 4. Benchmark de latencia y throughput (<5ms)
npm run benchmark

# 5. Pipeline de integración continua (CI)
npm run test:ci

🐳 Deployment mit Docker

# Construir imagen Docker multi-stage
docker build -t mcp-doc-mid:latest .

# Ejecutar contenedor en modo SSE
docker run -p 3000:3000 -e TRANSPORT_MODE=sse mcp-doc-mid:latest