Payment Engineering Guardrail MCP

面向 AI Coding Agent 的跨境支付接入 MCP。它不是普通的 API 文档查询器，而是把支付接入中的工程知识、业务规则、安全约束、状态机、测试和问题诊断结构化提供给 Coding Agent。

Problem

Coding Agent 可以快速生成支付 API 调用，但容易遗漏 Webhook 验签、幂等、金额精度、PROCESSING 语义、超时恢复和重复扣款保护。这些问题往往要到联调、验收甚至生产事故后才暴露。

Related MCP server: Tunzaa MCP Server

Solution

Payment MCP = Knowledge + Guardrails + Validation + Tests + Diagnosis

当前 MVP 聚焦 Python + FastAPI + Checkout/Payment Integration，核心规则优先使用 YAML、正则和 Python 静态分析确定性判断，不依赖 LLM 执行安全检查。

User Flow

Developer
  → Coding Agent
  → get_integration_pattern / search_payment_docs
  → Generate or modify code
  → validate_payment_design
  → Fix findings
  → generate_payment_tests
  → pytest
  → diagnose_integration when evidence is ambiguous

MCP Tools

• search_payment_docs：搜索本地结构化 API、支付规则、风险和参考资料。

• get_integration_pattern：返回 FastAPI Checkout 架构、职责和接入 Checklist。

• validate_payment_design：扫描 directory、file 或 source_code，返回 score 和逐条 Finding。

• generate_payment_tests：生成可执行 pytest，覆盖成功/失败、幂等、Webhook、Recovery、超时、429/500、退款和安全。

• diagnose_integration：根据 API、Webhook、日志和源码证据生成时间线、根因、修复建议和回归测试。

所有 Tool 都返回 Pydantic 结构化 envelope：

{"success": true, "data": {}}

非法输入或能力错误：

{"success": false, "error": {"code": "INVALID_INPUT", "message": "..."}}

Architecture

flowchart LR
  Agent[Coding Agent] --> MCP[FastMCP stdio server]
  MCP --> Tools[Tool boundary + Pydantic contracts]
  Tools --> Knowledge[Local payment knowledge]
  Tools --> Pattern[Integration pattern service]
  Tools --> Validator[Validation orchestration]
  Tools --> Tests[Test generator]
  Tools --> Diagnosis[Diagnosis service]
  Validator --> Rules[YAML rule definitions]
  Validator --> Evaluator[Deterministic evaluator]
  Evaluator --> StateMachine[Payment state machine]
  Tests --> MockProvider[MockProvider]
  MockProvider --> StateMachine

规则位于 rules/，当前包含 PAY-001 至 PAY-010。状态机只允许：

CREATED → PROCESSING → SUCCESS
                     ↘ FAILED

终态不可回退；重复应用同一终态是幂等的。MockProvider 支持成功、失败、PROCESSING、timeout、429、500、延迟/重复 Webhook、验签失败和退款；PingPongProvider 当前只保留 fail-closed 的 Sandbox Adapter 边界，不会调用真实生产资金接口。

Quick Start

需要 Python 3.11+ 和 uv。

uv sync --dev
uv run pytest
uv run payment-mcp

MCP 使用 stdio transport，Coding Agent 配置示例：

{
  "mcpServers": {
    "payment-engineering-guardrail": {
      "command": "uv",
      "args": ["run", "payment-mcp"],
      "cwd": "/absolute/path/to/Payment_MCP"
    }
  }
}

Demo

Demo 使用故意有缺陷的本地 FastAPI 风格支付模块，不连接任何真实支付 API：

uv run python demos/run_demo.py

脚本会真实执行：

Buggy Project → validate_payment_design → demo acceptance tests
             → Fixed Project → validate_payment_design → demo acceptance tests

输出包含 Before/After score、critical issues、Finding 和测试结果。当前 demo 的凭证是不可用的本地占位字符串，不是 Sandbox 或 Production Credential。

Benchmark

benchmark/ 提供 10 个任务：Checkout、Webhook Handler、Webhook 验签、Webhook 幂等、状态机、Transaction Recovery、Timeout/Retry、Refund、重复支付保护和 Secret/Security。

每个任务包含：

• 用户需求（不直接泄露完整规则）；

• 固定初始 fixture；

• 独立验收测试。

Runner 自动复制 fixture、运行验收测试、运行 Validator、收集规则违规/严重缺陷/人工干预/完成时间/MCP 调用，并生成 JSON：

uv run python benchmark/runner.py --mode baseline
uv run python benchmark/runner.py --mode mcp
uv run python benchmark/report.py

Coding Agent 执行部分当前是半自动的：开发者可以手动启动 Agent 修改 benchmark/baseline/<task-id>/ 或 benchmark/mcp/<task-id>/，并在候选目录放入可选的 .benchmark_metadata.json：

{
  "execution": "manual",
  "human_interventions": 1,
  "mcp_tool_calls": {
    "get_integration_pattern": 1,
    "validate_payment_design": 2
  }
}

Runner 不会伪造 Agent、模型、Token 或提升数据。只有真正运行 Runner 产生的 benchmark/results/*.json 才能用于 A/B 对比；README 不预填未经实验验证的提升结论。

Security

• 不调用生产支付 API，不执行真实资金操作。

• 不提交真实 Secret、Credential 或完整 Authorization Header。

• 日志和结果应使用脱敏后的 requestId、transactionId 和 provider 响应。

• .env.example 只提供 Mock/Sandbox 占位配置。

Limitations

• 当前仅支持 Python + FastAPI，不是通用 SAST，也不支持 Java、Go、Node.js 或多语言 AST。

• 本项目是个人技术 POC，不是任何支付公司的官方产品。

• 真实 Provider Sandbox 需要额外权限；无权限时由 MockProvider 完成闭环验证。

• 静态 Validator 对无法从源码确定的架构语义会保守处理，Finding 仍需 Agent/开发者复核。

• Benchmark 的 Agent API 自动化尚未接入，当前仅自动化 fixture reset、测试、Validator、Metrics 和结果聚合。