mcp-einvoicing-ae

# mcp-einvoicing-ae 🇦🇪

[English](README.md) | [العربية](README.ar.md)

<!-- mcp-name: io.github.cmendezs/mcp-einvoicing-ae -->

[![PyPI version](https://badge.fury.io/py/mcp-einvoicing-ae.svg)](https://badge.fury.io/py/mcp-einvoicing-ae)
[![Python](https://img.shields.io/pypi/pyversions/mcp-einvoicing-ae.svg)](https://pypi.org/project/mcp-einvoicing-ae/)
[![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0) [![mcp-einvoicing-ae MCP server](https://glama.ai/mcp/servers/cmendezs/mcp-einvoicing-ae/badges/score.svg)](https://glama.ai/mcp/servers/cmendezs/mcp-einvoicing-ae)

---

## Introduction

`mcp-einvoicing-ae` is an [MCP (Model Context Protocol)](https://modelcontextprotocol.io) server
that exposes tools for United Arab Emirates electronic invoicing. It is part of the
`mcp-einvoicing-*` family of country-specific servers, all built on
[`mcp-einvoicing-core`](https://github.com/cmendezs/mcp-einvoicing-core), which provides the
shared validation engine, EN 16931 abstractions, and Peppol network utilities.

Generated PINT AE invoices are structurally conformant: `cbc:UUID`, `cbc:ProfileExecutionID`,
per-line `cac:ItemPriceExtension`, and `trade_license_number` are all emitted, and round-trip
back through `parse_invoice_ae`. The 5.00% standard VAT rate is enforced by a model validator,
and a Peppol participant-lookup tool is exposed. `validate_invoice_ae` checks core's shared CEN
EN16931 base Schematron only, not the PINT AE jurisdiction overlay; `validate_tdd_ae` currently
reports "unavailable" — see [Supported standards](#supported-standards) and
[Available tools](#available-tools) below.

The UAE Peppol Authority's PINT AE (billing) specialization is at **Status: Final**, version
1.0.4 (2026-06-02); the Peppol AE Tax Data Document (TDD) is at Status: Final, version 1.0.4
(2026-07-23). Full citations: [`specs/README.md`](specs/README.md).

## Supported standards

- **PINT AE (billing)** — UBL 2.1, `CustomizationID: urn:peppol:pint:billing-1@ae-1`,
  `ProfileID: urn:peppol:bis:billing`. Version 1.0.4 (2026-06-02).
- **PINT AE (self-billing)** — `CustomizationID: urn:peppol:pint:selfbilling-1@ae-1`,
  `ProfileID: urn:peppol:bis:selfbilling`.
- **Peppol AE TDD** (Tax Data Document) — the 5th-corner reporting document sent to the FTA; its
  own XML namespace (`urn:peppol:schema:taxdata:1.0`), not a UBL invoice. Version 1.0.4
  (2026-07-23).

The UAE programme is a decentralized Peppol **5-corner** model routed through Accredited Service
Providers, adding a tax-authority reporting leg (the TDD above) beyond the 4-corner exchange used
elsewhere in this family. The invoice-tree pathway is confirmed `EN16931Invoice` (PINT AE is a
UBL 2.1 CIUS of EN 16931-1:2017) — no JSON binding was found in the supplied specifications.

`AEInvoice` serializes via `mcp_einvoicing_ae.wire_formats.AEUBLSerializer`, which layers the
AE-specific elements (`cbc:ProfileExecutionID`, `PartyLegalEntity/CompanyID` with
`schemeAgencyID="TL"` for `trade_license_number`) on top of core's `EN16931UBLSerializer` — the
latter now emits `cbc:UUID` (from `document_uuid`) and per-line `cac:ItemPriceExtension` natively
(`mcp-einvoicing-core` v1.25.0), since `profile`/`business_process` already hold the real Peppol
URNs. `AEParty.vat_id` carries the 15-digit TRN, format-validated via
`TaxIdentifier.validate_ae_trn()` (core v1.22.0); the Peppol participant ID (TIN) is auto-derived
as its first 10 digits. `AETaxDataDocument` models the TDD's mandatory fields but is not a UBL
invoice and is not built on `AEInvoice`. `parse_invoice_ae` re-extracts the AE-specific elements
from the raw XML and re-validates the result as `AEInvoice`, so parsing re-applies the same TRN
and tax-rate checks a fresh construction gets — see [Available tools](#available-tools) for
what's covered and what isn't. The TDD transport channel (same AS4 channel as the invoice, or a
separate one) remains an open documentation question, not a code gap. Full detail:
[`specs/README.md`](specs/README.md).

**Validation scope, as of v0.2.0:** `validate_invoice_ae` checks the CEN EN16931 base Schematron
only (structural + arithmetic/totals rules, shared with `mcp-einvoicing-be`/`mcp-ksef-pl`) — not
the PINT AE jurisdiction overlay (`ibr-*-ae` rules). `BR-CO-09` (VAT identifier must carry an ISO
3166-1 alpha-2 prefix) is expected to fire on every genuine AE invoice, since UAE TRNs carry no
country prefix; this is disclosed in every result, not a defect in your data. `validate_tdd_ae`
currently has no validation available at all. v0.1.0 bundled five self-compiled files derived
from OpenPeppol's PINT AE and TDD Schematron/XSD sources with no confirmed redistribution
rights — removed in v0.2.0. See [`CHANGELOG.md`](CHANGELOG.md).

## Installation

### Requirements

- Python ≥ 3.11
- [`mcp-einvoicing-core`](https://github.com/cmendezs/mcp-einvoicing-core) (installed
  automatically as a dependency)

### Using `uvx` (recommended)

```bash
uvx mcp-einvoicing-ae
```

### Using `uv`

```bash
uv add mcp-einvoicing-ae
```

### From source

```bash
git clone https://github.com/cmendezs/mcp-einvoicing-ae.git
cd mcp-einvoicing-ae
uv sync --all-extras
```

## Configuration

### Environment variables

| Variable | Required | Default | Description |
|---|---|---|---|
| `LOG_LEVEL` | No | `INFO` | Logging level: `DEBUG`, `INFO`, `WARNING`, or `ERROR` |

Country-specific variables (transport endpoints, credentials, environment switches) are added
once the specification documents them. See [`.env.example`](.env.example). This server needs no
credentials to run today.

## Claude Desktop integration

To use this server with Claude, add this configuration to your `claude_desktop_config.json` file:

```json
{
  "mcpServers": {
    "einvoicing-ae": {
      "command": "uvx",
      "args": ["mcp-einvoicing-ae"]
    }
  }
}
```

## Cursor integration

Cursor supports MCP servers via stdio. Add the configuration in:
- **Global** (all projects): `~/.cursor/mcp.json`
- **Project** (this repository only): `.cursor/mcp.json`

```json
{
  "mcpServers": {
    "einvoicing-ae": {
      "command": "uvx",
      "args": ["mcp-einvoicing-ae"]
    }
  }
}
```

Reload the Cursor window (`Ctrl+Shift+P` then *Reload Window*) to apply the changes.

## Kiro integration

Kiro supports MCP servers via its dedicated configuration file. Two levels are available:
- **Global** (all projects): `~/.kiro/settings/mcp.json`
- **Workspace** (this repository only): `.kiro/settings/mcp.json`

```json
{
  "mcpServers": {
    "einvoicing-ae": {
      "command": "uvx",
      "args": ["mcp-einvoicing-ae"],
      "disabled": false,
      "autoApprove": []
    }
  }
}
```

The file is automatically reloaded on save. You can also open the config via the command palette (`Cmd+Shift+P` / `Ctrl+Shift+P`) then *MCP*.

## Available tools

| Tool | Description |
|---|---|
| `generate_invoice_ae` | Generate a PINT AE UBL 2.1 invoice XML (billing or self-billing) from structured data via `AEUBLSerializer`. Emits every unconditionally-mandatory PINT AE element: `cbc:UUID`, `cbc:ProfileExecutionID`, per-line `cac:ItemPriceExtension`, and `PartyLegalEntity/CompanyID` (`trade_license_number`, when set). |
| `validate_invoice_ae` | Validate a PINT AE UBL 2.1 invoice against core's shared CEN EN16931 base Schematron (structural + arithmetic/totals rules only — not the PINT AE jurisdiction overlay). Requires the `xslt2` extra. |
| `validate_tdd_ae` | Always returns an explicit "unavailable" result — no licensed validation artifact is currently available for the Peppol AE Tax Data Document (TDD). |
| `parse_invoice_ae` | Parse a PINT AE UBL 2.1 invoice XML into a structured dict. Re-extracts `document_uuid`, `profile_execution_id`, and `trade_license_number` from the raw XML and re-validates the result as `AEInvoice` — TRN format and tax-rate/category checks are re-applied to parsed content, not just fresh constructions. |

Peppol participant lookup (core's `register_peppol_tools` plugin, TIN-based id adapter — scheme
`0235`, first 10 digits of the TRN):

| Tool | Description |
|---|---|
| `peppol_lookup_participant` | Check whether a business is registered on the Peppol network; returns registration status and supported document types |
| `peppol_get_service_endpoint` | Fetch the AS4 endpoint for a participant's document type |
| `resolve_peppol_dns` | DNS-only (SML) diagnostic, independent of SMP reachability |
| `peppol_send` | Transmit a UBL/CII invoice via AS4 |

`generate_invoice_ae`/`validate_invoice_ae`/`parse_invoice_ae` require `mcp-einvoicing-ae[xslt2]`
(bundles `saxonche`) for the base Schematron validator to load; without it, `validate_invoice_ae`
returns an explicit "unavailable" result rather than a silent pass.

The tool reference in [`docs/TOOLS.md`](docs/TOOLS.md) is generated from the running server:

```bash
uv run python scripts/gen_tool_reference.py
```

## Vendor neutrality

This server implements the standard itself: it builds, validates, and signs the document
locally. It is not a client for a commercial invoicing platform, and your signing keys and
credentials never leave your own infrastructure.

A Peppol access point is required for PINT AE / Peppol AE TDD, but any accredited access point
speaks the same AS4 profile, so switching providers is a configuration change, not a code
change.

## Contributing

See [CONTRIBUTING.md](CONTRIBUTING.md) for development setup, the test and lint commands, and
the pull request checklist. Security issues follow the private disclosure process in
[SECURITY.md](SECURITY.md).

## Other e-invoicing MCP servers

| Country | Server |
|---------|--------|
| 🌍 Global | [mcp-einvoicing-core](https://github.com/cmendezs/mcp-einvoicing-core) |
| 🇧🇪 Belgium | [mcp-einvoicing-be](https://github.com/cmendezs/mcp-einvoicing-be) |
| 🇧🇷 Brazil | [mcp-nfe-br](https://github.com/cmendezs/mcp-nfe-br) |
| 🇫🇷 France | [mcp-facture-electronique-fr](https://github.com/