InvoiceIn

Official

by peculiar-systems

Overview Schema Source Related Servers Score Discussions Admin

Python

Remote

Read invoice

read_invoice

Read-onlyIdempotent

Parse European e-invoices into EN 16931 JSON and validate against official rules. Returns validation report with fix hints; accepts file path or base64.

Instructions

Parse one European e-invoice into canonical EN 16931 JSON and validate it against the official rule sets in the same call. Use it when you need the invoice content (seller, buyer, lines, totals, payment) together with the verdict; use validate_invoice for a verdict-only answer, invoice_to_html / invoice_to_csv / invoice_to_datev for renderings. Input: XML (UBL, CII, XRechnung, Peppol BIS 3, FatturaPA, KSeF FA(2)/FA(3)) or a ZUGFeRD/Factur-X hybrid PDF up to 25 MB; plain or scanned PDFs without embedded XML are rejected (no OCR). Returns the parsed invoice, the validation report with fix hints in lang, and timings; an unreadable file returns ok=false with error.code/message/hint instead of raising. A FatturaPA lot returns only its first invoice, with a note. Costs one invoice credit per call; without an API key the anonymous quota is 20 invoices per day per IP. Nothing is stored.

Input Schema

TableJSON Schema

Name	Required	Description	Default
`lang`	No	Language of the fix hints in the validation report and of the labels in HTML output. Default en.	en
`path`	No	Absolute path of the invoice file on the machine running the server, used instead of file_base64. Only honoured over stdio (`python -m invoicein.mcp_server`); the hosted server at invoicein-api.peculiar.systems ignores it and answers with an error asking for file_base64.
`file_base64`	No	Invoice file content, base64-encoded (standard alphabet). Accepted content: XML in UBL 2.1, CII D16B, XRechnung, Peppol BIS Billing 3, FatturaPA 1.2 or KSeF FA(2)/FA(3) syntax, or a ZUGFeRD 1.0/2.x or Factur-X hybrid PDF (the embedded XML is used). Max 25 MB decoded. Required unless `path` is given.

Output Schema

TableJSON Schema

Name	Required	Description
`ok`	Yes	False when the file could not be read; then only `error` is set
`note`	No	Set when the file is a lot of several invoices: only the first is returned
`error`	No	Present when ok is false: code, message, hint
`source`	No	Detected syntax, format, profile and container
`invoice`	No	Canonical EN 16931 JSON: document, seller, buyer, lines, tax_breakdown, totals, payment, attachments, extensions; field names carry BT/BG numbers in /v1/schema
`timings_ms`	No	Processing time per stage: detect, map, validate, total
`validation`	No

Schema Changelog

Changes observed during successful MCP inspections.

Changed18 schema fields changedv0.1.1Sep 8, 2026

addedInput schema / properties / file_base64 / default
```
Added value: +""
```

addedInput schema / properties / file_base64 / description

Added value: +"Invoice file content, base64-encoded (standard alphabet). Accepted content: XML in UBL 2.1, CII D16B, XRechnung, Peppol BIS Billing 3, FatturaPA 1.2 or KSeF FA(2)/FA(3) syntax, or a ZUGFeRD 1.0/2.x or Factur-X hybrid PDF (the embedded XML is used). Max 25 MB decoded. Required unless `path` is given."

addedInput schema / properties / lang / description

Added value: +"Language of the fix hints in the validation report and of the labels in HTML output. Default en."

addedInput schema / properties / lang / enum

Added value: +[
+  "en",
+  "de",
+  "pl",
+  "it",
+  "fr"
+]

addedInput schema / properties / path

Added value: +{
+  "default": "",
+  "description": "Absolute path of the invoice file on the machine running the server, used instead of file_base64. Only honoured over stdio (`python -m invoicein.mcp_server`); the hosted server at invoicein-api.peculiar.systems ignores it and answers with an error asking for file_base64.",
+  "title": "Path",
+  "type": "string"
+}

removedInput schema / required
```
Removed value: -[
-  "file_base64"
-]
```

addedOutput schema / $defs

Added value: +{
+  "Issue": {
+    "additionalProperties": true,
+    "properties": {
+      "field": {
+        "anyOf": [
+          {
+            "type": "string"
+          },
+          {
+            "type": "null"
+          }
+        ],
+        "default": null,
+        "description": "Affected canonical field with its EN 16931 BT/BG number",
+        "title": "Field"
+      },
+      "hint": {
+        "anyOf": [
+          {
+            "type": "string"
+          },
+          {
+            "type": "null"
+          }
+        ],
+        "default": null,
+        "description": "Plain-language explanation of what the sender must fix, in the requested language",
+        "title": "Hint"
+      },
+      "id": {
+        "description": "Rule id, e.g. BR-CO-15, BR-DE-2, PEPPOL-EN16931-R040, XSD-UNEXPECTED-ELEMENT",
+        "title": "Id",
+        "type": "string"
+      },
+      "message": {
+        "description": "The rule's own message",
+        "title": "Message",
+        "type": "string"
+      },
+      "severity": {
+        "description": "error, warning or info",
+        "title": "Severity",
+        "type": "string"
+      },
+      "who": {
+        "anyOf": [
+          {
+            "type": "string"
+          },
+          {
+            "type": "null"
+          }
+        ],
+        "default": null,
+        "description": "Who has to act: sender or receiver",
+        "title": "Who"
+      }
+    },
+    "required": [
+      "id",
+      "severity",
+      "message"
+    ],
+    "title": "Issue",
+    "type": "object"
+  },
+  "SourceInfo": {
+    "additionalProperties": true,
+    "properties": {
+      "container": {
+        "description": "xml or pdf",
+        "title": "Container",
+        "type": "string"
+      },
+      "format": {
+        "description": "Detected format: xrechnung-ubl, xrechnung-cii, ubl, cii, peppol-bis3, zugferd, facturx, fatturapa, ksef-fa3, ksef-fa2",
+        "title": "Format",
+        "type": "string"
+      },
+      "profile": {
+        "anyOf": [
+          {
+            "type": "string"
+          },
+          {
+            "type": "null"
+          }
+        ],
+        "default": null,
+        "description": "Profile or specification, e.g. 'EN 16931', 'XRechnung 3.0', 'FA (3)'",
+        "title": "Profile"
+      },
+      "syntax": {
+        "description": "UBL, CII, FatturaPA or FA3",
+        "title": "Syntax",
+        "type": "string"
+      }
+    },
+    "required": [
+      "syntax",
+      "format",
+      "container"
+    ],
+    "title": "SourceInfo",
+    "type": "object"
+  },
+  "Validation": {
+    "additionalProperties": true,
+    "properties": {
+      "errors": {
+        "description": "Number of failed rules with severity error",
+        "title": "Errors",
+        "type": "integer"
+      },
+      "issues": {
+        "description": "Failed rules, each with a fix hint",
+        "items": {
+          "$ref": "#/$defs/Issue"
+        },
+        "title": "Issues",
+        "type": "array"
+      },
+      "notes": {
+        "description": "Informational notes about the validation run",
+        "items": {
+          "type": "string"
+        },
+        "title": "Notes",
+        "type": "array"
+      },
+      "rule_sets": {
+        "description": "Rule sets applied, with versions (XSD, EN 16931, XRechnung, Peppol, FatturaPA, KSeF, arithmetic)",
+        "items": {
+          "additionalProperties": true,
+          "type": "object"
+        },
+        "title": "Rule Sets",
+        "type": "array"
+      },
+      "valid": {
+        "description": "True when no rule of severity error failed",
+        "title": "Valid",
+        "type": "boolean"
+      },
+      "warnings": {
+        "description": "Number of failed rules with severity warning",
+        "title": "Warnings",
+        "type": "integer"
+      }
+    },
+    "required": [
+      "valid",
+      "errors",
+      "warnings",
+      "rule_sets",
+      "issues"
+    ],
+    "title": "Validation",
+    "type": "object"
+  }
+}

addedOutput schema / additionalProperties
```
Added value: +true
```

addedOutput schema / properties / error

Added value: +{
+  "anyOf": [
+    {
+      "additionalProperties": true,
+      "type": "object"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null,
+  "description": "Present when ok is false: code, message, hint",
+  "title": "Error"
+}

addedOutput schema / properties / invoice

Added value: +{
+  "anyOf": [
+    {
+      "additionalProperties": true,
+      "type": "object"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null,
+  "description": "Canonical EN 16931 JSON: document, seller, buyer, lines, tax_breakdown, totals, payment, attachments, extensions; field names carry BT/BG numbers in /v1/schema",
+  "title": "Invoice"
+}

addedOutput schema / properties / note

Added value: +{
+  "anyOf": [
+    {
+      "type": "string"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null,
+  "description": "Set when the file is a lot of several invoices: only the first is returned",
+  "title": "Note"
+}

addedOutput schema / properties / ok

Added value: +{
+  "description": "False when the file could not be read; then only `error` is set",
+  "title": "Ok",
+  "type": "boolean"
+}

removedOutput schema / properties / result

Removed value: -{
-  "title": "Result",
-  "type": "string"
-}

addedOutput schema / properties / source

Added value: +{
+  "anyOf": [
+    {
+      "$ref": "#/$defs/SourceInfo"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null,
+  "description": "Detected syntax, format, profile and container"
+}

addedOutput schema / properties / timings_ms

Added value: +{
+  "anyOf": [
+    {
+      "additionalProperties": {
+        "type": "number"
+      },
+      "type": "object"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null,
+  "description": "Processing time per stage: detect, map, validate, total",
+  "title": "Timings Ms"
+}

addedOutput schema / properties / validation

Added value: +{
+  "anyOf": [
+    {
+      "$ref": "#/$defs/Validation"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null
+}

changedOutput schema / required

Previous value: -[
-  "result"
-]New value: +[
+  "ok"
+]

changedOutput schema / title

Previous value: -"read_invoiceOutput"New value: +"ReadResult"

First observedv0.1.0Sep 8, 2026

TDQS

A4.6/5.0

Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already indicate readOnly, idempotent, and non-destructive behavior. The description adds significant behavioral context beyond these: cost per call, anonymous quota limits, no storage guarantee, path handling differences between stdio and hosted server, and handling of FatturaPA lots (returns only first invoice with a note). These details give the agent a complete picture of side effects and constraints.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is long but structured and efficient. Each sentence adds a distinct piece of information: purpose, usage alternatives, input details, output details, FatturaPA special case, cost/quota, and storage. There is no redundancy, and the most critical information (purpose and when to use) is front-loaded in the first two sentences. A slightly more compact wording could be possible, but nothing is extraneous.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's complexity (multiple input formats, validation, detailed output, error handling, cost, quota, storage), the description covers all relevant aspects. It specifies accepted formats, file size limits, path vs base64 input, output components (parsed invoice, validation report, timings), and error behavior. The existence of an output schema (not shown but present) means return values do not need to be explained in the description.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100% (3/3 parameters have detailed descriptions explaining purpose, defaults, and constraints). The description itself does not add parameter-level information beyond what the schema already provides. Since schema coverage is high, the baseline score of 3 applies, and no additional parameter clarification is needed.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's core function: 'Parse one European e-invoice into canonical EN 16931 JSON and validate it against the official rule sets.' It also distinguishes itself from sibling tools by explicitly mentioning alternatives (validate_invoice for verdict-only, invoice_to_html/csv/datev for renderings), making the tool's unique purpose unambiguous.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides explicit guidance on when to use this tool ('Use it when you need the invoice content together with the verdict') and when not to (suggests alternatives). It also details input methods (path vs file_base64), constraints (max 25 MB, accepted formats), and error behavior (returns ok=false instead of raising), covering all practical usage aspects.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Install Server