Spring AI MCP

MCP 是一种开放协议，它对应用程序向大语言模型（LLMs）提供上下文信息的方式进行了标准化。可以把 MCP 想象成人工智能应用程序的 USB-C 接口。就像 USB-C 为将设备连接到各种外围设备和配件提供了一种标准化方式一样，MCP 将人工智能模型连接到不同的数据源和工具提供了一种标准化方式。
MCP 可在 LLM 之上构建智能体和复杂的工作流。LLM 通常需要与数据和工具集成，而 MCP 可提供：

• 在 LLM 提供商和供应商之间切换的灵活性。
• 不断扩充的预构建集成列表，大语言模型可以直接接入其中；
• 保护基础设施内数据的最佳实践

MCP Java SDK 提供模型上下文协议的 Java 实现，通过同步和异步通信模式实现与 AI 模型和工具的标准化交互。
Spring AI MCP通过 Spring Boot 集成扩展了 MCP Java SDK，同时提供了客户端和服务器启动器。 使用 Spring Initializer 通过 MCP 支持引导您的 AI 应用程序。

架构

MCP架构

MCP 的核心遵循客户端-服务器架构，其中主机应用程序可以连接到多个服务器：

• MCP 主机：通过 MCP 访问数据的 Claude Desktop、IDE 或 AI 工具等程序
• MCP 客户端：与服务器保持 1：1 连接的协议客户端
• MCP 服务器：轻量级程序，每个程序都通过标准化的模型上下文协议公开特定功能
• 本地数据源：MCP 服务器可以安全访问的计算机文件、数据库和服务
• 远程服务：MCP 服务器可以连接到的互联网（例如，通过 API）提供的外部系统

MCP Java SDK 架构

Java MCP 实现遵循三层架构：

• 客户端/服务器层：McpClient 处理客户端作，而 McpServer 管理服务器端协议作。两者都使用 McpSession 进行通信管理。
• 会话层 （McpSession）：通过 DefaultMcpSession 实现管理通信模式和状态。
• 传输层 （McpTransport）：处理 JSON-RPC 消息序列化和反序列化，并支持多种传输实现。

MCP 客户端

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

• 协议版本协商，确保与服务器兼容
• 用于确定可用功能的功能协商
• 消息传输和 JSON-RPC 通信
• 工具发现和执行
• 资源访问和管理
• 提示系统交互
• 可选功能：
  • 根管理
  • 采样支持
• 同步和异步作
• 交通方式：
  • 基于 Stdio 的传输，用于基于进程的通信
  • 基于 Java HttpClient 的 SSE 客户端传输
  • 用于反应式 HTTP 流的 WebFlux SSE 客户端传输

MCP 服务器

MCP 服务器是模型上下文协议 （MCP） 架构中的基础组件，用于向客户端提供工具、资源和功能。它实现了协议的服务器端，负责：

• 服务器端协议作实现
  • 工具曝光和发现
  • 使用基于 URI 的访问进行资源管理
  • 及时的模板配置和处理
  • 与客户的能力协商
  • 结构化日志记录和通知
• 并发客户端连接管理
• 同步和异步 API 支持
• Transport 实现：
  • 基于 Stdio 的传输，用于基于进程的通信
  • 基于 Servlet 的 SSE 服务器传输
  • 用于反应式 HTTP 流的 WebFlux SSE 服务器传输
  • 用于基于 servlet 的 HTTP 流的 WebMVC SSE 服务器传输

MCP 集成

Spring AI 通过以下 Spring Boot 启动器提供 MCP 集成：
客户端启动器

• spring-ai-starter-mcp-client- Core starter 提供 STDIO 和基于 HTTP 的 SSE 支持
• spring-ai-starter-mcp-client-webflux- 基于 WebFlux 的 SSE 传输实现
  服务器启动器
• spring-ai-starter-mcp-server- 支持 STDIO 传输的核心服务器
• spring-ai-starter-mcp-server-webmvc- 基于 Spring MVC 的 SSE 传输实现
• spring-ai-starter-mcp-server-webflux- 基于 WebFlux 的 SSE 传输实现

客户端启动器

MCP Client Boot Starter 提供：

• 管理多个客户端实例
• 自动客户端初始化（如果启用）
• 支持多个命名传输
• 与 Spring AI 的工具执行框架集成
• 适当的生命周期管理，在应用程序上下文关闭时自动清理资源
• 通过定制器创建可定制的客户端

标准 MCP 客户端
标准启动器通过（进程内）和/或（远程）传输同时连接到一个或多个 MCP 服务器。 SSE 连接使用基于 HttpClient 的传输实现。 与 MCP 服务器的每次连接都会创建一个新的 MCP 客户端实例。 可以选择 MCP 客户端之一（注意：不能混合使用同步客户端和异步客户端）。 对于生产部署，建议将基于 WebFlux 的 SSE 连接与 .STDIOSSESYNCASYNCspring-ai-starter-mcp-client-webflux

<dependency>
    <groupId>org.springframework.ai</groupId>
    <artifactId>spring-ai-starter-mcp-client</artifactId>
</dependency>

WebFlux 客户端
WebFlux 启动器提供与标准启动器类似的功能，但使用基于 WebFlux 的 SSE 传输实现。

<dependency>
    <groupId>org.springframework.ai</groupId>
    <artifactId>spring-ai-starter-mcp-client-webflux</artifactId>
</dependency>

配置属性

通用属性
通用属性的前缀为 ：spring.ai.mcp.client

标准传输属性
标准 I/O 传输的属性前缀为 ：spring.ai.mcp.client.stdio

SSE 传输属性
服务器发送事件 （SSE） 传输的属性前缀为：spring.ai.mcp.client.sse

配置示例：

spring:
  ai:
    mcp:
      client:
        stdio:
          root-change-notification: true
          connections:
            server1:
              command: /path/to/server
              args:
                - --port=8080
                - --mode=production
              env:
                API_KEY: your-api-key
                DEBUG: "true"

自定义客户端

自动配置通过回调接口提供广泛的客户端规范自定义功能。这些定制器允许配置 MCP 客户端行为的各个方面，从请求超时到事件处理和消息处理。

自定义类型
以下自定义选项可用：

• 请求配置 - 设置自定义请求超时
• 自定义采样处理程序 - 服务器通过客户端从 LLM 请求 LLM 采样（或 ）的标准化方式。此流程允许客户端保持对模型访问、选择和权限的控制，同时使服务器能够利用 AI 功能，而无需服务器 API 密钥。completionsgenerations
• 文件系统（根）访问 - 客户端向服务器公开文件系统的标准化方式。 根定义了服务器在文件系统中可以运行的位置的边界，使它们能够了解它们可以访问哪些目录和文件。 服务器可以从支持客户端请求根列表，并在该列表更改时接收通知。roots
• Event Handlers - 当某个服务器事件发生时通知客户端的处理程序：
  • 工具更改通知 - 当可用服务器工具列表发生更改时
  • 资源更改通知 - 当可用服务器资源列表发生更改时。
  • 提示更改通知 - 当可用服务器列表提示更改时。
• 日志记录处理程序 - 服务器向客户端发送结构化日志消息的标准化方式。 客户端可以通过设置最小日志级别来控制日志记录详细程度

可以为同步（McpSyncClientCustomizer ）客户端或异步（McpAsyncClientCustomizer）客户端实现，具体取决于应用程序的需要。
McpSyncClientCustomizer

@Component
public class CustomMcpSyncClientCustomizer implements McpSyncClientCustomizer {
    @Override
    public void customize(String serverConfigurationName, McpClient.SyncSpec spec) {

        // Customize the request timeout configuration
        spec.requestTimeout(Duration.ofSeconds(30));

        // Sets the root URIs that this client can access.
        spec.roots(roots);

        // Sets a custom sampling handler for processing message creation requests.
        spec.sampling((CreateMessageRequest messageRequest) -> {
            // Handle sampling
            CreateMessageResult result = ...
            return result;
        });

        // Adds a consumer to be notified when the available tools change, such as tools
        // being added or removed.
        spec.toolsChangeConsumer((List<McpSchema.Tool> tools) -> {
            // Handle tools change
        });

        // Adds a consumer to be notified when the available resources change, such as resources
        // being added or removed.
        spec.resourcesChangeConsumer((List<McpSchema.Resource> resources) -> {
            // Handle resources change
        });

        // Adds a consumer to be notified when the available prompts change, such as prompts
        // being added or removed.
        spec.promptsChangeConsumer((List<McpSchema.Prompt> prompts) -> {
            // Handle prompts change
        });

        // Adds a consumer to be notified when logging messages are received from the server.
        spec.loggingConsumer((McpSchema.LoggingMessageNotification log) -> {
            // Handle log messages
        });
    }
}

McpAsyncClientCustomizer

@Component
public class CustomMcpAsyncClientCustomizer implements McpAsyncClientCustomizer {
    @Override
    public void customize(String serverConfigurationName, McpClient.AsyncSpec spec) {
        // Customize the async client configuration
        spec.requestTimeout(Duration.ofSeconds(30));
    }
}

服务器启动器

Spring AI MCP（模型上下文协议）服务器启动器提供了在 Spring Boot 应用程序中设置 MCP 服务器的自动配置。它支持将 MCP 服务器功能与 Spring Boot 的自动配置系统无缝集成。
MCP Server Boot Starter 提供：

• 自动配置 MCP 服务器组件
• 支持同步和异步作模式
• 多个传输层选项
• 灵活的工具、资源和提示符规范
• 更改通知功能

标准 MCP 服务器 STDIO

完整的 MCP Server 功能支持服务器传输。

<dependency>
    <groupId>org.springframework.ai</groupId>
    <artifactId>spring-ai-mcp-server-spring-boot-starter</artifactId>
</dependency>

• 适用于命令行和桌面工具
• 不需要额外的 Web 依赖项

启动器激活自动配置(McpServerAutoConfiguration)，负责：

• 配置基本 Server 组件
• 处理工具、资源和提示规范
• 管理 Server 功能和更改通知
• 提供同步和异步服务器实现

WebMVC 服务器传输

完整的 MCP 服务器功能支持基于 Spring MVC 的 SSE（服务器发送事件）服务器传输和可选的STDIO传输。

<dependency>
    <groupId>org.springframework.ai</groupId>
    <artifactId>spring-ai-starter-mcp-server-webmvc</artifactId>
</dependency>

Starter 激活McpWebMvcServerAutoConfiguration 和McpServerAutoConfiguration 的 auto-configurations ：

• 使用 Spring MVC 的基于 HTTP 的传输 （WebMvcSseServerTransportProvider)
• 自动配置的 SSE 终端节点
• 可选传输（通过设置STDIOspring.ai.mcp.server.stdio=true)
• 包含和依赖项spring-boot-starter-webmcp-spring-webmvc

WebFlux 服务器传输

完整的 MCP 服务器功能支持基于 Spring WebFlux 的 SSE（Server-Sent Events） 服务器传输和可选的STDIO传输。

<dependency>
    <groupId>org.springframework.ai</groupId>
    <artifactId>spring-ai-starter-mcp-server-webflux</artifactId>
</dependency>

Starter 激活 McpWebFluxServerAutoConfiguration和McpServerAutoConfiguration 的 auto-configurations ：

• 使用 Spring WebFlux （WebFluxSseServerTransportProvider)
• 自动配置的反应式 SSE 终端节点
• 可选传输（通过设置STDIOspring.ai.mcp.server.stdio=true)
• 包含和依赖项spring-boot-starter-webfluxmcp-spring-webflux

服务器类型

• 同步服务器 - 使用 实现的默认服务器类型。 它专为应用程序中的简单请求-响应模式而设计。 要启用此服务器类型，请在您的配置中设置。 激活后，它会自动处理同步工具规格的配置。McpSyncServerspring.ai.mcp.server.type=SYNC
• 异步服务器 - 异步服务器实现使用非阻塞作并针对非阻塞作进行了优化。 要启用此服务器类型，请使用 配置您的应用程序。 此服务器类型会自动设置具有内置 Project Reactor 支持的异步工具规范。McpAsyncServerspring.ai.mcp.server.type=ASYNC

服务器功能

MCP 服务器支持四种主要功能类型，可以单独启用或禁用：

• 工具 - 启用/禁用工具功能spring.ai.mcp.server.capabilities.tool=true|false
• 资源 - 启用/禁用资源功能spring.ai.mcp.server.capabilities.resource=true|false
• 提示 - 启用/禁用提示功能spring.ai.mcp.server.capabilities.prompt=true|false
• 完成 - 启用/禁用完成功能spring.ai.mcp.server.capabilities.completion=true|false

默认情况下，所有功能均处于启用状态。禁用功能将阻止服务器注册和向客户端公开相应的功能。