@firmo-ecf/mcp

Servidor MCP (Model Context Protocol) de Firmo: permite que agentes de IA (Claude, Cursor, etc.) emitan y consulten comprobantes fiscales electrónicos (e-CF) de la DGII de República Dominicana.

Con una clave sk_test_… todo ocurre en sandbox (simulador de la DGII). Con sk_live_… el agente emite comprobantes fiscales reales.

Dos formas de usarlo

| Modo | Cómo | |---|---| | Remoto (HTTP streamable) | https://api.firmo.do/mcp con Authorization: Bearer sk_… | | Local (stdio) | npx -y @firmo-ecf/mcp con la variable FIRMO_API_KEY |

Variables del modo local:

| Variable | Obligatoria | Descripción | |---|---|---| | FIRMO_API_KEY | sí* | sk_test_… o sk_live_…. *Sin ella solo funcionan calcular_totales y explicar_tipo_ecf. | | FIRMO_BASE_URL | no | Por defecto https://api.firmo.do (en desarrollo, http://localhost:8080). | | FIRMO_EMPRESA_ID | no | Empresa sobre la que actuar (integradores con varias empresas). |

El servidor llama a la API con la cabecera Firmo-Channel: mcp, así que los e-CF emitidos desde un asistente quedan con canal: "mcp" (dato declarado por el cliente, no verificado).

Claude Desktop

Edita claude_desktop_config.json (macOS: ~/Library/Application Support/Claude/, Windows: %APPDATA%\Claude\):

{
  "mcpServers": {
    "firmo": {
      "command": "npx",
      "args": ["-y", "@firmo-ecf/mcp"],
      "env": {
        "FIRMO_API_KEY": "sk_test_…"
      }
    }
  }
}

Reinicia Claude Desktop. También puedes agregar el MCP remoto como conector personalizado con la URL https://api.firmo.do/mcp.

Claude Code

Local (stdio):

claude mcp add firmo --env FIRMO_API_KEY=sk_test_… -- npx -y @firmo-ecf/mcp

Remoto (HTTP):

claude mcp add --transport http firmo https://api.firmo.do/mcp --header "Authorization: Bearer sk_test_…"

Cursor

En ~/.cursor/mcp.json (global) o .cursor/mcp.json (proyecto):

{
  "mcpServers": {
    "firmo": {
      "command": "npx",
      "args": ["-y", "@firmo-ecf/mcp"],
      "env": { "FIRMO_API_KEY": "sk_test_…" }
    }
  }
}

O remoto:

{
  "mcpServers": {
    "firmo": {
      "url": "https://api.firmo.do/mcp",
      "headers": { "Authorization": "Bearer sk_test_…" }
    }
  }
}

Herramientas

| Herramienta | Qué hace | |---|---| | emitir_ecf | Emite un e-CF (espera hasta 20 s el resultado de la DGII) | | obtener_ecf | Obtiene un e-CF por id o e-NCF | | listar_ecf | Lista e-CF emitidos con filtros y paginación | | descargar_xml_ecf | XML firmado de un e-CF | | reenviar_ecf | Reintenta el envío del mismo XML de un e-CF en error o pendiente sin avanzar | | reporte_facturas | Reporte de un periodo (hoy, ayer, semana, mes o rango, hora de RD): totales por estado y canal, monto, ITBIS y lista | | facturas_que_requieren_atencion | e-CF en error, rechazado sin corregir, pendiente o en_proceso sin avanzar, con la acción sugerida | | reintentar_envio | Reenvía el mismo XML (antes confirma con la DGII que no lo tenía) | | consultar_estado_dgii_ecf | Consulta en la DGII el estado real de un e-CF propio y lo actualiza (distinta de consultar_estado_dgii, para terceros) | | corregir_ecf_rechazado | Reemite un rechazado corregido: mismo e-NCF si la DGII lo permite; si no, uno nuevo enlazado | | reenviar_pendientes | Reenvío en lote (máx. 100). Pide confirmación al usuario y exige confirmado: true | | enviar_ecf_por_correo | Envía la representación impresa por correo | | anular_secuencias | Anula rangos de e-NCF no usados (ANECF). Pide confirmación al usuario | | listar_recibidos | e-CF recibidos de proveedores | | aprobar_recibido | Aprobación comercial (ACECF) | | rechazar_recibido | Rechazo comercial (ACECF). Pide confirmación al usuario | | consultar_estado_dgii | Estado de un e-CF (propio o de terceros) en la DGII | | ver_empresa / actualizar_empresa | Datos del emisor y ambiente | | listar_secuencias / registrar_secuencia | Rangos de e-NCF autorizados | | listar_webhooks / crear_webhook / eliminar_webhook | Webhooks | | listar_empresas / crear_empresa | Empresas hijas (integradores) | | progreso_certificacion | Avance en los 14 pasos de certificación DGII | | calcular_totales | Totales e ITBIS como la DGII (local, sin red) | | explicar_tipo_ecf | Qué tipo de e-CF usar y qué exige (local) |

Todas devuelven un resumen legible y structuredContent con los datos completos, e incluyen annotations (readOnlyHint, destructiveHint, idempotentHint).

Recursos: firmo://catalogo/tipos-ecf, firmo://catalogo/codigos-error, firmo://catalogo/indicadores.

Prompt: emitir_factura_guiada — guía al agente para emitir una factura paso a paso, con confirmación antes de emitir.

Ejemplo de conversación

«Factúrale a Cliente SRL (RNC 131880681) 10 horas de consultoría a RD$2,500 la hora.»

El agente usa calcular_totales (gravado RD$25,000.00, ITBIS RD$4,500.00, total RD$29,500.00), te pide confirmar y luego llama a emitir_ecf con tipo 31.

Uso programático

@firmo-ecf/mcp exporta createFirmoMcpServer para montarlo en tu propio servidor (así lo hace la API de Firmo en /mcp):

import { createFirmoMcpServer } from '@firmo-ecf/mcp';
import { StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/streamableHttp.js';

const server = createFirmoMcpServer({ apiKey, baseUrl: 'https://api.firmo.do', empresaId });
const transport = new StreamableHTTPServerTransport({ sessionIdGenerator: undefined });
await server.connect(transport);
await transport.handleRequest(req, res, req.body);

Licencia

MIT