Kontor MCP

Kontor MCP

面向 AI Agent 的自主电子发票工具包。 官方 XRechnung / EN 16931 验证，支持导入和导出 ZUGFeRD，100 % 离线，无需 API 密钥。

Kontor MCP 是一套本地离线工具箱，可让 AI 助手（Claude Desktop、Claude Code，以及任何 MCP 客户端）处理德国／欧盟电子发票：符合 EN 16931 标准的 XRechnung 和 ZUGFeRD/Factur-X。它可以读取发票（纯 XML 或嵌入 PDF 的 XML）、依据官方 KoSIT / EN 16931 规则手册进行检查、用德语或英语解释晦涩的错误、创建有效的新发票（XML 或 ZUGFeRD PDF/A-3）、在不同格式间转换，并告知企业适用哪些法律义务。其核心承诺是自主可控：不依赖云端、不需要 API 密钥、不进行网络调用、运行时无需 Java——并经过测试验证。

这很重要：从 2025 年起，德国所有企业都必须能够接收电子发票；从 2027/2028 年起，还必须能够开具电子发票。电子发票是经过验证的 XML，而不是 PDF；规则校验失败可能导致无法抵扣进项增值税。发票包含个人和银行数据，因此应当在数据所在之处——你的设备上——使用公共部门接收方所用的同一套规则进行检查。

Claude Desktop 搭配 kontor 服务：验证 → BR-DE-15（缺少 Leitweg-ID），并提供修复提示 · 解析 ZUGFeRD PDF · 解释 BR-DE-18。MP4

v1.0 — 8 个工具 · 4 类资源 · 3 个提示词 · KoSIT 一致性 89/89，并作为 CI 门禁强制执行 · ZUGFeRD PDF/A-3 输出经 veraPDF 和 Mustang 验证 · stdio 和 Streamable HTTP（Bearer 身份验证）· Docker 镜像（amd64/arm64）· kontor-agent 参考客户端 · 已列入官方 MCP 注册表。可通过 npx、Docker 或从源代码安装。

为什么选择 Kontor MCP

• 遵循官方规则，而非近似实现。 KoSIT XRechnung Schematron 和 CEN EN 16931 规则未经修改地运行（编译为 XSLT/SEF，由 Saxon-JS 执行），并采用 KoSIT 场景模型——所得判定与公共部门接收方一致，且已通过官方验证器逐文件验证。
• 从设计上确保自主可控。 纯 TypeScript/WASM，运行时无需 Java，不进行网络调用，不存储任何内容，也不记录日志。发票在哪里，就在哪里运行。
• 原生适用于 Agent。 每个工具都会返回结构化内容和易读摘要；检查结果包含德语／英语说明、受影响的业务术语及修复提示；生成结果如实报告（valid 为真实判定，绝不预设为有效）。
• 双向支持 ZUGFeRD。 可从任何 ZUGFeRD/Factur-X PDF 中读取嵌入的 XML；也可生成带有 factur-x.xml 的 PDF/A-3 发票，并通过 veraPDF 和 Mustang 验证。

五分钟快速入门

需要 Node ≥ 20。所有内容——规则、架构、代码列表、字体——均随 npm 包一起提供；运行时无需下载，也无需 Java。

安装方式	命令
npx（零配置 stdio）	npx -y @kontor-mcp/server
Docker（Streamable HTTP，需要令牌）	docker run -d -p 127.0.0.1:3333:3333 -e KONTOR_AUTH_TOKEN=… ghcr.io/dashankanadeeshandesilva/kontor-mcp
参考客户端	npx -y -p @kontor-mcp/client kontor-agent audit invoice.xml
从源代码安装	git clone … && pnpm install && pnpm build → node packages/server/dist/bin.js

Claude Desktop — 设置 → 开发者 → 编辑配置，然后退出（⌘Q）并重新打开：

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

（从源代码检出目录运行时，改用 "command": "node", "args": ["/absolute/path/to/kontor-mcp/packages/server/dist/bin.js"]。）

**Claude Code:**

```sh
claude mcp add kontor -- npx -y @kontor-mcp/server

现在审计一张示例发票。 向 Claude 提问：

审计 /absolute/path/to/kontor-mcp/packages/server/samples/broken-missing-buyer-reference.xml——它有效吗？

你会得到判定结果（invalid）、发现项 BR-DE-15（缺少买方引用 / Leitweg-ID）的说明和修复提示、重新计算的总额和增值税明细，以及附带理由的拒绝建议。接着试试 ZUGFeRD PDF：

/absolute/path/to/kontor-mcp/packages/server/samples/generated-zugferd-en16931.pdf 中有什么？

（如果愿意，也可以直接附加 XML 文件；PDF 必须通过本地路径引用——Claude Desktop 不会将 PDF 字节传递给 MCP 服务。）

没有聊天客户端时，可使用无界面的 MCP Inspector：

npx @modelcontextprotocol/inspector@latest --cli node packages/server/dist/bin.js \
  --method tools/call --tool-name audit_invoice \
  --tool-arg file_path=$PWD/packages/server/samples/broken-missing-buyer-reference.xml --tool-arg lang=en

kontor-agent CLI — 参考客户端；audit 无需大模型，并针对接受 / 复核 / 拒绝分别返回 0/1/2；chat 是 Anthropic Agent 循环，会打印每次工具调用（需要 ANTHROPIC_API_KEY）：

node packages/client/dist/bin.js audit packages/server/samples/broken-missing-buyer-reference.xml --lang en
node packages/client/dist/bin.js chat -m "Prüfe $PWD/packages/server/samples/valid-zugferd-en16931.pdf"
node packages/client/dist/bin.js --url http://127.0.0.1:3333/mcp --token "$KONTOR_AUTH_TOKEN" tools   # against Docker / HTTP

Docker / Streamable HTTP — 通过 HTTP 提供同一服务，供远程 Agent 和容器使用（需要令牌，端口仅发布到回环地址，TLS 由你的反向代理负责）：

docker build -t kontor-mcp .              # multi-stage, non-root, ~70 MB, amd64 + arm64
docker run -d -p 127.0.0.1:3333:3333 -e KONTOR_AUTH_TOKEN="$(openssl rand -hex 24)" kontor-mcp
curl -s http://127.0.0.1:3333/healthz     # {"ok":true,"name":"kontor-mcp",...}

或者运行 cp .env.example .env && docker compose up -d（根文件系统为只读，./invoices 挂载到 /data）。配置项和安全态势详见：packages/server/README.md、SECURITY.md。

工具

工具	功能
parse_invoice	检测格式（UBL / CII · EN 16931 · XRechnung 版本及变体 · ZUGFeRD 配置文件），并返回 EN 16931 语义模型
validate_invoice	执行 XSD + 官方 EN 16931 / XRechnung Schematron（KoSIT 场景）+ Kontor 合理性校验 → 返回 valid / valid_with_warnings / invalid，并附上说明性发现项
audit_invoice	为应付账款提供一次调用所需的信息：抬头事实、增值税明细、判定结果、分组发现项，以及附带理由的接受 / 复核 / 拒绝建议；通过 known_invoice_numbers 无状态检测重复项
generate_invoice	结构化数据 → XRechnung 3.0 (UBL) 或 ZUGFeRD 2.3 / Factur-X PDF/A-3（target: zugferd-pdf，配置文件为 EN16931 / BASIC / EXTENDED）；金额采用安全的十进制计算，执行内部校验，并报告确定性的自动修复
convert_invoice	ZUGFeRD PDF → XML，通过语义模型进行 UBL ↔ CII 转换（转换后校验，并如实报告信息损失），生成自包含 HTML 预览
check_obligations	德国电子发票强制规定决策树（B2B/B2G/B2C，2025 → 2028 过渡期，豁免情况），并提供一手法律来源
explain_rule	提供任何 BR-* / BR-DE-* / KONTOR-* 规则 ID 对应的官方文本、说明、受影响的业务术语和修复提示
list_capabilities	格式、随包提供的标准版本、知识库统计、法律信息的 lastVerified、清单和主权声明

资源：kontor://samples/{name}、kontor://reference/rules、kontor://reference/codelists/{list}、kontor://reference/cheatsheet。提示词：audit-incoming-invoice、draft-supplier-rejection、create-invoice-interview。包含输入和约定的完整参考文档：packages/server/README.md。

主权性——以及我们如何证明这一点

声明	证明
运行时不联网	每套规则、架构、代码列表和法律事实都打包在 @kontor-mcp/rules 中，并附有来源信息和校验和。sovereignty.test.ts 为此提供证明：运行每个工具、资源和提示词时，所有出站路径（套接字、DNS、TLS、http/https、fetch）均会被拦截并记录——尝试次数为零；静态扫描仅允许在入站 HTTP 主机中导入网络模块；CI 还会在 --network none 容器中运行完整审计。详见 SECURITY.md。
不使用 Java，不含原生代码	Schematron 在构建时编译，并通过 Saxon-JS 执行；XSD 使用 xmllint-wasm；PDF 使用 pdf-lib。Java 仅用于 CI 中开发阶段的参考验证工具（KoSIT validator、veraPDF、Mustang）。
不存储任何内容，不记录任何日志	服务是无状态的；发票内容绝不会写入日志（KONTOR_LOG_PAYLOADS 默认关闭）。
判定结果与官方结果一致	docs/CONFORMANCE.md：官方 XRechnung 测试套件的 89/89 个文件，其判定结果和发现项均与 KoSIT validator 完全一致，并在每次 CI 运行时重新验证。
PDF 确实符合 PDF/A-3	每个生成的示例都会在 CI 中重新生成，并由 veraPDF（PDF/A-3b，零违规）和 Mustang CLI（PDF/A + XMP + 配置文件 XSD + EN 16931 规则）检查。

架构

flowchart LR
  subgraph client [MCP client]
    A[Claude Desktop / Claude Code / kontor-agent]
  end
  A -- stdio / Streamable HTTP --> S

  subgraph server ["@kontor-mcp/server"]
    S[tools · resources · prompts<br/>Zod schemas, structuredContent + text]
  end

  subgraph core ["@kontor-mcp/core (MCP-free library)"]
    D[detect] --> P[parse → EN 16931 model]
    P --> V[validate: XSD → Schematron → plausibility]
    P --> G[generate / convert / preview]
    G --> Z[ZUGFeRD PDF/A-3 assembly]
    V --> AU[audit → verdict + recommendation]
    O[obligations decision tree]
  end

  subgraph rules ["@kontor-mcp/rules (bundled, checksummed)"]
    R1[XSDs UBL 2.1 / CII D16B]
    R2[EN 16931 + XRechnung Schematron as SEF]
    R3[rule knowledge base DE/EN]
    R4[code lists · legal timeline · fonts + ICC]
  end

  S --> core
  core --> rules

验证流水线：第 1 层 XSD（xmllint-wasm）→ 第 2 层 官方 Schematron（Saxon-JS、KoSIT 场景选择和严重性覆盖）→ 第 3 层 Kontor 合理性检查（KONTOR-PLAUS-*：小数重新计算、增值税税率、IBAN/BIC、Leitweg-ID 校验位、日期、重复项——绝不改变官方判定结果）。金额计算仅使用 decimal.js；每次 XML 解析都会禁用 DTD/外部实体。

一致性

内容	参考标准	结果（2026-08-25）
验证判定结果和发现项	KoSIT validator 1.6.3、XRechnung 3.0.2 测试套件（86 个文件）+ Kontor 固定测试样例（3 个）	判定结果和发现项均 89/89 一致
生成的 ZUGFeRD PDF	veraPDF 1.30.2（PDF/A-3b）	6/6 通过，零违规
生成的 ZUGFeRD PDF	Mustang CLI 2.26.0（PDF/A + XMP + Factur-X 配置文件 XSD + EN 16931）	6/6 有效（EN 16931、BASIC、EXTENDED × DE/EN）
生成的 XRechnung	自有流水线（与上述参考实现一致），50 个随机输入	50/50 有效且合理

详细信息、命令和记录的报告：docs/CONFORMANCE.md。

软件包

软件包	用途
@kontor-mcp/core	不依赖 MCP 的库：检测、解析、验证、审计、生成、转换、ZUGFeRD PDF
@kontor-mcp/rules	打包的标准文件（XSD、编译后的 Schematron、代码列表、法律时间线、PDF 资源）+ 规则知识库
@kontor-mcp/server	MCP 服务（stdio 和带 bearer 身份验证的 Streamable HTTP；Docker 镜像），提供工具、资源和提示词
@kontor-mcp/client	kontor-agent——参考 MCP 客户端命令行工具：tools 检查、可编写脚本的 audit <file>（无需大模型，返回退出码）、带工具调用轨迹的 chat Anthropic Agent 循环；支持 stdio 或 HTTP

常见问题

这是法律或税务建议吗？ 不是。Kontor 会依据已发布的标准和法律时间表及其来源，报告正式和技术检查结果；由你自行作出决定。每条回答都附有此免责声明。

支持 XRechnung 3.0.2 / 2025 年规则吗？ 支持：XRechnung 3.0.2、Schematron 2.5.0、validator configuration 2026-01-31、EN 16931 1.3.16。版本已固定，并通过 list_capabilities 列出。

可以读取和写入哪些 ZUGFeRD 配置文件？ 读取：MINIMUM、BASIC WL、BASIC、EN 16931、EXTENDED、XRECHNUNG（来自 XMP 的配置文件）。写入：EN 16931（默认）、BASIC、EXTENDED——关于 BASIC 会丢弃哪些内容，请参阅 D-042。

可以从 Claude Desktop 向它发送 PDF 吗？ 请使用本地路径引用文件。桌面应用不会将附加的 PDF 字节传递给 MCP 服务；XML 附件则两种方式都可以。

KoSIT 的验证器是 Java 编写的，为什么这里不用 Java？ 为了确保自主可控并便于安装：Schematron 在构建时编译一次，然后使用 TypeScript（Saxon-JS）执行。Java 工具仅在 CI 中用作验证基准，以证明结果一致。

支持 Windows 吗？ 支持——CI 会在 Ubuntu、macOS 和 Windows 上使用 Node 20 和 22 运行完整测试套件。

开发

pnpm install
pnpm build
pnpm -r test
pnpm lint
pnpm artifacts        # fetch pinned third-party artefacts for the oracles (dev only)
pnpm oracle --diff …  # KoSIT parity (Java 17+)
pnpm check:zugferd    # regenerate samples, veraPDF + Mustang (Java + veraPDF)

提交 PR 前，请先阅读 CONTRIBUTING.md；安全问题请通过 SECURITY.md 反馈。

文档

• 产品需求 · 实施计划 · 决策日志
• 符合性 · 业务术语覆盖情况 · 制品来源
• v0.1 Claude Desktop 验证

许可证

Apache-2.0——有关捆绑的第三方组件（KoSIT 制品 Apache-2.0、EN 16931 制品 EUPL-1.2、Liberation Fonts OFL 1.1、ICC sRGB 配置文件），请参阅 LICENSE 和 NOTICE。