跳到主要内容

MCP客户端

备注

0.8.x版本的重大变更 ⚠️

注意： 0.8.x版本引入了几个重大变更，包括新的基于会话的架构。 如果您从0.7.0版本升级，请参考迁移指南获取详细说明。

概述

MCP客户端负责建立和管理与MCP服务器的连接。它处理：

  • 协议版本协商
  • 消息传输
  • 工具发现和调用
  • 资源管理
  • 提示处理

传输选项

MCP客户端支持多种传输实现：

STDIO传输

StdioClientTransportProvider transportProvider = new StdioClientTransportProvider(new ObjectMapper());

HTTP SSE传输

HttpClient

HttpClientSseClientTransportProvider transportProvider = new HttpClientSseClientTransportProvider(
    HttpClient.newBuilder().build(),
    new ObjectMapper(),
    URI.create("http://localhost:8080/mcp/message")
);

WebFlux

WebFluxSseClientTransportProvider transportProvider = new WebFluxSseClientTransportProvider(
    WebClient.builder()
        .baseUrl("http://localhost:8080")
        .build(),
    new ObjectMapper(),
    "/mcp/message"
);

客户端功能

客户端可以配置各种功能：

var capabilities = ClientCapabilities.builder()
    .filesystemRoots(true)  // 启用文件系统根目录支持
    .sampling(true)         // 启用AI模型交互采样
    .build();

使用客户端

同步API

// 创建客户端
var client = McpClient.sync(transportProvider)
    .capabilities(capabilities)
    .build();

// 连接到服务器
client.connect();

// 执行工具
var result = client.callTool("calculator", Map.of(
    "operation", "add",
    "a", 5,
    "b", 3
));

// 读取资源
var content = client.readResource("file:///path/to/resource");

// 获取提示
var prompt = client.getPrompt("greeting", Map.of("name", "Alice"));

// 完成后关闭
client.close();

异步API

// 创建客户端
var client = McpClient.async(transportProvider)
    .capabilities(capabilities)
    .build();

// 连接到服务器
client.connect()
    .doOnSuccess(v -> logger.info("已连接到服务器"))
    .subscribe();

// 执行工具
client.callTool("calculator", Map.of(
    "operation", "add",
    "a", 5,
    "b", 3
))
    .doOnSuccess(result -> logger.info("计算结果: {}", result))
    .subscribe();

// 读取资源
client.readResource("file:///path/to/resource")
    .doOnSuccess(content -> logger.info("资源内容: {}", content))
    .subscribe();

// 获取提示
client.getPrompt("greeting", Map.of("name", "Alice"))
    .doOnSuccess(prompt -> logger.info("生成的提示: {}", prompt))
    .subscribe();

// 完成后关闭
client.close()
    .doOnSuccess(v -> logger.info("客户端已关闭"))
    .subscribe();

错误处理

MCP客户端提供全面的错误处理机制：

try {
    // 执行可能失败的操作
    client.connect();
} catch (McpException e) {
    // 处理MCP特定错误
    logger.error("MCP错误: " + e.getMessage());
} catch (Exception e) {
    // 处理其他错误
    logger.error("错误: " + e.getMessage());
}

对于异步API，错误处理通过错误回调进行：

client.connect()
    .subscribe(
        v -> logger.info("已连接到服务器"),
        error -> logger.error("连接错误: " + error.getMessage())
    );

最佳实践

  1. 资源管理

    • 及时关闭客户端连接
    • 使用try-with-resources语句
    • 管理资源订阅的生命周期

  2. 错误处理

    • 实现适当的错误处理
    • 记录错误信息
    • 提供用户友好的错误消息

  3. 性能优化

    • 重用客户端实例
    • 适当设置超时
    • 管理并发请求

  4. 安全性

    • 验证服务器证书
    • 保护敏感数据
    • 实现适当的访问控制

  5. 监控和日志

    • 记录重要操作
    • 监控性能指标
    • 跟踪错误模式

下一步