Skip to main content
Prompts 允许 servers 定义可复用的提示模板和工作流，clients 可以轻松地将它们呈现给用户和 LLMs。它们提供了一种强大的方式来标准化和共享常见的 LLM 交互。
Prompts 的设计是用户控制的，这意味着它们从 servers 暴露给 clients，目的是让用户能够明确地选择使用它们。

​
概述

MCP 中的 Prompts 是预定义的模板，可以：
  • 接受动态参数
  • 包含来自 resources 的上下文
  • 链接多个交互
  • 引导特定的工作流程
  • 呈现为 UI 元素（如斜杠命令）

​
Prompt 结构

每个 prompt 都定义如下： 
{
  name: string;              // Prompt 的唯一标识符
  description?: string;      // 易于理解的描述
  arguments?: [              // 可选的参数列表
    {
      name: string;          // 参数标识符
      description?: string;  // 参数描述
      required?: boolean;    // 参数是否必需
    }
  ]
}

​
发现 prompts

Clients 可以通过 prompts/list 端点发现可用的 prompts： 
// 请求
{
  method: "prompts/list"
}

// 响应
{
  prompts: [
    {
      name: "analyze-code",
      description: "分析代码以获得潜在改进",
      arguments: [
        {
          name: "language",
          description: "编程语言",
          required: true
        }
      ]
    }
  ]
}

​
使用 prompts

要使用 prompt，clients 发出 prompts/get 请求： 
// 请求
{
  method: "prompts/get",
  params: {
    name: "analyze-code",
    arguments: {
      language: "python"
    }
  }
}

// 响应
{
  description: "分析 Python 代码以获得潜在改进",
  messages: [
    {
      role: "user",
      content: {
        type: "text",
        text: "请分析以下 Python 代码以获得潜在改进:\n\n```python\ndef calculate_sum(numbers):\n    total = 0\n    for num in numbers:\n        total = total + num\n    return total\n\nresult = calculate_sum([1, 2, 3, 4, 5])\nprint(result)\n```"
      }
    }
  ]
}

​
动态 prompts

Prompts 可以是动态的，并且包括：

​
嵌入的 resource 上下文

{
  "name": "analyze-project",
  "description": "分析项目日志和代码",
  "arguments": [
    {
      "name": "timeframe",
      "description": "分析日志的时间段",
      "required": true
    },
    {
      "name": "fileUri",
      "description": "要审查的代码文件的 URI",
      "required": true
    }
  ]
}
当处理 prompts/get 请求时： 
{
  "messages": [
    {
      "role": "user",
      "content": {
        "type": "text",
        "text": "分析这些系统日志和代码文件以查找任何问题:"
      }
    },
    {
      "role": "user",
      "content": {
        "type": "resource",
        "resource": {
          "uri": "logs://recent?timeframe=1h",
          "text": "[2024-03-14 15:32:11] ERROR: Connection timeout in network.py:127\n[2024-03-14 15:32:15] WARN: Retrying connection (attempt 2/3)\n[2024-03-14 15:32:20] ERROR: Max retries exceeded",
          "mimeType": "text/plain"
        }
      }
    },
    {
      "role": "user",
      "content": {
        "type": "resource",
        "resource": {
          "uri": "file:///path/to/code.py",
          "text": "def connect_to_service(timeout=30):\n    retries = 3\n    for attempt in range(retries):\n        try:\n            return establish_connection(timeout)\n        except TimeoutError:\n            if attempt == retries - 1:\n                raise\n            time.sleep(5)\n\ndef establish_connection(timeout):\n    # Connection implementation\n    pass",
          "mimeType": "text/x-python"
        }
      }
    }
  ]
}

​
多步骤工作流程

const debugWorkflow = {
  name: "debug-error",
  async getMessages(error: string) {
    return [
      {
        role: "user",
        content: {
          type: "text",
          text: `我看到的错误是: ${error}`
        }
      },
      {
        role: "assistant",
        content: {
          type: "text",
          text: "我将帮助分析这个错误。你到目前为止尝试了什么？"
        }
      },
      {
        role: "user",
        content: {
          type: "text",
          text: "我已经尝试重新启动服务，但错误仍然存在。"
        }
      }
    ];
  }
};

​
实现示例

以下是在 MCP server 中实现 prompts 的完整示例：
  • TypeScript
  • Python
import { Server } from "@modelcontextprotocol/sdk/server";
import {
  ListPromptsRequestSchema,
  GetPromptRequestSchema
} from "@modelcontextprotocol/sdk/types";

const PROMPTS = {
  "git-commit": {
    name: "git-commit",
    description: "生成 Git commit 消息",
    arguments: [
      {
        name: "changes",
        description: "Git diff 或更改描述",
        required: true
      }
    ]
  },
  "explain-code": {
    name: "explain-code",
    description: "解释代码的工作原理",
    arguments: [
      {
        name: "code",
        description: "要解释的代码",
        required: true
      },
      {
        name: "language",
        description: "编程语言",
        required: false
      }
    ]
  }
};

const server = new Server({
  name: "example-prompts-server",
  version: "1.0.0"
}, {
  capabilities: {
    prompts: {}
  }
});

// 列出可用的 prompts
server.setRequestHandler(ListPromptsRequestSchema, async () => {
  return {
    prompts: Object.values(PROMPTS)
  };
});

// 获取特定的 prompt
server.setRequestHandler(GetPromptRequestSchema, async (request) => {
  const prompt = PROMPTS[request.params.name];
  if (!prompt) {
    throw new Error(`未找到 prompt: ${request.params.name}`);
  }

  if (request.params.name === "git-commit") {
    return {
      messages: [
        {
          role: "user",
          content: {
            type: "text",
            text: `为这些更改生成简洁但描述性的 commit 消息:\n\n${request.params.arguments?.changes}`
          }
        }
      ]
    };
  }

  if (request.params.name === "explain-code") {
    const language = request.params.arguments?.language || "未知";
    return {
      messages: [
        {
          role: "user",
          content: {
            type: "text",
            text: `解释这段 ${language} 代码的工作原理:\n\n${request.params.arguments?.code}`
          }
        }
      ]
    };
  }

  throw new Error("未找到 prompt 实现");
});

​
最佳实践

在实现 prompts 时：
  1. 使用清晰、描述性的 prompt 名称
  2. 为 prompts 和参数提供详细的描述
  3. 验证所有必需的参数
  4. 优雅地处理缺失的参数
  5. 考虑 prompt 模板的版本控制
  6. 在适当的时候缓存动态内容
  7. 实现错误处理
  8. 记录预期的参数格式
  9. 考虑 prompt 的可组合性
  10. 使用各种输入测试 prompts

​
UI 集成

Prompts 可以在 client UI 中呈现为：
  • 斜杠命令
  • 快速操作
  • 上下文菜单项
  • 命令面板条目
  • 引导式工作流程
  • 交互式表单

​
更新和更改

Servers 可以通知 clients 关于 prompt 的更改：
  1. Server 功能：prompts.listChanged
  2. 通知：notifications/prompts/list_changed
  3. Client 重新获取 prompt 列表

​
安全考虑

在实现 prompts 时：
  • 验证所有参数
  • 清理用户输入
  • 考虑速率限制
  • 实现访问控制
  • 审计 prompt 使用情况
  • 适当地处理敏感数据
  • 验证生成的内容
  • 实现超时
  • 考虑 prompt 注入风险
  • 记录安全要求