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

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.

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.

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.

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.

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.

Args:
    message_type: A supported ISO 20022 pain message type.
    records: One or more flat payment records.

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

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.

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.

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.

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.

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.

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.

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

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

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

Args:
    value: The text to sanitise.

Returns:
    ``{"value": str, "sanitised": str, "was_valid": bool, "changed": bool}``.

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.