MCP 资源订阅变更通知的客户端处理

我在给 MCP 客户端加资源缓存时，最容易混淆的是“资源清单变了”和“某个资源的内容变了”。两者收到的通知不同，后续请求也不同：清单变化要重新调用 resources/list，单资源更新要拿通知中的 URI 重新调用 resources/read。把这两条路径混在一起，轻则多发请求，重则缓存里一直留着旧内容。

官方地址：https://modelcontextprotocol.io/

先分清两类通知与重读动作

资源能力中的 listChanged 面向资源集合，适用于新增、移除或资源元数据发生变化；它没有告诉客户端是哪一个 URI 变了，所以处理方式是重新拉取资源列表并更新本地索引。subscribe 面向具体资源，服务端发送 notifications/resources/updated 时会带上 URI，客户端只需要让这个 URI 失效，再重新读取它。

const resourceUri = 'config://app';

// 这里只把通知当成缓存失效信号，不把它误当成资源正文。
client.setNotificationHandler('notifications/resources/updated', async notification => {
  const uri = notification.params.uri;
  if (uri !== resourceUri) return; // 只处理当前连接明确关注的 URI

  const fresh = await client.readResource({ uri }); // 通知后重新读取正文
  resourceCache.set(uri, fresh); // 读取成功后再替换旧缓存
});

// 清单变更没有具体 URI，应该重新列举资源，而不是逐个 read。
client.setNotificationHandler('notifications/resources/list_changed', async () => {
  const resources = await client.listResources();
  resourceIndex.replace(resources);
});

客户端订阅要绑定 URI 和连接生命周期

在 2026-07-28 协议中，客户端通过 subscriptions/listen 打开长期订阅流，并在 resourceSubscriptions 中给出要关注的 URI。监听器必须早于订阅建立，这样确认消息之后到达的更新不会落空；流关闭后也不要假定订阅仍然存在，应按客户端实现重新建立。

如果需要兼容 2025-era 连接，使用 SDK 提供的 subscribeResource / unsubscribeResource，或直接处理对应的旧 RPC。两条路径的共同点是 URI 精确匹配、服务端必须声明资源订阅能力，以及客户端不能把“订阅请求成功”误判成“以后一定收到通知”。

const watchedUri = 'config://app';

// 先注册处理器，再打开当前协议的订阅流，避免错过早到的更新。
client.setNotificationHandler('notifications/resources/updated', notification => {
  const uri = notification.params.uri;
  if (uri === watchedUri) return refreshOnce(uri); // 同一 URI 合并并发刷新
});

const stream = await client.listen({
  resourcesListChanged: true, // 同时关心资源集合变化
  resourceSubscriptions: [watchedUri] // 只接收这个资源的内容变更
});

async function refreshOnce(uri: string) {
  const running = pendingRefresh.get(uri);
  if (running) return running; // 防止连续通知造成重复 read
  const job = client.readResource({ uri }).then(value => {
    resourceCache.set(uri, value); // 读取完成后才覆盖缓存
  }).finally(() => pendingRefresh.delete(uri)); // 无论成功失败都释放占位
  pendingRefresh.set(uri, job);
  return job;
}

// 应用退出或切换资源时关闭流，避免遗留连接继续接收事件。
await stream.close();

通知到达后的处理顺序与边界检查

更新通知只说明“这个 URI 的内容可能已经变了”，并不携带新的正文、版本号或完整资源对象。因此缓存层应先标记失效，再执行一次读取；读取失败时保留旧值并记录可重试状态，不要把失败结果写成空内容。多个通知同时到达时，以 URI 为键做单飞合并，避免一个资源在短时间内被重复读取。

排查时按四项检查：服务端初始化结果是否包含 resources.subscribe；客户端订阅的 URI 是否与通知 URI 完全一致；订阅流是否仍然存活；多进程服务端是否把更新事件送到了承载订阅的进程。若使用旧协议，还要确认客户端确实走的是 resources/subscribe 兼容路径，而不是把新协议的 listen 请求重试到旧端点。

常见问题

收到 list_changed 后要不要重读全部资源？

不用。先重新列举资源并比较 URI；只有发现某个资源确实需要刷新时，再对目标 URI 调用 readResource。

updated 通知里有没有资源正文？

没有。它主要携带变化资源的 URI，客户端应把它当作失效通知，然后重新读取。

订阅成功但一直收不到通知怎么办？

先看能力声明、URI 精确匹配和长连接状态，再检查服务端是否只在订阅连接所属的事件总线上发布更新。