摘要MCP Prompts原语提供标准化提示词模板支持参数化注入和组合调用。本文详解提示定义、消息构建、客户端调用流程和提示与工具的联动设计。Prompts原语标准化提示词模板前阵子我给团队维护一坨提示词散落在十几个Python文件里每人写法都不一样有人把system prompt硬编码有人用f-string拼改一个变量得全局搜一遍。后来我把这些提示词迁移到MCP的Prompts原语里统一用参数化模板管理客户端能自动发现并填参数团队再也没为谁的提示词版本对吵过架。这篇我把Prompts原语的设计理念和用法讲透。Prompts原语的设计理念MCP规范里Prompts原语让Server定义可复用的提示词模板和工作流客户端能直接展示给用户和模型。它的核心定位是user-controlled由用户主动选择使用这点和Resources一样和Tools的model-controlled不同。Prompts的设计目标是标准化和共享。你在Server端定义好模板参数化加描述任何MCP客户端连上来都能发现这些模板用户像选斜杠命令一样选用填几个参数就能生成一段完整的对话消息。团队共享提示词这件事从复制粘贴代码变成了连同一个Server。一个Prompt的定义包含这些字段。name是唯一标识description是人可读的描述arguments是可选的参数列表每个参数有name、description和required。客户端拿这些信息自动生成输入表单。参数化提示模板参数化是Prompts最实用的特性。你定义一个函数参数就是模板变量客户端调用时传参函数返回组装好的消息。下面是规范里analyze-code这个prompt的参数定义。{name:analyze-code,description:Analyze code for potential improvements,arguments:[{name:language,description:Programming language,required:true}]}用FastMCP定义参数化prompt非常直观函数参数就是模板参数有默认值的算可选没默认值的算必填。FastMCP还会解析docstring自动提取每个参数的描述省得你手动写。我发现一个隐藏好处参数化模板天然防注入。以前用f-string拼提示词用户输入直接插进去容易被prompt injection。现在参数走JSON Schema校验我在函数里做转义和校验安全性好很多。多消息组合与嵌入资源Prompts不只能返回单条消息它能返回一整个消息序列模拟一段多轮对话。每条消息有role可以是user或assistant。这让你能预设对话上下文模型接手时已经有了开场白。更强大的能力是嵌入资源。Prompt的消息内容可以是text类型也可以是resource类型直接把一个Resource的内容塞进消息里。这样你能把日志文件、代码文件和提问组合在一起模型一次拿到完整上下文。我做过一个debug-error的prompt模板第一条user消息放错误描述第二条assistant消息预设回应我来帮你分析第三条user消息嵌入日志资源。模型接手时对话已经有了结构分析质量明显比单条消息高。完整代码下面是完整的Prompts示例包含单消息模板、多消息组合和嵌入资源的模板。客户端测试脚本调用这些prompt。server.py# server.py MCP Prompts原语完整示例# 运行方式 python server.py# 依赖安装 pip install fastmcpfromfastmcpimportFastMCP,Contextfromfastmcp.promptsimportMessage# 创建服务器实例mcpFastMCP(namePromptTemplatesServer)# ---------- 简单的单消息prompt ----------mcp.promptdefcode_review(code:str,language:strpython)-str:生成代码审查请求的提示词. Args: code: 要审查的代码片段. language: 代码的编程语言, 默认python. # 拼装提示词, 参数已经被FastMCP校验过return(f请审查以下{language}代码, 重点关注潜在bug、f性能问题和可读性.\n\nf\n{code}\n)# ---------- 多消息组合prompt ----------mcp.promptdefdebug_workflow(error:str)-list[Message]:生成调试工作流的多轮对话. Args: error: 遇到的错误描述. # 返回多条消息, 模拟一段预设的对话开场return[# 第一条, 用户描述问题Message(f我遇到了这个错误, 请帮我分析{error}),# 第二条, assistant预设回应, 引导用户继续Message(好的, 我来帮你分析这个错误. 请问你之前尝试过什么方法?,roleassistant),]# ---------- 带上下文的prompt, 读取资源嵌入 ----------mcp.promptasyncdefanalyze_with_context(question:str,file_path:str,ctx:Context,)-list[Message]:结合文件内容生成分析请求. Args: question: 要分析的问题. file_path: 要参考的文件路径. # 通过Context读取服务器上的资源, 获取文件内容# 这里复用上一篇Resources里的思路, 直接read_resourcecontentsawaitctx.read_resource(ffile:///{file_path})file_contentcontents[0].contentifcontentselse文件为空# 组合问题和文件内容, 让模型同时看到两者return[Message(f请基于以下文件内容回答我的问题.\n\n问题{question}),Message(f以下是文件{file_path}的内容\n\n{file_content}),]# ---------- 返回PromptResult, 带元数据 ----------mcp.promptdefsummarize_text(text:str)-str:生成文本摘要请求. Args: text: 需要摘要的长文本. returnf请用三句话总结以下内容的核心要点.\n\n{text}if__name____main__:mcp.run()client_test.py# client_test.py Prompts客户端测试# 运行方式 python client_test.pyimportasynciofromfastmcpimportClientasyncdefmain():asyncwithClient(server.py)asclient:# 第一步, 列出所有可用prompt, 相当于发prompts/listpromptsawaitclient.list_prompts()print( 可用Prompt列表 )forpinprompts:print(f 名称{p.name})print(f 描述{p.description})print()# 第二步, 调用单消息prompt, 相当于发prompts/getprint( 调用 code_review )resultawaitclient.get_prompt(code_review,{code:def add(a, b): return a b,language:python},)# result.messages 是返回的消息列表formsginresult.messages:print(f 角色{msg.role})print(f 内容{msg.content.text})print()# 第三步, 调用多消息promptprint( 调用 debug_workflow )resultawaitclient.get_prompt(debug_workflow,{error:TypeError unsupported operand type(s) for int and str},)formsginresult.messages:print(f 角色{msg.role})print(f 内容{msg.content.text})print()# 第四步, 调用摘要promptprint( 调用 summarize_text )resultawaitclient.get_prompt(summarize_text,{text:MCP是一个开放协议, 让大模型连接外部工具和数据源. 它定义了统一的通信标准.},)formsginresult.messages:print(f 角色{msg.role})print(f 内容{msg.content.text})if__name____main__:asyncio.run(main())效果验证装好fastmcp后跑client_test.py输出大致如下。 可用Prompt列表 名称 code_review 描述 生成代码审查请求的提示词. 名称 debug_workflow 描述 生成调试工作流的多轮对话. 名称 analyze_with_context 描述 结合文件内容生成分析请求. 名称 summarize_text 描述 生成文本摘要请求. 调用 code_review 角色 user 内容 请审查以下python代码, 重点关注潜在bug、性能问题和可读性.def add(a, b): return a b 调用 debug_workflow 角色 user 内容 我遇到了这个错误, 请帮我分析 TypeError unsupported operand type(s)... 角色 assistant 内容 好的, 我来帮你分析这个错误. 请问你之前尝试过什么方法?客户端list到四个prompt再分别get调用拿到组装好的消息序列。在真实MCP客户端里这些prompt会变成斜杠命令或快捷操作用户点一下填参数就能用。与普通Prompt工程的区别很多人觉得Prompts原语就是换了个地方写提示词其实区别挺大。我做了个对比。维度MCP Prompts普通Prompt工程存储位置集中在Server端管理散落在代码或配置文件发现方式客户端自动prompts/list发现手动维护文档或代码参数化协议级参数校验和描述自己写f-string或模板引擎共享范围任何MCP客户端连上就能用绑定特定应用代码多消息原生支持多轮对话序列手动拼接消息数组嵌入资源直接把Resource嵌入消息自己读文件再拼字符串最实际的区别在团队协作。普通Prompt工程里提示词改了得改代码、发版本、通知所有人。用Prompts原语提示词在Server端维护改了客户端自动发现新版本零成本同步。我团队之前有个code-review的提示词三个人各自维护了一份参数名都不一样。迁到Prompts原语后统一成一个code_review模板参数叫code和language所有人用的都是同一份再也没出过版本不一致的问题。常见问题与避坑坑1必填参数没传导致get失败。Prompt的required参数客户端必须传漏传一个prompts/get直接报错。FastMCP里没默认值的参数就是必填的定义模板时想清楚哪些参数真的必填能给默认值的就给。坑2多消息prompt的role用错。Message默认role是user预设assistant回应时忘了传role“assistant”模型把预设回应也当成用户输入对话逻辑就乱了。多消息场景每条消息都要确认role对不对。坑3嵌入资源时URI写错读不到内容。Prompt里嵌入resource消息时URI要和Resources里定义的一致。我之前模板里写了file:///notes.txt但实际资源URI是file:///{path}模板read的时候传错了路径拿空内容。嵌入资源前先确认URI能read成功。坑4提示词里直接拼接用户输入被注入。参数化模板降低了风险但如果直接把用户输入拼进提示词文本还是有prompt injection的风险。对用户输入做长度限制和必要的转义特别是code这种可能包含特殊内容的参数。坑5docstring格式不规范导致描述丢失。FastMCP靠解析docstring提取参数描述格式不对就提取不到。用Google或NumPy风格的docstringArgs段落写清楚每个参数FastMCP会自动填充到协议的argument description里。小结Prompts原语把提示词模板标准化了。核心要点有三个参数化模板让提示词可复用可校验多消息组合支持预设对话上下文嵌入资源让模型一次拿到完整背景。和普通Prompt工程相比Prompts原语的优势在集中管理、自动发现和团队共享。下一篇我们进入一个相对反直觉的原语Sampling它让Server反过来请求Client的LLM能力。相关推荐MCP三大原语初体验Tools、Resources、Prompts一个都不少提示模板开发参数化提示与组合提示Tools原语深度解析从定义到调用全流程
摘要MCP Prompts原语提供标准化提示词模板支持参数化注入和组合调用。本文详解提示定义、消息构建、客户端调用流程和提示与工具的联动设计。Prompts原语标准化提示词模板前阵子我给团队维护一坨提示词散落在十几个Python文件里每人写法都不一样有人把system prompt硬编码有人用f-string拼改一个变量得全局搜一遍。后来我把这些提示词迁移到MCP的Prompts原语里统一用参数化模板管理客户端能自动发现并填参数团队再也没为谁的提示词版本对吵过架。这篇我把Prompts原语的设计理念和用法讲透。Prompts原语的设计理念MCP规范里Prompts原语让Server定义可复用的提示词模板和工作流客户端能直接展示给用户和模型。它的核心定位是user-controlled由用户主动选择使用这点和Resources一样和Tools的model-controlled不同。Prompts的设计目标是标准化和共享。你在Server端定义好模板参数化加描述任何MCP客户端连上来都能发现这些模板用户像选斜杠命令一样选用填几个参数就能生成一段完整的对话消息。团队共享提示词这件事从复制粘贴代码变成了连同一个Server。一个Prompt的定义包含这些字段。name是唯一标识description是人可读的描述arguments是可选的参数列表每个参数有name、description和required。客户端拿这些信息自动生成输入表单。参数化提示模板参数化是Prompts最实用的特性。你定义一个函数参数就是模板变量客户端调用时传参函数返回组装好的消息。下面是规范里analyze-code这个prompt的参数定义。{name:analyze-code,description:Analyze code for potential improvements,arguments:[{name:language,description:Programming language,required:true}]}用FastMCP定义参数化prompt非常直观函数参数就是模板参数有默认值的算可选没默认值的算必填。FastMCP还会解析docstring自动提取每个参数的描述省得你手动写。我发现一个隐藏好处参数化模板天然防注入。以前用f-string拼提示词用户输入直接插进去容易被prompt injection。现在参数走JSON Schema校验我在函数里做转义和校验安全性好很多。多消息组合与嵌入资源Prompts不只能返回单条消息它能返回一整个消息序列模拟一段多轮对话。每条消息有role可以是user或assistant。这让你能预设对话上下文模型接手时已经有了开场白。更强大的能力是嵌入资源。Prompt的消息内容可以是text类型也可以是resource类型直接把一个Resource的内容塞进消息里。这样你能把日志文件、代码文件和提问组合在一起模型一次拿到完整上下文。我做过一个debug-error的prompt模板第一条user消息放错误描述第二条assistant消息预设回应我来帮你分析第三条user消息嵌入日志资源。模型接手时对话已经有了结构分析质量明显比单条消息高。完整代码下面是完整的Prompts示例包含单消息模板、多消息组合和嵌入资源的模板。客户端测试脚本调用这些prompt。server.py# server.py MCP Prompts原语完整示例# 运行方式 python server.py# 依赖安装 pip install fastmcpfromfastmcpimportFastMCP,Contextfromfastmcp.promptsimportMessage# 创建服务器实例mcpFastMCP(namePromptTemplatesServer)# ---------- 简单的单消息prompt ----------mcp.promptdefcode_review(code:str,language:strpython)-str:生成代码审查请求的提示词. Args: code: 要审查的代码片段. language: 代码的编程语言, 默认python. # 拼装提示词, 参数已经被FastMCP校验过return(f请审查以下{language}代码, 重点关注潜在bug、f性能问题和可读性.\n\nf\n{code}\n)# ---------- 多消息组合prompt ----------mcp.promptdefdebug_workflow(error:str)-list[Message]:生成调试工作流的多轮对话. Args: error: 遇到的错误描述. # 返回多条消息, 模拟一段预设的对话开场return[# 第一条, 用户描述问题Message(f我遇到了这个错误, 请帮我分析{error}),# 第二条, assistant预设回应, 引导用户继续Message(好的, 我来帮你分析这个错误. 请问你之前尝试过什么方法?,roleassistant),]# ---------- 带上下文的prompt, 读取资源嵌入 ----------mcp.promptasyncdefanalyze_with_context(question:str,file_path:str,ctx:Context,)-list[Message]:结合文件内容生成分析请求. Args: question: 要分析的问题. file_path: 要参考的文件路径. # 通过Context读取服务器上的资源, 获取文件内容# 这里复用上一篇Resources里的思路, 直接read_resourcecontentsawaitctx.read_resource(ffile:///{file_path})file_contentcontents[0].contentifcontentselse文件为空# 组合问题和文件内容, 让模型同时看到两者return[Message(f请基于以下文件内容回答我的问题.\n\n问题{question}),Message(f以下是文件{file_path}的内容\n\n{file_content}),]# ---------- 返回PromptResult, 带元数据 ----------mcp.promptdefsummarize_text(text:str)-str:生成文本摘要请求. Args: text: 需要摘要的长文本. returnf请用三句话总结以下内容的核心要点.\n\n{text}if__name____main__:mcp.run()client_test.py# client_test.py Prompts客户端测试# 运行方式 python client_test.pyimportasynciofromfastmcpimportClientasyncdefmain():asyncwithClient(server.py)asclient:# 第一步, 列出所有可用prompt, 相当于发prompts/listpromptsawaitclient.list_prompts()print( 可用Prompt列表 )forpinprompts:print(f 名称{p.name})print(f 描述{p.description})print()# 第二步, 调用单消息prompt, 相当于发prompts/getprint( 调用 code_review )resultawaitclient.get_prompt(code_review,{code:def add(a, b): return a b,language:python},)# result.messages 是返回的消息列表formsginresult.messages:print(f 角色{msg.role})print(f 内容{msg.content.text})print()# 第三步, 调用多消息promptprint( 调用 debug_workflow )resultawaitclient.get_prompt(debug_workflow,{error:TypeError unsupported operand type(s) for int and str},)formsginresult.messages:print(f 角色{msg.role})print(f 内容{msg.content.text})print()# 第四步, 调用摘要promptprint( 调用 summarize_text )resultawaitclient.get_prompt(summarize_text,{text:MCP是一个开放协议, 让大模型连接外部工具和数据源. 它定义了统一的通信标准.},)formsginresult.messages:print(f 角色{msg.role})print(f 内容{msg.content.text})if__name____main__:asyncio.run(main())效果验证装好fastmcp后跑client_test.py输出大致如下。 可用Prompt列表 名称 code_review 描述 生成代码审查请求的提示词. 名称 debug_workflow 描述 生成调试工作流的多轮对话. 名称 analyze_with_context 描述 结合文件内容生成分析请求. 名称 summarize_text 描述 生成文本摘要请求. 调用 code_review 角色 user 内容 请审查以下python代码, 重点关注潜在bug、性能问题和可读性.def add(a, b): return a b 调用 debug_workflow 角色 user 内容 我遇到了这个错误, 请帮我分析 TypeError unsupported operand type(s)... 角色 assistant 内容 好的, 我来帮你分析这个错误. 请问你之前尝试过什么方法?客户端list到四个prompt再分别get调用拿到组装好的消息序列。在真实MCP客户端里这些prompt会变成斜杠命令或快捷操作用户点一下填参数就能用。与普通Prompt工程的区别很多人觉得Prompts原语就是换了个地方写提示词其实区别挺大。我做了个对比。维度MCP Prompts普通Prompt工程存储位置集中在Server端管理散落在代码或配置文件发现方式客户端自动prompts/list发现手动维护文档或代码参数化协议级参数校验和描述自己写f-string或模板引擎共享范围任何MCP客户端连上就能用绑定特定应用代码多消息原生支持多轮对话序列手动拼接消息数组嵌入资源直接把Resource嵌入消息自己读文件再拼字符串最实际的区别在团队协作。普通Prompt工程里提示词改了得改代码、发版本、通知所有人。用Prompts原语提示词在Server端维护改了客户端自动发现新版本零成本同步。我团队之前有个code-review的提示词三个人各自维护了一份参数名都不一样。迁到Prompts原语后统一成一个code_review模板参数叫code和language所有人用的都是同一份再也没出过版本不一致的问题。常见问题与避坑坑1必填参数没传导致get失败。Prompt的required参数客户端必须传漏传一个prompts/get直接报错。FastMCP里没默认值的参数就是必填的定义模板时想清楚哪些参数真的必填能给默认值的就给。坑2多消息prompt的role用错。Message默认role是user预设assistant回应时忘了传role“assistant”模型把预设回应也当成用户输入对话逻辑就乱了。多消息场景每条消息都要确认role对不对。坑3嵌入资源时URI写错读不到内容。Prompt里嵌入resource消息时URI要和Resources里定义的一致。我之前模板里写了file:///notes.txt但实际资源URI是file:///{path}模板read的时候传错了路径拿空内容。嵌入资源前先确认URI能read成功。坑4提示词里直接拼接用户输入被注入。参数化模板降低了风险但如果直接把用户输入拼进提示词文本还是有prompt injection的风险。对用户输入做长度限制和必要的转义特别是code这种可能包含特殊内容的参数。坑5docstring格式不规范导致描述丢失。FastMCP靠解析docstring提取参数描述格式不对就提取不到。用Google或NumPy风格的docstringArgs段落写清楚每个参数FastMCP会自动填充到协议的argument description里。小结Prompts原语把提示词模板标准化了。核心要点有三个参数化模板让提示词可复用可校验多消息组合支持预设对话上下文嵌入资源让模型一次拿到完整背景。和普通Prompt工程相比Prompts原语的优势在集中管理、自动发现和团队共享。下一篇我们进入一个相对反直觉的原语Sampling它让Server反过来请求Client的LLM能力。相关推荐MCP三大原语初体验Tools、Resources、Prompts一个都不少提示模板开发参数化提示与组合提示Tools原语深度解析从定义到调用全流程
