​
Model Context Protocol 客户端

MCP 客户端是 Model Context Protocol (MCP) 架构中的一个关键组件，负责建立和管理与 MCP 服务器的连接。它实现了协议的客户端部分，处理：
  • 协议版本协商以确保与服务器的兼容性
  • 能力协商以确定可用功能
  • 消息传输和 JSON-RPC 通信
  • 工具发现和执行
  • 资源访问和管理
  • 提示系统交互
  • 可选功能，如根目录管理和采样支持
核心的 io.modelcontextprotocol.sdk:mcp 模块提供了 STDIO 和 SSE 客户端传输实现，无需额外的 Web 框架。对于 Spring Framework 用户，Spring 特定的传输实现作为可选依赖 io.modelcontextprotocol.sdk:mcp-spring-webflux 提供。
客户端同时提供同步和异步 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))
);

// 列出和读取资源
ListResourcesResult resources = client.listResources();
ReadResourceResult resource = client.readResource(
    new ReadResourceRequest("resource://uri")
);

// 列出和使用提示
ListPromptsResult prompts = client.listPrompts();
GetPromptResult prompt = client.getPrompt(
    new GetPromptRequest("greeting", Map.of("name", "Spring"))
);

// 添加/删除根目录
client.addRoot(new Root("file:///path", "description"));
client.removeRoot("file:///path");

// 关闭客户端
client.closeGracefully();

​
客户端传输

传输层处理 MCP 客户端和服务器之间的通信，为不同的用例提供不同的实现。客户端传输管理消息序列化、连接建立和协议特定的通信模式。
为进程内通信创建传输
ServerParameters params = ServerParameters.builder("npx")
    .args("-y", "@modelcontextprotocol/server-everything", "dir")
    .build();
McpTransport transport = new StdioClientTransport(params);

​
客户端能力

客户端可以配置各种能力： 
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();
此功能允许：
  • 服务器无需 API 密钥即可利用 AI 功能
  • 客户端保持对模型访问和权限的控制
  • 支持文本和基于图像的交互
  • 可选在提示中包含 MCP 服务器上下文

​
日志支持

客户端可以注册日志消费者以接收来自服务器的日志消息，并设置最小日志级别以过滤消息： 
var mcpClient = McpClient.sync(transport)
        .loggingConsumer(notification -> {
            System.out.println("收到日志消息：" + notification.data());
        })
        .build();

mcpClient.initialize();

mcpClient.setLoggingLevel(McpSchema.LoggingLevel.INFO);

// 调用可以发送日志通知的工具
CallToolResult result = mcpClient.callTool(new McpSchema.CallToolRequest("logging-test", Map.of()));
客户端可以通过 mcpClient.setLoggingLevel(level) 请求控制它们接收的最小日志级别。低于设置级别的消息将被过滤掉。 支持的日志级别（按严重程度递增排序）：DEBUG (0)、INFO (1)、NOTICE (2)、WARNING (3)、ERROR (4)、CRITICAL (5)、ALERT (6)、EMERGENCY (7)

​
使用 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
));

​
资源访问

资源代表客户端可以使用 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"
));

​
提示系统

提示系统支持与服务器端提示模板的交互。这些模板可以被发现并使用自定义参数执行，允许基于预定义模式生成动态文本。 
// 列出可用提示模板
var prompts = client.listPrompts();
prompts.forEach(prompt -> System.out.println(prompt.getName()));

// 使用参数执行提示模板
var response = client.executePrompt("echo", Map.of(
    "text", "你好，世界！"
));