openapi-md-mcp

Ein MCP-Server, der OpenAPI-Specs progressiv offenlegt (progressive disclosure) als Markdown.

Warum

• Swagger UI (/docs) ist eine JS-Hülle, die AI kann den Inhalt nicht erfassen.

• Die vollständige /openapi.json umfasst oft dutzende K Tokens; den gesamten Kontext damit zu füllen ist zu teuer.

• Dieses Tool gibt der AI nur eine dauerhaft im Kontext residente Endpunkttabelle mit „Schlüssel + Zusammenfassung“ (~1k Tokens). Über den Schlüssel wird in die Markdown-Details eines einzelnen Endpunkts / Schemas eingetaucht. In der Praxis spart das ~90% Kontext.

Related MCP server: OpenAPI MCP Server

Tools (progressive Offenlegung, alle Ausgaben als Markdown)

Der Drilldown-Schlüssel ist METHOD /path oder der Schema-Name; er wird direkt aus der Ausgabe der oberen Ebene übernommen.

Batch-Modus (select + get_batch)

Der Drilldown mit einem einzelnen Schlüssel kann horizontale Fragen nicht beantworten („alle authentifizierten Endpunkte“ erforderten dutzende einzelne get_endpoint-Aufrufe), die Batch-Ebene füllt diese Lücke:

• select(patterns=["GET /v1/auth/*", "* /v1/scoring/*"], security="X-Service-Token", tag="scoring", schema_glob="Credit*")

  • patterns-Elemente haben die Form "METHOD /path/glob": Die Methode kann * sein (Groß-/Kleinschreibung wird ignoriert); der Pfad-Glob unterscheidet Groß-/Kleinschreibung.

  • security ist der Scheme-Name; zwischen den patterns gilt OR, mit security/tag gilt AND.

  • Null Treffer liefern Erfolgstext (verfügbare Schemes/Tags + Vorschläge zur Lockerung), keinen Fehler.

• get_batch(["POST /v1/scoring/credit", "CreditBatchRequest"])

  • Schlüssel werden dedupliziert und in Reihenfolge beibehalten, Obergrenze 40; die Gesamtzahl der gerenderten Zeichen ist auf 100k begrenzt; bei Überschreitung wird include_refs=False oder eine Aufteilung in Chargen empfohlen.

  • include_refs=True fasst die im Rendering referenzierten $ref automatisch zu einem „gemeinsamen Schema-Anhang“ zusammen (jeder Name wird nur einmal gerendert).

Konfiguration (env)

• Die Spec unterstützt JSON und YAML; nach dem Laden wird sie 60 s im Prozess zwischengespeichert.

• Die Anfragen erfolgen direkt (trust_env=False): Ziel ist eine localhost-/Intranet-Spec, der Systemproxy wird nicht verwendet (der macOS-Systemproxy kapert localhost und erzeugt 502).

• Nur lesend, keine Fähigkeit zum Aufrufen von APIs (Authentifizierungs-Header gelangen nicht in die MCP-Ebene).

Einbindung in beliebige Repositories

Claude-Code-Registrierung auf Benutzerebene (einmal registriert, für alle Repositories verfügbar):

claude mcp add openapi-md -s user -- \
  uv run --directory /path/to/openapi-md-mcp openapi-md-mcp

Repositories, die unterschiedliche Datenquellen benötigen, überschreiben einfach die env-Werte in ihrem projektweiten .mcp.json.

Protokollkonformität (MCP 2026-07-28, allgemein als 2.0 bekannt)

• Toolname / Beschreibung / inputSchema entsprechen der Spezifikation §Tools (Zeichensatz und Länge der Namen, deterministische tools/list-Reihenfolge).

• Alle fünf Tools deklarieren annotations.readOnlyHint: true (nur lesen).

• Die Fehlersemantik folgt §Tools Error Handling der Spezifikation: Spec-Ladefehler, unbekannte Schlüssel (einschließlich Vorschlägen für ähnliche Schlüssel), ungültige Filterpatterns und Überschreitung des Batch-Limits werden als Tool Execution Error mit ToolError geworfen → auf der Leitung erscheint das als CallToolResult(isError=true), der Client gibt die Vorschläge zur Selbstkorrektur an das Modell zurück; Null Treffer sind Erfolgstext; keine call-Fähigkeit (API-Aufruf).

• Versionsaushandlung: stdio nutzt die initialize-Handshake-Ära (maximal 2025-11-25); die zustandslose Envelope-Ära von 2026-07-28 wird vom SDK auf der HTTP-Transportebene behandelt (server/discover), das stdio-Szenario ist nicht betroffen.

Entwicklung

uv sync                 # 安装依赖
uv run pytest --cov=openapi_md_mcp   # 测试（fixture 为真实 OpenAPI 3.1 快照）