🌤️ MCP Server — Clima/Tempo (Java 17 + Spring Boot 3 + Spring AI)

Servidor MCP (Model Context Protocol) em Java 17 / Spring Boot 3, com transporte HTTP. Expõe tools de clima/tempo e, para compatibilidade com ChatGPT MCP, inclui ações search e fetch.

Recomendo a leitura do Conceitos.md antes de seguir para os próximos passos.

Compatibilidade de transporte

• Spring AI 1.0.2 → HTTP + SSE (spec 2024-11-05)
• Spring AI 1.1.x (preview) → Streamable HTTP (spec 2025-03-26 / 2025-06-18)

---

✨ Funcionalidades

• Protocolo MCP com negociação de versão

• Transporte HTTP/SSE (1.0.2) ou Streamable HTTP (1.1.x)

• Tools (exemplos):

  • search e fetch (descoberta/obtenção exigidas pelo ChatGPT)
  • getWeatherForecastByLocation(lat, lon) — previsão detalhada (fonte: weather.gov, EUA)
  • getAlerts(uf) — alertas por estado dos EUA (ex.: NY, CA)

---

🚀 Pré-requisitos

• Java 17+
• Maven 3.9+
• Acesso à internet (para chamada da API Open-Meteo)

---

🛠️ Como rodar localmente

git clone https://github.com/<SEU_USUARIO>/<SEU_REPO>.git
cd <SEU_REPO>
./mvnw package -DskipTests
java -jar target/mcpweather-0.0.1-SNAPSHOT.jar

Por padrão, o servidor inicia em http://localhost:8080/mcp.

---

🧪 Testes rápidos com curl

A) Spring AI 1.0.2 (HTTP+SSE)

Terminal 1 — abra o SSE:

curl -N -H "Accept: text/event-stream" http://127.0.0.1:8080/sse

Terminal 2 — initialize (JSON-RPC):

curl -s -X POST http://127.0.0.1:8080/mcp/message \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":"1","method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"curl","version":"0.1"}}}'

Listar tools:

curl -s -X POST http://127.0.0.1:8080/mcp/message \
  -H "Content-Type: application/json" -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":"2","method":"tools/list","params":{}}'

Chamar getWeatherForecastByLocation (ex.: Seattle):

curl -s -X POST http://127.0.0.1:8080/mcp/message \
  -H "Content-Type: application/json" -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":"3","method":"tools/call","params":{"name":"getWeatherForecastByLocation","arguments":{"latitude":47.6062,"longitude":-122.3321}}}'

B) Spring AI 1.1.x (Streamable HTTP)

initialize:

curl -s -X POST http://127.0.0.1:8080/mcp \
  -H "Content-Type: application/json" -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":"1","method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"curl","version":"0.1"}}}'

Listar tools:

curl -s -X POST http://127.0.0.1:8080/mcp \
  -H "Content-Type: application/json" -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":"2","method":"tools/list","params":{}}'

---

⚙️ Configuração em Ferramentas MCP

1️⃣ ChatGPT (OpenAI MCP)

O ChatGPT não aceita localhost/IPs privados por segurança. Use HTTPS público (domínio) ou um túnel (ngrok/Cloudflare Tunnel).

Com ngrok (gratuito): Criando a conta e obtendo o token https://dashboard.ngrok.com/get-started/your-authtoken

ngrok config add-authtoken <SEU_TOKEN>
ngrok http 8080
# anote a URL https://<subdominio>.ngrok-free.app

1. Abra Settings ▸ Advanced ▸ Model Context Protocol (MCP).
2. Adicione uma nova conexão:

Configuração (SSE, Spring AI 1.0.2):

{
  "name": "mcp-server-clima-tempo",
  "transport": {
    "type": "sse",
    "url": "https://fa54c7e0ae29.ngrok-free.app/sse"
  }
}

Salve e teste.

Agora você pode enviar comandos como:

Use a ferramenta clima.getWeatherForecastByLocation com cidade New York
Obter alertas meteorológicos por estado do NY

2️⃣ Claude Desktop

1. Edite o arquivo de configuração (Menu → Preferences → MCP).

2. Inclua:

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

3️⃣ VS Code – GitHub Copilot Chat

É necessário o VS Code 1.92+ e GitHub Copilot Chat com suporte a MCP (em preview).

1. No VS Code, abra Settings (JSON) e adicione:

   "github.copilot.mcpServers": {
     "weather-mcp": {
       "transport": {
         "type": "sse",
         "url": "http://localhost:8080/mcp"
       }
     }
   }
   

2. Reinicie o VS Code.

3. No painel Copilot Chat, faça:

   @weather-mcp get_weather city="Lisbon,PT"
   

---

🧩 Estrutura do Projeto

src/
 └─ main/
    ├─ java/com/example/mcpweather/
    │    ├─ McpServerApplication.java  # bootstrap Spring Boot
    │    └─ WeatherService.java        # tool get_weather
    └─ resources/
         └─ application.yml            # configurações MCP

---

🔗 Referências Oficiais

• Model Context Protocol

  • Especificação MCP
  • Exemplos de servidores Java

• Spring AI 1.0.2

  • Starter MCP Server WebMVC
  • https://docs.spring.io/spring-ai/reference/api/mcp/mcp-server-boot-starter-docs.html
  • https://github.com/spring-projects/spring-ai/blob/main/spring-ai-spring-boot-starters

• Open-Meteo API

  • Documentação
  • https://platform.openai.com/docs/mcp#create-an-mcp-server

---

📜 Licença

MIT

---

💡 Dica

Este projeto é apenas um exemplo educativo. Em produção, proteja o endpoint /mcp (HTTPS, autenticação).