Skip to main content
Glama

Contents

Getting started

The pain001-mcp ecosystem

Library reference

Operational


Related MCP server: camt053-mcp

Install

As a Python library

python -m pip install pain001-mcp

Latest release: v0.0.90: released with pain001 0.0.90. Requires pain001 0.0.90 and pain001-loader-mt101 0.0.90; the 30 MCP tools behave as they did in 0.0.89.

Test unreleased changes on this companion's feat/v<next-version> branch against the matching core branch.


Requirements

Python 3.11 or newer. CI tests 3.11–3.14 on Linux. See toolchain policy; no distro-system-Python claim is made.


Quick Start

pain001-mcp --help
pain001-mcp

The second command starts the stdio MCP server and waits for a client. Configure your client to launch pain001-mcp. Use generated help for optional HTTP/SSE transports; secure network access before exposing any listener.


The pain001-mcp ecosystem

This independently installed companion delegates payment behavior to core. Coordinated versioning does not imply branch changes have been released.

Component

Purpose

Use case

pain001

Generation and validation

Shared contracts and XML engine


Capabilities at a glance

Area

Capability

Status

Integration

Payment validation and generation tools

Released; branch work is test-gated until it ships


Ecosystem comparison

This matrix describes the repository's scope, not an independently benchmarked comparison with competitors.

Project

Generate payment XML

Real settlement

Synthetic bank replies

pain001-mcp

Delegates to core

No

Not a bank service

See docs/COMPARISON.md for the evidence and complete matrix.


Benchmarks

CI smoke-runs benchmarks. No hardware-independent throughput or latency promise is made; use the generated run report for measurements.

Scenario

Result

Environment

Adapter operations

Run-specific

Python, hardware and dependency versions recorded per run

See docs/BENCHMARKS.md for methodology and full results.


Features

The authoritative tool catalogue is generated from the server. It covers validation, identifiers, generation, migration, bank-report parsing, corpus access, review-only record fixes (suggest_record_fix) and the faces (list_faces, project_face). Suggestions require review; financial fields are refused, never guessed. Test unreleased tools with the matching core feature branch. In-tree core MCP is a separate smaller surface.


Configuration

Run pain001-mcp --help for transport, host and port options. Stdio is default. See the tool catalogue for request shapes rather than a copied tool count.


Examples

Run the self-checking scripts under examples/. Tests cover valid and malformed inputs and integration with the core contract.


When not to use pain001-mcp

Not a bank, settlement engine or autonomous payment approver. Review outputs before use. Transport support is not bank certification.


Development

poetry install
poetry run make check
poetry run make security
poetry run python scripts/tool_catalogue.py --check
poetry run python scripts/render_readme.py --check

Coverage is gated at 100% line and branch. See CONTRIBUTING.md and DEVELOPMENT.md. README is generated from the canonical layout and docs/readme-values.json; CI rejects drift.


Security

Treat requests as untrusted. Protect HTTP listeners and avoid real secrets in logs. Tools may read authorized input paths. Corrections never patch IBANs, BICs, amounts or currencies.

Report vulnerabilities according to SECURITY.md.


Documentation

What is pain.001? · User manual · API reference · Developer guide · Family map


Stability guarantees

Versions advance in coordinated 0.0.1 steps with core. The maintainer opens releases; this iteration ships 0.0.90 with the family. Contract and output changes need compatibility review. No stronger platform or stability guarantee is implied.


License

Dual-licensed under Apache-2.0 OR MIT, at your option. See LICENSE. Dependencies retain their own licences.

Available Tools

30 tools
check_payment_fileCheck an existing payment fileA
Read-onlyIdempotent

Check an existing pain.001 or pain.008 file, as pain001 check does.

Use this on a payment file that already exists (one a bank returned,
another system wrote, or an earlier run produced) to learn whether it
is valid and why not. ``validate_records`` checks rows before
generation; this checks the XML itself: its message type's XSD, the
cross-element rules of the message definition, and the scheme
profiles and Schematron preset asked for. Every rung runs, so all
problems come back at once.

Delegates to :func:`pain001.check.check_document`.

Args:
    xml_content: The document as XML text.
    scheme: Scheme profiles, comma-separated, or ``None``.
    schematron: A Schematron preset, or ``None``.

Returns:
    ``{"message_type", "passed", "errors", "warnings", "rungs",
    "findings": [{"rung", "rule", "severity", "message",
    "location"}, ...]}``, or ``{"error": ...}`` when the document
    cannot be checked (not a bundled pain.001 or pain.008, a DTD,
    too large, an unknown scheme or preset) or the installed
    pain001 has no checker.

Inputs: xml_content (required), scheme, schematron. Returns: The verdict, the rungs that ran and every finding, or a refusal.

commit_payment_batchCommit staged payment batchA

Commit a staged payment batch with its confirmation token.

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 a new ``.xml`` file inside the output directory (see
``_output.py``). The token guards against an accidental commit only.

Args:
    stage_id: Staging identifier from stage_payment_batch.
    confirmation_token: Secondary secret confirmation token.
    output_file_path: Optional new XML file in the output directory.

Returns:
    CommitPaymentBatchResult with commit timestamp and fingerprint,
    or {"error": ...}.

Inputs: stage_id (required), confirmation_token (required), output_file_path. Returns: Confirmation of authorized payment batch commit.

convert_mt101Convert MT101 to pain.001 recordsA
Read-onlyIdempotent

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.

Inputs: mt101_text (required). Returns: result

generate_messageGenerate pain XML from recordsA
Read-onlyIdempotent

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. The records are validated first exactly as ``validate_records``
and the pain001 CLI validate them (row contract, every IBAN and BIC
unless ``identifier_checks`` is false, one payment information
block, the JSON Schema); values are never coerced.

Returns the validated XML document as a string, or a JSON-encoded
``{"error": ..., "issues": [...]}`` payload if generation fails;
``issues`` (present when the validation refused the rows) lists each
finding's ``line``, ``column``, ``P001-E...`` ``code`` and
``message``.

Args:
    message_type: A supported ISO 20022 pain message type.
    records: One or more flat payment records.
    identifier_checks: If false, skip the IBAN and BIC checks.

Inputs: records (required), message_type (required), identifier_checks. Returns: result

generate_message_asyncGenerate pain XML (async, large batches)A
Read-onlyIdempotent

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.

Validates in a worker thread, then delegates to
:func:`pain001.async_adapter.generate_xml_string_async`. Returns the
validated XML, or the same JSON-encoded ``{"error", "issues"?}``
payload as ``generate_message``.

Args:
    message_type: A supported ISO 20022 pain message type.
    records: One or more flat payment records.
    identifier_checks: If false, skip the IBAN and BIC checks.

Inputs: records (required), message_type (required), identifier_checks. Returns: result

generate_message_from_fileGenerate pain XML from a CSV fileA
Read-onlyIdempotent

Generate validated pain XML from a payment data file on the local disk.

Use this when the records live in a file rather than in memory; if
you already have them as dicts, call ``generate_message``. The file
is read and validated by the core's own loader and validation
ladder, exactly as ``pain001 generate`` reads it, so the same
path-safety guards apply and the same files are refused; an issue's
``line`` is the file's line (a CSV header is line 1).

Args:
    message_type: A supported ISO 20022 pain message type.
    data_file_path: Path to the payment data file.

Returns:
    The validated XML, or a JSON-encoded ``{"error", "issues"?}``
    payload as ``generate_message`` returns it.

Inputs: message_type (required), data_file_path (required). Returns: result

get_corpus_coverageGet schema coverage reportA
Read-onlyIdempotent

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.

Inputs: version (required). Returns: Schema-path coverage of the corpus for one message edition.

get_corpus_fileGet example corpus fileA
Read-onlyIdempotent

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.

Inputs: version (required), scenario_id (required), variant. Returns: One corpus XML file with the request echoed beside it.

get_corpus_provenanceGet example corpus provenanceA
Read-onlyIdempotent

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.

Inputs: version (required), scenario_id (required), variant. Returns: A scenario's provenance record, as the corpus ships it.

get_input_schemaGet input JSON SchemaA
Read-onlyIdempotent

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.

Inputs: message_type (required). Returns: A JSON Schema (draft 7) for one message type's flat records.

get_required_fieldsGet required fieldsA
Read-onlyIdempotent

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.

Inputs: message_type (required). Returns: result

inspect_templateInspect CSV template columnsA
Read-onlyIdempotent

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.

Inputs: message_type (required). Returns: The bundled CSV template's column names for one message type.

list_corpus_filesList example corpus filesA
Read-onlyIdempotent

List the example files pain001 ships: market scenarios and coverage sets.

Use this to discover the ``scenario_id``, ``version``, and ``variant``
identifiers of the ready-made, validated ISO 20022 files ``pain001``
ships; ``get_corpus_file`` and ``get_corpus_provenance`` accept those
identifiers. 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.

Inputs: kind, country, version. Returns: The example corpus index.

list_facesList facesA
Read-onlyIdempotent

List the faces: the standards a pain.001 document can be projected into.

Use this before ``project_face`` to pick a target and to learn which
bindings it accepts. A binding is a value the payment message does
not carry, such as the UK Open Banking ``ConsentId`` agreed with the
bank; any key a face does not list is refused.

Delegates to :func:`pain001.faces.list_supported_faces`.

Returns:
    ``{"count", "faces": [{"name", "description", "bindings"}, ...]}``,
    or ``{"error": ...}`` when the installed pain001 has no faces.

Inputs: no named parameters. Returns: Every face, or an error when the library has none.

list_message_typesList pain message typesA
Read-onlyIdempotent

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. Returns
message-type codes and display names only; use ``get_required_fields``
or ``get_input_schema`` to inspect fields or schemas.

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

Inputs: no named parameters. Returns: result

list_scheme_profilesList scheme profilesA
Read-onlyIdempotent

List every payment-scheme rulebook profile the core ships.

Use this to choose the ``profile`` for ``validate_payment_scheme`` (or
the ``scheme`` of ``simulate_payment_batch`` and
``stage_payment_batch``) before calling it. Each entry gives the
profile name, a one-line description, the prefix of the rule ids a
rail profile reports (null for the SEPA, cross-border, duplicate and
purpose-mandate profiles), and the public documents it was built
from. Everything comes from the installed pain001; nothing is
restated here.

Returns:
    ``{"count": int, "profiles": [{"name", "description",
    "rule_prefix", "sources"}, ...]}`` in name order.

Inputs: no named parameters. Returns: Every scheme profile the core ships, in name order.

list_supported_formatsList supported input formatsA
Read-onlyIdempotent

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).

Inputs: no named parameters. Returns: result

migrate_recordsMigrate records between versionsA
Read-onlyIdempotent

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": ...}``.

Inputs: records (required), to_version (required), from_version (required). Returns: Records rewritten from one message edition to another.

parse_camt053Parse camt.053 statement fileA
Read-onlyIdempotent

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:
    The first statement's header and entries, every statement under
    ``statements``, or an ``{"error": ...}`` payload on failure.

Inputs: xml_file_path (required), xsd_file_path. Returns: A parsed camt.053: the first statement's fields, and every one.

parse_pain002Parse pain.002 status report fileA
Read-onlyIdempotent

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.

Inputs: xml_file_path (required), xsd_file_path. Returns: A parsed pain.002 status report, as the core library reports it.

project_faceProject pain.001 into a faceA
Read-onlyIdempotent

Project a pain.001 document into another standard's JSON shape.

Use this to turn a payment file into the request body a UK Open
Banking or Berlin Group API expects, or into ISO 20022 element names,
and to see exactly what the target cannot carry: the loss report
lists every source element left out, by indexed path. A face never
invents a value: when the target requires an element the document
lacks, the answer is an ``{"error": ...}`` naming it. To check the
document itself first, use ``validate_xml_against_schema``.

Delegates to :func:`pain001.faces.project_face_text`.

Args:
    xml_content: The pain.001 document as XML text.
    face: The target face.
    version: The edition, or ``None`` to detect it.
    bindings: Side inputs the face accepts, or ``None``.

Returns:
    ``{"face", "version", "payload", "loss_report"}``, or
    ``{"error": ...}`` when the face refuses the document or a
    binding, or the installed pain001 has no faces.

Inputs: face (required), xml_content (required), version, bindings. Returns: The target payload and its loss report, or the face's refusal.

sanitize_to_iso20022_charsetSanitise text to ISO 20022 charsetA
Read-onlyIdempotent

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}``.

Inputs: value (required), charset. Returns: A value and its ISO 20022 charset-clean rendering.

simulate_clearingSimulate clearing network executionA
Read-onlyIdempotent

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": ...}.

Inputs: stage_id (required), clearing_system. Returns: Clearing network simulation verdict and settlement estimation.

simulate_payment_batchSimulate payment batchA
Read-onlyIdempotent

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.

Inputs: records (required), message_type (required), scheme. Returns: Simulation and pre-flight verdict over a payment batch.

stage_payment_batchStage payment batch for simulation and approvalA

Stage a payment batch for simulation and a confirmed commit.

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. A confirmation token that commit_payment_batch requires.

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": ...}.

Inputs: records (required), message_type (required), scheme. Returns: Result of staging a payment batch for simulation and approval.

suggest_record_fixSuggest review-only record fixesA
Read-onlyIdempotent

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.

Inputs: record (required), validation_error (required), message_type. Returns: object

validate_identifierValidate IBAN or BICA
Read-onlyIdempotent

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.

Inputs: kind (required), value (required). Returns: An IBAN or BIC verdict, with the library's message when invalid.

validate_payment_schemeValidate against scheme rulebookA
Read-onlyIdempotent

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`. The ``profile``
parameter lists every profile the installed pain001 ships.

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.

Inputs: records (required), profile. Returns: Verdict against a scheme rulebook profile.

validate_recordsValidate records against schemaA
Read-onlyIdempotent

Validate flat records the way the pain001 CLI and REST API do.

Use this before ``generate_message``: it runs the core's validation
ladder (pain001.validate), so a batch it accepts is one the CLI,
the REST API and ``generate_message`` accept, and a batch it
refuses is refused there too. The ladder checks the row contract
(required fields, amounts, booleans, dates), every IBAN and BIC
(unless ``identifier_checks`` is false), that the rows form one
payment information block, then the message type's JSON Schema
(for example an ISO 4217 currency). For payment-scheme rulebook
checks (SEPA field lengths, charset, etc.) also run
``validate_payment_scheme``.

The row contract and identifier checks refuse the batch as a whole
(``valid_count`` 0) and name the first problems; the schema check
then reports every row. Each error carries ``row`` (from 0),
``line`` (from 1), ``path`` (the field), ``code`` (the core's
stable ``P001-E...`` issue code) and ``message``, which never
repeats the value.

Returns a report ``{"valid": bool, "total": int, "valid_count": int,
"errors": [...]}``, or ``{"error": ...}`` for rows that do not form
one batch, an empty list or an unknown message type.

Args:
    message_type: A supported ISO 20022 pain message type.
    records: One or more flat payment records to validate.
    identifier_checks: If false, skip the IBAN and BIC checks.

Inputs: records (required), message_type (required), identifier_checks. Returns: Verdict over a batch: one entry per violation, plus the counts.

validate_xml_against_schemaValidate XML string against XSDA
Read-onlyIdempotent

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``.

Inputs: xml_content (required), message_type (required). Returns: Verdict of an XML document against the official XSD.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A4.1/5.0

    Scored across 30 tools

    Disambiguation4/5

    Most tools target clearly distinct operations: record validation, scheme validation, XSD validation, full document checking, generation, parsing, corpus inspection, and projection. The main ambiguity is the validation/simulation/staging cluster—validate_records, validate_payment_scheme, simulate_payment_batch, stage_payment_batch, and check_payment_file overlap in purpose, although the descriptions do distinguish their roles.

    Naming Consistency5/5

    All tool names use consistent snake_case and begin with a clear action verb such as list_, get_, validate_, generate_, parse_, stage_, or commit_. Variants and standard codes are handled predictably, e.g. generate_message_async and parse_camt053, with no mixed casing or vague names.

    Tool Count2/5

    With 30 tools, the surface exceeds the typical well-scoped MCP range and the rubric's 25+ threshold. The advanced corpus, faces, migration, staging/clearing, and simulation tools are useful, but they make the server heavy; some could be split into sub-servers or collapsed into higher-level workflow tools.

    Completeness5/5

    Coverage across the ISO 20022 payment lifecycle is excellent: discovery, schema introspection, record and XML validation, generation, migration, parsing, corpus inspection, scheme validation, faces, MT101 conversion, and staged commit/clearing. No obvious dead ends exist for the stated pain.001-focused domain.

    Maintenance

    ActivityActive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      D
      maintenance
      Pactus is an MCP server for parsing and validating ISO 20022 payment messages directly from chat. It exposes nine tools that let AI assistants inspect or validate pacs.008, pacs.002, pain.001, and camt.053 messages — the message types at the centre of the CBPR+ migration — without leaving the conversation.
      9
      17 PyPI
      2
      MIT
    • A
      license
      A
      quality
      B
      maintenance
      MCP server that enables AI agents to parse, validate, and reverse ISO 20022 bank statements, with tools for discovering message types and return reasons.
      24
      190 PyPI
      2
      Apache 2.0
    • A
      license
      A
      quality
      B
      maintenance
      An MCP server that exposes the pacs008 ISO 20022 FI-to-FI Customer Credit Transfer library as tools for AI agents and assistants, enabling generation, validation, and parsing of pacs.008 credit transfer XML messages.
      16
      84 PyPI
      1
      Apache 2.0
    • A
      license
      A
      quality
      D
      maintenance
      An MCP server that provides AI agents with tools to validate SWIFT MT and ISO 20022 MX payment messages, check BIC/IBAN correctness, and convert between MT and MX formats.
      7
      4 npm
      MIT