Invoice Intake (reference)

com.justdukkanPublished by justdukkan.comv0.1.1Updated Nov 3, 2026

Reference invoice-intake MCP servers: read/draft/commit split, typed errors, approval gate, audit

VerifiedSTDIODesktop onlyDeveloper ToolsBusiness & Commerce

Overview

AI-generated overview

A reference invoice-intake MCP server that lets an assistant extract, match and stage supplier invoices, with posting gated behind a recorded human approval.

What you can do
  • Extract invoices from an inbox and resolve vendors
  • Match invoices against purchase orders and stage them in a fake ERP
  • Post approved invoices through a separate commit-role server
  • Return typed errors such as approval_required, validation_failed, business_rule and not_found
  • Record actor, tool, ids and approval reference in an append-only audit log
When to use it
Useful as a worked example of safe tool design for back-office processes: read/draft/commit separation, strict schemas, typed errors and a server-side approval gate. It is a small reference implementation with a JSON-file ERP, not a production invoice system.
Requirements
Runs locally over stdio as a PyPI package launched with uvx (Python). Two server entries are configured, one with the read role and one with the commit role. No API key or credentials are declared; the orchestrator is deterministic and replays without one.
Before you install
The commit-role server performs irreversible posting, so give agents only the read server unless they are the orchestrator. Posting is refused without a recorded approval, which is granted through a separate CLI. Tool results are treated as untrusted input, and the eval set includes a prompt-injection case. The ERP is a local JSON file, not a real system.

Installation

In SourceWeft

  1. Open Invoice Intake (reference) in the dashboard and add it to a workspace.
  2. Enable the server for the chats that should use its tools.

Desktop only via STDIO. STDIO servers start a local process, so they need the SourceWeft desktop host.

Other MCP clients

Follow the launch instructions in the repository.

README

invoice-intake-mcp

Reference implementation of the tool-design rules in Designing MCP servers and tools that agents can use safely, 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

RuleWhere
Model the business operation, not the APIerp_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 schemasLiteral enums for currency, ids not names, found=false as a valid empty result
Permissions on the server and credentialspecialist agents get read; only the orchestrator connects to commit
Tool results are untrusted inputinvoices_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 auditoraudit.jsonl: actor, tool, ids, approval reference
Human checkpoint enforced server-sideerp_post_invoice refuses without a recorded approval, whatever the client believes

Run it

bash
python -m venv .venv && . .venv/bin/activatepip install -e ".[dev]"
python -m invoice_intake_mcp.orchestrator            # process the inboxpython -m invoice_intake_mcp.approve list            # see what is waitingpython -m invoice_intake_mcp.approve APR-xxxx approved --by cfopython -m invoice_intake_mcp.orchestrator --resume   # post the approved itemcat 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 gatepython 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/             pytestevals/             cases.jsonl + run.py

MIT. Built by JustDukkan, AI solutions architecture.

Source: README.md at commit aa9a9cd

Tools

0
SourceWeft has not started this package in its sandbox yet, so its tools are not known.

Version history

1
  1. v0.1.1LatestSep 16, 2026

Score

50% of the applicable checks met

How complete this listing is, computed from the registry entry, the endpoint and public sources. Not a rating of the server and not a statement that it is safe or working today: reachability is a dated check, and no installs or reviews go into the score.

  • Reached in the last 30 days25 pts

    Keep the endpoint answering the MCP handshake; SourceWeft probes it every 30 days.

  • Auth declared10 pts

    Declare the credential headers in the registry entry, or keep the endpoint answering the probe so its auth can be classified.

  • Tools listed15 pts

    Answer tools/list without a credential, or ship a package that starts in a sandbox without one.

  • DescriptionRequired15 pts
  • Logo10 pts
  • Documentation15 pts
  • License10 pts