Invoice Intake (reference)

Name: Invoice Intake (reference)
Author: justdukkan.com

本地服务

justdukkan.com开发工具07 周前更新

代码仓库访问官网

关于 Invoice Intake (reference)

Invoice Intake (reference) 是围绕供应商发票处理设计的 MCP 服务参考实现，面向构建安全后台流程的开发者。它通过读写分离、类型化错误、审计日志和服务端审批门展示工具设计规则。

主要功能

01分离读取、暂存与提交
02严格的工具参数结构
03类型化错误与重试标记
04审批门和审计日志
05可重放的确定性流程

适用场景

01设计带审批的人机协作发票流程
02参考 MCP 工具权限分层
03测试发票处理决策与异常

MCP 相关

提供读角色和提交角色两个 MCP 服务，分别处理读取与可撤销暂存、不可逆过账。服务端在过账前强制检查已记录的人工审批。

配置

本地服务的配置在各客户端中通用，复制后粘贴到客户端的 MCP 配置文件即可。

mcp.json · 通用配置

{
  "mcpServers": {
    "com-justdukkan-invoice-intake": {
      "command": "uvx",
      "args": [
        "invoice-intake-mcp"
      ]
    }
  }
}

启动命令uvx invoice-intake-mcp

本地服务需要在你的电脑上安装运行环境（如 Node.js 18+）。各客户端的配置文件位置不同，请参考客户端文档。

安装包

pypiinvoice-intake-mcp0.1.1stdio

工具

收录的工具列表 · 更新于 3 周前

参数	类型	必填	说明
name	string	是

详细介绍

invoice-intake-mcp

Designing MCP servers and tools that agents can use safely 中工具设计规则的参考实现，应用于真实的后台流程：供应商发票接收。

它刻意保持精简。模拟 ERP 是一个 JSON 文件；其他部分则采用我们在生产系统中使用的结构。

展示内容

规则	位置
对业务操作建模，而非对 API 建模	`erp_match_po`、`erp_stage_invoice`，而不是 `PATCH /invoices`
将读取、草稿和提交分开	`--role read` 服务（读取 + 可撤销的暂存）与 `--role commit` 服务（不可撤销的过账）
严格的架构	用于币种的 `Literal` 枚举、使用 ID 而非名称、将 `found=false` 作为有效的空结果
在服务端和凭证上设置权限	专业 Agent 获得读取权限；只有协调器连接到提交服务
工具结果是不可信输入	`invoices_extract` 在其描述中明确说明这一点；评估集包含一个提示注入案例
类型化错误	`{"error": "approval_required" \| "validation_failed" \| "business_rule" \| "not_found", "retryable": bool, ...}`
为审计人员记录日志	`audit.jsonl`：操作者、工具、ID、审批引用
在服务端强制执行人工检查点	无论客户端如何判断，`erp_post_invoice` 在没有记录的审批时都会拒绝

运行

python -m venv .venv && . .venv/bin/activate
pip install -e ".[dev]"

python -m invoice_intake_mcp.orchestrator            # process the inbox
python -m invoice_intake_mcp.approve list            # see what is waiting
python -m invoice_intake_mcp.approve APR-xxxx approved --by cfo
python -m invoice_intake_mcp.orchestrator --resume   # post the approved item
cat audit.jsonl

首次运行的预期结果：

plan: 4 new invoices -> extract, resolve vendor, match, stage, post-or-approve
  invoice_2291.pdf: staged STG-… -> WAITING for APR-…        (7,420 EUR > 5,000 limit)
  invoice_2292.pdf: match=goods_not_received -> REVIEW
  invoice_2293.pdf: match=variance {"variance_pct": 2.34} -> REVIEW
  invoice_2294.pdf: no PO reference -> REVIEW (ask requester)

协调器具有确定性，因此无需 API 密钥即可重放整个流程。大模型应放在 orchestrator.py 中标记的位置（含糊的供应商候选项、自由文本备注、回复请求者的说明），而不是用于匹配规则、容差或审批限额。

从 MCP 客户端使用这些服务

{
  "mcpServers": {
    "invoice-intake-read":   { "command": "uvx", "args": ["invoice-intake-mcp", "--role", "read"] },
    "invoice-intake-commit": { "command": "uvx", "args": ["invoice-intake-mcp", "--role", "commit"] }
  }
}

除非是协调器，否则只向 Agent 提供读取服务。

测试与评估

pytest                 # unit tests on the core operations and the gate
python evals/run.py    # replayable decision cases, run on every change

目录结构

invoice_intake_mcp/
  core.py          business operations + policy (tolerance, approval limit), pure functions
  server.py        the two MCP servers and their tool descriptions
  orchestrator.py  minimal hub over MCP stdio: read server for work, commit server for posting
  approve.py       the human decision, as a CLI
  audit.py         append-only JSONL audit log
  erp.py           fake ERP / inbox state (JSON file)
tests/             pytest
evals/             cases.jsonl + run.py

MIT。由 JustDukkan 构建，AI 解决方案架构。

支持 Markdown

登录后评论