MCP Tool Call Result Truncated 怎么解决？分页、cursor 与结果大小排查

直接答案：Tool call result truncated 通常不代表 MCP 协议规定了统一的 64KB 上限，而是客户端展示限制、工具结果限制、模型上下文预算、序列化体积或传输消费速度中的某一层先触顶。正确修复不是静默截断，而是让 Tool 返回有界结果、总量信息和可继续读取的 cursor/offset；需要完整内容时，再按页读取或先生成摘要与索引。

2026-08-10 版本说明： MCP 2026-07-28 规范已经发布；协议本身仍没有定义统一的“Tool Result 64KB 上限”。TypeScript SDK v2 的 stdio 实现新增了可配置 maxBufferSize，迁移文档给出的默认值是 10 MB——这是 SDK 读取缓冲区的实现边界，不是 MCP 协议对工具结果的统一上限。因此排查时必须区分“协议规则”和“具体客户端/SDK 的实现限制”。

本文解决的问题：信息丢失的物理重置

• 为什么我的 MCP Server 在读取一个 1MB 的日志文件时，Cursor 提示 Tool call result truncated？
• 如何在 Stdio 缓冲区溢出前，优雅地告诉 AI「还有更多内容未读」？
• 为什么简单的物理截断（如 text[:5000]）会导致 AI 产生幻觉？
• 在处理海量数据库查询结果时，如何设计具备「感知力」的流式反馈机制？

---

适合谁读

• AI 系统开发者：正在编写涉及大数据量交互的自定义 MCP Server。
• Agent 架构师：需要解决 Agent 在处理长文档、长日志时的「上下文贫血」问题。
• 全栈工程师：在调试本地私有云 Agent 时，频繁遇到协议层报错或响应超时的技术人。

---

一、病因拆解：先区分协议、客户端与上下文上限

在贵阳花果园的工作室里，我曾尝试让 AI 审计一个 2GB 的 SQLite 原始交易表。结果很快失败，但失败原因不能简单归结为“MCP 只有 64KB”。MCP 的 stdio 传输要求客户端与 Server 通过 stdin/stdout 交换合法的 JSON-RPC 消息，规范本身没有声明一个统一的 64KB 工具结果上限。

真正需要逐层检查的是：客户端是否限制单次 Tool Result 的显示或注入长度、模型剩余上下文是否足够、JSON 序列化后的消息是否过大、宿主进程是否及时消费 stdout，以及工具是否在超时前完成读取。操作系统管道缓冲区可能影响写入是否阻塞，但它不是“超过某个固定字节数就必然截断”的 MCP 规则。

因此，排查时应先记录原始结果字节数、序列化后字节数、客户端实际收到的长度、耗时和截断标记，再决定使用分页、cursor、范围查询、摘要或对象存储链接。官方 MCP 分页适用于 resources/list、tools/list 等列表操作；自定义 Tool 的大结果需要在 Tool Schema 中自行设计 cursor/offset 和明确的 has_more。

---

二、 解决方案 A：物理分页与二级召唤

不要试图一次性喂饱 AI，要教它「翻页」。

1. 建立 Offset 机制

在编写 Tool 逻辑时，强制要求传入 offset 和 limit 参数。

# ✅ 推荐的「物理分页」模式
@app.call_tool("read_large_file")
def read_large_file(path: str, offset: int = 0, limit: int = 5000):
    with open(path, 'r') as f:
        f.seek(offset)
        content = f.read(limit)

        has_more = f.tell() < os.path.getsize(path)

        # 物理反馈：不仅给内容，还要给「元数据」
        return {
            "content": content,
            "metadata": {
                "next_offset": f.tell() if has_more else None,
                "status": "partial_success" if has_more else "complete"
            }
        }

2. 在 System Prompt 中注入「翻页逻辑」

必须明确告诉 AI：「如果检测到 metadata.status 为 partial_success，你必须主动调用下一页，严禁根据残缺信息进行臆测。」

---

三、 解决方案 B：语义压缩（The Semantic Shrink）

物理截断是粗暴的，它会切断逻辑链。真正硬核的做法是在 Server 端进行「感知压缩」。

核心结论：不要让 AI 读原始数据，要让它读「审计报告」。

我们在处理一个包含 10000 行报错信息的生产环境日志时，采用了一套简单的逻辑：

1. 去重：利用正则提取报错指纹，将 500 次相同的 ConnectionTimeout 归类为一行。
2. 头尾采样：保留日志的前 100 行（启动配置）和最后 200 行（故障时刻）。
3. 关键词召回：仅返回包含 ERROR、FATAL 或 RETRY 的上下文 Chunk。

这种方法将 5MB 的日志物理压缩到了 20KB 以内，完美避开了 Stdio 的截断阈值，且 AI 的诊断准确率提升了 40%。

---

四、 对比块：物理截断 vs 逻辑压缩

• 物理截断 (str[:limit])：
  • 优点：代码实现只需 1 行，无计算开销。
  • 缺点：可能切断 JSON 结构或核心逻辑，导致 AI 产生幻觉（Hallucination）。
• 逻辑分页 (Pagination)：
  • 优点：保证了数据的完整性，AI 具备自主决策权。
  • 缺点：增加了对话轮次（Multiple Turns），增加了 Token 消耗。
• 语义压缩 (Summarization)：
  • 优点：最高效，AI 一次性获得高质量上下文。
  • 缺点：Server 端需要额外的算力（如调用本地小模型或更复杂的逻辑）。

---

五、 常见坑与报错 (Error Logs)

1. Error: JSON-RPC message exceeds max length

• 原因：这是具体 Client、SDK、代理层或宿主应用给出的大小限制，不是 MCP 规范统一规定的 1MB 阈值。
• 对策：先查看报错来自哪一层，再记录序列化后的消息大小；避免把 Base64 图片或二进制流直接塞进 Tool Result，改为返回受控 URI、摘要和分段读取参数。

2. Error: Tool Execution Timeout

• 现象：Server 逻辑似乎已经完成，但 Client 仍报告超时。
• 排查：分别记录业务读取耗时、JSON 序列化耗时、写出耗时和 Client 超时配置。超时可能来自查询本身、消息过大、传输背压或宿主超时，不能只凭现象断定 stdout 被某个固定缓冲区截断。

---

六、 常见问题解答

Q: 既然 stdio 容易受到本地进程和宿主限制，为什么不全换成 Streamable HTTP？

A: 两者面向的部署边界不同。stdio 适合由 Client 启动的本地 Server，不需要单独监听端口；Streamable HTTP 更适合远程、多客户端和需要认证、会话与网络可观测性的服务。更换传输并不会自动消除 Tool Result 过大或模型上下文不足的问题。

Q: 如果我必须提供一个 10MB 的 CSV 表格怎么办？

A: 不要把完整文件直接嵌入 Tool Result。把文件保存到经过权限控制、Client 可访问的位置，返回 URI、文件大小、校验值、字段摘要和允许的读取范围；随后由另一个读取 Tool 按行、分片或查询条件取回必要内容。

Q: 如何判断我的 Server 是否发生了截断？

A: 同时记录原始字节数、序列化字节数、Client 实际收到的字节数、校验值、耗时与 has_more。任何固定的 100KB 或 1MB 数字都只能是某个具体 Client 的配置，不能当作 MCP 通用阈值。

---

推荐深度阅读

• MCP 官方传输规范：stdio 与 Streamable HTTP
• MCP 官方分页规范：cursor 与支持分页的列表操作
• MCP 专题：协议、Server、部署与排错入口
• MCP Resources、Tools、Prompts、Roots 有什么区别？
• MCP Stdio 污染与 -32700 Parse Error 排查
• MCP Streamable HTTP 部署：远程传输、会话与安全边界
• MCP 安全治理：Tool 权限、路径与高风险操作

专题入口 / MCP Hub

继续按 MCP 生产部署路径读，而不是堆 guide / tutorial

MCP 内容统一按协议理解、本地 Server、远程部署、OAuth、安全治理、stdio/JSON-RPC 排障和工具对比来承接，避免站内关键词互相抢。

进入 MCP 专题 → 查看安全治理清单 订阅更新