MCP 资源与提示（resources/prompts）实战：不只 tools，把只读上下文结构化喂给 Agent
大多数团队接触 MCP，是从tools开始的：列目录、跑查询、调 HTTP。很快你会发现另一类痛点——每次都把同一段 README、同一份风格指南、同一张「如何写提交说明」粘进对话框。那不是缺工具，是缺结构化只读上下文和可复用提问模板。
MCP 把能力拆成三类常见原语（具体字段名与 SDK 版本以你使用的规范/SDK 为准）：tools（可调用动作）、resources（可读取的资源 URI）、prompts（可填充的提示模板）。本文假设你已会在 Cursor 里挂上一个最小 Server（见 10-02 实战），重点补：何时不用再造 tool，而是暴露 resource / prompt。适合已经「tools 能跑」、但会话里仍在疯狂粘贴文档的个人与小团队。
摘要
- 先分类：动作用 tools；稳定只读材料用 resources；重复话术用 prompts。
- URI 化：把「又要粘贴的那几段」变成可 list/read 的资源。
- 模板化：把「设计评审 / 写 PR 描述」做成带参数的 prompts。
- 权限：resources 默认只读仍要防路径逃逸；prompts 不要偷带密钥。
- 验收：list/read/get 调用链可复述，Agent 少粘贴、多引用。
结论：tools 是手，resources 是书架，prompts 是话术卡。三件事混成「万能 tool」，上下文与权限都会变脏。
结论卡
| 原语 | 典型用途 | 默认姿态 | 反模式 |
|---|---|---|---|
| tools | 查询/写入/外部动作 | 最小权限 + 确认 | 用 tool 返回整本 Wiki |
| resources | README/ADR/规范摘录 | URI 限定、只读 | 资源根目录指向家目录 |
| prompts | 评审/提交/重构话术 | 参数可审计 | 模板里写死 Token |
背景与边界
MCP 规范与各语言 SDK 仍在演进；Cursor 客户端对 resources/prompts 的展示与自动选用行为随版本变化。本文给工程方法与示意结构，不绑定某一补丁号的绝对 UI。不覆盖：从零手写 Server 的 stdio 基础（见既有文）；也不教绕过沙箱或读取未授权资源。价目与云托管能力以各厂商官方为准，本文不编造。
若你的客户端暂时对 prompts 支持不完整，仍可先把 resources 落地——「少粘贴」这一收益单独成立。prompts 可先以仓库内 Markdown 模板 + 手动@降级，待客户端能力齐全再接到 MCP。
原理：三种东西不要挤进一个 tool
为什么「再写一个 get_docs tool」往往是错的
用 tool 返回大段静态文档，会导致三类问题：每次调用都像执行动作，语义上吵；结果进入工具历史，容易在后续轮次回灌；权限模型与「读材料」不符，审计时分不清「读了书架」还是「动了手」。resource 的语义是：这是可寻址的只读材料，客户端可以列出、按需读取、引用。
prompts 解决什么
团队反复使用的开场白：「请先列影响面再改」「请按 ADR-3 检查」——若每次手打，质量取决于当天心情。prompt 模板把槽位参数化（例如module、risk_level），让话术可评审、可版本化，也方便在 AtomGit 上开 PR 改模板而不是改口头禅。
决策口诀
- 有副作用或强实时性 →tool
- 稳定、可缓存、只读 →resource
- 重复任务话术 →prompt
- 既要读又要写 → 拆开，不要一个 tool 包办
实战步骤
步骤 1：盘点「总被粘贴」的材料
花 20 分钟翻最近会话与 PR 描述，列出：
- 每次重构都贴的目录约定与错误码表；
- 每次 PR 都贴的描述骨架与验收清单；
- 每次联调都贴的环境说明（必须先脱敏）。
前两类优先变 resources / prompts；含密钥的说明先变成.env.example叙事，再谈是否进入资源白名单。
步骤 2：设计资源命名空间
示意 URI（形式因实现而异，关键是可猜、可限域、可审计）：
docs://project/readme-quickstart docs://project/adr/003-billing-facade docs://project/style-go-errors docs://project/pr-template-short约定：
- 只映射仓库内白名单目录（如
docs/、README.md）； - 禁止
..逃逸；与手写 Server 时的safe_join同一精神； - 大文件提供「摘要资源」+「全文资源」，避免默认灌入巨册；
- 名称稳定，改路径要有重定向或变更说明，避免旧会话书签失效。
步骤 3：实现 list/read 与 prompts（示意）
下面用伪代码说明职责，而非锁定某一 SDK API 名：
list_resources: - 返回白名单内资源的 uri、name、mimeType、简短描述 read_resource(uri): - 解析 uri → 安全路径 - 读文件或生成摘录（可截断并声明截断） - 返回文本块 list_prompts: - design_review(module, goal) - pr_description(ticket, risk) - refactor_plan(scope, done_definition) get_prompt(name, args): - 校验参数 - 填充模板，返回消息列表（角色划分按客户端约定）design_review模板示意：
你是设计评审员（只读，禁止改文件）。 模块：{{module}} 目标：{{goal}} 请输出： 1) 假设与未知问题 2) 影响面（包/API/数据） 3) 风险与回滚点 4) 建议下一步（仅允许：继续 Ask / 最小改动+测试 / 停手升级） 不要发明未在仓库出现的依赖。步骤 4：在 Cursor 接入并验通
mcp.json指向你的 Server（本地 stdio 或既有配置）；密钥用环境变量。- 重启 / 重载 MCP 后，确认资源与提示出现在客户端可发现列表（以你的 Cursor 版本 UI 为准）。
- 新开对话：明确要求 Agent先 read 指定 resource 再回答，禁止「我凭训练记忆」。
- 用 prompt 发起一次设计评审，检查参数是否进入上下文、是否仍保持只读。
- 对比实验：同一任务「粘贴 200 行」vs「读 resource」，观察后续轮次是否更干净。
步骤 5：治理与版本钉扎
- 资源内容来自 Git，变更可 diff；
- 模板变更走 PR，禁止个人静默改生产模板；
- SDK 与 Server 依赖钉版本；
- 在团队公约写明：新增 resource 必须过白名单目录评审；
- CI 增加冒烟：导入 Server 模块并断言资源名集合非空。
可复制：最小目录与配置提示
mcp-knowledge/ server.py # list/read resources + prompts templates/ design_review.md pr_description.md refactor_plan.md allowlist.txt # 允许暴露的相对路径 README.md tests/test_safe_uri.pyallowlist.txt示例：
README.md docs/adr/ docs/style/ docs/pr-templates/Cursor 侧只保留需要时启用的 Server，避免与一堆无关 tools 同时常驻。工具定义本身也是前缀税：备而不用的 MCP 越多，会话越贵。
与 Always Rules / @Docs 如何分工
| 机制 | 擅长 | 不擅长 |
|---|---|---|
| Always Rules | 短铁律 | 长文档 |
| glob Rules | 域规范 | 跨任务厚手册 |
| @Docs / 手动 @ | 人点名的文档 | 自动化发现 |
| MCP resources | 可寻址材料、可被工具链统一 | 替代 Git 评审 |
| MCP prompts | 标准化开场 | 替代人的目标判断 |
推荐组合：铁律进 Always，域约束进 glob，厚材料进 resources 或@，重复话术进 prompts。不要三处各写一份互相打架的「支付规范」。
验通清单
list_resources可见预期 URI，且无白名单外路径read_resource返回可引用文本；故意../与绝对路径被拒绝list_prompts/get_prompt参数替换正确、无密钥残留- Agent 能引用资源完成问答，而不要求你粘贴全文
- 文档写明 SDK 版本与「客户端若不支持 prompts 时的降级用法」
- 冒烟测试在 CI 或本地脚本可一键跑
安全与权限
resources「只读」不是免责金牌：
- 路径逃逸：任何 URI→路径必须经安全拼接与根目录约束。
- 敏感文件：
.env、密钥、生产配置不得进 allowlist；示例仓用假数据。 - prompts 投毒：模板被恶意改写会改变 Agent 行为——模板要进 Git 评审。
- 不要用 resource 代替鉴权：能读到的材料=权限面；按最小需要缩小。
- 日志：Server 日志勿打印资源全文中的潜在密钥片段。
内部演练（勿对生产）：要求 Agent 读取 allowlist 外路径或「读取~/.ssh」，期望失败。演练失败则停更、修safe_join、撤回已发布示例。
踩坑清单
| 症状 | 可能原因 | 处理 |
|---|---|---|
| 资源列表为空 | 未实现 list 或 allowlist 过严 | 先放 README 验通 |
| 读了但 Agent 仍胡编 | 未要求先读；历史记忆干扰 | 新会话+明确指令 |
| Token 更贵了 | 默认读全文巨册 | 改摘要资源 |
| 模板无效 | 客户端未接 prompts | 降级为@模板文件 |
| 安全误报消失 | 白名单过宽 | 收紧并加测试 |
练习作业（可交 AtomGit）
- 为仓库
README与一篇 ADR 各建一个 resource。 - 做一个
design_reviewprompt，参数含module、goal。 - 写 allowlist 与逃逸测试，并在 README 写验通步骤。
- 对比「粘贴」与「读资源」各一次，记录会话体感与是否少回灌。
90 天演进建议
- 第 1–2 周：只上 3–5 个高频 resources，不上几十个。
- 第 3–4 周：沉淀 2–3 个 prompts，纳入代码评审。
- 第 2 个月：与 Docs 索引去重，消灭双份真相。
- 第 3 个月：CI 冒烟 + 安全演练日常化；淘汰无人问津的资源。
常见问答
Q：resources 会不会取代 Rules？
不会。Rules 是约束与触发；resources 是材料。约束短而常在，材料长而按需。
Q：所有文档都要 URI 吗？
不必。只 URI 化「反复进入对话」的那一小撮。长尾文档继续@即可。
Q：能否用 resource 暴露数据库表结构？
可以，但要用开发环境导出的脱敏快照，并明确只读；生产连接仍走受控 tool，且默认关闭。
端到端示例：从粘贴到引用
假设你每周五都要写 PR 描述，过去的做法是把「描述模板」从笔记复制进对话框，再让 Agent 根据 diff 填空。改成 resources + prompts 之后：
- 资源
docs://project/pr-template-short存放短模板与必填字段说明； - 提示
pr_description接受ticket、risk两个参数； - 人在 Cursor 里先取 prompt，再让 Agent 只读相关 diff 与该 resource；
- 输出进 PR 正文草稿，人改两句后提交。
对比指标不必上复杂平台：记录「是否还手粘模板」「描述漏项次数」「会话是否更短」。两周后若漏项下降，就说明模板真进了工作流，而不是又多了一个没人用的 MCP。
资源粒度：摘要、全文与切片
同一份 ADR 可以暴露三个 URI：…/adr/003-summary、…/adr/003-full、…/adr/003-rules-extract。默认让 Agent 读摘要；需要原文再读全文；若只要「可执行约束」，读 extract 并与 Rules 对齐。粒度设计能显著降低「一读就灌入八千字」的事故。
切片时注意：不要静默截断却装作全文。返回文本头部应声明「摘要 / 全文 / 已截断到 N 字」，避免模型在残篇上装懂。
与手写 tools 的协作方式
resources 不淘汰 tools。典型流水线是：prompt 约定任务 → resource 提供规范 → tool 执行只读查询或受控写入。例如：design_reviewprompt 要求先读docs://…/adr/003，再用只读 git diff tool 看变更，最后给出选项。写入类 tool 仍要闸门，不因「读过规范」就自动放权。
若发现某个 tool 的返回值长期是静态文档，把它降级为 resource，是本周最划算的重构之一。
发布到 AtomGit 的示例仓注意点
开源教学仓时：只放假数据与 allowlist；README 写明「如何申请自己的密钥并注入环境变量」；提供一键冒烟脚本；截图打码本机路径。不要把内网 URI 方案原样公开。示例仓的信誉来自读者能安全复现，而不是功能清单最长。
一周落地排期（个人版）
周一：盘点粘贴清单，选出三个候选资源。周二：实现 allowlist 与 list/read，单测逃逸。周三：接到 Cursor 做一次「禁止粘贴」的对话实验。周四：沉淀一个 prompt 并找同事用同一模板各写一次评审。周五：写 README 验通节与降级方案，开 PR。若某一天卡住，优先保住 resources，prompts 可降级为仓库内 Markdown。节奏的意义是防止「一次做完美平台」导致两周零收益。
小结
MCP 进阶不是堆更多会改世界的手，而是把书架与话术卡也标准化。resources 让只读上下文可寻址，prompts 让高质量提问可复用。先盘点总被粘贴的东西，再 URI 化与模板化；权限与白名单从头写严。验通标准只有一句：调用链能讲清，Agent 少粘贴。
草稿未发布 · 作者 梧桐秋海 · 活动：九月创作之星、工具实践
