# Nigeria Invoice MCP 🇳🇬 — How can my AI agent issue a FIRS e-invoice (IRN) in Nigeria?

Remote MCP server that lets any AI agent issue **Nigeria e-invoices** — validating, signing and confirming invoices through **FIRS / NRS MBS** (the NRS **Merchant Buyer Solution** e-invoicing platform). FIRS signs the invoice **server-side** and returns the **IRN** (Invoice Reference Number), **CSID** (Cryptographic Stamp Identifier) and **QR code**. Stateless, bring-your-own credentials, never stores anything.

> **Honest status.** Each merchant enables e-invoicing on the NRS Merchant Buyer Solution and generates their own API key/secret in the NRSMBS Dashboard; this server is a pure forwarder (in-house / OEM path — not an APP/SI accreditation intermediary). The sandbox base URL is self-served from your Dashboard (send it via `x-firs-base-url`). This build is calibrated against the official FIRS MBS API surface and forwards correctly — fake-key probes reach the live gateway `api.firsmbs.com` and return its native error fingerprint — but **no real end-to-end signing run has been made yet**; the first real merchant with live credentials completes that verification. (Same honest posture as the India sister server.)

**Live endpoint:** `https://inv-ng.wishpool.app/mcp` · Registry: `app.wishpool/nigeria-invoice-mcp`

## Quick start

```json
{
  "mcpServers": {
    "nigeria-invoice": {
      "type": "http",
      "url": "https://inv-ng.wishpool.app/mcp",
      "headers": {
        "x-firs-api-key": "your-key",
        "x-firs-api-secret": "your-secret"
      }
    }
  }
}
```

Generate your API key and secret in your **NRSMBS Dashboard → API Integration**. Your business must first be enabled for e-invoicing on the NRS Merchant Buyer Solution. If your Dashboard issued a sandbox base URL, also send header `x-firs-base-url` (defaults to production `https://api.firsmbs.com/api/v1`).

## Tools

| Tool | What it does |
|---|---|
| `validate_invoice` | Pre-validate an invoice at FIRS / NRS MBS (`POST /invoice/validate`) **before** signing — returns pass, or the FIRS error list so you fix it before spending a submission. |
| `create_invoice` | Sign and submit the invoice (`POST /invoice/sign`). FIRS signs server-side and returns `irn` (IRN), `csid` (CSID) and `qr_code`. |
| `query_invoice` | Confirm a signed invoice by IRN (`GET /invoice/confirm/{irn}`) — transmission / delivery status. |

You send flat fields (`business_id`, supplier/customer `party_name` + `tin`, `invoice_number`, `service_id`, line items with `price`); the server builds the **UBL-mapped JSON** and computes VAT.

Owner policy guardrails ride optional headers (`x-agentpay-max-amount`, `x-agentpay-approval-above`, `x-agentpay-allowed-tools`) — set by the human owner in client config; the agent cannot relax them. The amount cap/threshold applies to the invoice total (NGN).

## IRN & VAT (computed for you)

- **IRN** = `InvoiceNumber-ServiceID-YYYYMMDD` (e.g. `ITW20853450-6997D6BB-20240703`). Pass `irn` directly, or let the server build it from `invoice_number` + `service_id` + `issue_date`.
- **VAT** at Nigeria's **7.5%** standard rate (override per line with `vat_rate`; use `0` for exempt/zero-rated). The server groups `tax_subtotal` by rate under `tax_category` id `VAT`, and fills `legal_monetary_total` (`line_extension_amount`, `tax_exclusive_amount`, `tax_inclusive_amount`, `payable_amount`).

Example: one line of ₦1000 × 2 @ 7.5% → net ₦2000, VAT ₦150, payable ₦2150.

## Develop

```bash
node test/serve.js   # local server on :3244
node test/e2e.js     # protocol + validation + VAT math unit check + fake-key live probe
```

## Safety

Pure stateless translation layer. FIRS / NRS MBS carries the validation and signing; the merchant's e-invoicing enablement and API credentials stay in the merchant's own NRSMBS account. Credentials travel per-request in headers, nothing is stored. [Privacy policy](https://inv-ng.wishpool.app/privacy).

## Sister servers

Mexico CFDI 4.0 e-invoices ([inv-mx.wishpool.app](https://inv-mx.wishpool.app)) and India GST e-invoices / IRN ([inv-in.wishpool.app](https://inv-in.wishpool.app)) are live. Local payments in 81 countries, one family: [mcp.wishpool.app](https://mcp.wishpool.app) · Taiwan e-invoice 電子發票 included. More invoice countries coming: Brazil NF-e · Chile DTE · Peru CPE · Poland KSeF · Romania e-Factura · Italy SdI.

MIT licensed.