MCP工具版本锁定：别让哈希校验成了你的生产事故

在公司给团队部署MCP工具的时候，为了防止服务器端偷偷改接口导致Agent崩溃，我之前给工具清单加了哈希校验（Pinning）。结果发现这玩意儿太死板了：只要服务端改一个字符，哪怕只是给参数加个可选描述，校验直接报错，整个工作流就断了。

说白了，哈希校验只能告诉你“变了”，但不能告诉你“是否搞砸了”。在实际落地中，绝大多数的Schema更新是向下兼容的，但哈希校验把所有变更都当成了“破坏性更新”，导致我们陷入了频繁的人工审核地狱。

要解决这个问题，不能只靠简单的哈希对比，得引入兼容性检查。真正的“破坏性变更”是指新Schema定义的有效调用集比旧的要小，导致之前能跑通的调用现在报错了。

我试着用Python写了一个简单的兼容性检查逻辑 compat_gate.py，核心思路是对比 inputSchema 的差异，并回放之前记录的调用记录。如果是兼容性更新，直接静默通过；如果是破坏性更新，才触发拦截。

这里分享一下判定兼容性的逻辑参考：

• 向下兼容（不拦截）： 增加可选参数、放宽参数限制、修改描述文字。
• 破坏性变更（拦截）： 删除现有参数、将可选参数改为必填、收紧参数取值范围。

具体实现可以用类似这样的逻辑来比对：

def check_compatibility(old_schema, new_schema):
    # 1. 检查必填项是否增加 (增加必填项 = 破坏性)
    old_required = set(old_schema.get('required', []))
    new_required = set(new_schema.get('required', []))
    if not old_required.issubset(new_required):
        # 这里其实是 new_required 必须包含 old_required 且不能增加新必填项
        # 正确逻辑：如果 new_required 有 old_required 没有的元素，则是破坏性的
        if new_required - old_required:
            return False, "New required parameters added"

    # 2. 检查参数是否丢失 (删除参数 = 破坏性)
    old_props = set(old_schema.get('properties', {}).keys())
    new_props = set(new_schema.get('properties', {}).keys())
    if not old_props.issubset(new_props):
        return False, "Existing parameters removed"

    return True, "Compatible"

在公司内部推行这套逻辑后，我们减少了约 80% 的无意义告警。经验之谈就是：在AI Agent的工程化实践中，不要盲目追求绝对的不可变性，而应该追求“可预测的兼容性”。哈希锁定是粗粒度的，而Schema Diff才是真正能给生产环境保驾护航的实操方案。