Spring AI MCP Weather STDIO Server

Spring AI MCP Weather STDIO Server

一个 Spring Boot 启动项目，演示如何构建使用 National Weather Service（weather.gov）API 提供天气相关工具的 Model Context Protocol（MCP）服务。本项目展示了 Spring AI MCP Server Boot Starter 的功能，以及 STDIO 传输实现。

更多信息请参阅 MCP Server Boot Starter 参考文档。

前置条件

• Java 17 或更高版本
• Maven 3.6 或更高版本
• 了解 Spring Boot 和 Spring AI 概念
• （可选）用于集成 AI 助手的 Claude Desktop

关于 Spring AI MCP Server Boot Starter

spring-ai-mcp-server-spring-boot-starter 提供：

• MCP 服务组件的自动配置
• 同步和异步运行模式支持
• STDIO 传输层实现
• 通过 Spring Bean 灵活注册工具
• 变更通知功能

项目结构

关于 Spring AI MCP Server Boot Starter

spring-ai-mcp-server-spring-boot-starter 提供：

• MCP 服务组件的自动配置
• 同步和异步运行模式支持
• STDIO 传输层实现
• 通过 Spring Bean 灵活注册工具
• 变更通知功能

项目结构

src/
├── main/
│   ├── java/
│   │   └── org/springframework/ai/mcp/sample/server/
│   │       ├── McpServerApplication.java    # Main application class with tool registration
│   │       └── WeatherService.java          # Weather service implementation with MCP tools
│   └── resources/
│       └── application.properties           # Server and transport configuration
└── test/
    └── java/
        └── org/springframework/ai/mcp/sample/client/
            └── ClientStdio.java             # Test client implementation

构建和运行

服务使用 STDIO 传输模式，通常由客户端自动启动。要构建服务 JAR：

./mvnw clean install -DskipTests

工具实现

本项目演示如何使用 Spring 的依赖注入和自动配置来实现并注册 MCP 工具：

@Service
public class WeatherService {
    @Tool(description = "Get weather forecast for a specific latitude/longitude")
    public String getWeatherForecastBrazil(
        double latitude,   // Latitude coordinate
        double longitude   // Longitude coordinate
    ) {
        // Implementation
    }

    @Tool(description = "Get weather alerts for a US state")
    public String getAlerts(
        String state  // Two-letter US state code (e.g., CA, NY)
    ) {
        // Implementation
    }
}

@SpringBootApplication
public class McpServerApplication {
    @Bean
    public List<ToolCallback> weatherTools(WeatherService weatherService) {
        return ToolCallbacks.from(weatherService);
    }
}

自动配置会自动将这些工具注册到 MCP 服务。你可以有多个 Bean 生成 ToolCallbacks 列表，自动配置会将它们合并。

可用工具

1. 天气预报工具

@Tool(description = "Get weather forecast for a specific latitude/longitude")
public String getWeatherForecastBrazil(
    double latitude,   // Latitude coordinate
    double longitude   // Longitude coordinate
) {
    // Returns detailed forecast including:
    // - Temperature and unit
    // - Wind speed and direction
    // - Detailed forecast description
}

// Example usage:
CallToolResult forecast = client.callTool(
    new CallToolRequest("getWeatherForecastBrazil",
        Map.of(
            "latitude", 47.6062,    // Seattle coordinates
            "longitude", -122.3321
        )
    )
);

2. 天气警报工具

@Tool(description = "Get weather alerts for a US state")
public String getAlerts(
    String state  // Two-letter US state code (e.g., CA, NY)
) {
    // Returns active alerts including:
    // - Event type
    // - Affected area
    // - Severity
    // - Description
    // - Safety instructions
}

// Example usage:
CallToolResult alerts = client.callTool(
    new CallToolRequest("getAlerts",
        Map.of("state", "NY")
    )
);

客户端集成

Java 客户端示例

手动创建 MCP 客户端

// Create server parameters
ServerParameters stdioParams = ServerParameters.builder("java")
    .args("-Dspring.ai.mcp.server.transport=STDIO",
          "-Dspring.main.web-application-type=none",
          "-Dlogging.pattern.console=",
          "-jar",
          "target/my-mcp-stdio-server-0.0.1-SNAPSHOT.jar")
    .build();

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

ClientStdio.java 演示了如何手动实现 MCP 客户端。

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

使用 MCP Client Boot Starter

使用 starter-default-client 连接天气 starter-stdio-server：

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

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

java -Dspring.ai.mcp.client.stdio.connections.server1.command=java \
     -Dspring.ai.mcp.client.stdio.connections.server1.args=-jar,/Users/christiantzolov/Dev/projects/spring-ai-examples/model-context-protocol/weather/starter-stdio-server/target/my-mcp-stdio-server-0.0.1-SNAPSHOT.jar \
     -Dai.user.input='What is the weather in NY?' \
     -Dlogging.pattern.console= \
     -jar mcp-starter-default-client-0.0.1-SNAPSHOT.jar

Claude Desktop 集成

要集成 Claude Desktop，请将以下配置添加到 Claude Desktop 设置中：

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

将 /absolute/path/to/ 替换为已构建 JAR 文件的实际路径。

配置

应用属性

所有属性均以 spring.ai.mcp.server 为前缀：

# Required STDIO Configuration
spring.main.web-application-type=none
spring.main.banner-mode=off
logging.pattern.console=

# Server Configuration
spring.ai.mcp.server.enabled=true
spring.ai.mcp.server.name=my-weather-server
spring.ai.mcp.server.version=0.0.1
# SYNC or ASYNC
spring.ai.mcp.server.type=SYNC
spring.ai.mcp.server.resource-change-notification=true
spring.ai.mcp.server.tool-change-notification=true
spring.ai.mcp.server.prompt-change-notification=true

# Optional file logging
logging.file.name=my-mcp-stdio-server.log

关键配置说明

1. STDIO 模式要求

   • 禁用 Web 应用类型（spring.main.web-application-type=none）
   • 禁用 Spring 横幅（spring.main.banner-mode=off）
   • 清空控制台日志模式（logging.pattern.console=）

2. 服务类型

   • SYNC（默认）：使用 McpSyncServer 实现简洁的请求-响应模式
   • ASYNC：使用 McpAsyncServer 实现非阻塞操作，并支持 Project Reactor

附加资源

• Spring AI 文档
• MCP 服务 Boot Starter
• MCP 客户端 Boot Starter
• Model Context Protocol 规范
• Spring Boot 自动配置