Spring AI MCP Weather Server Sample with WebMVC Starter

Spring AI MCP Weather Server Sample with WebMVC Starter

此示例项目演示如何使用 Spring AI MCP Server Boot Starter 和 WebMVC 传输创建 MCP 服务。它实现了一个天气服务，通过 National Weather Service API 提供用于获取天气信息的工具。

如需了解详情，请参阅 MCP Server Boot Starter 参考文档。

概述

此示例展示了：

• 与 spring-ai-mcp-server-webmvc-spring-boot-starter 集成
• 同时支持 SSE（Server-Sent Events）和 STDIO 传输
• 使用 Spring AI 的 @Tool 注解自动注册工具
• 两个天气相关工具：
  • 根据位置（纬度/经度）获取天气预报
  • 根据美国州份获取天气预警

依赖项

此项目需要 Spring AI MCP Server WebMVC Boot Starter：

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

此 Starter 提供：

• 使用 Spring MVC（WebMvcSseServerTransport）的基于 HTTP 的传输
• 自动配置的 SSE 端点
• 可选的 STDIO 传输
• 内含 spring-boot-starter-web 和 mcp-spring-webmvc 依赖项

构建项目

使用 Maven 构建项目：

./mvnw clean install -DskipTests

运行服务

此服务支持两种传输模式：

WebMVC SSE 模式（默认）

java -jar target/mcp-weather-starter-webmvc-server-0.0.1-SNAPSHOT.jar

STDIO 模式

要启用 STDIO 传输，请设置相应的属性：

java -Dspring.ai.mcp.server.stdio=true -Dspring.main.web-application-type=none -jar target/mcp-weather-starter-webmvc-server-0.0.1-SNAPSHOT.jar

配置

通过 application.properties 配置服务：

# Server identification
spring.ai.mcp.server.name=my-weather-server
spring.ai.mcp.server.version=0.0.1

# Server type (SYNC/ASYNC)
spring.ai.mcp.server.type=SYNC

# Transport configuration
spring.ai.mcp.server.stdio=false
spring.ai.mcp.server.sse-message-endpoint=/mcp/message

# Change notifications
spring.ai.mcp.server.resource-change-notification=true
spring.ai.mcp.server.tool-change-notification=true
spring.ai.mcp.server.prompt-change-notification=true

# Logging (required for STDIO transport)
spring.main.banner-mode=off
logging.file.name=./target/starter-webmvc-server.log

可用工具

天气预报工具

• 名称：getWeatherForecastByLocation
• 描述：获取指定纬度/经度的天气预报
• 参数：
  • latitude：double - 纬度坐标
  • longitude：double - 经度坐标

天气预警工具

• 名称：getAlerts
• 描述：获取美国某州的天气预警
• 参数：
  • state：String - 两字母的美国州代码（例如，CA、NY）

服务实现

此服务使用 Spring Boot 和 Spring AI 的工具注解自动注册工具：

@SpringBootApplication
public class McpServerApplication {
    public static void main(String[] args) {
        SpringApplication.run(McpServerApplication.class, args);
    }

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

WeatherService 使用 @Tool 注解实现天气工具：

@Service
public class WeatherService {
    @Tool(description = "Get weather forecast for a specific latitude/longitude")
    public String getWeatherForecastByLocation(double latitude, double longitude) {
        // Implementation using weather.gov API
    }

    @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) {
        // Implementation using weather.gov API
    }
}

MCP 客户端

你可以使用 STDIO 或 SSE 传输连接天气服务：

手动客户端

WebMVC SSE 客户端

适用于使用 SSE 传输的服务：

var transport = new HttpClientSseClientTransport("http://localhost:8080");
var client = McpClient.sync(transport).build();

STDIO 客户端

适用于使用 STDIO 传输的服务：

var stdioParams = ServerParameters.builder("java")
        .args("-Dspring.ai.mcp.server.stdio=true",
                "-Dspring.main.web-application-type=none",
                "-Dspring.main.banner-mode=off",
                "-Dlogging.pattern.console=",
                "-jar",
                "target/mcp-weather-starter-webmvc-server-0.0.1-SNAPSHOT.jar")
        .build();

var transport = new StdioClientTransport(stdioParams);
var client = McpClient.sync(transport).build();

示例项目包含客户端实现示例：

• SampleClient.java：手动实现的 MCP 客户端
• ClientStdio.java：STDIO 传输连接
• ClientSse.java：SSE 传输连接

为获得更好的开发体验，可以考虑使用 MCP Client Boot Starters。这些 Starter 支持自动配置与 MCP 服务的多个 STDIO 和/或 SSE 连接。示例请参阅 starter-default-client 项目。

Boot Starter 客户端

下面使用 starter-default-client 客户端连接到天气 starter-webmvc-server。

按照 starter-default-client readme 中的说明，构建 mcp-starter-default-client-0.0.1-SNAPSHOT.jar 客户端应用程序。

STDIO 传输

1. 创建一个 mcp-servers-config.json 配置文件，内容如下：

{
  "mcpServers": {
    "weather-starter-webmvc-server": {
      "command": "java",
      "args": [
        "-Dspring.ai.mcp.server.stdio=true",
        "-Dspring.main.web-application-type=none",
        "-Dlogging.pattern.console=",
        "-jar",
        "/absolute/path/to/mcp-weather-starter-webmvc-server-0.0.1-SNAPSHOT.jar"
      ]
    }
  }
}

2. 使用该配置文件运行客户端：

java -Dspring.ai.mcp.client.stdio.servers-configuration=file:mcp-servers-config.json \
 -Dai.user.input='What is the weather in NY?' \
 -Dlogging.pattern.console= \
 -jar mcp-starter-default-client-0.0.1-SNAPSHOT.jar

SSE（WebMVC）传输

1. 启动 mcp-weather-starter-webmvc-server：

java -jar mcp-weather-starter-webmvc-server-0.0.1-SNAPSHOT.jar

这将在端口 8080 上启动 MCP 服务。

2. 在另一个控制台中，启动配置为使用 SSE 传输的客户端：

java -Dspring.ai.mcp.client.sse.connections.weather-server.url=http://localhost:8080 \
 -Dlogging.pattern.console= \
 -Dai.user.input='What is the weather in NY?' \
 -jar mcp-starter-default-client-0.0.1-SNAPSHOT.jar

其他资源

• Spring AI 文档
• MCP 服务 Boot Starter
• MCP 客户端 Boot Starter
• 模型上下文协议规范
• Spring Boot 自动配置