Spring AI MCP Server 集成与源码解析

Spring AI 进一步封装了这些依赖，提供了更便捷的自动配置。若使用 WebMvc 作为传输层，只需引入以下 Starter：

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

工具定义与服务端配置

在 Spring Boot 应用中，我们通常将业务方法暴露为 MCP Tool。这里以天气查询服务为例，利用 @Tool 注解标记可被大模型调用的方法。

业务服务 Bean

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

    /**
     * 获取指定经纬度的天气预报
     */
    @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"));
    }

    // 其他数据结构定义...
    // Points, Forecast, Period, Alert 等 Record 类省略
}

工具回调提供者

为了让 MCP 识别这些工具，需要将其注册为 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) {
        // 建立 SSE 连接
        var transport = new HttpClientSseClientTransport("http://localhost:8080");
        var client = McpClient.sync(transport).build();
        
        try {
            client.initialize();
            client.ping();

            // 1. 列出可用工具
            ListToolsResult toolsList = client.listTools();
            System.out.println("Available Tools = " + toolsList);

            // 2. 调用天气查询工具
            CallToolResult weatherResult = client.callTool(
                    new CallToolRequest("getWeatherForecastByLocation", 
                            Map.of("latitude", "47.6062", "longitude", "-122.3321")));
            System.out.println("Weather Forecast: " + weatherResult);

            // 3. 调用警报工具
            CallToolResult alertResult = client.callTool(
                    new CallToolRequest("getAlerts", Map.of("state", "NY")));
            System.out.println("Alert Response = " + alertResult);
        } finally {
            client.closeGracefully();
        }
    }
}

运行后会看到类似以下的日志输出，确认工具已正确注册并返回数据：

INFO io.modelcontextprotocol.client.McpAsyncClient -- Server response with Protocol: 2024-11-05
Available Tools = ListToolsResult[tools=[Tool[name=toUpperCase...], Tool[name=getAlerts...], Tool[name=getWeatherForecastByLocation...]]]
Weather Forcast: CallToolResult[content=[TextContent[text="Overnight: Temperature: 50 F..."]]]

核心机制与源码分析

了解底层实现有助于排查问题。Spring AI MCP 的核心在于自动配置与协议握手。

协议规范 (McpSchema)

McpSchema 类定义了所有协议方法名，包括生命周期（initialize, ping）、工具（tools/list, tools/call）和资源操作等。这确保了客户端与服务端的通信遵循统一标准。

同步客户端包装 (McpSyncClient)

McpSyncClient 是对异步内核 McpAsyncClient 的同步封装。它实现了 AutoCloseable 接口，确保资源释放。关键方法如 initialize() 负责协商协议版本和能力集，callTool() 则阻塞等待工具执行结果。

自动配置 (McpServerAutoConfiguration)

这是 Spring Boot 集成的入口。它根据配置属性决定创建 McpSyncServer 还是 McpAsyncServer。主要逻辑包括：

1. 能力构建：通过 ServerCapabilities.Builder 声明支持的工具、资源或提示词变更通知。
2. 工具注册：扫描 ToolCallback 列表，将其转换为 SyncToolSpecification 并注入服务器。
3. 传输适配：结合 WebMvcSseServerTransportProvider，将 MCP 会话映射到 Spring MVC 的 RouterFunction。

@Bean
public McpSyncServer mcpSyncServer(...) {
    // 构建服务器信息
    McpSchema.Implementation serverInfo = new Implementation(...);
    AsyncSpecification serverBuilder = McpServer.sync(transportProvider).serverInfo(serverInfo);
    
    // 注册工具
    if (!CollectionUtils.isEmpty(toolSpecifications)) {
        serverBuilder.tools(toolSpecifications);
        capabilitiesBuilder.tools(true); // 启用工具变更通知
    }
    
    return serverBuilder.build();
}

总结

Spring AI MCP Server 通过标准化协议降低了大模型接入本地工具的门槛。开发者只需关注业务逻辑的 @Tool 标注，框架会自动处理 HTTP/SSE 传输、协议握手及参数序列化。理解 McpServerAutoConfiguration 和 McpSyncClient 的工作流，能帮助我们在复杂场景下更好地调试和扩展功能。

参考资料

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