pain001-mcp Architecture

A map of the codebase for new contributors and maintainers. The goal is that anyone can navigate, extend, and reason about pain001-mcp without prior context.

The pipeline

MCP client (Claude Desktop, IDE, agent)
        |  stdio, or streamable HTTP / SSE (JSON-RPC)
        v
pain001_mcp/server.py        (FastMCP server: registers every tool,
        |                     resource and prompt from the family modules)
        |  thin typed wrappers
        v
pain001 public API           (pain001.generate_xml_string,
        |                     pain001.validate_scheme, pain001.parse_camt053_statement,
        |                     pain001.parse_pain002_report,
        |                     pain001.validation.{validate_iban, validate_bic})
        v
ISO 20022 XML / structured data

Tools are deliberately thin: every one is a small adapter that delegates to the pain001 library and returns a JSON-serialisable result. The agent surface is the entire public API of that library, exposed in a way an MCP client can call.

Module map

Area

Module

Responsibility

Server

pain001_mcp/server.py

The FastMCP server, all tool / resource / prompt registrations, and a re-export of every tool

Shared

pain001_mcp/_common.py, pain001_mcp/_shapes.py

Parameter types derived from the core (message types, scheme profiles), tool annotations, schema loading; the result TypedDicts every output schema comes from

Discovery

pain001_mcp/_catalogue.py

list_message_types, get_required_fields, get_input_schema, inspect_template, list_supported_formats, the schema resource and the build_payment_batch prompt

Validation ladder

pain001_mcp/_ladder.py

Runs the core’s validation ladder (pain001.validate) for every tool that validates or generates, and turns its issues into row errors and issues payloads

Records

pain001_mcp/_records.py

validate_records, suggest_record_fix, validate_identifier, migrate_records, sanitize_to_iso20022_charset, convert_mt101

Generation

pain001_mcp/_generate.py

generate_message, generate_message_async, generate_message_from_file, validate_xml_against_schema

Bank replies

pain001_mcp/_replies.py

parse_camt053, parse_pain002

Schemes

pain001_mcp/_schemes.py

validate_payment_scheme, list_scheme_profiles, simulate_payment_batch

Corpus

pain001_mcp/_corpus.py

The four example-corpus tools over pain001.corpus (pain001 >= 0.0.67)

Faces

pain001_mcp/_faces.py

list_faces and project_face over pain001.faces (pain001 >= 0.0.78)

Staging

pain001_mcp/_staging.py, pain001_mcp/_clearing.py, pain001_mcp/_output.py

stage_payment_batch, commit_payment_batch and the in-memory store; simulate_clearing, one table row per clearing system; the confined commit write

Entry point

pain001_mcp.server:main (console script: pain001-mcp)

Launches the server over stdio, or over streamable HTTP / SSE with --transport (_cli.py + _transports.py, ADR 0004)

Version

pain001_mcp/__init__.py

Single source of truth (__version__); the LSP reads it for the protocol handshake

Tests

tests/test_mcp_server.py, tests/test_stdio_e2e.py

In-process + end-to-end-via-subprocess regressions

Fixtures

tests/fixtures/

Bundled camt053_sample.xml and pain002_sample.xml for reproducible parser tests

Examples

examples/

One runnable script per usage shape (tool walkthrough, validation pipeline, parsers)

Release helpers

scripts/verify_versions.py

Asserts __version__, pyproject.toml, and CHANGELOG.md agree

Tools, resources, prompts

The current MCP surface:

  • Tools - list_message_types, get_required_fields, get_input_schema, validate_records, suggest_record_fix, validate_identifier, generate_message, generate_message_async, generate_message_from_file, list_supported_formats, parse_camt053, parse_pain002, inspect_template, validate_payment_scheme, list_scheme_profiles, simulate_payment_batch, migrate_records, validate_xml_against_schema, sanitize_to_iso20022_charset, convert_mt101, and the example-corpus four list_corpus_files, get_corpus_file, get_corpus_provenance, get_corpus_coverage (pain001 >= 0.0.67, else a clear error payload), and the faces two list_faces, project_face (pain001 >= 0.0.78, likewise), and the staging three stage_payment_batch, simulate_clearing, commit_payment_batch.

  • Resources - pain001://schema/{message_type} (returns the bundled XSD text).

  • Prompts - build_payment_batch(message_type=...) (guided instruction template).

Key design decisions

  • Delegation, not duplication. Every tool is a thin wrapper over the pain001 public API. If you want a new tool, port the matching helper from pain001 rather than re-implementing it here.

  • One verdict per payload. validate_records, the three generate_message tools, simulate_payment_batch and stage_payment_batch run the core’s validation ladder (pain001

    = 0.0.87), the one its CLI and REST API run, so a payload gets the same verdict and the same P001-E... issue codes on every surface. tests/test_verdict_parity.py drives the CLI, the REST API and these tools with the same fixtures and checks they agree.

  • Errors as data. Tools never raise. A ValueError (or a pain001.exceptions subclass thereof) is turned into an {"error": ...} payload so the agent can reason about failure without parsing tracebacks.

  • stdio by default, HTTP on request. With no flags the server speaks stdio and opens no socket. --transport streamable-http serves MCP at /mcp, and --transport sse serves the older HTTP+SSE transport at /sse and /messages/ (ADR 0004). Both bind --host/--port, which default to 127.0.0.1:8000. They add no authentication or TLS of their own: as SECURITY.md says, put the server behind a gateway you trust before binding a routable address with --host.

  • Path safety reused. File-path tools (parse_camt053, parse_pain002, generate_message_from_file) delegate to pain001.security.validate_path(), the same guard the CLI and REST API use.

  • Coverage enforced at 100% line+branch and docstring; only defensive guards against bundled-asset removal are # pragma: no cover.

Extension points

  • Add a tool: add a plain function to the module of its family (or a new pain001_mcp/_<family>.py), import it in pain001_mcp/server.py, and add one server.tool(...)(name) line in the registration block before main() (decorators are not used: mutmut never mutates a decorated function, see ADR 0003); pair it with tests in tests/test_mcp_server.py, add it to EXPECTED_TOOLS there, and run scripts/tool_catalogue.py.

  • Add a resource: @server.resource("pain001://...") decorator.

  • Add a prompt: @server.prompt() decorator.

  • Match a new pain001 feature: when a new public helper lands upstream, port it as a tool here in the same release window.

Where to look first