MCP Python SDK · 第 5 章 资源、模板与提示词

MCP Python SDK · 第 5 章 资源、模板与提示词

章节摘要:第 4 章讲了模型驱动的工具,本章讲另外两类原语——应用控制的资源与用户控制的提示词。它们不像工具那样有副作用、由模型决定调用,而是各自服务于不同的交互模式:资源是「宿主按需加载进模型上下文的只读数据」(类比 GET),提示词是「用户主动触发的命名消息模板」(类比保存的查询)。我们会先讲资源与资源模板(URI 带参数)的注册与读取机制,再用「为什么不直接用工具」这个追问讲透它的设计动机;然后展开提示词——它的参数只能是扁平字符串列表,返回的是消息而非数据;最后介绍补全(Completions),这一让资源模板与提示词参数获得自动建议的能力。读完本章,你将能精准地区分三类原语的边界,各得其所地使用它们。

学习目标

阅读完本章,你应当能够:

1. 区分具体资源(@mcp.resource("config://app"))与资源模板(@mcp.resource("greeting://{name}"))在注册、列举、读取上的差异。
2. 解释资源为什么是应用控制的——由宿主决定何时加载进上下文,而非模型决定调用,并用一个适用场景说明。
3. 构造一个提示词(@mcp.prompt()),理解它的参数为何只能是扁平字符串列表,以及返回的消息如何被宿主当作用户消息注入。
4. 实现一个补全(Completions) 处理器,为资源模板或提示词的参数提供自动建议,并理解它为何需要单独的能力声明。
5. 在「该用工具、资源还是提示词」这一常见纠结中,基于控制权归属做出正确取舍。

核心概念速览

整章逻辑可浓缩为一句话:资源与提示词的存在,让 MCP 能表达「不只是模型主动干活」的交互——资源让宿主按需喂数据,提示词让用户一键注入预设指令,三者合起来覆盖了 LLM 应用的三类控制权归属。

子章节导航

01 资源与资源模板:URI 即接口

讲清资源的注册(@mcp.resource(uri))与两种形态:具体资源(URI 无参数,可直接列举)与资源模板(URI 带 {param},需提供参数实例化)。用一个「读配置」「读用户资料」的例子说明它如何像 GET 一样提供只读数据。

02 为什么不直接用工具:资源的设计动机

一个关键追问。工具也能返回数据,为什么要单独造资源?答案在控制权——资源由应用决定加载(可在模型发言前预载),工具由模型决定调用(每次都消耗一轮)。这一节用「文件树展示」「上下文预载」等场景讲透分工。

03 提示词:用户控制的消息模板

提示词是「用户主动触发的命名调用」。讲清它的注册(@mcp.prompt())、参数模型(只能是扁平字符串列表,无 JSON Schema)、返回值(字符串变成一条用户消息)。用「代码评审」「生成提交信息」等场景说明它为何是「保存的查询」的最佳类比。

04 补全:为参数提供自动建议

资源模板与提示词的参数经常有固定候选值(如「项目名」「语言」)。补全(Completions)让宿主在用户输入时获得自动建议。讲清它的注册(需单独处理器)、能力声明(注册才声明 completions 能力)、与资源/提示词的协作。

子章节之间的逻辑关系

本章遵循「认识资源 → 追问动机 → 转向提示词 → 补全收尾」的认知路径,用「为什么」串联每一节:

资源与模板 (01) ── 应用控制的只读数据,URI 即接口
   │
   ▼
设计动机 (02)  ── 为什么不直接用工具?控制权与成本
   │
   ▼
提示词 (03)    ── 用户控制的命名消息模板
   │
   ▼
补全 (04)      ── 为模板/提示词参数提供自动建议
   │
   ▼
第 6 章:深入「一次请求的内部」——上下文、依赖与生命周期
​

认识资源是前提,追问动机让你理解协议设计的深度(避免把所有交互都塞进工具),提示词补上「用户控制」的最后一类,补全则是资源与提示词的体验增强。理解了这四节,你就能在「该用哪个原语」的纠结里基于控制权归属果断取舍。

前置知识与后续延伸

前置知识:

• 第 2 章的「谁决定调用」原语划分(控制权归属是本章的总纲)
• 第 3 章的 @mcp.resource / @mcp.prompt 装饰器基本用法
• 第 4 章的「类型即契约」思想(资源模板参数同样适用)

本章为后续章节奠定的基础:

• 资源概念是第 6 章(上下文 read_resource)的直接操作对象
• 提示词返回消息的机制是第 7 章(交互式能力中消息构造)的铺垫
• 补全的能力声明机制是第 9 章(客户端如何询问补全)的前置
• 「为什么不直接用工具」的取舍思维会在第 12 章(扩展设计)再次出现