Skip to content
Lv4MCP 协议进度 3 / 6

第 3 章:三个原语:工具、资源、提示词 ​

谁来决定用不用——这是区分三个原语最准的一把尺子。


学习目标 ​

  • 用"谁发起"区分 tools、resources、prompts
  • 会写一个工具的 schema,并让返回值结构化
  • 知道什么时候该用 resource 而不是 tool
  • 理解客户端侧三个能力(sampling / roots / elicitation)

3.1 一句话区别 ​

原语是什么谁决定使用典型例子
Tools可执行的动作模型(模型判断需要就调)发邮件、查订单、跑 SQL
Resources可读的上下文数据应用(由宿主决定挂什么)文件内容、数据库 schema
Prompts可选的提示词模板用户(在界面上选)"总结这份周报"、"代码审查"
三个原语,三种"决策权"Tools动 作决策者:模型"我需要查库存 → 调用 query_stock"有副作用,要谨慎授权必须有 inputSchema返回值是 content 数组Resources数 据决策者:应用宿主把需要的上下文挂上去只读,通常无副作用用 URI 标识(file:// / db://)支持模板与变更订阅Prompts模 板决策者:用户在界面上选一个"技能"带参数,可预填上下文返回 messages 数组本质是"提示词分发"判断顺序:这件事要不要动手?要动手 → tool;只是提供资料 → resource;只是给个话术 → prompt。最常犯的错:把"读文件"做成 tool。它有副作用风险(模型可以随便读),而 resource 天然只读、由应用控制。但如果你需要"按路径读任意文件",那就是 tool —— 因为走哪条路径得由模型决定。

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}

三个要点:

  1. description 是给模型看的,不是给人看的文档。"查询库存数量"比"query_stock 函数"有用得多;
  2. 参数类型要明确,sku: str 会被转成 JSON Schema 的 type: string;
  3. 返回值尽量是结构化的,模型读 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 调通。

本文阅读--次|全站访问--次|访客--人