# 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):

```bash
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

```bash
npx -y @reneturcios/invoiceproof mcp
```

MCP client config:

```json
{
  "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

```bash
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

```bash
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`.