facturas-inbox-mcp

facturas-inbox-mcp

一个 MCP 服务，可将西班牙商业文档文件夹转换为经过验证、结构化的数据，供 AI Agent 推理。它会为每份 PDF 分类（factura、rectificativa、ticket、nómina、modelo AEAT……），提取发票字段（NIF/CIF、应税基数、各税率的 IVA、IRPF、总额），检查算术结果和税号校验位，并计算一个季度的 IVA soportado / repercutido 情况。

本地运行，离线可用。无需 API 密钥。它只读取你指定的文件夹。

为西班牙 gestoría 的日常工作打造：客户将一个月的 PDF 放入文件夹后，就得有人弄清楚每份文件是什么、金额是否相符，以及 VAT 情况如何。

30 秒演示

Claude Code、Sonnet，指向合成的 examples/inbox（11 份文档，包括一份总额错误的文档、一张小票、一份贷项通知单、一张工资单、一份 modelo 303 和一页扫描件）。 实际会话；为缩短篇幅，答案经过删减（完整、未经编辑的对话记录见 docs/demo-transcript.md）：

> I'm the bookkeeper for Gestoría Demo Ficticia SL (CIF B87654323). Process the invoice
  inbox and tell me our IVA position for Q3 2026, and flag anything I need to look at
  by hand. Answer in English, briefly.

  ⏺ facturas - scan_folder {}
  ⏺ facturas - vat_summary {"own_tax_id":"B87654323","quarter":"2026-Q3"}
  ⏺ facturas - validate_tax_id {"tax_id":"B87654323"}

Q3 2026 IVA position: €243.00 to pay (a pagar), provisional.

- IVA repercutido: €504.00, from 1 issued invoice (GD-2026-0088, base €2,400 at 21%)
- IVA soportado: €261.00, from 4 received documents (base €1,400): €231 at 21% and
  €30 at 10%
- The July papelería invoice (€52.50 IVA) is cancelled out by the September credit note.

Check by hand:
1. Papelería PE-2026/0455 (30 Jul): the total says €1,250 but base + IVA comes to
   €1,210. Excluded. If the supplier corrects it, your position drops to about €33.
2. Gasolinera ticket 88213 (14 Aug, €60): IVA not broken out and no recipient NIF.
   Excluded. Probably not deductible without a full invoice.
3. Scanned PDF (5 Sep): no text layer, so it needs OCR or a manual read. It could be
   a missing Q3 invoice.
4. Credit note PE-2026/R-0019: classified at 0.69 confidence. Confirm it really is a
   rectificativa of PE-2026/0412.
5. Laura's advisory invoice (3 Aug): €150 IRPF withheld, which goes on modelo 111,
   not the IVA return.
   …

5 轮 · 23 秒 · $0.13。 每个数字都来自工具结果，而不是模型自行计算。未通过检查的文档会被排除并列出原因，不会在不知情的情况下被计入或丢弃。

工具

工具	功能	提示
scan_folder	为文件夹中的每份文档分类并提取信息；每份文档一行简洁记录，支持使用 limit / cursor 分页	只读
classify_document	为单份文档分类，并提供置信度分数及分类依据	只读
extract_invoice	发票编号、日期、开具方/接收方 NIF、应税基数、VAT 明细、IRPF、总额以及所有交叉检查结果。response_format: concise | detailed	只读
validate_tax_id	NIF / NIE / CIF 校验位验证。若校验失败，会指出预期的控制字符	只读
vat_summary	按税率汇总 quarter（2026-Q3）或 from/to 日期范围内的 IVA repercutido 与 soportado，并列出排除项	只读
export_csv	将扫描结果写入新的 .csv 文件（以 ; 分隔，使用逗号作为小数点，可直接在西班牙版 Excel 中打开）。绝不覆盖现有文件	写入新文件

每个工具都会发布 outputSchema 并返回 structuredContent，SDK 会验证这两个方向。所有工具都设置了完整的注解（readOnlyHint、destructiveHint: false、idempotentHint、openWorldHint: false），因此客户端可以自动批准只读工具。

检查项

只有通过所有检查时，extract_invoice 才会返回 status: "ok"：

检查	规则
issuer_tax_id	客户信息部分之前存在校验位有效的 NIF/NIE/CIF
issue_date	找到了有效的日历日期（15/07/2026、22 de septiembre de 2026 等）
vat_rate_standard	每个 VAT 税率都是西班牙税率（0、4、5、10、21 %）
vat_math	应税基数 × 税率 = VAT；如果发票按税率分别列出应税基数，则逐项检查（误差不超过 1 分）
irpf_math	应税基数 × IRPF 税率 = 预扣税额（误差不超过 1 分）
total_math	应税基数 + VAT − IRPF = 总额

所有算术计算均以整数分为单位。

安装

需要 Node.js 20.12 或更高版本。

30 秒快速体验（内置示例数据）

claude mcp add facturas-demo -- npx -y facturas-inbox-mcp --demo

--demo 会提供随包附带的合成收件箱。然后询问 Claude： “我是 CIF B87654323 的簿记员。我们 2026 年第三季度的 IVA 情况如何？有哪些内容需要我手动检查？”

Claude Code

claude mcp add facturas -- npx -y facturas-inbox-mcp ~/Documents/facturas

Claude Desktop

将以下内容添加到 claude_desktop_config.json（Settings → Developer → Edit Config）：

{
  "mcpServers": {
    "facturas": {
      "command": "npx",
      "args": ["-y", "facturas-inbox-mcp", "/Users/you/Documents/facturas"]
    }
  }
}

其他 MCP 客户端

这是一个标准的 stdio 服务：npx -y facturas-inbox-mcp <folder> [more folders…]，或 npx -y facturas-inbox-mcp --demo。文件夹也可以通过 FACTURAS_INBOX_DIRS 指定（分隔 方式与 PATH 相同）。

使用示例收件箱从源码运行

git clone https://github.com/pedrozapatadev/facturas-inbox-mcp && cd facturas-inbox-mcp
npm install && npm run build
claude mcp add facturas -- node "$PWD/dist/index.js" "$PWD/examples/inbox"

然后提问：“我是 CIF B87654323 的簿记员。我们 2026 年第三季度的 IVA 情况如何？”

若要在不使用大模型的情况下试用工具，请运行 npm run inspect（MCP Inspector）。

设计决策

• 核心逻辑确定，不内置模型。 Agent 本身已经是语言模型。它缺少的是值得信赖的工具。信息提取基于规则，且每个结果都附带证据：分类器信号、检查详情和警告。服务能够解释自身行为，同样的输入始终产生相同的输出。
• 错误要明确报告，不要悄悄忽略。 未找到的字段为 null，不会猜测。未通过检查的文档会从总额中排除，并列出排除原因。错误会以 isError 结果返回，并说明如何修复调用（“传入 force: true 以继续尝试”“先运行 OCR”）。
• 节省 Token。 scan_folder 返回精简行并支持分页。extract_invoice 默认简洁。export_csv 返回路径和计数，不返回数据。
• 文件系统受沙箱保护。 路径会通过 realpath 解析，且必须位于启动时指定的文件夹内，因此会拒绝 ../ 遍历和指向外部的符号链接（并有测试覆盖）。唯一的写入操作是 export_csv，它只会创建新的 .csv 文件，不会覆盖现有文件。
• 文档文本不可信。 服务指令会告知 Agent 切勿遵循文档中的指令。只有在收到请求时才会返回原始文本，并标记为 untrusted_text_preview。以 =、+、- 或 @ 开头的 CSV 单元格会经过处理，以防止电子表格公式注入。导出文件的权限为 0600。
• 限制每份文档的处理量。 文件大小上限为 20 MB，PDF 页数上限为 200 页。分析前，文本会截断至 1M 个字符。信息提取正则表达式的运行时间为线性，且有针对 ReDoS 情况的回归测试。
• 威胁模型。 攻击者可以控制文档内容，但不能控制文件系统。不存在的路径和位于指定文件夹之外的路径会返回相同错误，因此无法利用该工具探测其他位置的内容。已经拥有收件箱写入权限的用户可能在检查与读取之间制造竞态（TOCTOU 窗口）；这不在范围内。
• stdout 是协议。 所有日志都写入 stderr。端到端测试会通过真实的 stdio 驱动构建后的二进制文件，任何多余的 console.log 都会导致测试失败。

限制

诚实界定范围。这是一个展示规模的工具，不是会计软件。

• PDF 需要文本层。 扫描图像会标记为 unreadable，并提示使用 OCR（例如 ocrmypdf）；工具没有内置 OCR。
• 启发式信息提取针对常见的西班牙发票版式进行优化（带标签的字段，如 Base imponible、IVA 21 %、Total factura）。遇到不常见的版式时，会标记为 needs_review，而不是返回错误结果。
• **暂不支持：**等价附加税、欧盟内部／反向征收发票、Facturae XML 和交易对方名称（仅支持税号）。
• **仅进行校验和验证。**有效的 NIF 格式正确，但这并不能确认其已在 AEAT 或 VIES 注册。
• **不是电子发票或 VeriFactu 工具。**它读取收到的单据，不会开具发票或提交申报。vat_summary 是供审核的暂估数据，不是 modelo 303。

开发

npm install
npm run fixtures    # regenerate examples/inbox (synthetic data, valid-checksum fictional IDs)
npm run typecheck
npm test            # unit + in-memory MCP client + stdio end-to-end (build first for the e2e)
npm run build
npm run inspect     # MCP Inspector UI against the sample inbox

src/
  index.ts        stdio entry point, CLI args → allowed folders
  server.ts       the six tools: schemas, annotations, error mapping
  schemas.ts      zod input/output schemas
  pipeline.ts     read → classify → extract, shared by all tools
  classify.ts     rule-based document classifier with explainable signals
  extract.ts      invoice field extraction + arithmetic checks
  taxid.ts        NIF / NIE / CIF validation
  amounts.ts      Spanish amounts and dates, in integer cents
  vat-summary.ts  repercutido / soportado aggregation
  documents.ts    sandboxed filesystem + PDF text extraction
  csv.ts          Excel-friendly CSV export
test/             MCP-level tests (in-memory client, stdio e2e, sandbox escapes)

基于官方的 MCP TypeScript SDK v2（@modelcontextprotocol/server）、zod 和 unpdf 构建。

发布

1. 更新 package.json 中的 version，以及 server.json 中的两个 version 字段。
2. 运行 npm publish（会先运行构建和测试；需要启用 npm 2FA）。
3. 运行 gh workflow run publish-mcp-registry.yml，通过 GitHub OIDC（无需密钥）在 MCP Registry 中列出新版本。

路线图

• 为扫描文档提供可选的 OCR 处理
• 交易对手名称、recargo de equivalencia、欧盟内部发票
• Facturae XML 输入
• 将 VIES 查询作为可选工具，并明确标示其网络访问属性
• 支持远程部署的可流式 HTTP 传输

许可证

MIT © 2026 Pedro Zapata Medal。所有示例文档均为合成内容：公司、人员和税号均为虚构。