Preparing diagram...

{
  "capabilities": {
    "sampling": {}
  }
}

Preparing diagram...

Preparing diagram...

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "sampling/createMessage",
  "params": {
    "messages": [
      {
        "role": "user",
        "content": {
          "type": "text",
          "text": "What is the capital of France?"
        }
      }
    ],
    "modelPreferences": {
      "hints": [{ "name": "claude-3-sonnet" }],
      "intelligencePriority": 0.8,
      "speedPriority": 0.5
    },
    "systemPrompt": "You are a helpful assistant.",
    "maxTokens": 100
  }
}

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "role": "assistant",
    "content": {
      "type": "text",
      "text": "The capital of France is Paris."
    },
    "model": "claude-3-sonnet-20240307",
    "stopReason": "endTurn"
  }
}

{
  "type": "text",
  "text": "The message content"
}

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

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

{
  "messages": [
    {
      "role": "user",
      "content": {
        "type": "image",
        "data": "iVBORw0KGgoAAAANS...",
        "mimeType": "image/png"
      }
    },
    {
      "role": "user",
      "content": {
        "type": "text",
        "text": "What's in this image?"
      }
    }
  ]
}

Preparing diagram...

{
  "hints": [
    { "name": "claude-3-sonnet" }, // 优先选择 Sonnet 级别模型
    { "name": "claude" } // 退而求其次选择任何 Claude 模型
  ],
  "costPriority": 0.3, // 成本不太重要
  "speedPriority": 0.8, // 速度非常重要
  "intelligencePriority": 0.5 // 能力需求中等
}

Preparing diagram...

Preparing diagram...

// 服务器端代码
async function requestCodeComments(code: string) {
  const response = await mcpClient.request({
    method: 'sampling/createMessage',
    params: {
      messages: [
        {
          role: 'user',
          content: {
            type: 'text',
            text: `请为以下代码添加详细注释:\n\n${code}`,
          },
        },
      ],
      modelPreferences: {
        hints: [{ name: 'claude-3-sonnet' }],
        intelligencePriority: 0.7,
        speedPriority: 0.5,
        costPriority: 0.3,
      },
      systemPrompt: '你是一个专业的代码审查助手，擅长编写清晰的代码注释。',
      maxTokens: 1000,
    },
  });

  return response.result.content.text;
}

async function analyzeChart(imageBase64: string) {
  const response = await mcpClient.request({
    method: 'sampling/createMessage',
    params: {
      messages: [
        {
          role: 'user',
          content: {
            type: 'image',
            data: imageBase64,
            mimeType: 'image/png',
          },
        },
        {
          role: 'user',
          content: {
            type: 'text',
            text: '请分析这个图表中的趋势和关键发现',
          },
        },
      ],
      modelPreferences: {
        hints: [{ name: 'claude-3-opus' }],
        intelligencePriority: 0.9, // 需要高级理解能力
        speedPriority: 0.3,
        costPriority: 0.2,
      },
      maxTokens: 2000,
    },
  });

  return response.result.content.text;
}

class CustomerServiceAgent {
  private conversationHistory: Message[] = [];

  async chat(userMessage: string): Promise<string> {
    // 添加用户消息到历史
    this.conversationHistory.push({
      role: 'user',
      content: { type: 'text', text: userMessage },
    });

    // 请求 LLM 响应
    const response = await mcpClient.request({
      method: 'sampling/createMessage',
      params: {
        messages: this.conversationHistory,
        modelPreferences: {
          hints: [{ name: 'claude-3-sonnet' }],
          intelligencePriority: 0.6,
          speedPriority: 0.8, // 需要快速响应
          costPriority: 0.5,
        },
        systemPrompt: '你是一个友好且专业的客服代表，帮助用户解决问题。',
        maxTokens: 500,
      },
    });

    // 添加助手响应到历史
    const assistantMessage = response.result.content.text;
    this.conversationHistory.push({
      role: 'assistant',
      content: { type: 'text', text: assistantMessage },
    });

    return assistantMessage;
  }
}

async function robustSampling(prompt: string) {
  try {
    const response = await mcpClient.request({
      method: 'sampling/createMessage',
      params: {
        messages: [
          {
            role: 'user',
            content: { type: 'text', text: prompt },
          },
        ],
        modelPreferences: {
          hints: [{ name: 'claude-3-sonnet' }],
          intelligencePriority: 0.7,
          speedPriority: 0.5,
          costPriority: 0.5,
        },
        maxTokens: 1000,
      },
    });

    return response.result.content.text;
  } catch (error) {
    if (error.code === -1) {
      // 用户拒绝了请求
      console.log('用户拒绝了采样请求');
      return null;
    } else if (error.message.includes('rate limit')) {
      // 速率限制
      console.log('已达到速率限制，请稍后重试');
      throw new Error('RATE_LIMIT_EXCEEDED');
    } else {
      // 其他错误
      console.error('采样请求失败:', error);
      throw error;
    }
  }
}

{
  "jsonrpc": "2.0",
  "id": 1,
  "error": {
    "code": -1,
    "message": "User rejected sampling request"
  }
}

Preparing diagram...

async function analyzeResource(resourceUri: string) {
  // 1. 获取资源内容
  const resource = await getResource(resourceUri);

  // 2. 使用采样分析资源
  const analysis = await mcpClient.request({
    method: 'sampling/createMessage',
    params: {
      messages: [
        {
          role: 'user',
          content: {
            type: 'text',
            text: `分析以下文档内容:\n\n${resource.content}`,
          },
        },
      ],
      modelPreferences: {
        intelligencePriority: 0.8,
      },
    },
  });

  return analysis.result.content.text;
}

{
  "chat.mcp.serverSampling": {
    "my-server": {
      "allowedModels": [
        "github.copilot-chat/gpt-4o",
        "github.copilot-chat/claude-sonnet-4",
        "github.copilot-chat/claude-3.7-sonnet",
        "github.copilot-chat/gemini-2.5-pro",
        "github.copilot-chat/o4-mini"
      ]
    }
  }
}

// .vscode/settings.json 或用户设置
{
  // 启用 MCP 采样功能
  "chat.mcp.serverSampling": {
    "task-master-ai": {
      "allowedModels": [
        "github.copilot-chat/gpt-4.1",
        "github.copilot-chat/claude-3.7-sonnet",
        "github.copilot-chat/claude-3.7-sonnet-thought",
        "github.copilot-chat/claude-sonnet-4",
        "github.copilot-chat/gemini-2.5-pro",
        "github.copilot-chat/gpt-4o",
        "github.copilot-chat/o4-mini"
      ]
    }
  }
}

from fastmcp import FastMCP, Context, schema

mcp = FastMCP("SamplingDemo")

class SentimentResult(schema.BaseModel):
    text: str
    sentiment: str

@mcp.tool
async def analyze_sentiment(text: str, ctx: Context) -> SentimentResult:
    """使用 LLM 分析文本情感"""

    # 构建采样请求
    prompt = (
        "Classify the following text as 'positive', 'negative', or 'neutral'. "
        "Return only one word.\n\n"
        f"Text: {text}"
    )

    # 调用客户端的采样接口
    resp = await ctx.sample(
        messages=prompt,
        temperature=0.0,
        max_tokens=8,
    )

    label = (resp.text or "").strip().lower()

    if label not in {"positive", "negative", "neutral"}:
        label = "neutral"

    return SentimentResult(text=text, sentiment=label)

Preparing diagram...

// 示例配置结构
{
  "agents": {
    "default": {
      "provider": "anthropic",
      "model": "claude-sonnet-4",
      "samplingConfig": {
        "temperature": 0.7,
        "maxTokens": 2000,
        "enableMultiRound": true
      }
    }
  }
}

# 客户端必须实现 sampling handler
async def sampling_handler(
    messages: list,
    model: str = None,
    temperature: float = 0.7,
    max_tokens: int = 1000,
    **kwargs
) -> dict:
    """
    处理来自 MCP 服务器的采样请求

    Args:
        messages: 消息列表或单个字符串
        model: 模型名称（可选）
        temperature: 采样温度
        max_tokens: 最大 token 数

    Returns:
        包含 text 字段的响应字典
    """
    # 1. 可选：展示给用户审核
    user_approved = await show_to_user_for_approval(messages)
    if not user_approved:
        raise Exception("User rejected sampling request")

    # 2. 调用 LLM API
    response = await llm_client.create_completion(
        model=model or "default-model",
        messages=messages,
        temperature=temperature,
        max_tokens=max_tokens,
        **kwargs
    )

    # 3. 可选：响应审核
    final_response = await show_response_for_approval(response)

    return {
        "text": final_response,
        "model": model,
        "stopReason": "endTurn"
    }

# 注册 handler
mcp_client.register_sampling_handler(sampling_handler)

Preparing diagram...

Preparing diagram...

// 预期的标准化 API
interface SamplingConfig {
  // 必需
  messages: Message[];
  maxTokens: number;

  // 模型选择
  modelPreferences?: {
    hints?: ModelHint[];
    costPriority?: number;
    speedPriority?: number;
    intelligencePriority?: number;
  };

  // 可选配置
  systemPrompt?: string;
  temperature?: number;
  includeContext?: 'none' | 'thisServer' | 'allServers';

  // 新增：结构化输出
  outputSchema?: JSONSchema;

  // 新增：工具调用
  tools?: Tool[];
  toolChoice?: 'auto' | 'none' | { name: string };
}

用户: "分析这个 PR 的影响"
Server -> Client Sampling: "分析 PR #123"
  ↓
LLM: 需要获取 PR 详情 [调用工具 get_pr_details]
  ↓
Client: 执行工具 -> 返回数据
  ↓
LLM: 生成分析报告
  ↓
Client -> Server: 返回报告

Preparing diagram...

// 未来的智能路由
class SamplingRouter {
  async route(request: SamplingRequest): Promise<SamplingResponse> {
    // 1. 分析请求特征
    const features = this.analyzeRequest(request);

    // 2. 选择最优模型
    const model = this.selectOptimalModel(features, request.modelPreferences);

    // 3. 决定执行策略
    if (this.canCache(request)) {
      return this.getCached(request);
    }

    if (this.canBatch(request)) {
      return this.addToBatch(request);
    }

    return this.executeDirect(request, model);
  }
}

# 初始化时检查 Sampling 支持
async def check_sampling_support(client_capabilities):
    if "sampling" not in client_capabilities:
        logger.warning("Client does not support sampling")
        # 提供降级方案
        return False
    return True

@mcp.tool
async def analyze_text(text: str, ctx: Context):
    if hasattr(ctx, 'sample'):
        # 使用 Sampling
        result = await ctx.sample(messages=prompt)
    else:
        # 降级：使用本地方法或返回提示
        result = "This feature requires a client with sampling support"
    return result

## Requirements

- MCP Client with Sampling support
- Supported clients: VS Code GitHub Copilot, fast-agent, AIQL TUUI
- Not supported: Claude Desktop, Cursor, Cline

Preparing diagram...