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 |
|
The FastMCP server, all tool / resource / prompt registrations, and a re-export of every tool |
Shared |
|
Parameter types derived from the core (message types, scheme profiles), tool annotations, schema loading; the result TypedDicts every output schema comes from |
Discovery |
|
|
Validation ladder |
|
Runs the core’s validation ladder ( |
Records |
|
|
Generation |
|
|
Bank replies |
|
|
Schemes |
|
|
Corpus |
|
The four example-corpus tools over |
Faces |
|
|
Staging |
|
|
Entry point |
|
Launches the server over stdio, or over streamable HTTP / SSE with |
Version |
|
Single source of truth ( |
Tests |
|
In-process + end-to-end-via-subprocess regressions |
Fixtures |
|
Bundled |
Examples |
|
One runnable script per usage shape (tool walkthrough, validation pipeline, parsers) |
Release helpers |
|
Asserts |
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 fourlist_corpus_files,get_corpus_file,get_corpus_provenance,get_corpus_coverage(pain001 >= 0.0.67, else a clear error payload), and the faces twolist_faces,project_face(pain001 >= 0.0.78, likewise), and the staging threestage_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
pain001public API. If you want a new tool, port the matching helper frompain001rather than re-implementing it here.One verdict per payload.
validate_records, the threegenerate_messagetools,simulate_payment_batchandstage_payment_batchrun 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.pydrives 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 apain001.exceptionssubclass 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-httpserves MCP at/mcp, and--transport sseserves the older HTTP+SSE transport at/sseand/messages/(ADR 0004). Both bind--host/--port, which default to127.0.0.1:8000. They add no authentication or TLS of their own: asSECURITY.mdsays, 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 topain001.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 inpain001_mcp/server.py, and add oneserver.tool(...)(name)line in the registration block beforemain()(decorators are not used: mutmut never mutates a decorated function, see ADR 0003); pair it with tests intests/test_mcp_server.py, add it toEXPECTED_TOOLSthere, and runscripts/tool_catalogue.py.Add a resource:
@server.resource("pain001://...")decorator.Add a prompt:
@server.prompt()decorator.Match a new
pain001feature: when a new public helper lands upstream, port it as a tool here in the same release window.
Where to look first¶
Runnable examples:
examples/Roadmap:
ROADMAP.mdRelease process:
RELEASING.mdParent library:
pain001