顺利路径偏差
翻阅大多数 MCP 服务器的 README,您能学到如何完成搭建以及该服务器在理想条件下的能力清单。"查询任意 SQL 数据库""读写文件""搜索网络"——此类能力描述准确,却并不完整,因为它们没有告诉您事情出岔时会发生什么。
当您查询一张拥有 1000 万行的表时会发生什么?当查询过程中数据库连接断开时又会怎样?多大体积的文件会无法处理?究竟支持哪些 SQL 方言?这些问题的答案,通常只能通过痛苦的反复试错来获得。
失败场景文档应包含哪些内容
已知限制:"结果集最大容量为 10,000 行,超出部分将被截断。""不支持二进制文件,调用将返回错误。"此类信息可设定合理预期,避免用户在试错中浪费时间。
常见错误情形:"如果出现 connection timeout,数据库服务器可能不可达,请检查配置中的 host 与 port 是否正确。"此类说明能为常见错误提供最有可能的成因,显著节省排障时间。
边界场景:"含 BLOB 列的查询将失败,因为二进制数据无法序列化为 JSON。""在 Windows 上,含 Unicode 字符的文件路径可能不可用。"这些提示可有效避免那些最令人挫败的具体意外。
信任效应
看似有违直觉的是,主动记录失败场景反而能赢得信任。当一份 README 坦诚地写道"该服务器在 10,000 行以下查询表现优异,但应对更大结果集时会吃力",您对作者的信赖感会高于另一份宣称能力无限的文档。同时,您也能据此作出更知情的采纳决策。
优良的失败场景文档,是对开发者体验的投资。理解工具边界的用户会在边界内合理使用并获得良好体验;通过失败才发现边界的用户则体验不佳,进而可能转投替代方案。