billparse

billparse

发票以 PDF、扫描件和手机照片的形式到来，其中的数字仍然需要放到可用的地方。billparse 是连接托管 InvoiceParserPro MCP 服务的轻量本地桥接工具：你只需提供发票文档，它就能将文档转换为电子表格、检查其中的计算是否正确、提取结构化数据，或获取你此前提交的文档的处理结果。

所有解析工作都不会在你自己的设备上进行。此软件包会根据捕获的工具定义，在本地响应 tools/list，并通过可流式传输的 HTTP JSON-RPC 会话，将每个 tools/call 转发到托管服务，再原样返回服务发来的内容。

工具

这四种工具都可处理你提供的文档。三种读取工具支持以下三种方式提供发票：file_url（服务可下载的 https 链接）、file_base64（文件的 Base64 编码字节，可选提供 file_name），或 file（客户端附加的文件对象，适用于支持附件的客户端）。

• invoice_to_excel — 读取发票并返回其抬头字段和行项目，同时提供 Excel（.xlsx）文件和 CSV 文件的下载链接。根据捕获的描述，这些链接无需登录即可在 60 分钟内有效，调用还会返回已处理文档的 job_id。
• check_invoice — 检查发票的计算是否正确：每行的数量乘以单价、各行金额与小计、税额与打印的税率，以及小计加税额与总额。它会返回一行结论以及发现的所有问题，并引用发票上的原始数字。
• extract_invoice_data — 将发票内容提取为结构化 JSON：供应商和客户、发票编号和日期、PO 编号、币种、小计、折扣、运费、税额和总额、税目、所有行项目，以及整体和各字段的置信度。
• get_result — 根据先前调用返回的 job_id，获取该发票可用的电子表格链接、计算检查结果和提取的数据。如果你想获取已提交文档的其他输出，而不想再次提交并重复计费，请使用此工具。

此工具集中的工具不会购买任何商品、启动订阅、结账或创建 API 密钥；输入内容均为你自己的文档。

安装和运行

通过 npm 作为 MCP 服务运行：

npx -y @reneturcios/billparse mcp

MCP 客户端配置：

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

作为容器运行：

docker run -i ghcr.io/cloudcorprecords/billparse
docker run --rm ghcr.io/cloudcorprecords/billparse get_result '{"job_id":"job-123"}'

命令行界面

同一个二进制文件既可用于命令行，也可用作 MCP 服务。每个工具都是一个子命令，接受一个包含该工具参数的 JSON 字符串：

billparse invoice_to_excel '{"file_url":"https://example.com/invoice-1042.pdf"}'
billparse check_invoice '{"file_base64":"...","file_name":"invoice-1042.pdf"}'
billparse extract_invoice_data '{"file_url":"https://example.com/invoice-1042.pdf"}'
billparse get_result '{"job_id":"job-123"}'
billparse --version

退出代码：转发的调用成功时为 0，上游结果为错误时为 1，遇到用法问题（例如未知子命令或格式错误的 JSON 参数）时为 2。

配置

• INVOICEPARSERPRO_MCP_URL — 覆盖上游端点。默认值为固定的托管端点 https://api.invoiceparserpro.com/mcp。（此覆盖变量是本次重建中新增的。）
• INVOICEPARSERPRO_API_KEY — 设置后，每次请求都会将其值作为 Authorization: Bearer <value> 标头发送到上游。未设置时，则完全不发送密钥标头，这与捕获工具集时的免密行为一致。（变量名称和 Bearer 格式均为重建内容；托管服务的注册记录声明了 Authorization 标头，但没有指定软件包的环境变量名称。）

上游故障——服务返回 JSON-RPC 错误、响应状态码非 2xx、响应正文无法读取，或请求彻底失败——都会以错误结果的形式报告给调用方，错误文本以 billparse error: 开头。

转发工作原理

首次转发调用会开启一个会话：先发送 initialize 请求（协议版本为 2025-03-26），再发送 notifications/initialized 通知，随后才是 tools/call。如果服务在响应初始化请求时返回 Mcp-Session-Id 标头，则后续每个请求都会携带该值，并且此进程的其余部分会重复使用已开启的会话。响应可以是纯 JSON，也可以是服务器发送的事件。成功结果会原样传递，包括任何 isError 标志以及服务提供的任何额外字段。

开发

npm install
npm run build   # tsc -> dist/ (dist/cli.js is the bin)
npm test        # tsx --test test/*.test.ts — stubbed upstream, no network
npm run dev     # run the CLI from source

测试套件会逐项将服务提供的工具列表与捕获到的工具列表进行比对，测试会话握手及其重复使用，覆盖两种密钥标头分支，并验证参数会原样发送到上游，结果也会原样返回。

许可证

MIT——详见 LICENSE。版权所有 (c) 2026 Rene Turcios。