MCP Java SDK

为 Model Context Protocol 提供 Java SDK 集成的一系列项目。此 SDK 使 Java 应用程序能够通过标准化接口与 AI 模型和工具交互，支持同步和异步通信模式。

📚 参考文档

MCP Java SDK 文档

全面的指南和 SDK API 文档

• Features - 概述 Java MCP SDK 提供的功能
• Architecture - Java MCP SDK 架构概述
• Java Dependencies / BOM - Java 依赖项和 BOM
• Java MCP Client - 了解如何使用 MCP 客户端与 MCP 服务器交互
• Java MCP Server - 了解如何实现和配置 MCP 服务器

Spring AI MCP 文档

Spring AI MCP 扩展了 MCP Java SDK，提供 Spring Boot 集成，包括 client 和 server 启动器。MCP Annotations 为 Java 中的 MCP 服务器和客户端提供基于注解的方法处理。MCP Security 为 Spring AI 中的 Model Context Protocol 实现提供全面的 OAuth 2.0 和基于 API 密钥的安全支持。使用 Spring Initializer 快速搭建具有 MCP 支持的 AI 应用程序。

开发

从源代码构建

./mvnw clean install -DskipTests

运行测试

运行测试前，您需要预先安装 Docker 和 npx。

./mvnw test

一致性测试

SDK 已通过 MCP 一致性测试套件 0.1.15 版本的验证。 完整详情和说明请参见 conformance-tests/VALIDATION_RESULTS.md。

最新结果：

套件	结果
服务端	✅ 40/40 通过 (100%)
客户端	🟡 3/4 场景，9/10 检查项通过
认证（Spring）	🟡 12/14 场景完全通过（98.9% 检查项）

要在本地运行一致性测试，您需要安装 npx。

# Server conformance
./mvnw compile -pl conformance-tests/server-servlet -am exec:java
npx @modelcontextprotocol/conformance server --url http://localhost:8080/mcp --suite active

# Client conformance
./mvnw clean package -DskipTests -pl conformance-tests/client-jdk-http-client -am
for scenario in initialize tools_call elicitation-sep1034-client-defaults sse-retry; do
  npx @modelcontextprotocol/conformance client \
    --command "java -jar conformance-tests/client-jdk-http-client/target/client-jdk-http-client-2.0.1-SNAPSHOT.jar" \
    --scenario $scenario
done

# Auth conformance (Spring HTTP Client)
./mvnw clean package -DskipTests -pl conformance-tests/client-spring-http-client -am
npx @modelcontextprotocol/conformance@0.1.15 client \
  --spec-version 2025-11-25 \
  --command "java -jar conformance-tests/client-spring-http-client/target/client-spring-http-client-2.0.1-SNAPSHOT.jar" \
  --suite auth

贡献指南

欢迎贡献代码！ 请遵循贡献指南。

团队成员

• Christian Tzolov
• Dariusz Jędrzejczyk
• Daniel Garnier-Moiroux

相关链接

• GitHub 代码仓库
• 问题跟踪器
• CI/CD

架构与设计决策

引言

构建通用的 MCP Java SDK，需要在 JDK 支持有限或缺失的领域做出技术决策。Java 生态系统功能强大但较为分散：存在多种有效的实现方案，且各自拥有庞大的社区支持。 我们的目标并非规定“唯一正确的方式”，而是提供 MCP 规范的参考实现，该实现应具备以下特性：

• 实用性——帮助开发者快速提升开发效率
• 互操作性——与广泛使用的库和实践保持一致
• 可插拔性——允许项目在偏好不同技术栈时选择替代方案
• 基于团队熟悉度——我们选择团队当前能够高效使用的技术，同时对能扩展 SDK 功能的社区贡献保持开放态度

关键选择与考量

SDK 需在以下领域做出决策：

1. JSON 序列化——JSON 与 Java 类型之间的映射

2. 编程模型——支持异步处理、取消操作和流式传输，同时保持阻塞用例的简洁性

3. 可观测性——日志记录以及与指标/追踪系统的集成支持

4. 远程客户端与服务器——支持消费 MCP 服务器（客户端传输）和暴露 MCP 端点（带授权的服务器传输）

以下部分将说明我们的选择、选择的原因以及这些选择如何与 SDK 的目标保持一致。

1. JSON 序列化

• SDK 选择：采用 Jackson 进行 JSON 序列化和反序列化，并通过 SDK 抽象层封装（位于 mcp-core 中的 io.modelcontextprotocol.json 包）

• 选择原因：Jackson 在 Java 生态系统中被广泛采用，具备出色的性能和成熟的注解模型，并且为 SDK 团队及众多潜在贡献者所熟悉。

• 暴露方式：公共 API 使用捆绑的抽象层。Jackson 作为默认实现（mcp-json-jackson3）提供，同时支持插入其他替代实现。

• 与 SDK 的契合度：这一选择提供了实用的默认方案，同时为偏好其他 JSON 库的项目保留了灵活性。

2. 编程模型

• SDK 选择：公共 API 采用 Reactive Streams，内部实现使用 Project Reactor，并为阻塞用例提供同步外观

• 选择原因：MCP 建立在 JSON-RPC 的异步特性之上，并在其基础上定义了双向协议，支持异步和流式交互。MCP 明确支持：

  • 多个进行中的请求和响应
  • 不期望回复的通知
  • 用于进程间通信的 STDIO 传输（使用管道）
  • 流式传输，如 Server-Sent Events 和 Streamable HTTP

  这些要求需要比 CompletableFuture 等单结果 futures 更强大的编程模型。

  • Reactive Streams：社区标准

    Reactive Streams 是一个小型 Java 规范，它标准化了带背压的异步流处理。它定义了四个最小接口（Publisher、Subscriber、Subscription 和 Processor）。这些接口被广泛认为是 Java 中异步、非阻塞管道的标准契约。

  • Reactive Streams 实现

    SDK 使用 Project Reactor 作为 Reactive Streams 规范的实现。Reactor 成熟且被广泛采用，提供丰富的操作符，并通过上下文传播与可观测性良好集成。团队对其的熟悉度也使我们能够快速交付坚实的基础。 我们计划将公共 API 转换为仅公开 Reactive Streams 接口。通过基于 Reactive Streams 接口定义公共 API 并在内部使用 Reactor，SDK 保持了基于标准的特性，同时受益于实用、生产就绪的实现。

  • SDK 中的同步外观

    并非所有 MCP 用例都需要流式管道。许多场景很简单，例如“发送请求并阻塞直到获得结果”。 为支持这一点，SDK 在响应式核心之上提供了同步外观。开发人员在足够的情况下可以保持阻塞模型，同时在需要时仍能访问异步流。

• 如何适应 SDK：这种设计平衡了可扩展性、易用性和未来演进（如即将发布的 JDK 中的虚拟线程和结构化并发）。

3. 可观测性

• SDK 选择：使用 SLF4J 进行日志记录；使用 Reactor Context 实现可观测性数据传播

• 选择原因：SLF4J 是 Java 领域事实上的日志门面，具有广泛的兼容性。Reactor Context 能够跨异步边界传播可观测性数据，如关联 ID 和追踪状态。这确保了与现代可观测性框架的互操作性。

• 暴露方式：公共 API 仅通过 SLF4J 记录日志，不包含任何后端实现。可观测性元数据通过 Reactor 管道流转。SDK 本身不提供指标或追踪的具体实现。

• 在 SDK 中的作用：这提供了默认的可靠日志记录，并能与 Micrometer、OpenTelemetry 或类似的指标和追踪系统无缝集成。

4. 远程 MCP 客户端与服务器

MCP 同时支持客户端（消费 MCP 服务器的应用程序）和服务器（公开 MCP 端点的应用程序）。SDK 为这两方都提供了支持。

SDK 中的客户端传输

• SDK 选择：JDK HttpClient（Java 11+）作为默认客户端

• 选择原因：JDK HttpClient 是内置组件，具有可移植性，并支持流式响应。这使得默认配置轻量且无额外依赖。

• 暴露方式：MCP 客户端 API 与传输方式无关。核心模块提供 JDK HttpClient 传输实现。基于 Spring WebClient 的传输可在 Spring AI 2.0+ 版本中获取。

• 在 SDK 中的作用：这确保所有应用程序都能开箱即用地与 MCP 服务器通信，同时允许在 Spring 和其他环境中进行更丰富的集成。

SDK 中的服务器传输

• SDK 选择：核心模块中采用 Jakarta Servlet 实现

• 选择原因：Servlet 是部署最广泛的 Java 服务器 API，无需额外依赖即可在阻塞和非阻塞模型中广泛应用。

• 暴露方式：服务器 API 与传输方式无关。核心模块包含 Servlet 支持。Spring WebFlux 和 WebMVC 服务器传输可在 Spring AI 2.0+ 版本中获取。

• 在 SDK 中的作用：这允许开发人员在当今最常见的 Java 环境中公开 MCP 服务器，同时支持其他传输实现，如 Netty、Vert.x 或 Helidon。

SDK 中的授权

• SDK 选择：为 MCP 服务器提供可插拔的授权钩子；无内置实现

• 选择原因：MCP 服务器必须限制仅授权和已认证的客户端访问。不同环境（如 Spring Security、MicroProfile JWT 或自定义解决方案）的授权需求各不相同。提供钩子可以避免锁定，并利用成熟的库。

• 暴露方式：授权集成在服务器传输层中。SDK 不包含其自身的授权系统。

• 在 SDK 中的作用：这保持了服务器端安全的生态系统中立性，同时确保应用程序可以接入其首选的授权策略。

SDK 的项目结构

SDK 按模块组织，以实现关注点分离，并允许使用者仅引入所需内容：

• mcp-bom – 依赖版本
• mcp-core – 参考实现（STDIO、JDK HttpClient、Servlet）、JSON 绑定接口定义
• mcp-json-jackson2 – JSON 绑定的 Jackson 2 实现
• mcp-json-jackson3 – JSON 绑定的 Jackson 3 实现
• mcp – 便捷捆绑包（核心 + Jackson 3）
• mcp-test – 共享测试工具

Spring 集成（WebClient、WebFlux、WebMVC）现已成为 Spring AI 2.0+（组 org.springframework.ai）的一部分。

例如，简单的使用者可能仅依赖 mcp（核心 + Jackson），而基于 Spring 的应用程序可以使用 Spring AI 的 mcp-spring-webflux 或 mcp-spring-webmvc 构件以实现更深层次的框架集成。

此外，mcp-test 包含 mcp-core 的集成测试。 mcp-core 需要 JSON 实现才能运行完整的集成测试。 诸如 mcp-json-jackson3 之类的实现依赖于 mcp-core，因此不能在 mcp-core 的测试中导入。 相反，所有需要 JSON 实现的集成测试现在都位于 mcp-test 中，并默认使用 jackson3。 jackson2 maven 配置文件允许使用 Jackson 2 运行集成测试，如下所示：

./mvnw -pl mcp-test -am -Pjackson2 test

未来发展方向

本 SDK 旨在随 Java 生态系统共同发展。我们正密切关注的领域包括： JDK 中的并发——虚拟线程和结构化并发可能会简化同步 API 的实现

许可证

本项目采用 MIT 许可证 进行许可。