maxed-mcp

One Model Context Protocol server that fronts the deterministic tools in the open-source accounting suite, so an AI agent can call them the same way it calls any other MCP tool.

Agents are good at judgement and bad at arithmetic, parsing, and signature checks. This server hands the deterministic, auditable work to the libraries built for it: parse a bank statement, classify a document, validate a workpaper against the open spec, do exact money math, and verify a webhook signature. Every tool returns structured JSON and a uniform error envelope. Nothing here is generative, and nothing is faked: when a backing tool is not installed, the tool says so and tells the agent how to install it, rather than inventing an answer.

This is the agentic front door to the suite. The parsers and validators live in their own repositories and stay the single source of truth for their behavior; maxed-mcp shells out to the ones that ship a CLI and parses their JSON, and computes the small pure primitives (money math, HMAC) in-process, mirroring the semantics of their canonical sibling libraries.

Tools

Tool	What it does	Backend
list_capabilities	List every tool and whether its backend is installed on this host.	in-process
normalize_bank_statement	Parse CSV / OFX / QFX / MT940 / CAMT / QIF / text into normalized transaction JSON.	statement-normalizer CLI
normalize_ofx	Parse an OFX/QFX or CSV bank export into normalized transaction JSON.	ofx-normalizer ofxnorm (Go)
classify_document	Classify accounting document text: w2, form_1099, invoice, bank_statement, receipt, or unknown.	doc-classifier-kit CLI
validate_workpaper	Validate a document against a cpa-workpaper-spec JSON Schema.	spec validator
money_allocate	Split an amount across ratios or evenly, with no lost minor units.	money-rs semantics
money_apply_rate	Apply a rate (tax, tip, share) with explicit rounding.	money-rs semantics
verify_webhook_hmac	Constant-time verify a Stripe / hex / base64 webhook HMAC signature.	webhook-hmac-verifier semantics

money_* and verify_webhook_hmac are computed in-process and are always available; they faithfully mirror the rules of the canonical Rust and Go libraries so an agent gets the same answer either way. The four parser and validator tools shell out to a sibling CLI; call list_capabilities first to see which are installed.

Install

pip install maxed-mcp

# Make the two Python-backed tools available out of the box:
pip install "maxed-mcp[suite]"      # adds statement-normalizer + doc-classifier-kit

Optional backends for the remaining shell-backed tools:

• normalize_ofx: build the Go binary and put it on PATH (go install github.com/maxed-oss/ofx-normalizer/cmd/ofxnorm@latest).
• validate_workpaper: point CPA_WORKPAPER_SPEC_DIR at a cpa-workpaper-spec checkout (the directory containing validator/validate.py).

Run

maxed-mcp            # start the server on stdio
python -m maxed_mcp  # equivalent

The server speaks MCP over stdio, so it plugs into any MCP client. Register it with a client like this (the exact file differs per client):

{
  "mcpServers": {
    "maxed": {
      "command": "maxed-mcp",
      "env": {
        "CPA_WORKPAPER_SPEC_DIR": "/path/to/cpa-workpaper-spec"
      }
    }
  }
}

Backend resolution

Each shell-backed tool resolves its command in this order:

1. an explicit environment variable (a full command line): MAXED_MCP_STATEMENT_NORMALIZER, MAXED_MCP_DOC_CLASSIFIER, MAXED_MCP_OFXNORM, MAXED_MCP_CPA_WORKPAPER_VALIDATE;
2. the tool's console-script (or ofxnorm binary) on PATH;
3. a fallback: python -m ... for the Python tools, or a sibling cpa-workpaper-spec/ checkout for the validator (CPA_WORKPAPER_SPEC_DIR).

If nothing resolves, the tool returns {"ok": false, "error": {"code": "tool_unavailable", ...}} with an install hint instead of failing opaquely.

Response shape

Every tool returns a JSON object. Success carries "ok": true plus tool fields; failure carries "ok": false and an error object:

{ "ok": false, "error": { "code": "tool_unavailable", "message": "...", "detail": { "hint": "..." } } }

See AGENT.md for the condensed machine interface, llms.txt for the machine-readable tool reference, and examples/agent_call_example.py for a full, runnable in-process client that calls every tool.

Development

pip install -e ".[dev,suite]"
pytest -q

The test suite exercises the in-process tools directly and the shell-backed tools against the installed Python siblings; tools whose backend is not present assert the graceful tool_unavailable path.

License

Apache-2.0.