Servidor MCP

El servidor MCP fiskaly-docs da a los asistentes de codificación de IA acceso directo a la documentación de fiskaly, las especificaciones OpenAPI, los metadatos de productos y los códigos de error — sin web scraping ni búsquedas manuales.

Implementa el Model Context Protocol (MCP) y expone 9 herramientas que puede llamar cualquier cliente compatible con MCP.

Herramientas disponibles

Herramientas de documentación

Buscar páginas de documentación por palabre clave. Devuelve títulos de páginas coincidentes, rutas y fragmentos relevantes de 500 caracteres.

Parámetros:

• query (obligatorio) — palabre clave de búsqueda (coincidencia de subcadena en título y cuerpo)
• product (opcional) — filtrar por nombre de producto, p. ej. SIGN DE, SIGN FR
• country (opcional) — filtrar por código de país, p. ej. DE, FR, IT

Leer una página de documentación completa por ruta. Admite coincidencia parcial y de sufijo. Devuelve el cuerpo completo de la página y las páginas hermanas relacionadas.

Parámetros:

• path (obligatorio) — ruta de la página o sufijo, p. ej. getting-started/quickstart, quickstart

Obtener metadatos de un producto de fiskaly: descripción, país, arquitectura de API, URLs base, enlaces a documentación y páginas relacionadas.

Parámetros:

• product (obligatorio) — ID del producto (p. ej. sign-de, sign-fr) o nombre del producto (p. ej. SIGN DE, DSFinV-K)

Obtener códigos de error de la API de fiskaly con estado HTTP, descripción y orientación para resolverlos. Opcionalmente filtrar por producto.

Parámetros:

• product (opcional) — filtrar por ID de producto (p. ej. sign-de, sign-fr). Omitir para obtener todos los códigos de error.

Herramientas de exploración de API

Obtener la especificación OpenAPI de un producto de fiskaly. Use format="summary" para una vista general de los endpoints y nombres de esquemas en lugar de la especificación completa.

Parámetros:

• product (obligatorio) — ID del producto: sign-de, sign-at, sign-fr, sign-it, sign-es, dsfinvk, ereceipt, management, obono
• format (opcional) — full (predeterminado) o summary (info + lista de endpoints + nombres de esquemas)

Listar todos los endpoints de API de un producto, agrupados por etiqueta. Muestra método, ruta, operationId y resumen.

Parámetros:

• product (obligatorio) — ID del producto
• tag (opcional) — filtrar por nombre de etiqueta (coincidencia parcial sin distinción de mayúsculas/minúsculas)

Obtener información detallada sobre un endpoint específico: parámetros, cuerpo de solicitud, esquemas de respuesta y seguridad.

Parámetros:

• product (obligatorio) — ID del producto
• path (opcional) — ruta de API a coincidir (coincidencia parcial)
• method (opcional) — método HTTP (GET, POST, PUT, etc.)
• operationId (opcional) — ID de operación (parcial, sin distinción de mayúsculas/minúsculas)

Buscar un esquema OpenAPI por nombre con expansión de $ref (2 niveles de profundidad, seguro ante ciclos). Use list=true para ver todos los nombres de esquemas disponibles.

Parámetros:

• product (obligatorio) — ID del producto
• schema (opcional) — nombre del esquema (coincidencia parcial, sin distinción de mayúsculas/minúsculas)
• list (opcional) — establecer en true para listar todos los nombres de esquemas

Herramientas de integración

Obtener una guía de integración paso a paso para un producto. Combina información del entorno, flujo de autenticación, pasos de inicio rápido de la documentación, endpoints clave de la especificación y enlaces a la documentación.

Parámetros:

• product (obligatorio) — ID o nombre del producto (p. ej. sign-de, SIGN FR)

Configuración

Claude Code

Añade el servidor MCP fiskaly-docs a tu proyecto:

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

O añádalo al .mcp.json de tu proyecto:

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

Cursor

Añade a su .cursor/mcp.json:

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

Windsurf

Añade a ~/.codeium/windsurf/mcp_config.json:

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

VS Code (GitHub Copilot)

Añade al .vscode/mcp.json de tu proyecto:

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

IDEs de JetBrains

Ve a Configuración > Herramientas > Asistente de IA > Model Context Protocol y añade un nuevo servidor con:

• Comando: npx
• Argumentos: @fiskaly/docs-mcp

Clientes MCP genéricos

El servidor se comunica a través de stdio usando el protocolo MCP. Inícielo con:

npx @fiskaly/docs-mcp

Requiere Node.js 24+.

Ejemplos de uso

Leer una página de documentación completa

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

Devuelve el cuerpo completo de la página con enlaces a páginas hermanas — ideal para leer guías de integración de principio a fin.

Explorar endpoints de API

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

Devuelve todos los endpoints relacionados con transacciones agrupados por etiqueta, con método, ruta, operationId y resumen.

Buscar un endpoint específico

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

Devuelve información detallada: parámetros, esquema del cuerpo de solicitud (resuelto), esquemas de respuesta y requisitos de seguridad.

Obtener una guía de integración

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

Devuelve una guía compuesta con URLs de entorno, flujo de autenticación, contenido de inicio rápido, endpoints clave de la especificación y enlaces a páginas de documentación relevantes.

Resolver un esquema

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

Devuelve el esquema resuelto con $ref expandido 2 niveles de profundidad. Use list=true para ver primero todos los nombres de esquemas disponibles.

Obtener un resumen de la especificación

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

Devuelve información de la API, una lista de todos los endpoints y nombres de esquemas — sin la especificación completa de más de 5000 líneas.

Buscar en la documentación

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

Devuelve páginas coincidentes con títulos, rutas y fragmentos de contenido de 500 caracteres relevantes para las transacciones de SIGN DE.

Consultar metadatos de un producto

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

Devuelve metadatos estructurados:

• Nombre, descripción y país del producto
• Arquitectura de API (especializada o unificada)
• URLs base para entornos TEST y LIVE
• URL de especificación, URL de documentación y páginas relacionadas

Consultar códigos de error

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

Devuelve todos los códigos de error de SIGN DE con códigos de estado HTTP, descripciones y orientación para su resolución.

Resolución de problemas

¿El servidor no arranca? Asegúrate de tener instalado Node.js 24+. Ejecuta node --version para comprobarlo.

¿Sin resultados de search_docs? Prueba con un término de búsqueda más amplio. La búsqueda usa coincidencia de subcadenas en títulos y texto del cuerpo — las palabres clave más cortas devuelven más resultados.

¿get_openapi_spec devuelve un error? No todos los productos tienen una especificación OpenAPI. Use get_product_info para comprobar si un producto tiene un specFile.

Alternativa: Endpoints HTTP

Si prefiere HTTP sobre MCP, los mismos datos están disponibles como endpoints legibles por máquinas:

• Buscar documentación — obtener y buscar en /llms-full.txt
• Especificaciones OpenAPI — obtener /specs/{product}.json o .yaml directamente
• Información del producto — obtener /products.json
• Códigos de error — usar get_error_codes vía MCP, o consultar la referencia de Códigos de Error