Spring AI MCP Server 集成指南与源码解析

Spring AI 扩展集成

Spring AI MCP 进一步封装了上述 SDK，提供了 Spring Boot Starter 形式的自动配置。这里主要关注 Server 端的集成，WebMvc 和 WebFlux 版本都有对应的 Starter。

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

实战示例

1. 依赖配置

项目中只需引入 WebMvc 版本的 Starter 即可：

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

2. 工具定义

我们需要定义一些业务逻辑作为 Tool 供 AI 调用。这里以天气查询为例，利用 @Tool 注解标记方法，Spring AI 会自动将其注册到 MCP Server。

@Service
public class WeatherService {
    private static final String BASE_URL = "https://api.weather.gov";
    private final RestClient restClient;

    public WeatherService() {
        this.restClient = RestClient.builder()
                .baseUrl(BASE_URL)
                .defaultHeader("Accept", "application/geo+json")
                .defaultHeader("User-Agent", "WeatherApiClient/1.0 ([email protected])")
                .build();
    }

    // 内部记录类用于解析 JSON 响应
    @JsonIgnoreProperties(ignoreUnknown = true)
    public record Points(@JsonProperty("properties") Props properties) { }
    
    @JsonIgnoreProperties(ignoreUnknown = true)
    public record Forecast(@JsonProperty("properties") Props properties) { }

    /**
     * 获取特定经纬度的天气预报
     */
    @Tool(description = "Get weather forecast for a specific latitude/longitude")
    public String getWeatherForecastByLocation(double latitude, double longitude) {
        var points = restClient.get()
                .uri("/points/{latitude},{longitude}", latitude, longitude)
                .retrieve().body(Points.class);
        var forecast = restClient.get()
                .uri(points.properties().forecast())
                .retrieve().body(Forecast.class);
        
        return forecast.properties().periods().stream()
                .map(p -> String.format("%s: Temperature: %s %s Wind: %s %s Forecast: %s",
                        p.name(), p.temperature(), p.temperatureUnit(),
                        p.windSpeed(), p.windDirection(), p.detailedForecast()))
                .collect(Collectors.joining("\n"));
    }
}

除了 Service 类中的方法，我们也可以直接通过回调构建简单的函数工具：

@Bean
public ToolCallback toUpperCase() {
    return FunctionToolCallback.builder("toUpperCase", input -> input.input().toUpperCase())
            .inputType(TextInput.class)
            .description("Put the text to upper case")
            .build();
}

3. 客户端调用

服务端启动后，客户端可以通过 SSE 连接进行交互。这里演示了一个同步客户端的使用流程：初始化、Ping 测试、列出工具以及调用工具。

public class SampleClient {
    public static void main(String[] args) {
        var transport = new HttpClientSseClientTransport("http://localhost:8080");
        var client = McpClient.sync(transport).build();
        
        client.initialize();
        client.ping();
        
        // 查看可用工具列表
        ListToolsResult toolsList = client.listTools();
        System.out.println("Available Tools = " + toolsList);
        
        // 调用天气查询工具
        CallToolResult weatherForcastResult = client.callTool(
            new CallToolRequest("getWeatherForecastByLocation", 
                Map.of("latitude", "47.6062", "longitude", "-122.3321")));
        System.out.println("Weather Forcast: " + weatherForcastResult);
        
        client.closeGracefully();
    }
}

运行后的日志输出会显示协议版本、服务器能力以及具体的工具执行结果。例如，getWeatherForecastByLocation 会返回详细的未来几天天气预报文本。

核心源码剖析

理解了用法之后，我们来看看背后的实现机制，这有助于排查问题或进行二次开发。

协议定义

McpSchema 类集中定义了所有协议层面的常量，包括生命周期方法（如 initialize, ping）、工具方法（tools/list, tools/call）等。这些字符串常量是客户端与服务端通信的基础。

同步客户端封装

McpSyncClient 是对异步客户端 McpAsyncClient 的同步包装。它实现了 AutoCloseable 接口，确保资源能够被正确释放。在实际使用中，我们通常通过 McpClient.sync() 工厂方法获取实例，而不是直接构造，这样更符合现代 Reactor 风格的最佳实践。

自动配置流程

Spring Boot 的自动配置类 McpServerAutoConfiguration 是核心枢纽。它根据配置属性决定创建 McpSyncServer 还是 McpAsyncServer。

该配置类依赖于 McpServerTransportProvider 来提供传输层，并扫描容器中的 ToolCallbackProvider 来注册工具。如果启用了 WebMvc 支持，McpWebMvcServerAutoConfiguration 会进一步注册 SSE 路由函数，处理 HTTP 连接。

简单来说，请求进来后，WebMvcSseServerTransportProvider 会建立会话，将消息分发给 McpServerSession，最终由底层的 RequestHandler 执行具体的工具逻辑。

总结

Spring AI MCP Server 为 Java 开发者接入大模型工具链提供了标准且低侵入的方案。通过简单的注解和配置，即可将本地 API 暴露为 AI 可调用的工具。理解其自动配置机制和底层协议定义，能帮助我们在复杂场景下更好地调试和扩展功能。

参考资料：

• modelcontextprotocol
• modelcontextprotocol java sdk
• mcp-server-boot-starter-docs