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

structured-address-fix-mcp: An MCP Server for ISO 20022 Postal Addresses

[![PyPI Version][pypi-badge]][07] [![Python Versions][python-versions-badge]][07] [![License][license-badge]][01] [![Tests][tests-badge]][tests-url] [![Quality][quality-badge]][quality-url] [![OpenSSF Scorecard][scorecard-badge]][scorecard-url] [![Documentation][docs-badge]][docs-url] [![Glama MCP server score][glama-badge]][glama-url]

A [Model Context Protocol][mcp] server that exposes the [structured-address-fix][core] ISO 20022 postal-address library as tools for AI agents and assistants — classify an address's shape, assess it against a scheme policy, and remediate it (or a whole pacs.008 / pain.001 message) into the structured form the November 2026 cutover requires, all from your favourite MCP client.

The 14 November 2026 cliff. On that date CBPR+, HVPS+, T2, CHAPS, and Fedwire stop accepting fully unstructured postal addresses: a payment whose debtor/creditor address is a free-text blob is rejected. structured-address-fix-mcp puts the readiness check and the fix in front of your agent — assess_message flags the offending parties, remediate_message proposes the compliant form, and get_cutover_date reports the binding date. v0.0.6, stdio, streamable HTTP and SSE transports, 13 tools, Python 3.12+.

Contents

• Overview
• The ISO 20022 MCP Suite
• Install
• Quick Start
• Transports — stdio, streamable HTTP (2026-07-28 and 2025-11-25) and SSE from one command line
• Tools
• Using the tools
• Related MCP Servers
• When not to use structured-address-fix-mcp
• Development
• Security
• Documentation
• License
• Contributing
• Acknowledgements

Overview

The [Model Context Protocol][mcp] (MCP) is an open standard that lets AI agents and assistants discover and call external tools in a uniform way. structured-address-fix-mcp is an MCP server that turns the [structured-address-fix][core] library into a set of first-class agent tools, so an assistant can read a postal address — or every addressed party in an ISO 20022 pacs.008 / pain.001 message — and bring it into line with the structured-address rules that become mandatory on 14 November 2026, directly from a conversation.

The headline capability is the one-shot remediation workflow: assess a message, find the parties whose addresses will be rejected at the cliff, and emit the compliant form with each change explained and confidence-scored.

Every tool is a thin, typed wrapper over structured_address_fix.services — the single shared facade also used by the CLI — so all interfaces behave identically. Tools return JSON-serialisable data; on an error they return an {"error": ...} payload rather than raising.

• Website: https://sebastienrousseau.github.io/structured-address-fix/
• Source code: https://github.com/sebastienrousseau/structured-address-fix-mcp
• Bug reports: https://github.com/sebastienrousseau/structured-address-fix-mcp/issues

flowchart LR
    A["MCP client<br/>(Claude Desktop, IDE, agent)"] -->|stdio, streamable HTTP or SSE| B["structured-address-fix-mcp"]
    B -->|delegates to| C["structured_address_fix.services"]
    C -->|classify + assess + remediate| D["ISO 20022 postal addresses<br/>(pacs.008 / pain.001)"]

The ISO 20022 MCP Suite

structured-address-fix-mcp is the postal-address specialist in a set of coordinated, vendor-neutral MCP servers for the ISO 20022 migration. Dependency ranges are kept aligned across the suite, so the servers co-install cleanly in a single Python environment: start with one, add the rest as your workflow grows.

The suite also includes the iso20022-mcp gateway (unified search / describe / validate / generate / parse meta-tools across the whole message catalogue) and acmt001-mcp (account management). Where pacs008-mcp lints a message for address problems, structured-address-fix-mcp is the specialist that classifies, assesses, and fixes the addresses themselves against per-scheme policies.

Install

structured-address-fix-mcp runs on macOS, Linux, and Windows and requires Python 3.12+ and pip. It pulls in the core structured-address-fix library and the MCP SDK automatically.

python -m pip install structured-address-fix-mcp

Using an isolated virtual environment (recommended)

python -m venv venv
source venv/bin/activate        # macOS/Linux
venv\Scripts\activate           # Windows
python -m pip install -U structured-address-fix-mcp

Quick Start

For the 10-minute install → MCP client config → first conversation tutorial, see docs/quickstart.md.

Launch the server over stdio (the default transport):

structured-address-fix-mcp

Register it with any MCP client (e.g. Claude Desktop) by adding it to the client's configuration:

{
  "mcpServers": {
    "structured-address-fix": { "command": "structured-address-fix-mcp" }
  }
}

The command speaks MCP on stdin/stdout by default — it is meant to be launched by an MCP client, not used interactively. For a shared deployment or an HTTP client, see Transports. The agent can then call the tools below to assess and remediate postal addresses on demand.

Transports

One command line, three transports:

--host and --port change the bind address (defaults 127.0.0.1 and 8000). The HTTP transports carry no authentication of their own: bind loopback, or put the server behind a gateway you trust before binding a routable address. Every release is verified over streamable HTTP with scout in both protocol eras and over SSE with the MCP SDK client; see ADR 0001.

{
  "mcpServers": {
    "structured-address-fix": { "url": "http://127.0.0.1:8000/mcp" }
  }
}

Tools

All tools delegate to the shared structured_address_fix.services layer, so they behave identically to the CLI. Tools return JSON-serialisable data; on a domain, validation, or value error they return an {"error": ...} payload.

• list_policies — List every available address policy (rulebook) with its tier (e.g. cbpr-2026, sepa, hvps-plus, generic-structured)
• classify_address — Classify a postal address as structured, hybrid, or unstructured (a quick shape check)
• assess_address — Score a single address against a policy and return its findings
• assess_message — Assess every addressed party in a pacs.008 / pain.001 message against a policy
• remediate_address — Propose the compliant form of an address, with the before/after and confidence-scored patch operations
• remediate_message — Assess and remediate every addressed party in a message; optionally apply the operations and return the patched XML
• preview_patch — Return the patch operations remediation would apply to a message (a dry run)
• explain_finding — Explain what a finding code (e.g. SAF001) means and how to resolve it
• get_cutover_date — Return the binding November 2026 structured-address cutover date and the scheme that sets it
• normalize_country_code — Resolve a country name or code to its ISO 3166-1 alpha-2 code, accepting English names, local endonyms (Deutschland, España, Nippon) and everyday aliases (UK, USA, Holland, UAE)
• split_street_and_building — Split a street line into street name, building and sub-building, handling both the leading-number convention (10 Downing Street) and the trailing-number one used across much of continental Europe
• validate_postal_policy — Validate an address's post_code against a country's format policy (US ZIP / ZIP+4, GB alphanumeric, and others)
• parse_address_libpostal — Parse a free-text address into ISO 20022 postal fields; uses libpostal's statistical parser when the optional postal extra is installed, and a deterministic fallback otherwise

Optional parameters shared across the assessment/remediation tools: policy_id (defaults to cbpr-2026), as_of (an YYYY-MM-DD date that decides the cliff wording; defaults to today), and country_hint (an ISO 3166-1 alpha-2 code to assume when an address carries no country of its own).

Using the tools

You can invoke the tools in-process — without a transport — straight through the FastMCP instance. This mirrors what an agent receives over stdio. The runnable version of this snippet lives in examples/mcp_tools.py.

import asyncio

from structured_address_fix_mcp import server

# A fully unstructured address: two free-text lines, no structured fields.
# At the 14 Nov 2026 cliff this form is rejected across the major schemes.
unstructured = {
    "address_lines": ["10 Downing St", "London SW1A 2AA"],
    "country": "GB",
}


async def main() -> None:
    async def call(name, args):
        result = await server.server.call_tool(name, args)
        # mcp 2.x returns a CallToolResult (read .content); 1.x
        # returns the content list, or a (content, meta) tuple.
        content = getattr(result, "content", None)
        if content is None:
            content = result[0] if isinstance(result, tuple) else result
        return content[0].text if content else ""

    # When does the cliff bite?
    print(await call("get_cutover_date", {}))
    # -> {"date": "2026-11-14", "scheme": "SWIFT CBPR+ UG2026"}

    # What shape is this address in right now?
    print(await call("classify_address", {"address": unstructured}))
    # -> {"classification": "unstructured"}

    # Propose the compliant form, with each change explained.
    print(await call("remediate_address",
                     {"address": unstructured, "policy_id": "cbpr-2026"}))
    # -> {"policy_id": "cbpr-2026", "findings": [...], "suggestions": [...],
    #     "is_compliant_before": false, "is_compliant_after": true, ...}


asyncio.run(main())

Run it directly:

python examples/mcp_tools.py

Related MCP Servers

Part of the ISO 20022 MCP Suite — open-source, Apache-2.0 licensed MCP servers for banking and financial-services AI agents:

When not to use structured-address-fix-mcp

• You have no MCP client. This server only makes sense paired with an MCP-aware host (Claude Desktop, the IDE plugins, an agent framework). For scripted / CI use, the structured-address-fix CLI covers the same ground without the stdio protocol overhead.
• You need an authenticated, multi-tenant service. The HTTP transports (Transports) carry no authentication of their own and bind loopback by default; put them behind a gateway you trust. OAuth 2.1 resource-server auth and tenant scoping are on the roadmap, not in this release.
• You need streaming responses. Tool calls return whole values, not streams. Large messages are assessed and remediated in one call, not chunked over multiple responses.
• You need to build the pacs.008 / pain.001 message. Out of scope; this server fixes the addresses inside a message. Use pacs008-mcp or pain001-mcp to generate and validate the message itself.

Development

structured-address-fix-mcp uses Poetry and mise.

git clone https://github.com/sebastienrousseau/structured-address-fix-mcp.git && cd structured-address-fix-mcp
mise install
poetry install
poetry shell

Note: the server depends on the core structured-address-fix library. Until it is published to PyPI, the dev dependency group installs it from the sibling checkout (../structured-address-fix); see CONTRIBUTING.md.

A Makefile orchestrates the quality gates (kept in lockstep with CI):

make check        # all gates (REQUIRED before commit): lint + type-check + test + examples
make test         # pytest
make lint         # ruff + black
make type-check   # mypy --strict
make security     # bandit

Security

structured-address-fix-mcp is a thin wrapper — every tool delegates to structured_address_fix.services, where the defence-in-depth for XML parsing (defusedxml) lives. Tools catch the documented domain, validation, and value errors and return an {"error": ...} envelope per the suite convention; they never propagate raw exceptions to the MCP client. Reporting practice, supported versions, and the full supply-chain posture (SLSA L3 provenance, PEP 740 attestations, SBOMs, and the NIST SP 800-218 SSDF practice mapping) are documented in SECURITY.md. Vulnerabilities go via GitHub Private Vulnerability Reporting, not public issues.

Documentation

• README.md — this file
• CHANGELOG.md — release notes
• SECURITY.md — disclosure + supported versions
• SUPPORT.md — how to get help
• ROADMAP.md — what's next (OAuth on the HTTP transports, observability, entitlement gating)
• MAINTAINERS.md — who can merge
• docs/quickstart.md — 10-minute install → first conversation
• docs/deployment-cookbook.md — client configs (Claude Desktop, Cursor, containers) and the HTTP transports
• docs/adr/ — architecture decision records
• ARCHITECTURE.md — a map of the codebase
• RELEASING.md — how a release is cut
• examples/ — runnable scripts
• glama.json — Glama directory manifest

MCP Registry

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

License

Licensed under the [Apache License, Version 2.0][01]. Any contribution submitted for inclusion shall be licensed as above, without additional terms.

Contributing

Contributions are welcome — see the [contributing instructions][04]. Thanks to all [contributors][05].

Acknowledgements

Built on the [structured-address-fix][core] ISO 20022 postal-address library and the [Model Context Protocol][mcp] Python SDK.

[01]: https://opensource.org/license/apache-2-0/ [04]: https://github.com/sebastienrousseau/structured-address-fix-mcp/blob/main/CONTRIBUTING.md [05]: https://github.com/sebastienrousseau/structured-address-fix-mcp/graphs/contributors [07]: https://pypi.org/project/structured-address-fix-mcp/ [core]: https://github.com/sebastienrousseau/structured-address-fix [mcp]: https://modelcontextprotocol.io [docs-badge]: https://img.shields.io/badge/Docs-structured--address--fix-blue?style=for-the-badge [docs-url]: https://sebastienrousseau.github.io/structured-address-fix/ [license-badge]: https://img.shields.io/pypi/l/structured-address-fix-mcp?style=for-the-badge [pypi-badge]: https://img.shields.io/pypi/v/structured-address-fix-mcp?style=for-the-badge [python-versions-badge]: https://img.shields.io/pypi/pyversions/structured-address-fix-mcp.svg?style=for-the-badge [quality-badge]: https://img.shields.io/github/actions/workflow/status/sebastienrousseau/structured-address-fix-mcp/ci.yml?branch=main&label=Quality&style=for-the-badge [quality-url]: https://github.com/sebastienrousseau/structured-address-fix-mcp/actions/workflows/ci.yml [scorecard-badge]: https://api.scorecard.dev/projects/github.com/sebastienrousseau/structured-address-fix-mcp/badge?style=for-the-badge [scorecard-url]: https://scorecard.dev/viewer/?uri=github.com/sebastienrousseau/structured-address-fix-mcp [tests-badge]: https://img.shields.io/github/actions/workflow/status/sebastienrousseau/structured-address-fix-mcp/ci.yml?branch=main&label=Tests&style=for-the-badge [tests-url]: https://github.com/sebastienrousseau/structured-address-fix-mcp/actions/workflows/ci.yml [glama-badge]: https://glama.ai/mcp/servers/sebastienrousseau/structured-address-fix-mcp/badges/score.svg [glama-url]: https://glama.ai/mcp/servers/sebastienrousseau/structured-address-fix-mcp