Invoice Intake (reference)
Reference invoice-intake MCP servers: read/draft/commit split, typed errors, approval gate, audit
Open source Open in the app JSON README (API)
About
Reference invoice-intake MCP servers: read/draft/commit split, typed errors, approval gate, audit
Details
- Kind
- MCP servers
- Topic
- Finance & crypto
- Publisher
- com.justdukkan
- Origin
- official
- Category
- ferramentas
- Transport
- local
- Version
- 0.1.1
- Last push
- 2026-09-13T12:18:03Z
- Repository state
- ativo
- Language
- Python
- License
- MIT
- Added
- 2026-09-13 13:04:26
- Updated
- 2026-09-13 13:04:26
- Origin id
com.justdukkan/invoice-intake-mcp
README
# invoice-intake-mcp
<!-- mcp-name: com.justdukkan/invoice-intake-mcp -->
Reference implementation of the tool-design rules in
[Designing MCP servers and tools that agents can use safely](https://justdukkan.com/insights/mcp-server-and-tool-design/),
on a real back-office process: supplier invoice intake.
It is small on purpose. The fake ERP is a JSON file; everything else is the
shape we use in production systems.
## What it shows
| Rule | Where |
|---|---|
| Model the business operation, not the API | `erp_match_po`, `erp_stage_invoice`, not `PATCH /invoices` |
| Separate reads, drafts and commits | `--role read` server (reads + reversible staging) vs `--role commit` server (irreversible post) |
| Strict schemas | `Literal` enums for currency, ids not names, `found=false` as a valid empty result |
| Permissions on the server and credential | specialist agents get *read*; only the orchestrator connects to *commit* |
| Tool results are untrusted input | `invoices_extract` says so in its description; the eval set includes a prompt-injection case |
| Typed errors | `{"error": "approval_required" \| "validation_failed" \| "business_rule" \| "not_found", "retryable": bool, ...}` |
| Log for the auditor | `audit.jsonl`: actor, tool, ids, approval reference |
| Human checkpoint enforced server-side | `erp_post_invoice` refuses without a recorded approval, whatever the client believes |
## Run it
```bash
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
```
Expected first run:
```
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)
```
The orchestrator is deterministic so the flow replays without an API key.
An LLM belongs in the places marked in `orchestrator.py` (ambiguous vendor
candidates, free-text remarks, the note back to the requester), not in the
match rule, the tolerance or the approval limit.
## Use the servers from an MCP client
```json
{
"mcpServers": {
"invoice-intake-read": { "command": "uvx", "args": ["invoice-intake-mcp", "--role", "read"] },
"invoice-intake-commit": { "command": "uvx", "args": ["invoice-intake-mcp", "--role", "commit"] }
}
}
```
Give an agent only the *read* server unless it is the orchestrator.
## Tests and evals
```bash
pytest # unit tests on the core operations and the gate
python evals/run.py # replayable decision cases, run on every change
```
## Layout
```
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. Built by [JustDukkan](https://justdukkan.com), AI solutions architecture.