使用说明

MCP气象服务器

一个基于Spring Boot的模型上下文协议（MCP）服务器，提供来自美国国家气象局（NWS）API的天气信息。此服务器公开了MCP客户端可以使用的天气工具，还提供了用于直接HTTP访问的REST端点。

特性

MCP工具（共8个）

GetCurrentWeather -按纬度/经度获取当前天气
GetWeatherForecast -按纬度/经度获取扩展预报
GetWeatherAlerts -按纬度/经度获取活动天气警报
GetLocationInfo -从坐标中获取位置详细信息
GetCurrentWeatherByCity -按城市名称获取当前天气
按城市获取天气预报 -按城市名称获取扩展预测
GetWeatherAlertsByCity -按城市名称获取活动警报
获取城市坐标 -获取城市名称的坐标

REST端点

GET /weather/{city} -一个城市的当前天气
GET /weather/{city}/forecast -一个城市的5天天气预报
GET /cities -支持城市列表

数据源

国家气象局（NWS） -主要气象数据源
Open-Meteo地理编码API -城市名称到坐标转换

先决条件

Java 17或更高版本
无需安装Maven（使用Maven Wrapper）

建筑

# Clone the repository
git clone <repository-url>
cd mcp-weather-server

# Make Maven Wrapper executable (Unix/macOS)
chmod +x ./mvnw

# Clean and compile
./mvnw clean compile

# Build the JAR file
./mvnw clean package

跑步

发展模式

./mvnw spring-boot:run

生产模式

java -jar target/mcp-weather-server-1.0.0-SNAPSHOT.jar

服务器将在端口上启动 8085 默认情况下。

测试

测试REST端点

获取支持的城市：

curl http://localhost:8085/cities

获取一个城市的当前天气：

curl http://localhost:8085/weather/Chicago

获取一个城市的天气预报：

curl http://localhost:8085/weather/Chicago/forecast

测试错误处理（无效城市）：

curl http://localhost:8085/weather/InvalidCity

运行单元测试

# Run all tests
./mvnw test

# Run tests with coverage
./mvnw test jacoco:report

# Run specific test class
./mvnw test -Dtest=WeatherControllerTest

测试MCP集成

MCP服务器通过服务器发送事件公开工具 /mcp/messages。您可以将MCP客户端连接到：

http://localhost:8085/mcp/messages

示例响应

当前天气：

{
  "location": "41.8781, -87.6298",
  "name": "Tonight",
  "temperature": "32°F",
  "windSpeed": "5 mph",
  "windDirection": "NW",
  "shortForecast": "Partly Cloudy",
  "detailedForecast": "Partly cloudy, with a low around 32..."
}

支持城市：

[
  "New York", "Los Angeles", "Chicago", "Houston", "Phoenix",
  "Philadelphia", "San Antonio", "San Diego", "Dallas", "San Jose",
  "Austin", "Jacksonville", "Fort Worth", "Columbus", "Charlotte",
  "Seattle", "Denver", "Boston", "Nashville", "Baltimore"
]

配置

该应用程序可以通过以下方式配置 src/main/resources/application.yaml:

spring:
  application:
    name: weather-mcp-server
  ai:
    mcp:
      server:
        name: weather-mcp-server
        stdio: false
        version: 1.0.0
        type: ASYNC
        sse-message-endpoint: /mcp/messages

server:
  port: 8085

logging:
  level:
    com.godaddy.examples.mcp.weather: DEBUG
    org.springframework.ai: DEBUG

建筑

弹簧靴3.2.0 -应用框架
Spring AI MCP服务器 -MCP协议实现
RestTemplate -用于外部API的HTTP客户端
龙目 -用于减少样板的代码生成
春季重试 -API调用的重试机制
自定义异常处理 -带有正确HTTP状态代码的结构化错误响应

错误处理

该服务器包括具有自定义功能的全面错误处理 WeatherServerException:

自定义例外功能：

结构化错误代码 -具体错误识别
操作上下文 -知道哪个操作失败了
正确的HTTP状态映射 -RESTful错误响应
增强日志记录 -带完整上下文的格式化错误消息

错误代码：

错误代码	状态码	描述
`CITY_NOT_FOUND`	404找不到	在地理编码API中找不到城市
`GEOCODING_ERROR`	502网关错误	无法对城市名称进行地理编码
`NWS_GRID_ERROR`	502网关错误	获取NWS网格点失败
`NWS_FORECAST_ERROR`	502网关错误	获取NWS预测数据失败
`NWS_LOCATION_ERROR`	502网关错误	无法获取NWS位置信息
`NO_WEATHER_DATA`	500内部服务器错误	没有可用的天气时段
`WEATHER_FETCH_ERROR`	500内部服务器错误	常规天气数据获取失败
`CITY_WEATHER_ERROR`	500内部服务器错误	获取城市天气失败
`COORDINATES_ERROR`	500内部服务器错误	常规坐标查找失败

错误响应格式：

{
  "error": true,
  "message": "City not found: InvalidCity",
  "errorCode": "CITY_NOT_FOUND",
  "operation": "getCityCoordinates",
  "timestamp": 1640995200000
}

错误处理优势：

更好的调试 -清晰的错误识别和上下文
客户友好 -具有有意义HTTP状态代码的结构化JSON响应
综合录井 -带有操作上下文的全栈跟踪
一致格式 -所有错误都遵循相同的响应结构

发展

项目结构

src/
├── main/
│   ├── java/com/godaddy/examples/mcp/weather/
│   │   ├── WeatherMcpApplication.java      # Main application class
│   │   ├── controllers/
│   │   │   └── WeatherController.java     # REST endpoints
│   │   └── services/
│   │       └── WeatherService.java        # Business logic & MCP tools
│   └── resources/
│       └── application.yaml               # Configuration
└── target/                                # Build output

添加新工具

添加新方法 WeatherService.java
用注释 @Tool(name="ToolName", description="Description")
该工具将由Spring AI自动注册

扩展功能

通过扩展添加新的天气数据源 WeatherService
在中添加新的REST端点 WeatherController
在中修改城市列表 WeatherService.getSupportedCities()

许可证

该项目是一个用于教育目的的示例实施。

支持

对于问题或疑问，请查看应用程序日志，其中包括天气操作和Spring AI MCP服务器活动的详细调试信息。