Python Weather Server

Un servidor basado en FastAPI que proporciona información meteorológica de la API del Servicio Meteorológico Nacional, asegurado con OAuth 2.1.

GitHub
27
Prueba este MCPPatrocinado

Documentación

Servidor Meteorológico MCP en Python con Autenticación OAuth 2.1

Un servidor de Model Context Protocol (MCP) listo para producción, construido con FastAPI, que proporciona información meteorológica utilizando la API del Servicio Meteorológico Nacional. Incluye cumplimiento total de MCP OAuth 2.1 con PKCE, registro dinámico de clientes e integración con Azure AD. Listo para implementarse en Azure App Service con Azure Developer CLI (azd).

🌟 Características

  • Cumplimiento de la Especificación MCP OAuth 2.1: Implementación completa de la Especificación de Autorización MCP (2025-03-26)
  • PKCE Obligatorio: Autorización segura con Proof Key for Code Exchange (RFC 7636, método S256)
  • Registro Dinámico de Clientes: Registro automático de clientes según RFC 7591
  • Metadatos del Servidor de Autorización: Punto de descubrimiento según RFC 8414
  • Autorización de Terceros: Utiliza Azure AD como servidor de autorización
  • Encabezados del Protocolo MCP: Soporte completo para MCP-Protocol-Version: 2025-03-26
  • Gestión de Tokens JWT: Autenticación segura basada en tokens
  • Herramientas Meteorológicas:
    • get_alerts: Obtener alertas meteorológicas para cualquier estado de EE. UU.
    • get_forecast: Obtener pronóstico meteorológico detallado para cualquier ubicación
  • Listo para Azure: Preconfigurado para implementación en Azure App Service
  • Interfaz de Pruebas Web: Pruebas integradas del flujo OAuth 2.1

🔐 Implementación de Autorización MCP

Este servidor implementa la Especificación de Autorización MCP (2025-03-26) completa:

Puntos Finales OAuth 2.1

  • GET /.well-known/oauth-authorization-server - Metadatos del servidor de autorización (RFC 8414)
  • POST /register - Registro dinámico de clientes (RFC 7591)
  • GET /authorize - Punto final de autorización con PKCE (RFC 7636)
  • POST /token - Punto final de tokens para intercambio de código y actualización
  • GET /auth/azure/callback - Devolución de llamada de autorización de terceros

Características del Protocolo MCP

  • ✅ Encabezados de Versión del Protocolo: MCP-Protocol-Version: 2025-03-26
  • ✅ PKCE Obligatorio: Todos los clientes deben usar el método S256
  • ✅ Registro Dinámico: Incorporación automática de clientes
  • ✅ Autenticación JWT: Validación de tokens Bearer en puntos finales MCP
  • ✅ Manejo Adecuado de Errores: Respuestas 401/403/400 con detalles
  • ✅ Integración con Azure AD: Servidor de autorización de nivel empresarial

⚠️ Importante: Se requiere configuración completa de OAuth antes de su uso. Consulte AUTH_SETUP.md para instrucciones de configuración de Azure AD.

💻 Desarrollo Local

Requisitos Previos

  • Python 3.8+
  • Cuenta de Azure con configuración OAuth completada (consulte AUTH_SETUP.md)

Configuración y Ejecución

  1. Complete primero la configuración de OAuth: Siga las instrucciones en AUTH_SETUP.md para crear su registro de aplicación en Azure.

  2. Clone e instale las dependencias:

    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 las variables de entorno:

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

  4. Inicie el servidor de desarrollo:

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

  5. Acceda al servidor:

🔌 Conexión al Servidor MCP Local

Autenticación Requerida

Antes de conectar cualquier cliente MCP, debe autenticarse:

  1. Obtener Token JWT: Visite http://localhost:8000/mcp_oauth_test.html
  2. Complete el Flujo OAuth: Utilice la interfaz de pruebas OAuth 2.1 integrada
  3. Copie el Token JWT: Use el token en la configuración de su cliente MCP

Uso de MCP Inspector

  1. En una nueva ventana de terminal, instale y ejecute MCP Inspector:

    npx @modelcontextprotocol/inspector

  2. Haga CTRL+clic en la URL mostrada por la aplicación (por ejemplo, http://localhost:5173/#resources)

  3. Configure la conexión autenticada:

    • Establezca el tipo de transporte en HTTP
    • Establezca la URL en: http://localhost:8000/
    • Agregue el encabezado Authorization: Bearer <your-jwt-token>

    💡 Cómo obtener su token JWT: Visite http://localhost:8000/mcp_oauth_test.html para completar el flujo OAuth 2.1 y obtener su token JWT.

  4. Pruebe la conexión: Liste las herramientas, haga clic en una herramienta y ejecútela

Configuración 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

Configuración Posterior a la Implementación

⚠️ Crítico: Después de la implementación, debe actualizar su registro de aplicación en Azure:

  1. Anote su URL implementada: https://app-web-[unique-id].azurewebsites.net/
  2. Vaya a Azure Portal → Microsoft Entra ID → Registros de aplicaciones → Su aplicación
  3. Haga clic en Autenticación → Agregar URI de redirección: https://app-web-[unique-id].azurewebsites.net/auth/azure/callback
  4. Haga clic en Guardar

💡 Nota: El URI de redirección debe ser /auth/azure/callback (no /auth/callback) para que el flujo MCP OAuth 2.1 funcione correctamente.

Pruebe su Implementación

Después de la implementación, su servidor MCP autenticado estará disponible en:

  • Interfaz de Pruebas OAuth 2.1: https://<your-app>.azurewebsites.net/mcp_oauth_test.html
  • Verificación de estado: https://<your-app>.azurewebsites.net/health
  • Capacidades MCP: https://<your-app>.azurewebsites.net/mcp/capabilities
  • Documentación de API: https://<your-app>.azurewebsites.net/docs

🔌 Conexión al Servidor MCP Remoto

Siga las mismas instrucciones que para la configuración local, pero use su URL de Azure App Service y asegúrese de tener un token JWT válido del punto final de autenticación implementado.

Configuración para el servidor implementado:

{
  "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"
    }
  }
}

🧪 Pruebas

Pruebas Interactivas de OAuth 2.1

La interfaz de pruebas proporciona:

  1. Flujo OAuth 2.1 Completo: Registro dinámico de clientes → Autorización → Intercambio de tokens
  2. Validación PKCE: Pruebe el flujo completo de Proof Key for Code Exchange
  3. Pruebas de Puntos Finales MCP: Pruebe las herramientas meteorológicas autenticadas
  4. Visualización de Tokens JWT: Vea y valide sus tokens de autenticación
  5. Pruebas de Devolución de Llamada del Cliente: Incluye el punto final /client-callback para la validación del flujo OAuth

Arquitectura del Flujo OAuth

El servidor implementa un flujo OAuth 2.1 completo:

  • Registro del Cliente: Registro dinámico de clientes con credenciales generadas automáticamente
  • Autorización: El usuario es redirigido a Azure AD para autenticación
  • Devolución de Llamada de Azure: El servidor recibe el código de autorización de Azure en /auth/azure/callback
  • Devolución de Llamada del Cliente: El servidor redirige a la devolución de llamada del cliente (por ejemplo, /client-callback) con el código de autorización
  • Intercambio de Tokens: El cliente intercambia el código de autorización por un token de acceso JWT

Pruebas con Clientes MCP

Pruebe con cualquier cliente compatible con MCP usando los puntos finales autenticados y su token JWT.

🌦️ Fuente de Datos

Este servidor utiliza la API del Servicio Meteorológico Nacional (NWS):

  • Alertas y avisos meteorológicos en tiempo real
  • Pronósticos meteorológicos detallados
  • Datos meteorológicos oficiales del gobierno de EE. UU.
  • No se requiere clave de API
  • Alta confiabilidad y precisión

🔒 Características de Seguridad

  • ✅ Cumplimiento de OAuth 2.1: Implementación completa de la Especificación de Autorización MCP
  • ✅ PKCE Obligatorio: Método S256 para todos los flujos de autorización
  • ✅ Registro Dinámico de Clientes: Incorporación automática y segura de clientes
  • ✅ Integración con Azure AD: Servidor de autorización de nivel empresarial
  • ✅ Seguridad de Tokens JWT: Expiración configurable y validación segura
  • ✅ Aplicación de Versión del Protocolo: Validación del encabezado MCP-Protocol-Version
  • ✅ Registro de Solicitudes: Registro de auditoría completo con identificación de usuarios
  • ✅ Protección CORS: Políticas adecuadas de intercambio de recursos entre orígenes