Spring AI MCP Server 集成与源码解析

Spring AI 的 Starter 进一步简化了集成过程：

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

注意：mcp-server 系列 Starter 通常包含 WebMvc 和 WebFlux 两个版本，需根据实际架构选择。

服务端实现

核心在于将业务方法暴露为 MCP Tool。我们定义一个 WeatherService，利用 RestClient 调用天气 API，并通过 @Tool 注解标记可被大模型调用的方法。

@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();
    }

    @JsonIgnoreProperties(ignoreUnknown = true)
    public record Points(@JsonProperty("properties") Props properties) { }

    @JsonIgnoreProperties(ignoreUnknown = true)
    public record Forecast(@JsonProperty("properties") Props properties) { }

    @JsonIgnoreProperties(ignoreUnknown = true)
    public record Alert(@JsonProperty("features") List<Feature> features) { }

    /**
     * Get forecast for a specific latitude/longitude
     */
    @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());
    }

    /**
     * Get alerts for a specific area
     */
    @Tool(description = "Get weather alerts for a US state.")
    public String getAlerts(String state) {
        Alert alert = restClient.get()
                .uri("/alerts/active/area/{state}", state)
                .retrieve().body(Alert.class);
        
        return alert.features().stream()
                .map(f -> String.format(
                        "Event: %s Area: %s Severity: %s Description: %s Instructions: %s",
                        f.properties().event(), f.properties().areaDesc(),
                        f.properties().severity(), f.properties().description(),
                        f.properties().instruction()))
                .collect(Collectors.joining("\n"));
    }
}

在配置类中，我们需要将这些服务注册为 ToolCallbackProvider，这样 Spring AI 才能识别它们：

@Bean
public ToolCallbackProvider weatherTools(WeatherService weatherService) {
    return MethodToolCallbackProvider.builder()
            .toolObjects(weatherService)
            .build();
}

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

客户端调用

客户端通过 SSE 传输层与服务端建立连接。初始化后，可以列出可用工具并执行调用。

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);
        
        // 调用警报工具
        CallToolResult alertResult = client.callTool(
            new CallToolRequest("getAlerts", Map.of("state", "NY")));
        System.out.println("Alert Response = " + alertResult);
        
        client.closeGracefully();
    }
}

运行后的日志会显示协议版本、能力协商结果以及工具列表详情，确认连接正常且工具已就绪。

源码解析

协议定义 (McpSchema)

McpSchema 类集中定义了所有协议常量，包括生命周期方法（initialize, ping）、工具方法（tools/list, tools/call）以及资源、提示词等模块的方法名。这确保了客户端和服务端对交互指令的理解一致。

同步客户端 (McpSyncClient)

McpSyncClient 是对异步内核 McpAsyncClient 的同步包装。它实现了 AutoCloseable 接口，内部通过 .block() 阻塞等待响应。对于大多数传统 Java 应用而言，使用同步客户端能显著降低代码复杂度。

自动配置 (McpServerAutoConfiguration)

这是 Spring Boot 集成的核心。该类负责创建 McpSyncServer 或 McpAsyncServer，并根据 McpServerProperties 注册工具、资源和提示词。

@AutoConfiguration(after = { McpWebMvcServerAutoConfiguration.class, McpWebFluxServerAutoConfiguration.class })
@ConditionalOnClass({ McpSchema.class, McpSyncServer.class })
public class McpServerAutoConfiguration {
    // ... 省略部分 Bean 定义
    
    @Bean
    public McpSyncServer mcpSyncServer(...) {
        // 构建 ServerInfo
        McpSchema.Implementation serverInfo = new Implementation(...);
        // 创建 Server Builder
        SyncSpecification serverBuilder = McpServer.sync(transportProvider).serverInfo(serverInfo);
        
        // 注册工具
        if (!CollectionUtils.isEmpty(toolSpecifications)) {
            serverBuilder.tools(toolSpecifications);
            capabilitiesBuilder.tools(serverProperties.isToolChangeNotification());
        }
        // ... 注册资源、提示词等
        
        return serverBuilder.build();
    }
}

传输层适配

McpWebMvcServerAutoConfiguration 负责将 MCP 协议桥接到 Spring MVC 的 SSE 通道。它创建了 WebMvcSseServerTransportProvider，并在其中定义了路由函数，处理 HTTP 请求并建立长连接会话。

参考资料

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