pain001-mcp
Expose pain001 ISO 20022 payment tooling through MCP for discovering schemas, validating/generating pain XML, parsing bank reports, and simulating/staging payment batches.
Discover supported pain.001/pain.008 message types, required fields, JSON schemas, CSV template columns, input formats, scheme profiles, corpus files, and projection faces.
Validate flat records, individual IBAN/BIC identifiers, payment-scheme rulebooks, raw XML against XSD, and existing payment files; suggest review-only fixes for non-financial fields.
Generate XSD-validated pain XML from in-memory records, async large batches, or local CSV/SQLite/JSON/JSONL/Parquet files; migrate records between pain.001 versions.
Parse camt.053 statements and pain.002 status reports; retrieve corpus XML/provenance/coverage; convert SWIFT MT101 to pain.001 records.
Sanitize text to ISO 20022/SWIFT charsets and project pain.001 documents into Berlin Group, ISO 2018, or UK Open Banking faces with loss reports.
Simulate/pre-flight batches, stage payment batches with risk/fee/fingerprint/confirmation token, simulate clearing across rails, and commit staged batches for approval workflows, not actual settlement.
Generates and validates SEPA payment initiation messages (pain.001 for credit transfers, pain.008 for direct debits) and applies scheme rulebooks (SEPA SCT, SDD, INST, B2B) via dedicated tools.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@pain001-mcp Generate a credit transfer XML for EUR 1000 to DE89370400440532013000"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Contents
Getting started
Install: PyPI and source
Requirements: toolchain floor, platforms
Quick Start: use the installed companion
The pain001-mcp ecosystem
The pain001-mcp ecosystem: core and this companion
Library reference
Capabilities at a glance: the current surface by theme
Ecosystem comparison: short matrix; full table at
docs/COMPARISON.mdBenchmarks: headline numbers; full table at
docs/BENCHMARKS.mdFeatures: module-level capability list
Configuration: core options
Examples: runnable example index
Operational
When not to use pain001-mcp: limitations
Development: make targets, fuzzing, CI
Security: guarantees and compliance
Documentation: all reference docs
Stability guarantees: SemVer axis, output stability, minimum toolchain discipline
Related MCP server: camt053-mcp
Install
As a Python library
python -m pip install pain001-mcpLatest 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-mcpThe 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 |
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 --checkCoverage 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 toolscheck_payment_fileCheck an existing payment fileARead-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 recordsARead-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 recordsARead-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)ARead-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 fileARead-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 reportARead-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 fileARead-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 provenanceARead-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 SchemaARead-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 fieldsARead-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 columnsARead-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 filesARead-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 facesARead-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 typesARead-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 profilesARead-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 formatsARead-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 versionsARead-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 fileARead-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 fileARead-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 faceARead-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 charsetARead-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 executionARead-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 batchARead-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 fixesARead-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 BICARead-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 rulebookARead-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 schemaARead-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 XSDARead-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
Scored across 30 tools
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.
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.
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.
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
Related MCP Connectors
The Mercado Pago MCP Server implements the Model Context Protocol to provide AI agents and LLMs with access to Mercado Pago's APIs and tools within compatible development environments. It acts as an intermediary that translates Mercado Pago resources into executable functions (tools) that AI applications can invoke to perform actions and automate flows. The server simplifies integration, enables using documentation to implement or improve code, and optimizes operations through natural language interactions without manual implementations.
A comprehensive Model Context Protocol (MCP) server that enables AI assistants to interact with yo…
MCP server for your apps' tools and custom tools, plus hosted AI agents and approval-gated workflows
MCP server for secureFlows: token-free URL builders and integration-linting tools for AI agents.
Related MCP Servers
- AlicenseAqualityDmaintenancePactus 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.917 PyPI2MIT
- AlicenseAqualityBmaintenanceMCP server that enables AI agents to parse, validate, and reverse ISO 20022 bank statements, with tools for discovering message types and return reasons.24190 PyPI2Apache 2.0
- AlicenseAqualityBmaintenanceAn 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.1684 PyPI1Apache 2.0
- AlicenseAqualityDmaintenanceAn 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.74 npmMIT