iso20022-evidence-pack-mcp

iso20022-evidence-pack-mcp：密封的 ISO 20022 审计证据包

一个完全本地、封闭世界的 Model Context Protocol (MCP) 服务，可将 ISO 20022 就绪情况的发现结果、修复差异和模拟银行响应汇编成一个密封、可导出的审计证据包。它是审计与认证版的 iso20022-readiness-suite-mcp （负责生成这些发现结果）以及 iso20022-bank-profile-mcp 的姊妹项目，属于 ISO 20022 MCP Suite。

从设计上即可防篡改。 证据包的密封值是基于证据包规范化 JSON 计算得出的确定性 SHA-256 摘要（不包含 digest 字段）。 对相同内容重新密封会得到相同摘要，任何字段的更改都会导致验证失败，因此审计人员可以发现未经检测的更改。这里 没有网络接口、没有子服务，也不处理 XML：每个工具都是纯粹的 本地确定性转换，仅处理传入的 JSON 结构。 v0.0.6，stdio、streamable HTTP、SSE 或经过身份验证的 streamable HTTP， 共 11 个工具，包括 Ed25519 证据包签名，Python 3.10+。

目录

• 概览
• ISO 20022 MCP Suite
• 安装
• 快速开始
• 传输方式 — 通过一条命令行使用 stdio、streamable HTTP（2026-07-28 和 2025-11-25）、SSE 和经过身份验证的 HTTP
• 工具
• HTTP 传输与身份验证
• 签署证据包
• 示例
• 它在套件中的作用
• 开源核心版与高级版
• 密封与签名
• 何时不应使用 iso20022-evidence-pack-mcp
• 开发
• 安全
• 文档
• 许可证
• 贡献
• 致谢

概述

模型上下文协议（MCP）是一项开放标准，让 AI Agent 和助手能够以统一的方式发现并调用外部工具。iso20022-evidence-pack-mcp 是 ISO 20022 MCP Suite 中负责审计／认证的部分：它接收 iso20022-readiness-suite-mcp 生成的结果——包含发现项的就绪度评分、可选的修复结果以及任何模拟银行响应——并将它们汇总为一个强类型、分级且密封的证据包，可导出、验证并呈现为合规报告。

EvidencePack 将三个类型较宽松的输入汇总为一个自描述文档：就绪度结果（消息类型、有效性、评分、发现项）、可选的修复结果（已应用的修复、残留发现项）以及任何模拟银行响应（接受／拒绝状态）。证据包根据就绪度评分分级（A／B／C／F），并经过密封。

密封是关键：它是在证据包的规范 JSON 形式上计算出的确定性 SHA-256 摘要（键已排序，分隔符紧凑，并排除 digest 字段本身）。对相同内容进行密封始终会得到相同值，这正是证据包具有防篡改特性的原因——重新计算密封值，并与证据包中携带的值进行比较，即可告知审计员，自密封以来是否有任何字节发生变化。

每个工具都会返回类型化、可序列化为 JSON 的数据；遇到任何错误——输入无效、JSON 无法解析、结构与证据包架构不匹配——都会返回 {"error": ...} 负载，而不会向客户端传输层抛出异常。

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

flowchart LR
    A["iso20022-readiness-suite-mcp<br/>(readiness + remediation + simulation)"] -->|JSON results| B["iso20022-evidence-pack-mcp<br/>(build + seal)"]
    B -->|sealed pack + digest| C["verify_seal<br/>(tamper check)"]
    B -->|markdown report| D["render_markdown<br/>(compliance report)"]

该服务完全在本地运行，且仅处理明确提供的内容：不保存状态、不打开套接字，也不启动进程。你向它提供 JSON，它就会返回密封后的证据包。

ISO 20022 MCP 套件

iso20022-evidence-pack-mcp 是一组协同的、厂商中立的 MCP 服务中负责审计与认证的服务，专为 ISO 20022 迁移打造。 该套件中的服务保持依赖范围一致，因此可以在同一个 Python 环境中顺利安装。

就绪度套件负责判断付款是否已就绪并进行修复，而本服务负责认证结果：它会将这些发现转化为经过密封、可审计的产物。

安装

iso20022-evidence-pack-mcp 可在 macOS、Linux 和 Windows 上运行，需要 Python 3.10+ 和 pip。它仅会自动安装 MCP SDK 和 pydantic，没有其他运行时依赖。

python -m pip install iso20022-evidence-pack-mcp

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

快速开始

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

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

iso20022-evidence-pack-mcp

将以下配置添加到客户端配置中，即可向任意 MCP 客户端（例如 Claude Desktop）注册该服务：

{
  "mcpServers": {
    "iso20022-evidence-pack": { "command": "iso20022-evidence-pack-mcp" }
  }
}

该命令通过标准输入／标准输出进行 MCP 通信，旨在由 MCP 客户端启动，而非供交互式使用。随后，Agent 即可调用下方的工具。

你也可以直接通过 FastMCP 实例在进程内调用这些工具，无需使用传输方式。这与 Agent 通过 stdio 接收的内容一致。以下示例会根据一份小型就绪度结果构建密封包，然后演示密封的往返验证（以及篡改后验证失败）：

import asyncio
import json

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

    readiness = json.dumps({
        "message_type": "pacs.008.001.08",
        "is_valid": True,
        "readiness_score": 92,
        "structural_errors": [],
        "profile_findings": [],
    })

    # Fold the readiness result into a graded, sealed evidence pack.
    built = json.loads(await call("build_evidence_pack",
                                  {"readiness_content": readiness}))
    pack, digest = built["pack"], built["digest"]
    print(pack["grade"], digest)      # -> A sha256:01388e3dfbea7d21...

    # The seal round-trips: re-verifying the pack against its digest holds.
    ok = json.loads(await call("verify_seal", {
        "pack_content": json.dumps(pack),
        "expected_digest": digest,
    }))
    print(ok["verified"])             # -> True

    # Change any field and verification against the old digest fails.
    tampered = {**pack, "grade": "F"}
    bad = json.loads(await call("verify_seal", {
        "pack_content": json.dumps(tampered),
        "expected_digest": digest,
    }))
    print(bad["verified"])            # -> False


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-evidence-pack": { "url": "http://127.0.0.1:8000/mcp" }
  }
}

工具

所有工具均为只读、本地、幂等且限定于封闭世界。它们返回 可序列化为 JSON 的数据；遇到验证错误或结构错误时，会返回 {"error": ...} 负载，而不是抛出异常。

• build_evidence_pack — 将就绪度结果（以及可选的整改结果、可选的模拟银行响应和自由格式元数据）汇总为经过分级和封存的证据包；返回证据包、其摘要以及渲染后的 Markdown 报告。
• seal_pack — 计算证据包（原始 JSON）的确定性 SHA-256 封存值。
• verify_seal — 重新计算证据包的封存值，并与预期摘要进行比较。
• render_markdown — 将证据包渲染为 Markdown 合规报告。
• sign_pack — 使用操作员的 Ed25519 密钥（通过环境配置）对证据包的规范字节进行签名；返回 base64 分离式签名、PEM 公钥和 key_id。未配置密钥时会以 EP_NO_SIGNING_KEY 失败。参见签署证据包。
• verify_pack_signature — 使用作为参数传入的公钥，验证针对证据包规范字节的 Ed25519 分离式签名；返回 verified 和 key_id。

HTTP 传输与身份验证

服务器默认使用 stdio 通信——由本地 MCP 客户端启动，每位操作员运行一个进程，不暴露网络接口，也不需要身份验证。对于共享的多租户部署，v0.0.2 新增了一个可选的流式 HTTP 传输：

iso20022-evidence-pack-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_EVIDENCE_PACK_OAUTH_* 变量：

  变量	必需	含义
  ISO20022_EVIDENCE_PACK_OAUTH_ISSUER	是	授权服务器的签发者；JWT 的 iss 必须与其完全匹配。
  ISO20022_EVIDENCE_PACK_OAUTH_AUDIENCE	是	此服务器的规范资源 URI（RFC 8707）；JWT 的 aud 必须包含该 URI。
  ISO20022_EVIDENCE_PACK_OAUTH_JWKS_URL	否	JWKS 文档 URL（默认为 <issuer>/.well-known/jwks.json）。
  ISO20022_EVIDENCE_PACK_OAUTH_SCOPES	否	以空格分隔的权限范围，每个令牌都必须包含这些权限范围。

  每个请求都必须提供 Authorization: Bearer <jwt>；系统会根据 JWKS 验证 JWT（iss / aud / exp / nbf 以及任何必需的权限范围）。受保护资源元数据通过 /.well-known/oauth-protected-resource 提供；验证失败时会返回 401（权限范围不足时返回 403），并附带 WWW-Authenticate 质询。

• 静态开发模式 Bearer 令牌——将 ISO20022_EVIDENCE_PACK_TOKEN 设置为非空密钥。之后，每个请求都必须发送 Authorization: Bearer <secret>。这是一个没有过期时间和权限范围的共享密钥；生产环境请使用 OAuth 2.1。

HTTP 调用方还可以发送可选的 X-MCP-Tenant 标头，该标头会转发到工具可见的请求上下文，用于多租户范围限定。HTTP 传输会引入额外依赖（pyjwt[crypto]、httpx、starlette、uvicorn）；默认的 stdio 传输无需这些依赖。完整参考请参阅 docs/transport.md。

签署证据包

证据包的封印用于证明完整性——内容未被更改。签名用于证明真实性——特定密钥对该内容进行了认证。v0.0.2 新增了两个工具，用于 Ed25519 签名：

• sign_pack 对证据包的规范字节进行签名——这与封印计算摘要时使用的序列化完全相同，但不包含 digest 字段。由于签名涵盖封印内容，因此只要 digest 字段发生变化，签名仍然有效；但如果任何封印字段发生变化，签名就会失效。该工具会返回 base64 分离式签名、algorithm "ed25519"、PEM 公钥，以及 key_id（ed25519:<16 hex>）。
• verify_pack_signature 使用作为工具参数传入的公钥，验证证据包规范字节的分离式签名。公钥可以安全地跨越工具边界传递；该工具会返回 verified 和 key_id。

Ed25519私钥由操作员在启动时通过环境配置：

• ISO20022_EVIDENCE_PACK_SIGNING_KEY——直接提供 PEM 私钥，或
• ISO20022_EVIDENCE_PACK_SIGNING_KEY_FILE——PEM 密钥文件的路径。

**私钥绝不会跨越 MCP 工具边界。**服务器不会生成或持久化私钥——密钥材料由操作员生成并保管，最好存放在 HSM/KMS 中。未配置密钥时，sign_pack 会返回 EP_NO_SIGNING_KEY；密钥格式错误或签名无效时，会返回 EP_INVALID_INPUT。

目前已支持使用操作员提供的密钥进行签名。无密钥（sigstore）签名，以及带有验证信任根的 PKI 签名仍属于路线图项目。

示例

可运行、独立的示例位于 examples/ 中。每个脚本都直接调用公开工具，无需网络或子服务：

python examples/01_build_full_pack.py

完整目录请参阅 examples/README.md，也可以运行 make examples 一次运行全部示例。

它如何融入套件

就绪度套件和证据包服务构成了一个两阶段工作流：

1. 就绪度 → 结果。 iso20022-readiness-suite-mcp 运行 run_readiness_check（评分 + 发现项）、remediate_payload （自动修复）和 simulate_bank_response（模拟的 pacs.002 结果）。 每个工具都会返回类型化 JSON。
2. 结果 → 封存包。 将这些 JSON 结果交给此处的 build_evidence_pack。它会将结果规范化为强类型包，对就绪度评分进行分级（A/B/C/F），并使用确定性的 SHA-256 摘要封存整个包。之后，verify_seal 可以证明该包未被更改；render_markdown 则会将其转换为人类可读的合规报告。

由于封存具有确定性，相同的输入始终会产生相同的摘要——因此今天构建、下个季度重新封存的包，可以被证明是同一个包，也可以被证明不是。两个服务保持解耦：就绪度套件无需了解封存，且此服务无需了解发现项的生成方式——它只负责汇总和认证这些发现项。

开源核心与高级版

该服务采用开源核心模式：构建、封存、验证和呈现证据包的功能均为开源且始终可用。能让具有防篡改能力的包成为可认证、可长期存档的制品的高阶功能，是路线图上的商业附加功能。

开源版本中的功能没有时间限制，也没有功能门槛：封存和报告功能目前均可完整使用。

封存与签名

封存是完整性摘要，不是加密签名。 它可以证明证据包自封存后未被更改（具备防篡改能力），但不能证明是谁生成了该包（真实性）。任何能够构建证据包的人也都能为其计算有效封存值，因此封存是校验和，而非来源证明。

sign_pack / verify_pack_signature 在封存的基础上增加了真实性——将证据包与特定密钥绑定：对证据包规范字节进行的 Ed25519 签名，可以证明该内容由持有操作员密钥的人生成。封存和签名相辅相成：封存保证完整性，签名保证真实性。请注意，签名的可信度取决于你对公钥来源的信任——无密钥（sigstore）/ PKI 签名及验证信任根仍是路线图中的项目（请参阅 ROADMAP.md）。如果未配置签名密钥，请仅将已封存但未签名的证据包视为经过完整性检查：通过你已经信任的渠道传输和存储它，不要将其标示为已签名。完整的威胁模型说明请参阅 SECURITY.md。

不适合使用 iso20022-evidence-pack-mcp 的情况

• 你没有 MCP 客户端。 此服务只有与支持 MCP 的宿主（Claude Desktop、IDE 插件、Agent 框架）配合使用才有意义。
• 你需要就绪情况的评估结果本身。 此服务负责认证结果，而不负责生成结果。请先运行 iso20022-readiness-suite-mcp 进行评分、修复和模拟，然后再将其输出整合到这里。
• 你需要使用公用信任根进行无密钥 / PKI 签名。 密封是用于检测篡改的摘要，而不是签名（参见 密封与签名）。v0.0.2 中提供了使用操作员提供的密钥进行 Ed25519 签名的功能 (签署证据包)，但无密钥（sigstore）/PKI 签名及验证信任根仍在 路线图中。
• 你希望使用零依赖的网络服务。 默认传输方式是 stdio — 每位操作员启动一个由客户端运行的进程，不暴露网络接口。v0.0.2 中提供了可选的身份验证 HTTP 传输（OAuth 2.1 / RFC 9728） (HTTP 传输与身份验证)，适用于共享的多租户部署，但它会引入额外依赖， 且必须显式启用。
• 你需要流式响应。 工具调用返回完整值，而不是数据流。

开发

iso20022-evidence-pack-mcp 使用 Poetry 和 mise。

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

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
make examples     # run every examples/*.py end to end

安全

iso20022-evidence-pack-mcp 会将错误作为数据返回 — 每个工具都会捕获文档中说明的验证错误和值错误，并返回 {"error": ...} 封装；它绝不会将原始异常传递给 MCP 客户端。在默认的 stdio 传输方式下，服务不暴露网络接口、不启动子进程，也不解析 XML — 攻击者可触及的整个接口都由标准库解析的 JSON 组成，并通过 pydantic 模型进行验证。可选的 HTTP 传输默认关闭；启用时，如果没有 OAuth 2.1 (RFC 9728) 或静态开发模式承载令牌，则拒绝启动（参见 HTTP 传输与身份验证）。证据包密封是用于检测篡改的摘要，而不是签名；Ed25519 签名 (sign_pack) 可在此基础上增加真实性（参见 密封与签名）。报告 实践、支持的版本、密封威胁模型说明，以及完整的供应链安全态势（SLSA L3 来源证明、PEP 740 证明、SBOM 和 NIST SP 800-218 SSDF 实践映射）均记录在 SECURITY.md 中。漏洞应通过 GitHub 私有漏洞报告渠道提交，而非公开议题。

文档

• README.md — 本文件
• CHANGELOG.md — 发布说明
• SECURITY.md — 漏洞披露、支持的版本及密封威胁模型
• SUPPORT.md — 如何获取帮助
• ROADMAP.md — 后续计划（无密钥/PKI 签名、长期存储、高级版权益）
• MAINTAINERS.md — 有权合并代码的人员
• ARCHITECTURE.md — 模块图、传输方式、扩展点
• RELEASING.md — 发布标准及发布流程
• docs/adr/ — 架构决策记录
• docs/quickstart.md — 10 分钟完成安装并开始首次对话
• docs/evidence-packs.md — 证据包架构、SHA-256 密封模型、Ed25519 签名，以及从就绪评估到证据包的流程
• docs/transport.md — 可选的 HTTP 传输和 OAuth 2.1 (RFC 9728) 身份验证
• glama.json — Glama 目录清单

MCP Registry

mcp-name: io.github.sebastienrousseau/iso20022-evidence-pack-mcp

许可证

根据 Apache License, Version 2.0 获得许可。提交以纳入项目的任何贡献 均应遵循上述许可，且不附加其他条款。

贡献

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

致谢

与 ISO 20022 MCP Suite 的服务以及 Model Context Protocol Python SDK 共同构建。