Documentación del servidor MCP y del plugin

El ciclo en llamadas

Una sesión de facturación empieza por sales_get_context, resuelve cliente y conceptos, crea un lote de borradores en staging, lo materializa como facturas borrador con enlace para revisar y, con la confirmación explícita del usuario, emite. Varios ítems van siempre en una sola llamada, nunca una por factura.

Lectura · mcp:sales:read

• sales_get_context — se llama una vez al empezar: si la empresa puede emitir ya (setup.ready_to_emit con sus bloqueos y avisos), el modo de impuestos (motor o códigos explícitos), el catálogo de productos, la serie por defecto y las disponibles, y la regulación Verifactu.
• sales_find_customer — busca clientes por palabras del nombre. Sin coincidencia, el cliente es nuevo y la ficha se crea al materializar: hacen falta NIF, nombre y país (sin país el motor no calcula el IVA).
• sales_get_customer — ficha básica de un cliente por NIF o id: identificación, nombre, dirección y contacto principal.
• sales_find_product — resuelve un concepto contra el catálogo, si está activo; con un candidato claro toma su tarifa y su clasificación fiscal; sin coincidencia razonable, línea de texto libre. No inventa SKU.
• sales_list_tax_codes — catálogo vigente de códigos fiscales para el modo de impuestos explícito.
• sales_list_invoices · sales_get_invoice — facturas de venta con filtros por estado, cliente y fechas, paginadas; el detalle trae el estado de comunicación a la AEAT (notify_state), que es de donde se responde, nunca de memoria.
• sales_list_recent_batches · sales_get_batch — lotes recientes y su checklist por ítem (estado, incidencias, resolución), para retomar trabajo de otra conversación.

Preparación · mcp:sales:manage

• sales_create_invoice_draft — crea un lote de borradores en staging, sin efectos fiscales. La respuesta trae, por ítem, el cliente resuelto, las incidencias y los totales reales calculados por el servidor, para confirmarlos antes de seguir. En rectificativas, trae la factura original.
• sales_update_invoice_draft — corrige ítems del lote enviando solo lo que cambia. Un borrador ya materializado se descarta y se recrea por debajo, con nuevo enlace.
• sales_materialize_drafts — convierte los ítems listos en facturas borrador (sin número, sin efectos fiscales) y devuelve el enlace de cada una en la app para que el usuario la revise.
• sales_adopt_invoices — incorpora al lote borradores creados desde la web, para emitirlos o descartarlos desde el agente. No modifica su contenido.
• sales_discard_drafts — descarta borradores (borrado lógico). Un descartado no se recupera: se recrea.
• sales_update_customer — datos básicos de la ficha: nombres, país y dirección. Nunca borra valores; el NIF, el tipo y lo contable o bancario se cambian en la web.
• sales_create_product — añade un producto al catálogo, solo cuando el usuario lo pide de forma explícita.
• sales_activate_regulation — activa Verifactu con la referencia CSV del apoderamiento otorgado en la sede de la AEAT, cuando la regulación está configurada y pendiente de activar.

Emisión · mcp:sales:emit (implica manage)

• sales_issue_invoices — asigna número fiscal y crea el registro Verifactu. Irreversible salvo anulación, solo con confirmación explícita del usuario. La remisión a la AEAT es asíncrona: el estado real se consulta después con sales_get_invoice. Entrega número, enlace en Cruasan y PDF con QR.
• sales_cancel_issued_invoices — genera el registro de anulación Verifactu, que se remite a la AEAT. Procede en casos muy concretos (pruebas, facturas que no debieron emitirse); en la mayoría de los casos lo que toca es una rectificativa.

Validaciones antes de emitir

• La empresa puede emitir: series, datos fiscales y regulación en orden (setup.ready_to_emit).
• Numeración correlativa asignada por el servidor en el momento de emitir, nunca por el modelo.
• Cliente resuelto contra la base de datos, con país para calcular el IVA.
• Impuestos del motor de Cruasan o códigos fiscales del catálogo vigente; los importes dictados se tratan como base imponible y los totales los calcula el servidor.
• Lo que no cuadra vuelve como incidencia del ítem, no como factura a medias.
• Confirmación explícita del usuario e idempotencia por llamada: un reintento no emite dos veces.

Rectificativas y anulaciones

Una factura emitida no se edita. Se rectifica creando un nuevo borrador con subtype: corrective en sales_create_invoice_draft, que devuelve la factura original en resolution.corrected para enseñarla antes de seguir; el abono sale con su propio registro Verifactu. La anulación con sales_cancel_issued_invoices es la excepción, no el camino habitual. Los borradores, en cambio, se descartan. Es el mismo motor que el programa de facturación por otra puerta, no un circuito aparte.

Las trece herramientas

Lectura · mcp:banks:read

• banks_list_connections — qué bancos están conectados y en qué estado está cada conexión.
• banks_sync_status — de cuándo son los datos. Si no están frescos, el agente lo dice antes de dar la cifra.
• banks_list_accounts — las cuentas con su saldo, siempre con el IBAN enmascarado.
• banks_get_account — el detalle de una cuenta concreta, con su última sincronización.
• banks_account_summary — lo que entró y salió en un periodo, sin listar doscientos movimientos.
• banks_list_movements — los movimientos de la cuenta, con sus fechas y sus importes.

Conciliación · mcp:banks:reconcile (implica read)

• banks_list_unreconciled_movements — la cola de lo pendiente: los apuntes que aún no casan con nada.
• banks_find_reconcile_candidates — las facturas candidatas de cada movimiento, con la evidencia de por qué (importe, fecha o el concepto que cita la factura).
• banks_reconcile_movement — casa el movimiento con su factura y el cobro queda marcado.
• banks_reconcile_split — reparte un apunte: la comisión, el cobro parcial o varias facturas a la vez. Deja constancia de qué parte fue a cada sitio.
• banks_settle_remittance — liquida la remesa: un apunte del banco que por dentro son muchos recibos.
• banks_register_return — registra la devolución del recibo que el banco ha devuelto; la factura recupera su pendiente.
• banks_undo_reconciliation — deshace una conciliación, con su rastro. Equivocarse se corrige, no se tapa.

Propuesta y confirmación

• El agente trae candidatas y una propuesta; el clic de confirmar es del usuario. Ninguna herramienta de escritura se llama sin esa confirmación.
• Si el importe no cuadra con lo pendiente de la factura, no se concilia: se pregunta si es una comisión, un cobro parcial o una remesa, y se usa la herramienta que corresponde.
• Cada conciliación queda registrada con su herramienta, su cliente de IA, su usuario y su hora, y se puede revertir.

Debajo hay un algoritmo, y no gasta los tokens del agente

El grueso del cuadre no pasa por el modelo. El casado evidente por fecha e importe y las reglas aprendidas de cómo lo resuelve el usuario corren dentro de Cruasan, deterministas y auditables. Las candidatas de cada apunte pendiente también las calcula el producto en el servidor: el agente pide candidatas y le llegan ordenadas con su evidencia. Una sesión de conciliación son unas pocas llamadas sobre la lista corta de lo dudoso, no una por movimiento. La escalera completa del casado está explicada en la página de conciliación bancaria.

El agente no se conecta al banco ni lanza sincronizaciones: la conexión la mantiene Cruasan por agregador PSD2 o fichero Norma 43, con sus credenciales fuera de la conversación, y cada cifra lleva la fecha de su última sincronización.

Qué es

The Oven es el marketplace público de plugins de Cruasan para agentes de terminal. Hoy contiene un plugin, cruasan-sales («Ventas»), con tres skills que se leen como se lee un manual:

• concierge — enruta la petición a la skill que toca.
• onboard — alta si aún no hay cuenta, conexión de la credencial y comprobación previa de que se puede emitir: datos de empresa, series y regulación Verifactu.
• invoicing — borradores, revisión, emisión con registro Verifactu, lotes (retomables en otra conversación), catálogo, clientes, rectificativas y anulaciones.

El plugin habla con los endpoints REST estables de app.cruasan.com, no con el servidor MCP. Los dos comparten cuenta y datos, así que se pueden usar a la vez.

Cómo está montado

• Solo ventas, a propósito. La credencial del plugin solo puede ver, preparar y emitir ventas (sales.view, sales.manage, sales.emit). Aunque la apruebe un administrador, el servidor recorta el alcance a eso: un 403 no es un error, es la puerta que no se le ha dado. Gastos, bancos y firma van por el servidor MCP.
• Credencial acotada y fuera del plugin. La conexión preferida es OAuth por código de dispositivo (RFC 8628): el agente abre el navegador con un código corto, el usuario aprueba y los tokens quedan en ~/.config/cruasan/, donde una actualización del plugin no los borra. Como alternativa admite una API key de mínimo privilegio creada en la app (Settings → Developer → API Keys). Los tokens nunca se muestran en la conversación.
• El agente prepara; emite el usuario. Emitir asigna número fiscal y dispara el registro Verifactu, así que es irreversible salvo anulación. El plugin siempre enseña el borrador con los totales calculados por el servidor y espera la confirmación antes de ese paso. Un borrador se descarta; una emitida se rectifica o se anula en regla.
• Abierto y versionado. Cada skill es un fichero de texto en el repositorio público: lo que se lee es exactamente lo que se ejecuta. Desconectar: «desconecta Cruasan», o desde la app en perfil → Seguridad → Aplicaciones conectadas.