ISO 20022 MCP Suite: tool reference.

Use this first, before any generation or validation call, to discover the exact message_type strings this server accepts. Do not use it to fetch a type's fields or schema - call get_required_fields or get_input_schema for that.

Returns a list of {"message_type": ..., "name": ...} dictionaries, one per supported message type (e.g. pain.001.001.09).

This tool takes no parameters.

Use this for a quick checklist of the mandatory columns before building records. When you need full type/format constraints (not just which fields are required), call get_input_schema instead.

Use this to learn every field, its type, and its constraints before assembling records, or to drive a form/UI. For just the required-field names use get_required_fields; to actually check records against this schema use validate_records.

Use this before generate_message to catch structural/type errors per record and get a row-by-row error report. This checks JSON-Schema shape only; for payment-scheme rulebook checks (SEPA field lengths, charset, etc.) also run validate_payment_scheme.

Returns a report {"valid": bool, "total": int, "valid_count": int, "errors": [...]}.

Use this for a one-off identifier check with a clear pass/fail and reason. To validate identifiers embedded across a whole batch, prefer validate_records / validate_payment_scheme instead of calling this per field.

Returns {"kind": str, "value": str, "valid": bool, "error": str} (the error key is present only when valid is False).

This is the primary generation tool: pass records you already hold in memory. Use generate_message_from_file when the data lives in a CSV on disk, and generate_message_async for very large batches you want to run off the event loop. The result is XSD-validated before return; no file is written.

Returns the validated XML document as a string, or a JSON-encoded {"error": ...} payload if generation fails.

Use this to tell a user which file types they may supply to generate_message_from_file. This lists data-source formats (CSV, SQLite, …); for the list of ISO 20022 message types call list_message_types instead.

Returns a list of {"id", "name", "extension"} dictionaries covering CSV, SQLite, JSON, JSONL, and Parquet (the last requires the pain001[parquet] extra).

This tool takes no parameters.

Behaves exactly like generate_message but runs the synchronous renderer in a worker thread so an agent can interleave a long generation with other tool calls. Use generate_message for small or interactive batches; use this only when the record count is large enough that blocking would matter.

Delegates to pain001.async_adapter.generate_xml_string_async. Returns the validated XML, or a JSON-encoded {"error": ...} payload.

Use this when the records live in a CSV file rather than in memory; it reads data_file_path from the local filesystem, then delegates to generate_message. If you already have the records as dicts, call generate_message directly. Only CSV is supported today (JSON / JSONL / SQLite / Parquet are planned for a follow-up release).

Loads data_file_path via pain001.csv.load_csv_data.load_csv_data so the same path-safety guards apply as in the core library.

Use this to read a bank's account statement (the reply that confirms settlement) into a header + entry list. Reads xml_file_path from the local filesystem. For the payment-status reply (accepted/rejected per transaction) use parse_pain002 instead; to validate a camt.053 string you already hold, this is not it - this tool needs a file path.

Wraps pain001.parse_camt053_statement. When xsd_file_path is provided, the document is first validated against that XSD; on a schema or parse error the tool returns {"error": ...} rather than raising.

Use this to read the bank's acknowledgement of a submitted pain.001 - the per-transaction accepted/rejected status and reason codes. Reads xml_file_path from the local filesystem. For the account statement that later confirms booked entries, use parse_camt053 instead.

Wraps pain001.parse_pain002_report. When xsd_file_path is provided, the document is first validated against that XSD; on a schema or parse error the tool returns {"error": ...} rather than raising.

Use this to see the exact column order for hand-building a CSV before generate_message_from_file. This returns column names from the bundled sample; for the typed JSON contract (types, required flags) use get_input_schema.

Mirrors the in-tree pain001.mcp.server.inspect_template tool so an agent can introspect the column layout before assembling rows.

Use this after validate_records to enforce scheme-specific business rules (SEPA field lengths, allowed characters, currency/BIC constraints) that JSON-Schema validation alone does not cover. validate_records checks structural shape; this checks rulebook compliance for one profile.

Delegates to pain001.validate_scheme. Supported profiles: sepa-sct, sepa-sdd, sepa-inst, xborder-ct.

Use this to upgrade/downgrade records when your bank requires a different pain.001 version than your source data uses (e.g. move .03 rows to .09); it reports which fields were renamed, derived, or dropped. This transforms records only - run validate_records afterwards, then generate_message to emit XML.

Wraps pain001.migration.VersionMapper. Returns the migrated rows plus a summary of which fields were renamed, derived, or dropped; {"error": ...} if either version is unsupported.

Use this to check XML you already have as a string (e.g. received from another system) without touching the filesystem. To validate records before they become XML, use validate_records; to parse a statement or status-report file, use parse_camt053 / parse_pain002.

Wraps pain001.xml.validate_via_xsd.validate_xml_string_via_xsd.

Use this on a single free-text value (name, remittance info) to transliterate accents and drop unsupported symbols before placing it in a record, and to see whether the value changed. Operates on one string; to check a whole batch's rulebook compliance use validate_payment_scheme.

Wraps pain001.sanitize_to_charset. Transliterates accents (é -> e), removes unsupported symbols, and returns both the cleaned string and a flag for whether the original was already valid - useful for surfacing the change to the user before writing it back to a record.

Use this to bridge the Nov-2025+ SWIFT MT→MX migration: parse an MT101 (Request for Transfer) into the flat records the other tools consume - feed the result straight to validate_records / validate_payment_scheme and then generate_message to emit pain.001.001.09 XML. An MT101 can request many transfers (repeating sequence B), so this returns one record per transaction. Operates on the supplied text only; no file is read or written.

Wraps pain001_loader_mt101.loader.parse_mt101. Sequence-A ordering-customer / account-servicing fields apply to every transaction unless a sequence-B block overrides them; fields the MT101 does not carry are synthesised to schema defaults (payment_method "TRF", service_level_code "SEPA", etc.).

Use this first, before any generation or validation call, to discover the exact message_type strings this server accepts (e.g. pacs.008.001.08 FI-to-FI Customer Credit Transfer). To learn a type's required fields or full schema, call get_required_fields or get_input_schema instead.

Returns a list of {"message_type": ..., "name": ...} dictionaries, one per supported message type.

This tool takes no parameters.

Scheme profiles (CBPR+, HVPS+, Fedwire, CHAPS, T2 RTGS, SCT Inst, generic) layer rail-specific rules on top of base ISO 20022. Use this to discover the scheme names accepted by get_scheme and validate_scheme.

Registry aliases (e.g. cbpr+, cbprplus) collapse to their canonical profile, so each profile appears exactly once. Returns a list of {"scheme": ..., "name": ...} dictionaries.

This tool takes no parameters.

Use this to inspect a rail's constraints -- whether the UETR is mandatory, the permitted charge bearers, remittance-info length cap, per-message transaction cardinality, pinned message versions, and which parties must carry an LEI -- before assembling or validating a batch.

Use this for a quick checklist of the mandatory columns before building payment records. For full type/format constraints (not just which fields are required), call get_input_schema instead.

Use this to learn every field, its type, and its constraints before assembling records, or to drive a form/UI. For just the required-field names use get_required_fields; to check records against this schema use validate_records.

Use this before generate_message to catch structural/type errors per record and get a row-by-row error report. This checks JSON-Schema shape only; to check a batch against a rail's usage guidelines use validate_scheme.

Returns a report {"is_valid": bool, "total": int, "valid": int, "errors": [...]}.

Use this to check a batch against a rail's rulebook (CBPR+, HVPS+, Fedwire, CHAPS, T2 RTGS, SCT Inst) -- charge-bearer restrictions, UETR presence, remittance-info length, and per-message transaction cardinality. This is complementary to validate_records (JSON-Schema shape).

Returns {"scheme": str, "is_valid": bool, "total": int, "violations": [...]}.

This is the primary generation tool: pass payment records you already hold in memory and receive an XSD-validated XML document; no file is written. Run validate_records first to surface record-level errors, and list_message_types to confirm the message_type string.

Returns the validated XML document as a string, or an {"error": ...} payload (serialized) if generation fails.

Use this to check an externally produced XML document against the official ISO 20022 schema. To generate a document that is already XSD-validated, use generate_message instead.

Returns {"message_type": str, "is_valid": bool}.

Use this on the receiving side to identify what a message is -- its msg_def_idr (e.g. pacs.002.001.10), family, version, and any Business Application Header -- before processing it. Handles both bare Document messages and BAH-wrapped envelopes.

Returns a dict with msg_def_idr, msg_family, version, root_local_name, namespace_uri, envelope_wrapped and bah.

This is the SWIFT MT-to-MX migration path (correspondent-banking MT103 coexistence with ISO 20022 ends November 2025): parse an MT103 text payload and get back the flat pacs.008 record(s) that can be fed straight into validate_records / generate_message. An MT103 carries exactly one transfer, so the records list always holds a single record. No file is read or written.

Returns {"message_type": "pacs.008.001.08", "records": [{...}]} with the parsed flat record, or an {"error": ...} payload if the MT103 is missing a mandatory field (:20:, :32A:, beneficiary) or malformed.

Use this to see where an address stands against the 14 November 2026 SWIFT cliff: structured (town + country + structured detail, no free-form lines), hybrid (town + country + 1-2 free-form adr_line lines, the minimum CBPR+ UG2026 bar), or unstructured (free-form only - rejected from the cliff date). To check acceptability under a policy use validate_address; to upgrade legacy lines use repair_address.

Returns {"classification": str, "is_structured": bool, "is_hybrid": bool, "is_unstructured": bool, "has_structured_fields": bool} or an {"error": ...} payload.

Use this to decide whether an address will clear a rail. The default hybrid_or_structured policy is the November 14, 2026 cliff rule (SWIFT CBPR+, HVPS+, T2 RTGS, CHAPS, Fedwire, Lynx): it rejects fully unstructured addresses. Findings mirror the library's pipeline severity (a policy rejection is a blocking finding).

Returns {"policy": str, "classification": str, "is_acceptable": bool, "findings": [{"severity": str, "message": str}, ...]} or an {"error": ...} payload.

Experimental country-aware repair (GB, US, DE, FR, JP have dedicated heuristics; other countries get a best-effort pass promoting the last line to a town). Use this to lift pre-cliff data over the November 14, 2026 bar; audit the output before submitting, and keep both the original and derived address in your audit trail.

Returns {"address": {...}, "classification": str, "is_structured": bool, "is_hybrid": bool} (so you can see the unstructured -> hybrid / structured upgrade) or an {"error": ...} payload.

Use this before generate_message to catch addresses that will be rejected at the rail. The default hybrid_or_structured policy enforces the November 14, 2026 cliff. Each finding is reported per offending (row, party) pair.

Returns {"policy": str, "is_valid": bool, "total": int, "errors": [{"row": int, "party": str, "severity": str, "message": str, "classification": str}, ...]} or an {"error": ...} payload.

Use this first, before any validation or generation call, to discover the exact message_type strings this server accepts. For the return-reason codes rather than message types, call list_return_reasons instead.

Returns a list of {"message_type": ..., "name": ...} dictionaries, one per supported message type (e.g. camt.053.001.14).

This tool takes no parameters.

Use this to discover the reason_code values that filter_entries and generate_reversal accept (e.g. AC04 Closed Account). For the supported message types rather than reason codes, use list_message_types.

Returns a list of {"code": ..., "name": ...} dictionaries (e.g. {"code": "AC04", "name": "Closed Account Number"}).

This tool takes no parameters.

Use this for a quick checklist of the mandatory columns before building reversing-entry records. When you need full type/format constraints (not just which fields are required), call get_input_schema instead.

Use this to learn every field, its type, and its constraints before assembling records, or to drive a form/UI. For just the required-field names use get_required_fields; to actually check records against this schema use validate_records.

Use this on in-memory reversing-entry records to catch structural/type errors per row before generation. To validate a whole camt.05x document (XML) against its XSD instead, use validate_statement.

Returns a report {"valid": bool, "total": int, "valid_count": int, "errors": [...]}.

Use this for a one-off identifier check with a clear pass/fail. To validate identifiers embedded across a whole batch of records, prefer validate_records rather than calling this per field.

Returns {"kind": str, "value": str, "valid": bool}.

Use this to turn a raw statement into a navigable dict (header, statements, accounts, balances, entries). To pull just the flat entry list use list_entries; to only check the document is schema-valid use validate_statement.

Returns the parsed document as a JSON-serialisable dict (group header plus statements, each with its account, balances, and entries), or an {"error": ...} payload if the XML cannot be parsed.

Use this as the Phase-1 migration wedge: SWIFT MT940 customer statements retire in **November 2028**, so this tool bridges the gap by turning raw MT940 text into the same JSON-serialisable camt.053 document shape that parse_statement returns (group header plus statements, each with its account, balances, and entries). Downstream tools (list_entries, filter_entries, classify_entry, export_journal) then work on the result unchanged.

Wraps the camt053-loader-mt940 library's parse_mt940; the MT parsing itself is delegated (no MT grammar is reimplemented here). The resulting ParsedDocument is serialised with the same to_dict() the server's other parse tools use, so agents get a consistent structure. Nothing is read from or written to disk.

Returns the converted document as a JSON-serialisable dict, or an {"error": ...} payload if the MT940 text cannot be parsed (e.g. a missing :20: reference or a malformed balance / statement line).

Use this as the Phase-1 migration wedge for intraday reporting: SWIFT MT94x messages retire in **November 2028**, so this tool bridges the gap by turning raw MT942 Interim Transaction Report text into the same JSON-serialisable camt.052 (Bank-to-Customer Account **Report**) document shape the server's parse tools return (group header plus statements, each with its account, balances, and entries). MT942 is the intraday sibling of MT940: where MT940 maps to camt.053 (end-of-day statement), MT942 maps to camt.052, so the resulting message_type is camt.052.001.08. Downstream tools (list_entries, filter_entries, classify_entry, export_journal) then work on the result unchanged.

Wraps the camt053-loader-mt942 library's parse_mt942; the MT parsing itself is delegated (no MT grammar is reimplemented here). The resulting ParsedDocument is serialised with the same to_dict() the server's other parse tools use, so agents get a consistent structure. Nothing is read from or written to disk.

**Documented model limitation.** The camt053 typed model is camt.053-statement-oriented: it has no dedicated field for camt.052's floor-limit (<Lmt>) or transaction-summary (<TxsSummry>) blocks. Rather than drop that data, the loader surfaces it on the balance list using clearly proprietary type_code values so consumers can recognise and filter them: :34F: floor limits become FLIMD / FLIMC balances, and :90D: / :90C: entry-count summaries become SUMD:<count> / SUMC:<count> balances (the ISO NbOfNtries count is encoded after the colon; the sum is the balance amount). See the loader's README.

Returns the converted document as a JSON-serialisable dict, or an {"error": ...} payload if the MT942 text cannot be parsed (e.g. a missing :20: reference or a malformed floor-limit / summary / statement line).

Use this to confirm a document is well-formed and schema-valid before processing it. This checks XSD conformance only; for the Nov 2026 CBPR+ business rules use check_cbpr_readiness, and to extract the data use parse_statement.

Detects the document's message type, validates it against the matching ISO 20022 schema, and returns a report {"valid": bool, "message_type": str, "errors": [...]}. A well-formed but schema-invalid document yields valid=False with a populated errors list (and the detected message_type); a valid one yields valid=True with no errors.

Returns an {"error": ...} payload instead if the XML cannot be parsed (e.g. it is malformed or is not a camt Document).

Use this to audit a statement for the business-rule changes (schema version, structured postal addresses) enforced from the Nov 2026 cutover. For plain XSD schema validity use validate_statement instead; for just the cutover date use get_cbpr_cutover_date.

A coordinated CBPR+ / Fedwire / CHAPS / T2 cutover lands on **14-16 November 2026**: unstructured-only postal addresses get rejected, camt.110/111 exceptions and investigations become mandatory, and T2S R2026.NOV upgrades camt.053 / 054 to schema revision MR2026.

This tool walks the supplied payload and reports every issue that will fail the Nov 2026 acceptance rules:

* **Schema version** vs the CBPR+ current set (camt.053.001.08 / camt.053.001.13); .02-.07 are flagged as deprecated warnings; unknown / non-camt.053 namespaces as errors. * **Postal addresses**: every <PstlAdr> is classified as fully structured, hybrid, or **unstructured-only** (<AdrLine> without <TwnNm> + <Ctry> siblings, the Nov 2026 reject case).

Returns a dictionary {"cbpr_ready": bool, "schema_version": str | None, "checked_at": ISO-8601 UTC, "cutover_date": "2026-11-16", "issues": [...], "summary": {...}}. cbpr_ready is True iff no severity="error" issue was raised. An {"error": ...} envelope is returned instead if the XML is malformed or refused by the hardened pre-flight (DOCTYPE / ENTITY / oversized payload).

Use this to quote the enforcement date directly, without parsing a document. To actually audit a statement against the rules that take effect on that date, call check_cbpr_readiness instead.

The cutover (2026-11-16) is the date after which the rules checked by check_cbpr_readiness are enforced by the major clearing systems; payments that fail will be rejected at receive-time. Surfaced as a discrete tool so agents can quote it directly without having to call a readiness check first.

This tool takes no parameters.

Use this to quote one specific rule (with its canonical source URL) once you know the scheme/version/clause. To discover which clauses exist first, call list_rulebook_clauses.

Looks up one well-known rule across the SEPA, CBPR+, and HVPS+ rulebooks and returns a short summary together with the canonical source URL so an agent can quote the rule and the operator can verify it against the official document.

The registry is a curated convenience layer, not a verbatim reproduction of copyrighted text. Always defer to source_url for authoritative wording before relying on a citation for compliance or contractual decisions; the returned disclaimer field repeats this for the calling agent.

Use this to browse the citation registry and pick a clause id; then pass that id to cite_rulebook to fetch the full summary and source URL.

Returns the full registry, optionally filtered by scheme and / or version. Use the resulting clause values as input to cite_rulebook.

Use this to reshape a statement's booked entries into ready-to-POST Xero or QuickBooks payloads (the tool builds the payloads only; it does not call any external API or write files). To discover the valid target values first, call list_export_journal_targets.

Parses the supplied statement and re-shapes every booked entry into a target-specific journal-entry payload ready for direct POST to the accounting platform's REST API.

Supported targets (see camt053_mcp.export_journal.SUPPORTED_TARGETS):

"xero" - returns a list of Xero BankTransactions payloads. Each entry maps to {Type, Reference, Date, BankAccount, Contact, LineAmountTypes, CurrencyCode, LineItems}; CRDT entries become Type=RECEIVE and DBIT entries Type=SPEND. "qbo" - returns a list of QuickBooks Online JournalEntry payloads. Each entry produces a balanced two-line journal (one to the bank account, one to a clearing account; sign flipped on debit entries).

Operator-specific values (account codes, contact identifiers, realm IDs) appear as "OPERATOR_FILL" placeholders so the operator knows exactly what still needs wiring. The response's placeholder_count field reports the total.

NetSuite + SAP S/4HANA targets are tracked as a follow-up in #17.

Use this to tell a user which target values export_journal accepts before invoking it. This lists export destinations only; for the LLM classifier's category vocabulary use list_classify_entry_categories.

Returns the sorted list of valid target arguments accepted by export_journal (["qbo", "xero"] today). NetSuite and SAP S/4HANA support is a tracked follow-up.

This tool takes no parameters.

Use this when you want a semantic, model-driven label for an entry (payroll, fee, refund, …) rather than a deterministic rule match. Because it delegates an LLM completion to the client it is open-world and non-idempotent; for the fixed candidate categories it chooses from, call list_classify_entry_categories first.

Uses the **MCP Sampling** protocol primitive: the server (this process) asks the client (the agent's host application) to perform an LLM completion on the server's behalf, then receives the model's structured response. Keeps every LLM call in the operator's existing model contract (privacy, billing, audit).

The model is asked to choose exactly one category from categories (or camt053_mcp.classify.DEFAULT_CATEGORIES if None is passed) and return a structured {category, confidence, explanation} payload.

Clients that do not support Sampling will get an {"error": "..."} envelope and can fall back to a rules-only classifier.

Use this to quote the built-in category vocabulary to a user before running the LLM classifier. This is a static list lookup (no model call); to actually classify an entry, call classify_entry.

Operators can override the list per call; this tool exposes the default the prompt template ships with so an agent can quote them to the user before invoking the classifier.

This tool takes no parameters.

Use this to get the flat, paginable entry list from a statement. To keep only the entries carrying a given return-reason code use filter_entries; for the full nested document structure use parse_statement.

When limit is None (the default) the full list of entries is returned. When limit is given, a paginated envelope {"total", "offset", "limit", "entries"} is returned instead, exposing the offset:offset + limit slice. A negative offset or limit yields an {"error": ...} payload.

Use this to preview exactly which entries a reversal would touch before calling generate_reversal with the same reason_code. For every entry regardless of reason code use list_entries instead.

When limit is None (the default) the full list of matching entries is returned, preserving the behaviour expected by existing callers. When limit is given, a paginated envelope {"total", "offset", "limit", "entries"} is returned instead, exposing the offset:offset + limit slice. A negative offset or limit yields an {"error": ...} payload.

This is the headline one-shot workflow: pass an incoming statement and a return-reason code and get back the reversal XML (nothing is written to disk). Preview which entries will be reversed first with filter_entries using the same reason_code.

This is the headline one-shot workflow: parse the incoming camt.053, pick the entries with the requested return reason (e.g. AC04 Closed Account), and emit a validated camt.053.001.14 reversal statement.

Returns the validated XML document as a string, or an {"error": ...} payload (serialized) if generation fails.

This tool takes no parameters.

This tool takes no parameters.

Use this first, before any generation or validation call, to discover the exact message_type strings this server accepts (e.g. acmt.001.001.08 Account Opening Instruction). Do not use it to fetch a type's fields or schema -- call get_required_fields or get_input_schema for that.

Returns a list of {"message_type": ..., "name": ...} dictionaries, one per supported message type (e.g. acmt.001.001.08).

This tool takes no parameters.

Use this for a quick checklist of the mandatory columns before building account records. When you need full type/format constraints (not just which fields are required), call get_input_schema instead.

Use this to learn every field, its type, and its constraints before assembling records, or to drive a form/UI. For just the required-field names use get_required_fields; to actually check records against this schema use validate_records.

Use this before generate_message to catch structural/type errors per record and get a row-by-row error report. This checks JSON-Schema shape only; to validate a single financial identifier in isolation use validate_identifier.

Returns a report {"valid": bool, "total": int, "valid_count": int, "errors": [...]}.

Use this for a one-off identifier check with a clear pass/fail. To validate identifiers embedded across a whole batch of account records, prefer validate_records rather than calling this per field.

Returns {"kind": str, "value": str, "valid": bool}.

This is the primary generation tool: pass account records you already hold in memory and receive an XSD-validated XML document; no file is written. Run validate_records first to surface record-level errors, and list_message_types to confirm the message_type string.

Returns the validated XML document as a string, or an {"error": ...} payload (serialized) if generation fails.

This tool takes no parameters.