SpecBridge MCP

SpecBridge MCP ist ein „Clone-and-own“-MCP-Starter, um OpenAPI/Huma-Vertragsintelligenz für KI-Agenten verfügbar zu machen. Es wandelt OpenAPI/Huma-Spezifikationen in deterministische Endpunkt-Metadaten, Schemas, Validierungsfakten, referenzierte DTOs und TypeScript-Deklarationen um, die Agenten verwenden können, bevor sie Frontend- oder Client-Code ändern.

Dieses Projekt ist bewusst „Repository-first“ konzipiert und nicht als npm-Paket veröffentlicht: Klonen Sie es, passen Sie die Backend-Registrierung an Ihre privaten oder öffentlichen Spezifikationen an und registrieren Sie den lokalen MCP-Server bei Ihrem Agent-Host. Die Implementierung hält den Kern neutral, indem sie Dateimanipulationen nachgelagert vermeidet, ein neutrales öffentliches Demo-Backend verwendet, mehrere injizierte Backends unterstützt und abgeleitete Hilfsmittel als „Best-Effort“ und nicht als Garantien behandelt.

Status: experimentell. Die Tool-Oberfläche ist nützlich für lokale Automatisierung, aber das Repository ist dazu gedacht, von jedem Team selbst verwaltet und angepasst zu werden.

Kurze Geschichte

SpecBridge MCP begann als persönliches internes Tool bei SesameLab, um den Entwicklungszyklus rund um Backend-API-Verträge zu verbessern. In der Praxis reduzierte die Bereitstellung strukturierter OpenAPI/Huma-Vertragsdaten für KI-Agenten über MCP Halluzinationen im Vergleich dazu, sie direkt API-Dokumentationsseiten lesen zu lassen.

Was es bietet

• Konfigurierbare Backend-Registrierung für eine oder mehrere OpenAPI/Huma-kompatible Spezifikationen

• Zero-Config-Demo-Backend unter Verwendung einer echten öffentlichen OpenAPI-URL

• Laden und Aktualisieren von Spezifikationen mit JSON/YAML-Unterstützung

• Auflistung und Filterung von Endpunkten

• Endpunkt-Vertragsbündel mit deterministischen Fakten:

  • Operations-Metadaten

  • Parameter

  • Anfrage- und Antwort-Schemas

  • Referenzierte Komponenten-Schemas

  • Endpunkt-spezifische TypeScript-DTO-Deklarationen

  • Validierungsfakten wie required, nullable, enum, format, Arrays, Maps und Komposition

• Generierung von TypeScript-DTO-Deklarationen aus Komponenten-Schemas

• „Best-Effort“-Vorschlagshilfen, die explizit zweitrangig gegenüber deterministischen Spezifikationsfakten sind

Nicht-Ziele

• Veröffentlichung dieses Projekts auf npm für v1

• Bereitstellung einer generischen installierbaren CLI-Abstraktion

• Veränderung von nachgelagerten Frontend-/Client-Repositories

• Entwicklung eines Framework-spezifischen Clients oder SDK-Generators

• Hosting von Spezifikationen oder Remote-Speicherung von Team-API-Daten

Anforderungen

• Node.js 18+

• pnpm 10+

Installation

git clone <your-fork-or-copy-url> specbridge-mcp
cd specbridge-mcp
pnpm install
pnpm build

Backends konfigurieren

SpecBridge wird mit openapi.backends.json ausgeliefert, das auf eine öffentliche Demo-API verweist, damit die Tools sofort funktionieren.

Um Ihre eigenen APIs zu verwenden, bearbeiten Sie openapi.backends.json oder verweisen Sie OPENAPI_BACKENDS_FILE auf eine andere JSON-Datei.

[
  {
    "id": "public-demo",
    "name": "Public Demo API",
    "specUrl": "https://petstore3.swagger.io/api/v3/openapi.json",
    "description": "Public OpenAPI demo backend",
    "domainHints": ["/pet", "/store", "/user"]
  },
  {
    "id": "local-service",
    "name": "Local Service API",
    "specUrl": "http://localhost:8080/openapi.json",
    "fallbackSpecUrls": ["http://localhost:8080/openapi.yaml"],
    "description": "Your local service contract"
  }
]

Konfigurationsvorrang

Bei einem Tool-Aufruf wird zuerst eine explizite specUrl-Überschreibung für diesen Aufruf versucht.

Backend-Registrierungsquellen werden in dieser Reihenfolge zusammengeführt, wobei spätere Quellen frühere anhand der id überschreiben:

1. Eingebautes öffentliches Demo-Backend

2. Repository-lokale openapi.backends.json, falls vorhanden

3. OPENAPI_BACKENDS_FILE, falls gesetzt

4. OPENAPI_BACKENDS, falls gesetzt

DEFAULT_BACKEND_ID wählt das Standard-Backend aus. Wenn nicht gesetzt, verwendet SpecBridge swagger-petstore.

Umgebungsvariablen

• MCP_TRANSPORT: stdio oder http

• MCP_HTTP_HOST: HTTP-Bind-Host

• MCP_HTTP_PORT: HTTP-Port

• MCP_HTTP_PATH: MCP-Endpunktpfad, z. B. /mcp

• MCP_HTTP_STATELESS: auf true setzen für zustandslosen HTTP-Modus

• DEFAULT_BACKEND_ID: Standard-Backend-ID

• OPENAPI_BACKENDS: JSON-Array von Backend-Konfigurationen

• OPENAPI_BACKENDS_FILE: Pfad zu einer Backend-Konfigurations-JSON-Datei

• OPENAPI_FETCH_TIMEOUT_MS: Fetch-Timeout für das Laden von Spezifikationen

• OPENAPI_CACHE_TTL_MS: In-Memory-Spezifikations-Cache-TTL

• OPENAPI_ENABLE_SWAGGER_UI_SCRIPT_EXTRACTION: Opt-in für strikte JSON-Objekt-Extraktion aus statischen Swagger-UI-Skripten; abgerufene JavaScript-Dateien werden niemals ausgeführt

Ausführen

stdio-Modus

pnpm mcp
# or
./mcp-server.sh

HTTP-Modus

pnpm mcp:http

Zustandsloser HTTP-Modus:

pnpm mcp:http:stateless

MCP-Host-Einrichtung

Befehlsbasierte stdio-Konfiguration

{
  "mcpServers": {
    "specbridge-mcp": {
      "command": "/absolute/path/to/specbridge-mcp/mcp-server.sh"
    }
  }
}

Codex config.toml-Beispiel

[mcp_servers.specbridge-mcp]
args = ["/absolute/path/to/specbridge-mcp/mcp-server.sh"]
command = "bash"

HTTP-URL

Starten Sie den Server:

./mcp-server.sh --transport http --host 127.0.0.1 --port 3000 --path /mcp

Verbinden Sie dann Ihren Host mit:

• http://127.0.0.1:3000/mcp

Wenn Ihr Host Probleme mit dem Sitzungsstatus hat, versuchen Sie es erneut mit --stateless.

Tools

Empfohlener Ablauf:

1. list_backends

2. load_openapi_spec

3. list_api_endpoints

4. get_endpoint_contract

5. generate_typescript_dto

list_backends

Listet konfigurierte Backend-Ziele, die Standard-Backend-ID und optionale Domain-Hinweise auf.

load_openapi_spec

Lädt oder aktualisiert eine OpenAPI/Huma-kompatible Spezifikation für ein Backend. Unterstützt direkte specUrl-Überschreibungen.

list_api_endpoints

Listet Endpunkte aus einer geladenen Spezifikation mit optionalen Filtern für Tag, Methode, Pfad-Substring und Limit auf.

get_endpoint_contract

Gibt ein deterministisches Endpunkt-Vertragsbündel zurück: Operations-Metadaten, Parameter, Request-Body, Antworten, referenzierte Schemas, Endpunkt-spezifische TypeScript-DTO-Deklarationen, Validierungsfakten und „Best-Effort“-Hinweise.

generate_typescript_dto

Generiert TypeScript-DTO-Deklarationen aus einem Komponenten-Schemanamen und enthält referenzierte verschachtelte DTO-Typen.

propose_new_endpoint

Gibt einen „Best-Effort“-Endpunkt- und DTO-Vorschlag zurück, der auf Mustern basiert, die in der aktuellen Spezifikation gefunden wurden. Betrachten Sie dies als Agenten-Hilfe, nicht als deterministische Garantie.

Entwicklung

pnpm install
pnpm check
pnpm build
pnpm test

Nützliche Skripte:

• pnpm check: Biome-Check

• pnpm format: Biome-Formatierung anwenden

• pnpm lint: Nur Biome-Linting

• pnpm build: Sauberes TypeScript-Build

• pnpm test: Alle Tests bauen und ausführen

• pnpm test:e2e: MCP-Smoke-Tests bauen und ausführen

„Clone-and-own“-Leitfaden

SpecBridge ist bewusst „Repository-first“. Halten Sie den Kern klein, passen Sie die Backend-Konfiguration lokal an und lassen Sie nachgelagerte Agenten entscheiden, wie Ihr Client-Code bearbeitet werden soll. Wenn Ihr Team benutzerdefinierte Authentifizierung, interne Namensregeln oder zusätzliche Vertragsfakten benötigt, fügen Sie diese in Ihrem Klon hinzu, anstatt gegen eine globale Paketabstraktion zu kämpfen.