Weather MCP

Servidor Weather MCP

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

🚀 Início Rápido

Compile o arquivo JAR primeiro

./mvnw clean package

Inicie o servidor MCP

docker-compose up

O servidor estará disponível em:

- HTTP: http://localhost:8080

- Endpoint MCP: 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

Compile o JAR (necessário antes de executar docker-compose)

./mvnw clean package

Inicie em segundo plano

docker-compose up -d

Veja os logs

docker-compose logs -f

Pare

docker-compose down

Recompile e inicie

./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 e execute testes unitários

./mvnw clean verify

Compile o JAR executável (saída em target/)

./mvnw clean package

Executar Localmente

Execute diretamente com a JVM

java -jar target/weather-0.0.1-SNAPSHOT.jar

Ou use o Spring Boot devtools para hot-reload

./mvnw spring-boot:run

Ou execute com 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	Executa 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 dois tipos 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.

---