# SPDX-FileCopyrightText: 2023-2026 Sebastien Rousseau <sebastian.rousseau@gmail.com>
# SPDX-License-Identifier: Apache-2.0 OR MIT
"""Discovery tools: message types, fields, schemas, templates, formats.
Also the ``pain001://schema/{message_type}`` resource and the
``build_payment_batch`` prompt, which point an agent at these tools.
"""
import csv
import io
from typing import cast
from pain001.constants import valid_xml_types
from pain001.templates import DEFAULT_TEMPLATE_REGISTRY
from pain001_mcp._common import (
_check_message_type,
_load_schema,
_MessageType,
_template_dir,
)
from pain001_mcp._shapes import SchemaResult, TemplateResult
# Data formats the underlying ``pain001`` library can load. Surfaces what an
# agent can offer the user without poking the filesystem.
_SUPPORTED_FORMATS = [
{"id": "csv", "name": "Comma-Separated Values", "extension": ".csv"},
{"id": "sqlite", "name": "SQLite database", "extension": ".db"},
{"id": "json", "name": "JSON array of records", "extension": ".json"},
{
"id": "jsonl",
"name": "Newline-delimited JSON (one record per line)",
"extension": ".jsonl",
},
{
"id": "parquet",
"name": "Apache Parquet (requires pain001[parquet] extra)",
"extension": ".parquet",
},
]
def _display_name(message_type: str) -> str:
"""Return the core's ISO 20022 name for a type, else the type itself.
The name is ``TemplateMetadata.display_name`` (pain001 >= 0.0.81),
such as ``Customer Credit Transfer Initiation V09``, so this server
never restates the names. A type the registry does not describe keeps
its code rather than failing the whole listing.
"""
try:
return str(
DEFAULT_TEMPLATE_REGISTRY.get_template(message_type).display_name
)
except KeyError:
return message_type
[docs]
def list_message_types() -> list[dict]:
"""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``).
"""
return [
{"message_type": mt, "name": _display_name(mt)}
for mt in valid_xml_types
]
[docs]
def get_required_fields(message_type: _MessageType) -> list[str]:
"""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.
"""
try:
schema = _load_schema(message_type)
required = schema.get("required", [])
return list(required)
except ValueError as exc:
return [f"error: {exc}"]
[docs]
def inspect_template(message_type: _MessageType) -> TemplateResult:
"""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.
"""
try:
message_type = _check_message_type(message_type)
sample = _template_dir(message_type) / "template.csv"
if not sample.is_file():
raise ValueError(f"No bundled CSV template for {message_type}")
reader = csv.reader(io.StringIO(sample.read_text(encoding="utf-8")))
columns = next(reader, [])
return {"message_type": message_type, "columns": list(columns)}
except ValueError as exc:
return {"error": str(exc)}
[docs]
def schema_resource(message_type: _MessageType) -> str:
"""Expose the official XSD schema text for a message type as a resource.
MCP clients can subscribe to or fetch ``pain001://schema/{type}`` to
pull the canonical XSD without having to install pain001 themselves.
Args:
message_type: A supported ISO 20022 pain message type.
Returns:
The XSD schema text. Raises ``ValueError`` for an unsupported type.
"""
message_type = _check_message_type(message_type)
xsd = _template_dir(message_type) / f"{message_type}.xsd"
return xsd.read_text(encoding="utf-8")
[docs]
def build_payment_batch(
message_type: _MessageType = "pain.001.001.09",
) -> str:
"""Guided prompt for assembling a compliant payment batch.
The MCP client sends this to the model to teach it the recommended
tool order: discover columns, build rows, validate, then generate.
Args:
message_type: The target ISO 20022 pain message type.
Returns:
A prompt string instructing the model how to proceed.
"""
return (
f"Help me build a compliant {message_type} batch. First call "
f"inspect_template('{message_type}') for the column layout, "
"then call get_required_fields and get_input_schema for the "
"typed contract. Assemble one dict per payment, validate them "
"with validate_records (and validate_payment_scheme for SEPA), "
"then call generate_message to produce the XML."
)