MCP 客戶端

模型上下文協議客戶端

MCP客戶端是模型上下文協議(MCP)架構中的核心組件，負責建立和管理與MCP服務器的連接。它實現了協議的客戶端部分，處理以下功能：

協議版本協商以確保與服務器的兼容性
能力協商以確定可用功能
消息傳輸和JSON-RPC通信
工具發現和執行
資源訪問和管理
提示系統交互
可選功能如根目錄管理和採樣支持

客戶端同時提供同步和異步API，以適應不同的應用場景。

// 創建具有自定義配置的同步客戶端
McpSyncClient client = McpClient.sync(transport)
    .requestTimeout(Duration.ofSeconds(10))
    .capabilities(ClientCapabilities.builder()
        .roots(true)      // 啟用根目錄功能
        .sampling()       // 啟用採樣功能
        .build())
    .sampling(request -> new CreateMessageResult(response))
    .build();

// 初始化連接
client.initialize();

// 列出可用工具
ListToolsResult tools = client.listTools();

// 調用工具
CallToolResult result = client.callTool(
    new CallToolRequest("calculator", 
        Map.of("operation", "add", "a", 2, "b", 3))
);

// 創建具有自定義配置的異步客戶端
McpAsyncClient client = McpClient.async(transport)
    .requestTimeout(Duration.ofSeconds(10))
    .capabilities(ClientCapabilities.builder()
        .roots(true)      // 啟用根目錄功能
        .sampling()       // 啟用採樣功能
        .build())
    .sampling(request -> Mono.just(new CreateMessageResult(response)))
    .build();

客戶端傳輸

傳輸層處理MCP客戶端和服務器之間的通信，為不同的用例提供多種實現。客戶端傳輸管理消息序列化、連接建立和協議特定的通信模式。

創建基於進程的通信傳輸

ServerParameters params = ServerParameters.builder("npx")
    .args("-y", "@modelcontextprotocol/server-everything", "dir")
    .build();
McpTransport transport = new StdioClientTransport(params);

創建框架無關的（純Java API）SSE客戶端傳輸。包含在核心mcp模塊中。

McpTransport transport = new HttpClientSseClientTransport("http://your-mcp-server");

創建基於WebFlux的SSE客戶端傳輸。需要mcp-webflux-sse-transport依賴。

WebClient.Builder webClientBuilder = WebClient.builder()
    .baseUrl("http://your-mcp-server");
McpTransport transport = new WebFluxSseClientTransport(webClientBuilder);

客戶端功能

客戶端可以配置各種功能：

var capabilities = ClientCapabilities.builder()
    .roots(true)      // 啟用文件系統根目錄支持，並通知列表更改
    .sampling()       // 啟用LLM採樣支持
    .build();

根目錄支持

根目錄定義了服務器在文件系統中可以操作的邊界：

// 動態添加根目錄
client.addRoot(new Root("file:///path", "description"));

// 移除根目錄
client.removeRoot("file:///path");

// 通知服務器根目錄列表更改
client.rootsListChangedNotification();

根目錄功能允許服務器：

採樣支持

採樣使服務器能夠通過客戶端請求LLM交互（“補全”或“生成”）：

// 配置採樣處理器
Function<CreateMessageRequest, CreateMessageResult> samplingHandler = request -> {
    // 採樣實現，接口與LLM
    return new CreateMessageResult(response);
};

// 創建具有采樣支持的客戶端
var client = McpClient.sync(transport)
    .capabilities(ClientCapabilities.builder()
        .sampling()
        .build())
    .sampling(samplingHandler)
    .build();

此功能允許：

服務器利用AI功能而無需API密鑰
客戶端保持對模型訪問和權限的控制
支持文本和圖像交互
可選地在提示中包含MCP服務器上下文

使用MCP客戶端

工具執行

工具是客戶端可以發現和執行的服務器端功能。MCP客戶端提供列出可用工具和使用特定參數執行它們的方法。每個工具都有一個唯一的名稱，並接受一個參數映射。

// 列出可用工具及其名稱
var tools = client.listTools();
tools.forEach(tool -> System.out.println(tool.getName()));

// 使用參數執行工具
var result = client.callTool("calculator", Map.of(
    "operation", "add",
    "a", 1,
    "b", 2
));

// 異步列出可用工具
client.listTools()
    .doOnNext(tools -> tools.forEach(tool -> 
        System.out.println(tool.getName())))
    .subscribe();

// 異步執行工具
client.callTool("calculator", Map.of(
        "operation", "add",
        "a", 1,
        "b", 2
    ))
    .subscribe();

資源訪問

資源表示客戶端可以使用URI模板訪問的服務器端數據源。MCP客戶端提供發現可用資源並通過標準化接口檢索其內容的方法。

// 列出可用資源及其名稱
var resources = client.listResources();
resources.forEach(resource -> System.out.println(resource.getName()));

// 使用URI模板檢索資源內容
var content = client.getResource("file", Map.of(
    "path", "/path/to/file.txt"
));

// 異步列出可用資源
client.listResources()
    .doOnNext(resources -> resources.forEach(resource -> 
        System.out.println(resource.getName())))
    .subscribe();

// 異步檢索資源內容
client.getResource("file", Map.of(
        "path", "/path/to/file.txt"
    ))
    .subscribe();

提示系統

提示系統使與服務器端提示模板的交互成為可能。這些模板可以被發現並使用自定義參數執行，從而根據預定義模式生成動態文本。

// 列出可用提示模板
var prompts = client.listPrompts();
prompts.forEach(prompt -> System.out.println(prompt.getName()));

// 使用參數執行提示模板
var response = client.executePrompt("echo", Map.of(
    "text", "你好，世界!"
));

// 異步列出可用提示模板
client.listPrompts()
    .doOnNext(prompts -> prompts.forEach(prompt -> 
        System.out.println(prompt.getName())))
    .subscribe();

// 異步執行提示模板
client.executePrompt("echo", Map.of(
        "text", "你好，世界!"
    ))
    .subscribe();

MCP 服務器