OpenAPI Schema Explorer

MCP OpenAPI Schema Explorer

Ein MCP-Server (Model Context Protocol), der über MCP-Ressourcen tokeneffizienten Zugriff auf OpenAPI- (v3.0) und Swagger- (v2.0) Spezifikationen bietet.

Projektziel

Das Hauptziel dieses Projekts besteht darin, MCP-Clients (wie Cline oder Claude Desktop) die Möglichkeit zu geben, die Struktur und Details großer OpenAPI-Spezifikationen zu erkunden, ohne die gesamte Datei in das Kontextfenster eines LLM laden zu müssen. Dies wird erreicht, indem Teile der Spezifikation über MCP-Ressourcen bereitgestellt werden, die sich gut für die schreibgeschützte Datenexploration eignen.

Dieser Server unterstützt das Laden von Spezifikationen sowohl aus lokalen Dateipfaden als auch aus Remote-HTTP/HTTPS-URLs. Swagger v2.0-Spezifikationen werden beim Laden automatisch in OpenAPI v3.0 konvertiert.

Warum MCP Resources?

Das Model Context Protocol definiert sowohl Ressourcen als auch Tools .

• Ressourcen: Stellen Datenquellen dar (wie Dateien, API-Antworten). Sie eignen sich ideal für den schreibgeschützten Zugriff und die Erkundung durch MCP-Clients (z. B. zum Durchsuchen von API-Pfaden in Claude Desktop).
• Tools: Stellen ausführbare Aktionen oder Funktionen dar, die häufig von LLMs verwendet werden, um Aufgaben auszuführen oder mit externen Systemen zu interagieren.

Während andere MCP-Server Zugriff auf OpenAPI-Spezifikationen über Tools ermöglichen, konzentriert sich dieses Projekt speziell auf den Zugriff über Resources . Dies macht es besonders nützlich für die direkte Erkundung innerhalb von MCP-Clientanwendungen.

Weitere Einzelheiten zu MCP-Clients und ihren Funktionen finden Sie in der MCP-Client-Dokumentation .

Installation

Für die empfohlenen Verwendungsmethoden ( npx und Docker, unten beschrieben) ist kein separater Installationsschritt erforderlich . Ihr MCP-Client lädt das Paket herunter oder ruft das Docker-Image basierend auf der von Ihnen angegebenen Konfiguration automatisch ab.

Wenn Sie den Server jedoch lieber explizit installieren möchten oder müssen, haben Sie zwei Möglichkeiten:

1. Globale Installation: Sie können das Paket global mit npm installieren:
   npm install -g mcp-openapi-schema-explorer
   Informationen zum Konfigurieren Ihres MCP-Clients für die Verwendung eines global installierten Servers finden Sie weiter unten unter Methode 3 .
2. Lokale Entwicklung/Installation: Sie können das Repository klonen und lokal erstellen:
   git clone https://github.com/kadykov/mcp-openapi-schema-explorer.git cd mcp-openapi-schema-explorer npm install npm run build
   Unter Methode 4 unten erfahren Sie, wie Sie Ihren MCP-Client so konfigurieren, dass der Server mithilfe von node von Ihrem lokalen Build aus ausgeführt wird.

Hinzufügen des Servers zu Ihrem MCP-Client

Dieser Server ist für den Betrieb durch MCP-Clients (wie Claude Desktop, Windsurf, Cline usw.) konzipiert. Um ihn zu nutzen, fügen Sie der Einstellungsdatei Ihres Clients (häufig eine JSON-Datei) einen Konfigurationseintrag hinzu. Dieser Eintrag teilt dem Client mit, wie der Serverprozess ausgeführt werden soll (z. B. mit npx , docker oder node ). Der Server selbst benötigt keine separate Konfiguration über die im Client-Einstellungseintrag angegebenen Kommandozeilenargumente hinaus.

Nachfolgend finden Sie die gängigen Methoden zum Hinzufügen des Servereintrags zur Konfiguration Ihres Clients.

Methode 1: npx (empfohlen)

Die Verwendung npx wird empfohlen, da dadurch eine globale/lokale Installation vermieden wird und sichergestellt wird, dass der Client die neueste veröffentlichte Version verwendet.

Beispiel eines Client-Konfigurationseintrags (npx-Methode):

Fügen Sie das folgende JSON-Objekt zum Abschnitt mcpServers der Konfigurationsdatei Ihres MCP-Clients hinzu. Dieser Eintrag weist den Client an, wie er den Server mit npx ausführen soll:

Konfigurationshinweise:

• Ersetzen Sie "My API Spec (npx)" durch einen eindeutigen Namen für diese Serverinstanz in Ihrem Client.
• Ersetzen Sie <path-or-url-to-spec> durch den absoluten lokalen Dateipfad oder die vollständige Remote-URL Ihrer Spezifikation.
• Das --output-format ist optional ( json , yaml , json-minified ), der Standardwert ist json .
• Um mehrere Spezifikationen zu untersuchen, fügen Sie in mcpServers separate Einträge hinzu, von denen jeder einen eindeutigen Namen hat und auf eine andere Spezifikation verweist.

Methode 2: Docker

Sie können Ihren MCP-Client anweisen, den Server mit dem offiziellen Docker-Image auszuführen: kadykov/mcp-openapi-schema-explorer .

Beispiele für Client-Konfigurationseinträge (Docker-Methode):

Fügen Sie im Abschnitt mcpServers der Konfigurationsdatei Ihres MCP-Clients eines der folgenden JSON-Objekte hinzu. Diese Einträge weisen den Client an, wie der Server mit docker run ausgeführt wird:

• Remote-URL: Übergeben Sie die URL direkt an docker run .
• Verwenden einer Remote-URL:
  { "mcpServers": { "My API Spec (Docker Remote)": { "command": "docker", "args": [ "run", "--rm", "-i", "kadykov/mcp-openapi-schema-explorer:latest", "<remote-url-to-spec>" ], "env": {} } } }
• Verwenden einer lokalen Datei: (Erfordert das Einbinden der Datei in den Container)
  { "mcpServers": { "My API Spec (Docker Local)": { "command": "docker", "args": [ "run", "--rm", "-i", "-v", "/full/host/path/to/spec.yaml:/spec/api.yaml", "kadykov/mcp-openapi-schema-explorer:latest", "/spec/api.yaml", "--output-format", "yaml" ], "env": {} } } }
  Wichtig: Ersetzen Sie /full/host/path/to/spec.yaml durch den korrekten absoluten Pfad auf Ihrem Host-Rechner. Der Pfad /spec/api.yaml ist der entsprechende Pfad innerhalb des Containers.

Methode 3: Globale Installation (seltener)

Wenn Sie das Paket global mit npm install -g installiert haben, können Sie Ihren Client so konfigurieren, dass es direkt ausgeführt wird.

Beispiel eines Client-Konfigurationseintrags (globale Installationsmethode):

Fügen Sie den folgenden Eintrag zur Konfigurationsdatei Ihres MCP-Clients hinzu. Dies setzt voraus, dass der Befehl mcp-openapi-schema-explorer im PATH der Ausführungsumgebung des Clients zugänglich ist.

• Stellen Sie sicher, dass der command ( mcp-openapi-schema-explorer ) in der von Ihrem MCP-Client verwendeten Umgebungsvariable PATH zugänglich ist.

Methode 4: Lokale Entwicklung/Installation

Diese Methode ist nützlich, wenn Sie das Repository lokal zur Entwicklung geklont haben oder eine geänderte Version ausführen möchten.

Einrichtungsschritte (einmal in Ihrem Terminal ausführen):

1. Klonen Sie das Repository: git clone https://github.com/kadykov/mcp-openapi-schema-explorer.git
2. Navigieren Sie in das Verzeichnis: cd mcp-openapi-schema-explorer
3. Abhängigkeiten installieren: npm install
4. Erstellen Sie das Projekt: npm run build (oder just build )

Beispiel für einen Client-Konfigurationseintrag (lokale Entwicklungsmethode):

Fügen Sie der Konfigurationsdatei Ihres MCP-Clients den folgenden Eintrag hinzu. Dadurch wird der Client angewiesen, den lokal erstellten Server mit node auszuführen.

Wichtig: Ersetzen Sie /full/path/to/cloned/mcp-openapi-schema-explorer/dist/src/index.js durch den richtigen absoluten Pfad zur erstellten Datei index.js in Ihrem geklonten Repository.

Merkmale

• MCP-Ressourcenzugriff: Erkunden Sie OpenAPI-Spezifikationen über intuitive URIs ( openapi://info , openapi://paths/... , openapi://components/... ).
• Unterstützung für OpenAPI v3.0 und Swagger v2.0: Lädt beide Formate und konvertiert v2.0 automatisch in v3.0.
• Lokale und Remote-Dateien: Laden Sie Spezifikationen von lokalen Dateipfaden oder HTTP/HTTPS-URLs.
• Token-effizient: Entwickelt, um die Token-Nutzung für LLMs durch Bereitstellung eines strukturierten Zugriffs zu minimieren.
• Mehrere Ausgabeformate: Erhalten Sie detaillierte Ansichten in JSON (Standard), YAML oder minimiertem JSON ( --output-format ).
• Dynamischer Servername: Der Servername in MCP-Clients spiegelt den info.title aus der geladenen Spezifikation wider.
• Referenztransformation: Interne $ref s ( #/components/... ) werden in anklickbare MCP-URIs umgewandelt.

Verfügbare MCP-Ressourcen

Dieser Server stellt die folgenden MCP-Ressourcenvorlagen zum Erkunden der OpenAPI-Spezifikation bereit.

Grundlegendes zu mehrwertigen Parametern ( * )

Einige Ressourcenvorlagen enthalten Parameter, die mit einem Sternchen ( * ) enden, wie z. B. {method*} oder {name*} . Dies bedeutet, dass der Parameter mehrere durch Kommas getrennte Werte akzeptiert. Um beispielsweise Details sowohl für die GET als auch für die POST Methode eines Pfads anzufordern, verwenden Sie eine URI wie openapi://paths/users/get,post . Dadurch können Details für mehrere Elemente in einer einzigen Anfrage abgerufen werden.

Ressourcenvorlagen:

• openapi://{field}
  • Beschreibung: Greift auf die Felder der obersten Ebene des OpenAPI-Dokuments zu (z. B. info , servers , tags ) oder listet den Inhalt von paths oder components auf. Die jeweils verfügbaren Felder hängen von der geladenen Spezifikation ab.
  • Beispiel: openapi://info
  • Ausgabe: text/plain Liste für paths und components ; konfiguriertes Format (JSON/YAML/minimiertes JSON) für andere Felder.
  • Vervollständigungen: Bietet dynamische Vorschläge für {field} basierend auf den tatsächlichen Schlüsseln der obersten Ebene, die in der geladenen Spezifikation gefunden wurden.
• openapi://paths/{path}
  • Beschreibung: Listet die verfügbaren HTTP-Methoden (Operationen) für einen bestimmten API-Pfad auf.
  • Parameter: {path} – Die API-Pfadzeichenfolge. Muss URL-codiert sein (z. B. wird aus /users/{id}``users/{id} ).
  • Beispiel: openapi://paths/users/{id}
  • Ausgabe: text/plain Liste der Methoden.
  • Vervollständigungen: Bietet dynamische Vorschläge für {path} basierend auf den in der geladenen Spezifikation gefundenen Pfaden (URL-codiert).
• openapi://paths/{path}/{method*}
  • Beschreibung: Ruft die detaillierte Spezifikation für eine oder mehrere Operationen (HTTP-Methoden) auf einem bestimmten API-Pfad ab.
  • Parameter:
    • {path} – Die API-Pfadzeichenfolge. Muss URL-codiert sein .
    • {method*} – Eine oder mehrere HTTP-Methoden (z. B. get , post , get,post ). Groß-/Kleinschreibung wird nicht berücksichtigt.
  • Beispiel (Einzeln): openapi://paths/users/{id}/get
  • Beispiel (mehrere): openapi://paths/users/{id}/get,post
  • Ausgabe: Konfiguriertes Format (JSON/YAML/minimiertes JSON).
  • Vervollständigungen: Bietet dynamische Vorschläge für {path} . Bietet statische Vorschläge für {method*} (gängige HTTP-Verben wie GET, POST, PUT, DELETE usw.).
• openapi://components/{type}
  • Beschreibung: Listet die Namen aller definierten Komponenten eines bestimmten Typs auf (z. B. schemas , responses , parameters ). Die jeweils verfügbaren Typen hängen von der geladenen Spezifikation ab. Bietet außerdem eine kurze Beschreibung für jeden aufgelisteten Typ.
  • Beispiel: openapi://components/schemas
  • Ausgabe: text/plain Liste der Komponentennamen mit Beschreibungen.
  • Vervollständigungen: Bietet dynamische Vorschläge für {type} basierend auf den in der geladenen Spezifikation gefundenen Komponententypen.
• openapi://components/{type}/{name*}
  • Beschreibung: Ruft die detaillierte Spezifikation für eine oder mehrere benannte Komponenten eines bestimmten Typs ab.
  • Parameter:
    • {type} – Der Komponententyp.
    • {name*} – Ein oder mehrere Komponentennamen (z. B. User , Order , User,Order ). Groß-/Kleinschreibung wird beachtet.
  • Beispiel (Einzeln): openapi://components/schemas/User
  • Beispiel (mehrere): openapi://components/schemas/User,Order
  • Ausgabe: Konfiguriertes Format (JSON/YAML/minimiertes JSON).
  • Vervollständigungen: Bietet dynamische Vorschläge für {type} . Dynamische Vorschläge für {name*} werden nur dann bereitgestellt, wenn die geladene Spezifikation insgesamt genau einen Komponententyp enthält (z. B. nur schemas ). Diese Einschränkung besteht, weil das MCP SDK derzeit keine Vervollständigungen für den ausgewählten {type} unterstützt. Die Angabe aller Namen für alle Typen könnte irreführend sein.

Beitragen

Beiträge sind willkommen! Hinweise zum Einrichten der Entwicklungsumgebung, Ausführen von Tests und Einreichen von Änderungen finden Sie in der Datei CONTRIBUTING.md .

Veröffentlichungen

Dieses Projekt verwendet semantic-release für die automatisierte Versionsverwaltung und Paketveröffentlichung basierend auf konventionellen Commits .

Zukunftspläne

(Zukünftige Pläne müssen noch festgelegt werden)