鸭梨公共文档

主题

提示词（Prompts） ​

协议版本：2025-06-18

Model Context Protocol (MCP) 为服务器向客户端公开提示词模板提供了标准化的方式。提示词允许服务器提供结构化的消息和指令，用于与语言模型进行交互。客户端可以发现可用的提示词、检索其内容，并提供参数来自定义它们。

1. 用户交互模型 ​

提示词被设计为用户控制的，这意味着它们从服务器暴露给客户端，目的是让用户能够明确选择它们进行使用。

通常，提示词会通过用户界面中用户发起的命令来触发，这使用户能够自然地发现和调用可用的提示词。

例如，作为斜杠命令：

Example of prompt exposed as slash command

但是，实现者可以自由地通过任何适合其需求的界面模式来公开提示词——协议本身并不强制要求任何特定的用户交互模型。

2. 能力声明 ​

支持提示词的服务器必须在初始化过程中声明 prompts 能力：

json
{
  "capabilities": {
    "prompts": {
      "listChanged": true
    }
  }
}

listChanged 表示服务器是否会在可用提示词列表发生变化时发出通知。

3. 协议消息 ​

3.1 列出提示词 ​

要获取可用的提示词，客户端发送 prompts/list 请求。此操作支持 分页。

请求：

json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "prompts/list",
  "params": {
    "cursor": "optional-cursor-value"
  }
}

响应：

json
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "prompts": [
      {
        "name": "code_review",
        "title": "Request Code Review",
        "description": "Asks the LLM to analyze code quality and suggest improvements",
        "arguments": [
          {
            "name": "code",
            "description": "The code to review",
            "required": true
          }
        ]
      }
    ],
    "nextCursor": "next-page-cursor"
  }
}

3.2 获取提示词 ​

要检索特定的提示词，客户端发送 prompts/get 请求。参数可以通过 补全 API 进行自动补全。

请求：

json
{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "prompts/get",
  "params": {
    "name": "code_review",
    "arguments": {
      "code": "def hello():\n    print('world')"
    }
  }
}

响应：

json
{
  "jsonrpc": "2.0",
  "id": 2,
  "result": {
    "description": "Code review prompt",
    "messages": [
      {
        "role": "user",
        "content": {
          "type": "text",
          "text": "Please review this Python code:\ndef hello():\n    print('world')"
        }
      }
    ]
  }
}

3.3 列表变更通知 ​

当可用提示词列表发生变化时，声明了 listChanged 能力的服务器应该发送通知：

json
{
  "jsonrpc": "2.0",
  "method": "notifications/prompts/list_changed"
}

4. 消息流程 ​

5. 数据类型 ​

5.1 提示词（Prompt） ​

提示词定义包括：

  • name：提示词的唯一标识符
  • title：可选的人类可读的提示词显示名称
  • description：可选的人类可读描述
  • arguments：可选的用于自定义的参数列表

5.2 提示词消息（PromptMessage） ​

提示词中的消息可以包含：

  • role：用于指示说话者的角色，可以是 "user" 或 "assistant"
  • content：以下内容类型之一：

NOTE

提示词消息中的所有内容类型都支持可选的 注解（annotations），用于关于受众、优先级和修改时间的元数据。

文本内容 ​

文本内容表示纯文本消息：

json
{
  "type": "text",
  "text": "The text content of the message"
}

这是用于自然语言交互的最常见内容类型。

图像内容 ​

图像内容允许在消息中包含视觉信息：

json
{
  "type": "image",
  "data": "base64-encoded-image-data",
  "mimeType": "image/png"
}

图像数据必须是 base64 编码的，并包含有效的 MIME 类型。这使得在视觉上下文很重要的情况下进行多模态交互成为可能。

音频内容 ​

音频内容允许在消息中包含音频信息：

json
{
  "type": "audio",
  "data": "base64-encoded-audio-data",
  "mimeType": "audio/wav"
}

音频数据必须是 base64 编码的，并包含有效的 MIME 类型。这使得在音频上下文很重要的情况下进行多模态交互成为可能。

嵌入式资源 ​

嵌入式资源允许在消息中直接引用服务器端资源：

json
{
  "type": "resource",
  "resource": {
    "uri": "resource://example",
    "name": "example",
    "title": "My Example Resource",
    "mimeType": "text/plain",
    "text": "Resource content"
  }
}

资源可以包含文本或二进制（blob）数据，并且必须包括：

  • 有效的资源 URI
  • 适当的 MIME 类型
  • 文本内容或 base64 编码的 blob 数据

嵌入式资源使提示词能够将服务器管理的内容（如文档、代码示例或其他参考资料）无缝地直接集成到对话流程中。

6. 错误处理 ​

服务器应该为常见的失败情况返回标准的 JSON-RPC 错误：

  • 无效的提示词名称：-32602（无效参数）
  • 缺少必需参数：-32602（无效参数）
  • 内部错误：-32603（内部错误）

7. 实现注意事项 ​

  1. 服务器应该在处理之前验证提示词参数
  2. 客户端应该处理大型提示词列表的分页
  3. 双方都应该遵守能力协商

8. 安全性 ​

实现必须仔细验证所有提示词输入和输出，以防止注入攻击或对资源的未授权访问。