invoiceproof

invoiceproof

invoiceproof is a thin local bridge to the eInvoiceChecker hosted MCP server, a service for working with European electronic invoices. It can tell you which formats are supported, identify an invoice you hand it, extract its contents as normalised JSON, check it against the official rule set for its format, repair the deterministic errors it finds, and render the document as HTML or PDF.

The bridge holds no invoice logic and validates nothing itself. It serves the upstream server's tool list locally — exactly as captured from the live endpoint — and forwards each tool call upstream, returning the result untouched. Coverage spans XRechnung, ZUGFeRD and Factur-X, Peppol BIS, KSeF, and the other formats and national rule sets the upstream supports.

Tools

No tool declares a required field; the invoice goes in as content (XML text) or content_base64 (a ZUGFeRD / Factur-X PDF or other file), both optional in the captured schemas.

• list_supported_formats — which formats, profiles and rule sets the service supports, and what each tool costs. No arguments.
• detect_invoice — identify the format, syntax, profile/customisation and country standard of an invoice file. The cheap first step before validating.
• parse_invoice — extract the invoice as normalised JSON: number, dates, seller, buyer, lines, VAT breakdown, totals and payment details.
• fix_invoice — deterministically repair validation errors of an EN 16931 invoice: empty elements, decimals, date and code formats, specification ids; with totals: true it also recalculates totals and the VAT breakdown from the lines. Data missing from the file can be supplied under values; anything still missing is listed in needs_input. dry_run reports changes without applying them. Counts as 2 requests upstream.
• validate_invoice — run the official rule set for the detected format and return every failed rule with id, severity, message and XPath. kosit: false skips the full KoSIT schematron for a faster, schema-and-core-only check.
• render_invoice_html — a human-readable invoice document in HTML (A4 print layout), with label language selectable via lang (en, de, fr, pl, nl, hr, es).
• render_invoice_pdf — the same document as a PDF, returned as a base64 resource, with the same lang choices. Counts as 2 requests upstream.
• my_usage — the plan, monthly quota, usage this month and subscription state of the API key used for the connection. Free. No arguments.

Configuration

• EINVOICECHECKER_API_KEY (optional) — when set, every upstream request carries Authorization: Bearer <key>. When it is not set, no auth header is sent and the upstream's anonymous rate limit applies. The key is never required by this client.
• EINVOICECHECKER_MCP_URL (optional) — override the upstream endpoint. Defaults to https://einvoicechecker.com/v1/mcp. (The override hook is this rebuild's own labelled reconstruction.)

Forwarding mechanics

On the first tool call the client opens a streamable HTTP session with the upstream: a JSON-RPC initialize request (protocolVersion 2025-03-26, clientInfo name invoiceproof), then a notifications/initialized notification, then the tools/call request carrying the caller's arguments unchanged. When the upstream answers initialize with an Mcp-Session-Id header, that value rides on every later request of the session, which is reused for the life of the process. Replies may arrive as plain JSON or as server-sent events; both are read.

Successful upstream results pass through verbatim, including any isError flag the upstream sets. Failures — a JSON-RPC error, a non-2xx status, an unreadable response, or a request that cannot be completed — come back as an isError result whose text starts with invoiceproof error: (this rendering is this rebuild's own labelled reconstruction).

CLI

Each tool is also a subcommand taking one JSON argument string (omit it for tools that take none):

npx @reneturcios/invoiceproof list_supported_formats
npx @reneturcios/invoiceproof validate_invoice '{"content":"<Invoice>...</Invoice>"}'
npx @reneturcios/invoiceproof render_invoice_html '{"content":"<Invoice>...</Invoice>","lang":"de"}'
npx @reneturcios/invoiceproof --version

Exit codes: 0 on success, 1 on an isError result, 2 on a usage error.

MCP server

npx -y @reneturcios/invoiceproof mcp

MCP client config:

{
  "mcpServers": {
    "invoiceproof": {
      "command": "npx",
      "args": ["-y", "@reneturcios/invoiceproof", "mcp"]
    }
  }
}

To run the MCP server with an API key, add EINVOICECHECKER_API_KEY to the client's env block for this server.

Docker

docker run -i ghcr.io/cloudcorprecords/invoiceproof
docker run --rm ghcr.io/cloudcorprecords/invoiceproof --version

The container's default command is mcp, so the first form is a stdio MCP server; any other arguments reach the CLI normally.

Development

npm install
npm run build
npm test
npm run dev

The test suite runs entirely against a stubbed JSON-RPC upstream — no live network calls.

License

MIT — see LICENSE.