MCP 工具 schema 一改就崩?开发者开源 Pyverge 自动迁移 v1→v2 请求载荷

OpinionPurple2940 · reddit · 2026-09-30

开发者维护 FastMCP 工具时反复遇到 schema 演进问题:工具从 v1(location: str)升级到 v2(要求 lat/lng)后,持有旧上下文或缓存 prompt 的 agent 仍发送 v1 格式载荷,导致校验崩溃;在每个工具 handler 里手写 if/else 兼容旧输入又迅速失控。

作者的解法是开源库 Pyverge:迁移逻辑放在 handler 之前而非函数内部,通过定义带版本号的模型和 JSON patch 转换,在请求进入函数前自动将 v1 载荷迁移到 v2。业务逻辑与版本迁移管道解耦。同时提供了 FastMCP 的可运行示例(含 repo 与 showcase 链接),并向社区征询生产环境的 schema 版本管理方案。