MCP 工具接入与适配规则

适用于把业务能力封装为 MCP Tools，供 AI 在调度、查询与执行链路中稳定调用。

规则文件内容

请复制以下内容，保存为 .cursor/rules/mcp-tool-adapter-pattern.mdc：

---
description: MCP Tools 注册、Schema 约束、超时重试与错误映射规则
globs: src/integrations/mcp/**, src/modules/tools/**
---

# MCP 工具接入与适配业务规则

## 1. 核心原则
- **接口先契约**：每个 Tool 必须先定义输入输出 Schema。
- **调用可恢复**：超时、网络抖动、下游故障需可重试或降级。
- **结果可审计**：每次 Tool 调用都需留痕到日志与审计表。

## 2. Tool 定义规则
- `name` 必须稳定、语义明确，禁止频繁变更。
- `description` 必须包含业务边界与副作用说明。
- `input_schema` 必须声明必填字段、枚举、范围限制。
- `output_schema` 必须给出 `success/error` 的标准结构。

## 3. 参数校验规则
- 请求进入业务逻辑前必须通过 Schema 校验。
- 校验失败返回 `BAD_REQUEST`，禁止直接抛裸错误。
- 风险字段（金额、时间、坐标）需二次业务校验。

```ts
interface ToolResult<T> {
  success: boolean;
  data?: T;
  errorCode?: string;
  errorMessage?: string;
  traceId: string;
}

4. 超时与重试规则

• 默认超时 5s，复杂任务可配置到 15s。
• 仅对幂等操作重试，最多 2 次，指数退避。
• 连续失败触发熔断并返回降级提示。

5. 错误映射规则

• 参数错误 -> BAD_REQUEST
• 权限错误 -> FORBIDDEN
• 下游超时 -> UPSTREAM_TIMEOUT
• 下游不可用 -> UPSTREAM_UNAVAILABLE
• 未知错误 -> INTERNAL_ERROR

6. 权限与租户隔离规则

• Tool 调用必须携带 tenant_id 与 operator_id。
• 跨租户访问一律拒绝。
• 高风险 Tool 需二次确认开关。

7. 观测与审计规则

• 必须记录：tool_name, trace_id, latency_ms, status。
• 错误日志必须包含 error_code 与下游依赖标识。
• 审计表保留最近 180 天调用记录。

8. 数据模型约束

• mcp_tool_calls 必须包含：trace_id, tool_name, tenant_id, input_snapshot, status, latency_ms, created_at
• mcp_tool_errors 必须包含：trace_id, tool_name, error_code, error_message, upstream_service, created_at

9. 实施注意事项

• Tool 名称变更时必须保留兼容别名窗口。
• 输入输出 Schema 建议版本化（v1/v2）。
• 对副作用操作建议开启幂等键校验。

## 适用场景

- MCP 工具服务接入
- AI 调用业务动作封装
- 多系统工具网关适配