MCP resources/read 返回空内容怎么办：URI 编码、资源类型与客户端缓存边界

MCP 客户端调用 resources/read 后拿到空内容，先别急着把锅甩给模型。这个问题更常见的根因是：请求里的 uri 没有按资源列表返回的原值传回去，响应的 contents 被错误地当成单个对象，或者客户端把旧的资源列表缓存得太久。

先把“空内容”拆成三种结果

排查时先记录原始 JSON-RPC 响应，不要只把它转换成页面上的空字符串。真正的空内容至少有三种：响应里有 contents: []；响应有内容但渲染器只读取了不存在的 text；请求实际上返回了资源不存在或服务端错误，只是客户端把错误吞掉了。

协议层的读取请求方法是 resources/read，参数对象里包含一个字符串 uri。服务端返回的读取结果包含 contents 数组，数组元素可以是文本资源，也可以是二进制资源。这个结构决定了第一步必须保留完整响应，而不是直接做 response.contents[0].text。

URI 要从资源列表原样带回读取请求

资源的 uri 是资源的唯一标识，不是给人看的标题。客户端在列表阶段拿到的 URI 可能包含查询参数、百分号编码、大小写敏感部分或自定义协议。把它解析成路径后再重新拼接，容易丢掉编码或改变语义。

const resource = resources.find(item => item.name === wantedName);
if (!resource) throw new Error("resource not found in list");

const result = await client.request({
  method: "resources/read",
  params: { uri: resource.uri }
});

for (const item of result.contents ?? []) {
  if ("text" in item) renderText(item.text, item.mimeType);
  else if ("blob" in item) renderBinary(item.blob, item.mimeType);
  else throw new Error("unsupported resource content");
}

这里有两个关键点：读取参数使用列表返回的 resource.uri，结果处理遍历 contents。如果业务需要显示名称，应使用 name 或可选的 title 做展示，但不要用展示文本替换 URI。

文本和二进制资源不能共用一个渲染分支

文本资源通常带有 text 字段和可选的 mimeType；二进制资源则使用 blob，其内容是 Base64 表示。渲染器如果只认 text，读取 Markdown、JSON 之外的图片或压缩包时就会表现成“成功但没有内容”。

建议把协议适配层和展示层分开：适配层完整保存 URI、MIME 类型、文本或二进制字段；展示层再决定是否预览、下载或交给下一步解析。不要因为 MIME 类型缺省就猜成 HTML，也不要把任意文本直接插入页面。

缓存问题要看资源列表和读取结果两条链

资源列表可能支持变化通知，但客户端是否订阅、如何刷新，和某一次 resources/read 的结果缓存是两件事。出现“昨天能读、今天空了”时，先比较当前列表中的 URI 与缓存中的 URI，再用原 URI 重读一次并记录响应。

实际验收可以固定四个观察值：列表快照的 URI、读取请求的 URI、响应中的 contents 长度、每个内容项的 text/blob 分支。如果 URI 相同但内容变更，要由服务端或客户端约定更新策略；如果资源已经不存在，应该保留协议错误，而不是返回一个看似正常的空字符串。

一套可复现的排查顺序

1. 保存 resources/list 的原始响应，确认目标资源确实存在，并复制其 URI。
2. 用复制出的 URI 发起一次 resources/read，记录请求和完整响应，不经过展示层转换。
3. 检查是否有 JSON-RPC error；资源不存在时按服务端返回的错误处理，不要把它当成空数组。
4. 检查 contents 是否为数组，分别处理 text 和 blob，同时记录 MIME 类型。
5. 最后再清理资源列表和读取缓存，重做一次同样请求，确认问题来自缓存还是协议适配。

常见问题

resources/read 可以传资源名称吗？

不建议。请求参数是资源 URI，名称只适合用于列表展示和用户选择。正确做法是先从资源列表选中对象，再把它的 URI 原样传入读取请求。

contents 为空时一定是服务端 bug 吗？

不一定。还要同时检查是否吞掉了 JSON-RPC 错误、是否读错资源 URI、是否只支持 text 分支，以及缓存是否仍指向旧资源。

二进制资源为什么看不到文字？

因为二进制内容通常放在 blob 字段中，并以 Base64 表示。客户端应根据 MIME 类型决定预览或下载，不应把它强行当作普通字符串。

把协议边界留在适配层

处理 resources/read 的稳定做法，是把 URI 原值、完整响应、错误信息和内容分支先收敛在一个适配层，再交给缓存与界面。这样即使资源从文本变为二进制、URI 增加编码，或者列表发生变化，也能在日志里看到是哪一层改变了结果。