MCP-Server

Der fiskaly-docs-MCP-Server gibt KI-Coding-Assistenten direkten Zugriff auf fiskaly-Dokumentation, OpenAPI-Spezifikationen, Produkt-Metadaten und Fehlercodes — ohne Web-Scraping oder manuelle Suche.

Er implementiert das Model Context Protocol (MCP) und stellt 9 Tools bereit, die jeder MCP-kompatible Client aufrufen kann.

Verfügbare Tools

Dokumentations-Tools

Dokumentationsseiten nach Schlüsselwort durchsuchen. Gibt passende Seitentitel, Pfade und relevante 500-Zeichen-Ausschnitte zurück.

Parameter:

query (erforderlich) — Suchbegriff (Teilstring-Abgleich auf Titel und Text)
product (optional) — nach Produktname filtern, z. B. SIGN DE, SIGN FR
country (optional) — nach Ländercode filtern, z. B. DE, FR, IT

Eine vollständige Dokumentationsseite anhand des Pfads lesen. Unterstützt teilweisen und Suffix-Abgleich. Gibt den vollständigen Seiteninhalt und verwandte Geschwisterseiten zurück.

Parameter:

path (erforderlich) — Seitenpfad oder Suffix, z. B. getting-started/quickstart, quickstart

Metadaten für ein fiskaly-Produkt abrufen: Beschreibung, Land, API-Architektur, Basis-URLs, Dokumentationslinks und verwandte Seiten.

Parameter:

product (erforderlich) — Produkt-ID (z. B. sign-de, sign-fr) oder Produktname (z. B. SIGN DE, DSFinV-K)

fiskaly-API-Fehlercodes mit HTTP-Status, Beschreibung und Lösungshinweisen abrufen. Optional nach Produkt filtern.

Parameter:

product (optional) — nach Produkt-ID filtern (z. B. sign-de, sign-fr). Weglassen, um alle Fehlercodes zu erhalten.

API-Explorations-Tools

Die OpenAPI-Spezifikation für ein fiskaly-Produkt abrufen. Verwenden Sie format="summary" für eine Übersicht der Endpunkte und Schema-Namen anstelle der vollständigen Spezifikation.

Parameter:

product (erforderlich) — Produkt-ID: sign-de, sign-at, sign-fr, sign-it, sign-es, dsfinvk, ereceipt, management, obono
format (optional) — full (Standard) oder summary (Info + Endpunktliste + Schema-Namen)

Alle API-Endpunkte für ein Produkt auflisten, gruppiert nach Tag. Zeigt Methode, Pfad, operationId und Zusammenfassung.

Parameter:

product (erforderlich) — Produkt-ID
tag (optional) — nach Tag-Name filtern (Groß-/Kleinschreibung-unempfindlicher Teilabgleich)

Detaillierte Informationen zu einem bestimmten Endpunkt abrufen: Parameter, Anfrage-Body, Antwort-Schemas und Sicherheit.

Parameter:

product (erforderlich) — Produkt-ID
path (optional) — API-Pfad für Abgleich (Teilabgleich)
method (optional) — HTTP-Methode (GET, POST, PUT usw.)
operationId (optional) — Operations-ID (Teil, Groß-/Kleinschreibung-unempfindlich)

Ein OpenAPI-Schema anhand des Namens mit $ref-Auflösung (2 Ebenen tief, zyklen-sicher) nachschlagen. Verwenden Sie list=true, um alle verfügbaren Schema-Namen anzuzeigen.

Parameter:

product (erforderlich) — Produkt-ID
schema (optional) — Schema-Name (Teilabgleich, Groß-/Kleinschreibung-unempfindlich)
list (optional) — auf true setzen, um alle Schema-Namen aufzulisten

Integrations-Tools

Einen schrittweisen Integrationsleitfaden für ein Produkt abrufen. Fasst Umgebungsinformationen, Authentifizierungsablauf, Quickstart-Schritte aus der Dokumentation, wichtige Endpunkte aus der Spezifikation und Dokumentationslinks zusammen.

Parameter:

product (erforderlich) — Produkt-ID oder -Name (z. B. sign-de, SIGN FR)

Einrichtung

💡Tip

Alle nachfolgenden Einrichtungsmethoden starten den Server über npx. Beim ersten Start lädt npx das Paket herunter, was häufig das Startup-Timeout Ihres MCP-Clients überschreitet und sich als einmaliger Fehler failed to connect / -32000 äußert. Wärmen Sie den Cache vor, indem Sie npx -y @fiskaly/docs-mcp einmal im Terminal ausführen (warten Sie, bis er startet, und drücken Sie dann Strg+C), und fügen Sie den Server anschließend zu Ihrem Client hinzu.

Wenn weiterhin ein Verbindungsfehler auftritt, siehe Fehlerbehebung. Stellen Sie sicher, dass Node.js installiert und im PATH Ihres Clients verfügbar ist — prüfen Sie dies mit node --version.

Claude Code

Fügen Sie den fiskaly-docs-MCP-Server zu Ihrem Projekt hinzu:

claude mcp add fiskaly-docs -- npx @fiskaly/docs-mcp

Oder fügen Sie ihn zur .mcp.json Ihres Projekts hinzu:

{
  "mcpServers": {
    "fiskaly-docs": {
      "command": "npx",
      "args": ["@fiskaly/docs-mcp"]
    }
  }
}

Cursor

Fügen Sie zur .cursor/mcp.json hinzu:

{
  "mcpServers": {
    "fiskaly-docs": {
      "command": "npx",
      "args": ["@fiskaly/docs-mcp"]
    }
  }
}

Windsurf

Fügen Sie zur ~/.codeium/windsurf/mcp_config.json hinzu:

{
  "mcpServers": {
    "fiskaly-docs": {
      "command": "npx",
      "args": ["@fiskaly/docs-mcp"]
    }
  }
}

VS Code (GitHub Copilot)

Fügen Sie zur .vscode/mcp.json Ihres Projekts hinzu:

{
  "servers": {
    "fiskaly-docs": {
      "command": "npx",
      "args": ["@fiskaly/docs-mcp"]
    }
  }
}

JetBrains-IDEs

Gehen Sie zu Einstellungen > Tools > KI-Assistent > Model Context Protocol und fügen Sie einen neuen Server hinzu mit:

Befehl: npx
Argumente: @fiskaly/docs-mcp

Generische MCP-Clients

Der Server kommuniziert über stdio mittels des MCP-Protokolls. Starten Sie ihn mit:

npx @fiskaly/docs-mcp

Er benötigt Node.js 24+.

Verwendungsbeispiele

Vollständige Dokumentationsseite lesen

Tool: get_doc_page
Input: { "path": "getting-started/quickstart" }

Gibt den vollständigen Seiteninhalt mit Links zu Geschwisterseiten zurück — ideal zum vollständigen Durchlesen von Integrationsleitfäden.

API-Endpunkte erkunden

Tool: list_endpoints
Input: { "product": "sign-de", "tag": "Transaction" }

Gibt alle transaktionsbezogenen Endpunkte gruppiert nach Tag zurück, mit Methode, Pfad, operationId und Zusammenfassung.

Spezifischen Endpunkt nachschlagen

Tool: get_endpoint
Input: { "product": "sign-de", "operationId": "upsertTransaction" }

Gibt fokussierte Details zurück: Parameter, Anfrage-Body-Schema (aufgelöst), Antwort-Schemas und Sicherheitsanforderungen.

Integrationsleitfaden abrufen

Tool: get_integration_guide
Input: { "product": "sign-fr" }

Gibt einen zusammengesetzten Leitfaden mit Umgebungs-URLs, Authentifizierungsablauf, Quickstart-Inhalten, wichtigen Endpunkten aus der Spezifikation und Links zu relevanten Dokumentationsseiten zurück.

Schema auflösen

Tool: resolve_schema
Input: { "product": "sign-de", "schema": "Transaction" }

Gibt das aufgelöste Schema mit $ref 2 Ebenen tief ausgeklappt zurück. Verwenden Sie zuerst list=true, um alle verfügbaren Schema-Namen anzuzeigen.

Spec-Zusammenfassung abrufen

Tool: get_openapi_spec
Input: { "product": "sign-de", "format": "summary" }

Gibt API-Info, eine Liste aller Endpunkte und Schema-Namen zurück — ohne die vollständige 5000+ Zeilen-Spezifikation.

Dokumentation durchsuchen

Tool: search_docs
Input: { "query": "transaction", "product": "SIGN DE" }

Gibt passende Seiten mit Titeln, Pfaden und 500-Zeichen-Inhaltsausschnitten zurück, die für SIGN DE-Transaktionen relevant sind.

Produkt-Metadaten nachschlagen

Tool: get_product_info
Input: { "product": "sign-de" }

Gibt strukturierte Metadaten zurück:

Produktname, Beschreibung und Land
API-Architektur (spezialisiert oder unified)
Basis-URLs für TEST- und LIVE-Umgebungen
Spec-URL, Dokumentations-URL und verwandte Seiten

Fehlercodes nachschlagen

Tool: get_error_codes
Input: { "product": "sign-de" }

Gibt alle Fehlercodes für SIGN DE mit HTTP-Statuscodes, Beschreibungen und Lösungshinweisen zurück.

Fehlerbehebung

failed to connect to MCP server / Fehlercode -32000? Dieser JSON-RPC-Fehler bedeutet, dass Ihr MCP-Client den Server nicht starten oder den Handshake über stdio nicht abschließen konnte. Nach Wahrscheinlichkeit geordnet:

npx-Kaltstart-Timeout (am häufigsten). Beim ersten Start lädt npx @fiskaly/docs-mcp herunter, was oft länger dauert als das Startup-Timeout Ihres Clients. Führen Sie npx -y @fiskaly/docs-mcp einmal im Terminal aus, um den Cache vorzuwärmen, und starten Sie dann Ihren Client neu.
npx oder node in der Client-Umgebung nicht gefunden. MCP-Clients starten häufig mit einem minimalen PATH, der Ihre Node-Installation nicht enthält (häufig bei nvm, fnm oder Homebrew). Wenn which npx im Terminal funktioniert, der Server aber dennoch nicht startet, verweisen Sie den Client auf einen absoluten Pfad — setzen Sie command auf den vollständigen Pfad aus which node und übergeben Sie das Paket als Argument, oder verwenden Sie den absoluten Pfad zu npx.
Veralteter oder beschädigter npx-Cache. Wenn der Server zuvor funktioniert hat und plötzlich fehlschlägt, leeren Sie den Cache und lassen Sie ihn neu herunterladen: rm -rf "$(npm config get cache)/_npx", und starten Sie dann Ihren Client neu.

Stellen Sie sicher, dass Node.js installiert und im PATH verfügbar ist, den Ihr Client verwendet. Führen Sie node --version zur Überprüfung aus — und beachten Sie, dass einige Clients eine andere Shell oder ein anderes Node als Ihr Terminal verwenden; überprüfen Sie daher die Umgebung, die Ihr Client tatsächlich startet.

Keine Ergebnisse von search_docs? Versuchen Sie einen breiteren Suchbegriff. Die Suche verwendet Teilstring-Abgleich auf Titeln und Texten — kürzere Schlüsselwörter liefern mehr Ergebnisse.

get_openapi_spec gibt einen Fehler zurück? Nicht alle Produkte haben eine OpenAPI-Spezifikation. Verwenden Sie get_product_info, um zu prüfen, ob ein Produkt eine specFile hat.

Alternative: HTTP-Endpunkte

Wenn Sie HTTP gegenüber MCP bevorzugen, sind dieselben Daten als maschinenlesbare Endpunkte verfügbar:

Dokumentation durchsuchen — /llms-full.txt abrufen und durchsuchen
OpenAPI-Specs — /specs/{product}.json oder .yaml direkt abrufen
Produktinformationen — /products.json abrufen
Fehlercodes — get_error_codes über MCP verwenden oder die Fehlercodes-Referenz prüfen

Was this page helpful?