Invoice Parser MCP

{
 "file_path": "/Users/me/documents/invoice_acme_jan2025.pdf",
 "api_key": "ip_free_abc123"
}

{
 "ok": true,
 "document_type": "invoice",
 "vendor": {
 "name": "Acme Corp",
 "address": "123 Industrial Way, Austin TX 78701",
 "email": "billing@acme.com",
 "phone": "512-555-0100",
 "tax_id": "12-3456789"
 },
 "bill_to": {
 "name": "Jane Smith",
 "address": "456 Oak Ave, Boston MA 02101",
 "email": "jane@example.com"
 },
 "invoice_number": "INV-2025-0142",
 "invoice_date": "2025-01-15",
 "due_date": "2025-02-15",
 "payment_terms": "Net 30",
 "currency": "USD",
 "line_items": [
 {
 "description": "Software consulting — January",
 "quantity": 40,
 "unit_price": 175.0,
 "total": 7000.0,
 "tax_rate": 0.0
 }
 ],
 "subtotal": 7000.0,
 "discount": 0.0,
 "tax_amount": 560.0,
 "shipping": 0.0,
 "total": 7560.0,
 "amount_due": 7560.0,
 "notes": "Wire transfer preferred. See banking details on page 2.",
 "po_number": "PO-98765"
}

{
 "file_path": "/Users/me/receipts/coffee_shop_march1.jpg",
 "api_key": "ip_free_abc123"
}

{
 "ok": true,
 "document_type": "receipt",
 "merchant": {
 "name": "Blue Bottle Coffee",
 "address": "300 Webster St, Oakland CA 94609",
 "phone": "510-555-0200",
 "website": "bluebottlecoffee.com"
 },
 "date": "2025-03-01",
 "time": "09:14",
 "receipt_number": "5541",
 "cashier": "Maria",
 "items": [
 { "name": "Latte (large)", "quantity": 1, "unit_price": 6.50, "total": 6.50, "sku": "", "category": "beverage" },
 { "name": "Croissant", "quantity": 1, "unit_price": 4.00, "total": 4.00, "sku": "", "category": "pastry" }
 ],
 "subtotal": 10.50,
 "discounts": 0.0,
 "tax": 0.84,
 "tip": 2.00,
 "total": 13.34,
 "currency": "USD",
 "payment_method": "Visa",
 "card_last_four": "4242",
 "transaction_id": "TXN-88821",
 "loyalty_points": null,
 "notes": ""
}

{
 "ok": true,
 "line_items": [
 { "description": "Widget A (x10)", "quantity": 10, "unit_price": 12.00, "total": 120.00 },
 { "description": "Widget B (x5)", "quantity": 5, "unit_price": 24.00, "total": 120.00 }
 ],
 "item_count": 2
}

{
 "ok": true,
 "currency": "USD",
 "subtotal": 240.00,
 "discount": 0.0,
 "tax_amount": 19.20,
 "tax_rate": 8.0,
 "shipping": 0.0,
 "tip": 0.0,
 "total": 259.20,
 "amount_due": 259.20,
 "invoice_date": "2025-01-15",
 "due_date": "2025-02-15"
}

{
 "ok": true,
 "valid": true,
 "issues": [],
 "summary": {
 "line_items_checked": 3,
 "subtotal": 450.00,
 "tax": 36.00,
 "total": 486.00,
 "currency": "USD"
 }
}

{
 "ok": true,
 "valid": false,
 "issues": [
 {
 "field": "line_item_2_total",
 "expected": 120.00,
 "found": 100.00,
 "description": "quantity (10) × unit_price (12.00) = 120.00, but stated total is 100.00"
 }
 ],
 "summary": {
 "line_items_checked": 3,
 "subtotal": 340.00,
 "tax": 27.20,
 "total": 367.20,
 "currency": "USD"
 }
}

{
 "file_paths": [
 "/Users/me/invoices/jan2025.pdf",
 "/Users/me/invoices/feb2025.pdf",
 "/Users/me/receipts/expense_march.jpg"
 ],
 "output_path": "/Users/me/exports/q1_summary.csv",
 "api_key": "ip_free_abc123"
}

{
 "ok": true,
 "output_path": "/Users/me/exports/q1_summary.csv",
 "rows_written": 3,
 "errors": []
}

{
 "error": "Payment required",
 "x402": {
 "network": "base",
 "token": "USDC",
 "recipient": "0x9053FeDC90c1BCB4a8Cf708DdB426aB02430d6ad",
 "amount_usdc": 0.05
 }
}

{
 "mcpServers": {
 "invoice-parser": {
 "url": "https://invoice-parser.plenitudo.ai/mcp?ref=readme"
 }
 }
}

server.py — MCP server (6 tools: parse_invoice, parse_receipt,
 extract_line_items, extract_totals, validate_invoice,
 export_to_csv)
auth.py — API key validation + usage tracking (SQLite)
x402.py — x402 micropayment verification (USDC on Base)
config.py — Environment variable loading
worker.js — Cloudflare Worker (remote proxy for MCP traffic)
data/keys.db — API key store (created at runtime)
data/usage.db — Monthly usage counters (created at runtime)
logs/ — Structured log files
tests/ — Unit tests (mock Vision API, no real documents needed)

AI agent (Claude Desktop, Cursor, etc.)
 │
 │ MCP tool call (JSON-RPC over HTTP)
 ▼
Cloudflare Worker (worker.js) ← optional remote proxy
 │
 │ Forwards to Railway deployment
 ▼
server.py (FastMCP, streamable HTTP)
 │
 ├── auth.py validates API key / x402 proof
 ├── x402.py verifies USDC transaction on Base
 └── Anthropic API Claude Vision reads the document
 │
 ▼
 structured JSON → returned to agent

ANTHROPIC_API_KEY=maxproxy
ANTHROPIC_BASE_URL=http://localhost:3456