three-way-match

三方供应商发票匹配 MCP 服务

在 Claude 或其他 MCP 客户端中，将供应商发票与其采购订单和收货凭证进行核对。此本地服务会将每个精确 SKU、单价和开票数量，与采购订单、累计验收收货量以及你提供的已开票数量进行比较。即使发票和采购订单的总金额一致，它也能发现相互抵消的 SKU 错误，并返回每项异常背后的来源数值。请提供结构化文档；此服务不会提取 PDF、执行 OCR、连接 ERP、支付款项或批准发票。

由 theluckystrike 开发。MIT 许可。支持邮箱：[email protected]。

安装

Claude Desktop：下载 three-way-match.mcpb v0.22.8 并打开。SHA-256：6397928ec44ea9d5c406a66f4eb7aa9a2f34f5731bf8ef9972fadfdac882f040。其他客户端可参照下方的源代码说明。

需要 Node.js 18 或更高版本。请从源代码检出目录构建；npm 包尚未发布。运行免费工具无需 API 密钥或账户。

git clone https://github.com/theluckystrike/mcp-servers.git
cd mcp-servers
npm install
node scripts/bootstrap-timezone.mjs
npm run build --workspace @theluckystrike/mcp-license
npm run build --workspace @theluckystrike/mcp-three-way-match

请使用检出目录中 servers/three-way-match/dist/index.js 的绝对路径。此服务使用 stdio 通信；由 MCP 客户端启动。请勿用 HTTP URL 替代该路径。

Claude Desktop：将此条目合并到 macOS 上 ~/Library/Application Support/Claude/claude_desktop_config.json 的 mcpServers 中（Windows 上为 %APPDATA%\Claude\claude_desktop_config.json），并将 /absolute/path 替换为你的检出目录位置：

{
  "mcpServers": {
    "three-way-match": {
      "command": "node",
      "args": ["/absolute/path/mcp-servers/servers/three-way-match/dist/index.js"]
    }
  }
}

Claude Code：

claude mcp add three-way-match -- node /absolute/path/mcp-servers/servers/three-way-match/dist/index.js

Cursor：将相同的 JSON 合并到项目中的 .cursor/mcp.json 或 ~/.cursor/mcp.json。重启客户端，调用 license_status，然后运行下方示例。仅有 tools/list 结果并不能验证匹配功能。

对于 Claude Desktop，下载 three-way-match.mcpb 并打开以进行安装。SHA-256：6397928ec44ea9d5c406a66f4eb7aa9a2f34f5731bf8ef9972fadfdac882f040。这是本地 stdio 服务；没有托管端点。

工具

工具	参数和结果
three_way_match	采购订单、收货凭证、发票、必需的 prior_invoiced、可选的 save；返回完整报告和保存结果。
report_list	可选的 offset（0）、limit（20，最大值为 100）；返回已保存报告的 UUID 和摘要。
report_get	id；来源文档、所有问题和逐 SKU 证据。
report_page	id、section、可选的 offset/limit、receipt_index/sku；分页返回所有问题、SKU 证据和来源行，不收费。
report_delete	id；删除该已保存报告并释放一个存储槽位。
report_export_csv	id、可选的 offset/limit；返回 CSV 文本以及货币、状态和文档级问题代码；大型导出会分页。
license_status	无参数；离线查看免费版/Pro 状态和结账链接。
license_activate	key；离线验证并保存 Pro 密钥。

输入约定

每次调用传入一个 PO 和一张当前供应商发票。不进行模糊匹配：SKU、供应商和 PO 引用都是精确且区分大小写的字符串，前后不能有空白或控制字符。单据引用和 SKU 长度为 1–120 个字符。PO、发票和收货单的单据引用必须互不相同。同一单据或 prior_invoiced 中的重复 SKU，以及重复的收货单引用，都会导致 invalid；含糊不清的行会从比较中排除。不同收货单中的重复 SKU 属于预期情况，数量会累加。

数量必须是 0 到 1,000,000,000 之间的整数单位；PO 和发票行的数量必须为正数。不接受小数数量。accepted_quantity 和 rejected_quantity 是互不重叠的数量，不是总数量及其子集。拒收单位不会增加可开票数量。收货单必须包含有效的 YYYY-MM-DD 日期；仅提供与本次检查相关的收货单。日期是凭证，不会自动作为发票日期的截止条件。

所有金额输入必须是 0 到 Number.MAX_SAFE_INTEGER（9,007,199,254,740,991）之间的整数最小货币单位金额。对于 USD，100 表示 $1.00；对于零小数位货币，使用该货币自己的最小单位。PO 和发票都必须提供大写的三字母货币代码。不进行货币兑换，也不查询货币代码目录。单价必须完全匹配，不设容差。金额乘积和总额均使用整数运算；若结果不安全，则返回 invalid 和 unsafe_money_arithmetic，绝不返回四舍五入后的金额。

invoice.total_minor 是所提供商品行的总额。不包含任何隐含税费、运费、折扣、舍入或贷项调整。将约定费用作为明确标价的 PO/发票 SKU，并提供相应的收货凭证；或者在调用前准备好不含调整项的商品总额。若省略调整项，请勿提供包含这些调整项的发票总额。

必须提供 prior_invoiced，即使它为空也不例外。请提供此 PO 下每个 SKU 之前已开票的累计数量，不包括当前发票。[] 明确表示无此前开票数量。当前数量与此前数量之和必须同时符合已验收收货数量和 PO 数量。保存报告不会更新此历史记录，也不会检测不同检查之间重复的发票引用；历史记录错误或遗漏可能导致重复开票未被发现。报告是凭证快照，不是会计账簿。

免费版和 Pro 均适用以下限制：PO 行数为 1–500，发票行数为 1–500，此前开票 SKU 最多 500 个；收货单最多 100 张，每张包含 1–500 行。收货单数组可以为空，此时已开票的 PO SKU 会产生缺少收货凭证异常。空白或格式错误的引用、空白/缺失的 SKU、小数、不安全的输入数字和无效日期都会作为输入错误被拒绝。未知 SKU 会产生明确的 unordered_sku 异常。

总额相等也可能掩盖 SKU 错误

使用以下内容调用 three_way_match：

{
  "po": {
    "reference": "PO-1", "supplier": "Supply Co", "currency": "USD",
    "lines": [
      {"sku": "A", "quantity": 10, "unit_price_minor": 100},
      {"sku": "B", "quantity": 10, "unit_price_minor": 100}
    ]
  },
  "receipts": [{
    "reference": "GR-1", "po_reference": "PO-1", "supplier": "Supply Co", "date": "2026-10-16",
    "lines": [
      {"sku": "A", "accepted_quantity": 5, "rejected_quantity": 0},
      {"sku": "B", "accepted_quantity": 15, "rejected_quantity": 0}
    ]
  }],
  "invoice": {
    "reference": "INV-1", "po_reference": "PO-1", "supplier": "Supply Co", "currency": "USD",
    "lines": [
      {"sku": "A", "quantity": 10, "unit_price_minor": 100},
      {"sku": "B", "quantity": 10, "unit_price_minor": 100}
    ],
    "total_minor": 2000
  },
  "prior_invoiced": [],
  "save": false
}

尽管 PO 和发票总额均为 2,000 个最小货币单位，且总数量相等，报告状态仍为 exceptions。SKU A 的问题是 invoiced_above_accepted（已开票 10 件，已验收 5 件）；SKU B 的问题是 accepted_above_order（已验收 15 件，订购 10 件）。将 A 的发票单价改为 90，将 B 的发票单价改为 110，也能保持总额不变，但会产生两个 unit_price_mismatch 问题。

部分交付也可以匹配

使用相同的 PO，提供一张仅包含 A 的收货单，其中 accepted_quantity: 4、rejected_quantity: 2。发票仅包含 A，数量为 4，unit_price_minor: 100，total_minor: 400，并保持 prior_invoiced: []。这会返回 matched。A 仍有 6 件未交付；B 无需出现在这张部分发票中。另一张匹配的收货单会增加已验收数量；拒收数量仍是单独的凭证。此前已开票 2 件 A 后，提供 prior_invoiced: [{"sku":"A","quantity":2}]，并且针对这 4 件已验收数量，最多再开票 2 件。

阅读报告

matched 表示提供的证据通过了这些精确检查；这并不代表授权付款。exceptions 用于指出单据不匹配、未知 SKU、缺少收据、已接受或已开票数量超出限额、价格差异，或声明的发票总额不一致。invalid 用于指出存在歧义或计算出的金额不安全；请先解决这些问题，再解读比较结果。采购订单（PO）或供应商引用不匹配的收据会被标记，且这些收据不能作为开票依据。

每个问题都包含 code、severity、source、可选的 sku，以及具体说明。每个按 SKU 排序的行都包含 PO/发票中的 1 起始源行号；订购、已接受、拒收、此前及当前发票数量；两种单价；累计已开票数量；本张发票开票前的可用数量；尚未交付的数量；收据引用/行号及纳入标记；以及问题代码。报告会保留提供的完整单据，因此重复行不会从审计证据中消失。部分短缺会显示为剩余数量，不会仅因此导致有依据的部分发票失败。

小型报告会以内联形式返回。若 MCP 响应转义后的大小超过 8 MiB，则会返回明确标记 paginated: true 的概览，其中包含状态、总额、计数、源单据标头和 report_id。所有证据都可以通过 report_page 免费获取。将 section 设为 issues、lines、po_lines、invoice_lines、prior_invoiced、receipts、receipt_lines 或 line_receipts；使用 offset（默认为 0）和 limit（默认为 100，最大值为 100），并持续获取，直到 next_offset 为 null。lines 分页包含标量证据和 receipt_count；使用完全匹配的 sku，通过 line_receipts 获取对应的收据条目。receipt_lines 需要使用原始收据数组中的零起始 receipt_index。receipts 分页包含单据标头和行数。这些分区合在一起，会保留每个源行和每个计算出的问题。

已保存报告的分页使用其持久化 UUID，且对于大型已保存报告，report_get 会返回相同的有界概览。大型未保存报告（包括达到保存上限和存储失败的情况）使用 preview:<UUID> ID：进程会将最近的两个大型预览保留 30 分钟。重启、过期或生成第三个预览都可能导致其被清除；重新提交原始诊断即可重新创建免费预览。预览 ID 仅属于当前运行的服务端进程。底层 SDK 还会将传入的 stdio 消息限制为 10 MiB；即使各行数量符合架构限制，编码后的请求也必须满足此传输限制。

CSV 每个 SKU 占一行，包含精确到最小货币单位的价格、数量和行级问题代码；单据问题则保留在随附的 JSON 和完整报告中。CSV 以文本形式返回，不会写入调用方任意指定的路径。类似公式的前导字符会转义，以便用于电子表格。

符合相同 8 MiB 响应预算的 CSV 导出会以内联形式返回。较大的导出会先返回最多 1,000 行的首个数据块，并包含 paginated、offset、returned、total_rows 和 next_offset。在后续的 report_export_csv 调用中，将该 next_offset 作为 offset 传入；可选的 limit 范围为 1–1,000。每个数据块都会重复包含表头；合并数据块时请保留一个表头。

免费版和 Pro 版

功能	免费版	Pro 版
完整诊断检查和来源证据	所有检查，最多 500 行采购订单/发票明细	相同
收据和历史发票检查	相同的已记录限制	相同
已保存的报告	同时最多 3 份	报告数量不限
列出/获取/删除和导出 CSV	包含	包含

当 save: true 触及免费版上限时，仍会返回完整报告，并附带 saved: false、save_error: "free_saved_report_cap" 和结账链接。发生存储错误时，也会保留诊断报告。删除旧的已保存报告，即可腾出一个免费版名额。已保存的报告文件在保存和读取时不得超过 64 MiB；这是存储完整性保护，而非 Pro 版限制。

购买 Pro：一次性支付 $19。所有服务：$39 套装。使用 license_activate 激活密钥，或设置 MCP_LICENSE_KEY。密钥可离线验证。

所有数据都保留在本地。匹配过程不会发起网络请求。已保存的 JSON 报告位于 ${XDG_DATA_HOME:-~/.local/share}/mcp-servers/three-way-match/；XDG_DATA_HOME 必须是绝对路径，且存储目录的祖先目录不得包含符号链接。文件采用原子重命名，所有变更共用跨进程锁。报告包含商业单据数据：请妥善管理本地访问权限和备份。激活许可证会写入共享的本地许可证配置。

开发

npm run build --workspace @theluckystrike/mcp-three-way-match
npm test --workspace @theluckystrike/mcp-three-way-match

测试涵盖数量/价格错误相互抵消、被拒收的收据和多份收据、部分收货、明确的历史开票记录、未知和重复的 SKU/引用编号、币种/采购订单/供应商不匹配、日期、整数边界、免费版/Pro 版保存策略、原子存储，以及 MCP stdio 初始化与 tools/call 往返测试。Docker 从仓库根目录构建：docker build -f servers/three-way-match/Dockerfile .。