Swagger MCP

Ein MCP-Server, der eine Verbindung zu einer Swagger-Spezifikation herstellt und einer KI hilft, alle erforderlichen Modelle zu erstellen, um einen MCP-Server für diesen Dienst zu generieren.

Merkmale

• Lädt eine Swagger-Spezifikation herunter und speichert sie lokal, damit Sie schneller darauf zugreifen können.

• Gibt eine Liste aller Endpunkte und ihrer HTTP-Methoden und Beschreibungen zurück

• Gibt eine Liste aller Modelle zurück

• Gibt ein Modell zurück

• Gibt den Dienst zurück, um eine Verbindung zum Endpunkt herzustellen

• Gibt MCP-Funktionsdefinitionen zurück

• Generiert vollständige MCP-Tooldefinitionen mit vollständigen Schemainformationen

• Enthält KI-spezifische Anweisungen in den Werkzeugbeschreibungen

Related MCP server: Mcp-Swagger-Server

Voraussetzungen

• Node.js (v14 oder höher)

• npm oder yarn

Installation

1. Klonen Sie das Repository:

git clone https://github.com/readingdancer/swagger-mcp.git
cd swagger-mcp

2. Installieren Sie Abhängigkeiten:

npm install

3. Erstellen Sie eine .env Datei basierend auf der .env.example -Datei:

cp .env.example .env

4. Aktualisieren Sie die .env Datei.

Konfiguration

Bearbeiten Sie die .env Datei, um die Anwendung zu konfigurieren:

• PORT : Der Port, auf dem der Server läuft (Standard: 3000)

• NODE_ENV : Die Umgebung (Entwicklung, Produktion, Test)

• LOG_LEVEL : Protokollierungsebene (Info, Fehler, Debug)

Verwendung

Erstellen der Anwendung

Erstellen Sie die Anwendung:

npm run build

Dadurch wird der TypeScript-Code kompiliert und ist bereit, als MCP-Server verwendet zu werden

Wird als MCP-Server ausgeführt

So führen Sie es als MCP-Server zur Integration mit Cursor und anderen Anwendungen aus:

node build/index.js

Verwenden des MCP-Inspektors

So führen Sie den MCP-Inspector zum Debuggen aus:

npm run inspector

Zum Cursor hinzufügen

So fügen Sie diesen MCP-Server zu Cursor hinzu:

1. Öffnen Sie Cursoreinstellungen > Funktionen > MCP

2. Klicken Sie auf „+ Neuen MCP-Server hinzufügen“

3. Geben Sie einen Namen für den Server ein (z. B. „Swagger MCP“)

4. Wählen Sie „stdio“ als Transporttyp

5. Geben Sie den Befehl zum Ausführen des Servers ein: node path/to/swagger-mcp/build/index.js und fügen Sie dann bei Bedarf die Befehlszeilenargumente wie oben erwähnt hinzu.

6. Klicken Sie auf „Hinzufügen“

Die Swagger MCP-Tools stehen jetzt dem Cursor-Agenten in Composer zur Verfügung.

Verfügbare Swagger MCP-Tools

Die folgenden Tools sind über den MCP-Server verfügbar:

• getSwaggerDefinition : Lädt eine Swagger-Definition von einer URL herunter

• listEndpoints : Listet alle Endpunkte aus der Swagger-Definition auf

• listEndpointModels : Listet alle Modelle auf, die von einem bestimmten Endpunkt verwendet werden

• generateModelCode : Generiert TypeScript-Code für ein Modell

• generateEndpointToolCode : Generiert TypeScript-Code für eine MCP-Tooldefinition

Verfügbare Swagger MCP-Eingabeaufforderungen

Der Server bietet außerdem MCP-Eingabeaufforderungen, die KI-Assistenten durch gängige Arbeitsabläufe führen:

• add-endpoint : Eine Schritt-für-Schritt-Anleitung zum Hinzufügen eines neuen Endpunkts mit den Swagger MCP-Tools

Um eine Eingabeaufforderung zu verwenden, können Clients eine prompts/get -Anforderung mit dem Namen der Eingabeaufforderung und optionalen Argumenten stellen:

{
  "method": "prompts/get",
  "params": {
    "name": "add-endpoint",
    "arguments": {
      "swaggerUrl": "https://petstore.swagger.io/v2/swagger.json",
      "endpointPath": "/pets/{id}",
      "httpMethod": "GET"
    }
  }
}

Die Eingabeaufforderung gibt eine Reihe von Nachrichten zurück, die den KI-Assistenten durch den genauen Prozess führen, der zum Hinzufügen eines neuen Endpunkts erforderlich ist.

Einrichten Ihres neuen Projekts

Bitten Sie den Agenten zunächst, die Swagger-Datei abzurufen. Geben Sie ihm unbedingt die URL für die Swagger-Datei oder zumindest eine Möglichkeit, diese für Sie zu finden. Dadurch wird die Datei heruntergeladen und lokal unter einem gehashten Dateinamen gespeichert. Dieser Dateiname wird automatisch zu einer .swagger-mcp Einstellungsdatei im Stammverzeichnis Ihrer aktuellen Lösung hinzugefügt.

Automatisch generierte .swagger-mcp-Konfigurationsdatei

SWAGGER_FILENAME = TheFilenameOfTheLocallyStoredSwaggerFile

Diese einfache Konfigurationsdatei verknüpft Ihr aktuelles Projekt mit einer bestimmten Swagger-API. Wir können sie in Zukunft verwenden, um weitere Details zu speichern.

Nach der Konfiguration kann das MCP Ihre Swagger-Definition finden und sie mit Ihrer aktuellen Lösung verknüpfen. Dadurch wird die Anzahl der API-Aufrufe reduziert, die erforderlich sind, um das Projekt und die Aufgaben abzurufen, die mit der Lösung zusammenhängen, an der Sie arbeiten.

Verbesserter MCP-Tool-Codegenerator

Der MCP-Toolcodegenerator wurde erweitert, um vollständigere und benutzerfreundlichere Tooldefinitionen bereitzustellen:

Wichtige Verbesserungen

1. Vollständige Schemainformationen : Der Generator enthält jetzt vollständige Schemainformationen für alle Modelle, einschließlich verschachtelter Objekte, direkt im Eingabeschema.

2. Bessere Parameterbenennung : Parameternamen sind jetzt semantischer und vermeiden problematische Zeichen wie Punkte (z. B. taskRequest statt task.Request ).

3. Semantische Toolnamen : Toolnamen sind jetzt aussagekräftiger und folgen konsistenten Namenskonventionen basierend auf der HTTP-Methode und dem Ressourcenpfad.

4. Unterstützung für YAML-Swagger-Dateien : Der Generator unterstützt jetzt sowohl JSON- als auch YAML-Swagger-Definitionsdateien.

5. Verbesserte Dokumentation : Generierte Werkzeugdefinitionen enthalten umfassende Beschreibungen aller Parameter und Eigenschaften.

6. Keine externen Abhängigkeiten : Der generierte Code erfordert keinen Import externer Modelldateien, wodurch er eigenständiger und einfacher zu verwenden ist.

7. KI-spezifische Anweisungen : Die Toolbeschreibungen enthalten jetzt spezielle Anweisungen für KI-Agenten, die ihnen helfen zu verstehen, wie sie die Tools effektiv nutzen können.

Beispielverwendung

So generieren Sie eine MCP-Tooldefinition für einen Endpunkt:

import generateEndpointToolCode from './services/generateEndpointToolCode.js';

const toolCode = await generateEndpointToolCode({
  path: '/pets',
  method: 'POST',
  swaggerFilePath: './petstore.json',
  singularizeResourceNames: true
});

console.log(toolCode);

Dadurch wird eine vollständige MCP-Tooldefinition mit vollständigen Schemainformationen für den POST /pets-Endpunkt generiert.

Lizenz

Dieses Projekt ist unter der MIT-Lizenz lizenziert – Einzelheiten finden Sie in der Datei LICENSE .

MCP-Eingabeaufforderungen für KI-Assistenten

Damit KI-Assistenten die Swagger MCP-Tools effektiv nutzen können, haben wir eine Reihe von Eingabeaufforderungen erstellt, die sie durch häufige Aufgaben führen. Diese Eingabeaufforderungen bieten Schritt-für-Schritt-Anleitungen für Prozesse wie das Hinzufügen neuer Endpunkte, die Verwendung generierter Modelle und mehr.

Die vollständige Sammlung der Eingabeaufforderungen finden Sie in der Datei PROMPTS.md .

Beispiel-Anwendungsfall: Wenn Sie einen KI-Assistenten bitten, Ihrem Projekt einen neuen Endpunkt hinzuzufügen, können Sie auf die Eingabeaufforderung „Hinzufügen eines neuen Endpunkts“ verweisen, um sicherzustellen, dass der Assistent den richtigen Prozess in der richtigen Reihenfolge befolgt.