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客户端提供列出可用工具和使用特定参数执行它们的方法。每个工具都有一个唯一的名称，并接受一个参数映射。

```java // 列出可用工具及其名称 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 ));

  </Tab>

  <Tab title="异步 API">
```java
// 异步列出可用工具
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客户端提供发现可用资源并通过标准化接口检索其内容的方法。

```java // 列出可用资源及其名称 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” ));

  </Tab>

  <Tab title="异步 API">
```java
// 异步列出可用资源
client.listResources()
    .doOnNext(resources -> resources.forEach(resource -> 
        System.out.println(resource.getName())))
    .subscribe();

// 异步检索资源内容
client.getResource("file", Map.of(
        "path", "/path/to/file.txt"
    ))
    .subscribe();

提示系统

提示系统使与服务器端提示模板的交互成为可能。这些模板可以被发现并使用自定义参数执行，从而根据预定义模式生成动态文本。

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

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

  </Tab>

  <Tab title="异步 API">
```java
// 异步列出可用提示模板
client.listPrompts()
    .doOnNext(prompts -> prompts.forEach(prompt -> 
        System.out.println(prompt.getName())))
    .subscribe();

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

MCP 服务器