MCP中文文檔
核心概念
採樣

採樣

採樣是 MCP 的一個強大功能，允許服務器通過客戶端請求 LLM 補全，從而實現複雜的代理行為，同時保持安全性和隱私性。

MCP 的這個功能目前在 Claude Desktop 客戶端中尚不支持。

採樣工作原理

採樣流程遵循以下步驟：

  1. 服務器向客戶端發送 sampling/createMessage 請求
  2. 客戶端審查請求並可以修改它
  3. 客戶端從 LLM 採樣
  4. 客戶端審查補全結果
  5. 客戶端將結果返回給服務器

這種人在環路(human-in-the-loop)的設計確保用戶能夠控制 LLM 看到和生成的內容。

消息格式

採樣請求使用標準化的消息格式：

{
  messages: [
    {
      role: "user" | "assistant",
      content: {
        type: "text" | "image",

        // 文本類型：
        text?: string,

        // 圖片類型：
        data?: string,             // base64 編碼
        mimeType?: string
      }
    }
  ],
  modelPreferences?: {
    hints?: [{
      name?: string                // 建議的模型名稱/系列
    }],
    costPriority?: number,         // 0-1，最小化成本的重要性
    speedPriority?: number,        // 0-1，低延遲的重要性
    intelligencePriority?: number  // 0-1，能力的重要性
  },
  systemPrompt?: string,
  includeContext?: "none" | "thisServer" | "allServers",
  temperature?: number,
  maxTokens: number,
  stopSequences?: string[],
  metadata?: Record<string, unknown>
}

請求參數

消息

messages 數組包含要發送給 LLM 的對話歷史。每條消息有：

  • role：可以是 “user” 或 “assistant”
  • content：消息內容，可以是：
    • 帶有 text 字段的文本內容
    • 帶有 data（base64）和 mimeType 字段的圖片內容

模型偏好

modelPreferences 對象允許服務器指定其模型選擇偏好：

  • hints：客戶端可以用來選擇合適模型的模型名稱建議數組：

    • name：可以匹配完整或部分模型名稱的字符串（如 “claude-3”、“sonnet”）
    • 客戶端可以將提示映射到不同提供商的等效模型
    • 多個提示按優先順序評估

  • 優先級值（0-1 歸一化）：

    • costPriority：最小化成本的重要性
    • speedPriority：低延遲響應的重要性
    • intelligencePriority：高級模型能力的重要性

客戶端根據這些偏好和其可用模型做出最終的模型選擇。

系統提示詞

可選的 systemPrompt 字段允許服務器請求特定的系統提示詞。客戶端可以修改或忽略這個提示詞。

上下文包含

includeContext 參數指定要包含哪些 MCP 上下文：

  • "none"：不包含額外上下文
  • "thisServer"：包含來自請求服務器的上下文
  • "allServers"：包含來自所有已連接 MCP 服務器的上下文

客戶端控制實際包含的上下文。

採樣參數

通過以下參數微調 LLM 採樣：

  • temperature：控制隨機性（0.0 到 1.0）
  • maxTokens：生成的最大令牌數
  • stopSequences：停止生成的序列數組
  • metadata：額外的提供商特定參數

響應格式

客戶端返回補全結果：

{
  model: string,  // 使用的模型名稱
  stopReason?: "endTurn" | "stopSequence" | "maxTokens" | string,
  role: "user" | "assistant",
  content: {
    type: "text" | "image",
    text?: string,
    data?: string,
    mimeType?: string
  }
}

示例請求

這是向客戶端請求採樣的示例：

{
  "method": "sampling/createMessage",
  "params": {
    "messages": [
      {
        "role": "user",
        "content": {
          "type": "text",
          "text": "當前目錄中有哪些文件？"
        }
      }
    ],
    "systemPrompt": "你是一個有幫助的文件系統助手。",
    "includeContext": "thisServer",
    "maxTokens": 100
  }
}

最佳實踐

在實現採樣時：

  1. 始終提供清晰、結構良好的提示詞
  2. 適當處理文本和圖片內容
  3. 設置合理的令牌限制
  4. 通過 includeContext 包含相關上下文
  5. 在使用前驗證響應
  6. 優雅地處理錯誤
  7. 考慮採樣請求的速率限制
  8. 記錄預期的採樣行為
  9. 使用各種模型參數進行測試
  10. 監控採樣成本

人在環路控制

採樣設計時考慮了人工監督：

對於提示詞

  • 客戶端應向用戶展示建議的提示詞
  • 用戶應能修改或拒絕提示詞
  • 系統提示詞可以被過濾或修改
  • 上下文包含由客戶端控制

對於補全

  • 客戶端應向用戶展示補全結果
  • 用戶應能修改或拒絕補全結果
  • 客戶端可以過濾或修改補全結果
  • 用戶控制使用哪個模型

安全考慮

在實現採樣時：

  • 驗證所有消息內容
  • 淨化敏感信息
  • 實現適當的速率限制
  • 監控採樣使用情況
  • 加密傳輸中的數據
  • 處理用戶數據隱私
  • 審計採樣請求
  • 控制成本暴露
  • 實現超時
  • 優雅地處理模型錯誤

常見模式

代理工作流

採樣支持的代理模式包括：

  • 讀取和分析資源
  • 基於上下文做出決策
  • 生成結構化數據
  • 處理多步驟任務
  • 提供交互式幫助

上下文管理

上下文的最佳實踐：

  • 請求最少必要的上下文
  • 清晰地組織上下文
  • 處理上下文大小限制
  • 根據需要更新上下文
  • 清理過時的上下文

錯誤處理

健壯的錯誤處理應該：

  • 捕獲採樣失敗
  • 處理超時錯誤
  • 管理速率限制
  • 驗證響應
  • 提供回退行為
  • 適當記錄錯誤

限制

需要注意這些限制：

  • 採樣依賴於客戶端功能
  • 用戶控制採樣行為
  • 上下文大小有限制
  • 可能應用速率限制
  • 需要考慮成本
  • 模型可用性不同
  • 響應時間不同
  • 不是所有內容類型都支持
根目錄提示詞