Prompts：复用提示词模板

Prompt 的本质与适用场景

MCP 中的 Prompt（提示词模板）是预定义的、可参数化的对话启动模板，由用户主动触发。它让复杂的、多步骤的 AI 交互流程标准化，可在团队间共享和复用。

三种能力的控制方对比

Prompt 定义与参数

一个 Prompt 由以下字段构成：

基本 Prompt 注册

import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { z } from "zod";

const server = new McpServer({ name: "prompt-server", version: "1.0.0" });

// ─── 基本代码审查 Prompt ────────────────────────────────────────
server.prompt(
  "code_review",                          // 模板名称
  "对提供的代码进行专业的代码审查",          // 描述
  {
    code: z.string().describe("要审查的代码"),
    language: z.string().optional().describe("编程语言（可选）"),
    focus: z.enum(["bugs", "performance", "security", "all"])
      .default("all")
      .describe("审查重点"),
  },
  ({ code, language, focus }) => {
    const langNote = language ? `（${language}）` : "";
    const focusMap = {
      bugs: "潜在的 Bug 和逻辑错误",
      performance: "性能问题和优化点",
      security: "安全漏洞和风险",
      all: "代码质量、Bug、性能和安全",
    };

    return {
      messages: [
        {
          role: "user",
          content: {
            type: "text",
            text: `请对以下代码${langNote}进行专业的代码审查，重点关注${focusMap[focus]}。

请按以下格式输出：
1. **总体评价**：代码整体质量
2. **发现的问题**：列出所有问题，按严重程度排序
3. **改进建议**：具体的修改方案和示例
4. **优点**：代码中做得好的地方

待审查代码：
\`\`\`
${code}
\`\`\``,
          },
        },
      ],
    };
  }
);

嵌套消息格式

Prompt 返回的是 消息序列（messages array），而不仅仅是一段文字。这使得 Prompt 可以模拟对话历史，创建更复杂的上下文。

// 多轮对话 Prompt：带上下文的技术解释
server.prompt(
  "explain_with_example",
  "通过示例解释技术概念",
  {
    concept: z.string().describe("要解释的技术概念"),
    level: z.enum(["beginner", "intermediate", "expert"])
      .default("intermediate"),
  },
  ({ concept, level }) => {
    const levelDesc = { beginner: "初学者", intermediate: "有一定基础的", expert: "有经验的" };
    return {
      messages: [
        // 第一条：设置 AI 角色
        {
          role: "user",
          content: {
            type: "text",
            text: `你是一位技术导师，擅长用简单清晰的方式解释复杂概念。
请为${levelDesc[level]}开发者解释：${concept}`,
          },
        },
        // 第二条：AI 的确认回应（模拟已有的对话上下文）
        {
          role: "assistant",
          content: {
            type: "text",
            text: `好的，我来为${levelDesc[level]}开发者详细解释 ${concept}。`,
          },
        },
        // 第三条：用户跟进问题
        {
          role: "user",
          content: {
            type: "text",
            text: "请用一个实际的代码示例来说明，并解释每个关键步骤。",
          },
        },
      ],
    };
  }
);

在 Prompt 中嵌入 Resource 内容

Prompt 可以引用 Resource URI，让 Host 自动将资源内容嵌入到消息中：

server.prompt(
  "analyze_file",
  "分析指定文件的内容",
  {
    file_uri: z.string().describe("要分析的文件 URI"),
    task: z.string().describe("分析任务描述"),
  },
  ({ file_uri, task }) => ({
    messages: [
      {
        role: "user",
        content: {
          type: "text",
          text: task,
        },
      },
      {
        role: "user",
        content: {
          // 嵌入资源内容
          type: "resource",
          resource: {
            uri: file_uri,
            mimeType: "text/plain",
            text: "（Host 会自动填充文件内容）",
          },
        },
      },
    ],
  })
);

动态 Prompt 生成

Prompt 处理函数可以包含复杂逻辑，根据参数动态构建不同的提示词：

// 根据项目类型生成不同的文档模板
server.prompt(
  "generate_docs",
  "为函数或模块生成文档注释",
  {
    code: z.string().describe("源代码"),
    style: z.enum(["jsdoc", "tsdoc", "docstring", "rustdoc"])
      .describe("文档风格"),
    include_examples: z.boolean().default(true).describe("是否包含用法示例"),
  },
  ({ code, style, include_examples }) => {
    // 根据不同风格生成不同的指令
    const styleGuides = {
      jsdoc: "使用 JSDoc 格式，包含 @param、@returns、@throws 标签",
      tsdoc: "使用 TSDoc 格式，包含类型信息和 @remarks 标签",
      docstring: "使用 Python docstring 格式（Google 风格）",
      rustdoc: "使用 Rust doc comments（///）格式",
    };

    const exampleInstruction = include_examples
      ? `\n5. **示例用法**：提供 1-2 个实际的调用示例`
      : "";

    return {
      messages: [{
        role: "user",
        content: {
          type: "text",
          text: `为以下代码生成专业的文档注释。
要求：
1. ${styleGuides[style]}
2. **参数说明**：详细描述每个参数的类型、用途和约束
3. **返回值说明**：描述返回值的类型和含义
4. **错误情况**：说明可能抛出的错误${exampleInstruction}

代码：
\`\`\`
${code}
\`\`\``,
        },
      }],
    };
  }
);

Prompt 库设计

随着业务增长，Prompt 数量会越来越多。良好的组织结构可以让 Prompt 库易于维护：

// prompts/index.ts — 统一管理所有 Prompt 定义
interface PromptDefinition {
  name: string;
  description: string;
  category: "code" | "writing" | "analysis" | "debug";
  args: Record<string, z.ZodTypeAny>;
  handler: (args: any) => GetPromptResult;
}

export const PROMPT_LIBRARY: PromptDefinition[] = [
  {
    name: "code_review",
    category: "code",
    description: "代码审查",
    args: { code: z.string(), focus: z.enum(["bugs", "all"]) },
    handler: codeReviewHandler,
  },
  {
    name: "explain_error",
    category: "debug",
    description: "解释错误信息并提供修复方案",
    args: { error: z.string(), context: z.string().optional() },
    handler: explainErrorHandler,
  },
];

// 批量注册所有 Prompt
export function registerAllPrompts(server: McpServer) {
  for (const def of PROMPT_LIBRARY) {
    server.prompt(def.name, def.description, def.args, def.handler);
  }
}