MCP指南
A2A协议
MCP规范
A2A规范
博客
MCP指南
A2A协议
MCP规范
A2A规范
博客

提示

协议修订：2024-11-05

模型上下文协议（MCP）为服务器向客户端公开提示模板提供了一种标准化的方式。提示允许服务器为与语言模型的交互提供结构化的消息和指令。客户端可以发现可用提示，检索其内容，并提供参数以进行自定义。

用户交互模型

提示被设计为 用户控制，这意味着它们从服务器公开给客户端，旨在让用户能够明确选择使用它们。

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

例如，作为斜杠命令：

提示作为斜杠命令的示例

然而，实现者可以根据需要通过任何适合的界面模式公开提示——协议本身不强制任何特定的用户交互模型。

能力

支持提示的服务器 必须 在初始化期间声明 prompts 能力：

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

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

协议消息

列出提示

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

请求：

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

响应：

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "prompts": [
      {
        "name": "code_review",
        "description": "请求语言模型分析代码质量并提出改进建议",
        "arguments": [
          {
            "name": "code",
            "description": "要审查的代码",
            "required": true
          }
        ]
      }
    ],
    "nextCursor": "next-page-cursor"
  }
}

获取提示

要检索特定提示，客户端发送 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": {
    "description": "代码审查提示",
    "messages": [
      {
        "role": "user",
        "content": {
          "type": "text",
          "text": "请审查以下 Python 代码：\ndef hello():\n    print('world')"
        }
      }
    ]
  }
}

列表变更通知

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

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

消息流程

sequenceDiagram
    participant Client as 客户端
    participant Server as 服务器

    Note over Client,Server: 发现
    Client->>Server: prompts/list
    Server-->>Client: 提示列表

    Note over Client,Server: 使用
    Client->>Server: prompts/get
    Server-->>Client: 提示内容

    opt listChanged
      Note over Client,Server: 变更
      Server--)Client: prompts/list_changed
      Client->>Server: prompts/list
      Server-->>Client: 更新后的提示
    end

数据类型

提示

提示定义包括：

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

提示消息

提示中的消息可以包含：

  • role：表示发言者的“用户”或“助手”
  • content：以下内容类型之一：

文本内容

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

{
  "type": "text",
  "text": "消息的文本内容"
}

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

图像内容

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

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

图像数据 必须 进行 base64 编码并包含有效的 MIME 类型。这支持多模态交互，其中视觉上下文很重要。

嵌入资源

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

{
  "type": "resource",
  "resource": {
    "uri": "resource://example",
    "mimeType": "text/plain",
    "text": "资源内容"
  }
}

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

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

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

错误处理

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

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

实现注意事项

  1. 服务器 应该 在处理前验证提示参数
  2. 客户端 应该 为大型提示列表处理分页
  3. 双方 应该 尊重能力协商

安全性

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

ON THIS PAGE