io.github.sebastienrousseau/structured-address-fix-mcp

Score a single address against a policy and return its findings. Args: address: The postal address to assess. policy_id: The policy to assess against (defaults to cbpr-2026). as_of: The assessment date (YYYY-MM-DD); defaults to today. country_hint: Country to assume when the address has none.

Assess every addressed party in a pacs.008 / pain.001 message. Args: xml: The ISO 20022 message document. policy_id: The policy to assess against (defaults to cbpr-2026). as_of: The assessment date (YYYY-MM-DD); defaults to today.

Classify a postal address as structured, hybrid, or unstructured. Use this for a quick shape check before deciding whether to remediate. For the specific compliance findings under a policy, use ``assess_address`` instead. Args: address: The postal address to classify.

Explain what a finding code means and how to resolve it. Args: code: The finding code to explain.

Report when the structured-address requirement binds, if it yet does. Swift accepted a community request on 27 August 2026 and deferred every payments change in Standards Release 2026, the structured-address requirement among them. No replacement date has been set; Swift will confirm timing by December 2026 at the latest. ``date`` is therefore ``None``. It is left null rather than filled with the withdrawn date because an agent reading this hands the answer to somebody planning a migration, and a date with no force is worse than no date at all. The requirement itself was agreed by the community in 2023 and stands: ``status`` says deferred, not withdrawn. The deferral is Swift's, and covers CBPR+. Domestic market infrastructures set their own timing and several were aligned to the same November date; check the schemes you settle through rather than assuming they moved with Swift.

List every available address policy (rulebook) with its tier. Use this first to discover the ``policy_id`` values the other tools accept (e.g. ``cbpr-2026``, ``sepa``, ``hvps-plus``, ``generic-structured``). Returns a list of ``{"id": ..., "title": ..., "tier": ...}`` objects.

Resolve a country name or code to its ISO 3166-1 alpha-2 code. Accepts English names, common local-language endonyms (Deutschland, España, Nippon), everyday aliases (UK, USA, Holland, UAE), and existing 2- or 3-letter codes. Matching is case-, accent-, and punctuation- insensitive. Args: country_name_or_code: The country name, alias, or code to resolve. Returns a ``{"country_code": "DE"}`` object, or ``{"error": ...}`` when the input matches no known country.

Parse a free-text address into ISO 20022 postal fields. Uses the optional libpostal statistical parser (the ``postal`` binding, which requires the system libpostal C library) when it is installed, and otherwise degrades to this repo's own regex heuristics. Either way the address is mapped to ``StrtNm``, ``BldgNb``, ``PstCd``, ``TwnNm`` and ``Ctry``. The result's ``parser`` field is ``"libpostal"`` or ``"fallback"`` so callers know which path ran. Runs purely on CPU with no network or filesystem access, though the libpostal path depends on an external C library. Args: unstructured_address: The free-text address to parse. country_hint: Country to assume when the text names none. Returns ``{"parser": ..., "address": {StrtNm, BldgNb, PstCd, TwnNm, Ctry}}``.

Return the patch operations remediation would apply (a dry run). Args: xml: The ISO 20022 message document. policy_id: The policy to remediate for (defaults to cbpr-2026). as_of: The assessment date (YYYY-MM-DD); defaults to today.

Propose the compliant form of an address, with explained changes. Returns the findings, the before/after addresses, and the patch operations (each carrying the finding it resolves, the source token, and a confidence score). Args: address: The postal address to remediate. policy_id: The policy to remediate for (defaults to cbpr-2026). as_of: The assessment date (YYYY-MM-DD); defaults to today. country_hint: Country to assume when the address has none.

Assess and remediate every addressed party in a message. Args: xml: The ISO 20022 message document. policy_id: The policy to remediate for (defaults to cbpr-2026). apply: Whether to apply the operations and return patched XML. as_of: The assessment date (YYYY-MM-DD); defaults to today.

Split a street line into street name, building, and sub-building. Handles the leading-number convention (US/UK: ``10 Downing Street``), the trailing-number convention (much of continental Europe: ``Rue de Rivoli 12``), and an optional sub-building marker (``Flat 2``, ``Apt 3B``, ``Suite 400``). When no building number is present the whole line is returned as ``street_name`` (never an error). Args: street_line: The free-text street line to split. Returns ``{"street_name", "building_number", "sub_building"}`` with ``building_number`` / ``sub_building`` set to ``null`` when absent.

Validate an address's post_code against a country's format policy. Supported policies: US (5-digit ZIP or ZIP+4), GB (alphanumeric UK postcode), DE and FR (5 digits), JP (3-then-4 digits). The address is a canonical-field JSON object; only its ``post_code`` is inspected. Args: address: The structured address whose post_code to validate. country_code: The alpha-2 code selecting the policy. Returns ``{"is_compliant": bool, "policy_errors": [...]}``. An unknown country or a missing post_code is reported as non-compliant with a descriptive error rather than raising.