# Payment Engineering Guardrail MCP

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

## Problem

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

## Solution

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

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

## User Flow

```text
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：

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

非法输入或能力错误：

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

## Architecture

```mermaid
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。状态机只允许：

```text
CREATED → PROCESSING → SUCCESS
                     ↘ FAILED
```

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

## Quick Start

需要 Python 3.11+ 和 [uv](https://docs.astral.sh/uv/)。

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

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

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

## Demo

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

```bash
uv run python demos/run_demo.py
```

脚本会真实执行：

```text
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：

```bash
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`：

```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 和结果聚合。