com.contadeo/mcp
Contadeo: emite y consulta comprobantes electrónicos del SRI (Ecuador) desde asistentes de IA
Open source Open in the app JSON README (API)
About
Contadeo: emite y consulta comprobantes electrónicos del SRI (Ecuador) desde asistentes de IA
Details
- Kind
- MCP servers
- Topic
- No topic detected
- Publisher
- com.contadeo
- Origin
- official
- Category
- ferramentas
- Transport
- http
- Version
- 0.24.1
- Added
- 2026-09-05 17:00:48
- Updated
- 2026-09-05 17:00:48
- Origin id
com.contadeo/mcp
README
# contadeo-mcp
Servidor [MCP](https://modelcontextprotocol.io) 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`](../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](https://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).
```bash
# 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:
```bash
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`)
```json
{
"mcpServers": {
"contadeo": {
"command": "npx",
"args": ["-y", "contadeo-mcp"],
"env": { "CONTADEO_API_KEY": "cdo_tu_api_key" }
}
}
}
```
### Claude Code
```bash
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](https://registry.modelcontextprotocol.io) 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 maria@correo.com
>
> **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: maria@correo.com
> ```
> ¿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** | `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.
> **37 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`](../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/`](skill/facturacion-contadeo/SKILL.md)
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:
```bash
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](https://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
```bash
# 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