apifable

Lies die Spezifikation. Verstehe die API. Integriere mit Zuversicht.

Englisch | 繁體中文

Überblick

apifable ist ein MCP-Server, der KI dabei hilft, APIs reibungsloser in TypeScript-Frontend-Projekte zu integrieren. Er macht es einfach, die API-Struktur zu erkunden, Endpunkte zu durchsuchen und TypeScript-Typen zu generieren, wodurch dein KI-Agent den Kontext erhält, den er für das Schreiben präziser Integrationscodes benötigt.

Related MCP server: openapi-mcp-proxy

✨ Funktionen

• 📦 KI-bereiter API-Kontext — gib der KI die Struktur, die sie benötigt, um deine API zu verstehen und damit zu arbeiten

• 📘 OpenAPI 3.0 / 3.1 Unterstützung — funktioniert mit Standard-Spezifikationen als verlässliche Quelle der Wahrheit

• 🤖 MCP-Server für KI-Agenten — verbinde dich mit Claude, Cursor und Windsurf

• 🔍 API-Erkundungstools — durchsuche Endpunkte, suche nach Schlüsselwörtern und untersuche vollständige Request/Response-Details

• 🏷️ TypeScript-Typgenerierung — generiere TypeScript-Typdefinitionen, die direkt im Frontend-Code verwendet werden können

Erste Schritte

Installation

Führe apifable init aus, um deine Projektkonfiguration einzurichten:

npx apifable@latest init

Dies erstellt eine apifable.config.json in deinem Projektstammverzeichnis. Die Konfigurationsdatei sollte in die Versionsverwaltung aufgenommen werden, damit der Pfad zur Spezifikation mit deinem Team geteilt wird.

Nachdem der Befehl gestartet wurde, kannst du zwischen Manuelle Datei und Remote-URL wählen.

1. Manuelle Datei

Verwende diesen Modus, wenn deine OpenAPI-Spezifikation bereits im Projekt vorhanden ist oder wenn du Spezifikationsaktualisierungen selbst verwalten möchtest.

init fragt nach dem lokalen Dateipfad, wie z. B. openapi.yaml.

Du musst deine OpenAPI-Spezifikation dann manuell an diesem Pfad ablegen. Wenn sich die Backend-API ändert, musst du diese Datei ebenfalls manuell aktualisieren.

2. Remote-URL

Verwende diesen Modus, wenn deine OpenAPI-Spezifikation über eine stabile Remote-URL verfügbar ist, wie z. B. der OpenAPI-Spezifikations-Endpunkt, der von deiner Backend-API-Dokumentation bereitgestellt wird.

init fragt zuerst nach der Remote-URL, wie z. B. https://api.example.com/openapi.yaml, und dann nach dem lokalen Ausgabepfad, wie z. B. ./openapi.yaml.

[!NOTE] In diesem Modus fügt init den heruntergeladenen lokalen Spezifikationspfad automatisch zu .gitignore hinzu, da die Datei dazu gedacht ist, von der Remote-Quelle aktualisiert zu werden.

Du kannst dann den folgenden Befehl ausführen, um die OpenAPI-Spezifikation von der Remote-URL auf deinen lokalen Pfad herunterzuladen (spec.url → spec.path). Wann immer sich die Spezifikation ändert, führe ihn einfach erneut aus, um sie zu aktualisieren:

npx apifable@latest fetch

Header

Für nicht sensible Header, die mit deinem Team geteilt werden können, füge spec.headers zur apifable.config.json hinzu:

{
  "spec": {
    "path": "openapi.yaml",
    "url": "https://example.com/openapi.yaml",
    "headers": {
      "X-Api-Version": "2"
    }
  }
}

Auth-Header (Geheime Token)

Wenn das Herunterladen der Remote-OpenAPI-Spezifikation eine Authentifizierung erfordert (private API), speichere geheime Header in .apifable/auth.json. Diese Datei sollte nicht in die Versionsverwaltung aufgenommen werden:

{
  "headers": {
    "Authorization": "Bearer YOUR_SECRET_TOKEN"
  }
}

Sowohl apifable.config.json als auch .apifable/auth.json unterstützen die ${ENV_VAR}-Syntax in Header-Werten.

{
  "headers": {
    "Authorization": "Bearer ${MY_API_KEY}"
  }
}

Header-Priorität (höchste bis niedrigste)

1. .apifable/auth.json Header (überschreibt gleichnamige Schlüssel)

2. apifable.config.json spec.headers

Claude Code

Füge Folgendes zu deiner .mcp.json hinzu:

{
  "mcpServers": {
    "apifable": {
      "command": "npx",
      "args": ["-y", "apifable@latest", "mcp"]
    }
  }
}

Für andere KI-Agenten wie Cursor und Windsurf kannst du denselben Ansatz verfolgen, um apifable als MCP-Server zu konfigurieren.

Verwendung

Hier sind einige Beispiel-Prompts, die du verwenden kannst, um APIs zu erkunden und Funktionen zu erstellen.

Die API erkunden

List all APIs

Show me APIs related to posts

List APIs under the Post tag

Show me the API details for post comments

Show me the API details for GET /posts/{id}/comments

Show me the API details for postComments

Eine Funktion erstellen

Implement the post comments feature

Post page: src/pages/posts/[id].tsx

Related APIs:
- GET /posts/{id}/comments (list post comments)
- POST /posts/{id}/comments (create a post comment)

[!TIP] Wenn du einen Prompt zum Erstellen einer Funktion schreibst, füge relevanten Kontext hinzu: Seitenpfade, Komponentenorte, zugehörige APIs sowie alle Muster oder Beispiele, denen gefolgt werden soll.

Anleitung für KI-Agenten

Füge Folgendes zur AGENTS.md deines Projekts hinzu, um KI-Agenten dabei zu helfen, apifable effektiver zu nutzen:

## API Integration (apifable)

- Always use `get_endpoint` to verify the exact path, method, and parameters before writing integration code. Never assume.
- When presenting endpoint list data from apifable tools, display exactly these columns in order: `Method` (Uppercase), `Path`, `Summary`. Keep all values verbatim, including summary prefixes like `[ 32 - 001 ]`. Do not omit, rename, paraphrase, or add extra columns.
- When saving generated types, store them under `src/types/` and name files by domain (e.g., `src/types/auth.ts`, `src/types/user.ts`), not by OpenAPI tag names.

Das Obige ist ein empfohlener Ausgangspunkt. Fühle dich frei, die Spalten der Endpunktliste und den Pfad zum Typen-Ordner an dein Projekt anzupassen.

MCP-Tools-Referenz

get_spec_info

Gibt den API-Titel, die Version, die Beschreibung, die Server und alle Tags mit ihren Endpunkt-Anzahlen zurück. Beginne hier, um die Form einer unbekannten Spezifikation zu verstehen.

list_endpoints_by_tag

Eingaben:

• tag (string): Der Tag-Name zum Filtern

• limit (number, optional): Maximale Anzahl der zurückzugebenden Endpunkte

• offset (number, optional): Anzahl der zu überspringenden Endpunkte (Standard: 0)

Gibt alle Endpunkte zurück, die zum angegebenen Tag gehören. Die Antwort enthält total, offset und hasMore-Felder für die Paginierung. Enthält eine Warnung, wenn die Ergebnisse 30 Elemente überschreiten und kein limit angegeben ist.

search_endpoints

Eingaben:

• query (string): Schlüsselwort für die Suche

• tag (string, optional): Suche auf einen bestimmten Tag beschränken

• limit (number, optional): Maximale Anzahl der zurückzugebenden Ergebnisse (Standard: 10)

Schlüsselwortsuche über operationId, Pfad, Zusammenfassung und Beschreibung. Die Ergebnisse werden nach Relevanz sortiert. Wenn keine exakten Übereinstimmungen gefunden werden, wird automatisch auf eine Fuzzy-Suche zurückgegriffen. Die Antwort enthält ein matchType-Feld ("exact" oder "fuzzy"); Fuzzy-Ergebnisse enthalten zusätzlich ein score-Feld pro Ergebnis.

get_endpoint

Eingaben (wähle eine):

• method (string) + path (string): HTTP-Methode und Endpunktpfad (z. B. get + /users/{id})

• operationId (string): Operations-ID (z. B. listUsers)

Gibt das vollständige Endpunkt-Objekt zurück, einschließlich Parametern, requestBody und Antworten, wobei unterstützte interne Komponenten-$refs inline aufgelöst werden.

search_schemas

Eingaben:

• query (string): Schlüsselwort für die Suche

• limit (number, optional): Maximale Anzahl der zurückzugebenden Ergebnisse (Standard: 10)

Schlüsselwortsuche über Schemaname und Beschreibung. Die Ergebnisse werden nach Relevanz sortiert. Wenn keine exakten Übereinstimmungen gefunden werden, wird automatisch auf eine Fuzzy-Suche zurückgegriffen. Die Antwort enthält ein matchType-Feld ("exact" oder "fuzzy"); Fuzzy-Ergebnisse enthalten zusätzlich ein score-Feld pro Ergebnis. Leere Ergebnisse können auch ein message-Feld mit Anleitungen für den nächsten Schritt enthalten.

get_schema

Eingaben:

• name (string): Schemaname aus components/schemas

Gibt das vollständige Schema mit aufgelösten unterstützten internen Komponenten-$refs zurück.

get_types

Eingaben (wähle einen Modus):

• schemas (string[]): Array von Schemanamen aus components/schemas

• method (string) + path (string): HTTP-Methode und Endpunktpfad

• operationId (string): Operations-ID (z. B. listUsers)

Generiert in sich geschlossene TypeScript-Deklarationen als Codetext. Im Endpunkt-Modus folgt es unterstützten internen Komponenten-$refs, bevor Schema-Abhängigkeiten gesammelt werden. Es enthält automatisch transitive Abhängigkeiten und keine Import-Anweisungen.

Modus-Regeln:

• Verwende genau einen Modus pro Aufruf: schemas, method + path oder operationId

• Mische keine Modi im selben Aufruf

Einschränkungen

• Externe $refs (z. B. Verweise auf andere Dateien oder URLs) werden nicht unterstützt.

• OpenAPI 2.0 (Swagger) wird nicht unterstützt. Nur OpenAPI 3.0 und 3.1 Spezifikationen werden unterstützt.

Sponsor

Wenn du denkst, dass dieses Paket dir geholfen hat, ziehe bitte in Betracht, Sponsor zu werden, um meine Arbeit zu unterstützen~ und dein Avatar wird auf meinen Hauptprojekten sichtbar sein.

Credits

• @reapi/mcp-openapi — für die anfängliche Inspiration

Lizenz

MIT LIZENZ

Star History