fiskaly Docs MCP Server (Community)

Ein eigenständiger, funktionsgleicher Nachbau des fiskaly Docs MCP Servers. Stellt KI-Coding-Assistenten (Claude Code, Cursor, Windsurf, VS Code, JetBrains …) Zugriff auf die fiskaly-Dokumentation, OpenAPI-Specs, Produkt-Metadaten und Fehlercodes bereit — über das Model Context Protocol via stdio.

Die Inhalte werden live von https://workspace.fiskaly.com geladen und im Speicher mit TTL gecacht. Dadurch ist der Server immer aktuell, ohne veraltende, gebündelte Daten.

Schnellstart

npx -y fiskaly-docs-mcp-community

Kein Klonen, kein Build — npx lädt das Paket und startet den stdio-Server.

Claude Code

claude mcp add fiskaly-docs -- npx -y fiskaly-docs-mcp-community

Cursor / Windsurf / VS Code / JetBrains

In der jeweiligen MCP-Konfiguration (z. B. .cursor/mcp.json):

{
  "mcpServers": {
    "fiskaly-docs": {
      "command": "npx",
      "args": ["-y", "fiskaly-docs-mcp-community"]
    }
  }
}

Funktionen (9 Tools)

| Tool | Beschreibung | Parameter | |------|--------------|-----------| | search_docs | Doku per Stichwort durchsuchen, optional nach Produkt/Land gefiltert | query (Pflicht), product, country, limit | | get_doc_page | Vollständige Doku-Seite per Pfad (Suffix-/Teilmatch) + Geschwisterseiten | path (Pflicht) | | get_product_info | Produkt-Metadaten (Beschreibung, Land, Architektur, Base-URLs, Links) | product (optional → sonst alle) | | get_error_codes | HTTP-Statuscodes, Standard-Fehlerschema + produktspezifische Fehlercodes | product (optional) | | get_openapi_spec | OpenAPI-Spec als summary (Endpoint-/Schema-Liste) oder full | product (Pflicht), format | | list_endpoints | Alle Endpoints nach Tag gruppiert | product (Pflicht), tag | | get_endpoint | Endpoint-Details (Parameter, Body, Responses, Security) | product (Pflicht), path/method/operationId | | resolve_schema | OpenAPI-Schema mit $ref-Expansion (2 Ebenen, zyklensicher) | product (Pflicht), schema, list | | get_integration_guide | Schritt-für-Schritt-Integrationsleitfaden | product (Pflicht) |

Unterstützt sowohl OpenAPI 3.x als auch Swagger 2.0 Specs.

Produkte

sign-de, sign-at, sign-fr, sign-it, sign-es, sign-se, dsfinvk, ereceipt, management, submit-de, e-invoice-be, e-invoice-de, e-invoice-it, obono, safe, hub, platform, e-invoice.

Nicht alle Produkte besitzen eine OpenAPI-Spec — get_openapi_spec meldet die verfügbaren Spec-Produkte, wenn keine existiert.

Konfiguration (Umgebungsvariablen, optional)

| Variable | Default | Zweck | |----------|---------|-------| | FISKALY_DOCS_HOST | https://workspace.fiskaly.com | Quell-Host der Dokumentation | | FISKALY_DOCS_CACHE_TTL | 3600000 (1h) | Cache-Lebensdauer in ms | | FISKALY_DOCS_FETCH_TIMEOUT | 30000 | Netzwerk-Timeout pro Request in ms |

Beispiel (Claude Code mit eigener Cache-TTL):

{
  "mcpServers": {
    "fiskaly-docs": {
      "command": "npx",
      "args": ["-y", "fiskaly-docs-mcp-community"],
      "env": { "FISKALY_DOCS_CACHE_TTL": "600000" }
    }
  }
}

Entwicklung

git clone https://github.com/PlaxXOnline/fiskaly_mcp.git
cd fiskaly_mcp
npm install          # installiert Deps und baut via prepare-Hook
npm run build        # erneut bauen nach Änderungen
npm run inspect      # MCP Inspector (interaktive UI)

Hinweis: Im Quell-Repo selbst den Server über node dist/index.js einbinden, nicht über npx fiskaly-docs-mcp-community — npx würde den Paketnamen sonst gegen die lokale package.json auflösen.

claude mcp add fiskaly-docs -- node "$(pwd)/dist/index.js"

Architektur

src/
  index.ts     # Server-Bootstrap (stdio), Tool-Registrierung
  tools.ts     # Definition + Handler der 9 Tools
  fiskaly.ts   # Datenlayer: Fetch + Cache (products.json, llms-full.txt, Specs)
  search.ts    # Volltext-Suche über Doku-Seiten + Produkt-/Land-Mapping
  openapi.ts   # Endpoint-Extraktion, Spec-Summary, $ref-Auflösung (3.x + 2.0)
  errors.ts    # Universelle Statuscodes + produktspezifische Fehlercode-Extraktion

Lizenz & Hinweis

MIT. Dieses Projekt ist ein inoffizielles, community-gepflegtes Tool und steht in keiner Verbindung zu fiskaly. „fiskaly" ist eine Marke der fiskaly GmbH.