{
  "markdown": "# contadeo-mcp\n\nServidor [MCP](https://modelcontextprotocol.io) de **Contadeo™**: conecta tu\nasistente de IA (Claude Desktop, Claude Code, Cursor…) a la facturación\nelectrónica del SRI (Ecuador).\n\n> — *\"Emite una factura de 2 horas de consultoría a $75 para Juan Pérez, pago\n> por transferencia, y mándale el PDF a su correo\"*\n>\n> El asistente busca (o crea) al cliente, **el servidor calcula el IVA y\n> cuadra los totales con las reglas oficiales del SRI**, te muestra el\n> resumen, y tras tu confirmación emite, espera la autorización del SRI y te\n> entrega el RIDE.\n\n## Por qué es seguro\n\nLa matemática tributaria **no la hace el modelo de IA — la hace este\nservidor**, con las mismas reglas que valida Contadeo:\n\n- Cálculo y cuadre de totales con aritmética decimal exacta (redondeo\n  half-up a 2 decimales, agrupación de IVA por tarifa).\n- Validación del dígito verificador de cédulas y RUC (los 3 tipos) **antes**\n  de enviar nada — espejo verificado contra el núcleo fiscal de Contadeo\n  (fuzz de 100 000 valores, 0 diferencias).\n- Regla de consumidor final (identificación fija, máximo $50 — error SRI 69).\n- Catálogos oficiales embebidos: tarifas de IVA (Tabla 18), formas de pago\n  (Tabla 24), tipos de identificación (Tabla 7).\n- El flujo exige **confirmación humana**: `preparar_factura` solo calcula y\n  devuelve un resumen; `emitir_factura` re-valida el cuadre y rechaza\n  payloads hechos a mano.\n- **Ambiente siempre visible** (Pruebas/Producción): el objeto `ambiente` viaja\n  en las respuestas y el `resumen` que confirmas encabeza con un banner\n  (⚠️ **Producción** = documento tributario real). Nunca se describe \"de memoria\".\n- **`confirmToken`**: `preparar_*` firma el resumen y `emitir_*` lo verifica —\n  ata la emisión al resumen exacto que confirmaste y bloquea payloads\n  modificados o resúmenes rancios (se activa con `MCP_CONFIRM_SECRET`).\n- **Auditoría**: cada emisión queda registrada (tenant, tool, latencia, sin\n  datos personales) para depuración y cumplimiento.\n- **Reverso legal**: para dejar sin efecto una factura se emite una **nota de\n  crédito** (`preparar_nota_credito` / `emitir_nota_credito`) — la vía del SRI\n  cuando ya no aplica la anulación (fuera del plazo del día 7, o consumidor\n  final). La **anulación** interna (estado `ANULADO`) sigue haciéndose desde el\n  panel; su trámite formal ante el SRI es en *SRI en línea*.\n\n## Protección de datos e IA\n\nLas respuestas de estas tools pueden contener **datos personales de terceros**:\nlos compradores y proveedores del emisor (identificación, nombre, email,\nteléfono, dirección). Eso significa que la facturación pasa a tratarse\n**mediante un sistema de IA**, con un reparto de roles que conviene tener claro\n(LOPDP y resolución SPSP-SPD-2026-0009-R de la SPDP):\n\n| Quién | Rol |\n|---|---|\n| 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 |\n| 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 |\n| 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 |\n\nQué hace el servidor por su parte: las `instructions` incluyen la regla (10),\nque ordena al asistente usar esos datos **solo para la tarea en curso** y no\nretenerlos ni reutilizarlos fuera de ella; la auditoría (`mcp_auditoria`)\nregistra la llamada **sin PII**; y el catálogo y los comprobantes siguen\nacotados por la credencial y por RLS al tenant conectado.\n\nQué le toca al tenant: **decirlo en su aviso de privacidad**. Hay un texto\nmodelo listo para copiar en\n[`docs/legal/TEXTO-MODELO-AVISO-IA.md`](../docs/legal/TEXTO-MODELO-AVISO-IA.md).\nSi el asistente va a manejar datos de compradores, ese aviso es parte de la\ntransparencia que la LOPDP exige hacia el titular.\n\n## Requisitos\n\n- Cuenta en [contadeo.com](https://contadeo.com) (gratis: 10 comprobantes/mes)\n  con emisor y certificado `.p12` configurados\n- Para el modo stdio: Node.js 18+ y una **API key** (panel →\n  **Configuración → API** → Crear; rol `emisor` basta)\n\n## Conexión recomendada: servidor remoto con OAuth\n\nSin API keys: el cliente abre el **login de Contadeo**, autorizas con un\nclic y listo (OAuth 2.1 con PKCE y registro dinámico de clientes).\n\n```bash\n# Claude Code\nclaude mcp add --transport http contadeo https://contadeo.com/api/mcp\n# dentro de la sesión: /mcp → authenticate (abre el navegador)\n```\n\nEn **claude.ai**: Settings → Connectors → *Add custom connector* →\n`https://contadeo.com/api/mcp`.\n\nPara clientes que solo hablan stdio pero soportan OAuth vía proxy:\n\n```bash\nclaude mcp add contadeo -- npx -y mcp-remote https://contadeo.com/api/mcp\n```\n\nRevocar el acceso: cambia tu contraseña en Contadeo (invalida los tokens de\ntodos los clientes conectados).\n\n## Método alternativo: stdio + API key\n\nÚtil para automatizaciones machine-to-machine o clientes sin MCP remoto.\nLa API key se crea en el panel (**Configuración → API**; el rol `emisor`\nbasta).\n\n### Claude Desktop / Cursor (`claude_desktop_config.json`)\n\n```json\n{\n  \"mcpServers\": {\n    \"contadeo\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"contadeo-mcp\"],\n      \"env\": { \"CONTADEO_API_KEY\": \"cdo_tu_api_key\" }\n    }\n  }\n}\n```\n\n### Claude Code\n\n```bash\nclaude mcp add contadeo -e CONTADEO_API_KEY=cdo_tu_api_key -- npx -y contadeo-mcp\n```\n\n### Variables de entorno (solo stdio)\n\n| Variable | Requerida | Default |\n|---|---|---|\n| `CONTADEO_API_KEY` | ✅ | — |\n| `CONTADEO_API_URL` | — | `https://contadeo.com/api` |\n\n## MCP Registry\n\nLos metadatos del servidor para el\n[MCP Registry](https://registry.modelcontextprotocol.io) oficial viven en\n`server.json`, bajo el nombre **`com.contadeo/mcp`**. Ese es el identificador\ncon el que lo resuelven los clientes que leen el registro. Si el tuyo no lo\nencuentra, se instala igual desde npm como `contadeo-mcp` o se conecta como\nservidor remoto (ver arriba).\n\n## Tu primera factura (tutorial)\n\n> Recomendado: deja tu cuenta en ambiente de **Pruebas** (Configuración →\n> Empresa) hasta dominar el flujo — los comprobantes de Pruebas no tienen\n> validez tributaria.\n\nUna conversación real se ve así:\n\n> **Tú:** Factúrale a María García, cédula 1723456784, 3 cajas de té a $4.50\n> cada una, pago en efectivo. Su correo es maria@correo.com\n>\n> **Asistente:** *(usa contexto_emision, crear_cliente y preparar_factura)*\n> Te muestro el resumen antes de emitir:\n> ```\n> Factura para: MARIA GARCIA (Cédula 1723456784)\n> Detalle:\n>   • 3 × Caja de té @ $4.50 = $13.50 [IVA 15% (tarifa general vigente)]\n> Subtotal (sin impuestos): $13.50\n> IVA: $2.03\n> TOTAL: $15.53\n> Forma de pago: Sin utilización del sistema financiero (efectivo)\n> RIDE se enviará a: maria@correo.com\n> ```\n> ¿Confirmas la emisión?\n>\n> **Tú:** Sí\n>\n> **Asistente:** *(emitir_factura → esperar_autorizacion)* ✅ **AUTORIZADA**\n> por el SRI en 8 segundos. Clave de acceso 2306…947. Aquí tienes el PDF:\n> [descargar RIDE]. María también lo recibirá en su correo.\n\nEn clientes MCP que soportan *prompts*, el comando **`facturar`** arranca\neste flujo guiado automáticamente.\n\n## Tools\n\n| Categoría | Tool | Qué hace |\n|---|---|---|\n| Cuenta | `consultar_cuenta` | Plan, consumo del mes y **ambiente** (Pruebas/Producción) |\n| Contexto | `contexto_emision` | Emisores, establecimientos, puntos y certificados (los IDs para emitir) |\n| Catálogo | `buscar_clientes` / `buscar_productos` | Búsqueda por texto |\n| Catálogo | `crear_cliente` / `crear_producto` | Altas (valida cédula/RUC y tarifas antes de enviar) |\n| Catálogo | `ajustar_stock` | Ajusta las existencias de un producto (entrada, salida o corrección de inventario) |\n| Catálogo | `consultar_ruc` | Autocompleta al comprador por RUC/cédula (directorio + catastro SRI); alerta de contribuyente fantasma/inactivo |\n| **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 |\n| **Emisión** | `emitir_factura` | Emite tras confirmación; re-valida el cuadre localmente |\n| **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 |\n| **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) |\n| **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 |\n| **Reverso** | `emitir_nota_credito` | Emite la nota de crédito tras confirmación; re-valida cuadre y confirmToken |\n| 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 |\n| Consulta | `listar_comprobantes` / `consultar_comprobante` | Estados y detalle; con `eventos: true` incluye el timeline paso a paso de la emisión |\n| Descarga | `descargar_ride` / `descargar_xml` | URLs temporales (1 h) del PDF y XML |\n| 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 |\n| Reportes | `reporte_ventas` | Agregados del período |\n| 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' |\n| Referencia | `consultar_reglas_sri` | Tablas oficiales: tarifas IVA, formas de pago, identificaciones, reglas |\n| **Asesor** | `consultar_calendario_tributario` | Próximos vencimientos según el 9.º dígito del RUC y el régimen |\n| **Asesor** | `consultar_semaforo_rimpe` | Proyección de ingresos vs límites RIMPE: VERDE/AMARILLO/ROJO |\n| **Asesor** | `consultar_obligaciones` | Checklist de obligaciones del perfil (declaraciones, anexos, contabilidad) |\n| **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 |\n| **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 |\n| **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 |\n| **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 |\n| **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) |\n| **Asesor** | `consultar_retenciones` | Retenciones **practicadas por el emisor** (no las que le practican a él) en el período |\n| **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 |\n| 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 |\n| Orientación | `explicar_termino` | Glosario del SRI (RIDE, RIMPE, retención, clave de acceso…) para no definir de memoria |\n\n> Los tools del **Asesor** son informativos: el servidor calcula con sus\n> catálogos legislativos vigentes y toda respuesta incluye un `disclaimer`\n> («no constituye asesoría tributaria») que el asistente siempre muestra.\n> **37 tools en total**, las mismas para todas las cuentas: el catálogo ya no\n> se filtra por perfil (las 3 tools de despacho multiempresa se retiraron en\n> la v0.19.0).\n\n> **Campos de respuesta (v0.7.0):** `preparar_*` incluye el objeto `ambiente`,\n> `preparadoEn` y un `confirmToken` en cada payload (reenvíalo tal cual, junto\n> al `idempotencyKey`); `emitir_*` devuelve el `ambiente` legible y `encoladoEn`\n> (y en el lote `estadoComprobante`); `esperar_autorizacion` y\n> `consultar_comprobante` traen el `ambiente` legible, y con `eventos:true` el\n> timeline incluye **firmado → enviado → autorizado → notificado**. El detalle\n> interno de arquitectura vive en [`docs/MCP.md`](../docs/MCP.md).\n\n## Lotes: varias facturas de una vez\n\nPara emitir hasta **25 facturas en una sola pasada** (p. ej. la facturación\nmensual a toda la cartera):\n\n1. `preparar_lote` — construye el lote con la matemática hecha por el\n   servidor: comprador, forma de pago y `fechaEmision` comunes al lote, con\n   override por factura. Devuelve el `resumenAgregado` (tabla por factura +\n   totales del lote).\n2. **UNA confirmación** — el asistente muestra la tabla completa y pide una\n   única confirmación explícita del lote entero antes de emitir.\n3. `emitir_lote` — emite en secuencia con pre-vuelo todo-o-nada (si un\n   payload no cuadra, no se emite ninguna); si una factura falla continúa\n   con las demás, salvo 401/402/429 que corta el lote.\n4. `esperar_autorizacion` con `ids` — sigue todos los comprobantes hasta el\n   estado terminal (timeout sugerido: 90 s).\n\nReintentos seguros: cada payload lleva su `idempotencyKey` (lo genera\n`preparar_lote`); reintentar la emisión con la misma clave devuelve el\ncomprobante original — no quema secuenciales ni duplica facturas.\n\n## Reglas del SRI que el servidor aplica por ti\n\n| Regla | Detalle |\n|---|---|\n| Tarifas de IVA (Tabla 18) | `'4'` = **15% (general vigente)** · `'0'` = 0% · `'5'` = 5% · `'7'` = exento · `'6'` = no objeto |\n| Formas de pago (Tabla 24) | `'01'` efectivo · `'20'` transferencia · `'19'` t. crédito · `'16'` t. débito · más en `consultar_reglas_sri` |\n| Identificación (Tabla 7) | `'04'` RUC · `'05'` cédula · `'06'` pasaporte · `'07'` consumidor final — **con dígito verificador validado** |\n| Consumidor final | Identificación fija `9999999999999`, importe **máximo $50** |\n| Cuadre | línea = cantidad×precio−descuento; IVA = base×tarifa/100; total = subtotal+IVA+propina — redondeo half-up a 2 decimales |\n| 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) |\n\n## Skill para Claude (opcional, recomendado)\n\nLa carpeta [`skill/facturacion-contadeo/`](skill/facturacion-contadeo/SKILL.md)\ncontiene un **Agent Skill** que le enseña a Claude el flujo completo, las\nreglas de oro (nunca emitir sin confirmación, nunca calcular de cabeza,\nverificar el ambiente) y el manejo de errores del SRI. Instalación en Claude\nCode:\n\n```bash\nmkdir -p ~/.claude/skills && cp -r node_modules/contadeo-mcp/skill/facturacion-contadeo ~/.claude/skills/\n```\n\n(o copia la carpeta a `.claude/skills/` de tu proyecto).\n\n## Troubleshooting\n\n| Síntoma | Causa probable | Solución |\n|---|---|---|\n| `401 API key inválida o revocada` | Key mal copiada o revocada | Genera otra en Configuración → API |\n| `402 Cupo mensual agotado` | Límite del plan | [contadeo.com/precios](https://contadeo.com/precios) |\n| `RECHAZADO` con error 62 | Identificación inválida | El flujo normal lo previene; revisa el número con el comprador |\n| `RECHAZADO` con error 52 | Totales descuadrados | Usa siempre `preparar_factura`; no edites el payload |\n| Queda en `ENVIADO`/`CONTINGENCIA` | SRI lento o caído | Reintentos automáticos; consulta en unos minutos |\n| La factura salió \"de verdad\" sin querer | Cuenta en Producción | Cambia a Pruebas en Configuración → Empresa para experimentar |\n\n## Desarrollo\n\n```bash\n# desde la raíz del monorepo (el paquete vive en el workspace)\npnpm install\npnpm --filter contadeo-mcp test    # vitest: identificación + cálculo/cuadre\npnpm --filter contadeo-mcp build   # tsc → dist/\nCONTADEO_API_KEY=cdo_... node mcp/dist/index.js   # corre por stdio\n```\n\nEl paquete exporta `crearServidorContadeo({ apiUrl, token, confirmSecret?,\nonAuditoria? })`: la misma factoría que usa el backend de Contadeo para montar\nel **servidor remoto** en `https://contadeo.com/api/mcp`. Arquitectura interna\n(protocolo, garantías, modelo de datos): `docs/MCP.md`; transporte/OAuth y\ndespliegue: `docs/MCP-REMOTO.md`.\n\nDocumentación completa de la API REST: https://contadeo.com/desarrolladores",
  "bytes": 17078,
  "sha": "469f85c910ade4141a3cb36480ba122b77385a200f0a1306bf89c98d0bec80fc",
  "repo_slug": "",
  "fonte": "npm",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_com_contadeo_mcp_fbf5f424/readme"
}