MCP Server Prompt 完整深度详解

一、核心定义与定位

1. 什么是 MCP Prompt

Prompt 是 MCP 三大核心原语（Tool/Resource/Prompt）之一，是服务端预定义、带动态参数、结构化的 LLM 交互模板Model Cont...。

• Tool：AI 自动调用，执行增删改操作（模型驱动）
• Resource：只读数据源，给 AI 注入上下文（数据载体）
• Prompt：用户主动手动触发（客户端斜杠命令 / 菜单），封装成熟提示词、角色设定、标准化工作流，统一复用交互逻辑

2. 核心价值

1. 统一提示词标准：服务端开发者封装领域最优 Prompt，用户无需手写复杂指令；
2. 动态参数注入：支持自定义入参，一套模板适配不同场景；
3. 自动关联资源 / 工具：模板内可嵌入服务端 Resource 数据，开箱即用；
4. 跨客户端通用：Claude Desktop / VSCode Copilot / Cursor 均可读取并调用；
5. 标准化消息结构：严格区分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 返回）

表格

2. 内层消息体（prompts/get 返回核心）

messages[]是 Prompt 真正内容，支持多轮对话、多模态：

typescript

运行

type PromptMessage = { role: "user" | "assistant"; // 对话角色，不支持system（系统提示由客户端宿主注入） content: TextContent | ImageContent | AudioContent | EmbeddedResource; }

四种内容类型

1. TextContent（最常用）

json

{"type":"text","text":"模板文本，支持{参数名}插值"}

1. EmbeddedResource（内置资源，MCP 特色）直接在 Prompt 内嵌入服务端 Resource（如你之前的users://all），自动拉取数据注入上下文，无需用户手动引用：

json

{ "type": "resource", "resource": { "uri": "users://all" } }

1. 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 三者核心区分（避坑）

表格

关键边界区分

1. 想让 AI修改数据、执行操作→ 写 Tool（如你的createUser）
2. 想给 AI只读参考数据→ 写 Resource（你的users://all）
3. 想封装一套固定提问话术、工作流程，用户一键启用 → 写 Prompt

六、客户端使用示例（VSCode Copilot / Claude Desktop）

1. VSCode Copilot Agent

1. 打开 Copilot Chat → Agent 模式
2. MCP 面板加载你的服务，Browse Prompts查看全部模板
3. 点击模板，填入必填参数，一键插入对话上下文

2. Claude Desktop

1. 聊天框输入斜杠/user-data-analysis
2. 弹窗提示输入参数dimension，填写后自动加载完整 Prompt + 内置 users 资源
3. Claude 直接读取嵌入的users://all数据，按模板要求生成报告

七、高级特性与最佳实践

1. 动态依赖 Resource（EmbeddedResource）

Prompt 内直接嵌入服务端 Resource，无需用户手动粘贴 URI，服务端自动读取并注入上下文，解决你之前手动复制users://all的繁琐操作。

2. listChanged 动态更新模板

服务端新增 / 修改 Prompt 时，主动推送通知，客户端自动刷新列表，无需重启 MCP 服务。

3. 参数校验规范

arguments.required强制标记必填项，客户端会拦截空参数提交，避免模板渲染报错。

4. 最佳实践

1. 领域专属角色封装：把后端、数据、代码审查角色全部封装为 Prompt，统一输出格式；
2. 复用 Resource：所有依赖本地 JSON / 数据库数据的 Prompt，使用EmbeddedResource自动注入；
3. 多轮对话拆分：复杂工作流拆分为多轮user/assistant消息，引导 AI 分步执行；
4. 不要混用 Tool 逻辑：Prompt 只负责提示词，数据修改操作仍交给 Tool；
5. 兼容多客户端：主流 Claude、Cursor、VS Copilot 均完整支持 Prompt，ChatGPT 桌面端暂不支持。

5. 常见踩坑

1. 初始化capabilities忘记声明prompts，客户端看不到任何模板；
2. 模板回调未返回标准{description, messages}结构，MCP 抛出-32603内部错误；
3. 混淆控制权：试图让 AI 自动调用 Prompt，规范要求必须用户手动触发；
4. 大量复杂逻辑写在 Prompt 文本内，应拆分给 Tool 执行操作、Resource 提供数据。

八、和普通 System Prompt 的本质区别

1. 普通 System Prompt：客户端全局固定，所有对话统一生效，无法分场景切换；
2. MCP Prompt：服务端托管、按场景拆分、带动态参数、一键切换、内置业务资源，仅用户手动启用，不污染全局对话设定。