camt053-mcp 是一个 MCP（模型上下文协议）服务器，把 camt053 这个 ISO 20022 银行对账单库变成 AI 智能体和助手可以直接调用的一组工具。它面向的是标准化银行对客户账户报告、对账单以及借贷通知（camt.05x 现金管理报文），使用户可以在对话中读取和反向生成这些报文。
主要能力 该服务器提供 24 个 MCP 工具（最新版本 v0.0.22），涵盖以下方面：
- 查询与校验：list_message_types（列出声明的 3 种 camt.05x 报文类型）、list_return_reasons（列出 ISO 外部退回原因代码）、get_required_fields（某报文类型的必填字段）、get_input_schema（某报文类型的完整输入 JSON Schema）、validate_records（按报文类型校验扁平记录）、validate_identifier（校验 IBAN、BIC 或 LEI）、validate_statement（按 XSD 校验对账单并识别其类型）。
- 格式转换：convert_mt940_to_camt053（把传统 SWIFT MT940 对账单文本转换为 camt.053 结构）、convert_mt942（把传统 SWIFT MT942 临时交易报告文本转换为 camt.052 结构）。
- 规则与合规：check_cbpr_readiness（标记对账单中的 CBPR+ 2026 年 11 月切换问题）、get_cbpr_cutover_date（返回 CBPR+ 官方切换日期 2026-11-16）、cite_rulebook（引用 SEPA / CBPR+ / HVPS+ 规则手册条款）、list_rulebook_clauses（列出可用规则手册引文，可按条件过滤）、search_rulebook_vector（在不知道条款 id 时，按自然语言相似度检索规则手册条款，需要 [vector] 可选依赖）。
- 导出与分类：export_journal（把对账单分录导出为 Xero BankTransactions 或 QBO JournalEntry 载荷）、list_export_journal_targets（列出 export_journal 支持的会计平台目标）、classify_entry（通过 MCP Sampling 使用客户端 LLM 对分录分类）、list_classify_entry_categories（列出 classify_entry 使用的默认分类）。
- 解析与分析：parse_statement（把传入的 camt.05x 对账单解析为数据）、detect_statement_anomalies（用确定性规则筛查重复引用、异常费用扣减和速度尖峰，不依赖模型或网络）、list_entries（跨所有对账单列出全部分录，分页）、filter_entries（返回带退回原因代码的分录，分页）、generate_reversal（生成经过校验的反向记账 XML 文档）。
- 多租户上下文：get_tenant_context（报告调用的多租户范围，HTTP 传输下来自 Camt053-Account 请求头，stdio 下为 None）。
核心亮点是一次性反向记账工作流：读取传入的 camt.053 对账单，找到带退回原因代码（例如 AC04 账户已关闭）的分录，并生成经过校验的反向记账。
使用方式 安装与运行要求：支持 macOS、Linux、Windows，需要 Python 3.10+ 和 pip，会自动拉取核心 camt053 库和 MCP SDK。 以 stdio（FastMCP 默认传输）启动服务器后，可将其加入任意 MCP 客户端（如 Claude Desktop）的配置中，智能体随后即可按需调用工具解析对账单并生成反向记账。 服务器支持一条命令行切换四种传输方式：stdio、streamable HTTP、SSE 以及带认证的 streamable HTTP（--transport http）。--host 和 --port 可更改 streamable-http 与 sse 的绑定地址（默认 127.0.0.1 和 8000）；这两种传输自身不带认证，建议绑定回环地址或置于可信网关之后。面向共享的多租户部署，可启用带强制 bearer-token 认证的 streamable HTTP，并可选通过 Camt053-Account 请求头做逐请求租户范围限定。HTTP 传输实现 OAuth 2.1 资源服务器认证（RFC 9728 元数据），但不运行授权服务器，需要自带 IdP。 所有工具都是 camt053.services 这一共享门面的轻量类型化封装，因此与 CLI、REST API 行为一致；工具返回可 JSON 序列化的数据，出错时返回 {"error": ...} 载荷而不抛异常。也可以在进程内直接通过 FastMCP 实例调用工具，无需传输层。
适用场景 适合与支持 MCP 的宿主（Claude Desktop、IDE 插件、智能体框架）配合，用于 ISO 20022 银行对账单的解析、校验、合规检查、格式迁移、会计平台分录导出以及反向记账生成；支持 LangChain、CrewAI、LlamaIndex 等多框架智能体适配器。
限制
- 必须有 MCP 客户端：该服务器只在与 MCP 感知宿主配对时才有意义；脚本或 CI 场景应使用 camt053 CLI 与 REST API。
- 需要无 MCP 客户端的长驻守护进程时，可经 streamable HTTP 持久运行，但消费者仍须使用 MCP JSON-RPC；纯 REST 语义请使用 camt053 FastAPI 服务。
- 不支持流式响应：工具调用返回完整值而非流，大对账单通过 list_entries(xml, offset, limit) 分页信封处理，而非跨多个响应分块。
- 不代为处理逐用户 OAuth 流程：HTTP 传输只认证调用方并按租户头限定范围，需要自带身份提供商。
- 不生成 pain.001 对外支付文件，该功能属于 pain001-mcp。
- search_rulebook_vector 使用确定性词法向量（256 维词频向量，含整词和 3/4 字符 n-gram，BLAKE2b 分桶，sqlite-vec 排序），不是神经嵌入模型，只匹配措辞而非含义；需要可选 extra 及 Python 的 SQLite 可加载扩展支持，否则返回指明该 extra 的错误载荷。检索仅索引精选摘要，不存储或检索外部、受版权保护或需鉴权访问的规则手册文本。
项目采用 Poetry 和 mise 开发，用 Makefile 编排与 CI 同步的质量门禁。最新版本还包含多框架智能体适配器、HTTP 传输的 OAuth 2.1 资源服务器认证、Prometheus 指标、防篡改审计链以及真实 HTTP 负载基准。安全方面，防深度防御（defusedxml + xml_guard 字节上限 + DOCTYPE / ENTITY 预检）位于 camt053.services 层。项目以 Apache-2.0 或 MIT 双许可发布，属于 ISO 20022 MCP 套件的一部分。
