Prompts

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

NOTE

为简洁起见，本页的请求示例省略了 _meta 请求元数据（io.modelcontextprotocol/protocolVersion、 io.modelcontextprotocol/clientInfo 和 io.modelcontextprotocol/clientCapabilities）。每个请求 MUST（必须）包含必需的 _meta 字段；参见 _meta。

用户交互模型

提示模板被设计为用户控制的，这意味着它们由服务端暴露给客户端，其意图是用户能够显式选择使用它们。这指的是由谁决定何时使用提示模板，而非由谁编写其内容。提示模板的内容由服务端定义。

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

例如，作为斜杠命令：

Example of prompt exposed as slash command

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

能力

支持提示模板的服务端 MUST（必须）在其 DiscoverResult 中声明 prompts 能力：

json

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

listChanged 表示当可用提示模板列表发生变化时，服务端是否会发出通知。

声明了 prompts 能力的服务端 MUST（必须）响应 prompts/list 请求，返回当前可供发起请求的客户端使用的提示模板集合。该集合 MAY（可以）为空，并且 MAY（可以）随时间变化（参见 List Changed Notification），但 MUST NOT（不得）因连接而异，也不得作为该连接上其他请求的副作用而变化。该集合 MAY（可以）因请求所呈现的授权而异——例如，仅返回调用方被授予的 scope 所允许的提示模板——因为凭证是逐请求的输入，而非连接状态。

协议消息

列举提示

为获取可用的提示模板，客户端发送 prompts/list 请求。此操作支持分页和缓存。

Request:

json

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

Response:

json

{
  "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 自动补全。

Request:

json

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

Response:

json

{
  "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 的客户端发送通知：

json

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

消息流

sequenceDiagram
    participant Client
    participant Server

    Note over Client,Server: Discovery
    Client->>Server: prompts/list
    Server-->>Client: List of prompts

    Note over Client,Server: Usage
    Client->>Server: prompts/get
    Server-->>Client: Prompt content

    opt listChanged
      Client->>Server: subscriptions/listen (promptsListChanged: true)
      Server--)Client: notifications/subscriptions/acknowledged
      Note over Client,Server: Changes
      Server--)Client: notifications/prompts/list_changed
      Client->>Server: prompts/list
      Server-->>Client: Updated prompts
    end

数据类型

提示

提示模板定义包含：

name：提示模板的唯一标识符
title：可选的、供展示用途的提示模板人类可读名称。
description：可选的人类可读描述
icons：可选的图标数组，用于在用户界面中展示
arguments：可选的参数列表，用于自定义

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"
}

图像数据 MUST（必须）采用 base64 编码，并包含有效的 MIME 类型。这支持在视觉上下文很重要的场景下进行多模态交互。

音频内容

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

json

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

音频数据 MUST（必须）采用 base64 编码，并包含有效的 MIME 类型。这支持在音频上下文很重要的场景下进行多模态交互。

资源链接

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

json

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

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

嵌入式资源

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

json

{
  "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（必须）仔细验证所有提示模板的输入和输出，以防止注入攻击或对资源的未授权访问。

Prompts

用户交互模型

能力

协议消息

列举提示

获取提示

列表变更通知

消息流

数据类型

提示

PromptMessage

文本内容

图像内容

音频内容

资源链接

嵌入式资源

错误处理

实现注意事项

安全

友情链接