Costa Rica Invoices (Hacienda comprobante electronico v4.4) MCP server

Submit an ALREADY-SIGNED Costa Rica electronic invoice (comprobante electronico v4.4) to the Ministerio de Hacienda reception gateway — the /recepcion call. You build the v4.4 XML (FacturaElectronica / TiqueteElectronico / NotaCredito etc.), sign it with YOUR Hacienda certificate (llave criptografica), and pass { clave, fecha, emisor, receptor?, comprobante_xml(base64 signed XML) }. This server does NOT sign and does NOT hold your certificate — it exchanges your ATV API user/password for an OAuth token and forwards the bytes untouched. Hacienda accepts the document for ASYNCHRONOUS processing: a successful call returns HTTP 202 with ind_estado "recibido"/"procesando" — you then poll query_invoice to get the final ind_estado "aceptado" (accepted) or "rechazado" (rejected). Required credential headers (set once in your MCP client, per-request, never stored): x-hacienda-username (your ATV API user) + x-hacienda-password (its password) — exchanged for a short-lived OAuth token at the Hacienda IdP. Optional header x-hacienda-mode: stag (default, sandbox, no fiscal effect) | prod (production, real fiscal effect). Optional owner-policy headers x-agentpay-max-amount / x-agentpay-approval-above / x-agentpay-allowed-tools.

Query the processing status of a previously submitted Costa Rica comprobante by its 50-digit clave — the GET /recepcion/{clave} call. Returns ind_estado: "recibido" (queued) / "procesando" (in process) / "aceptado" (ACCEPTED — fiscally valid, hand respuesta_xml to the buyer) / "rechazado" (REJECTED — read respuesta_xml for the reason, fix and resubmit) / "error". respuesta_xml (base64) is the Hacienda "Mensaje Hacienda" response document. Poll this after submit_invoice until ind_estado is aceptado or rechazado. Required credential headers (set once in your MCP client, per-request, never stored): x-hacienda-username (your ATV API user) + x-hacienda-password (its password) — exchanged for a short-lived OAuth token at the Hacienda IdP. Optional header x-hacienda-mode: stag (default, sandbox, no fiscal effect) | prod (production, real fiscal effect). Optional owner-policy headers x-agentpay-max-amount / x-agentpay-approval-above / x-agentpay-allowed-tools.

Assemble a Costa Rica 50-digit clave numerica from its parts — a PURE LOCAL helper (no network, no credentials, no fiscal effect). Structure: 506 + DD + MM + YY + cedula(12) + consecutivo(20) + situacion(1) + codigoSeguridad(8). Provide either the ready-made 20-digit consecutivo, or its parts (sucursal, terminal, tipoComprobante, numeroConsecutivo). tipoComprobante codes: 01=Factura, 02=Nota Debito, 03=Nota Credito, 04=Tiquete, 08=Factura de Compra, 09=Factura de Exportacion, 10=Recibo de Pago. situacion: 1=normal, 2=contingencia, 3=sin internet. Pass codigoSeguridad (8 digits) for a reproducible clave, or omit to auto-generate one. Returns the clave plus a labelled breakdown. Does NOT sign or submit.