Model Context Protocol - Prompts

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