iso20022-readiness-suite-mcp

iso20022-readiness-suite-mcp：ISO 20022 就绪度与测试网关

一个高级编排 Model Context Protocol 服务——白标 ISO 20022 就绪度与测试网关。 对你的 Agent 而言，它是一个 MCP 服务；对 ISO 20022 MCP Suite 的基础服务而言，它是一个 MCP 客户端。它将这些服务组合起来，提供就绪度评分、自动修复、清算配置文件检查（CBPR+、SEPA_Instant、FedNow、Generic）和银行响应模拟——Agent 可通过这一个网关判断“这笔付款是否已准备就绪；如果没有，该如何修复”。

2026 年 11 月的重要里程碑。 随着主要支付体系（CBPR+、HVPS+、T2、FedNow）收紧 ISO 20022 要求——结构化邮政地址尤为重要——昨天还没问题的付款，明天就可能被拒绝。iso20022-readiness-suite-mcp 在你的 Agent 前面提供一个统一的就绪度网关：run_readiness_check 根据清算配置文件为负载评分，remediate_payload 提出符合要求的格式，simulate_bank_response 则模拟银行会如何响应。v0.0.6，支持 stdio（默认）、可流式 HTTP、SSE 或经过身份验证的可流式 HTTP，提供 4 个工具，需使用 Python 3.10+。

目录

• 概览
• ISO 20022 MCP Suite
• 安装
• 快速开始
• 传输方式 — 通过一个命令行使用 stdio、可流式 HTTP（2026-07-28 和 2025-11-25）、SSE 和经过身份验证的 HTTP
• 工具
• HTTP 传输与身份验证
• 编排与元客户端模式
• 开源核心与高级版
• 不适用 iso20022-readiness-suite-mcp 的情况
• 开发
• 安全
• 文档
• 许可证
• 贡献
• 致谢

概述

Model Context Protocol（MCP）是一项开放标准，让 AI Agent 和助手能够以统一的方式发现和调用外部工具。iso20022-readiness-suite-mcp 是 ISO 20022 MCP Suite 的编排入口：它向外部 Agent 提供四个高层工具，并在底层充当 MCP 客户端，通过标准输入/输出（stdio）启动基础套件服务并组合其结果——即元客户端模式。

其核心能力是一站式就绪度工作流：提供原始 ISO 20022 载荷和目标清算配置文件，它便会检测消息类型，将其路由至相应的基础验证器，依据配置文件的市场实践规则执行检查，并返回包含检查结果的单一就绪度评分；之后还可按需修复载荷，并模拟银行会如何响应。

每个工具都会返回类型化、可序列化为 JSON 的数据；任何情况下发生故障——输入错误、载荷无法解析、子服务缺失或出错——它都会返回 {"error": ...} 载荷，而不会向客户端传输层抛出异常。

• 网站： https://sebastienrousseau.github.io/iso20022-readiness-suite-mcp/
• 源代码： https://github.com/sebastienrousseau/iso20022-readiness-suite-mcp
• 错误报告： https://github.com/sebastienrousseau/iso20022-readiness-suite-mcp/issues

flowchart TD
    A["MCP client<br/>(Claude Desktop, IDE, agent)"] -->|stdio| B["iso20022-readiness-suite-mcp<br/>(orchestration gateway)"]
    B -->|spawns over stdio via uvx| C["iso20022-mcp"]
    B -->|spawns over stdio via uvx| D["camt053-mcp"]
    B -->|spawns over stdio via uvx| E["pain001-mcp"]
    B -->|spawns over stdio via uvx| F["reconcile-mcp"]
    B -->|spawns over stdio via uvx| G["bankstatementparser-mcp"]
    B -->|spawns over stdio via uvx| H["structured-address-fix-mcp"]

该网关对上层客户端是一个服务，对下方六个基础服务是一个客户端。list_profiles 和 simulate_bank_response 完全在本地运行，无需这些服务；run_readiness_check 和 remediate_payload 会调用子服务，因此要求这些服务已安装且可解析（参见编排与元客户端模式）。

ISO 20022 MCP Suite

iso20022-readiness-suite-mcp 是编排网关，构建于一组相互协作、与供应商无关的 MCP 服务之上，用于 ISO 20022 迁移。整个套件中的依赖版本范围保持一致，因此各服务可在同一个 Python 环境中顺利共同安装：安装所需的基础服务，再由此网关将它们组合起来。

每个基础服务都专注做好一项工作，而此网关则将它们组合起来：检测载荷并将其路由至合适的验证器，依据清算配置文件执行检查，为其评估就绪度，进行修复，并模拟银行的答复——所有操作都通过四个 Agent 工具完成。

安装

iso20022-readiness-suite-mcp 可在 macOS、Linux 和 Windows 上运行，需要 Python 3.10+ 和 pip。它会自动安装 MCP SDK、pydantic 和 defusedxml。

python -m pip install iso20022-readiness-suite-mcp

如需端到端测试 run_readiness_check 和 remediate_payload，还要确保基础服务可被解析——网关通过 uvx 启动这些服务，因此安装 uv 即可实现零安装启动：

python -m pip install uv        # provides the `uvx` launcher

python -m venv venv
source venv/bin/activate        # macOS/Linux
venv\Scripts\activate           # Windows
python -m pip install -U iso20022-readiness-suite-mcp

快速开始

如需查看 10 分钟完成安装 → MCP 客户端配置 → 首次对话的教程，请参阅 docs/quickstart.md。

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

iso20022-readiness-suite-mcp

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

{
  "mcpServers": {
    "iso20022-readiness-suite": { "command": "iso20022-readiness-suite-mcp" }
  }
}

该命令通过 stdin/stdout 传输 MCP 消息——它旨在由 MCP 客户端启动，而非供交互式使用。随后，Agent 即可调用下方的工具。

你也可以直接通过 FastMCP 实例在进程内调用工具，无需传输层。这与 Agent 通过 stdio 接收的内容一致。两个本地工具（list_profiles、simulate_bank_response）无需子服务：

import asyncio

from iso20022_readiness_suite_mcp import server


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 ""

    # Which clearing profiles can I target? (fully local)
    print(await call("list_profiles", {}))
    # -> [{"profile_id": "CBPR+", ...}, {"profile_id": "SEPA_Instant", ...}, ...]

    # Mock how a bank would answer an initiation. (fully local)
    pacs008 = '<Document><CdtTrfTxInf><Amt Ccy="EUR">10</Amt></CdtTrfTxInf></Document>'
    print(await call("simulate_bank_response",
                     {"inbound_payload": pacs008, "desired_behavior": "ACCP"}))
    # -> {"status": "ACCP", "generated_response_type": "pacs.002.001.10", ...}


asyncio.run(main())

传输方式

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

--host 和 --port 可更改 streamable-http 和 sse 的绑定地址（默认值分别为 127.0.0.1 和 8000）。这两种方式本身都不提供身份验证：请绑定到环回地址，或在绑定到可路由地址之前将服务置于可信网关之后；--transport http 是经过身份验证的选项。无论使用哪种外部传输方式，网关仍会通过 stdio 启动子服务，并对这些会话进行池化。每个版本都会使用 scout 在两个协议时代通过 Streamable HTTP 验证，并使用 MCP SDK 客户端通过 SSE 验证；请参阅 ADR 0001。

{
  "mcpServers": {
    "iso20022-readiness-suite": { "url": "http://127.0.0.1:8000/mcp" }
  }
}

工具

所有工具都会返回可序列化为 JSON 的数据；发生域错误、验证错误或子服务错误时，它们会返回 {"error": ...} 负载，而不会抛出异常。

• list_profiles — 列出可用的清算配置（CBPR+、SEPA_Instant、FedNow、Generic）及其市场实践和规则。完全在本地运行；无需子服务。
• run_readiness_check — 检测 ISO 20022 负载，对其进行结构验证、配置规则检查，并评估其是否符合目标清算配置的要求。会调用基础子服务。
• remediate_payload — 根据清算配置应用自动修复（例如 2026 年 11 月的结构化地址修复），并委托给 structured-address-fix-mcp。会调用基础子服务。
• simulate_bank_response — 生成 pacs.002 状态报告，模拟银行对传入发起请求的 ACCP / RJCT / PDNG 响应（RJCT 必须提供原因代码）。完全在本地运行；无需子服务。

可达性。 run_readiness_check 和 remediate_payload 会通过 stdio 使用 uvx 启动底层服务，因此必须已安装这些服务，或能够解析它们，两个工具才能正常运行。list_profiles 和 simulate_bank_response 完全在本地计算，可始终独立运行。

HTTP 传输与身份验证

默认情况下，网关使用 stdio — 由本地 MCP 客户端启动，每位操作员对应一个进程，不暴露网络接口，且无需身份验证：

iso20022-readiness-suite-mcp                 # stdio (default)

套件中无需身份验证的 --transport streamable-http 和 --transport sse 在传输一节中有说明。对于共享的多租户部署，网关还提供经过身份验证的 streamable-HTTP 传输。默认的 --bind 仅绑定到回环地址 （127.0.0.1:8080）；如需对外开放，请显式设置为 --bind=0.0.0.0:8080：

iso20022-readiness-suite-mcp --transport=http --bind=0.0.0.0:8080

HTTP 传输必须经过身份验证 — 如果未配置身份验证，启动将被拒绝。支持两种模式，按安全性从高到低排列。

OAuth 2.1 资源服务器（RFC 9728）— 生产环境。 设置 ISO20022_READINESS_OAUTH_* 环境变量，服务器便会根据授权服务器的 JWKS 验证 Authorization: Bearer <jwt>：

JWT 会经过签名验证（使用 JWKS，并在 kid 未知时轮换密钥），并检查 iss / aud / exp / nbf 以及所需作用域。RFC 9728 受保护资源元数据可在未经身份验证的情况下通过 /.well-known/oauth-protected-resource 获取。拒绝请求时会返回 401（作用域不足时返回 403），并附带指向该元数据的 WWW-Authenticate 质询。

静态 Bearer 令牌 — 仅限开发模式。 未设置 OAuth 变量时，系统会改为接受 ISO20022_READINESS_TOKEN 中的单个共享密钥 （使用 hmac.compare_digest 进行比较）。此模式明确仅用于开发 — 只有一个共享 密钥、没有过期时间、没有作用域；如果同时配置了 OAuth，则会忽略此密钥：

ISO20022_READINESS_TOKEN=s3cret \
  iso20022-readiness-suite-mcp --transport=http --bind=127.0.0.1:8080

HTTP 调用方可以发送可选的 X-MCP-Tenant 标头，该标头会被转发到每个请求的租户上下文；经过身份验证的令牌所含作用域也会提供给工具，以便工具代码可以按作用域调整行为，而无需根据传输方式进行分支判断。完整设置说明请参阅 docs/transport.md。

编排与元客户端模式

网关实现了编排中的“同时也是客户端的服务端”这一部分：编排器只依赖 SubServerInvoker 协议，而生产环境中的 StdioSubServerInvoker 会通过 stdio 启动底层服务端、调用一个工具，然后终止会话。所有故障——服务端缺失、启动错误、工具错误——都会作为数据（类型化的 ToolOutcome）返回，不会跨越调用方边界抛出。

默认情况下，每个基础服务端都会通过零安装的 uvx 命令启动：

命令映射可按部署进行覆盖，因此你可以让网关指向本地安装的控制台脚本、固定版本的虚拟环境或远程启动的进程，而不是使用 uvx。完整模式以及如何将其指向本地或远程子服务端，请参阅 docs/orchestration.md。

开源核心与高级版

该网关采用开源核心模式：基础验证工作流和通用方案配置文件均为开源，且始终可用。更高级的、针对特定机构的功能作为商业附加组件，接入相同的配置文件引擎和编排接口（配置文件引擎已提供 register() 钩子，可在运行时加载规则包）。

付费级别已列入路线图（高级规则包授权门控，以及配套的 iso20022-bank-profile-mcp 和 iso20022-evidence-pack-mcp 服务端），但不包含在此版本中。开源级别中的任何功能都没有使用期限，也不会受到功能门控限制。

以下情况不适合使用 iso20022-readiness-suite-mcp

• 你没有 MCP 客户端。 此服务端只有与支持 MCP 的宿主（Claude Desktop、IDE 插件、Agent 框架）配合使用才有意义。
• 你只需要一种报文操作。 如果你只想验证 pain.001 或解析 camt.053，请直接调用相应的基础服务端——网关的价值在于组合这些服务端。
• 你需要在没有子服务端的情况下使用 run_readiness_check / remediate_payload。 这两个工具要求基础服务端可解析（通过 uvx 或覆盖后的命令映射）。如果你无法安装它们，则只能使用 list_profiles 和 simulate_bank_response。
• 你需要长期运行的网络服务。 stdio（默认方式）是每个操作员启动一个进程，由客户端启动，且不开放网络接口。--transport streamable-http 和 --transport sse 会在 --host/--port 上监听，且不进行身份验证（参见传输方式）；对于共享的多租户部署，请使用经过身份验证的 streamable-HTTP 传输（--transport=http，配合 OAuth 2.1 或开发模式令牌）——参见HTTP 传输与身份验证。
• 你需要流式响应。 工具调用返回完整值，而非流。

开发

iso20022-readiness-suite-mcp 使用 Poetry 和 mise。

git clone https://github.com/sebastienrousseau/iso20022-readiness-suite-mcp.git && cd iso20022-readiness-suite-mcp
mise install
poetry install
poetry shell

注意： 测试套件会注入一个伪造的子服务端调用器，因此运行测试不需要安装基础服务端——只有在真实服务端上测试 run_readiness_check / remediate_payload 时才需要。请参阅 CONTRIBUTING.md。

Makefile 用于编排质量检查关卡（与 CI 保持同步）：

make check        # all gates (REQUIRED before commit): lint + type-check + test
make test         # pytest (100% line + branch coverage)
make lint         # ruff + black
make type-check   # mypy --strict
make security     # bandit

安全

iso20022-readiness-suite-mcp 将错误作为数据返回——每个工具都会捕获文档中说明的领域错误、验证错误和值错误（以及每个子服务故障），并返回 {"error": ...} 封装；它绝不会向 MCP 客户端传播原始异常。通过清算配置文件引擎处理的 XML 负载仅使用 defusedxml 解析（不会遭受 XXE / billion-laughs 攻击）。报告实践、支持的版本、元客户端攻击面，以及完整的供应链安全态势（SLSA L3 来源证明、PEP 740 证明、SBOM 和 NIST SP 800-218 SSDF 实践映射）均记载于 SECURITY.md。漏洞请通过 GitHub 私密漏洞报告渠道提交，而非公开问题。

文档

• README.md — 本文件
• CHANGELOG.md — 发布说明
• ARCHITECTURE.md — 模块概览及网关背后的设计决策
• RELEASING.md — 发布的条件及发布流程
• SECURITY.md — 漏洞披露和支持的版本
• SUPPORT.md — 获取帮助的方式
• ROADMAP.md — 后续计划（姊妹服务、付费规则包授权）
• MAINTAINERS.md — 有权合并代码的人员
• docs/adr/ — 架构决策记录
• docs/quickstart.md — 10 分钟完成安装并开始首次对话
• docs/transport.md — HTTP 传输和 OAuth 2.1 (RFC 9728) 身份验证设置
• docs/orchestration.md — 元客户端模式，以及如何将网关指向本地/远程子服务
• docs/profiles.md — 清算配置文件及付费规则包的接入方式
• glama.json — Glama 目录清单

MCP 注册表

mcp-name: io.github.sebastienrousseau/iso20022-readiness-suite-mcp

许可证

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

贡献

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

致谢

基于 ISO 20022 MCP Suite 的基础服务以及 Model Context Protocol Python SDK 构建。