structured-address-fix-mcp

<!-- SPDX-License-Identifier: Apache-2.0 OR MIT -->

# 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]

<p align="center">
  <img src=".github/demo.gif" alt="structured-address-fix-mcp Demo" width="100%" />
</p>


**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](#overview)
- [The ISO 20022 MCP Suite](#the-iso-20022-mcp-suite)
- [Install](#install)
- [Quick Start](#quick-start)
- [Transports](#transports) — stdio, streamable HTTP (2026-07-28 and 2025-11-25) and SSE from one command line
- [Tools](#tools)
- [Using the tools](#using-the-tools)
- [Related MCP Servers](#related-mcp-servers)
- [When not to use structured-address-fix-mcp](#when-not-to-use-structured-address-fix-mcp)
- [Development](#development)
- [Security](#security)
- [Documentation](#documentation)
- [License](#license)
- [Contributing](#contributing)
- [Acknowledgements](#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>

```mermaid
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.

| Server | Scope | Install | Use it when |
|------|------|------|------|
| [`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** |
| [`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 |
| [`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 |
| [`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 |
| [`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 |
| [`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 |
| [`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 |

The suite also includes the [`iso20022-mcp`](https://github.com/sebastienrousseau/iso20022-mcp)
gateway (unified `search` / `describe` / `validate` / `generate` / `parse`
meta-tools across the whole message catalogue) and
[`acmt001-mcp`](https://github.com/sebastienrousseau/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.

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

<details>
<summary>Using an isolated virtual environment (recommended)</summary>

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

## Quick Start

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

Launch the server over stdio (the default transport):

```sh
structured-address-fix-mcp
```

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

```json
{
  "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](#transports). The agent can then call
the tools below to assess and remediate postal addresses on demand.

## Transports

One command line, three transports:

| Command | Transport | Endpoint | Protocol revisions |
| :--- | :--- | :--- | :--- |
| `structured-address-fix-mcp` | stdio | the client spawns the process | 2026-07-28, 2025-11-25 |
| `structured-address-fix-mcp --transport streamable-http` | Streamable HTTP | `http://127.0.0.1:8000/mcp` | 2026-07-28 (stateless, `server/discover`) and 2025-11-25 (`initialize`, `Mcp-Session-Id`) on the same endpoint; responses stream as server-sent events, `GET` opens the server-to-client stream |
| `structured-address-fix-mcp --transport sse` | HTTP+SSE (2024-11-05) | `http://127.0.0.1:8000/sse` and `/messages/` | for clients that still expect the older transport |

`--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](https://github.com/sebastienrousseau/scout) in both protocol
eras and over SSE with the MCP SDK client; see
[ADR 0001](docs/adr/0001-three-transports-one-command-line.md).

```json
{
  "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 poli