{
  "markdown": "# structured-address-fix-mcp: An MCP Server for ISO 20022 Postal Addresses\n\n[![PyPI Version][pypi-badge]][07]\n[![Python Versions][python-versions-badge]][07]\n[![License][license-badge]][01]\n[![Tests][tests-badge]][tests-url]\n[![Quality][quality-badge]][quality-url]\n[![OpenSSF Scorecard][scorecard-badge]][scorecard-url]\n[![Documentation][docs-badge]][docs-url]\n\n**A [Model Context Protocol][mcp] server that exposes the\n[`structured-address-fix`][core] ISO 20022 postal-address library as tools for\nAI agents and assistants** — classify an address's shape, assess it against a\nscheme policy, and remediate it (or a whole pacs.008 / pain.001 message) into\nthe structured form the November 2026 cutover requires, all from your\nfavourite MCP client.\n\n> **The 14 November 2026 cliff.** On that date CBPR+, HVPS+, T2, CHAPS, and\n> Fedwire stop accepting fully unstructured postal addresses: a payment whose\n> debtor/creditor address is a free-text blob is rejected. `structured-address-fix-mcp`\n> puts the readiness check and the fix in front of your agent — `assess_message`\n> flags the offending parties, `remediate_message` proposes the compliant form,\n> and `get_cutover_date` reports the binding date. **v0.0.2**, stdio transport,\n> 13 tools, Python 3.12+.\n\n## Contents\n\n- [Overview](#overview)\n- [The ISO 20022 MCP Suite](#the-iso-20022-mcp-suite)\n- [Install](#install)\n- [Quick Start](#quick-start)\n- [Tools](#tools)\n- [Using the tools](#using-the-tools)\n- [Related MCP Servers](#related-mcp-servers)\n- [When not to use structured-address-fix-mcp](#when-not-to-use-structured-address-fix-mcp)\n- [Development](#development)\n- [Security](#security)\n- [Documentation](#documentation)\n- [License](#license)\n- [Contributing](#contributing)\n- [Acknowledgements](#acknowledgements)\n\n## Overview\n\nThe [Model Context Protocol][mcp] (MCP) is an open standard that lets AI agents\nand assistants discover and call external tools in a uniform way.\n**structured-address-fix-mcp** is an MCP server that turns the\n[`structured-address-fix`][core] library into a set of first-class agent tools,\nso an assistant can read a postal address — or every addressed party in an\n**ISO 20022 `pacs.008` / `pain.001` message** — and bring it into line with the\nstructured-address rules that become mandatory on **14 November 2026**,\ndirectly from a conversation.\n\nThe headline capability is the one-shot remediation workflow: assess a message,\nfind the parties whose addresses will be rejected at the cliff, and emit the\ncompliant form with each change explained and confidence-scored.\n\nEvery tool is a thin, typed wrapper over `structured_address_fix.services` —\nthe single shared facade also used by the CLI — so all interfaces behave\nidentically. Tools return JSON-serialisable data; on an error they return an\n`{\"error\": ...}` payload rather than raising.\n\n- **Website:** <https://sebastienrousseau.github.io/structured-address-fix/>\n- **Source code:** <https://github.com/sebastienrousseau/structured-address-fix-mcp>\n- **Bug reports:** <https://github.com/sebastienrousseau/structured-address-fix-mcp/issues>\n\n```mermaid\nflowchart LR\n    A[\"MCP client<br/>(Claude Desktop, IDE, agent)\"] -->|stdio| B[\"structured-address-fix-mcp\"]\n    B -->|delegates to| C[\"structured_address_fix.services\"]\n    C -->|classify + assess + remediate| D[\"ISO 20022 postal addresses<br/>(pacs.008 / pain.001)\"]\n```\n\n## The ISO 20022 MCP Suite\n\n`structured-address-fix-mcp` is the **postal-address specialist** in a set of\ncoordinated, vendor-neutral MCP servers for the ISO 20022 migration.\nDependency ranges are kept aligned across the suite, so the servers co-install\ncleanly in a single Python environment: start with one, add the rest as your\nworkflow grows.\n\n| Server | Scope | Install | Use it when |\n|------|------|------|------|\n| [`structured-address-fix-mcp`](#install) | ISO 20022 postal-address classification, assessment, and remediation for the Nov 2026 structured-address cliff | `pip install structured-address-fix-mcp` | You need to get debtor/creditor addresses cliff-ready — **this package** |\n| [`pacs008-mcp`](https://github.com/sebastienrousseau/pacs008-mcp) | Generate, validate, parse & scheme-check ISO 20022 pacs.008 FI-to-FI credit transfers, with Nov-2026 address linting | `pip install pacs008-mcp` | You work with pacs.008 messages end to end |\n| [`pain001-mcp`](https://github.com/sebastienrousseau/pain001-mcp) | Generate & validate ISO 20022 pain.001 payment-initiation files (v03–v12, pain.008, SEPA) with rulebook checks | `pip install pain001-mcp` | You originate outbound payment files |\n| [`camt053-mcp`](https://github.com/sebastienrousseau/camt053-mcp) | ISO 20022 camt.05x bank statements: parse, validate, filter, reverse; MT94x migration; CBPR+ readiness | `pip install camt053-mcp` | You work with bank-to-customer statements |\n| [`iso20022-readiness-suite-mcp`](https://github.com/sebastienrousseau/iso20022-readiness-suite-mcp) | Orchestration gateway: detect → validate → clearing-profile lint → readiness score, plus remediation and `pacs.002` simulation — a meta-client over the foundational servers | `pip install iso20022-readiness-suite-mcp` | You want one high-level readiness / orchestration entry point over the suite |\n| [`iso20022-bank-profile-mcp`](https://github.com/sebastienrousseau/iso20022-bank-profile-mcp) | Manages, validates and serves bank-specific clearing profiles / rule packs; premium rule-pack entitlement gating | `pip install iso20022-bank-profile-mcp` | You lint payments against your own institution's market practice |\n| [`iso20022-evidence-pack-mcp`](https://github.com/sebastienrousseau/iso20022-evidence-pack-mcp) | Compiles readiness findings, remediation diffs and simulated responses into a sealed, Ed25519-signable audit evidence pack | `pip install iso20022-evidence-pack-mcp` | You need tamper-evident audit / certification artifacts |\n\nThe suite also includes the [`iso20022-mcp`](https://github.com/sebastienrousseau/iso20022-mcp)\ngateway (unified `search` / `describe` / `validate` / `generate` / `parse`\nmeta-tools across the whole message catalogue) and\n[`acmt001-mcp`](https://github.com/sebastienrousseau/acmt001-mcp) (account\nmanagement). Where `pacs008-mcp` *lints* a message for address problems,\n`structured-address-fix-mcp` is the specialist that *classifies, assesses, and\nfixes* the addresses themselves against per-scheme policies.\n\n## Install\n\n**structured-address-fix-mcp** runs on macOS, Linux, and Windows and requires\n**Python 3.12+** and **pip**. It pulls in the core `structured-address-fix`\nlibrary and the MCP SDK automatically.\n\n```sh\npython -m pip install structured-address-fix-mcp\n```\n\n<details>\n<summary>Using an isolated virtual environment (recommended)</summary>\n\n```sh\npython -m venv venv\nsource venv/bin/activate        # macOS/Linux\nvenv\\Scripts\\activate           # Windows\npython -m pip install -U structured-address-fix-mcp\n```\n</details>\n\n## Quick Start\n\nFor the 10-minute install → MCP client config → first conversation\ntutorial, see [`docs/quickstart.md`](docs/quickstart.md).\n\nLaunch the server over stdio (the FastMCP default transport):\n\n```sh\nstructured-address-fix-mcp\n```\n\nRegister it with any MCP client (e.g. Claude Desktop) by adding it to the\nclient's configuration:\n\n```json\n{\n  \"mcpServers\": {\n    \"structured-address-fix\": { \"command\": \"structured-address-fix-mcp\" }\n  }\n}\n```\n\nThe command speaks MCP on stdin/stdout — it is meant to be launched by an\nMCP client, not used interactively. The agent can then call the tools below\nto assess and remediate postal addresses on demand.\n\n## Tools\n\nAll tools delegate to the shared `structured_address_fix.services` layer, so\nthey behave identically to the CLI. Tools return JSON-serialisable data; on a\ndomain, validation, or value error they return an `{\"error\": ...}` payload.\n\n- `list_policies` — List every available address policy (rulebook) with its tier (e.g. `cbpr-2026`, `sepa`, `hvps-plus`, `generic-structured`)\n- `classify_address` — Classify a postal address as structured, hybrid, or unstructured (a quick shape check)\n- `assess_address` — Score a single address against a policy and return its findings\n- `assess_message` — Assess every addressed party in a pacs.008 / pain.001 message against a policy\n- `remediate_address` — Propose the compliant form of an address, with the before/after and confidence-scored patch operations\n- `remediate_message` — Assess and remediate every addressed party in a message; optionally apply the operations and return the patched XML\n- `preview_patch` — Return the patch operations remediation would apply to a message (a dry run)\n- `explain_finding` — Explain what a finding code (e.g. `SAF001`) means and how to resolve it\n- `get_cutover_date` — Return the binding November 2026 structured-address cutover date and the scheme that sets it\n- `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)\n- `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\n- `validate_postal_policy` — Validate an address's `post_code` against a country's format policy (US ZIP / ZIP+4, GB alphanumeric, and others)\n- `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\n\nOptional parameters shared across the assessment/remediation tools: `policy_id`\n(defaults to `cbpr-2026`), `as_of` (an `YYYY-MM-DD` date that decides the cliff\nwording; defaults to today), and `country_hint` (an ISO 3166-1 alpha-2 code to\nassume when an address carries no country of its own).\n\n## Using the tools\n\nYou can invoke the tools in-process — without a transport — straight through the\nFastMCP instance. This mirrors what an agent receives over stdio. The runnable\nversion of this snippet lives in [`examples/mcp_tools.py`](examples/mcp_tools.py).\n\n```python\nimport asyncio\n\nfrom structured_address_fix_mcp import server\n\n# A fully unstructured address: two free-text lines, no structured fields.\n# At the 14 Nov 2026 cliff this form is rejected across the major schemes.\nunstructured = {\n    \"address_lines\": [\"10 Downing St\", \"London SW1A 2AA\"],\n    \"country\": \"GB\",\n}\n\n\nasync def main() -> None:\n    async def call(name, args):\n        result = await server.server.call_tool(name, args)\n        # mcp 2.x returns a CallToolResult (read .content); 1.x\n        # returns the content list, or a (content, meta) tuple.\n        content = getattr(result, \"content\", None)\n        if content is None:\n            content = result[0] if isinstance(result, tuple) else result\n        return content[0].text if content else \"\"\n\n    # When does the cliff bite?\n    print(await call(\"get_cutover_date\", {}))\n    # -> {\"date\": \"2026-11-14\", \"scheme\": \"SWIFT CBPR+ UG2026\"}\n\n    # What shape is this address in right now?\n    print(await call(\"classify_address\", {\"address\": unstructured}))\n    # -> {\"classification\": \"unstructured\"}\n\n    # Propose the compliant form, with each change explained.\n    print(await call(\"remediate_address\",\n                     {\"address\": unstructured, \"policy_id\": \"cbpr-2026\"}))\n    # -> {\"policy_id\": \"cbpr-2026\", \"findings\": [...], \"suggestions\": [...],\n    #     \"is_compliant_before\": false, \"is_compliant_after\": true, ...}\n\n\nasyncio.run(main())\n```\n\nRun it directly:\n\n```sh\npython examples/mcp_tools.py\n```\n\n## Related MCP Servers\n\nPart of the **ISO 20022 MCP Suite** — open-source, Apache-2.0 licensed MCP\nservers for banking and financial-services AI agents:\n\n| Server | Purpose |\n|---|---|\n| [`pacs008-mcp`](https://github.com/sebastienrousseau/pacs008-mcp) | Generate, validate, parse & scheme-check ISO 20022 pacs.008 FI-to-FI credit transfers + Nov-2026 address linting |\n| [`pain001-mcp`](https://github.com/sebastienrousseau/pain001-mcp) | Generate & validate ISO 20022 pain.001 payment files (v03–v12, pain.008, SEPA) with rulebook checks |\n| [`camt053-mcp`](https://github.com/sebastienrousseau/camt053-mcp) | Parse, validate, filter & reverse ISO 20022 camt.05x bank statements; MT94x migration; CBPR+ readiness |\n| [`acmt001-mcp`](https://github.com/sebastienrousseau/acmt001-mcp) | Generate & validate ISO 20022 acmt account-management messages |\n| [`iso20022-mcp`](https://github.com/sebastienrousseau/iso20022-mcp) | Unified gateway: `search` / `describe` / `validate` / `generate` / `parse` across the pain · pacs · camt · acmt families |\n\n## When not to use structured-address-fix-mcp\n\n- **You have no MCP client.** This server only makes sense paired with an\n  MCP-aware host (Claude Desktop, the IDE plugins, an agent framework). For\n  scripted / CI use, the `structured-address-fix` CLI covers the same ground\n  without the stdio protocol overhead.\n- **You need a long-lived network service.** v0.1 speaks **stdio only** —\n  one process per operator, launched by the client, no network surface. An\n  HTTP/OAuth transport for shared, multi-tenant deployments is on the\n  [roadmap](ROADMAP.md), not in this release.\n- **You need streaming responses.** Tool calls return whole values, not\n  streams. Large messages are assessed and remediated in one call, not\n  chunked over multiple responses.\n- **You need to *build* the pacs.008 / pain.001 message.** Out of scope; this\n  server fixes the addresses inside a message. Use\n  [`pacs008-mcp`](https://github.com/sebastienrousseau/pacs008-mcp) or\n  [`pain001-mcp`](https://github.com/sebastienrousseau/pain001-mcp) to\n  generate and validate the message itself.\n\n## Development\n\n**structured-address-fix-mcp** uses [Poetry](https://python-poetry.org/) and\n[mise](https://mise.jdx.dev/).\n\n```bash\ngit clone https://github.com/sebastienrousseau/structured-address-fix-mcp.git && cd structured-address-fix-mcp\nmise install\npoetry install\npoetry shell\n```\n\n> **Note:** the server depends on the core `structured-address-fix` library.\n> Until it is published to PyPI, the dev dependency group installs it from the\n> sibling checkout (`../structured-address-fix`); see\n> [`CONTRIBUTING.md`](CONTRIBUTING.md).\n\nA `Makefile` orchestrates the quality gates (kept in lockstep with CI):\n\n```bash\nmake check        # all gates (REQUIRED before commit): lint + type-check + test + examples\nmake test         # pytest\nmake lint         # ruff + black\nmake type-check   # mypy --strict\nmake security     # bandit\n```\n\n## Security\n\n`structured-address-fix-mcp` is a thin wrapper — every tool delegates to\n`structured_address_fix.services`, where the defence-in-depth for XML parsing\n(defusedxml) lives. Tools catch the documented domain, validation, and value\nerrors and return an `{\"error\": ...}` envelope per the suite convention; they\nnever propagate raw exceptions to the MCP client. Reporting practice, supported\nversions, and the full supply-chain posture (SLSA L3 provenance, PEP 740\nattestations, SBOMs, and the NIST SP 800-218 SSDF practice mapping) are\ndocumented in [`SECURITY.md`](SECURITY.md). Vulnerabilities go via GitHub\nPrivate Vulnerability Reporting, not public issues.\n\n## Documentation\n\n- [`README.md`](README.md) — this file\n- [`CHANGELOG.md`](CHANGELOG.md) — release notes\n- [`SECURITY.md`](SECURITY.md) — disclosure + supported versions\n- [`SUPPORT.md`](SUPPORT.md) — how to get help\n- [`ROADMAP.md`](ROADMAP.md) — what's next (HTTP/OAuth transport, observability, entitlement gating)\n- [`MAINTAINERS.md`](MAINTAINERS.md) — who can merge\n- [`docs/quickstart.md`](docs/quickstart.md) — 10-minute install → first conversation\n- [`docs/deployment-cookbook.md`](docs/deployment-cookbook.md) — stdio client configs (Claude Desktop, Cursor, containers)\n- [`examples/`](examples/) — runnable scripts\n- [`glama.json`](glama.json) — Glama directory manifest\n\n---\n\n## MCP Registry\n\n`mcp-name: io.github.sebastienrousseau/structured-address-fix-mcp`\n\n---\n\n## License\n\nLicensed under the [Apache License, Version 2.0][01]. Any contribution submitted\nfor inclusion shall be licensed as above, without additional terms.\n\n## Contributing\n\nContributions are welcome — see the [contributing instructions][04]. Thanks to\nall [contributors][05].\n\n## Acknowledgements\n\nBuilt on the [`structured-address-fix`][core] ISO 20022 postal-address library\nand the [Model Context Protocol][mcp] Python SDK.\n\n[01]: https://opensource.org/license/apache-2-0/\n[04]: https://github.com/sebastienrousseau/structured-address-fix-mcp/blob/main/CONTRIBUTING.md\n[05]: https://github.com/sebastienrousseau/structured-address-fix-mcp/graphs/contributors\n[07]: https://pypi.org/project/structured-address-fix-mcp/\n[core]: https://github.com/sebastienrousseau/structured-address-fix\n[mcp]: https://modelcontextprotocol.io\n[docs-badge]: https://img.shields.io/badge/Docs-structured--address--fix-blue?style=for-the-badge\n[docs-url]: https://sebastienrousseau.github.io/structured-address-fix/\n[license-badge]: https://img.shields.io/pypi/l/structured-address-fix-mcp?style=for-the-badge\n[pypi-badge]: https://img.shields.io/pypi/v/structured-address-fix-mcp?style=for-the-badge\n[python-versions-badge]: https://img.shields.io/pypi/pyversions/structured-address-fix-mcp.svg?style=for-the-badge\n[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\n[quality-url]: https://github.com/sebastienrousseau/structured-address-fix-mcp/actions/workflows/ci.yml\n[scorecard-badge]: https://api.scorecard.dev/projects/github.com/sebastienrousseau/structured-address-fix-mcp/badge?style=for-the-badge\n[scorecard-url]: https://scorecard.dev/viewer/?uri=github.com/sebastienrousseau/structured-address-fix-mcp\n[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\n[tests-url]: https://github.com/sebastienrousseau/structured-address-fix-mcp/actions/workflows/ci.yml\n",
  "bytes": 18173,
  "sha": "b9d8c3862907e811a9f288840f165276704284ecffe0f44b14d8d57ae6daaf7f",
  "repo_slug": "sebastienrousseau/structured-address-fix-mcp",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_sebastienrousseau_structured_a_d60da553/readme"
}