# Uruguay Invoice MCP

Remote MCP server that lets any AI agent submit **Uruguay DGI e-Factura** (Comprobante Fiscal Electrónico, **CFE**) documents to the DGI *facturación electrónica* webservice. It is a **stateless forwarder**: the CFE signature, the Sobre signature and the WS-Security SOAP signature all stay **merchant-side**. Bring your own Uruguayan CA certificate; nothing is stored.

- **Endpoint:** `https://inv-uy.wishpool.app/mcp` (MCP Streamable HTTP)
- **Region:** `gru1` (São Paulo) · **License:** MIT
- **Registry:** `app.wishpool/uruguay-invoice-mcp`

## The signing boundary (read this first)

DGI requires **message-level WS-Security**: every submission is a SOAP message whose Body is X.509-signed with the merchant's Uruguayan CA certificate (e.g. from Correo Uruguayo), and each CFE and the Sobre carry their own XML digital signatures. **All of that happens on your side, with your private key, which never leaves your side.**

This server does **not** sign and does **not** store anything. You hand it the *finished, WS-Security-signed SOAP envelope* (base64); it adds the `SOAPAction` header, POSTs it to the chosen DGI endpoint, and translates the DGI acknowledgement. This is the same "you sign, we forward" model as the sister Saudi ZATCA and Costa Rica Hacienda servers.

> This mirrors how DGI itself behaves: an **unsigned** POST to the live ePrueba endpoint is rejected with a DGI-signed SOAP Fault — `<Detalle>No signature in message!</Detalle>`. The signature is mandatory and is yours to produce.

## Tools

| Tool | DGI operation | What it does |
|------|---------------|--------------|
| `submit_sobre` | `EFACRECEPCIONSOBRE` | Submit a Sobre (envelope of signed CFEs). Input `signed_soap_envelope` (base64). Returns `estado` (AS accepted / BS rejected), `motivos_rechazo`, `consulta_token` + `consulta_fechahora`. |
| `submit_reporte_diario` | `EFACRECEPCIONREPORTE` | Submit the mandatory Reporte Diario. Same signed-envelope input. |
| `query_envio_status` | `EFACCONSULTARESTADOENVIO` | Query a submission status / fetch the 2nd message. Read-only at DGI. |
| `build_cfe_envelope` | — (local) | Wrap your signed inner XML into the exact SOAP Body to WS-Security-sign. No network, no signing. |
| `calc_iva` | — (local) | Compute CFE `MontosTotales` (IVA Tasa Básica 22% / Tasa Mínima 10% / Exento). No network. |
| `get_dgi_info` | — (local) | Reference: endpoints, operations + SOAPActions, `TipoCFE` codes, IVA rates, namespaces. |

### Typical flow

1. `calc_iva` → get the CFE `MontosTotales`.
2. Build and sign the CFE, build and sign the Sobre (merchant-side).
3. `build_cfe_envelope` → get the exact SOAP Body.
4. WS-Security-sign that envelope with your certificate, base64-encode it (merchant-side).
5. `submit_sobre` → forward. On `estado AS`, keep the returned `consulta_token`.
6. `query_envio_status` later → fetch the per-CFE 2nd message. Send the daily report with `submit_reporte_diario`.

## Configuration (headers, per-request, nothing stored)

- `x-dgi-mode`: `test` (default — DGI **ePrueba** sandbox, no fiscal effect, **verified live**) · `homologacion` · `produccion`.
- `x-dgi-endpoint`: an explicit `https://` DGI webservice URL (overrides `x-dgi-mode`).
- `x-agentpay-allowed-tools`: owner-set tool allow-list (the agent cannot relax it).

### Endpoints

| Mode | URL | Status |
|------|-----|--------|
| `test` | `https://efactura.dgi.gub.uy:6443/ePrueba/ws_eprueba` | **Verified live** (200 WSDL + signed fault on unsigned POST, 2026-07-10) |
| `homologacion` | `https://efactura.dgi.gub.uy:6470/eHomologacion/ws_ehomologacion` | Confirm port/path against your DGI onboarding |
| `produccion` | `https://efactura.dgi.gub.uy:6463/eFactura/ws_efactura` | Documented prod URL — **confirm against your DGI onboarding before going live** (this port was not reachable from the build sandbox) |

## Do I need to be a "Proveedor Habilitado"?

**No.** The *Registro de Proveedor Habilitado* is DGI's **optional** simplified-onboarding scheme for **commercial software vendors** — it requires being declared a software provider by **at least five** electronic issuers and holding the software-vendor activity codes (46510 / 62010 / 62020 / 63110). A merchant issuing its **own** CFEs onboards through the ordinary *ingreso al régimen* as an *emisor electrónico* with its own software; no vendor registration is required. This server is only a transport layer for documents you have already signed.

## Honest limitations / boundaries

- **We never sign.** If your envelope lacks a WS-Security signature, DGI rejects it (`No signature in message!`); the server surfaces this and blocks an obviously-unsigned envelope before it even reaches the network.
- **Amount policy cap is not enforced on submit.** The submitted envelope is an opaque signed blob; the grand total lives in each CFE's `MontosTotales` inside the signed body. Apply `x-agentpay-max-amount` logic at the `calc_iva` / build stage (pre-sign). The tool allow-list guardrail *does* apply to every call.
- **`test` is the only endpoint verified live from here.** `homologacion` / `produccion` URLs are the documented DGI ones but must be confirmed against your onboarding materials (or overridden with `x-dgi-endpoint`).
- **`calc_iva` covers the common Básica/Mínima/Exento breakdown**, not every special indicator (exports/assimilated, perceptions, etc.).

## Develop / test

```bash
npm run dev    # local server on http://localhost:3245
npm test       # e2e: protocol + IVA math + local helpers + validation + policy + LIVE DGI ePrueba assertions
```

The e2e suite hits the real DGI ePrueba endpoint: it asserts the WSDL is 200 with the three operations and that a fake-signed envelope round-trips to a DGI SOAP Fault (endpoint alive + fault passthrough).

## Safety

Stateless forwarder. The signed SOAP envelope travels per-request and is never stored; no credentials, documents, or customer data are persisted. Privacy: https://inv-uy.wishpool.app/privacy

## Family

Invoices: Saudi ZATCA (`inv-sa`), Chile DTE (`inv-cl`), Mexico CFDI 4.0 (`inv-mx`), Peru CPE (`inv-pe`), Brazil NF-e (`inv-br`), India GST (`inv-in`). Local payments in 81 countries — https://mcp.wishpool.app.