iso20022-bank-profile-mcp

iso20022-bank-profile-mcp：ISO 20022 银行清算配置文件服务

一个完全本地、封闭世界的 Model Context Protocol 服务，用于管理、验证和提供特定银行的 ISO 20022 清算配置文件／规则包——这些市场实践规则位于结构性 XSD 验证之外。它是 ISO 20022 MCP Suite 的基础成员，也是 iso20022-readiness-suite-mcp 的姊妹项目，后者的就绪度网关可以使用本服务提供的配置文件。

2026 年 11 月的重要节点。 随着主要支付体系（CBPR+、HVPS+、T2、 FedNow）收紧 ISO 20022 要求——结构化邮政地址是其中的重点——昨天还没问题的付款，明天就可能被拒绝。iso20022-bank-profile-mcp 将这些支付体系规则转化为带版本的、可由 Agent 调用的清算配置文件：list_profiles 和 get_profile 用于提供配置文件，lint_payload 用于根据配置文件评估载荷，而 validate_profile_definition 用于审核银行提供的规则包。v0.0.6， 通过 stdio（默认方式）、streamable HTTP、SSE 或经身份验证的 OAuth 2.1 HTTP 提供 4 个只读工具，支持高级规则包权益控制，要求 Python 3.10+。

目录

• 概览
• ISO 20022 MCP Suite
• 安装
• 快速入门
• 传输方式 — stdio、streamable HTTP（2026-07-28 和 2025-11-25）、SSE，以及通过一条命令行提供经身份验证的 HTTP
• 工具
• HTTP 传输与身份验证
• 它在套件中的作用
• 开源核心与高级版
• 何时不应使用 iso20022-bank-profile-mcp
• 开发
• 安全
• 文档
• 许可证
• 贡献
• 致谢

概览

Model Context Protocol（MCP）是一项开放标准，可让 AI Agent 和助手以统一方式发现并调用外部工具。 iso20022-bank-profile-mcp 负责 ISO 20022 MCP Suite 中的市场实践配置文件层：付款要通过清算必须满足的支付体系特定和银行特定规则。这些规则位于 XSD 之上，并且因清算系统而异。

清算配置文件是纯数据，包含 profile_id、market_practice、所支持的消息，以及声明式 custom_rules 列表。该服务附带开放基线配置文件（Generic、CBPR+、SEPA_Instant、FedNow），并提供四个只读工具，用于发现配置文件、获取完整内容、根据配置文件检查载荷，以及验证候选规则包。

这是一个完全本地、封闭世界的服务：没有网络接口、子服务或元客户端。每个工具都基于随附的配置文件数据进行计算，并返回类型化、可序列化为 JSON 的输出；发生任何故障时——输入有误、载荷无法解析或配置文件未知——它都会返回 {"error": ...} 载荷，而不会向客户端传输层抛出异常。XML 载荷仅使用 defusedxml 解析（无 XXE／十亿笑攻击）。

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

flowchart TD
    A["MCP client<br/>(Claude Desktop, IDE, agent)"] -->|stdio, streamable HTTP, SSE| B["iso20022-bank-profile-mcp<br/>(clearing-profile server)"]
    B --> C["ProfileEngine<br/>(bundled JSON + register() seam)"]
    C --> D["Generic"]
    C --> E["CBPR+"]
    C --> F["SEPA_Instant"]
    C --> G["FedNow"]
    H["iso20022-readiness-suite-mcp<br/>(readiness gateway)"] -.consumes profiles.-> B

ISO 20022 MCP 套件

iso20022-bank-profile-mcp 是一组协调配合、与供应商无关的 ISO 20022 迁移 MCP 服务之一。套件中的依赖版本范围保持一致，因此这些服务可以在同一个 Python 环境中顺利共同安装。

基础服务各自做好一种报文处理工作，而就绪度网关将它们组合起来；本服务负责清算配置文件：管理、验证并提供其余套件用于检查的市场实践规则包。

安装

iso20022-bank-profile-mcp 可在 macOS、Linux 和 Windows 上运行，需要 Python 3.10+ 和 pip。它会自动安装 MCP SDK、pydantic 和 defusedxml，这些软件包均发布在 PyPI 上。

python -m pip install iso20022-bank-profile-mcp

也可以使用 uvx 直接从 PyPI 运行，无需安装：

uvx iso20022-bank-profile-mcp

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

快速开始

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

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

iso20022-bank-profile-mcp

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

{
  "mcpServers": {
    "iso20022-bank-profile": { "command": "iso20022-bank-profile-mcp" }
  }
}

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

你也可以直接通过 FastMCP 实例在进程内调用这些工具，无需使用传输方式。这与 Agent 通过 stdio 接收的内容一致；所有操作均在本地进行，因此无需其他服务：

import asyncio

from iso20022_bank_profile_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 (use .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?
    print(await call("list_profiles", {}))
    # -> {"profile_id": "...", "market_practice": "...", "rule_count": ...}, ...

    # Lint a payload against a profile: a CBPR+ address missing its town.
    payload = "<Document><PstlAdr><Ctry>DE</Ctry></PstlAdr></Document>"
    print(await call("lint_payload",
                     {"payload_content": payload, "profile_id": "CBPR+"}))
    # -> {"profile_id": "CBPR+", "is_compliant": false,
    #     "findings": [{"code": "CBPR_MISSING_TOWN", "locator": "TwnNm", ...}]}


asyncio.run(main())

传输方式

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

--host 和 --port 可更改 streamable-http 和 sse 的绑定地址（默认值为 127.0.0.1 和 8000）。这两种方式本身都不提供身份验证：请绑定到环回地址，或者在绑定到可路由地址之前，将服务置于你信任的网关之后；--transport http 则是带身份验证的选项。每个版本都会使用 scout 在两个协议时期内通过 streamable HTTP 进行验证，并使用 MCP SDK 客户端通过 SSE 进行验证；参见 ADR 0001。

{
  "mcpServers": {
    "iso20022-bank-profile": { "url": "http://127.0.0.1:8000/mcp" }
  }
}

工具

所有工具都会返回可序列化为 JSON 的数据；遇到领域、验证或值错误时，它们会返回 {"error": ...} 负载，而非抛出异常。每个工具都是纯本地、只读、幂等的封闭世界查询——不访问网络，也不调用子服务。

• list_profiles — 列出可用清算配置文件的轻量级摘要（profile_id、market_practice、tier、entitled、supported_messages、rule_count）。使用此工具可发现其他工具接受的 profile_id 值，并查看当前调用者有权使用哪些配置文件。
• get_profile — 完整返回一个清算配置文件，包括其规则正文。对于高级版配置文件，调用者必须具有使用权，否则会返回 BP_NOT_ENTITLED 错误（参见开放核心版与高级版）。
• lint_payload — 根据清算配置文件评估原始 ISO 20022 负载并返回检查结果（符合要求的负载不会产生任何结果）。与 get_profile 一样，使用高级版配置文件需要相应使用权，否则会返回 BP_NOT_ENTITLED。
• validate_profile_definition — 验证以原始 JSON 形式提供的银行配置文件／规则包定义，确认其结构正确，且每条规则都使用已知的断言动词。

HTTP 传输与身份验证

stdio 是默认传输方式，无需身份验证——每位操作员使用一个进程，由客户端启动，不暴露网络接口。上文提到的套件 streamable-http 和 sse 传输方式也无需身份验证。对于共享的多租户部署，服务还支持经过身份验证的 streamable-HTTP 传输：

iso20022-bank-profile-mcp --transport=http --bind=127.0.0.1:8080

--bind 默认值为 127.0.0.1:8080（仅限环回地址），因此要将服务暴露给主机以外的网络，必须显式选择启用（例如 --bind=0.0.0.0:8080）。HTTP 传输未配置身份验证时会拒绝启动——绝不会提供未经身份验证的端点。支持两种身份验证模式，按安全性从高到低排列：

• OAuth 2.1 资源服务器（RFC 9728）——设置 ISO20022_BANK_PROFILE_OAUTH_ISSUER 和 ISO20022_BANK_PROFILE_OAUTH_AUDIENCE（均为必需），还可选设置 ISO20022_BANK_PROFILE_OAUTH_JWKS_URL（默认为 <issuer>/.well-known/jwks.json）和 ISO20022_BANK_PROFILE_OAUTH_SCOPES。每个请求都必须携带 Authorization: Bearer <jwt>；令牌会根据 JWKS 进行验证，并检查其 iss / aud / exp / nbf / 必需的作用域。验证失败时会返回 401 / 403，并附带 RFC 9728 WWW-Authenticate 质询；受保护资源元数据通过 /.well-known/oauth-protected-resource 提供。此服务会验证来自你现有授权服务器（Okta、Auth0、Entra ID 等）的令牌；运行授权服务器不在本项目范围内。

  ISO20022_BANK_PROFILE_OAUTH_ISSUER=https://auth.example.com \
  ISO20022_BANK_PROFILE_OAUTH_AUDIENCE=https://mcp.example.com/mcp \
    iso20022-bank-profile-mcp --transport=http --bind=0.0.0.0:8080
  

• 静态开发模式令牌——将 ISO20022_BANK_PROFILE_TOKEN 设为共享密钥；之后每个请求都必须发送 Authorization: Bearer <secret>。这是一个没有过期时间且不包含作用域的共享密钥——适用于本地开发，不适用于生产环境。

可选的 X-MCP-Tenant 请求标头会转发到工具可见的请求上下文中，以支持多租户范围控制。完整配置说明请参阅 docs/transport.md。

在套件中的作用

此服务是 ISO 20022 MCP Suite 的配置文件权威服务。同系列的 iso20022-readiness-suite-mcp 网关会根据清算配置文件对支付进行评分和修正；这些配置文件正是由此服务管理、验证和提供的。统一配置文件来源，可确保就绪度网关与任何银行自有工具都依据相同的市场惯例规则评估支付。

配置文件目录可在整个套件共用的接口处扩展。ProfileEngine 使用 ProfileEngine.from_bundled() 从捆绑的 JSON 加载开放基线，并提供 ProfileEngine.register(profile)，以便在运行时添加或替换配置文件。高级银行专属规则包与捆绑配置文件的结构相同——都是包含 profile_id、market_practice、supported_messages 和 custom_rules 列表的 ClearingProfile——因此，嵌入此服务的部署可以注册已获许可的规则包，并与开放基线一同提供，而无需更改工具接口。规则迷你语言和 register() 接口请参阅 docs/profiles.md。

开放核心与高级版

此服务采用开放核心模式：基线支付体系配置文件和配置文件引擎均为开源，始终可用。更高等级、面向特定机构的功能则作为商业附加组件，接入同一配置文件引擎接口（该引擎已提供 register() 钩子，可在运行时加载规则包）。

开源版本中的功能均无时间限制，也不会被功能门控。

权限门控的工作原理

每个清算配置文件都带有一个 tier："open"（基线配置文件——不受限制，始终可访问）或 "premium"（许可规则包）。随附的高级示例配置文件 ACME_Premium 可供你测试门控功能。list_profiles 会报告每个配置文件的 tier 和针对每个调用方的 entitled 布尔值；如果调用方没有相应权限，对高级配置文件调用 get_profile 和 lint_payload 会返回 BP_NOT_ENTITLED 错误。

权限可通过以下两个彼此独立的来源之一授予（逻辑 OR）：

• OAuth 作用域（HTTP 传输）——带有 profile:premium 作用域的令牌可访问所有高级配置文件；带有 profile:<profile_id> 的令牌则只能访问对应的配置文件。
• 环境允许列表（stdio / 开发模式）——ISO20022_BANK_PROFILE_ENTITLEMENTS 列出运营方获许可的高级 profile_id 值（用逗号或空格分隔）；* 表示授予全部权限。

# stdio: license the ACME_Premium sample pack for this process
ISO20022_BANK_PROFILE_ENTITLEMENTS=ACME_Premium iso20022-bank-profile-mcp

本版本包含门控功能；高级规则包本身（以及有状态的版本历史记录 / 审计日志）仍为付费的外部内容。完整的权限模型请参阅 docs/profiles.md。

哪些情况下不应使用 iso20022-bank-profile-mcp

• 你没有 MCP 客户端。 此服务只有与支持 MCP 的宿主配合使用才有意义（Claude Desktop、IDE 插件、Agent 框架）。
• 你需要结构化 XSD 验证或消息生成。 这些功能由基础套件服务提供（iso20022-mcp、camt053-mcp、pain001-mcp）。此服务会评估 XSD 之上的市场惯例规则；它不会解析、生成或进行消息的结构化验证。
• 你需要端到端的就绪度评分和修复建议。 这是 iso20022-readiness-suite-mcp 的工作，它会使用这些配置文件。如果你想将评分、修复建议和银行响应模拟组合在一起，请使用它。
• 你需要在可路由地址上运行不带身份验证的长期网络服务。 默认使用 stdio（每个运营方对应一个进程，不暴露网络）；--transport streamable-http 和 --transport sse 会绑定到环回地址，且不提供身份验证，因此可路由部署必须放在你信任的网关之后；--transport http 选项适用于共享、多租户部署，并且始终要求身份验证（OAuth 2.1 或静态开发模式令牌）——它不会提供未经身份验证的端点。
• 你需要流式响应。 工具调用会返回完整结果，而不是数据流。

开发

iso20022-bank-profile-mcp 使用 Poetry 和 mise。

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

注意： 此服务完全在本地运行，且采用封闭世界设计，因此运行测试套件无需安装其他内容。请参阅 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-bank-profile-mcp 会将错误作为数据返回——每个工具都会捕获文档中说明的领域错误、验证错误和值错误，并返回 {"error": ...} 封装；它绝不会将原始异常传递给 MCP 客户端。通过清算配置文件引擎处理的负载仅使用 defusedxml 进行解析（无 XXE / billion-laughs 漏洞），且服务不会打开网络套接字。报告惯例、支持的版本、攻击面以及完整的供应链安全状况（SLSA L3 来源证明、PEP 740 证明、SBOM 和 NIST SP 800-218 SSDF 实践映射）均记录在 SECURITY.md 中。请通过 GitHub Private Vulnerability Reporting 报告漏洞，而不要提交公开议题。

文档

• README.md — 本文件
• CHANGELOG.md — 发行说明
• SECURITY.md — 漏洞披露和受支持的版本
• SUPPORT.md — 获取帮助的方法
• ROADMAP.md — 已发布的内容（HTTP 传输、付费权益门控）和后续计划（更丰富的银行规则包）
• MAINTAINERS.md — 有权合并代码的人员
• docs/quickstart.md — 10 分钟安装 → 开始首次对话
• docs/profiles.md — 清算配置文件、规则小型语言、付费规则包和权益门控
• docs/transport.md — 可选的 HTTP 传输和 OAuth 2.1 设置
• glama.json — Glama 目录清单

MCP 注册表

mcp-name: io.github.sebastienrousseau/iso20022-bank-profile-mcp

许可证

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

贡献

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

致谢

本项目与 ISO 20022 MCP Suite 的基础服务以及 Model Context Protocol Python SDK 一同构建。