# Weather MCP Server

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

## 🚀 Quick Start

```bash
# 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`:

```json
{
  "mcpServers": {
    "weather": {
      "command": "<ABSOLUTE_PATH_OF_REPO_ON_LOCAL_MACHINE>/weather/start-mcp-server.sh"
    }
  }
}
```

## 🛠️ Available Tools

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

## 🐳 Docker Commands

```bash
# 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

```bash
# Compile & run unit tests
./mvnw clean verify

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

### Run Locally

```bash
# 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

| Name | Default | Description |
|------|---------|-------------|
| `SERVER_PORT` | `8080` | HTTP port to bind |
| `SPRING_AI_MCP_SERVER_STDIO` | `false` | Run the MCP server over stdio (useful for editor integrations) |
| `SPRING_PROFILES_ACTIVE` | *(none)* | Comma-separated list of Spring profiles |

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

| Tool | Signature | Description |
|------|-----------|-------------|
| `getWeatherForecastByLocation` | `(latitude: number, longitude: number)` | Returns a human-readable multi-day forecast for the supplied co-ordinates. |
| `getAlerts` | `(state: string)` | Returns active alerts for the supplied US state (two-letter code). |

### REST Endpoints

| Method | Path | Example |
|--------|------|---------|
| GET | `/forecast?lat={lat}&lon={lon}` | `/forecast?lat=37.7749&lon=-122.4194` |
| GET | `/alerts/{state}` | `/alerts/CA` |

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

---