MCP Java SDK Client和Server功能详细文档
·
仓库地址https://github.com/modelcontextprotocol/java-sdk
概述
MCP (Model Context Protocol) Java SDK 提供了一个标准化的接口，使AI模型能够通过客户端-服务器架构与外部工具和资源进行交互。该SDK实现了MCP规范的客户端和服务器端功能。
架构概览
分层架构
┌─────────────────────────────────────────────────────────────┐
│ Client/Server Layer │
│ ┌─────────────────┐ ┌─────────────────┐ │
│ │ McpClient │ │ McpServer │ │
│ └─────────────────┘ └─────────────────┘ │
└─────────────────────────────────────────────────────────────┘
┌─────────────────────────────────────────────────────────────┐
│ Session Layer │
│ ┌─────────────────────────────────────────────────────┐ │
│ │ McpSession │ │
│ └─────────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────┘
┌─────────────────────────────────────────────────────────────┐
│ Transport Layer │
│ ┌─────────┐ ┌─────────┐ ┌──────────┐ ┌──────────────────┐ │
│ │ STDIO │ │ SSE │ │Streamable│ │ Spring Transports│ │
│ └─────────┘ └─────────┘ └──────────┘ └──────────────────┘ │
└─────────────────────────────────────────────────────────────┘
Client功能详解
核心接口和类
1. McpClient (工厂类)
- 位置:
io.modelcontextprotocol.client.McpClient - 作用: 创建MCP客户端的入口点
- 主要方法:
sync(McpClientTransport transport)- 创建同步客户端async(McpClientTransport transport)- 创建异步客户端
2. McpAsyncClient (异步客户端)
- 位置:
io.modelcontextprotocol.client.McpAsyncClient - 特点: 使用Project Reactor的Mono和Flux类型进行异步通信
- 关键功能:
- 异步通信使用响应式编程模式
- 工具发现和调用
- 资源访问和管理
- 提示模板处理
- 实时通知
- 结构化日志记录
3. McpSyncClient (同步客户端)
- 位置:
io.modelcontextprotocol.client.McpSyncClient - 特点: 包装异步客户端提供阻塞操作
- 适用场景: 非响应式应用程序的简单集成
Client生命周期
- 初始化阶段 - 建立连接并协商能力
- 正常操作 - 处理请求和通知
- 优雅关闭 - 确保连接正确终止
Client传输层实现
1. STDIO传输
McpTransport transport = new StdioClientTransport();
- 特点: 通过标准输入/输出进行双向通信
- 适用场景: 进程间通信
2. Streamable HTTP传输
McpTransport transport = HttpClientStreamableHttpTransport
.builder("http://your-mcp-server")
.endpoint("/mcp")
.build();
- 特点: 高效的双向通信，支持连接恢复
- 协议版本: 2025-03-26
3. SSE HTTP传输 (传统)
McpTransport transport = new HttpClientSseClientTransport("http://your-mcp-server");
- 特点: 服务器发送事件，单向流式传输
- 协议版本: 2024-11-05
Client核心功能
1. 工具管理
- 工具发现: 获取服务器提供的工具列表
- 工具调用: 执行工具并获取结果
- 模式验证: 可选的JSON Schema验证
2. 资源管理
- 资源访问: URI-based资源访问模式
- 资源模板: 动态资源生成
- 订阅系统: 实时资源更新通知
3. 提示系统
- 提示模板: 标准化AI交互
- 参数化提示: 动态内容生成
- 嵌入式资源: 支持多媒体内容
4. 高级功能
- 采样支持: AI模型采样请求
- 引导支持: 用户信息收集
- 进度跟踪: 长时间操作进度监控
- 根管理: 资源根路径管理
Server功能详解
核心接口和类
1. McpServer (工厂类)
- 位置:
io.modelcontextprotocol.server.McpServer - 作用: 创建MCP服务器的入口点
- 主要方法:
sync(McpServerTransportProvider transportProvider)- 同步服务器async(McpServerTransportProvider transportProvider)- 异步服务器
2. McpAsyncServer (异步服务器)
- 位置:
io.modelcontextprotocol.server.McpAsyncServer - 特点: 使用Project Reactor进行非阻塞操作
- 关键功能:
- 动态工具注册和管理
- 资源处理
- 提示模板管理
- 实时客户端通知
3. McpSyncServer (同步服务器)
- 位置:
io.modelcontextprotocol.server.McpSyncServer - 特点: 阻塞操作，适合传统编程模型
4. McpStatelessSyncServer (无状态服务器)
- 位置:
io.modelcontextprotocol.server.McpStatelessSyncServer - 特点: 用于Streamable HTTP传输，支持水平扩展
Server传输层实现
1. STDIO传输
StdioServerTransportProvider transportProvider =
new StdioServerTransportProvider(new ObjectMapper());
- 特点: 标准输入/输出流通信
- 优势: 轻量级实现，简单配置
2. Streamable HTTP Servlet传输
HttpServletStreamableServerTransportProvider transportProvider =
HttpServletStreamableServerTransportProvider.builder()
.jsonMapper(jsonMapper)
.mcpEndpoint("/mcp")
.build();
- 特点: Servlet-based Streamable HTTP
- 集成: 可与Spring Web应用集成
3. SSE HTTP传输 (传统)
HttpServletSseServerTransportProvider transportProvider =
new HttpServletSseServerTransportProvider(new ObjectMapper(), "/mcp/message");
- 特点: Servlet-based SSE传输
- 端点: SSE端点(
/sse)和消息端点
Server核心功能
1. 工具暴露
- 工具注册: 动态添加和移除工具
- 工具执行: 处理客户端工具调用请求
- 错误处理: 健壮的错误处理和传播
2. 资源管理
- 资源注册: URI-based资源访问
- 资源模板: 动态资源生成模板
- 订阅系统: 资源变更实时通知
3. 提示系统
- 提示模板: 结构化AI交互模板
- 参数处理: 动态参数替换
- 内容支持: 文本、图像、音频等多媒体
4. 会话管理
- 会话生命周期: 连接初始化、操作、关闭
- 并发处理: 多客户端连接管理
- 状态管理: 会话状态维护
Server能力配置
服务器可以配置以下能力：
McpServerFeatures.Async features = McpServerFeatures.async()
.serverInfo(new McpSchema.Implementation("My Server", "1.0.0"))
.tools(myTools)
.resources(myResources)
.prompts(myPrompts)
.completions(myCompletions)
.build();
代码示例
Client使用示例
同步客户端
// 创建传输层
McpTransport transport = new StdioClientTransport();
// 创建同步客户端
McpSyncClient client = McpClient.sync(transport)
.requestTimeout(Duration.ofSeconds(5))
.build();
// 初始化连接
client.initialize();
// 获取工具列表
List<McpSchema.Tool> tools = client.listTools();
// 调用工具
McpSchema.CallToolResult result = client.callTool("myTool", arguments);
// 关闭连接
client.close();
异步客户端
// 创建异步客户端
McpAsyncClient client = McpClient.async(transport)
.requestTimeout(Duration.ofSeconds(10))
.build();
// 响应式操作
client.listTools()
.flatMapMany(tools -> Flux.fromIterable(tools))
.filter(tool -> tool.name().contains("search"))
.subscribe(tool -> System.out.println("Found tool: " + tool.name()));
Server使用示例
异步服务器
// 创建传输层
McpServerTransportProvider transportProvider =
new StdioServerTransportProvider(new ObjectMapper());
// 配置服务器能力
McpServerFeatures.Async features = McpServerFeatures.async()
.tool("calculator", this::handleCalculator)
.resource("file:///data/{filename}", this::handleFileResource)
.build();
// 创建异步服务器
McpAsyncServer server = McpServer.async(transportProvider)
.features(features)
.build();
// 启动服务器
server.start().block();
协议兼容性
支持的协议版本
- Streamable HTTP: 2025-03-26 (推荐)
- SSE HTTP: 2024-11-05 (传统)
- STDIO: 所有版本
能力协商
客户端和服务器在初始化阶段进行能力协商，确保协议兼容性。
性能特性
异步优势
- 高吞吐量: 非阻塞操作支持高并发
- 资源效率: 单线程处理多个请求
- 响应式编程: 支持响应式应用集成
同步优势
- 简单性: 阻塞API易于理解和使用
- 传统集成: 适合非响应式应用
- 调试友好: 同步调用栈更清晰
安全特性
传输安全
- TLS支持: HTTP传输支持TLS加密
- 认证机制: 支持OAuth 2.0和API密钥
- DNS重绑定保护: 防止DNS重绑定攻击
数据验证
- JSON Schema验证: 输入输出数据验证
- 参数验证: 工具参数类型检查
- 边界检查: 防止缓冲区溢出
部署和运维
容器化支持
- Docker镜像: 提供官方Docker镜像
- Kubernetes: 支持Kubernetes部署
- 健康检查: 内置健康检查端点
监控和日志
- 结构化日志: JSON格式结构化日志
- 指标收集: Prometheus指标支持
- 跟踪集成: OpenTelemetry跟踪支持
故障排除
常见问题
- 连接超时: 检查网络连接和防火墙设置
- 协议不匹配: 确认客户端和服务器协议版本兼容
- 内存泄漏: 确保正确关闭连接和释放资源
调试技巧
- 启用调试日志查看详细通信过程
- 使用Wireshark等工具分析网络流量
- 检查JSON-RPC消息格式正确性
总结
MCP Java SDK提供了完整的客户端和服务器实现，支持多种传输协议和编程模型。其模块化设计允许根据具体需求选择适当的组件，而丰富的功能集满足了AI应用与外部工具交互的各种场景需求。
AtomGit 是由开放原子开源基金会联合 CSDN 等生态伙伴共同推出的新一代开源与人工智能协作平台。平台坚持“开放、中立、公益”的理念，把代码托管、模型共享、数据集托管、智能体开发体验和算力服务整合在一起，为开发者提供从开发、训练到部署的一站式体验。
更多推荐
0
0- 0
已为社区贡献1条内容
所有评论(0)