invoiceproof

invoiceproof

invoiceproof 是连接到托管式 eInvoiceChecker MCP 服务的轻量本地桥接程序，该服务用于处理欧洲电子发票。它可以告知你支持哪些格式、识别你提交的发票、将其内容提取为规范化 JSON、依据相应格式的官方规则集检查发票、修复发现的确定性错误，并将文档渲染为 HTML 或 PDF。

该桥接程序不包含发票逻辑，也不自行执行验证。它在本地提供上游服务的工具列表——与从实时端点捕获的内容完全一致——并将每次工具调用转发到上游，原样返回结果。支持范围涵盖 XRechnung、ZUGFeRD 和 Factur-X、Peppol BIS、KSeF，以及上游支持的其他格式和国家规则集。

工具

没有工具声明必填字段；发票通过 content（XML 文本）或 content_base64（ZUGFeRD / Factur-X PDF 或其他文件）传入，在捕获的架构中，这两个字段都是可选的。

• list_supported_formats — 查询服务支持的格式、配置文件和规则集，以及每种工具的费用。无需参数。
• detect_invoice — 识别发票文件的格式、语法、配置文件／自定义项和国家标准。验证前的低成本第一步。
• parse_invoice — 将发票内容提取为规范化 JSON：编号、日期、卖方、买方、行项目、VAT 明细、总额和付款详情。
• fix_invoice — 确定性地修复 EN 16931 发票的验证错误：空元素、小数、日期和代码格式、规范标识符；设置 totals: true 后，还会根据行项目重新计算总额和 VAT 明细。可在 values 中提供文件缺失的数据；仍然缺失的内容会列在 needs_input 中。dry_run 会报告更改，但不实际应用。计为上游 2 次请求。
• validate_invoice — 对检测到的格式运行官方规则集，并返回每条未通过规则的 ID、严重程度、消息和 XPath。kosit: false 会跳过完整的 KoSIT schematron 检查，以更快地进行仅含架构和核心规则的检查。
• render_invoice_html — 生成便于阅读的 HTML 发票文档（A4 打印版式），可通过 lang 选择标签语言（en、de、fr、pl、nl、hr、es）。
• render_invoice_pdf — 将同一文档生成为 PDF，并以 base64 资源返回；可选的 lang 与上述相同。计为上游 2 次请求。
• my_usage — 查询连接所用 API 密钥的套餐、月度配额、本月用量和订阅状态。免费。无需参数。

配置

• EINVOICECHECKER_API_KEY（可选）— 设置后，每个上游请求都会携带 Authorization: Bearer <key>。未设置时，不会发送身份验证标头，并受上游匿名速率限制约束。此客户端不要求提供密钥。
• EINVOICECHECKER_MCP_URL（可选）— 覆盖上游端点。默认值为 https://einvoicechecker.com/v1/mcp。（此覆盖钩子是本次重建自行标注的还原内容。）

转发机制

首次调用工具时，客户端会与上游建立可流式传输的 HTTP 会话：先发送 JSON-RPC initialize 请求（protocolVersion 2025-03-26，clientInfo name invoiceproof），再发送 notifications/initialized 通知，然后发送携带调用方原始参数的 tools/call 请求。上游在 initialize 响应中返回 Mcp-Session-Id 标头时，该值会附加到此会话后续的每个请求中；会话会在进程整个生命周期内复用。响应可能是普通 JSON，也可能是服务器发送事件；客户端会读取这两种格式。

上游成功结果会原样透传，包括上游设置的任何 isError 标志。失败情况——JSON-RPC 错误、非 2xx 状态、无法读取的响应，或无法完成的请求——会以 isError 结果返回，文本以 invoiceproof error: 开头（此错误呈现方式是本次重建自行标注的还原内容）。

CLI

每个工具也是一个子命令，需要一个 JSON 参数字符串（不需要参数的工具可省略）：

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

退出代码：成功时为 0，结果为 isError 时为 1，用法错误时为 2。

MCP 服务

npx -y @reneturcios/invoiceproof mcp

MCP 客户端配置：

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

要使用 API 密钥运行 MCP 服务，请将 EINVOICECHECKER_API_KEY 添加到此服务的客户端 env 块中。

Docker

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

容器的默认命令是 mcp，因此第一种形式会启动 stdio MCP 服务；其他参数会照常传递给 CLI。

开发

npm install
npm run build
npm test
npm run dev

测试套件完全使用桩化的 JSON-RPC 上游运行，不会进行实时网络调用。

许可证

MIT — 详见 LICENSE。