MCP Apps 分块传输大文件实战：突破工具响应大小限制的完整指南-迪斯科星球

MCP Apps 分块传输大文件实战：突破工具响应大小限制的完整指南

【免费下载链接】ext-appsOfficial repo for spec & SDK of MCP Apps protocol - standard for UIs embedded AI chatbots, served by MCP servers项目地址: https://gitcode.com/GitHub_Trending/ex/ext-apps

如果你正在用MCP Apps协议（Model Context Protocol 官方扩展，让 MCP 服务器向 AI 聊天客户端直接交付可交互 UI）构建交互式界面，大概率会撞上一堵墙：工具调用响应有大小限制，一次性返回大文件会被截断甚至报错。本文带你用「App-only 工具 + 分块分页」模式实现MCP Apps 分块传输大文件，轻松突破工具响应大小限制，PDF、图片、视频统统能加载。

为什么大文件不能一次性发回来？

在 MCP Apps 中，工具的响应由宿主（ChatGPT、Claude 等聊天客户端）转发。这里有两个硬性约束：

响应体积上限：部分宿主平台对单次工具响应的大小做了限制，几十 MB 的 PDF 塞不进一条响应
模型上下文宝贵：二进制数据就算能发出去，也会白白吃掉 token，模型根本读不了

所以正确的姿势不是"硬塞"，而是切块：把大文件拆成若干小块，每次只传一块，客户端循环拉取直到拼完。这正是官方文档中推荐的标准模式——分块工具调用读取大数据。

分块传输的核心思路：App-only 工具 + hasMore 分页

整个模式由三个要素组成：

App-only 工具：工具声明_meta: { ui: { visibility: ["app"] } }，只有 UI 能调用，模型完全看不到，大块二进制数据因此彻底绕开模型上下文
分页元数据：每块响应携带offset、byteCount、totalBytes、hasMore四个字段，客户端据此决定"还有没有下一块"
循环拼装：UI 端while (hasMore)循环调用工具，逐块解码、拼接、渲染

服务端实现非常直观，下面这段来自官方模式库 patterns.tsx 的 chunkedDataServer：

const MAX_CHUNK_BYTES = 500 * 1024; // 每块 500KB registerAppTool(server, "read_data_bytes", { inputSchema: z.object({ id: z.string(), offset: z.number().min(0).default(0), byteCount: z.number().default(MAX_CHUNK_BYTES), }), _meta: { ui: { visibility: ["app"] } }, // 仅 App 可见 }, async ({ id, offset, byteCount }) => { const data = await loadData(id); const chunk = data.slice(offset, offset + byteCount); return { content: [{ type: "text", text: `${chunk.length} bytes at ${offset}` }], structuredContent: { bytes: Buffer.from(chunk).toString("base64"), // 二进制 → base64 offset, byteCount: chunk.length, totalBytes: data.length, hasMore: offset + chunk.length < data.length, }, }; });

客户端怎么写：循环拉块直到拼完

UI 端（跑在沙箱 iframe 里的你的界面）只负责循环调用工具。官方模式 chunkedDataClient 的核心逻辑就几行：

let offset = 0, hasMore = true, totalBytes = 0; const chunks = []; while (hasMore) { const result = await app.callServerTool({ name: "read_data_bytes", arguments: { id, offset, byteCount: 500 * 1024 }, }); const chunk = result.structuredContent; hasMore = chunk.hasMore; totalBytes = chunk.totalBytes; chunks.push(atob(chunk.bytes)); // base64 解码 offset += chunk.byteCount; onProgress(offset, totalBytes); // 顺手更新进度条 } // 最后把所有 chunk 拼接成一个完整的 Uint8Array

onProgress回调让你可以实时显示"已加载 68%"，这对大文件体验至关重要——用户看到进度条，就不会以为界面卡死了。

实战案例：官方 PDF 查看器的分块加载

仓库里最完整的实战就是 examples/pdf-server：一个能打开 arXiv 论文、支持批注的交互式 PDF 查看器。它的分块传输设计有几个值得抄作业的亮点：

每块上限 512KB：server.ts 中的 read_pdf_bytes 工具声明了MAX_CHUNK_BYTES = 512 * 1024，输入参数还带.max(MAX_CHUNK_BYTES)硬校验，防止客户端要太多
远程文件走 HTTP Range 请求：读取远端 PDF 时先发Range: bytes=0-524287只取需要的片段；若服务器不支持 Range（返回 501/416），则自动降级为完整 GET + 本地缓存
模型上下文同步：加载过程中通过app.updateModelContext()把"当前第几页、页面文字"告诉模型，用户翻到哪页模型就知道
有专门的 E2E 测试：pdf-incremental-load.spec.ts 验证了分块增量加载的完整链路

客户端拼装逻辑就一行循环：while (hasMore) { 拉块 → 解码 → offset += byteCount }，和上面模式库的代码如出一辙。

另一条路线：MCP 资源 + base64 整包投递

如果文件不算太大（几 MB 以内的视频、图片），还有更省事的方案：走MCP resources。

examples/video-resource-server 演示了这个 base64 blob 模式：

play_video工具返回一个指向 MCP 资源的videoUri
UI 通过resources/read拉取该资源
服务器把视频整体以 base64 blob 返回
UI 解码后塞进<video>标签播放

怎么选？文件超过 5~10MB、或宿主限制严格 → 用 App-only 分块工具；文件几 MB 以内、追求实现简单 → 用资源整包投递。两者可以共存，官方 PDF 示例甚至两种都用到了。

4 个实战技巧，避坑指南 🛠️

块大小选 500~512KB：太小请求次数多、开销大；太大可能触碰更保守宿主的限制
二进制必须 base64：JSON 传输通道走不了裸字节，Buffer.from(chunk).toString("base64")是标配
一定用 App-only 可见性：否则大块 base64 会进模型上下文，token 账单直接爆炸 💸
注意最后一块可能不满：hasMore === false时byteCount可能小于请求值，拼装时以实际byteCount为准，别假设每块都满额

动手跑起来，看看效果 🚀

想亲自体验分块传输？把官方示例仓库克隆到本地：

git clone https://gitcode.com/GitHub_Trending/ex/ext-apps cd ext-apps && npm install && npm start

打开 http://localhost:8080/ 即可看到包含 PDF 查看器在内的全部示例。下面是第一个 MCP App 跑通时的样子，分块加载成功后的界面：

参考资料（相对仓库根目录）：

官方分块模式文档：docs/patterns.md
模式示例源码：docs/patterns.tsx
PDF 分块服务实现：examples/pdf-server/server.ts
PDF 客户端拼装逻辑：examples/pdf-server/src/mcp-app.ts
视频资源模式说明：examples/video-resource-server/README.md
分块加载 E2E 测试：tests/e2e/pdf-incremental-load.spec.ts
协议规范：specification/2026-01-26/apps.mdx

掌握「App-only 工具 + 分页元数据 + 循环拼装」这套组合拳后，无论多大的文件，你的 MCP App 都能稳定传输——工具响应大小限制，从此不再是天花板。

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考

企业官网建设流程全解析