MCP Server Prompt 完整深度详解
一、核心定义与定位
1. 什么是 MCP Prompt
Prompt 是 MCP 三大核心原语（Tool/Resource/Prompt）之一，是服务端预定义、带动态参数、结构化的 LLM 交互模板Model Cont...。
- Tool：AI 自动调用，执行增删改操作（模型驱动）
- Resource：只读数据源，给 AI 注入上下文（数据载体）
- Prompt：用户主动手动触发（客户端斜杠命令 / 菜单），封装成熟提示词、角色设定、标准化工作流，统一复用交互逻辑
2. 核心价值
- 统一提示词标准：服务端开发者封装领域最优 Prompt，用户无需手写复杂指令；
- 动态参数注入：支持自定义入参，一套模板适配不同场景；
- 自动关联资源 / 工具：模板内可嵌入服务端 Resource 数据，开箱即用；
- 跨客户端通用：Claude Desktop / VSCode Copilot / Cursor 均可读取并调用；
- 标准化消息结构：严格区分
user/assistant多轮对话，支持文本、图片、音频多模态内容。
3. 关键特性：用户受控（User-Controlled）
Prompt不会被 AI 自动调用，必须由用户在客户端手动选择触发（如输入/code-review斜杠指令），区别于 Tool 由模型自主判断调用Model Cont...。
二、协议底层工作流程（完整报文链路）
阶段 1：服务端初始化声明能力
MCP 服务启动握手时，必须在capabilities声明支持 Prompt，否则客户端不会拉取模板列表：
json
{ "capabilities": { "prompts": { "listChanged": true } } }listChanged: true：当服务端新增 / 修改 Prompt 时，主动推送通知客户端刷新列表。
阶段 2：客户端拉取全部 Prompt 列表
客户端发送prompts/list请求，服务端返回所有模板元信息（不含完整消息内容，仅基础描述与参数）：
json
// 客户端请求 {"jsonrpc":"2.0","id":1,"method":"prompts/list"} // 服务端返回元数据 { "prompts": [ { "name": "code-review", "title": "代码审查", "description": "读取users资源，完整审查TS代码规范、漏洞、性能", "arguments": [ { "name": "filePath", "description": "待审查文件路径", "required": true } ] } ] }阶段 3：用户选择模板，传入参数，客户端拉取完整 Prompt
客户端调用prompts/get，携带模板名与用户填写参数，服务端动态渲染完整结构化消息数组返回：
json
// 客户端请求 { "jsonrpc":"2.0","id":2,"method":"prompts/get", "params": { "name": "code-review", "arguments": { "filePath": "./src/server.ts" } } } // 服务端渲染后返回完整对话消息 { "description": "TS代码审查模板", "messages": [ { "role": "user", "content": { "type": "text", "text": "你是资深TS后端工程师，读取资源users://all用户数据，审查文件./src/server.ts，输出漏洞、性能、规范问题，逐条给出修复代码" } } ] }阶段 4：客户端将 messages 直接注入 LLM 对话上下文
拿到消息数组后，客户端把完整 Prompt 追加到当前对话，直接发给大模型执行。
三、Prompt 完整数据结构（两层：元描述 + 消息体）
1. 外层元描述（prompts/list 返回）
表格
| 字段 | 类型 | 说明 |
|---|---|---|
name | string | 唯一标识，调用时必填（斜杠命令名称，如code-review） |
title | string (可选) | 客户端 UI 展示友好名称，中文如「用户数据分析」 |
description | string (可选) | 模板用途说明，给用户看的简介 |
arguments | Array (可选) | 动态参数列表，支持必填 / 选填 |
| arguments[].name | string | 参数键名，渲染模板时插值使用 |
| arguments[].description | string | 参数说明，客户端输入框提示 |
| arguments[].required | boolean | 是否必填，true 时客户端强制用户填写 |
2. 内层消息体（prompts/get 返回核心）
messages[]是 Prompt 真正内容，支持多轮对话、多模态：
typescript
运行
type PromptMessage = { role: "user" | "assistant"; // 对话角色，不支持system（系统提示由客户端宿主注入） content: TextContent | ImageContent | AudioContent | EmbeddedResource; }四种内容类型
- TextContent（最常用）
json
{"type":"text","text":"模板文本，支持{参数名}插值"}- EmbeddedResource（内置资源，MCP 特色）直接在 Prompt 内嵌入服务端 Resource（如你之前的
users://all），自动拉取数据注入上下文，无需用户手动引用：
json
{ "type": "resource", "resource": { "uri": "users://all" } }- ImageContent / AudioContent：图片、音频多模态输入，仅支持 Claude 等多模态客户端。
四、TS MCP 完整代码实战（适配你的项目）
示例 1：基础带参数 Prompt（用户数据分析模板）
typescript
运行
import { Server } from "@modelcontextprotocol/sdk/server/index.js"; import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js"; const server = new Server( { name: "user-mcp-server", version: "1.0.0" }, { capabilities: { prompts: { listChanged: true } } } ); // 注册Prompt模板 server.prompt( { name: "user-data-analysis", title: "用户数据分析报告", description: "读取users.json全部用户，按指定维度生成分析报表", arguments: [ { name: "dimension", description: "分析维度：age/email-distribution/address", required: true } ] }, // 动态渲染回调，接收用户传入参数，返回完整messages数组 async (args) => { const { dimension } = args; return { description: "用户数据自动化分析模板", messages: [ { role: "user", content: { type: "text", text: ` 你是数据分析师，自动读取服务内置资源 users://all 的全部用户JSON数据， 按照【${dimension}】维度做完整统计分析，输出结构化Markdown报表，包含： 1. 数据总量统计 2. 分布占比图表文字描述 3. 业务优化建议 ` } }, // 内置嵌入资源，自动拉取users://all数据注入上下文 { role: "user", content: { type: "resource", resource: { uri: "users://all" } } } ] }; } ); // 启动服务 const transport = new StdioServerTransport(); await server.connect(transport);示例 2：多轮对话 Prompt（代码审查多轮引导）
支持多轮assistant预置回复，形成完整工作流：
typescript
运行
server.prompt( { name: "code-review-workflow", title: "完整代码审查工作流", arguments: [{ name: "codePath", required: true, description: "待审查文件路径" }] }, async ({ codePath }) => ({ messages: [ { role: "user", content: { type: "text", text: `审查文件 ${codePath}，先列出全部风险点` } }, { role: "assistant", content: { type: "text", text: "我会先梳理文件结构，分安全、性能、TS规范三类输出问题清单" } }, { role: "user", content: { type: "text", text: "针对每个风险给出可直接复制的修复代码" } } ] }) );五、Prompt / Tool / Resource 三者核心区分（避坑）
表格
| 维度 | Prompt | Tool | Resource |
|---|---|---|---|
| 控制权 | 用户手动触发（斜杠命令） | AI 模型自动判断调用 | 客户端 / AI 按需读取 |
| 核心用途 | 封装提示词、角色、标准化工作流 | 执行增删改查、外部操作（有副作用） | 只读静态 / 动态数据源（无副作用） |
| 输入 | 自定义文本参数 | 结构化 JSON 参数（Zod 校验） | URI 定位，无入参 |
| 返回内容 | 多轮对话消息模板（文本 / 资源 / 图片） | 执行结果文本 / JSON | 标准化 contents 数组 |
| 客户端触发 | /模板名手动选择 | AI 自主调用，用户无感 | AI 自动读取或用户手动预览 |
| 典型场景 | 代码审查模板、数据分析角色、论文写作框架 | 创建用户 createUser、数据库查询、文件写入 | users://all 用户列表、配置 JSON、文档 |
关键边界区分
- 想让 AI修改数据、执行操作→ 写 Tool（如你的
createUser） - 想给 AI只读参考数据→ 写 Resource（你的
users://all） - 想封装一套固定提问话术、工作流程，用户一键启用 → 写 Prompt
六、客户端使用示例（VSCode Copilot / Claude Desktop）
1. VSCode Copilot Agent
- 打开 Copilot Chat → Agent 模式
- MCP 面板加载你的服务，
Browse Prompts查看全部模板 - 点击模板，填入必填参数，一键插入对话上下文
2. Claude Desktop
- 聊天框输入斜杠
/user-data-analysis - 弹窗提示输入参数
dimension，填写后自动加载完整 Prompt + 内置 users 资源 - Claude 直接读取嵌入的
users://all数据，按模板要求生成报告
七、高级特性与最佳实践
1. 动态依赖 Resource（EmbeddedResource）
Prompt 内直接嵌入服务端 Resource，无需用户手动粘贴 URI，服务端自动读取并注入上下文，解决你之前手动复制users://all的繁琐操作。
2. listChanged 动态更新模板
服务端新增 / 修改 Prompt 时，主动推送通知，客户端自动刷新列表，无需重启 MCP 服务。
3. 参数校验规范
arguments.required强制标记必填项，客户端会拦截空参数提交，避免模板渲染报错。
4. 最佳实践
- 领域专属角色封装：把后端、数据、代码审查角色全部封装为 Prompt，统一输出格式；
- 复用 Resource：所有依赖本地 JSON / 数据库数据的 Prompt，使用
EmbeddedResource自动注入； - 多轮对话拆分：复杂工作流拆分为多轮
user/assistant消息，引导 AI 分步执行； - 不要混用 Tool 逻辑：Prompt 只负责提示词，数据修改操作仍交给 Tool；
- 兼容多客户端：主流 Claude、Cursor、VS Copilot 均完整支持 Prompt，ChatGPT 桌面端暂不支持。
5. 常见踩坑
- 初始化
capabilities忘记声明prompts，客户端看不到任何模板； - 模板回调未返回标准
{description, messages}结构，MCP 抛出-32603内部错误； - 混淆控制权：试图让 AI 自动调用 Prompt，规范要求必须用户手动触发；
- 大量复杂逻辑写在 Prompt 文本内，应拆分给 Tool 执行操作、Resource 提供数据。
八、和普通 System Prompt 的本质区别
- 普通 System Prompt：客户端全局固定，所有对话统一生效，无法分场景切换；
- MCP Prompt：服务端托管、按场景拆分、带动态参数、一键切换、内置业务资源，仅用户手动启用，不污染全局对话设定。