---
name: ruxi-mcp
description: Emite, corrige, reenvía y consulta comprobantes electrónicos del SRI de Ecuador con el servidor MCP de Ruxi. Úsala cuando el usuario pida emitir una factura, nota de crédito, nota de débito, liquidación, guía de remisión o retención con Ruxi, o consultar, corregir, reenviar y descargar comprobantes emitidos.
---

# Ruxi MCP

Ruxi emite comprobantes electrónicos para el SRI de Ecuador. Estas herramientas operan sobre la
empresa y el ambiente de la clave API conectada: no existe un parámetro de ambiente y los
permisos dependen de los scopes de esa clave.

Antes de operar, ejecuta `ruxi.contexto` para conocer empresa, RUC, ambiente, permisos y
límites. Si el servidor MCP no está conectado, la sección **Conexión** explica cómo hacerlo.

## Reglas que nunca debes romper

1. **No inventes datos fiscales.** No envíes `ambiente`, `secuencial`, `codigoNumerico`,
   certificados ni contraseñas de firma: Ruxi los administra y la solicitud falla con
   `forbidden_field`. `emisorRuc` es opcional y debe coincidir con la clave.
2. **La fecha la pone Ruxi.** Omite `fechaEmision`; si la envías, debe ser el día actual en
   Ecuador (`America/Guayaquil`). Las correcciones conservan la fecha original.
3. **No uses producción como prueba.** Si el usuario quiere probar, verifica que
   `ruxi.contexto` indique `PRUEBAS`. Emitir en `PRODUCCION` es irreversible.
4. **Nunca expongas la clave API** en el chat, repositorios, capturas ni sitios web. Vive en
   la configuración local del cliente. Si se expuso, el usuario debe revocarla en el portal.
5. **Confirmación del usuario.** Antes de emitir, corregir o reenviar resume qué documento,
   empresa, ambiente, comprador e importe se enviará y espera su confirmación. No reenvíes
   ni corrijas por iniciativa propia ante un rechazo: primero explica el motivo.
6. **Idempotencia por contenido.** Si un resultado es incierto, repite **la misma** llamada
   con el mismo `documento`: el servidor deriva la identidad y no duplica. No inventes otra
   identidad para resolver un timeout.

## Conexión

- URL: `https://mcp.ruxi.ec/mcp` · autenticación `Authorization: Bearer <clave API>`.
- La clave se crea por empresa, ambiente e integración en el portal de Ruxi
  (`https://ruxi.ec/cuenta/claves`). Cada scope habilita sus herramientas.
- VS Code (`.vscode/mcp.json`):

```json
{
  "servers": {
    "ruxi": {
      "type": "http",
      "url": "https://mcp.ruxi.ec/mcp",
      "headers": { "Authorization": "Bearer ${input:ruxiApiKey}" }
    }
  },
  "inputs": [{ "type": "promptString", "id": "ruxiApiKey", "description": "Clave API de Ruxi", "password": true }]
}
```

Cursor (`~/.cursor/mcp.json`, configuración local, nunca en un repositorio):

```json
{
  "mcpServers": {
    "ruxi": {
      "url": "https://mcp.ruxi.ec/mcp",
      "headers": { "Authorization": "Bearer <TU_CLAVE_API>" }
    }
  }
}
```

- Claude Code: `claude mcp add --transport http ruxi https://mcp.ruxi.ec/mcp --header "Authorization: Bearer <clave>"`.
- Codex (CLI, IDE y app comparten `~/.codex/config.toml`):

```toml
[mcp_servers.ruxi]
url = "https://mcp.ruxi.ec/mcp"
bearer_token_env_var = "RUXI_API_KEY"
```

Exporta `RUXI_API_KEY` con la clave antes de abrir Codex y verifica con `codex mcp list`
(o `/mcp` en la sesión). También puedes usar
`codex mcp add ruxi --url https://mcp.ruxi.ec/mcp --bearer-token-env-var RUXI_API_KEY`.
- Claude Desktop: configura `mcp-remote` con la misma URL y encabezado.
- Si el cliente no admite encabezados (algunos conectores web), usa la API REST:
  `https://api.ruxi.ec/v1` con su contrato en `/v1/openapi.json`.

## Herramientas

### Consulta (`documents:read`)

| Herramienta | Uso |
| --- | --- |
| `ruxi.contexto` | Empresa, RUC, ambiente, permisos y límites de la clave. Sin consumo. |
| `ruxi.listar-comprobantes` | Listado por empresa/ambiente con filtros `tipo` y `estado`; `page`/`perPage` (máx. 100). |
| `ruxi.consultar-comprobante` | Detalle por UUID o clave de acceso. `actualizado=true` fuerza consulta al motor. |
| `ruxi.descargar-comprobante` | XML o RIDE (PDF) en base64; `formato`: `xml` (por defecto) o `ride`. Solo si el estado es `AUTORIZADO`. |

### Escritura

| Herramienta | Scope | Uso |
| --- | --- | --- |
| `ruxi.emitir-factura-simple` | `documents:write` | Factura; el motor calcula impuestos y totales. |
| `ruxi.emitir-factura` | `documents:write` | Factura completa: deben enviarse los importes exigidos. |
| `ruxi.emitir-liquidacion` | `documents:write` | Liquidación de compra. |
| `ruxi.emitir-nota-credito` | `documents:write` | Nota de crédito con el comprobante modificado. |
| `ruxi.emitir-nota-debito` | `documents:write` | Nota de débito con motivos. |
| `ruxi.emitir-guia-remision` | `documents:write` | Guía de remisión con transportista y destinatarios. |
| `ruxi.emitir-retencion` | `documents:write` | Retención con documentos de sustento. |
| `ruxi.corregir-comprobante` | `documents:correct` | Corrige `NO_AUTORIZADO` o `DEVUELTA_CORREGIBLE`. |
| `ruxi.reenviar-comprobante` | `documents:resend` | Reactiva el mismo expediente pendiente o en revisión. |

El esquema de `documento` de cada herramienta describe todos los campos aceptados y cuáles
son obligatorios: léelo antes de construir el payload. Cada emisión consume cuota comercial;
las consultas no.

## Flujo de emisión

1. Llama `ruxi.contexto` y confirma empresa, ambiente y permisos con el usuario.
2. Elige la herramienta: factura simple cuando el motor deba calcular; factura completa u
   otros tipos cuando el usuario ya tiene los importes o el documento específico.
3. Construye `documento`. Ejemplo mínimo de factura simple:

```json
{
  "estab": "001",
  "ptoEmi": "001",
  "comprador": {
    "tipoIdentificacion": "05",
    "identificacion": "0912345678",
    "razonSocial": "Cliente Ejemplo"
  },
  "detalles": [
    { "descripcion": "Servicio", "cantidad": 1, "precioUnitario": 10 }
  ]
}
```

4. Llama a la herramienta de emisión con `documento` (y `idempotencia` solo si el usuario
   necesita una identidad explícita). La respuesta trae `data.id`, `data.estado`,
   `data.cuota` y `data.error`. Conserva el `id` para el seguimiento.
5. Si `data.estado` es `PENDIENTE_ENVIO`, `EN_PROCESAMIENTO` o similar, consulta con
   `ruxi.consultar-comprobante` usando `actualizado=true`. Espera entre consultas (15–30 s):
   no satures el límite de lectura.
6. Con `AUTORIZADO`, descarga el XML (`formato: xml`) o el RIDE en PDF (`formato: ride`)
   con `ruxi.descargar-comprobante`.
7. Si `data.error` o `detalle.mensajes` muestran un rechazo, explica la causa y propone la
   corrección. No reenvíes un rechazo definitivo.

## Corrección

- Solo aplica a comprobantes `NO_AUTORIZADO` o `DEVUELTA_CORREGIBLE`; consulta primero con
  `ruxi.consultar-comprobante` si no conoces el estado.
- `documento` debe ser el **DTO completo del tipo original** (una factura simple se corrige
  con el DTO completo de factura). Revisa el esquema de `ruxi.corregir-comprobante`.
- Conserva clave de acceso, secuencial y fecha de emisión: omite `fechaEmision`.
- Omite `idempotencia` para que se derive del contenido, o envía una nueva por corrección.
  Repite la misma llamada si hay timeout; no generes otra identidad.
- Tras aceptar, la respuesta queda `PENDIENTE_CORRECCION`: sigue con `consultar` hasta el
  estado final.

## Reenvío

- Solo para expedientes `PENDIENTE_RECEPCION`, `RECEPCION_INCIERTA`, `EN_PROCESAMIENTO` o
  `REVISION_MANUAL`. No cambia el contenido ni reserva otro documento.
- Un rechazo definitivo requiere corrección, no reenvío. El reintento con la misma llamada
  es seguro.

## Errores frecuentes

| Código | Significado y acción |
| --- | --- |
| `insufficient_scope` | La clave no tiene el permiso. Pedir al usuario una clave con el scope indicado. |
| `forbidden_field` | Se envió ambiente, secuencial, certificados o similar. Eliminar esos campos. |
| `invalid_emission_date` | Fecha distinta a la de Ecuador u original. Omitir `fechaEmision`. |
| `idempotency_conflict` | La identidad ya pertenece a otro contenido. No reutilizarla; usar otra operación. |
| `invalid_document` | El motor rechazó la estructura o los datos. Leer `detalle.mensajes` y corregir. |
| `not_correctable` / `not_resendable` | El estado no admite la operación. Consultar el estado actual. |
| `rate_limited` | Se superó el límite. Esperar `Retry-After` antes de reintentar. |
| `quota_exhausted` / `insufficient_balance` | Sin cupo. El usuario debe ampliar el plan o recargar. |
| `sandbox_limit` | Cupo diario de pruebas agotado. Continuar mañana o usar producción con autorización. |
| `service_unavailable` / `fiscal_service_unavailable` | Resultado incierto. Repetir la misma llamada y conservar el `requestId`. |
| `not_found` | Documento fuera de la empresa/ambiente de la clave o inexistente. |

## Límites

- Lectura: 120 consultas/min por clave (600/min por cuenta).
- Descarga: 30/min por clave (120/min por cuenta).
- Escritura: 60/min por clave (300/min por cuenta) más la cuota del plan.
- El XML o el RIDE descargado tiene un límite de tamaño por MCP; si se excede, usar la API REST.

## Seguridad

- La clave API es la única credencial. No la muestres en respuestas ni la escribas en
  archivos versionados; guíala a la configuración local del cliente.
- Ante exposición, el usuario debe revocarla en `https://ruxi.ec/cuenta/claves` y crear otra.
- No incluyas XML completos, claves de acceso ni datos del comprador en resúmenes que salgan
  del equipo del usuario sin su autorización.

## Referencias

- Contrato de la API: `https://api.ruxi.ec/v1/openapi.json`.
- Guía del portal: `https://ruxi.ec/cuenta/mcp`.
- Este archivo: `https://ruxi.ec/skills/ruxi-mcp/SKILL.md`.

## Instalación de esta skill

Descarga `SKILL.md` en la carpeta de skills del cliente:

- Codex, Cursor, Copilot y compatibles con Agent Skills: `~/.agents/skills/ruxi-mcp/SKILL.md`.
  Codex también reconoce la carpeta legacy `~/.codex/skills/ruxi-mcp/`.
- Claude Code: `~/.claude/skills/ruxi-mcp/SKILL.md`.

En Codex puedes invocarla con `$ruxi-mcp` o dejar que se active por su descripción.