Weather MCP Server

A Model Context Protocol (MCP) server for weather data using Spring AI.

🚀 Quick Start

# Build the JAR file first
./mvnw clean package

# Start the MCP server
docker-compose up

# The server will be available at:
# - HTTP: http://localhost:8080
# - MCP Endpoint: http://localhost:8080/sse
# - Health: http://localhost:8080/actuator/health

🔌 Cursor Integration

Add to your `~/.cursor/mcp.json`:

{
  "mcpServers": {
    "weather": {
      "command": "/weather/start-mcp-server.sh"
    }
  }
}

🛠️ Available Tools

• `getWeatherForecastByLocation(latitude, longitude)` - Get weather forecast
• `getAlerts(state)` - Get weather alerts for US states

🐳 Docker Commands

# Build the JAR (required before running docker-compose)
./mvnw clean package

# Start in background
docker-compose up -d

# View logs
docker-compose logs -f

# Stop
docker-compose down

# Rebuild and start
./mvnw clean package && docker-compose up --build

🧑‍💻 Development

Prerequisites

• Java 21 (e.g. OpenJDK 21 or Temurin 21)
• Maven 3.9+
• Docker & Docker Compose

Build Locally

# Compile & run unit tests
./mvnw clean verify

# Build the runnable JAR (output in target/)
./mvnw clean package

Run Locally

# Run with the JVM directly
java -jar target/weather-0.0.1-SNAPSHOT.jar

# Or use Spring Boot devtools for hot-reload
./mvnw spring-boot:run

# Or run with Docker Compose
./mvnw clean package && docker-compose up

The server starts on `http://localhost:8080` by default.

Environment Variables

Variables can be defined in `src/main/resources/application.yml`, overridden via `-D` flags, or exported in your shell.

📡 API Reference

This project exposes two flavours of API:

1. MCP Tool Endpoints – consumed by supporting IDEs (e.g. Cursor).

2. REST Endpoints – ordinary HTTP endpoints that you can call with `curl`, Postman, etc.

MCP Tools

REST Endpoints

_Note: the REST layer simply proxies to the same service methods backing the MCP tools._