structured-address-fix-mcp

structured-address-fix-mcp：适用于 ISO 20022 邮政地址的 MCP 服务

一个 Model Context Protocol 服务，将 structured-address-fix ISO 20022 邮政地址库作为工具提供给 AI Agent 和助手 — 可判定地址的结构类型、依据方案策略评估地址，并将其（或整条 pacs.008 / pain.001 消息）修复为 2026 年 11 月切换要求的结构化格式，所有操作都可通过你喜爱的 MCP 客户端完成。

2026 年 11 月 14 日的临界期限。 从这一天起，CBPR+、HVPS+、T2、CHAPS 和 Fedwire 将不再接受完全非结构化的邮政地址：如果付款方或收款方的地址是自由文本块，支付指令就会被拒绝。structured-address-fix-mcp 将就绪情况检查和修复功能交到你的 Agent 手中 — assess_message 会标记有问题的参与方，remediate_message 会提出合规格式， get_cutover_date 会报告强制生效日期。v0.0.6，支持 stdio、可流式传输的 HTTP 和 SSE 传输方式，提供 13 个工具，要求 Python 3.12+。

目录

• 概览
• ISO 20022 MCP 套件
• 安装
• 快速开始
• 传输方式 — 通过一条命令行命令使用 stdio、可流式传输的 HTTP（2026-07-28 和 2025-11-25）以及 SSE
• 工具
• 使用工具
• 相关 MCP 服务
• 何时不应使用 structured-address-fix-mcp
• 开发
• 安全
• 文档
• 许可证
• 贡献
• 致谢

概览

Model Context Protocol（MCP）是一项开放标准，可让 AI Agent 和助手以统一方式发现并调用外部工具。 structured-address-fix-mcp 是一个 MCP 服务，可将 structured-address-fix 库转化为一组一流的 Agent 工具， 让助手能够直接在对话中读取邮政地址 — 或 ISO 20022 pacs.008 / pain.001 消息中的每个地址参与方 — 并使其符合将于 2026 年 11 月 14 日起强制执行的结构化地址规则。

其核心功能是一站式修复工作流：评估消息，找出地址将在临界期限被拒绝的参与方，并输出合规格式，同时解释每项更改并对其进行置信度评分。

每个工具都是对 structured_address_fix.services 的轻量类型化封装 — CLI 也使用这一统一共享的门面，因此所有接口的行为都一致。工具会返回可序列化为 JSON 的数据；出错时会返回 {"error": ...} 负载，而不会抛出异常。

• 网站： https://sebastienrousseau.github.io/structured-address-fix/
• 源代码： https://github.com/sebastienrousseau/structured-address-fix-mcp
• 错误报告： 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)"]

ISO 20022 MCP 套件

structured-address-fix-mcp 是一组协调配合、供应商中立的 MCP 服务中的邮政地址专家，专为 ISO 20022 迁移而打造。 套件中的依赖范围保持一致，因此这些服务可以在同一个 Python 环境中顺利共存：先从一个服务开始，随着工作流扩展，再添加其他服务。

该套件还包括 iso20022-mcp 网关（可在整个消息目录中统一使用 search / describe / validate / generate / parse 元工具），以及 acmt001-mcp（账户 管理）。pacs008-mcp 会对消息进行地址问题检查；而 structured-address-fix-mcp 则是专门针对各方案政策，对地址本身进行分类、评估和修正的工具。

安装

structured-address-fix-mcp 可在 macOS、Linux 和 Windows 上运行，需要 Python 3.12+ 和 pip。它会自动安装核心 structured-address-fix 库和 MCP SDK。

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

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

快速开始

10 分钟安装 → 配置 MCP 客户端 → 开始首次对话的教程，请参阅 docs/quickstart.md。

通过 stdio（默认传输方式）启动服务：

structured-address-fix-mcp

将其添加到客户端配置，即可在任意 MCP 客户端（例如 Claude Desktop）中注册：

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

默认情况下，该命令通过 stdin/stdout 进行 MCP 通信——它旨在由 MCP 客户端启动，而非供交互式使用。如需共享部署 或 HTTP 客户端，请参阅传输方式。之后，Agent 可以按需调用下方的工具来评估和修正邮政地址。

传输方式

一条命令行，三种传输方式：

--host 和 --port 用于更改绑定地址（默认为 127.0.0.1 和 8000）。HTTP 传输方式本身不提供身份验证：请绑定到环回地址，或者在绑定 可路由地址之前，将服务置于你信任的网关之后。每个版本都会通过 scout，在两个协议时代下使用可流式传输的 HTTP 进行验证， 并通过 MCP SDK 客户端使用 SSE 进行验证；请参阅 ADR 0001。

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

工具

所有工具都委托给共享的 structured_address_fix.services 层，因此 其行为与 CLI 完全相同。工具返回可序列化为 JSON 的数据；遇到领域错误、 验证错误或值错误时，会返回 {"error": ...} 负载。

• list_policies — 列出所有可用的地址政策（规则手册）及其层级（例如 cbpr-2026、sepa、hvps-plus、generic-structured）
• classify_address — 将邮政地址分类为结构化、混合式或非结构化（快速检查其形式）
• assess_address — 根据某项政策评估单个地址并返回检查结果
• assess_message — 根据某项政策评估 pacs.008 / pain.001 消息中的每个收件方
• remediate_address — 提出符合要求的地址形式，并提供修改前后的内容以及带置信度评分的补丁操作
• remediate_message — 评估并修正消息中的每个收件方；可选地应用这些操作并返回修补后的 XML
• preview_patch — 返回修正消息时将应用的补丁操作（试运行）
• explain_finding — 说明某个检查结果代码（例如 SAF001）的含义以及解决方法
• get_cutover_date — 返回具有约束力的 2026 年 11 月结构化地址切换日期及设定该日期的方案
• normalize_country_code — 将国家名称或代码解析为 ISO 3166-1 alpha-2 代码；接受英文名称、本地自称（Deutschland、España、Nippon）和常见别称（UK、USA、Holland、UAE）
• split_street_and_building — 将街道地址行拆分为街道名称、建筑物和子建筑物，同时处理数字在前的格式（10 Downing Street）以及在欧洲大陆许多地区使用的数字在后的格式
• validate_postal_policy — 根据国家格式政策验证地址的 post_code（美国 ZIP / ZIP+4、英国字母数字格式等）
• parse_address_libpostal — 将自由文本地址解析为 ISO 20022 邮政字段；若安装了可选的 postal 扩展，则使用 libpostal 的统计解析器，否则使用确定性回退方案

评估/修正工具共享的可选参数：policy_id （默认为 cbpr-2026）、as_of（用于决定截止日期措辞的 YYYY-MM-DD 日期；默认为今天）以及 country_hint（当地址本身不含国家信息时，假定使用的 ISO 3166-1 alpha-2 代码）。

使用工具

你可以直接通过 FastMCP 实例在进程内调用这些工具，无需使用传输方式。这与 Agent 通过 stdio 收到的内容一致。此代码片段的可运行版本位于 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())

直接运行：

python examples/mcp_tools.py

相关 MCP 服务

属于 ISO 20022 MCP Suite 的一部分——面向银行和金融服务 AI Agent 的开源 Apache-2.0 许可 MCP 服务：

哪些情况下不应使用 structured-address-fix-mcp

• 你没有 MCP 客户端。 此服务只有与支持 MCP 的宿主（Claude Desktop、IDE 插件、Agent 框架）配合使用才有意义。对于脚本或 CI 场景，structured-address-fix CLI 可以覆盖相同用途，且无需承担 stdio 协议开销。
• 你需要经过身份验证的多租户服务。 HTTP 传输方式（传输方式）本身不提供身份验证，并且默认绑定到环回地址；请将其置于你信任的网关后方。OAuth 2.1 资源服务身份验证和租户范围控制已列入路线图，但尚未包含在此版本中。
• 你需要流式响应。 工具调用返回完整值，而非数据流。大型报文会在一次调用中完成评估和修复，不会拆分为多个响应。
• 你需要构建 pacs.008 / pain.001 报文。 这不在本服务范围内；本服务只修复报文中的地址。请使用 pacs008-mcp 或 pain001-mcp 来生成和验证报文本身。

开发

structured-address-fix-mcp 使用 Poetry 和 mise。

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

注意： 此服务依赖核心 structured-address-fix 库。在该库发布到 PyPI 之前，开发依赖组会从同级目录检出（../structured-address-fix）安装该库；请参阅 CONTRIBUTING.md。

Makefile 用于协调质量检查（与 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

安全

structured-address-fix-mcp 是一个轻量封装——每个工具都会委托给 structured_address_fix.services，XML 解析的纵深防御（defusedxml）由该模块负责。工具会捕获文档所述的领域错误、验证错误和值错误，并按照套件惯例返回 {"error": ...} 封装；绝不会将原始异常传递给 MCP 客户端。有关漏洞报告流程、支持的版本以及完整的供应链安全措施（SLSA L3 来源证明、PEP 740 证明、SBOM，以及 NIST SP 800-218 SSDF 实践映射），请参阅 SECURITY.md。漏洞应通过 GitHub 私密漏洞报告渠道提交，而非发布到公开议题中。

文档

• README.md — 本文件
• CHANGELOG.md — 发行说明
• SECURITY.md — 漏洞披露与支持的版本
• SUPPORT.md — 如何获取帮助
• ROADMAP.md — 后续计划（HTTP 传输中的 OAuth、可观测性、权益门控）
• MAINTAINERS.md — 谁有权合并
• docs/quickstart.md — 10 分钟完成安装并开始首次对话
• docs/deployment-cookbook.md — 客户端配置（Claude Desktop、Cursor、容器）和 HTTP 传输
• docs/adr/ — 架构决策记录
• ARCHITECTURE.md — 代码库概览
• RELEASING.md — 如何发布版本
• examples/ — 可运行的脚本
• glama.json — Glama 目录清单

MCP Registry

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

许可证

本项目根据 Apache License, Version 2.0 授权。提交以纳入本项目的任何贡献均按上述条款授权，不附加其他条款。

贡献

欢迎贡献 — 请参阅贡献指南。感谢所有贡献者。

致谢

本项目基于 structured-address-fix ISO 20022 邮政地址库和 Model Context Protocol Python SDK 构建。