Spring AI MCP Server 集成与源码解析

Spring AI 进一步封装了这些依赖，提供了更便捷的自动配置。

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

注意：Spring AI 的 MCP Server 支持 WebMvc 和 WebFlux 两种传输方式，可根据项目架构选择。

服务定义

在 Spring Boot 应用中，我们需要将业务方法暴露为 MCP Tool。这通常通过 @Tool 注解配合 ToolCallbackProvider 实现。

工具提供者配置

创建一个 Bean 来注册工具回调。

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

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

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

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

    @JsonIgnoreProperties(ignoreUnknown = true)
    public record Forecast(@JsonProperty("properties") Props properties) {
        @JsonIgnoreProperties(ignoreUnknown = true)
        public record Props(@JsonProperty("periods") List<Period> periods) { }
        @JsonIgnoreProperties(ignoreUnknown = true)
        public record Period(@JsonProperty("number") Integer number, 
                             @JsonProperty("name") String name, 
                             @JsonProperty("startTime") String startTime, 
                             @JsonProperty("endTime") String endTime, 
                             @JsonProperty("isDaytime") Boolean isDayTime, 
                             @JsonProperty("temperature") Integer temperature, 
                             @JsonProperty("temperatureUnit") String temperatureUnit, 
                             @JsonProperty("temperatureTrend") String temperatureTrend, 
                             @JsonProperty("probabilityOfPrecipitation") Map probabilityOfPrecipitation, 
                             @JsonProperty("windSpeed") String windSpeed, 
                             @JsonProperty("windDirection") String windDirection, 
                             @JsonProperty("icon") String icon, 
                             @JsonProperty("shortForecast") String shortForecast, 
                             @JsonProperty("detailedForecast") String detailedForecast) { }
    }

    @JsonIgnoreProperties(ignoreUnknown = true)
    public record Alert(@JsonProperty("features") List<Feature> features) {
        @JsonIgnoreProperties(ignoreUnknown = true)
        public record Feature(@JsonProperty("properties") Properties properties) { }
        @JsonIgnoreProperties(ignoreUnknown = true)
        public record Properties(@JsonProperty("event") String event, 
                                 @JsonProperty("areaDesc") String areaDesc, 
                                 @JsonProperty("severity") String severity, 
                                 @JsonProperty("description") String description, 
                                 @JsonProperty("instruction") String instruction) { }
    }

    /**
     * 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);
        String forecastText = 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());
        return forecastText;
    }

    /**
     * Get alerts for a specific area
     */
    @Tool(description = "Get weather alerts for a US state. Input is Two-letter US state code (e.g. CA, NY)")
    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"));
    }

    public static void main(String[] args) {
        WeatherService client = new WeatherService();
        System.out.println(client.getWeatherForecastByLocation(47.6062, -122.3321));
        System.out.println(client.getAlerts("NY"));
    }
}

WeatherService 使用 RestClient 去请求 api.weather.gov，它使用@Tool 注解了 getWeatherForecastByLocation、getAlerts 方法。

客户端调用

服务端启动后，客户端可以通过 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(); 
        
        // List and demonstrate tools
        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();
    }
}

这里构建了 HttpClientSseClientTransport，然后通过 McpClient.sync(transport).build() 创建了 McpSyncClient；示例先调用 listTools 查看有哪些 tool，之后构建 CallToolRequest 去请求 getWeatherForecastByLocation、getAlerts 方法。

输出示例：

16:18:34.707 [HttpClient-1-Worker-0] INFO io.modelcontextprotocol.client.McpAsyncClient -- Server response with Protocol: 2024-11-05, Capabilities: ServerCapabilities[experimental=null, logging=LoggingCapabilities[], prompts=null, resources=null, tools=ToolCapabilities[listChanged=true]], Info: Implementation[name=my-weather-server, version=0.0.1] and Instructions null
Available Tools = ListToolsResult[tools=[Tool[name=toUpperCase, description=Put the text to upper case, inputSchema=JsonSchema[type=object, properties={input={type=string}}, required=[input], additionalProperties=false]], Tool[name=getAlerts, description=Get weather alerts for a US state. Input is Two-letter US state code (e.g. CA, NY), inputSchema=JsonSchema[type=object, properties={state={type=string}}, required=[state], additionalProperties=false]], Tool[name=getWeatherForecastByLocation, description=Get weather forecast for a specific latitude/longitude, inputSchema=JsonSchema[type=object, properties={latitude={type=number, format=double}, longitude={type=number, format=double}}, required=[latitude, longitude], additionalProperties=false]]], nextCursor=null]
Weather Forcast: CallToolResult[content=[TextContent[audience=null, priority=null, text="Overnight:\nTemperature: 50 F\nWind: 5 mph N\nForecast: Mostly cloudy, with a low around 50. North wind around 5 mph.\nWednesday:\nTemperature: 70 F\nWind: 2 to 7 mph NW\nForecast: A chance of rain showers between 9am and 5pm, then showers and thunderstorms. Some of the storms could be severe. Mostly cloudy. High near 70, with temperatures falling to around 68 in the afternoon. Northwest wind 2 to 7 mph. Chance of precipitation is 100%. New rainfall amounts between a quarter and half of an inch possible.\nWednesday Night:\nTemperature: 48 F\nWind: 7 to 10 mph SSW\nForecast: Showers and thunderstorms before 5am, then rain. Some of the storms could be severe. Cloudy. Low around 48, with temperatures rising to around 50 overnight. South southwest wind 7 to 10 mph, with gusts as high as 21 mph. Chance of precipitation is 100%. New rainfall amounts between a quarter and half of an inch possible.\nThursday:\nTemperature: 59 F\nWind: 9 mph S\nForecast: Rain. Cloudy, with a high near 59. South wind around 9 mph, with gusts as high as 21 mph. Chance of precipitation is 90%. New rainfall amounts between a tenth and quarter of an inch possible.\nThursday Night:\nTemperature: 47 F\nWind: 9 mph S\nForecast: Rain. Cloudy, with a low around 47. South wind around 9 mph, with gusts as high as 22 mph. Chance of precipitation is 90%. New rainfall amounts between a quarter and half of an inch possible.\nFriday:\nTemperature: 55 F\nWind: 9 to 13 mph S\nForecast: Rain. Cloudy, with a high near 55. Chance of precipitation is 100%. New rainfall amounts between a tenth and quarter of an inch possible.\nFriday Night:\nTemperature: 44 F\nWind: 6 to 10 mph S\nForecast: Rain. Mostly cloudy, with a low around 44. Chance of precipitation is 80%.\nSaturday:\nTemperature: 55 F\nWind: 7 mph S\nForecast: Rain likely. Partly sunny, with a high near 55.Saturday Night:Temperature: 41 FWind: 2 to 6 mph SEForecast: A chance of rain before 11pm. Mostly cloudy, with a low around 41.Sunday:Temperature: 59 FWind: 2 to 6 mph NNEForecast: A chance of rain after 11am. Mostly cloudy, with a high near 59.Sunday Night:Temperature: 45 FWind: 6 mph ESEForecast: Rain likely. Mostly cloudy, with a low around 45.Monday:Temperature: 54 FWind: 5 to 8 mph SForecast: Rain. Mostly cloudy, with a high near 54.Monday Night:Temperature: 42 FWind: 5 to 8 mph SForecast: Rain likely. Mostly cloudy, with a low around 42.Tuesday:Temperature: 54 FWind: 7 mph SSWForecast: Rain likely. Mostly cloudy, with a high near 54."]], isError=false]
Alert Response = CallToolResult[content=[TextContent[audience=null, priority=null,]], isError=false]

核心源码解析

了解底层实现有助于排查问题。Spring AI MCP Server 的核心在于自动配置类与传输层的对接。

协议定义

McpSchema 类定义了协议中的关键常量，包括生命周期方法（initialize, ping）、工具方法（tools/list, tools/call）等。

public final class McpSchema {
    private static final Logger logger = LoggerFactory.getLogger(McpSchema.class);
    private McpSchema() { }
    public static final String LATEST_PROTOCOL_VERSION = "2024-11-05";
    public static final String JSONRPC_VERSION = "2.0";
    
    // Lifecycle Methods
    public static final String METHOD_INITIALIZE = "initialize";
    public static final String METHOD_NOTIFICATION_INITIALIZED = "notifications/initialized";
    public static final String METHOD_PING = "ping";
    
    // Tool Methods
    public static final String METHOD_TOOLS_LIST = "tools/list";
    public static final String METHOD_TOOLS_CALL = "tools/call";
    public static final String METHOD_NOTIFICATION_TOOLS_LIST_CHANGED = "notifications/tools/list_changed";
    
    // Resources Methods
    public static final String METHOD_RESOURCES_LIST = "resources/list";
    public static final String METHOD_RESOURCES_READ = "resources/read";
    public static final String METHOD_NOTIFICATION_RESOURCES_LIST_CHANGED = "notifications/resources/list_changed";
    public static final String METHOD_RESOURCES_TEMPLATES_LIST = "resources/templates/list";
    public static final String METHOD_RESOURCES_SUBSCRIBE = "resources/subscribe";
    public static final String METHOD_RESOURCES_UNSUBSCRIBE = "resources/unsubscribe";
    
    // Prompt Methods
    public static final String METHOD_PROMPT_LIST = "prompts/list";
    public static final String METHOD_PROMPT_GET = "prompts/get";
    public static final String METHOD_NOTIFICATION_PROMPTS_LIST_CHANGED = "notifications/prompts/list_changed";
    
    // Logging Methods
    public static final String METHOD_LOGGING_SET_LEVEL = "logging/setLevel";
    public static final String METHOD_NOTIFICATION_MESSAGE = "notifications/message";
    
    // Roots Methods
    public static final String METHOD_ROOTS_LIST = "roots/list";
    public static final String METHOD_NOTIFICATION_ROOTS_LIST_CHANGED = "notifications/roots/list_changed";
    
    // Sampling Methods
    public static final String METHOD_SAMPLING_CREATE_MESSAGE = "sampling/createMessage";
    
    private static final ObjectMapper OBJECT_MAPPER = new ObjectMapper();
    //......
}

McpSchema 定义了 Lifecycle 方法 (initialize,notifications/initialized,ping)，Tool 方法 (tools/list,tools/call,notifications/tools/list_changed)，Resources 方法 (resources/list,resources/read,notifications/resources/list_changed,resources/templates/list,resources/subscribe,resources/unsubscribe)，Prompt 方法 (prompts/list,prompts/get,notifications/prompts/list_changed)；Logging 方法 (logging/setLevel,notifications/message)，Roots 方法 (roots/list,notifications/roots/list_changed)，Sampling 方法 (sampling/createMessage)

同步客户端包装

McpSyncClient 是对异步客户端的同步封装，实现了 AutoCloseable 接口，方便资源管理。它内部委托给 McpAsyncClient 执行阻塞操作。

public class McpSyncClient implements AutoCloseable {
    private static final Logger logger = LoggerFactory.getLogger(McpSyncClient.class);
    private static final long DEFAULT_CLOSE_TIMEOUT_MS = 10_000L;
    private final McpAsyncClient delegate;

    // ... constructor ...

    public McpSchema.ServerCapabilities getServerCapabilities() {
        return this.delegate.getServerCapabilities();
    }

    public Object ping() {
        return this.delegate.ping().block();
    }

    public McpSchema.CallToolResult callTool(McpSchema.CallToolRequest callToolRequest) {
        return this.delegate.callTool(callToolRequest).block();
    }

    public McpSchema.ListToolsResult listTools() {
        return this.delegate.listTools().block();
    }
    
    // ... other methods ...
}

McpSyncClient 实现了 AutoCloseable 接口，它主要是使用 McpAsyncClient 进行了包装，包装为同步方法；它提供了 getServerCapabilities、getServerInfo、getClientCapabilities、getClientInfo、initialize、rootsListChangedNotification、addRoot、removeRoot、ping、callTool、listTools、listResources、readResource、listResourceTemplates、subscribeResource、unsubscribeResource、listPrompts、getPrompt、setLoggingLevel

自动装配

McpServerAutoConfiguration 是 Spring Boot 集成的入口。它根据配置决定创建 McpSyncServer 还是 McpAsyncServer，并处理 ToolCallback 的注册逻辑。

@AutoConfiguration(after = { McpWebMvcServerAutoConfiguration.class, McpWebFluxServerAutoConfiguration.class })
@ConditionalOnClass({ McpSchema.class, McpSyncServer.class })
@EnableConfigurationProperties(McpServerProperties.class)
public class McpServerAutoConfiguration {
    private static final LogAccessor logger = new LogAccessor(McpServerAutoConfiguration.class);

    @Bean
    @ConditionalOnMissingBean
    public McpServerTransportProvider stdioServerTransport() {
        return new StdioServerTransportProvider();
    }

    @Bean
    @ConditionalOnProperty(prefix = McpServerProperties.CONFIG_PREFIX, name = "type", havingValue = "SYNC", matchIfMissing = true)
    public McpSyncServer mcpSyncServer(...) {
        // Create the server with both tool and resource capabilities
        AsyncSpecification serverBuilder = McpServer.sync(transportProvider).serverInfo(serverInfo);
        // Register tools, resources, prompts...
        return serverBuilder.build();
    }
}

McpServerAutoConfiguration 主要是提供 McpSyncServer 亦或是 McpAsyncServer，它依赖于 McpServerTransportProvider、McpSchema.ServerCapabilities.Builder、McpServerProperties、List<SyncToolSpecification>、List<SyncResourceSpecification>、List<SyncPromptSpecification>、BiConsumer<McpSyncServerExchange, List<McpSchema.Root>>、List<ToolCallbackProvider>；McpSyncServer 内部是包装 McpAsyncServer 来实现的。

传输层对接

McpWebMvcServerAutoConfiguration 负责配置 WebMvc 环境下的 SSE 传输。它创建了 WebMvcSseServerTransportProvider，并将路由函数注册到 Spring MVC 中，从而处理 HTTP 请求并建立 MCP 会话。

@AutoConfiguration
@ConditionalOnClass({ WebMvcSseServerTransportProvider.class })
@ConditionalOnMissingBean(McpServerTransportProvider.class)
public class McpWebMvcServerAutoConfiguration {
    @Bean
    @ConditionalOnMissingBean
    public WebMvcSseServerTransportProvider webMvcSseServerTransportProvider(ObjectMapper objectMapper, McpServerProperties serverProperties) {
        return new WebMvcSseServerTransportProvider(objectMapper, serverProperties.getSseMessageEndpoint());
    }

    @Bean
    public RouterFunction<ServerResponse> mvcMcpRouterFunction(WebMvcSseServerTransportProvider transportProvider) {
        return transportProvider.getRouterFunction();
    }
}

McpWebMvcServerAutoConfiguration 自动配置了 WebMvcSseServerTransportProvider、mvcMcpRouterFunction

小结

MCP 提供了 Java SDK，同时还提供了 Spring WebFlux 及 MVC 的 SSE 实现；Spring AI MCP 扩展了 MCP Java SDK，提供了 Spring Boot 的集成，其中 MCP-Server 提供了 WebMvc 及 WebFlux 两个版本。McpAsyncServer 内部实现了 MCP 协议定义的方法的 requestHandlers，之后创建 McpServerSession.Factory，设置给 McpServerTransportProvider，与 Spring 提供的 WebMvcSseServerTransportProvider 衔接起来。WebMvcSseServerTransportProvider 通过 McpServerSession.Factory 来集成 MCP，其构造器定义了 routerFunction（注册到 Spring 中），其 handleSseConnection 方法主要是构建 McpServerSession，其 handleMessage 方法获取 McpServerSession，执行其 handle 方法。

参考文档

• Model Context Protocol
• Spring AI MCP Reference