Weather MCP

Servidor Weather MCP

Um servidor Model Context Protocol (MCP) para dados meteorológicos usando Spring AI.

🚀 Início Rápido

# 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

🔌 Integração com Cursor

Adicione ao seu ~/.cursor/mcp.json:

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

🛠️ Ferramentas Disponíveis

• getWeatherForecastByLocation(latitude, longitude) - Obter previsão do tempo
• getAlerts(state) - Obter alertas meteorológicos para estados dos EUA

🐳 Comandos Docker

# 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

🧑💻 Desenvolvimento

Pré-requisitos

• Java 21 (ex.: OpenJDK 21 ou Temurin 21)
• Maven 3.9+
• Docker e Docker Compose

Compilar Localmente

# Compile & run unit tests
./mvnw clean verify

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

Executar Localmente

# 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

O servidor inicia em http://localhost:8080 por padrão.

Variáveis de Ambiente

Nome	Padrão	Descrição
SERVER_PORT	8080	Porta HTTP para vinculação
SPRING_AI_MCP_SERVER_STDIO	false	Executar o servidor MCP via stdio (útil para integrações com editores)
SPRING_PROFILES_ACTIVE	(nenhum)	Lista separada por vírgulas de perfis Spring

As variáveis podem ser definidas em src/main/resources/application.yml, sobrescritas via flags -D ou exportadas no seu shell.

---

📡 Referência da API

Este projeto expõe duas variações de API:

1. Endpoints de Ferramentas MCP – consumidos por IDEs compatíveis (ex.: Cursor).
2. Endpoints REST – endpoints HTTP comuns que você pode chamar com curl, Postman, etc.

Ferramentas MCP

Ferramenta	Assinatura	Descrição
getWeatherForecastByLocation	(latitude: number, longitude: number)	Retorna uma previsão legível de vários dias para as coordenadas fornecidas.
getAlerts	(state: string)	Retorna alertas ativos para o estado dos EUA fornecido (código de duas letras).

Endpoints REST

Método	Caminho	Exemplo
GET	/forecast?lat={lat}&lon={lon}	/forecast?lat=37.7749&lon=-122.4194
GET	/alerts/{state}	/alerts/CA

Nota: a camada REST simplesmente faz proxy para os mesmos métodos de serviço que sustentam as ferramentas MCP.