Spring AI MCP 服务端详解

概述

Model Context Protocol (MCP) 服务端是 MCP 架构的核心组件，用于将外部工具、资源和提示模板暴露给 AI 模型。通过 Spring AI，开发者可以使用 Boot Starters 和注解轻松构建 MCP 服务端，支持多种传输协议，如 STDIO、SSE、Streamable-HTTP 和 Stateless Streamable-HTTP。MCP 服务端负责工具暴露、资源管理、能力协商、日志记录和客户端通知，支持同步和异步操作。

MCP 服务端采用客户端-服务器架构，其中服务端包装外部系统（如数据库、API 或文件系统），并通过工具（可执行函数）提供标准化访问。Spring AI 通过注解简化开发，实现与 AI 应用的解耦。

设置

要使用 Spring AI 中的 MCP 服务端，请按照以下步骤设置：

1. 使用 Spring Initializer 初始化带有 MCP 支持的 Spring Boot 应用程序。
2. 在 pom.xml 中添加相应的 Spring Boot starter 依赖：

• spring-ai-starter-mcp-server：提供 STDIO 支持。
• spring-ai-starter-mcp-server-webmvc：提供基于 WebMVC 的 SSE、Streamable-HTTP 和 Stateless Streamable-HTTP 支持。
• spring-ai-starter-mcp-server-webflux：提供基于 WebFlux 的响应式传输支持。

例如，添加 MCP 服务端依赖：

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

使用 Spring AI BOM 管理版本：

<dependencyManagement>
    <dependencies>
        <dependency>
            <groupId>org.springframework.ai</groupId>
            <artifactId>spring-ai-bom</artifactId>
            <version>1.0.1</version>
            <type>pom</type>
            <scope>import</scope>
        </dependency>
    </dependencies>
</dependencyManagement>

配置

配置通过 Spring Boot 属性文件（如 application.yaml 或 application.properties）管理。主要传输类型包括 STDIO 和 HTTP 变体。

示例配置

1. STDIO 服务端：

   spring.ai.mcp.server.stdio=true

2. WebMVC 服务端（SSE 默认）：

   spring.ai.mcp.server.protocol=SSE

3. Streamable-HTTP：

   spring.ai.mcp.server.protocol=STREAMABLE

4. Stateless Streamable-HTTP：

   spring.ai.mcp.server.protocol=STATELESS

对于 WebFlux starter，使用类似协议配置。服务端自动配置暴露工具的端点，例如 /mcp。

使用

MCP 服务端 (McpServer) 负责：

• 工具暴露和发现。
• 资源 URI 访问和管理。
• 提示模板处理。
• 能力协商和版本兼容。
• 结构化日志和通知。
• 多客户端并发管理。
• 支持同步/异步 API。

在 Spring AI 中，使用注解定义工具：

• @McpTool：定义工具方法。
• @McpToolParam：定义参数描述。
• @McpResource：暴露资源。
• @McpPrompt：处理提示模板。
• @McpProgressToken：支持进度通知。

注册工具：

@Bean
ToolCallbackProvider authorTools() {
    return MethodToolCallbackProvider.builder()
        .toolObjects(new AuthorRepository())
        .build();
}

动态注册工具使用 McpSyncServer Bean：

mcpSyncServer.addTool(toolSpec);
mcpSyncServer.notifyToolsListChanged();

服务端通过 McpSyncServerExchange 支持双向通信，包括日志 (loggingNotification) 和进度 (progressNotification)。

示例

1. 自定义工具定义（作者仓库）

class AuthorRepository {

    @McpTool(description = "Get Baeldung author details using an article title")
    Author getAuthorByArticleTitle(String articleTitle) {
        // 实际实现查询数据库或 API
        return new Author("John Doe", "john.doe@baeldung.com");
    }

    @McpTool(description = "Get highest rated Baeldung authors")
    List<Author> getTopAuthors() {
        // 实际实现
        return List.of(/* 作者列表 */);
    }
}

2. 天气服务工具（高级示例）

@McpTool
public String getTemperature(McpSyncServerExchange exchange, 
    @McpToolParam double latitude, @McpToolParam double longitude, 
    @McpProgressToken String progressToken) {
    exchange.loggingNotification(/* 日志 */);
    // 获取天气数据
    exchange.progressNotification(new ProgressNotification(progressToken, 0.5, 1.0, "Fetching data"));
    // 如果支持采样，请求客户端生成内容
    if (exchange.supportsCapability(McpCapability.SAMPLING)) {
        // 使用 exchange.createMessage 生成采样
    }
    exchange.progressNotification(new ProgressNotification(progressToken, 1.0, 1.0, "Completed"));
    return "Temperature: 25°C"; // 格式化响应
}

3. 与客户端集成

在客户端应用中配置：

spring:
  ai:
    mcp:
      client:
        sse:
          connections:
            custom-server:
              url: http://localhost:8081

测试工具使用 MCP Inspector：npx @modelcontextprotocol/inspector。

关键特性

• 传输灵活性：支持 STDIO、SSE、Streamable-HTTP 和 Stateless Streamable-HTTP。
• 注解驱动：使用 @McpTool 等注解简化工具定义和自动 JSON schema 生成。
• 动态工具管理：运行时添加/移除工具，并通知客户端。
• 能力支持：日志、进度通知、采样和完成操作。
• Spring Boot 集成：自动配置和包扫描。
• 可扩展性：支持自定义交换对象以实现双向交互。

最佳实践

• 根据部署需求选择合适的 starter 和协议（例如，高并发使用 STATELESS）。
• 使用注解减少样板代码，并配置包扫描以自动发现。
• 实现动态工具以支持功能切换或基于角色的访问。
• 在工具方法中使用 McpSyncServerExchange 提供详细日志和进度更新。
• 测试服务端使用 MCP Inspector 或 Java SDK 客户端。
• 确保能力协商以维护客户端兼容性，并考虑可观察性通过结构化日志。