提示 - Model Context Protocol 中文文档

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

用户交互模型

提示被设计为用户控制，也就是说，服务器向客户端公开提示，是为了让用户能够明确选择并使用它们。这指的是由谁决定何时使用提示，而不是由谁编写提示内容。提示内容由服务器定义。通常，提示会通过用户界面中由用户发起的命令触发，使用户能够自然地发现并调用可用提示。例如，可以作为斜杠命令：

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

能力

支持提示的服务器 MUST 在其 DiscoverResult 中声明 prompts 能力：

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

listChanged 表示服务器是否会在可用提示列表变化时发出通知。声明 prompts 能力的服务器 MUST 响应 prompts/list 请求，并返回当前对请求客户端可用的一组提示。该集合 MAY 为空，也 MAY 随时间变化（见列表变化通知），但 MUST NOT 因连接不同或连接上其他请求的副作用而变化。该集合 MAY 随请求中提供的授权而变化，例如只返回调用方已授予 scope 允许的提示，因为凭据是逐请求输入，而不是连接状态。

协议消息

列出提示

为了检索可用提示，客户端会发送 prompts/list 请求。此操作支持分页和缓存。 请求：

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

响应：

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "resultType": "complete",
    "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
          }
        ],
        "icons": [
          {
            "src": "https://example.com/review-icon.svg",
            "mimeType": "image/svg+xml",
            "sizes": ["any"]
          }
        ]
      }
    ],
    "nextCursor": "next-page-cursor",
    "ttlMs": 600000,
    "cacheScope": "public"
  }
}

获取提示

为了检索特定提示，客户端会发送 prompts/get 请求。参数可以通过补全 API自动补全。 请求：

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

响应：

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

服务器 MAY 也可以用 InputRequiredResult 响应 prompts/get，表示在解析提示之前需要额外输入。这遵循多轮往返请求机制。重试请求时，客户端会在请求参数中包含 inputResponses，并在服务器提供时包含 requestState。

列表变化通知

当可用提示列表变化时，已声明 listChanged 能力的服务器 SHOULD 向已打开 subscriptions/listen 流且设置了 promptsListChanged: true 的客户端发送通知：

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

消息流

数据类型

Prompt

提示定义包括：

name：提示的唯一标识符
title：用于显示的可选人类可读提示名称。
description：可选的人类可读描述
icons：用于在用户界面中显示的可选图标数组
arguments：用于定制的可选参数列表

PromptMessage

提示中的消息可以包含：

role：“user” 或 “assistant”，用于表示说话者
content：以下内容类型之一：

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

文本内容

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

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

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

图像内容

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

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

图像数据 MUST 经过 base64 编码，并包含有效的 MIME 类型。这使得在视觉上下文很重要的场景中可以进行多模态交互。

音频内容

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

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

音频数据 MUST 经过 base64 编码，并包含有效的 MIME 类型。这使得在音频上下文很重要的场景中可以进行多模态交互。

资源链接

提示消息 MAY 包含指向资源的链接，以便在不直接嵌入资源内容的情况下提供额外上下文或数据。在这种情况下，提示消息会返回一个可由客户端获取的 URI：

{
  "type": "resource_link",
  "uri": "file:///project/src/main.rs",
  "name": "main.rs",
  "description": "Primary application entry point",
  "mimeType": "text/x-rust"
}

资源链接支持与常规资源相同的资源 annotations，以帮助客户端理解如何使用它们。

嵌入式资源

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

{
  "type": "resource",
  "resource": {
    "uri": "resource://example",
    "mimeType": "text/plain",
    "text": "Resource content"
  }
}

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

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

嵌入式资源使提示能够将文档、代码示例或其他参考材料等由服务器管理的内容直接、无缝地纳入对话流程。

错误处理

服务器 SHOULD 针对常见失败情况返回标准 JSON-RPC 错误：

无效提示名称：-32602（Invalid params）
缺少必需参数：-32602（Invalid params）
内部错误：-32603（Internal error）

实现注意事项

服务器 SHOULD 在处理前验证提示参数
客户端 SHOULD 为大型提示列表处理分页
双方 SHOULD 遵守能力协商

安全

实现 MUST 仔细验证所有提示输入和输出，防止注入攻击或未经授权访问资源。

基础协议

客户端能力

服务器能力

提示

用户交互模型

能力

协议消息

列出提示

获取提示

列表变化通知

消息流

数据类型

Prompt

PromptMessage

文本内容

图像内容

音频内容

资源链接

嵌入式资源

错误处理

实现注意事项

安全

​用户交互模型

​能力

​协议消息

​列出提示

​获取提示

​列表变化通知

​消息流

​数据类型

​Prompt

​PromptMessage

​文本内容

​图像内容

​音频内容

​资源链接

​嵌入式资源

​错误处理

​实现注意事项

​安全

用户交互模型

能力

协议消息

列出提示

获取提示

列表变化通知

消息流

数据类型

Prompt

PromptMessage

文本内容

图像内容

音频内容

资源链接

嵌入式资源

错误处理

实现注意事项

安全