> ## Documentation Index
> Fetch the complete documentation index at: https://docs.waytomcp.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 概述

> 模型上下文协议（MCP协议）Java SDK 简介

[模型上下文协议（MCP协议）](https://modelcontextprotocol.org/docs/concepts/architecture)的Java SDK，支持AI模型与工具之间的标准化集成。

## 特性

* MCP客户端和MCP服务器实现，支持：
  * 协议[版本兼容性协商](https://spec.modelcontextprotocol.io/specification/2024-11-05/basic/lifecycle/#initialization)
  * [工具](https://spec.modelcontextprotocol.io/specification/2024-11-05/server/tools/)发现、执行和列表变更通知
  * 使用URI模板的[资源](https://spec.modelcontextprotocol.io/specification/2024-11-05/server/resources/)管理
  * [根目录](https://spec.modelcontextprotocol.io/specification/2024-11-05/client/roots/)列表管理及通知
  * [提示](https://spec.modelcontextprotocol.io/specification/2024-11-05/server/prompts/)处理与管理
  * 支持AI模型交互的[采样](https://spec.modelcontextprotocol.io/specification/2024-11-05/client/sampling/)功能
* 多种传输实现：
  * 默认传输：
    * 基于Stdio的传输，用于进程间通信
    * 基于Java HttpClient的SSE客户端传输，用于HTTP SSE客户端流
    * 基于Servlet的SSE服务器传输，用于HTTP SSE服务器流
  * 基于Spring的传输：
    * WebFlux SSE客户端和服务器传输，用于响应式HTTP流
    * WebMVC SSE传输，用于基于Servlet的HTTP流
* 支持同步和异步编程范式

## 架构

SDK采用分层架构，职责清晰：

<img src="https://mintcdn.com/datalite/Wxs4Dp_Rbe4p9MYx/images/java/mcp-stack.svg?fit=max&auto=format&n=Wxs4Dp_Rbe4p9MYx&q=85&s=ad9eff07ed4eabdba59fd147e09e6765" alt="MCP堆栈架构" width="344" height="195" data-path="images/java/mcp-stack.svg" />

* **客户端/服务器层（McpClient/McpServer）**：均使用McpSession进行同步/异步操作，McpClient处理客户端协议操作，McpServer管理服务器端协议操作。
* **会话层（McpSession）**：使用DefaultMcpSession实现管理通信模式和状态。
* **传输层（McpTransport）**：通过以下方式处理JSON-RPC消息的序列化/反序列化：
  * 核心模块中的StdioTransport（stdin/stdout）
  * 专用传输模块中的HTTP SSE传输（Java HttpClient、Spring WebFlux、Spring WebMVC）

MCP客户端是模型上下文协议（MCP协议）架构中的关键组件，负责建立和管理与MCP服务器的连接。它实现了协议的客户端部分。

<img src="https://mintcdn.com/datalite/Wxs4Dp_Rbe4p9MYx/images/java/java-mcp-client-architecture.jpg?fit=max&auto=format&n=Wxs4Dp_Rbe4p9MYx&q=85&s=417e41c15ea04334c3ece4b3578a084f" alt="Java MCP客户端架构" width="4047" height="3953" data-path="images/java/java-mcp-client-architecture.jpg" />

MCP服务器是模型上下文协议（MCP协议）架构中的基础组件，为客户端提供工具、资源和能力。它实现了协议的服务器端部分。

<img src="https://mintcdn.com/datalite/Wxs4Dp_Rbe4p9MYx/images/java/java-mcp-server-architecture.jpg?fit=max&auto=format&n=Wxs4Dp_Rbe4p9MYx&q=85&s=81d4fdead04b6139b6b8e9ad4471ff91" alt="Java MCP服务器架构" width="4659" height="3433" data-path="images/java/java-mcp-server-architecture.jpg" />

关键交互：

* **客户端/服务器初始化**：传输设置、协议兼容性检查、能力协商和实现细节交换。
* **消息流**：JSON-RPC消息处理，包括验证、类型安全响应处理和错误处理。
* **资源管理**：资源发现、基于URI模板的访问、订阅系统和内容检索。

## 依赖

将以下Maven依赖项添加到您的项目中：

<Tabs>
  <Tab title="Maven">
    核心MCP功能：

    ```xml theme={null}
    <dependency>
        <groupId>io.modelcontextprotocol.sdk</groupId>
        <artifactId>mcp</artifactId>
    </dependency>
    ```

    对于HTTP SSE传输实现，请添加以下依赖项之一：

    ```xml theme={null}
    <!-- 基于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>
    ```
  </Tab>

  <Tab title="Gradle">
    核心MCP功能：

    ```groovy theme={null}
    dependencies {
      implementation platform("io.modelcontextprotocol.sdk:mcp")
      //...
    }
    ```

    对于HTTP SSE传输实现，请添加以下依赖项之一：

    ```groovy theme={null}
    // 基于Spring WebFlux的SSE客户端和服务器传输
    dependencies {
      implementation platform("io.modelcontextprotocol.sdk:mcp-spring-webflux")
    }

    // 基于Spring WebMVC的SSE服务器传输
    dependencies {
      implementation platform("io.modelcontextprotocol.sdk:mcp-spring-webmvc")
    }
    ```
  </Tab>
</Tabs>

### 物料清单（BOM）

物料清单（BOM）声明了给定版本中所有依赖项的推荐版本。在应用程序的构建脚本中使用BOM，可以避免您自己指定和维护依赖项版本。相反，您使用的BOM版本决定了所使用的依赖项版本。它还确保默认情况下您使用的是受支持和测试的依赖项版本，除非您选择覆盖它们。

将BOM添加到您的项目中：

<Tabs>
  <Tab title="Maven">
    ```xml theme={null}
    <dependencyManagement>
        <dependencies>
            <dependency>
                <groupId>io.modelcontextprotocol.sdk</groupId>
                <artifactId>mcp-bom</artifactId>
                <version>0.7.0</version>
                <type>pom</type>
                <scope>import</scope>
            </dependency>
        </dependencies>
    </dependencyManagement>
    ```
  </Tab>

  <Tab title="Gradle">
    ```groovy theme={null}
    dependencies {
      implementation platform("io.modelcontextprotocol.sdk:mcp-bom:0.7.0")
      //...
    }
    ```

    Gradle用户还可以通过使用Gradle（5.0+）原生支持声明依赖约束的Maven BOM来利用Spring AI MCP BOM。通过在Gradle构建脚本的依赖项部分添加'platform'依赖处理程序方法来实现。如上所示，随后可以声明您希望使用的一个或多个spring-ai模块的无版本Starter依赖项，例如spring-ai-openai。
  </Tab>
</Tabs>

将版本号替换为您要使用的BOM版本。

### 可用依赖项

以下依赖项由BOM管理：

* 核心依赖项
  * `io.modelcontextprotocol.sdk:mcp` - 核心MCP库，提供模型上下文协议（MCP协议）实现的基本功能和API。
* 传输依赖项
  * `io.modelcontextprotocol.sdk:mcp-spring-webflux` - 基于WebFlux的服务器发送事件（SSE）传输实现，用于响应式应用程序。
  * `io.modelcontextprotocol.sdk:mcp-spring-webmvc` - 基于WebMVC的服务器发送事件（SSE）传输实现，用于基于Servlet的应用程序。
* 测试依赖项
  * `io.modelcontextprotocol.sdk:mcp-test` - 用于MCP应用程序的测试工具和支持。