acmt001-mcp

acmt001-mcp：用于 ISO 20022 账户管理的 MCP 服务

一个 Model Context Protocol 服务，将 acmt001 ISO 20022 账户管理库作为工具提供给 AI Agent 和助手 — 可发现消息类型、检查输入架构、验证记录和金融标识符，并生成经过验证的 XML，所有操作均可通过您喜爱的 MCP 客户端完成。

最新版本：v0.0.13：提供 7 个 MCP 工具，支持 stdio、可流式传输的 HTTP 或 SSE，由共享的 acmt001.services 层提供支持，适用于 Python 3.10+。 与 acmt001 0.0.13 同步发布；所有 CI 和镜像安装均固定了哈希值，且这些工具经过模糊测试。查看更新内容 →

目录

• 概览
• 安装
• 快速开始
• 传输方式
• 工具
• 使用工具
• 基准测试
• 文档
• 开发
• 许可证
• 贡献
• 致谢

概述

模型上下文协议（MCP）是一项开放标准，让 AI Agent 和助手能够以统一的方式发现并调用外部工具。acmt001-mcp 是一个 MCP 服务，可将 acmt001 库转换为一组一等 Agent 工具，让助手可以直接通过对话生成和验证 ISO 20022 acmt 账户管理 XML 消息——这些标准化指令、确认和报告规定了银行账户的生命周期（开户、维护、销户、识别和转移）。

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

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

此软件包是 acmt001 套件的一部分——这是一组可独立安装的软件包，共享 acmt001.services 层：

• acmt001 — 核心库（CLI + REST API）
• acmt001-mcp — 本软件包，即 模型上下文协议服务
• acmt001-lsp — 面向编辑器的 语言服务器协议服务

flowchart LR
    A["MCP client<br/>(Claude Desktop, IDE, agent)"] -->|stdio| B["acmt001-mcp"]
    B -->|delegates to| C["acmt001.services"]
    C -->|render + validate| D["ISO 20022 acmt XML"]

安装

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

python -m pip install acmt001-mcp

注意： 核心 acmt001 库尚未发布到 PyPI，请先从源代码安装：

python -m pip install "git+https://github.com/sebastienrousseau/acmt001.git"
python -m pip install acmt001-mcp

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

快速开始

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

acmt001-mcp

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

{
  "mcpServers": {
    "acmt001": { "command": "acmt001-mcp" }
  }
}

随后，Agent 即可按需调用下方的工具来验证账户数据并生成 ISO 20022 消息。

传输方式

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

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

{
  "mcpServers": {
    "acmt001": { "url": "http://127.0.0.1:8000/mcp" }
  }
}

工具

所有工具都委托给共享的 acmt001.services 层，因此其行为与 CLI 和 REST API 完全一致。

• list_message_types — 列出支持的 34 种 acmt 消息类型
• get_required_fields — 获取某消息类型必需的输入字段
• get_input_schema — 获取某消息类型完整的输入 JSON Schema
• validate_records — 根据某消息类型验证扁平记录
• validate_identifier — 验证 IBAN、BIC 或 LEI
• generate_message — 生成通过验证的 acmt XML 消息
• verify_lei_online — 在 GLEIF 实时登记簿中查询 LEI（需要 online 附加项）

使用工具

你可以在进程内直接通过服务实例调用工具，无需使用传输层。这与 Agent 通过标准输入输出接收工具的方式一致。此代码片段的可运行版本位于 examples/mcp_tools.py。

import asyncio

from acmt001_mcp.server import server

# A single flat account-opening record.
record = [
    {
        "msg_id": "ACMT-MSG-0001",
        "creation_date_time": "2026-01-15T10:30:00",
        "process_id": "ACMT-PRC-0001",
        "account_id": "GB29NWBK60161331926819",
        "account_currency": "EUR",
        "account_name": "Treasury Operating Account",
        "account_type_cd": "CACC",
        "account_servicer_bic": "NWBKGB2LXXX",
        "account_owner_name": "Acme Embedded Finance Ltd",
        "account_owner_country": "GB",
        "org_full_legal_name": "Acme Embedded Finance Limited",
        "org_country_of_operation": "GB",
        "org_id_lei": "5493001KJTIIGC8Y1R12",
    }
]


async def main() -> None:
    async def call(name, args):
        result = await server.call_tool(name, args)
        content = result[0] if isinstance(result, tuple) else result
        return content[0].text if content else ""

    # Validate an identifier.
    print(await call("validate_identifier",
                     {"kind": "lei", "value": "5493001KJTIIGC8Y1R12"}))
    # -> {"kind": "lei", "value": "5493001KJTIIGC8Y1R12", "valid": true}

    # Generate a validated ISO 20022 Account Opening Request.
    xml = await call("generate_message",
                     {"message_type": "acmt.007.001.05", "records": record})
    print(xml[:46])  # -> <?xml version="1.0" encoding="UTF-8"?> ...


asyncio.run(main())

直接运行：

python examples/mcp_tools.py

基准测试

python benches/bench_tool_dispatch.py           # full run
python benches/bench_tool_dispatch.py --quick   # what CI runs

基准测试衡量的是 Agent 等待的内容：分发耗时下限（list_message_types，约为微秒级）、用于构建请求的元数据查询，以及两个批处理工具的并列表现。

值得关注的是这两个工具之间的不对称性。validate_records 会检查每条记录，因此耗时随批次大小线性增长。对于默认的 acmt.007.001.05 这类单账户消息类型，generate_message 只渲染第一条记录——三十四个模板中有二十七个采用这种方式。因此，验证一百条记录并据此生成消息，大约需要 260 ms 验证时间和 6 ms 生成时间，最终返回一条消息，而不是一百条。

这是符合 ISO 20022 规范的行为，也是批处理时容易踩到的坑。因此，基准测试会在耗时旁打印输出大小：随着输入增多，字节数保持不变，这就说明批次中的其余记录并未渲染。请参阅 docs/benchmarks.md。

文档

• 渲染后的文档（API 参考、ADR、基准测试、变更日志）： sebastienrousseau.github.io/acmt001-mcp
• 可运行示例： examples/mcp_tools.py
• 架构决策： docs/adr/
• 发布历史： CHANGELOG.md
• 核心库文档： acmt001.com
• MCP 规范： modelcontextprotocol.io

开发

acmt001-mcp 使用 Poetry 和 mise。

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

此包依赖核心 acmt001 库。在它发布到 PyPI 之前，请先从源代码安装： pip install "git+https://github.com/sebastienrousseau/acmt001.git"。

Makefile 负责协调质量检查（与 CI 保持同步）：

make check        # all gates (REQUIRED before commit)
make test         # pytest, 100% line and branch coverage
make lint         # ruff + black
make type-check   # mypy --strict
make doc-coverage # interrogate, 100% docstrings
make mutate       # mutmut over the tool handlers, gated on the score
make docs         # Sphinx site, warnings are errors

基于属性的测试（Hypothesis）会作为 make test 的一部分运行；设置 HYPOTHESIS_PROFILE=mutation 可使用变异测试所用的精简配置。

相关 MCP 服务

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

MCP Registry

mcp-name: io.github.sebastienrousseau/acmt001-mcp

许可证

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

贡献

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

致谢

本项目基于 acmt001 ISO 20022 账户管理库和 Model Context Protocol Python SDK 构建。