MCP 资源与提示（resources/prompts）实战：不只 tools，把只读上下文结构化喂给 Agent

MCP 资源与提示（resources/prompts）实战：不只 tools，把只读上下文结构化喂给 Agent

大多数团队接触 MCP，是从 tools 开始的：列目录、跑查询、调 HTTP。很快你会发现另一类痛点------每次都把同一段 README、同一份风格指南、同一张「如何写提交说明」粘进对话框。那不是缺工具，是缺结构化只读上下文 和可复用提问模板。

MCP 把能力拆成三类常见原语（具体字段名与 SDK 版本以你使用的规范/SDK 为准）：tools （可调用动作）、resources （可读取的资源 URI）、prompts （可填充的提示模板）。本文假设你已会在 Cursor 里挂上一个最小 Server（见 10-02 实战），重点补：何时不用再造 tool，而是暴露 resource / prompt。适合已经「tools 能跑」、但会话里仍在疯狂粘贴文档的个人与小团队。

摘要

1. 先分类：动作用 tools；稳定只读材料用 resources；重复话术用 prompts。
2. URI 化：把「又要粘贴的那几段」变成可 list/read 的资源。
3. 模板化：把「设计评审 / 写 PR 描述」做成带参数的 prompts。
4. 权限：resources 默认只读仍要防路径逃逸；prompts 不要偷带密钥。
5. 验收：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 接入并验通

1. mcp.json 指向你的 Server（本地 stdio 或既有配置）；密钥用环境变量。
2. 重启 / 重载 MCP 后，确认资源与提示出现在客户端可发现列表（以你的 Cursor 版本 UI 为准）。
3. 新开对话：明确要求 Agent 先 read 指定 resource 再回答，禁止「我凭训练记忆」。
4. 用 prompt 发起一次设计评审，检查参数是否进入上下文、是否仍保持只读。
5. 对比实验：同一任务「粘贴 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.py

allowlist.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「只读」不是免责金牌：

1. 路径逃逸：任何 URI→路径必须经安全拼接与根目录约束。
2. 敏感文件 ：.env、密钥、生产配置不得进 allowlist；示例仓用假数据。
3. prompts 投毒：模板被恶意改写会改变 Agent 行为------模板要进 Git 评审。
4. 不要用 resource 代替鉴权：能读到的材料=权限面；按最小需要缩小。
5. 日志：Server 日志勿打印资源全文中的潜在密钥片段。

内部演练（勿对生产）：要求 Agent 读取 allowlist 外路径或「读取 ~/.ssh」，期望失败。演练失败则停更、修 safe_join、撤回已发布示例。

踩坑清单

症状	可能原因	处理
资源列表为空	未实现 list 或 allowlist 过严	先放 README 验通
读了但 Agent 仍胡编	未要求先读；历史记忆干扰	新会话+明确指令
Token 更贵了	默认读全文巨册	改摘要资源
模板无效	客户端未接 prompts	降级为 @模板文件
安全误报消失	白名单过宽	收紧并加测试

练习作业（可交 AtomGit）

1. 为仓库 README 与一篇 ADR 各建一个 resource。
2. 做一个 design_review prompt，参数含 module、goal。
3. 写 allowlist 与逃逸测试，并在 README 写验通步骤。
4. 对比「粘贴」与「读资源」各一次，记录会话体感与是否少回灌。

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 之后：

1. 资源 docs://project/pr-template-short 存放短模板与必填字段说明；
2. 提示 pr_description 接受 ticket、risk 两个参数；
3. 人在 Cursor 里先取 prompt，再让 Agent 只读相关 diff 与该 resource；
4. 输出进 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_review prompt 要求先读 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 少粘贴。

---

草稿未发布 · 作者 梧桐秋海 · 活动：九月创作之星、工具实践