io.github.sebastienrousseau/pain001-mcp

Commit an authorized staged payment batch with dual-control authorization. Verifies the stage ID and validates the secondary confirmation token using constant-time cryptographic comparison (preventing timing attacks). Transitions the order status from 'staged' to 'committed'. Optionally writes the verified XML payload to the specified destination path. Args: stage_id: Staging identifier from stage_payment_batch. confirmation_token: Secondary secret confirmation token. output_file_path: Optional path to write the committed XML document. Returns: CommitPaymentBatchResult with commit timestamp and fingerprint, or {"error": ...}.

Convert a legacy SWIFT MT101 message into pain.001-ready records. 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 :func:`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.). Args: mt101_text: The MT101 payload as a string. Returns: A list of flat pain.001 records (one per transaction), or an ``{"error": ...}`` dict if the MT101 is missing a mandatory field (``:20:``, ``:30:``, or per transaction ``:21:`` / ``:32B:`` / a named beneficiary) or is otherwise malformed.

Generate a validated ISO 20022 pain XML message from in-memory records. 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. Records are normalized before rendering: 'amount'/'currency' aliases, JSON booleans, and bare 'YYYY-MM-DD' dates are accepted, and nb_of_txs/ctrl_sum are computed from the records. On failure the ``{"error": ...}`` payload lists every missing or invalid field at once. IBAN/BIC values are strictly validated, never coerced. Returns the validated XML document as a string, or a JSON-encoded ``{"error": ...}`` payload if generation fails. Args: message_type: A supported ISO 20022 pain message type. records: One or more flat payment records.

Generate validated pain XML off the event loop, for large batches. 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 :func:`pain001.async_adapter.generate_xml_string_async`. Returns the validated XML, or a JSON-encoded ``{"error": ...}`` payload. Args: message_type: A supported ISO 20022 pain message type. records: One or more flat payment records.

Generate validated pain XML from a CSV file on the local disk. 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 :func:`pain001.csv.load_csv_data.load_csv_data` so the same path-safety guards apply as in the core library. Args: message_type: A supported ISO 20022 pain message type. data_file_path: Path to a CSV file with one record per row. Returns: The validated XML, or a JSON-encoded ``{"error": ...}`` payload.

Return the schema coverage verdict of one message type's coverage set. Use this to check that the shipped coverage files reach every element path and choice branch of an edition's XSD before relying on them to smoke a parser or a mapping. Delegates to :func:`pain001.corpus.coverage_report`. Args: version: The message type. Returns: The ``coverage.json`` content (path and branch counts and percentages, completeness, missing and exempt lists), or ``{"error": ...}`` when the edition has no set or there is no corpus.

Return the XML of one validated example file from the market corpus. Use this to show a model, a tester or a mapping exercise what a correct file for a given country and rail looks like in a given edition. The text is exactly what pain001 ships; it passed the XSD, the ISO MDR rules, the rail profile and the overlay when it was built. Delegates to :func:`pain001.corpus.get_file`. Args: scenario_id: The scenario. version: The message type. variant: The overlay id of a bank variant, else ``None``. Returns: ``{"scenario_id", "version", "variant", "xml"}``, or ``{"error": ...}`` when there is no such file or no corpus.

Return the provenance sidecar of one example file. Use this to know how far to trust a file: the sources it was derived from, the confidence of the evidence (``verified``, ``derived`` or ``assumed``), the validation ladder result per rung, what the builder renamed or dropped to fit the edition, and the file's SHA-256. Delegates to :func:`pain001.corpus.provenance`. Args: scenario_id: The scenario. version: The message type. variant: The overlay id of a bank variant, else ``None``. Returns: The parsed sidecar as a dict, or ``{"error": ...}`` when there is no such file or no corpus.

Return the full JSON Schema for a message type's flat input record. 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``. Args: message_type: A supported ISO 20022 pain message type.

List only the required input field names for a pain message type. 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. Args: message_type: A supported ISO 20022 pain message type.

Return the CSV column headers the message type's bundled template uses. 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. Args: message_type: A supported ISO 20022 pain message type. Returns: ``{"message_type": str, "columns": list[str]}`` or ``{"error": ...}`` if the type is unsupported or no template ships.

List the example files pain001 ships: market scenarios and coverage sets. Use this to discover what ready-made, validated ISO 20022 files exist before calling ``get_corpus_file`` or ``get_corpus_provenance``. Market files are realistic payments per country and rail (``scenario_id`` like ``gb.chaps.property-purchase``); a ``variant`` names the bank overlay a file was built with. Coverage files exercise every element and choice branch of one message type and carry no scenario. Delegates to :func:`pain001.corpus.list_files`. Args: kind: ``market``, ``coverage`` or ``None`` for both. country: Optional two-letter country filter for market files. version: Optional message-type filter. Returns: ``{"count", "files": [{"kind", "scenario_id", "version", "country", "family", "variant", "file"}, ...]}``, or ``{"error": ...}`` when the installed pain001 has no corpus.

List every supported ISO 20022 pain message type and its human name. 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``).

List the on-disk data formats the pain001 loader can read. 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).

Migrate flat payment records between two pain.001 schema versions. 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 :class:`pain001.migration.VersionMapper`. Returns the migrated rows plus a summary of which fields were renamed, derived, or dropped; ``{"error": ...}`` if either version is unsupported. Args: records: Records in the ``from_version`` shape. from_version: Source pain.001 version (e.g. ``"pain.001.001.03"``). to_version: Target pain.001 version (e.g. ``"pain.001.001.09"``). Returns: ``{"records": [...], "migrated": int, "from": str, "to": str}`` or ``{"error": ...}``.

Parse a camt.053 bank-statement XML file on disk into structured data. 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 :func:`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. Args: xml_file_path: Filesystem path to the camt.053 XML statement. xsd_file_path: Optional path to a camt.053 XSD for upfront validation. Returns: A compact dict with the statement header and entry list, or an ``{"error": ...}`` payload on failure.

Parse a pain.002 payment-status report file on disk into structured data. 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 :func:`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. Args: xml_file_path: Filesystem path to the pain.002 XML report. xsd_file_path: Optional path to a pain.002 XSD for upfront validation. Returns: A dict with the group header and transaction statuses, or an ``{"error": ...}`` payload on failure.

Sanitise one free-text field to a SWIFT / ISO 20022 character set. 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``. Two character sets are supported via ``charset``: * ``"SWIFT_X"`` (default, backward-compatible) - the basic set used in most ISO 20022 / pain.001 fields. Delegates to :func:`pain001.sanitize_to_charset`. * ``"SWIFT_Z"`` - the SWIFT extended set, a strict superset of X that also permits ``= ! " % & * < > ; { @ # _`` (used in narrative / envelope fields). It does not permit ``|`` or ``}``. In both cases accents are transliterated (``é`` -> ``e``) and any remaining out-of-set character is replaced with a space. The result includes flags for whether the original was already valid and whether it changed - useful for surfacing the change to the user before writing it back to a record. Args: value: The text to sanitise. charset: ``"SWIFT_X"`` (default) or ``"SWIFT_Z"``. Returns: ``{"value": str, "sanitised": str, "was_valid": bool, "changed": bool}``.

Simulate settlement and clearing network execution for a staged batch. Evaluates network-specific rulebooks and clearing constraints: - EPC-SEPA: EUR currency mandate, SEPA-zone IBAN prefixes, SLEV charge bearer. - FedNow: USD instant gross settlement eligibility. - US-ACH: USD next-day clearing cycle routing. - SWIFT-MX: Cross-border correspondent banking BIC routing. - CHAPS: Same-day RTGS high-value GBP clearing. - BACS: Three-day GBP direct credit clearing. Args: stage_id: Staging identifier from stage_payment_batch. clearing_system: Clearing rail profile to simulate. Returns: SimulateClearingResult with verdict (ACCEPTED / REJECTED), detailed checks, and estimated settlement window, or {"error": ...}.

Simulate and pre-flight a payment batch before XML generation. Performs comprehensive pre-flight verification without generating XML or staging files: 1. Validates records against the message type's JSON Schema. 2. Validates records against an optional payment-scheme rulebook. 3. Computes control sums grouped by currency. 4. Calculates unique debtor and creditor account counts. 5. Detects intra-batch duplicate transactions (same debtor, creditor, amount, currency, and execution date). Returns a structured verdict with totals, sums by currency, duplicate findings, and schema/scheme errors. Args: message_type: A supported ISO 20022 pain message type. records: One or more flat payment records to simulate. scheme: Optional payment scheme profile to validate against.

Stage a payment batch for simulation and dual-control approval. Creates an in-memory staged payment order with zero fund movement and a 1-hour expiration window. Computes: 1. Schema validation against the message type's JSON Schema. 2. Optional scheme compliance verification (SEPA, BACS, etc.). 3. Multi-currency control sums and fee estimation. 4. Multi-factor risk scoring (detecting duplicates, high transaction amounts, and generic remittance narratives). 5. In-memory XML compilation and SHA-256 fingerprinting. 6. Cryptographic dual-control confirmation token for subsequent authorization. Args: message_type: A supported ISO 20022 pain message type. records: One or more flat payment records to stage. scheme: Optional payment scheme profile to validate against. Returns: StagedBatchResult with staging metadata, risk assessment, fingerprint, and confirmation token, or {"error": ...}.

Suggest deterministic, review-only fixes to non-financial fields. Returns patches or a cannot_autofix reason. Never changes IBANs, BICs, accounts, amounts or currencies, even for whitespace. Review every candidate and validate the full record before generating a payment. Args: record: A flat payment record, left unchanged. validation_error: Finding with field (or path) and rule keys. message_type: Supported schema supplying trusted field bounds.

Validate a single financial identifier (IBAN or BIC). 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``). Args: kind: One of ``"iban"`` or ``"bic"`` (case-insensitive). value: The identifier value to check.

Validate records against a payment-scheme rulebook (e.g. SEPA). 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 :func:`pain001.validate_scheme`. Supported profiles: ``sepa-sct``, ``sepa-sdd``, ``sepa-inst``, ``xborder-ct``. Args: records: Payment records as a list of flat dicts. profile: The scheme profile name. Returns: ``{"profile", "is_valid", "violations": [...]}`` with structured ``violations`` (each with ``rule``, ``severity``, ``field``, ``message``, ``remediation`` keys), or ``{"error": ...}`` for an unknown profile.

Validate flat records against a message type's input JSON Schema. 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": [...]}``. Args: message_type: A supported ISO 20022 pain message type. records: One or more flat payment records to validate.

Validate a raw pain.001 / pain.008 XML string against its official XSD. 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 :func:`pain001.xml.validate_via_xsd.validate_xml_string_via_xsd`. Args: xml_content: The XML document as a string. message_type: A supported ISO 20022 pain message type. Returns: ``{"valid": bool, "message_type": str, "error": str?}`` - ``error`` is present only when ``valid`` is ``False``.