Invoice Intake (reference)

invoice-intake-mcp

実際のバックオフィス業務である仕入先請求書の受付を題材にした、エージェントが安全に使える MCP サーバーとツールの設計におけるツール設計ルールのリファレンス実装です。

意図的に小規模にしています。模擬 ERP は JSON ファイルで、それ以外は本番システムで使用している構成です。

何を示しているか

ルール	該当箇所
API ではなく、業務上の操作をモデル化する	PATCH /invoices ではなく、erp_match_po、erp_stage_invoice
読み取り、下書き、確定を分離する	--role read サーバー（読み取り＋取り消し可能なステージング）と --role commit サーバー（取り消し不可能な登録）
厳格なスキーマ	通貨に Literal 列挙型を使用し、名前ではなく ID を使い、found=false を有効な空の結果として扱う
サーバーと認証情報で権限を設定する	専門エージェントには読み取り権限を付与し、オーケストレーターのみが確定サーバーに接続する
ツールの結果は信頼できない入力として扱う	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 キーがなくても処理を再実行できます。 LLM を使うのは 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"] }
  }
}

オーケストレーター以外のエージェントには、読み取りサーバーのみを利用させてください。

テストと評価

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。AI ソリューションアーキテクチャを手がける JustDukkan が開発しました。