Tool 与 MCP 考域：能力设计、协议生命周期与错误处理（18%）

工具设计从最小能力开始

一个工具应完成一个清晰动作。名称要表达意图，描述要说明何时使用，输入 schema 要约束类型、枚举和必填项，输出要区分成功结果和错误。不要把“读取、修改、发布”塞进同一个万能工具。

type SearchDocsInput = {
  query: string;
  limit?: number;
  source: 'official' | 'project';
};

最小接口有三项好处：权限容易控制、测试容易覆盖、失败容易定位。

MCP 的角色关系

MCP 架构中，Host 承载用户体验与安全策略，Client 维护到某个 Server 的连接，Server 暴露 Tools、Resources 和 Prompts。模型并不直接绕过 Host 操作外部系统，权限、确认和审计仍应由宿主应用控制。

三类能力的用途不同：

• Tools：执行动作或计算，通常带参数。
• Resources：提供可读取的上下文或数据。
• Prompts：提供可复用的交互模板。

生命周期

可靠实现要覆盖：

1. 建立传输连接。
2. 初始化并协商版本与 capabilities。
3. 枚举可用能力。
4. 发起调用并返回结构化内容。
5. 处理协议错误、工具错误和业务错误。
6. 关闭连接并释放资源。

任何一步都不应假设“对方一定支持”。能力协商和错误返回必须被程序处理。

权限与安全

工具权限遵循最小授权。只读和写入能力要分开；高风险动作要二次确认；密钥不进入 Prompt；日志要避免记录敏感数据；外部响应在进入上下文前要做大小和类型限制。

对于写操作，可以使用这样的门禁：

是否只读？
  是 → 执行并记录来源
  否 → 检查权限、展示变更、取得批准、执行、验证结果

错误处理

错误信息既要便于模型修正，也不能泄漏内部细节。推荐返回稳定错误码、用户可读摘要、是否可重试和建议动作。对非幂等写操作，不应盲目自动重试。

常见误区

• 工具描述含糊，导致错误选择。
• 输入 schema 过宽，把校验推给模型。
• Client 假设所有 Server 能力一致。
• 把外部文档内容直接当作可信指令。
• 工具失败后无限重试，没有预算或升级路径。

实战检查清单

• 每个工具只有一个主要动作。
• 输入与输出 schema 可自动验证。
• 读写权限分离，高风险动作需要确认。
• 初始化和 capability 协商有测试。
• 错误码、重试策略和幂等性明确。
• 关闭连接与资源清理可以被观测。