第 3 章:三个原语:工具、资源、提示词
谁来决定用不用——这是区分三个原语最准的一把尺子。
学习目标
- 用"谁发起"区分 tools、resources、prompts
- 会写一个工具的 schema,并让返回值结构化
- 知道什么时候该用 resource 而不是 tool
- 理解客户端侧三个能力(sampling / roots / elicitation)
3.1 一句话区别
| 原语 | 是什么 | 谁决定使用 | 典型例子 |
|---|---|---|---|
| Tools | 可执行的动作 | 模型(模型判断需要就调) | 发邮件、查订单、跑 SQL |
| Resources | 可读的上下文数据 | 应用(由宿主决定挂什么) | 文件内容、数据库 schema |
| Prompts | 可选的提示词模板 | 用户(在界面上选) | "总结这份周报"、"代码审查" |
3.2 Tools:把 schema 写对
python
# 概念示意:字段名以官方 SDK 为准
@mcp.tool()
def query_stock(sku: str, warehouse: str = "main") -> dict:
"""查询某个仓库里某个 SKU 的库存数量。
Args:
sku: 商品编码,例如 "A100-BLK"
warehouse: 仓库名,默认 main
"""
return {"sku": sku, "warehouse": warehouse, "qty": 42}三个要点:
- description 是给模型看的,不是给人看的文档。"查询库存数量"比"query_stock 函数"有用得多;
- 参数类型要明确,
sku: str会被转成 JSON Schema 的type: string; - 返回值尽量是结构化的,模型读 dict 比读一段拼接字符串准。
返回值最终会被转成 content 数组:
json
{
"content": [
{"type": "text", "text": "{\"sku\":\"A100-BLK\",\"qty\":42}"},
{"type": "resource", "resource": {"uri": "db://stock/A100-BLK", "text": "…"}}
],
"isError": false
}content 支持 text、image、resource(内嵌资源)。图片也走 image 类型,别把 base64 塞进 text。
3.3 Resources:给模型看的"资料",不是"动作"
python
@mcp.resource("file://project/README.md")
def readme() -> str:
return open("README.md", encoding="utf-8").read()三种访问方式:
| 方法 | 用途 |
|---|---|
resources/list | 列出固定资源 |
resources/templates/list | 列出 URI 模板(如 file://project/{path}) |
resources/read | 按 URI 读内容 |
URI 模板很关键:它让"无限多文件"变成一个可枚举的模式,而不是把一万个文件都列出来。
订阅(可选能力):资源变更可以通知客户端刷新。
json
{"jsonrpc":"2.0","method":"notifications/resources/updated","params":{"uri":"file://project/README.md"}}3.4 Prompts:把"常用问法"沉淀下来
python
@mcp.prompt()
def review_code(language: str = "python") -> str:
return f"请按团队规范审查这段 {language} 代码,重点看异常处理与命名。"- 用户在界面上选"代码审查",宿主调
prompts/get拿到模板; - 模板可以有参数,宿主可以让用户填;
- 返回的是一组 messages,直接拼进对话。
它适合"团队沉淀的标准问法",不适合"每次都要动态生成的长提示词"——后者交给应用自己拼更灵活。
3.5 客户端侧三个能力
这三个是客户端提供给 server 的,方向相反:
| 能力 | server 能做什么 | 典型用途 |
|---|---|---|
sampling | 请求客户端"帮我调一次模型" | server 内部要做总结/改写,但不想自带 API key |
roots | 查询客户端允许访问的目录边界 | 文件类 server 只在这些目录里操作 |
elicitation | 向用户索取补充信息 | 参数不够时弹一个确认框 |
roots 特别值得强调:它是权限边界。文件 server 如果不尊重 roots,就可能读到用户没授权的目录——这是第 6 章要讲的安全问题之一。
3.6 决策流程
一句话总结这段判断:
- 有副作用 → tool(只有模型能判断"现在要不要做");
- 只读且由应用控制 → resource(避免模型乱读);
- 只是模板 → prompt(给用户一个入口)。
本章小结
| 要点 | 说明 |
|---|---|
| Tools | 动作,模型决定,需要 schema,有副作用风险 |
| Resources | 数据,应用决定,URI 标识,只读 |
| Prompts | 模板,用户决定,返回 messages |
| 判断口诀 | 动手 → tool,资料 → resource,话术 → prompt |
| 返回值 | content 数组,支持 text/image/resource |
| 客户端能力 | sampling、roots、elicitation |
| roots | 是权限边界,不是建议 |
下一章
协议和原语都清楚了,接下来是"消息怎么传":stdio 还是 HTTP,各自适合什么场景,怎么在本地把 server 调通。