io.github.sebastienrousseau/pacs008-mcp

Classify a postal address as structured, hybrid, or unstructured. Use this to see where an address stands against the SWIFT structured-address rule: ``structured`` (town + country + structured detail, no free-form lines), ``hybrid`` (town + country + 1-2 free-form ``adr_line`` lines, the minimum CBPR+ UG2026 bar), or ``unstructured`` (free-form only — rejected from the cliff date). To check acceptability under a policy use ``validate_address``; to upgrade legacy lines use ``repair_address``. Returns ``{"classification": str, "is_structured": bool, "is_hybrid": bool, "is_unstructured": bool, "has_structured_fields": bool}`` or an ``{"error": ...}`` payload. Args: address: The postal address as a dict of snake_case fields.

Convert a legacy SWIFT MT103 into pacs.008-ready flat records. This is the SWIFT MT-to-MX migration path (correspondent-banking MT103 coexistence with ISO 20022 ends November 2025): parse an MT103 text payload and get back the flat pacs.008 record(s) that can be fed straight into ``validate_records`` / ``generate_message``. An MT103 carries exactly one transfer, so the ``records`` list always holds a single record. No file is read or written. Returns ``{"message_type": "pacs.008.001.08", "records": [{...}]}`` with the parsed flat record, or an ``{"error": ...}`` payload if the MT103 is missing a mandatory field (``:20:``, ``:32A:``, beneficiary) or malformed. Args: mt103_text: The MT103 payload as a string.

Generate a validated ISO 20022 pacs XML message from in-memory records. This is the primary generation tool: pass payment records you already hold in memory and receive an XSD-validated XML document; no file is written. Run ``validate_records`` first to surface record-level errors, and ``list_message_types`` to confirm the ``message_type`` string. Returns the validated XML document as a string, or an ``{"error": ...}`` payload (serialized) if generation fails. Args: message_type: A supported ISO 20022 pacs message type. records: One or more flat payment records.

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 check records against this schema use ``validate_records``. Args: message_type: A supported ISO 20022 pacs message type.

List only the required input field names for a pacs message type. Use this for a quick checklist of the mandatory columns before building payment records. For full type/format constraints (not just which fields are required), call ``get_input_schema`` instead. Args: message_type: A supported ISO 20022 pacs message type.

Return the rule attributes of a scheme / usage-guideline profile. Use this to inspect a rail's constraints -- whether the UETR is mandatory, the permitted charge bearers, remittance-info length cap, per-message transaction cardinality, pinned message versions, and which parties must carry an LEI -- before assembling or validating a batch. Args: scheme: A registered scheme profile name (see ``list_schemes``).

List every supported ISO 20022 pacs 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 (e.g. ``pacs.008.001.08`` FI-to-FI Customer Credit Transfer). To learn a type's required fields or full schema, call ``get_required_fields`` or ``get_input_schema`` instead. Returns a list of ``{"message_type": ..., "name": ...}`` dictionaries, one per supported message type.

List every registered scheme / usage-guideline profile. Scheme profiles (CBPR+, HVPS+, Fedwire, CHAPS, T2 RTGS, SCT Inst, generic) layer rail-specific rules on top of base ISO 20022. Use this to discover the ``scheme`` names accepted by ``get_scheme`` and ``validate_scheme``. Registry aliases (e.g. ``cbpr+``, ``cbprplus``) collapse to their canonical profile, so each profile appears exactly once. Returns a list of ``{"scheme": ..., "name": ...}`` dictionaries.

Parse and classify an inbound ISO 20022 XML message. Use this on the receiving side to identify what a message is -- its ``msg_def_idr`` (e.g. ``pacs.002.001.10``), family, version, and any Business Application Header -- before processing it. Handles both bare ``Document`` messages and BAH-wrapped envelopes. Returns a dict with ``msg_def_idr``, ``msg_family``, ``version``, ``root_local_name``, ``namespace_uri``, ``envelope_wrapped`` and ``bah``. Args: xml: The raw inbound XML message.

Upgrade legacy unstructured address lines toward hybrid/structured form. Experimental country-aware repair (``GB``, ``US``, ``DE``, ``FR``, ``JP`` have dedicated heuristics; other countries get a best-effort pass promoting the last line to a town). Use this to lift pre-cliff data over the November 14, 2026 bar; audit the output before submitting, and keep both the original and derived address in your audit trail. Returns ``{"address": {...}, "classification": str, "is_structured": bool, "is_hybrid": bool}`` (so you can see the unstructured -> hybrid / structured upgrade) or an ``{"error": ...}`` payload. Args: lines: Legacy unstructured address lines. country: ISO 3166-1 alpha-2 country code driving the heuristics.

Validate one postal address against an address policy. Use this to decide whether an address will clear a rail. The default ``hybrid_or_structured`` policy is the November 14, 2026 cliff rule (SWIFT CBPR+, HVPS+, T2 RTGS, CHAPS, Fedwire, Lynx): it rejects fully unstructured addresses. Findings mirror the library's pipeline severity (a policy rejection is a blocking finding). Returns ``{"policy": str, "classification": str, "is_acceptable": bool, "findings": [{"severity": str, "message": str}, ...]}`` or an ``{"error": ...}`` payload. Args: address: The postal address as a dict of snake_case fields. policy: The validation policy to enforce (see the enum values).

Batch-validate every party address across a list of payment rows. Use this before ``generate_message`` to catch addresses that will be rejected at the rail. The default ``hybrid_or_structured`` policy enforces the November 14, 2026 cliff. Each finding is reported per offending ``(row, party)`` pair. Returns ``{"policy": str, "is_valid": bool, "total": int, "errors": [{"row": int, "party": str, "severity": str, "message": str, "classification": str}, ...]}`` or an ``{"error": ...}`` payload. Args: addresses: One or more payment-row dicts (see the field description). policy: The validation policy to enforce (see the enum values).

Validate flat payment records against a message type's JSON Schema. 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; to check a batch against a rail's usage guidelines use ``validate_scheme``. Returns a report ``{"is_valid": bool, "total": int, "valid": int, "errors": [...]}``. Args: message_type: A supported ISO 20022 pacs message type. records: One or more flat payment records to validate.

Validate payment records against a scheme's usage-guideline rules. Use this to check a batch against a rail's rulebook (CBPR+, HVPS+, Fedwire, CHAPS, T2 RTGS, SCT Inst) -- charge-bearer restrictions, UETR presence, remittance-info length, and per-message transaction cardinality. This is complementary to ``validate_records`` (JSON-Schema shape). Returns ``{"scheme": str, "is_valid": bool, "total": int, "violations": [...]}``. Args: scheme: A registered scheme profile name (see ``list_schemes``). records: One or more flat payment records to check.

Validate a raw XML string against a message type's bundled XSD. Use this to check an externally produced XML document against the official ISO 20022 schema. To generate a document that is already XSD-validated, use ``generate_message`` instead. Returns ``{"message_type": str, "is_valid": bool}``. Args: message_type: A supported ISO 20022 pacs message type. xml: The raw XML document to validate.

Verify a BIC structurally, optionally enriched by a directory lookup. Two-stage verification. First an OFFLINE ISO 9362 structural check (via the pacs008 library): confirms the 8- or 11-character shape and that the country code (chars 5-6) is a valid ISO 3166-1 alpha-2 code. A malformed BIC returns ``{"bic": ..., "is_structurally_valid": False, "error": ...}`` and stops there. Then, only if a directory endpoint is configured (the ``directory_url`` argument or the ``PACS008_BIC_DIRECTORY_URL`` environment variable), the tool performs a read-only HTTP GET against that endpoint and folds whatever institution ``name``/``city``/``country``/``status`` it returns into a ``directory`` sub-dict. There is no free authoritative SWIFT BIC directory, so with NO endpoint configured the tool returns the structural result plus a ``note`` and ``directory: null`` -- it never fabricates a bank name. Online lookups require the optional ``online`` extra (``pip install 'pacs008-mcp[online]'``, which pulls in ``httpx``); without it the tool still returns the structural result plus an ``error`` explaining the missing extra. Endpoint 4xx/5xx responses and transport failures are likewise reported as a graceful ``error`` alongside the structural result. Returns a dict with ``bic``, ``is_structurally_valid``, ``bank_code``, ``country_code``, ``location_code``, ``branch_code``, ``length`` and either ``directory`` (a dict of institution details, or ``null``) plus, when applicable, ``note`` / ``error``. Args: bic: The BIC / SWIFT code to verify. directory_url: Optional directory endpoint for online enrichment.