MCP Java SDK 介绍与使用指南
MCP与MCP Java SDK 概念
- MCP 是什么？
模型上下文协议（Model Context Protocol, MCP）是用于标准化AI模型与工具间通信的规范。通过定义通用接口，确保不同AI组件（如模型推理服务、工具插件）能无缝协作。 - MCP Java SDK 的作用
提供Java实现的客户端/服务器组件，简化MCP协议的集成，支持同步/异步通信、资源管理、协议协商等功能。
** MCP Java 版本升级注意 (0.8.x)**
⚠️ 重大变更警告
- 0.8.x版本引入基于会话的架构（Session-Based），旧版本（0.7.0）用户需参考《迁移指南》调整代码。
- 主要影响：连接管理方式、API调用模式可能发生变化。
核心功能一览
| 类别 | 功能描述 |
|---|---|
| 协议兼容性 | 客户端与服务器自动协商协议版本，确保兼容性。 |
| 工具管理 | 动态发现工具、执行操作，并监听工具列表的变更。 |
| 资源管理 | 使用URI模板定位资源，支持订阅资源更新通知（如模型参数变化）。 |
| 提示处理 | 结构化提示的生成与管理，便于模型与工具交互。 |
| 传输方式 | 多种通信实现：Stdio（进程间）、HTTP SSE（流式）、Spring适配（WebFlux/WebMVC）。 |
MCP Java SDK架构分层解析
分层结构
- 客户端/服务器层 (McpClient/McpServer)
- 客户端：发起请求，处理工具调用、资源订阅等操作。
- 服务器：注册工具、管理资源，响应客户端请求。
- 通过
McpSession管理会话状态（如连接超时、重试逻辑）。
- 会话层 (McpSession)
- 控制通信模式（同步/异步），维护会话生命周期。
- 默认实现：
DefaultMcpSession。
- 传输层 (McpTransport)
- 处理消息的序列化与传输，核心实现包括：
StdioTransport：通过标准输入输出通信（无需网络）。HttpClientTransport：基于Java HttpClient的HTTP SSE客户端。SpringWebFluxTransport：响应式HTTP服务（需Spring WebFlux依赖）。
- 处理消息的序列化与传输，核心实现包括：
- 客户端/服务器层 (McpClient/McpServer)：都使用 McpSession 进行同步/异步操作， McpClient 处理客户端协议操作，McpServer 管理服务器端协议操作。
- 会话层 (McpSession)：使用 DefaultMcpSession 实现管理通信模式和状态。
- 传输层 (McpTransport)：通过以下方式处理 JSON-RPC 消息序列化/反序列化：
- 核心模块中的 StdioTransport (标准输入/输出)
- 专用传输模块中的 HTTP SSE 传输 (Java HttpClient, Spring WebFlux, Spring WebMVC)
客户端：
服务端：
** 关键交互流程**
初始化流程
- 设置传输层：选择Stdio、HTTP SSE或其他实现。
- 协议握手：交换版本信息，确认兼容性。
- 功能协商：确定支持的API端点、数据格式等。
消息处理
- 客户端请求 → 序列化为JSON-RPC → 传输层发送 → 服务器处理 → 返回结果/错误。
- 错误处理：内置验证机制，类型安全的响应解析。
资源访问示例
- 客户端通过URI模板请求资源（如
/models/{modelId}/status）。 - 服务器返回资源内容或订阅令牌，客户端监听变更通知。
依赖项配置
必选依赖（核心功能）
<dependency><groupId>io.modelcontextprotocol.sdk</groupId><artifactId>mcp</artifactId><version>0.9.0</version>
</dependency>- 包含Stdio和HTTP SSE传输，无需额外Web框架。
统一版本管理（BOM）
<dependencyManagement><dependencies><dependency><groupId>io.modelcontextprotocol.sdk</groupId><artifactId>mcp-bom</artifactId><version>0.9.0</version><type>pom</type><scope>import</scope></dependency></dependencies>
</dependencyManagement>- 使用BOM可自动对齐所有子依赖版本，避免冲突。
可选依赖（Spring场景）
| 场景 | 依赖项 | 用途 |
|---|---|---|
| 响应式应用 (WebFlux) | mcp-spring-webflux | 支持响应式HTTP SSE通信。 |
| 传统Servlet应用 (WebMVC) | mcp-spring-webmvc | 基于Servlet的HTTP SSE通信。 |
HTTP SSE传输：
<!-- 基于 Spring WebFlux 的 SSE 客户端和服务器传输 -->
<dependency><groupId>io.modelcontextprotocol.sdk</groupId><artifactId>mcp-spring-webflux</artifactId>
</dependency><!-- 基于 Spring WebMVC 的 SSE 服务器传输 -->
<dependency><groupId>io.modelcontextprotocol.sdk</groupId><artifactId>mcp-spring-webmvc</artifactId>
</dependency>
- 核心依赖
io.modelcontextprotocol.sdk:mcp - 提供 Model Context Protocol 实现的基本功能和 API 的核心 MCP 库。
- 传输依赖
io.modelcontextprotocol.sdk:mcp-spring-webflux - 用于响应式应用的基于 WebFlux 的服务器发送事件 (SSE) 传输实现。
io.modelcontextprotocol.sdk:mcp-spring-webmvc - 用于基于 servlet 的应用的基于 WebMVC 的服务器发送事件 (SSE) 传输实现。
- 测试依赖
io.modelcontextprotocol.sdk:mcp-test - MCP 应用的测试工具和支持。
参考：
- [https://modelcontextprotocol.io/sdk/java/mcp-server](https://modelcontextprotocol.io/sdk/java/mcp-server)