Source code for pain001_mcp._catalogue

# 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 get_input_schema(message_type: _MessageType) -> SchemaResult: """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. """ try: return cast(SchemaResult, _load_schema(message_type)) except ValueError as exc: return {"error": str(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 list_supported_formats() -> list[dict]: """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). """ return [dict(fmt) for fmt in _SUPPORTED_FORMATS]
[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." )