Model Context Protocol - Prompts

时间：2025-03-21 21:04:22

1. 概述

  • Model Context Protocol (MCP) 提供了一种标准化的方式，使服务器能够向客户端暴露提示模板（prompts）。
  • Prompts 是服务器提供的结构化消息和指令，用于与语言模型进行交互。客户端可以发现可用的提示、获取其内容，并提供参数以自定义它们。

2. 用户交互模型

  • 用户控制： Prompts 是用户控制的，服务器将它们暴露给客户端，目的是让用户能够明确选择使用它们。
  • 触发方式： 通常通过用户界面中的用户发起的命令（如斜杠命令）触发，但协议本身不限制具体的用户交互模式。

3. 功能声明

  • 支持 Prompts 的服务器必须在初始化时声明 prompts 功能：
    {
  "capabilities": {
    "prompts": {
      "listChanged": true
    }
  }
}
  • listChanged 表示服务器是否会发出通知，告知可用提示列表发生变化。

4. 协议消息

4.1 列出可用的 Prompts
  • 客户端通过发送 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": "Asks the LLM to analyze code quality and suggest improvements",
        "arguments": [
          {
            "name": "code",
            "description": "The code to review",
            "required": true
          }
        ]
      }
    ],
    "nextCursor": "next-page-cursor"
  }
}
4.2 获取特定 Prompt
  • 客户端可以通过发送 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": "Code review prompt",
    "messages": [
      {
        "role": "user",
        "content": {
          "type": "text",
          "text": "Please review this Python code:\ndef hello():\n    print('world')"
        }
      }
    ]
  }
}
4.3 列表变更通知
  • 如果可用提示列表发生变化，服务器会发送 notifications/prompts/list_changed 通知：
    {
  "jsonrpc": "2.0",
  "method": "notifications/prompts/list_changed"
}

5. 消息流程

  • Discovery（发现）： 客户端通过 prompts/list 获取可用提示列表。
  • Usage（使用）： 客户端通过 prompts/get 获取特定提示的内容。
  • Changes（变更）： 服务器通过 list_changed 通知客户端提示列表的更新。

6. 数据类型

6.1 Prompt
  • 提示定义包括：
    • name：提示的唯一标识符。
    • description：可选的人类可读描述。
    • arguments：可选的参数列表，用于自定义提示。
6.2 PromptMessage
  • 提示中的消息可以包含以下内容：
    • role：消息的发起者角色，可以是“user”或“assistant”。
    • content：消息的内容类型，包括以下几种：
      • Text Content（文本内容）：
        {
  "type": "text",
  "text": "The text content of the message"
}
      • Image Content（图像内容）：
        {
  "type": "image",
  "data": "base64-encoded-image-data",
  "mimeType": "image/png"
}
        • 图像数据必须是 base64 编码，并包含有效的 MIME 类型。
      • Audio Content（音频内容）：
        {
  "type": "audio",
  "data": "base64-encoded-audio-data",
  "mimeType": "audio/wav"
}
        • 音频数据必须是 base64 编码，并包含有效的 MIME 类型。
      • Embedded Resources（嵌入资源）：
        {
  "type": "resource",
  "resource": {
    "uri": "resource://example",
    "mimeType": "text/plain",
    "text": "Resource content"
  }
}
        • 嵌入资源可以包含文本或二进制数据，必须包含有效的 URI 和 MIME 类型。

7. 错误处理

  • 服务器应返回标准的 JSON-RPC 错误代码：
    • 无效的提示名称：-32602（Invalid params）
    • 缺少必需的参数：-32602（Invalid params）
    • 内部错误：-32603（Internal error）

8. 实现注意事项

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

9. 安全性

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

10. 相关链接

  • GitHub: Model Context Protocol Specification
  • User Guide
  • Python SDK
  • TypeScript SDK

相关文章