contadeo-mcp

Servidor MCP de Contadeo™: conecta tu asistente de IA (Claude Desktop, Claude Code, Cursor…) a la facturación electrónica del SRI (Ecuador).

— "Emite una factura de 2 horas de consultoría a $75 para Juan Pérez, pago por transferencia, y mándale el PDF a su correo"

El asistente busca (o crea) al cliente, el servidor calcula el IVA y cuadra los totales con las reglas oficiales del SRI, te muestra el resumen, y tras tu confirmación emite, espera la autorización del SRI y te entrega el RIDE.

Por qué es seguro

La matemática tributaria no la hace el modelo de IA — la hace este servidor, con las mismas reglas que valida Contadeo:

• Cálculo y cuadre de totales con aritmética decimal exacta (redondeo half-up a 2 decimales, agrupación de IVA por tarifa).
• Validación del dígito verificador de cédulas y RUC (los 3 tipos) antes de enviar nada — espejo verificado contra el núcleo fiscal de Contadeo (fuzz de 100 000 valores, 0 diferencias).
• Regla de consumidor final (identificación fija, máximo $50 — error SRI 69).
• Catálogos oficiales embebidos: tarifas de IVA (Tabla 18), formas de pago (Tabla 24), tipos de identificación (Tabla 7).
• El flujo exige confirmación humana: preparar_factura solo calcula y devuelve un resumen; emitir_factura re-valida el cuadre y rechaza payloads hechos a mano.
• Ambiente siempre visible (Pruebas/Producción): el objeto ambiente viaja en las respuestas y el resumen que confirmas encabeza con un banner (⚠️ Producción = documento tributario real). Nunca se describe "de memoria".
• confirmToken: preparar_* firma el resumen y emitir_* lo verifica — ata la emisión al resumen exacto que confirmaste y bloquea payloads modificados o resúmenes rancios (se activa con MCP_CONFIRM_SECRET).
• Auditoría: cada emisión queda registrada (tenant, tool, latencia, sin datos personales) para depuración y cumplimiento.
• Reverso legal: para dejar sin efecto una factura se emite una nota de crédito (preparar_nota_credito / emitir_nota_credito) — la vía del SRI cuando ya no aplica la anulación (fuera del plazo del día 7, o consumidor final). La anulación interna (estado ANULADO) sigue haciéndose desde el panel; su trámite formal ante el SRI es en SRI en línea.

Protección de datos e IA

Las respuestas de estas tools pueden contener datos personales de terceros: los compradores y proveedores del emisor (identificación, nombre, email, teléfono, dirección). Eso significa que la facturación pasa a tratarse mediante un sistema de IA, con un reparto de roles que conviene tener claro (LOPDP y resolución SPSP-SPD-2026-0009-R de la SPDP):

| Quién | Rol | |---|---| | La empresa emisora (tenant) | Responsable del tratamiento de los datos de sus compradores y desplegador del sistema de IA: es quien decide conectar el asistente y a cuál | | Contadeo | Encargado del tratamiento: entrega los datos por el canal MCP bajo instrucciones del tenant. No elige el asistente ni consume ningún modelo de lenguaje | | El proveedor del modelo (Anthropic, OpenAI, el que sea) | Lo elige y contrata el tenant con su cliente de IA. No es subencargado de Contadeo: la transferencia la ejecuta el asistente, bajo responsabilidad del tenant |

Qué hace el servidor por su parte: las instructions incluyen la regla (10), que ordena al asistente usar esos datos solo para la tarea en curso y no retenerlos ni reutilizarlos fuera de ella; la auditoría (mcp_auditoria) registra la llamada sin PII; y el catálogo y los comprobantes siguen acotados por la credencial y por RLS al tenant conectado.

Qué le toca al tenant: decirlo en su aviso de privacidad. Hay un texto modelo listo para copiar en docs/legal/TEXTO-MODELO-AVISO-IA.md. Si el asistente va a manejar datos de compradores, ese aviso es parte de la transparencia que la LOPDP exige hacia el titular.

Requisitos

• Cuenta en contadeo.com (gratis: 10 comprobantes/mes) con emisor y certificado .p12 configurados
• Para el modo stdio: Node.js 18+ y una API key (panel → Configuración → API → Crear; rol emisor basta)

Conexión recomendada: servidor remoto con OAuth

Sin API keys: el cliente abre el login de Contadeo, autorizas con un clic y listo (OAuth 2.1 con PKCE y registro dinámico de clientes).

# Claude Code
claude mcp add --transport http contadeo https://contadeo.com/api/mcp
# dentro de la sesión: /mcp → authenticate (abre el navegador)

En claude.ai: Settings → Connectors → Add custom connector → https://contadeo.com/api/mcp.

Para clientes que solo hablan stdio pero soportan OAuth vía proxy:

claude mcp add contadeo -- npx -y mcp-remote https://contadeo.com/api/mcp

Revocar el acceso: cambia tu contraseña en Contadeo (invalida los tokens de todos los clientes conectados).

Método alternativo: stdio + API key

Útil para automatizaciones machine-to-machine o clientes sin MCP remoto. La API key se crea en el panel (Configuración → API; el rol emisor basta).

Claude Desktop / Cursor (claude_desktop_config.json)

{
  "mcpServers": {
    "contadeo": {
      "command": "npx",
      "args": ["-y", "contadeo-mcp"],
      "env": { "CONTADEO_API_KEY": "cdo_tu_api_key" }
    }
  }
}

Claude Code

claude mcp add contadeo -e CONTADEO_API_KEY=cdo_tu_api_key -- npx -y contadeo-mcp

Variables de entorno (solo stdio)

| Variable | Requerida | Default | |---|---|---| | CONTADEO_API_KEY | ✅ | — | | CONTADEO_API_URL | — | https://contadeo.com/api |

MCP Registry

Los metadatos del servidor para el MCP Registry oficial viven en server.json, bajo el nombre com.contadeo/mcp. Ese es el identificador con el que lo resuelven los clientes que leen el registro. Si el tuyo no lo encuentra, se instala igual desde npm como contadeo-mcp o se conecta como servidor remoto (ver arriba).

Tu primera factura (tutorial)

Recomendado: deja tu cuenta en ambiente de Pruebas (Configuración → Empresa) hasta dominar el flujo — los comprobantes de Pruebas no tienen validez tributaria.

Una conversación real se ve así:

Tú: Factúrale a María García, cédula 1723456784, 3 cajas de té a $4.50 cada una, pago en efectivo. Su correo es [email protected]

Asistente: (usa contexto_emision, crear_cliente y preparar_factura) Te muestro el resumen antes de emitir:

Factura para: MARIA GARCIA (Cédula 1723456784)
Detalle:
  • 3 × Caja de té @ $4.50 = $13.50 [IVA 15% (tarifa general vigente)]
Subtotal (sin impuestos): $13.50
IVA: $2.03
TOTAL: $15.53
Forma de pago: Sin utilización del sistema financiero (efectivo)
RIDE se enviará a: [email protected]

¿Confirmas la emisión?

Tú: Sí

Asistente: (emitir_factura → esperar_autorizacion) ✅ AUTORIZADA por el SRI en 8 segundos. Clave de acceso 2306…947. Aquí tienes el PDF: [descargar RIDE]. María también lo recibirá en su correo.

En clientes MCP que soportan prompts, el comando facturar arranca este flujo guiado automáticamente.

Tools

| Categoría | Tool | Qué hace | |---|---|---| | Cuenta | consultar_cuenta | Plan, consumo del mes y ambiente (Pruebas/Producción) | | Contexto | contexto_emision | Emisores, establecimientos, puntos y certificados (los IDs para emitir) | | Catálogo | buscar_clientes / buscar_productos | Búsqueda por texto | | Catálogo | crear_cliente / crear_producto | Altas (valida cédula/RUC y tarifas antes de enviar) | | Catálogo | ajustar_stock | Ajusta las existencias de un producto (entrada, salida o corrección de inventario) | | Catálogo | consultar_ruc | Autocompleta al comprador por RUC/cédula (directorio + catastro SRI); alerta de contribuyente fantasma/inactivo | | Emisión | preparar_factura | Calcula y cuadra todo; devuelve resumen + payload (con idempotencyKey). fechaEmision opcional: default hoy, hasta 5 días atrás. No emite | | Emisión | emitir_factura | Emite tras confirmación; re-valida el cuadre localmente | | Emisión | preparar_lote | Hasta 25 facturas de una vez: datos comunes al lote + override por factura; devuelve resumenAgregado (tabla por factura + totales). No emite | | Emisión | emitir_lote | Emite el lote en secuencia tras UNA confirmación; pre-vuelo todo-o-nada y estado por factura (ENCOLADA/FALLO/NO_INTENTADA) | | Reverso | preparar_nota_credito | Nota de crédito (04) que revierte una factura: reverso TOTAL desde comprobanteId + motivo, o explícito/parcial con items. Calcula y cuadra; no emite | | Reverso | emitir_nota_credito | Emite la nota de crédito tras confirmación; re-valida cuadre y confirmToken | | Emisión | esperar_autorizacion | Polling hasta AUTORIZADO/RECHAZADO (el SRI tarda 5–30 s); acepta id o ids (hasta 25, para lotes). Los AUTORIZADO incluyen los links de descarga del RIDE y XML | | Consulta | listar_comprobantes / consultar_comprobante | Estados y detalle; con eventos: true incluye el timeline paso a paso de la emisión | | Descarga | descargar_ride / descargar_xml | URLs temporales (1 h) del PDF y XML | | Acción | anular_comprobante / reenviar_comprobante | Anula una factura autorizada (registro interno; si no aplica, orienta a nota de crédito) o reenvía el RIDE/XML por email | | Reportes | reporte_ventas | Agregados del período | | Multi-cuenta | (sin tool propia) | Si tu cuenta administra varias empresas (un RUC = una empresa), consultar_cuenta, contexto_emision y mi_situacion_tributaria traen el bloque multiempresa: cuál está activa y cuáles son las otras. Desde v0.23.0 todas las tools aceptan cuenta con el tenantId de otra empresa, emisión incluida: el resumen que confirmas nombra la razón social y el RUC emisor, y el confirmToken ata la empresa. Requiere conexión OAuth autorizada con 'operar todas mis cuentas' | | Referencia | consultar_reglas_sri | Tablas oficiales: tarifas IVA, formas de pago, identificaciones, reglas | | Asesor | consultar_calendario_tributario | Próximos vencimientos según el 9.º dígito del RUC y el régimen | | Asesor | consultar_semaforo_rimpe | Proyección de ingresos vs límites RIMPE: VERDE/AMARILLO/ROJO | | Asesor | consultar_obligaciones | Checklist de obligaciones del perfil (declaraciones, anexos, contabilidad) | | Asesor | consultar_f104 | Borrador del F104 de IVA explicado: cifras + resumen en español llano, desglose por casillero (429, 564, 601, 605, 609, 902/615), alertas proactivas y proyección del arrastre — no es la declaración oficial | | Asesor | explicar_f104 | Narra la declaración casillero por casillero para quien nunca ha declarado; también explica cifras pegadas de una declaración ya presentada | | Asesor | simular_f104 | "¿Si facturo $500 más, cuánto más pago?": escenarios de ventas/compras/retenciones/ventas a crédito sobre el borrador, con la tarifa vigente del servidor | | Asesor | validar_f104 | Chequeo previo a declarar: cruza el borrador contra los libros, detecta compras sin autorización, notas de crédito por compensar y diferencias con lo que piensas declarar | | Asesor | consultar_libro_ventas / consultar_libro_compras | Libros de ventas y de compras del período (líneas + totales, insumo de declaración y ATS) | | Asesor | consultar_retenciones | Retenciones practicadas por el emisor (no las que le practican a él) en el período | | Asesor | consultar_f103 | Auxiliar del F103 (retenciones en la fuente de RENTA): agrupa por código de retención del SRI (base, valor, cantidad) + vencimiento del catálogo; excluye IVA (va al F104/ATS). No es la declaración oficial: el mapeo código→casillero lo confirma el contador | | ATS (módulo sin publicar) | consultar_ats | Borrador de solo lectura del Anexo Transaccional Simplificado: conteos por sección, totales de cabecera, informe de validación (V1-V17/N1-N9), exclusiones, brechas del producto y si el período ya tiene un anexo archivado (snapshot). NUNCA devuelve el XML ni el ZIP — llevan la identificación de todos los clientes y proveedores del período; eso se descarga solo desde el panel. Requiere el módulo ats (402 sin él) | | Asesor | registrar_compra / clasificar_proveedor | Registro de una compra con su base y tarifa (el IVA lo deriva el servidor) y clasificación de IVA de un proveedor en dos fases: primero el impacto, y solo con confirmar se aplica | | Orientación | mi_situacion_tributaria | «¿Cómo voy?» en una llamada: qué falta para emitir, alertas, semáforo RIMPE y obligaciones, con el resumen ya redactado | | Orientación | explicar_termino | Glosario del SRI (RIDE, RIMPE, retención, clave de acceso…) para no definir de memoria |

Los tools del Asesor son informativos: el servidor calcula con sus catálogos legislativos vigentes y toda respuesta incluye un disclaimer («no constituye asesoría tributaria») que el asistente siempre muestra. 39 tools en total, las mismas para todas las cuentas: el catálogo ya no se filtra por perfil (las 3 tools de despacho multiempresa se retiraron en la v0.19.0).

Campos de respuesta (v0.7.0): preparar_* incluye el objeto ambiente, preparadoEn y un confirmToken en cada payload (reenvíalo tal cual, junto al idempotencyKey); emitir_* devuelve el ambiente legible y encoladoEn (y en el lote estadoComprobante); esperar_autorizacion y consultar_comprobante traen el ambiente legible, y con eventos:true el timeline incluye firmado → enviado → autorizado → notificado. El detalle interno de arquitectura vive en docs/MCP.md.

Lotes: varias facturas de una vez

Para emitir hasta 25 facturas en una sola pasada (p. ej. la facturación mensual a toda la cartera):

1. preparar_lote — construye el lote con la matemática hecha por el servidor: comprador, forma de pago y fechaEmision comunes al lote, con override por factura. Devuelve el resumenAgregado (tabla por factura + totales del lote).
2. UNA confirmación — el asistente muestra la tabla completa y pide una única confirmación explícita del lote entero antes de emitir.
3. emitir_lote — emite en secuencia con pre-vuelo todo-o-nada (si un payload no cuadra, no se emite ninguna); si una factura falla continúa con las demás, salvo 401/402/429 que corta el lote.
4. esperar_autorizacion con ids — sigue todos los comprobantes hasta el estado terminal (timeout sugerido: 90 s).

Reintentos seguros: cada payload lleva su idempotencyKey (lo genera preparar_lote); reintentar la emisión con la misma clave devuelve el comprobante original — no quema secuenciales ni duplica facturas.

Reglas del SRI que el servidor aplica por ti

| Regla | Detalle | |---|---| | Tarifas de IVA (Tabla 18) | '4' = 15% (general vigente) · '0' = 0% · '5' = 5% · '7' = exento · '6' = no objeto | | Formas de pago (Tabla 24) | '01' efectivo · '20' transferencia · '19' t. crédito · '16' t. débito · más en consultar_reglas_sri | | Identificación (Tabla 7) | '04' RUC · '05' cédula · '06' pasaporte · '07' consumidor final — con dígito verificador validado | | Consumidor final | Identificación fija 9999999999999, importe máximo $50 | | Cuadre | línea = cantidad×precio−descuento; IVA = base×tarifa/100; total = subtotal+IVA+propina — redondeo half-up a 2 decimales | | Fecha de emisión | Default: hoy (calendario de Ecuador). fechaEmision opcional acepta hasta 5 días atrás; nunca futura (la API la rechaza — error 65 SRI) |

Skill para Claude (opcional, recomendado)

La carpeta skill/facturacion-contadeo/ contiene un Agent Skill que le enseña a Claude el flujo completo, las reglas de oro (nunca emitir sin confirmación, nunca calcular de cabeza, verificar el ambiente) y el manejo de errores del SRI. Instalación en Claude Code:

mkdir -p ~/.claude/skills && cp -r node_modules/contadeo-mcp/skill/facturacion-contadeo ~/.claude/skills/

(o copia la carpeta a .claude/skills/ de tu proyecto).

Troubleshooting

| Síntoma | Causa probable | Solución | |---|---|---| | 401 API key inválida o revocada | Key mal copiada o revocada | Genera otra en Configuración → API | | 402 Cupo mensual agotado | Límite del plan | contadeo.com/precios | | RECHAZADO con error 62 | Identificación inválida | El flujo normal lo previene; revisa el número con el comprador | | RECHAZADO con error 52 | Totales descuadrados | Usa siempre preparar_factura; no edites el payload | | Queda en ENVIADO/CONTINGENCIA | SRI lento o caído | Reintentos automáticos; consulta en unos minutos | | La factura salió "de verdad" sin querer | Cuenta en Producción | Cambia a Pruebas en Configuración → Empresa para experimentar |

Desarrollo

# desde la raíz del monorepo (el paquete vive en el workspace)
pnpm install
pnpm --filter contadeo-mcp test    # vitest: identificación + cálculo/cuadre
pnpm --filter contadeo-mcp build   # tsc → dist/
CONTADEO_API_KEY=cdo_... node mcp/dist/index.js   # corre por stdio

El paquete exporta crearServidorContadeo({ apiUrl, token, confirmSecret?, onAuditoria? }): la misma factoría que usa el backend de Contadeo para montar el servidor remoto en https://contadeo.com/api/mcp. Arquitectura interna (protocolo, garantías, modelo de datos): docs/MCP.md; transporte/OAuth y despliegue: docs/MCP-REMOTO.md.

Documentación completa de la API REST: https://contadeo.com/desarrolladores