Server MCP

Il server MCP fiskaly-docs fornisce agli assistenti di codificazione IA accesso diretto alla documentazione di fiskaly, alle specifiche OpenAPI, ai metadati dei prodotti e ai codici di errore — senza web scraping o ricerche manuali.

Implementa il Model Context Protocol (MCP) e espone 9 strumenti che qualsiasi client compatibile con MCP può chiamare.

Strumenti disponibili

Strumenti di documentazione

Cercare pagine di documentazione per parola chiave. Restituisce titoli di pagine corrispondenti, percorsi e frammenti rilevanti di 500 caratteri.

Parametri:

query (obbligatorio) — parola chiave di ricerca (corrispondenza di sottostringa su titolo e corpo)
product (facoltativo) — filtrare per nome prodotto, ad es. SIGN DE, SIGN FR
country (facoltativo) — filtrare per codice paese, ad es. DE, FR, IT

Leggere una pagina di documentazione completa per percorso. Supporta corrispondenza parziale e di suffisso. Restituisce il corpo completo della pagina e le pagine sorelle correlate.

Parametri:

path (obbligatorio) — percorso della pagina o suffisso, ad es. getting-started/quickstart, quickstart

Ottenere metadati per un prodotto fiskaly: descrizione, paese, architettura API, URL base, link alla documentazione e pagine correlate.

Parametri:

product (obbligatorio) — ID del prodotto (ad es. sign-de, sign-fr) o nome del prodotto (ad es. SIGN DE, DSFinV-K)

Ottenere i codici di errore dell’API fiskaly con stato HTTP, descrizione e indicazioni per la risoluzione. Filtrare facoltativamente per prodotto.

Parametri:

product (facoltativo) — filtrare per ID prodotto (ad es. sign-de, sign-fr). Omettere per ottenere tutti i codici di errore.

Strumenti di esplorazione API

Ottenere la specifica OpenAPI per un prodotto fiskaly. Usare format="summary" per una panoramica degli endpoint e dei nomi degli schemi invece della specifica completa.

Parametri:

product (obbligatorio) — ID del prodotto: sign-de, sign-at, sign-fr, sign-it, sign-es, dsfinvk, ereceipt, management, obono
format (facoltativo) — full (predefinito) o summary (info + elenco endpoint + nomi schemi)

Elencare tutti gli endpoint API per un prodotto, raggruppati per tag. Mostra metodo, percorso, operationId e riepilogo.

Parametri:

product (obbligatorio) — ID del prodotto
tag (facoltativo) — filtrare per nome tag (corrispondenza parziale senza distinzione maiuscole/minuscole)

Ottenere informazioni dettagliate su un endpoint specifico: parametri, corpo della richiesta, schemi di risposta e sicurezza.

Parametri:

product (obbligatorio) — ID del prodotto
path (facoltativo) — percorso API da corrispondere (corrispondenza parziale)
method (facoltativo) — metodo HTTP (GET, POST, PUT, ecc.)
operationId (facoltativo) — ID operazione (parziale, senza distinzione maiuscole/minuscole)

Cercare uno schema OpenAPI per nome con espansione di $ref (2 livelli di profondità, sicuro contro i cicli). Usare list=true per vedere tutti i nomi degli schemi disponibili.

Parametri:

product (obbligatorio) — ID del prodotto
schema (facoltativo) — nome dello schema (corrispondenza parziale, senza distinzione maiuscole/minuscole)
list (facoltativo) — impostare su true per elencare tutti i nomi degli schemi

Strumenti di integrazione

Ottenere una guida di integrazione passo per passo per un prodotto. Compone informazioni sull’ambiente, flusso di autenticazione, passaggi di avvio rapido dalla documentazione, endpoint chiave dalla specifica e link alla documentazione.

Parametri:

product (obbligatorio) — ID o nome del prodotto (ad es. sign-de, SIGN FR)

Configurazione

💡Tip

Tutti i metodi di configurazione riportati di seguito avviano il server tramite npx. Al primo avvio, npx scarica il pacchetto, operazione che spesso supera il timeout di avvio del client MCP e si manifesta come un errore occasionale failed to connect / -32000. Preriscaldare la cache eseguendo npx -y @fiskaly/docs-mcp una volta nel terminale (attendere l’avvio, quindi premere Ctrl+C), quindi aggiungere il server al proprio client.

Se l’errore di connessione persiste, vedere Risoluzione dei problemi. Assicurarsi che Node.js sia installato e presente nel PATH utilizzato dal client — verificare con node --version.

Claude Code

Aggiungere il server MCP fiskaly-docs al proprio progetto:

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

Oppure aggiungerlo al file .mcp.json del progetto:

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

Cursor

Aggiungere al file .cursor/mcp.json:

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

Windsurf

Aggiungere a ~/.codeium/windsurf/mcp_config.json:

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

VS Code (GitHub Copilot)

Aggiungere al file .vscode/mcp.json del progetto:

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

IDE JetBrains

Andare a Impostazioni > Strumenti > Assistente IA > Model Context Protocol e aggiungere un nuovo server con:

Comando: npx
Argomenti: @fiskaly/docs-mcp

Client MCP generici

Il server comunica tramite stdio usando il protocollo MCP. Avviarlo con:

npx @fiskaly/docs-mcp

Richiede Node.js 24+.

Esempi di utilizzo

Leggere una pagina di documentazione completa

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

Restituisce il corpo completo della pagina con link alle pagine sorelle — ideale per leggere le guide di integrazione dall’inizio alla fine.

Esplorare gli endpoint API

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

Restituisce tutti gli endpoint relativi alle transazioni raggruppati per tag, con metodo, percorso, operationId e riepilogo.

Cercare un endpoint specifico

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

Restituisce dettagli mirati: parametri, schema del corpo della richiesta (risolto), schemi di risposta e requisiti di sicurezza.

Ottenere una guida di integrazione

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

Restituisce una guida composta con URL degli ambienti, flusso di autenticazione, contenuto di avvio rapido, endpoint chiave dalla specifica e link alle pagine di documentazione rilevanti.

Risolvere uno schema

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

Restituisce lo schema risolto con $ref espanso 2 livelli di profondità. Usare prima list=true per vedere tutti i nomi degli schemi disponibili.

Ottenere un riepilogo della specifica

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

Restituisce le informazioni sull’API, un elenco di tutti gli endpoint e i nomi degli schemi — senza la specifica completa di oltre 5000 righe.

Cercare nella documentazione

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

Restituisce pagine corrispondenti con titoli, percorsi e frammenti di contenuto di 500 caratteri rilevanti per le transazioni SIGN DE.

Consultare i metadati del prodotto

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

Restituisce metadati strutturati:

Nome, descrizione e paese del prodotto
Architettura API (specializzata o unificata)
URL base per ambienti TEST e LIVE
URL specifica, URL documentazione e pagine correlate

Consultare i codici di errore

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

Restituisce tutti i codici di errore per SIGN DE con codici di stato HTTP, descrizioni e indicazioni per la risoluzione.

Risoluzione dei problemi

failed to connect to MCP server / codice di errore -32000? Questo errore JSON-RPC indica che il client MCP non è riuscito ad avviare il server o a completare l’handshake tramite stdio. In ordine di probabilità:

Timeout di avvio a freddo di npx (il più comune). Al primo avvio, npx scarica @fiskaly/docs-mcp, operazione che spesso richiede più tempo del timeout di avvio del client. Eseguire npx -y @fiskaly/docs-mcp una volta nel terminale per preriscaldare la cache, quindi riavviare il client.
npx o node non trovati nell’ambiente del client. I client MCP vengono spesso avviati con un PATH minimo che non include la propria installazione di Node (comune con nvm, fnm o Homebrew). Se which npx funziona nel terminale ma il server non si avvia comunque, indicare al client un percorso assoluto — impostare command sul percorso completo restituito da which node e passare il pacchetto come argomento, oppure usare il percorso assoluto di npx.
Cache di npx obsoleta o danneggiata. Se il server funzionava in precedenza e improvvisamente fallisce, svuotare la cache e lasciarla riscaricare: rm -rf "$(npm config get cache)/_npx", quindi riavviare il client.

Assicurarsi che Node.js sia installato e presente nel PATH utilizzato dal client. Eseguire node --version per verificare — e tenere presente che alcuni client utilizzano una shell o un Node diverso dal terminale, quindi verificare l’ambiente effettivamente avviato dal client.

Nessun risultato da search_docs? Provare con un termine di ricerca più ampio. La ricerca utilizza la corrispondenza di sottostringa su titoli e testo del corpo — le parole chiave più brevi restituiscono più risultati.

get_openapi_spec restituisce un errore? Non tutti i prodotti hanno una specifica OpenAPI. Usare get_product_info per verificare se un prodotto ha un specFile.

Alternativa: Endpoint HTTP

Se si preferisce HTTP rispetto a MCP, gli stessi dati sono disponibili come endpoint leggibili dalle macchine:

Cercare documentazione — recuperare e cercare in /llms-full.txt
Specifiche OpenAPI — recuperare /specs/{product}.json o .yaml direttamente
Informazioni sul prodotto — recuperare /products.json
Codici di errore — usare get_error_codes via MCP, oppure consultare il riferimento Codici di Errore

Was this page helpful?