Weather

Fornece alertas meteorológicos e previsões usando a API do Serviço Nacional de Meteorologia.

GitHub
1

Documentação

Model Context Protocol (MCP)

🚀 Por que todos – de repente! – estão obcecados com MCP/Servidores? (Spoiler: está redefinindo a orquestração de IA)

O Model Context Protocol (MCP) é um padrão aberto desenvolvido pela Anthropic no final de 2024 para resolver um desafio crítico na integração de IA: conectar assistentes de IA a fontes de dados e sistemas do mundo real[1][3]. O MCP serve como uma interface padronizada para modelos de IA interagirem com ferramentas externas, bancos de dados e APIs, de forma semelhante a como o USB-C funciona como uma porta universal para dispositivos[4][7].

Principais Recursos e Benefícios

  1. Integração Padronizada: O MCP elimina a necessidade de integrações personalizadas, permitindo que desenvolvedores conectem modelos de IA a várias fontes de dados usando um único protocolo.

  2. Descoberta Dinâmica: Agentes de IA podem detectar e utilizar automaticamente servidores MCP disponíveis e suas capacidades sem integração codificada.

  3. Segurança Aprimorada: O MCP permite que desenvolvedores implementem medidas de segurança dentro dos servidores, garantindo que agentes de IA acessem apenas dados ou ações permitidas.

  4. Flexibilidade: O protocolo é agnóstico em relação ao modelo, permitindo que qualquer modelo de IA (por exemplo, Claude, GPT-4, LLMs de código aberto) use ferramentas habilitadas para MCP.

  5. Crescimento do Ecossistema: Desde sua introdução, o MCP ganhou tração significativa, com mais de 1.000 servidores MCP construídos pela comunidade disponíveis até fevereiro de 2025.

Impacto no Desenvolvimento de IA

O MCP está transformando o cenário da IA ao:

  1. Simplificar a Integração: Reduzir a complexidade de conectar modelos de IA a sistemas externos de um problema "N×M" para um problema "N+M".

  2. Habilitar Fluxos de Trabalho Complexos: Facilitar operações de múltiplas etapas e entre sistemas para agentes de IA, como planejamento de eventos que envolvem várias plataformas.

  3. Fomentar a Colaboração: Fornecer um espaço de trabalho compartilhado para sistemas multiagente, permitindo que agentes de IA especializados coordenem tarefas de forma eficiente.

  4. Aprimorar a Personalização: Permitir a integração segura de assistentes pessoais de IA com os dados e aplicativos dos usuários.

  5. Melhorar a Governança Empresarial: Padronizar o acesso de IA a ferramentas internas e permitir melhor monitoramento e controle das interações de IA.

Em março de 2025, o MCP se tornou um tópico significativo na comunidade de IA, com muitos o vendo como um componente crucial para o desenvolvimento de sistemas de IA mais integrados e conscientes do contexto. Sua natureza aberta e o apoio de um grande player de IA contribuíram para sua rápida adoção e evolução, posicionando o MCP como um potencial padrão de facto para a integração no mundo da IA.

Model Context Protocol (MCP) - início rápido do clima:

Visão Geral

Este documento fornece um guia abrangente para construir um servidor de clima MCP (Model Context Protocol) simples e conectá-lo a um host, o Claude for Desktop. O servidor expõe duas ferramentas: get-alerts e get-forecast, que buscam alertas meteorológicos e previsões usando a API do Serviço Meteorológico Nacional dos EUA.

Sumário

  1. Introdução
  2. Pré-requisitos
  3. Requisitos do Sistema
  4. Configuração
  5. Construindo o Servidor
  6. Testando com Claude for Desktop
  7. Por Dentro do Funcionamento
  8. Solução de Problemas

Introdução

Este guia orienta você na criação de um servidor MCP para aprimorar LLMs (como o Claude) com dados meteorológicos em tempo real. O servidor utiliza a estrutura MCP para expor ferramentas para buscar alertas meteorológicos e previsões, abordando a falta de consciência ambiental nativa dos LLMs.

Pré-requisitos

Antes de começar, certifique-se de ter:

  • Familiaridade com Python
  • Compreensão de LLMs como o Claude

Requisitos do Sistema

  • Python 3.10 ou superior
  • MCP SDK 1.2.0 ou superior

Configuração

  1. Instale uv:

    Windows

    powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

    macOS/Linux

    curl -LsSf https://astral.sh/uv/install.sh | sh

    Reinicie seu terminal para garantir que o comando uv seja reconhecido.

  2. Crie e Configure o Projeto:

    Windows (cd para o diretório do seu repositório, execute o comando abaixo no PowerShell/..)

    # Create a new directory for our project
  uv init weather
  cd weather

  # Create virtual environment and activate it
  uv venv
  .venv\Scripts\activate

  # Install dependencies
  uv add mcp[cli] httpx

  # Create our server file
  new-item weather.py

    macOS/Linux

    # Create a new directory for our project
uv init weather
cd weather

# Create virtual environment and activate it
uv venv
source .venv/bin/activate

# Install dependencies
uv add "mcp[cli]" httpx

# Create our server file
touch weather.py

Construindo o Servidor

Importando Pacotes e Configurando a Instância

Adicione o seguinte código ao topo do seu arquivo weather.py:

from typing import Any
import httpx
from mcp.server.fastmcp import FastMCP


# Initialize FastMCP server
mcp = FastMCP("weather")

# Constants
NWS_API_BASE = "https://api.weather.gov"
USER_AGENT = "weather-app/1.0"


#helper function
async def make_nws_request(url: str) -> dict[str, Any] | None:
    """Make a request to the NWS API with proper error handling."""
    headers = {
        "User-Agent": USER_AGENT,
        "Accept": "application/geo+json"
    }
    async with httpx.AsyncClient() as client:
        try:
            response = await client.get(url, headers=headers, timeout=30.0)
            response.raise_for_status()
            return response.json()
        except Exception:
            return None

def format_alert(feature: dict) -> str:
    """Format an alert feature into a readable string."""
    props = feature["properties"]
    return f"""
Event: {props.get('event', 'Unknown')}
Area: {props.get('areaDesc', 'Unknown')}
Severity: {props.get('severity', 'Unknown')}
Description: {props.get('description', 'No description available')}
Instructions: {props.get('instruction', 'No specific instructions provided')}
"""


@mcp.tool()
async def get_alerts(state: str) -> str:
    """Get weather alerts for a US state.

    Args:
        state: Two-letter US state code (e.g. CA, NY)
    """
    url = f"{NWS_API_BASE}/alerts/active/area/{state}"
    data = await make_nws_request(url)

    if not data or "features" not in data:
        return "Unable to fetch alerts or no alerts found."

    if not data["features"]:
        return "No active alerts for this state."

    alerts = [format_alert(feature) for feature in data["features"]]
    return "\n---\n".join(alerts)

@mcp.tool()
async def get_forecast(latitude: float, longitude: float) -> str:
    """Get weather forecast for a location.

    Args:
        latitude: Latitude of the location
        longitude: Longitude of the location
    """
    # First get the forecast grid endpoint
    points_url = f"{NWS_API_BASE}/points/{latitude},{longitude}"
    points_data = await make_nws_request(points_url)

    if not points_data:
        return "Unable to fetch forecast data for this location."

    # Get the forecast URL from the points response
    forecast_url = points_data["properties"]["forecast"]
    forecast_data = await make_nws_request(forecast_url)

    if not forecast_data:
        return "Unable to fetch detailed forecast."

    # Format the periods into a readable forecast
    periods = forecast_data["properties"]["periods"]
    forecasts = []
    for period in periods[:5]:  # Only show next 5 periods
        forecast = f"""
                    {period['name']}:
                    Temperature: {period['temperature']}°{period['temperatureUnit']}
                    Wind: {period['windSpeed']} {period['windDirection']}
                    Forecast: {period['detailedForecast']}
                    """
        forecasts.append(forecast)

    return "\n---\n".join(forecasts)


if __name__ == "__main__":
    # Initialize and run the server
    mcp.run(transport='stdio')

Executando o Servidor

Para verificar seu servidor, execute:

uv run weather.py

Testando Seu Servidor com Claude for Desktop

Configuração

  1. Instale/Atualize o Claude for Desktop: Certifique-se de ter a versão mais recente instalada.
  2. Configure os Servidores MCP: Abra ou crie o arquivo de configuração em ~/Library/Application Support/Claude/claude_desktop_config.json.

alt text

-> REINICIE O SISTEMA SE NÃO FUNCIONAR

  1. Adicione a Configuração do Servidor:

    {
  "mcpServers": {
    "weather": {
      "command": "uv",
      "args": [
        "--directory",
        "/ABSOLUTE/PATH/TO/PARENT/FOLDER/weather",# S:\\Dev\\weather
        "run",
        "weather.py"
      ]
    }
  }
}

    Substitua /ABSOLUTE/PATH/TO/PARENT/FOLDER/weather pelo caminho absoluto correto para o diretório do seu projeto. Talvez seja necessário fornecer o caminho completo para o executável uv no campo command (use which uv no MacOS/Linux ou where uv no Windows para encontrá-lo).

  2. Reinicie o Claude for Desktop.

Teste com Comandos

  1. Verifique a Detecção de Ferramentas: Procure o ícone de martelo no Claude for Desktop. Clicar nele deve listar as ferramentas get_alerts e get_forecast.

alt text 2. Execute Consultas de Teste:

- "Qual é o clima em Sacramento?"
- "Quais são os alertas meteorológicos ativos no Texas?"

Observação: Essas consultas funcionam apenas para locais nos EUA, pois usam o Serviço Meteorológico Nacional dos EUA.

O Que Acontece por Dentro

  1. O cliente envia sua pergunta para o Claude.
  2. O Claude analisa as ferramentas disponíveis e decide quais usar.
  3. O cliente executa a(s) ferramenta(s) escolhida(s) por meio do servidor MCP.
  4. Os resultados são enviados de volta para o Claude.
  5. O Claude formula e exibe uma resposta em linguagem natural.

Solução de Problemas

  • Obtendo logs do Claude for Desktop

    • mcp.log: Conexões MCP gerais e falhas.
    • mcp-server-SERVERNAME.log: Logs de erros do servidor nomeado.
    tail -n 20 -f ~/Library/Logs/Claude/mcp*.log

  • Servidor não aparecendo no Claude

    • Verifique a sintaxe do arquivo claude_desktop_config.json.
    • Certifique-se de que o caminho do projeto seja absoluto.
    • Reinicie completamente o Claude for Desktop.

  • Chamadas de ferramentas falhando silenciosamente

    • Verifique os logs do Claude para erros.
    • Verifique se seu servidor compila e executa sem erros.
    • Tente reiniciar o Claude for Desktop.

  • Nada disso está funcionando. O que eu faço?

  • Erro: Falha ao recuperar dados do ponto de grade

    • Coordenadas fora dos EUA
    • Problemas com a API do NWS
    • Limitação de taxa

    Correção:

  • Erro: Nenhum alerta ativo para [ESTADO]

    • Não há alertas meteorológicos atuais para esse estado. Tente um estado diferente.

Para solução de problemas mais avançada, consulte o guia de depuração do MCP.

MCP Inspector

npx @modelcontextprotocol/inspector uv run weather.py

alt text

alt text

concluído com teste local

Publicado no Github

🔗 Github - aitiwari/weather