Weather Bridge MCP

Weather Bridge MCP

一个基于 Spring Boot 的 模型上下文协议（MCP）服务，可将 OpenWeatherMap 的实时天气数据提供给 AI Agent。将其连接到 Claude Desktop 或 Claude Code，即可用日常语言询问天气问题，Agent 会自动调用合适的工具。

"What's the weather in Tokyo?" → getCurrentWeather("Tokyo") → 18°C, partly cloudy
"3-day forecast for Berlin?"   → getForecast("Berlin", 3)  → Mon 12°C, Tue 10°C, Wed 14°C

---

架构

graph TB
    subgraph dev["Developer Environment"]
        U(["👤 Developer"])
        CL["Claude Desktop\n/ Claude Code"]
        MC["MCP Client"]
        U -->|natural language| CL
        CL <--> MC
    end

    subgraph server["Weather Bridge MCP  —  Spring Boot :8080"]
        direction TB
        SSE["SSE Transport\n/sse"]
        SRV["MCP Server\n(auto-configured)"]
        TP["WeatherService\n@Tool methods"]
        RT["RestTemplate"]
        SSE --> SRV --> TP --> RT
    end

    OWM[("☁️ OpenWeatherMap\nREST API")]

    MC  -->|"SSE connection"| SSE
    RT  -->|"HTTPS"| OWM

---

MCP 工具

工具	描述	参数
getCurrentWeather	查询某个城市的当前天气状况	city — 例如 "London"
getForecast	查询多日天气预报	city、days（1–5）

这两个工具都会返回易于阅读的摘要，供 AI 模型据此组织回复。

---

快速开始

使用 Docker（无需安装 Java）：

git clone https://github.com/mm-camelcase/weather-bridge-mcp.git
cd weather-bridge-mcp
cp .env.example .env           # add your OPENWEATHERMAP_API_KEY
docker-compose up

连接 Claude Desktop — 将以下内容添加到 ~/Library/Application Support/Claude/claude_desktop_config.json：

{
  "mcpServers": {
    "weather-bridge": {
      "type": "sse",
      "url": "http://localhost:8080/sse"
    }
  }
}

重启 Claude Desktop 并询问：“纽约的天气怎么样？”

有关 Claude Code（CLI）的配置说明，请参阅 claude-config/README.md。

---

开始使用（不使用 Docker）

前置条件

• Java 21+
• Maven 3.9+
• 免费的 OpenWeatherMap API 密钥

配置

cp .env.example .env
# edit .env — set OPENWEATHERMAP_API_KEY=your_key_here
export $(cat .env | xargs)

或者直接设置该属性：

mvn spring-boot:run -Dopenweathermap.api-key=your_key_here

运行

mvn spring-boot:run

验证服务是否已启动：

curl http://localhost:8080/weather/health
# → {"status":"UP","service":"weather-bridge-mcp"}

手动测试工具（无需 MCP 客户端）：

curl "http://localhost:8080/weather/current/London"
curl "http://localhost:8080/weather/forecast/Paris?days=3"

---

工作原理

请求流程

sequenceDiagram
    actor Dev as 👤 Developer
    participant Claude as Claude Desktop
    participant Client as MCP Client
    participant Server as Weather Bridge MCP
    participant API as OpenWeatherMap

    Dev->>Claude: "What's the weather in Tokyo?"
    Claude->>Client: tool call: getCurrentWeather("Tokyo")
    Client->>Server: SSE POST /mcp/message
    Server->>API: GET /weather?q=Tokyo&units=metric
    API-->>Server: JSON payload
    Server-->>Client: formatted weather summary
    Client-->>Claude: tool result
    Claude-->>Dev: "Tokyo is 18°C, partly cloudy with light winds..."

应用组件

graph LR
    subgraph app["Spring Boot Application"]
        direction TB
        MAIN["WeatherBridgeMcpApplication\n@SpringBootApplication"]
        TCP["ToolCallbackProvider\nMethodToolCallbackProvider"]
        WS["WeatherService\n@Tool getCurrentWeather\n@Tool getForecast"]
        WC["WeatherController\nREST /weather/**"]
        GEH["GlobalExceptionHandler\n@RestControllerAdvice"]
        RT["RestTemplate"]

        MAIN --> TCP
        MAIN --> RT
        TCP --> WS
        WS --> RT
        WC --> WS
    end

    subgraph infra["Auto-configured by spring-ai-starter-mcp-server-webmvc"]
        SSE["SSE Transport\n/sse"]
        MCPSRV["MCP Server"]
        SSE --> MCPSRV --> TCP
    end

    RT --> OWM[("☁️ OpenWeatherMap")]

数据模型

classDiagram
    class WeatherData {
        +String name
        +List~WeatherCondition~ weather
        +MainData main
        +Wind wind
        +Clouds clouds
        +Sys sys
        +Integer visibility
    }
    class MainData {
        +double temp
        +double feelsLike
        +double tempMin
        +double tempMax
        +int humidity
        +int pressure
    }
    class ForecastData {
        +List~ForecastItem~ list
        +City city
    }
    class ForecastItem {
        +MainData main
        +List~WeatherCondition~ weather
        +Wind wind
        +String dtTxt
    }

    WeatherData "1" --> "1" MainData
    WeatherData "1" --> "0..*" WeatherCondition
    ForecastData "1" --> "1..*" ForecastItem
    ForecastItem "1" --> "1" MainData

---

项目结构

weather-bridge-mcp/
├── src/main/java/com/example/weatherbridgemcp/
│   ├── WeatherBridgeMcpApplication.java   # Entry point + bean definitions
│   ├── service/
│   │   └── WeatherService.java            # @Tool methods + OpenWeatherMap client
│   ├── model/
│   │   ├── WeatherData.java               # Current weather response model
│   │   └── ForecastData.java              # Forecast response model
│   ├── controller/
│   │   └── WeatherController.java         # REST endpoints for manual testing
│   └── exception/
│       ├── WeatherServiceException.java
│       └── GlobalExceptionHandler.java
├── src/main/resources/
│   ├── application.properties             # Server + MCP + API configuration
│   └── application-dev.properties         # Debug logging profile
├── src/test/                              # Unit tests (MockRestServiceServer)
├── claude-config/                         # Claude Desktop / Claude Code setup
├── Dockerfile                             # Multi-stage build
├── docker-compose.yml
└── .github/workflows/ci.yml               # GitHub Actions

---

开发

# Run tests (no API key needed — uses MockRestServiceServer)
mvn test

# Build a fat JAR
mvn clean package -DskipTests

# Run with debug logging
mvn spring-boot:run -Dspring.profiles.active=dev

---

环境变量

变量	必填	描述
OPENWEATHERMAP_API_KEY	是	openweathermap.org 提供的 API 密钥

---

资源

• 模型上下文协议（MCP）文档
• Spring AI MCP 服务参考
• OpenWeatherMap API 文档
• Claude Desktop MCP 指南

---

许可证

MIT © 2025 mm-camelcase