Python Weather Server

Um servidor baseado em FastAPI que fornece informações meteorológicas da API do National Weather Service, protegido com OAuth 2.1.

GitHub
27
Experimente este MCPPatrocinado

Documentação

Python Weather Server MCP com Autenticação OAuth 2.1

Um servidor Model Context Protocol (MCP) pronto para produção, construído com FastAPI, que fornece informações meteorológicas usando a API do National Weather Service. Oferece conformidade total com MCP OAuth 2.1 com PKCE, registro dinâmico de clientes e integração com Azure AD. Pronto para implantação no Azure App Service com Azure Developer CLI (azd).

🌟 Recursos

  • Conformidade com a Especificação MCP OAuth 2.1: Implementação completa da Especificação de Autorização MCP (2025-03-26)
  • PKCE Obrigatório: Autorização segura com Proof Key for Code Exchange (RFC 7636, método S256)
  • Registro Dinâmico de Clientes: Registro automático de clientes conforme RFC 7591
  • Metadados do Servidor de Autorização: Endpoint de descoberta conforme RFC 8414
  • Autorização de Terceiros: Usa Azure AD como servidor de autorização
  • Cabeçalhos do Protocolo MCP: Suporte completo para MCP-Protocol-Version: 2025-03-26
  • Gerenciamento de Tokens JWT: Autenticação segura baseada em tokens
  • Ferramentas Meteorológicas:
    • get_alerts: Obtenha alertas meteorológicos para qualquer estado dos EUA
    • get_forecast: Obtenha previsão meteorológica detalhada para qualquer local
  • Pronto para Azure: Pré-configurado para implantação no Azure App Service
  • Interface de Teste Web: Teste integrado do fluxo OAuth 2.1

🔐 Implementação de Autorização MCP

Este servidor implementa a Especificação de Autorização MCP (2025-03-26) completa:

Endpoints OAuth 2.1

  • GET /.well-known/oauth-authorization-server - Metadados do servidor de autorização (RFC 8414)
  • POST /register - Registro dinâmico de clientes (RFC 7591)
  • GET /authorize - Endpoint de autorização com PKCE (RFC 7636)
  • POST /token - Endpoint de token para troca de código e renovação
  • GET /auth/azure/callback - Callback de autorização de terceiros

Recursos do Protocolo MCP

  • ✅ Cabeçalhos de Versão do Protocolo: MCP-Protocol-Version: 2025-03-26
  • ✅ PKCE Obrigatório: Todos os clientes devem usar o método S256
  • ✅ Registro Dinâmico: Integração automática de clientes
  • ✅ Autenticação JWT: Validação de token Bearer nos endpoints MCP
  • ✅ Tratamento Adequado de Erros: Respostas 401/403/400 com detalhes
  • ✅ Integração com Azure AD: Servidor de autorização de nível empresarial

⚠️ Importante: Configuração OAuth completa necessária antes do uso. Consulte AUTH_SETUP.md para instruções de configuração do Azure AD.

💻 Desenvolvimento Local

Pré-requisitos

  • Python 3.8+
  • Conta Azure com configuração OAuth concluída (consulte AUTH_SETUP.md)

Configuração e Execução

  1. Conclua a configuração OAuth primeiro: Siga as instruções em AUTH_SETUP.md para criar seu Registro de Aplicativo Azure.

  2. Clone e instale as dependências:

    git clone <your-repo-url>
cd remote-mcp-webapp-python-auth-oauth
python -m venv venv
.\venv\Scripts\Activate.ps1  # Windows
# source venv/bin/activate   # macOS/Linux
pip install -r requirements.txt

  3. Configure as variáveis de ambiente:

    cp .env.example .env
# Edit .env with your Azure OAuth credentials from AUTH_SETUP.md

  4. Inicie o servidor de desenvolvimento:

    .\start_server.ps1  # Windows
# or manually:
uvicorn main:app --host 0.0.0.0 --port 8000 --reload

  5. Acesse o servidor:

🔌 Conecte-se ao Servidor MCP Local

Autenticação Necessária

Antes de conectar qualquer cliente MCP, você deve autenticar:

  1. Obtenha o Token JWT: Visite http://localhost:8000/mcp_oauth_test.html
  2. Conclua o Fluxo OAuth: Use a interface de teste OAuth 2.1 integrada
  3. Copie o Token JWT: Use o token na configuração do seu cliente MCP

Usando o MCP Inspector

  1. Em uma nova janela de terminal, instale e execute o MCP Inspector:

    npx @modelcontextprotocol/inspector

  2. CTRL+clique na URL exibida pelo aplicativo (ex.: http://localhost:5173/#resources)

  3. Configure a conexão autenticada:

    • Defina o tipo de transporte para HTTP
    • Defina a URL para: http://localhost:8000/
    • Adicione o cabeçalho Authorization: Bearer <your-jwt-token>

    💡 Obtendo seu token JWT: Visite http://localhost:8000/mcp_oauth_test.html para concluir o fluxo OAuth 2.1 e obter seu token JWT.

  4. Teste a conexão: Liste as ferramentas, clique em uma ferramenta e execute-a

Configuração para Clientes MCP

{
  "mcpServers": {
    "weather-mcp-server-local": {
      "transport": {
        "type": "http",
        "url": "http://localhost:8000/",
        "headers": {
          "Authorization": "Bearer <your-jwt-token>"
        }
      },
      "name": "Weather MCP Server (Local with Auth)",
      "description": "Authenticated MCP Server with weather tools"
    }
  }
}
```   > 💡 **Replace `<your-jwt-token>`** with the actual JWT token obtained from the OAuth 2.1 flow at `/mcp_oauth_test.html`.

## 🚀 Quick Deploy to Azure

### Prerequisites

- [Azure CLI](https://docs.microsoft.com/en-us/cli/azure/install-azure-cli)
- [Azure Developer CLI (azd)](https://learn.microsoft.com/en-us/azure/developer/azure-developer-cli/install-azd)
- Active Azure subscription
- **Completed OAuth setup** (see [AUTH_SETUP.md](AUTH_SETUP.md))

### Deploy in 5 Commands

```bash
# 1. Login to Azure
azd auth login

# 2. Initialize the project  
azd init

# 3. Set OAuth environment variables (from your AUTH_SETUP.md)
azd env set AZURE_CLIENT_ID "your-client-id"
azd env set AZURE_TENANT_ID "your-tenant-id"
azd env set AZURE_CLIENT_SECRET "your-client-secret"
azd env set JWT_SECRET_KEY "your-secure-jwt-secret"

# 4. Deploy to Azure (first time to get the URL)
azd up

# 5. Update environment with deployed URL and redeploy
azd env set BASE_URL "https://app-web-[unique-id].azurewebsites.net"
azd env set AZURE_REDIRECT_URI "https://app-web-[unique-id].azurewebsites.net/auth/azure/callback"
azd env set ENVIRONMENT "production"
azd up

Configuração Pós-Implantação

⚠️ Crítico: Após a implantação, você deve atualizar seu Registro de Aplicativo Azure:

  1. Anote sua URL implantada: https://app-web-[unique-id].azurewebsites.net/
  2. Vá para Azure Portal → Microsoft Entra ID → Registros de aplicativos → Seu aplicativo
  3. Clique em Autenticação → Adicione o URI de redirecionamento: https://app-web-[unique-id].azurewebsites.net/auth/azure/callback
  4. Clique em Salvar

💡 Observação: O URI de redirecionamento deve ser /auth/azure/callback (não /auth/callback) para que o fluxo MCP OAuth 2.1 funcione corretamente.

Teste Sua Implantação

Após a implantação, seu servidor MCP autenticado estará disponível em:

  • Interface de Teste OAuth 2.1: https://<your-app>.azurewebsites.net/mcp_oauth_test.html
  • Verificação de Saúde: https://<your-app>.azurewebsites.net/health
  • Recursos MCP: https://<your-app>.azurewebsites.net/mcp/capabilities
  • Documentação da API: https://<your-app>.azurewebsites.net/docs

🔌 Conecte-se ao Servidor MCP Remoto

Siga as mesmas orientações da configuração local, mas use a URL do seu Azure App Service e garanta que você tenha um token JWT válido do endpoint de autenticação implantado.

Configuração para o servidor implantado:

{
  "mcpServers": {
    "weather-mcp-server-azure": {
      "transport": {
        "type": "http", 
        "url": "https://<your-app>.azurewebsites.net/",
        "headers": {
          "Authorization": "Bearer <your-jwt-token>"
        }
      },
      "name": "Weather MCP Server (Azure with Auth)",
      "description": "Authenticated MCP Server hosted on Azure"
    }
  }
}

🧪 Testes

Teste Interativo de OAuth 2.1

A interface de teste oferece:

  1. Fluxo OAuth 2.1 Completo: Registro dinâmico de clientes → Autorização → Troca de tokens
  2. Validação PKCE: Teste o fluxo completo de Proof Key for Code Exchange
  3. Teste de Endpoints MCP: Teste as ferramentas meteorológicas autenticadas
  4. Exibição de Token JWT: Visualize e valide seus tokens de autenticação
  5. Teste de Callback do Cliente: Inclui o endpoint /client-callback para validação do fluxo OAuth

Arquitetura do Fluxo OAuth

O servidor implementa um fluxo OAuth 2.1 completo:

  • Registro do Cliente: Registro dinâmico de clientes com credenciais geradas automaticamente
  • Autorização: Usuário redirecionado para Azure AD para autenticação
  • Callback do Azure: O servidor recebe o código de autenticação do Azure em /auth/azure/callback
  • Callback do Cliente: O servidor redireciona para o callback do cliente (ex.: /client-callback) com o código de autorização
  • Troca de Token: O cliente troca o código de autorização pelo token de acesso JWT

Teste de Cliente MCP

Teste com qualquer cliente compatível com MCP usando os endpoints autenticados e seu token JWT.

🌦️ Fonte de Dados

Este servidor usa a API do National Weather Service (NWS):

  • Alertas e avisos meteorológicos em tempo real
  • Previsões meteorológicas detalhadas
  • Dados meteorológicos oficiais do governo dos EUA
  • Nenhuma chave de API necessária
  • Alta confiabilidade e precisão

🔒 Recursos de Segurança

  • ✅ Conformidade com OAuth 2.1: Implementação completa da Especificação de Autorização MCP
  • ✅ PKCE Obrigatório: Método S256 para todos os fluxos de autorização
  • ✅ Registro Dinâmico de Clientes: Integração automática e segura de clientes
  • ✅ Integração com Azure AD: Servidor de autorização de nível empresarial
  • ✅ Segurança de Token JWT: Expiração configurável e validação segura
  • ✅ Imposição de Versão do Protocolo: Validação do cabeçalho MCP-Protocol-Version
  • ✅ Registro de Solicitações: Trilha de auditoria completa com identificação do usuário
  • ✅ Proteção CORS: Políticas adequadas de compartilhamento de recursos entre origens