Python API reference

The standalone server’s importable Python surface (used by the runnable examples and any agent that wraps the FastMCP instance directly).

pacs008-mcp: a Model Context Protocol server for the pacs008 library.

Tool / resource / prompt module

Model Context Protocol (MCP) server for Pacs008.

This server exposes the Pacs008 library’s ISO 20022 pacs.008 (FI-to-FI Customer Credit Transfer) capabilities as MCP tools so that any MCP-compatible client (Claude Desktop, IDEs, agents) can discover message types and scheme profiles, validate records against the JSON Schema and against a rail’s usage guidelines, generate validated XML, validate raw XML against the bundled XSD, and parse inbound ISO 20022 messages.

Every tool is a thin, typed wrapper over the pacs008 library – the same package used by the CLI and REST API – so all interfaces behave identically. Tools return JSON-serializable data (dicts, lists, or strings); on a ValueError they return an {"error": ...} payload rather than raising.

Launching the server:

• As a console script:

  pacs008-mcp
  

• Programmatically:

  from pacs008_mcp.server import main
  main()
  

• In an MCP client config (e.g. Claude Desktop claude_desktop_config.json):

  {
    "mcpServers": {
      "pacs008": {
        "command": "pacs008-mcp"
      }
    }
  }
  

stdio by default; --transport streamable-http or --transport sse listens on --host/--port instead. See pacs008_mcp._cli.

pacs008_mcp.server.build_pacs008_message(goal='')

Guided prompt teaching the recommended tool order for a pacs.008.

The MCP client sends this to the model to establish the correct build-and-validate sequence so it uses the server’s tools in order instead of guessing a message type or skipping a validation gate.

Parameters:

goal (str) – The payments task in plain language.

Return type:

str

Returns:

A prompt string instructing the model how to proceed.

pacs008_mcp.server.classify_address(address)

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.

Parameters:

address (dict) – The postal address as a dict of snake_case fields.

Return type:

dict

pacs008_mcp.server.convert_mt103(mt103_text)

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.

Parameters:

mt103_text (str) – The MT103 payload as a string.

Return type:

dict

pacs008_mcp.server.generate_message(message_type, records)

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.

Parameters:

• message_type (str) – A supported ISO 20022 pacs message type.

• records (list[dict]) – One or more flat payment records.

Return type:

str

pacs008_mcp.server.get_input_schema(message_type)

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.

Parameters:

message_type (str) – A supported ISO 20022 pacs message type.

Return type:

dict

pacs008_mcp.server.get_required_fields(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.

Parameters:

message_type (str) – A supported ISO 20022 pacs message type.

Return type:

list[str]

pacs008_mcp.server.get_scheme(scheme)

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.

Parameters:

scheme (str) – A registered scheme profile name (see list_schemes).

Return type:

dict

pacs008_mcp.server.list_message_types()

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.

Return type:

list[dict]

pacs008_mcp.server.list_schemes()

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.

Return type:

list[dict]

pacs008_mcp.server.main(argv=None)

Run the pacs008 MCP server (the pacs008-mcp entry point).

stdio by default; --transport streamable-http or --transport sse listens on --host/--port instead. See pacs008_mcp._cli.

Parameters:

argv (list[str] | None) – Command-line arguments; None reads sys.argv[1:].

Return type:

None

pacs008_mcp.server.message_types_resource()

Expose the supported pacs message types as a JSON resource.

Returns the same catalogue as the list_message_types tool – each supported ISO 20022 pacs message_type and its human name – serialised as JSON, so an agent can load the accepted type set as reference context without a tool call. Mirrors list_message_types, which takes no arguments and cannot fail, so no error envelope is needed.

Return type:

str

pacs008_mcp.server.parse_message(xml)

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.

Parameters:

xml (str) – The raw inbound XML message.

Return type:

dict

pacs008_mcp.server.repair_address(lines, country)

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.

Parameters:

• lines (list[str]) – Legacy unstructured address lines.

• country (str) – ISO 3166-1 alpha-2 country code driving the heuristics.

Return type:

dict

pacs008_mcp.server.scheme_resource(scheme_id)

Expose one scheme profile’s rule attributes as a templated JSON resource.

A templated MCP Resource returning the same payload as the get_scheme tool for a single scheme: the UETR requirement, permitted charge bearers, remittance-info length cap, per-message transaction cardinality, pinned message versions, and LEI-required parties. Lets an agent pin pacs008://scheme/cbpr_plus as stable reference context for the rail it is building against. An unknown scheme_id yields the same {"error": ...} payload as get_scheme (serialised), so no separate error handling is added here.

Parameters:

scheme_id (str) – A registered scheme profile name (see list_schemes).

Return type:

str

pacs008_mcp.server.schemes_resource()

Expose the registered scheme / usage-guideline profiles as JSON.

Returns the same catalogue as the list_schemes tool – each canonical rail profile (CBPR+, HVPS+, Fedwire, CHAPS, T2 RTGS, SCT Inst, generic) – serialised as JSON, so an agent can load the accepted scheme set as reference context without a tool call. Mirrors list_schemes, which takes no arguments and cannot fail, so no error envelope is needed.

Return type:

str

pacs008_mcp.server.validate_address(address, policy='hybrid_or_structured')

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.

Parameters:

• address (dict) – The postal address as a dict of snake_case fields.

• policy (str) – The validation policy to enforce (see the enum values).

Return type:

dict

pacs008_mcp.server.validate_addresses(addresses, policy='hybrid_or_structured')

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.

Parameters:

• addresses (list[dict]) – One or more payment-row dicts (see the field description).

• policy (str) – The validation policy to enforce (see the enum values).

Return type:

dict

pacs008_mcp.server.validate_records(message_type, records)

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

Parameters:

• message_type (str) – A supported ISO 20022 pacs message type.

• records (list[dict]) – One or more flat payment records to validate.

Return type:

dict

pacs008_mcp.server.validate_scheme(scheme, records)

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

Parameters:

• scheme (str) – A registered scheme profile name (see list_schemes).

• records (list[dict]) – One or more flat payment records to check.

Return type:

dict

pacs008_mcp.server.validate_xml(message_type, xml)

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}, or {"error": ...} for an unsupported type or DTD entities; a bad year is invalid.

Parameters:

• message_type (str) – A supported ISO 20022 pacs message type.

• xml (str) – The raw XML document to validate.

Return type:

dict

pacs008_mcp.server.verify_bic_online(bic, directory_url=None)

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.

Parameters:

• bic (str) – The BIC / SWIFT code to verify.

• directory_url (str | None) – Optional directory endpoint for online enrichment.

Return type:

dict