Bug: task_result_handler.py serializes None optional fields as JSON null, breaking Node SDK Zod validation

问题场景

Python MCP 服务器运行了一个任务感知工具（task-aware tool），返回 CallToolResult(content=[TextContent(type="text", text="hello")])；Node MCP 客户端发起带 task: {} 的调用，任务完成后客户端请求 tasks/result 时，Zod 解析失败。

报错原文

Zod parse fails: "expected object, received null" at path ["annotations"], "expected record, received null" at path ["_meta"]

原因分析

Python SDK 有两个序列化路径：

• 正常响应（_send_response in session.py）使用了 model_dump(by_alias=True, mode="json", exclude_none=True)，正确省略了 None 字段。
• 任务结果交付（handle in task_result_handler.py line 131）使用了 result.model_dump(by_alias=True)，未加 exclude_none=True，导致 annotations 和 _meta 等可选字段被序列化为 JSON null。

Node SDK 的 Zod schema 将 annotations 定义为 .optional()，仅接受字段缺失（undefined），不接受 null，因此报错。这破坏了任务结果流，回退轮询时结果可能已被消费。

环境排查

• 确认 Python MCP SDK 版本（1.27.0 受影响，v2 已修复）
• 确认 Node @modelcontextprotocol/sdk 版本（1.29.0 对比测试）
• 检查 task_result_handler.py 中 model_dump 是否缺少 exclude_none=True
• 确认服务器返回的 TextContent 对象中 annotations 或 _meta 是否显式设为 None（默认即 None）

解决步骤

1. 定位 Python MCP SDK 安装目录下的 task_result_handler.py（通常在 mcp/shared/task_result_handler.py）。
2. 在第 131 行附近，将 result_data = result.model_dump(by_alias=True) 修改为 result_data = result.model_dump(by_alias=True, exclude_none=True)。
3. （可选）同步检查同文件中其他 model_dump 调用（如第 117、119 行），统一添加 exclude_none=True, mode="json"。
4. 重新启动 Python MCP 服务器，使用 Node 客户端重复调用步骤测试。

验证方法

触发带 task: {} 的工具调用，检查 Node 客户端日志不再出现 Zod 解析错误，且能正常收到 CallToolResult 响应。也可在 Python 端打印序列化的 JSON，确认 annotations 和 _meta 字段已从输出中消失（而非为 null）。

参考来源

modelcontextprotocol/python-sdk #2539

AI 工具推荐

想把多个 AI 模型放在一个入口？

GamsGo AI 集成 ChatGPT、DeepSeek、Gemini、Claude、Midjourney、Veo 等常用模型，适合写作、绘图、视频和日常 AI 工作流。

了解 GamsGo AI

推广链接：通过此链接购买，我可能获得佣金，不影响你的价格。