D3 resources 与 prompts：URI 模板、变更通知、进度与日志、分页，以及客户端能力

今日目标

能判断一份数据该做成资源还是做成工具，并说出判断依据
能用 URI 模板暴露一组参数化资源，并为列表接口实现游标分页
能说清订阅流与请求内通知的区别，并各举一个使用场景

昨天你的服务端只有工具，一共两个，谁调都一样快。今天换一份真实体量的数据进来——几千篇笔记——你会立刻撞上分页、缓存和通知这三堵墙。完整的报文骨架 D1 已经拆过一遍，今天只看新增的那几个字段。读完回来把上面三条勾掉。

小白版讲解

资源是应用驱动的：谁决定它进不进上下文

先回到插座那个类比。工具像是电器上的开关：模型看着说明书自己按。资源不一样，它更像插排上贴的标签——宿主应用或用户扫一眼，决定这一路要不要通电。

规范把这件事说得很直白：资源是"应用驱动"（application-driven）的，由宿主应用决定怎么把它并进上下文。典型的界面形态是一个文件选择器、一棵目录树，或者一个搜索框；也可以由应用按启发式规则自动带上。而工具是"模型控制"的，模型看着描述自己挑。

所以同一份数据做成哪一种，判据不是"它是什么"，而是这一次由谁来决定用不用它：

情况	做成
只读、可枚举、希望用户在界面上挑	资源
会产生副作用，或要由模型自己判断何时使用	工具
需要一次检索出结果，而不是先列后读	工具（哪怕它是只读的）

最后一行是最容易搞错的地方。"搜索代码"看起来是只读的，像资源，但它没法枚举——你不可能把所有可能的查询词列成一张清单让用户挑。能不能被列出来，是资源和工具之间那条最实用的分界线。

这条分界线还有一个说不出口但很现实的好处：资源不进上下文就不花钱。工具的定义无论用不用，每一轮都要塞进请求里；资源只是一条清单项，宿主不选它就一个 token 都不占。一个有三千篇文档的知识库，做成三千个工具会直接把上下文撑爆，做成资源则只在用户点中那一篇时才付费。

问题也就跟着来了：三千篇笔记，resources/list 一次性全吐回去吗？

URI 模板：一条定义顶一整组资源

答案当然是不能全吐，但在讲分页之前，先解决一个更前置的问题：有些资源你根本列不完，但它们又确实是可枚举的一族。

比如"按标签读笔记"。标签有几十个，每个标签下有若干篇，组合起来几百上千条，全列出来既慢又没人看。规范给的办法是资源模板（resource template）：用 resources/templates/list 返回一条 RFC 6570 格式的 URI 模板，把变化的部分留成占位符。

JSONJSON

{
  "resourceTemplates": [
    {
      "uriTemplate": "notes:///{tag}/{slug}",
      "name": "note-by-tag",
      "title": "按标签读一篇笔记",
      "mimeType": "text/markdown"
    }
  ],
  "ttlMs": 300000,
  "cacheScope": "public"
}

客户端拿到这条模板，就知道 notes:///mcp/pagination 是一个合法的资源地址，不需要它出现在清单里。占位符还可以接上补全接口，让用户在界面上边打边提示。

URI 的 scheme 怎么选，规范给了几条现成的：file:// 用于表现得像文件系统的东西（不一定真是文件）；git:// 是版本控制；https:// 有一条特别的限制——只在客户端能自己从网上抓到时才用它，如果内容其实得经过服务端，就别用 https，另定一个 scheme。自定义 scheme 只要符合 RFC 3986 就行，本课的实验用的是 notes:///。

自定义 scheme 好写，但有个必须自己堵的坑：

分页是必修课：游标不透明，页大小由服务端说了算

回到那三千篇笔记。MCP 的分页用的是不透明游标（opaque cursor），不是页码。规则只有几条，但每一条都有人踩：

游标是一个不透明的字符串，客户端不得解析它、修改它，也不得根据它的内容做任何判断。
页大小由服务端决定，客户端不得假设它是固定值。
只有 nextCursor 缺失才代表结束。 空字符串是一个完全合法的游标，把它当成结束是明确被禁止的。
非法游标应当回 -32602（Invalid params），而不是静默返回第一页。

支持分页的一共四个操作：resources/list、resources/templates/list、prompts/list、tools/list。

服务端这边爱怎么编游标都行——base64 包一个偏移量、一个数据库主键、一个时间戳都可以，反正对面不许看：

pagination.ts

const PAGE_SIZE = 50
 
export function encodeCursor(offset: number): string {
  // 包一层 base64 不是为了保密，是为了让客户端没法顺手去解析它
  return Buffer.from(`offset:${offset}`, 'utf8').toString('base64url')
}
 
export function decodeCursor(cursor: string | undefined): number {
  if (cursor === undefined) return 0 // 只有 undefined 才是「没有游标」
  const decoded = Buffer.from(cursor, 'base64url').toString('utf8')
  const match = /^offset:(\d+)$/.exec(decoded)
  if (!match) throw new InvalidCursorError(cursor) // 非法游标要报错，不能静默回第一页
  return Number(match[1])
}
 
export function paginate(all: string[], cursor: string | undefined) {
  const offset = decodeCursor(cursor)
  const items = all.slice(offset, offset + PAGE_SIZE)
  const nextOffset = offset + items.length
  // 只有确实还有下一页时才给 nextCursor；缺失本身就是结束的信号
  return nextOffset < all.length ? { items, nextCursor: encodeCursor(nextOffset) } : { items }
}

pagination.py

import base64
import re
 
PAGE_SIZE = 50
 
 
class InvalidCursorError(ValueError):
    code = -32602
 
 
def encode_cursor(offset: int) -> str:
    # 包一层 base64 不是为了保密，是为了让客户端没法顺手去解析它
    return base64.urlsafe_b64encode(f"offset:{offset}".encode()).decode().rstrip("=")
 
 
def decode_cursor(cursor: str | None) -> int:
    if cursor is None:  # 只有 None 才是「没有游标」
        return 0
    padded = cursor + "=" * (-len(cursor) % 4)
    match = re.fullmatch(r"offset:(\d+)", base64.urlsafe_b64decode(padded).decode())
    if match is None:  # 非法游标要报错，不能静默回第一页
        raise InvalidCursorError(cursor)
    return int(match.group(1))
 
 
def paginate(all_items: list[str], cursor: str | None) -> dict:
    offset = decode_cursor(cursor)
    items = all_items[offset : offset + PAGE_SIZE]
    next_offset = offset + len(items)
    # 只有确实还有下一页时才给 nextCursor；缺失本身就是结束的信号
    if next_offset < len(all_items):
        return {"items": items, "nextCursor": encode_cursor(next_offset)}
    return {"items": items}

工程代价藏在一个不显眼的地方：偏移量式游标要求列表顺序稳定。readdir 在不同文件系统上的返回顺序并不一致，中途插入一篇笔记也会让后面所有偏移量整体错位，客户端翻到第二页时会漏掉或重复。所以要么先排序，要么把游标编成"上一条的主键"而不是偏移量。今天的实验用的是排序加偏移量，够用且好读，但你要知道它的前提。

缓存提示 ttlMs 与 cacheScope

2026-07-28 新增了一个 CacheableResult 接口，把两个字段变成了必填：tools/list、prompts/list、resources/list、resources/read、resources/templates/list 这五个结果都要带上 ttlMs 和 cacheScope。

ttlMs 是新鲜度提示，单位毫秒，告诉客户端"这份东西可以缓存多久"，目的是减少轮询。cacheScope 只有两个取值：public 表示共享的中间层（网关、代理）也可以缓存这份响应，private 表示只能缓在这个客户端自己那儿。

用起来的直觉是：清单变得慢，正文变得快，两者的 ttl 应该差一个数量级；跟调用者身份有关的东西一律 private——工具清单可能随授权范围变化，那就不能是 public。

JSONJSON

{
  "resources": [{ "uri": "notes:///pagination", "name": "pagination", "mimeType": "text/markdown" }],
  "nextCursor": "b2Zmc2V0OjM",
  "ttlMs": 300000,
  "cacheScope": "public"
}

这套缓存提示和 listChanged 通知是互补关系，不是二选一：ttl 管的是"没有通知时你可以放心用多久"，通知管的是"变了我告诉你"。两个都给，客户端才能既不频繁轮询、又不拿着过期数据。

顺带一提，规范还建议 tools/list 应当返回确定性顺序——同一批工具在多次请求间的排列不要变。理由不只是好看：顺序稳定，客户端才敢缓存工具清单，而工具清单通常是要塞进模型上下文的，顺序一抖动，提示缓存就整体失效，这是实打实的钱。

提示模板：把团队里那句问烂了的话变成一个斜杠命令

第三种原语是提示模板（prompt）。它是用户控制的：由用户显式选中，典型形态就是聊天框里的斜杠命令。

它解决的是一个很土但很real的问题：团队里总有那么几句话被反复打，"帮我 review 这段代码，重点看并发安全"、"把这个报错翻译成人话并给三个排查方向"。每个人自己存一份，版本还各不相同。做成提示模板之后，它跟着服务端走，改一次所有人都更新。

prompts/get 返回的是一组消息，role 只有 user 和 assistant 两种，content 可以是文本、图片、音频、资源链接（resource_link）或内嵌资源（resource）。这里有个值得琢磨的设计选择：

digest-prompt.ts

// 按标签汇总笔记的提示模板
async function getDigestPrompt(tag: string) {
  const hits = await notesByTag(tag)
  return {
    description: `标签 ${tag} 下共 ${hits.length} 篇笔记`,
    messages: [
      { role: 'user', content: { type: 'text', text: `请把下面这些笔记汇总成不超过 200 字的要点。` } },
      // 用 resource_link 而不是内嵌正文：让宿主自己决定要不要真去读，
      // 正文进不进上下文由应用说了算——这正是「资源是应用驱动」在报文层面的样子
      ...hits.map((n) => ({
        role: 'user' as const,
        content: { type: 'resource_link' as const, uri: `notes:///${n.slug}`, name: n.slug },
      })),
    ],
  }
}

digest_prompt.py

# 按标签汇总笔记的提示模板
async def get_digest_prompt(tag: str) -> dict:
    hits = await notes_by_tag(tag)
    messages: list[dict] = [
        {"role": "user", "content": {"type": "text", "text": "请把下面这些笔记汇总成不超过 200 字的要点。"}}
    ]
    # 用 resource_link 而不是内嵌正文：让宿主自己决定要不要真去读，
    # 正文进不进上下文由应用说了算——这正是「资源是应用驱动」在报文层面的样子
    messages += [
        {
            "role": "user",
            "content": {"type": "resource_link", "uri": f"notes:///{n.slug}", "name": n.slug},
        }
        for n in hits
    ]
    return {"description": f"标签 {tag} 下共 {len(hits)} 篇笔记", "messages": messages}

返回链接而不是正文，是把"要不要花这份 token"的决定权交还给宿主。如果你直接内嵌，一个命中三十篇的标签会瞬间灌进几万 token，而用户可能只想看其中两篇。错误处理这边很简单：提示模板名无效、缺必填参数，都用 -32602；服务端内部出错用 -32603。

两条通知通道：订阅流管长期变更，响应流管这一次的进度

这一节是本章和旧文档差别最大的地方，读到网上任何讲 resources/subscribe 的材料都可以直接跳过了。

2026-07-28 把 resources/subscribe 和 resources/unsubscribe 两个方法、以及 HTTP 上那条独立的 GET 长连接，一起换成了一个 subscriptions/listen。它本身是一条普通请求，只不过它的响应是一条一直开着的通知流。客户端在 notifications 过滤器里显式勾选想收哪几类，服务端不得推送没被勾选的类型：

JSONJSON

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "subscriptions/listen",
  "params": {
    "notifications": {
      "toolsListChanged": true,
      "resourceSubscriptions": ["notes:///pagination"]
    }
  }
}

四个可选字段是 toolsListChanged、promptsListChanged、resourcesListChanged 和 resourceSubscriptions（一个 URI 数组）。流上的第一条消息必须是 notifications/subscriptions/acknowledged，里面回的是服务端实际答应的那个子集——它不支持的类型会被悄悄去掉，所以客户端应当拿它和自己请求的对一遍。此后每一条通知都会在 _meta 里带上 io.modelcontextprotocol/subscriptionId，值就是当初那条 subscriptions/listen 请求的 JSON-RPC id。stdio 上所有消息共用一条通道，客户端必须靠这个字段区分是哪个订阅来的。

另一条通道完全不同：请求内通知只走它所属那条请求的响应流。notifications/progress 和 notifications/message 属于这一类，它们不会出现在订阅流上。进度要靠客户端在请求的 _meta 里放一个 progressToken 来开启，之后服务端可以发若干条带 progress（必须递增）、可选 total 和 message 的通知：

JSONJSON

{
  "jsonrpc": "2.0",
  "method": "notifications/progress",
  "params": { "progressToken": "abc123", "progress": 50, "total": 100, "message": "正在建索引" }
}

一句话记住分工：订阅流回答"世界变了吗"，响应流回答"我这一单做到哪了"。 前者跨请求、长期存在；后者随请求生随请求死。

日志这边有个必须知道的变化：日志功能（Logging）连同 Roots、Sampling 一起，在这一版被标记为弃用（deprecated），弃用窗口至少十二个月，新实现不该再采用。logging/setLevel 方法已经删除，日志级别改成每请求在 _meta.io.modelcontextprotocol/logLevel 里指定，而且服务端不得对没带这个字段的请求发 notifications/message。官方建议的迁移路径是：stdio 直接写 stderr，或者接 OpenTelemetry。

客户端能力：为什么服务端不能假设对面会弹表单

最后一块拼图。服务端想让用户填个东西、或者想借客户端的模型跑一段推理，前提是对面得有这个能力。规范对此的要求是硬的：服务端不得依赖客户端没有声明的能力；真的需要而对方没声明时，必须回 -32021（MissingRequiredClientCapability），并在 data.requiredCapabilities 里列出缺了哪些。

这一版的客户端能力以 elicitation（征询）为主——就是"弹个表单问用户"这件事。声明长这样：

JSONJSON

{
  "_meta": {
    "io.modelcontextprotocol/clientCapabilities": {
      "elicitation": { "form": {}, "url": {} }
    }
  }
}

两种模式：form 是在客户端界面里收结构化数据，schema 被刻意限制成扁平对象加基础类型（字符串、数字、布尔、枚举），复杂嵌套一律不支持，为的是让任何客户端都能自动生成表单。url 是把用户导到服务端自己的安全页面上去。规范硬性规定：密码、API key、访问令牌、支付凭证这类东西不得用 form 模式收，必须走 url 模式——因为 form 收上来的数据会经过客户端，而 url 模式下敏感信息只在用户浏览器和服务端之间流动。为了向后兼容，一个空的 elicitation: {} 等价于"只支持 form"。

Roots 和 Sampling 已经弃用了，所以你今天设计服务端时，能指望的客户端能力基本就是 elicitation 这一个。默认假设对面什么都不会，需要额外输入时把它做成工具参数让模型来填，实在不行再退回到征询——这是 2026 年写 MCP 服务端最稳妥的姿势。

至于"工具和资源太多，上下文塞不下"的通用裁剪策略，那是另一门课的主场，需要时去看工具结果与检索的上下文管理，本课只负责把 MCP 这一层的接口讲干净。

源码导读

动手实验

🧪 D3 实验：一个把本地 Markdown 笔记库暴露成资源的 MCP 服务端

代码位置：labs/mcp-7days/day-03-notes-resource-server

验收标准：

resources/list 能翻完全部笔记，第二页与第一页不重复，最后一页不带 nextCursor
非法游标被拒绝，而不是静默返回第一页
resources/templates/list 返回一条带 uriTemplate 的资源模板，resources/read 能读到笔记正文
prompts/get 按标签筛出笔记，并为每一篇附上一条 resource_link
MOCK=1 SELFTEST=1 pnpm start 六项全绿，退出码为 0

实验完全离线，数据就是仓库里的八篇 Markdown，不需要任何 key。starter 原样跑是 1 / 6 通过，四个练习点各对应若干条红项——把红的一条条变绿，就是今天的全部工作。做完第一个练习之后会撞上一个很值得琢磨的现象：清单条数对了，翻页却在原地打转。原因是 starter 的游标编码返回的是空字符串、解码恒定返回 0，而空串是一个合法游标、并不代表结束——这正是本章那条规则的现场演示。卡住了先回到上面"分页是必修课"那一节。

打开 solution 的 server.ts，找到 resources/list 与 resources/templates/list 两个处理器，看清静态清单与 URI 模板分别长什么样。
在 starter 的 notes.ts 里补全 scanNotes，跑一次自测，看到第 1 项的条数从 1 变成真实笔记数。
补全 pagination.ts 的游标编解码，跑自测确认第 2 项变绿、并且第 6 项也跟着变绿。
补全 server.ts 里的资源模板与按标签检索的提示模板，让第 4、5 项变绿。
用 MOCK=1 pnpm start 常驻起来，接上你自己的客户端或 Inspector，亲眼确认 ttlMs 与 cacheScope 出现在响应里。

面试题

今天 3 道题在下方题库区，侧重资源与工具的边界、URI 设计、分页与缓存、通知通道的分工。展开后先看"分析过程"再看要点——照着推导练，比背要点管用。标注"国内高频 / 海外高频"方便按目标市场取舍。

检查清单与明日预告

能判断一份数据该做成资源还是做成工具，并说出判断依据
能用 URI 模板暴露一组参数化资源，并为列表接口实现游标分页
能说清订阅流与请求内通知的区别，并各举一个使用场景
能说出 ttlMs 与 cacheScope 各管什么，以及它们和 listChanged 是什么关系
知道 Roots、Sampling、Logging 三项已被弃用，以及各自建议的迁移路径
实验的 5 条验收标准全部通过
3 道面试题不看要点也能答出至少 2 道

明天（D4）把服务端搬到公网上去。顺序是有意的：前三天所有东西都跑在本机子进程里，传输的坑被 stdio 挡掉了大半；一旦换成 HTTP，鉴权、多副本、来源校验、超时会一次性全冒出来，而这一版恰好把会话、GET 长连接和断流续传全删了，客户端要补的东西比你想的多。今天学的分页与缓存到那时会立刻显出价值——无状态加上可缓存的清单，才是多副本部署能横着扩的前提。

resources 与 prompts：URI 模板、变更通知、进度与日志、分页，以及客户端能力

今日目标

小白版讲解

资源是应用驱动的：谁决定它进不进上下文

URI 模板：一条定义顶一整组资源

分页是必修课：游标不透明，页大小由服务端说了算

缓存提示 ttlMs 与 cacheScope

提示模板：把团队里那句问烂了的话变成一个斜杠命令

两条通知通道：订阅流管长期变更，响应流管这一次的进度

客户端能力：为什么服务端不能假设对面会弹表单

源码导读

动手实验

面试题

检查清单与明日预告

面试题库

评论