MCP 工具注解

MCP 工具的安全元数据 — 读/写/破坏性提示，用于正确的客户端确认 UI。

AACWorkflow 提供的每个 MCP 工具都带有安全元数据注解，使 MCP 客户端（Claude、ChatGPT、自定义工具）能渲染正确的确认 UI 并在调用敏感操作前强制适当的防护。

注解类型

注解	含义	示例
`ReadOnlyHint`	不修改状态	`list_issues`, `get_issue`, `dashboard_usage_daily`
`DestructiveHint`	可能删除或覆盖数据	`delete_issue`, `delete_comment`
`IdempotentHint`	重复调用没额外效果	`update_issue`, `assign_issue_to_agent`
`OpenWorldHint`	接触外部系统	任何调用 GitHub、Telegram 或第三方 API 的工具

工具分类

工具	仅读	破坏性	幂等	范围
`list_issues`	✓		✓	`issues:read`
`get_issue`	✓		✓	`issues:read`
`list_comments`	✓		✓	`comments:read`
`dashboard_usage_daily`	✓		✓	`dashboard:read`
`create_issue`				`issues:write`
`update_issue`			✓	`issues:write`
`comment_issue`				`comments:write`
`assign_issue_to_agent`			✓	`agents:write`
`trigger_autopilot`				`autopilot:run`
`delete_issue` (若添加)		✓	✓	`issues:write`

客户端行为

仅读工具

MCP 宿主不为仅读操作要求确认。工具可安全调用而无用户交互。

破坏性工具

调用破坏性工具前，MCP 宿主必须：

请求用户确认 — 「确定要删除此 issue 吗？」
在工具参数中传递 confirm: true

服务器验证 confirm: true 存在。若缺失，调用被拒绝并返回 400 Bad Request：

{
  "error": "confirm: true required for destructive operations"
}

幂等工具

幂等工具可安全重试而无副作用。MCP 宿主可多次调用（如为对抗瞬时故障）并获得相同结果。

读写工具（非幂等）

如 create_issue 和 comment_issue 创建新实体的工具非幂等。MCP 宿主不应在失败时重试 — 这会创建重复记录。

服务器强制

注解对客户端建议但在服务器上权威：

范围被强制 — 破坏性调用仍失败若令牌缺 issues:write，无论客户端提示如何
破坏性标志被检查 — 破坏性工具缺 confirm: true 在服务器端被拒绝
仅读查询被审计 — 即使仅读调用也被记录用于合规，但不需确认

示例：破坏性工具调用

客户端要删除 issue。流程：

客户端检查工具注解并看到 DestructiveHint: true
客户端提示用户：「删除 issue AAC-42？」
用户确认
客户端使用 confirm: true 调用工具

{
  "name": "delete_issue",
  "arguments": {
    "issue_id": "550e8400-e29b-41d4-a716-446655440000",
    "confirm": true
  }
}

服务器验证：

令牌有 issues:write 范围
confirm: true 存在
Issue 存在且属于令牌工作区
用户有权限

若所有检查通过，issue 被删除。否则返回 400 或 403 错误。

实现说明

仅读工具处理器绝不调用 Queries.Update* 或 Delete* 方法。CI 测试对所有标记为 ReadOnlyHint: true 的工具强制此不变。

每个工具处理器被标记其注解
注解嵌入在向 MCP 服务器注册时的 MCP Tool 定义中
相同注解由 /tools introspection 端点返回使客户端可发现能力
范围检查在令牌层发生；注解补充但不替代范围强制

审计追踪

每个工具调用（读或写，成功或拒绝）被记录在连接器审计日志中：

{
  "tool": "delete_issue",
  "outcome": "denied",
  "reason": "destructive_flag_missing",
  "scopes_provided": ["issues:write"],
  "timestamp": "2025-06-22T15:30:00Z"
}

这让管理员监控哪些工具被调用并检测异常模式。

本页目录