Pikud Haoref Real-Time Alert System

Proporciona acceso en tiempo real a alertas de emergencia israelíes desde la API oficial de Pikud Haoref.

GitHub
5
Prueba este MCPPatrocinado

Documentación

Sistema de Alertas en Tiempo Real de Pikud Haoref

System Architecture

Un servicio middleware integral y servidor MCP para acceder a alertas de emergencia israelíes desde la API oficial de Pikud Haoref (Comando del Frente Interior israelí).

Descripción general

Este proyecto proporciona dos formas de acceder a datos de alertas de emergencia israelíes utilizando una arquitectura de publicación-suscripción:

  1. Servicio Middleware FastAPI - Sondeo de fuente única con transmisión SSE en tiempo real
  2. Servidor MCP - Suscriptor basado en eventos para asistentes de IA (construido con FastMCP)

El servicio FastAPI consulta la API oficial de Pikud Haoref en https://www.oref.org.il/WarningMessages/alert/alerts.json y publica alertas mediante Eventos Enviados por el Servidor. El servidor MCP se suscribe a esta transmisión, creando un sistema eficiente de publicación-suscripción que elimina llamadas API duplicadas mientras proporciona acceso en tiempo real a alertas de emergencia, incluyendo alertas de cohetes, intrusiones aéreas, terremotos y otras emergencias.

Características

Características del Servicio FastAPI

  • Sondeo de fuente única de alertas de emergencia (elimina llamadas API duplicadas)
  • Transmisión SSE en tiempo real a través de endpoint público de webhook
  • Autenticación con clave API para endpoints de clientes y restricción geográfica a Israel
  • Soporte Docker para fácil implementación
  • Suite de pruebas integral

Características del Servidor MCP

  • Cliente SSE basado en eventos - Se suscribe al webhook de FastAPI para alertas en tiempo real
  • 3 Herramientas para asistentes de IA:
    • check_current_alerts - Verificar alertas activas de la transmisión suscrita
    • get_alert_history - Obtener alertas recientes con filtrado (límite: 1-50, filtro de región, coincidencia inteligente de ciudades)
    • get_connection_status - Verificar estado de conexión de suscripción SSE
  • 2 Recursos:
    • poha://alerts/recent - Datos JSON de alertas recientes
    • poha://alerts/current-status - Información de estado del sistema
  • Filtrado Inteligente de Ciudades:
    • Coincidencia exacta de subcadenas - Encontrar alertas por nombre de ciudad (ej., "תל אביב" coincide con todas las áreas de Tel Aviv)
    • Coincidencia difusa - Coincidencia inteligente con umbral 60 para nombres parciales o similares
    • Soporte multi-ciudad - Buscar múltiples ciudades simultáneamente
    • Nombres de ciudades en hebreo - Optimizado para nombres de ubicaciones en hebreo de la API
  • Construido con FastMCP siguiendo patrones probados
  • Reconexión automática y manejo de errores para conexiones SSE

Inicio Rápido

Importante: La API de Pikud HaOref (oref.org.il) bloquea geográficamente IPs no israelíes. Debe ejecutar los servicios en una máquina con IP israelí — ya sea localmente en Israel o en una VM de GCP me-west1 (Tel Aviv).

1. Implementar con Docker (Recomendado)

# Clone and deploy (one command)
git clone <repo-url> && cd pikud-a-oref-mcp
make deploy   # Creates .env, builds 3 containers, starts, health-checks

# Manage services
make logs     # View logs from all services
make status   # Show container status
make down     # Stop all services
make restart  # Rebuild and restart

Después del inicio, los servicios están disponibles en:

2. Configurar su cliente MCP

Agregar a VS Code mcp.json, configuración de Claude Desktop o configuración de Cursor:

{
  "servers": {
    "pikud-haoref": {
      "type": "http",
      "url": "http://localhost:8001/mcp"
    }
  }
}

3. Probar alertas

make test-alert       # Hebrew missile alert (תל אביב, רמת גן)
make test-alert-en    # English earthquake alert (Jerusalem, Haifa)
make test-alert-drill # Drill alert (כל הארץ)

4. Conectarse a la transmisión SSE

curl -N -H "X-API-Key: dev-secret-key" http://localhost:8000/api/alerts-stream

Desarrollo Local (sin Docker)

pip install -r requirements.txt

# Start services individually (3 separate terminals)
uvicorn src.api.main:app --host 0.0.0.0 --port 8000 --reload  # Terminal 1
python -m src.core.mcp_server                                   # Terminal 2
uvicorn src.api.sse_gateway:app --host 0.0.0.0 --port 8002      # Terminal 3

Endpoints de API (Servicio FastAPI)

GET /

Endpoint de estado básico.

GET /api/alerts-stream

Encabezados: X-API-Key: your-key

Transmisión de Eventos Enviados por el Servidor para alertas en tiempo real (endpoint autenticado). Devuelve:

  • event: new_alert - Cuando se detecta una nueva alerta
  • : keep-alive - Mensajes periódicos de mantenimiento de conexión

GET /api/webhook/alerts

Encabezados: X-API-Key: your-key

Endpoint interno de webhook SSE para servicios como el servidor MCP. Transmite los mismos datos de alerta que el endpoint de cliente y requiere la misma autenticación de clave API por seguridad. Diseñado para comunicación servidor a servidor.

Ejemplo de respuesta para ambos endpoints:

event: new_alert
data: {"id": "12345", "data": ["Tel Aviv", "Ramat Gan"], "cat": "1", "title": "Rocket Alert", "desc": "Immediate shelter required"}

: keep-alive

Uso de Herramientas MCP

Verificar Alertas Actuales

Use the check_current_alerts tool to see if there are any active emergency alerts from the subscribed SSE stream.

Obtener Historial de Alertas MCP

Use get_alert_history with limit=5 to get the 5 most recent alerts from the API.
Use get_alert_history with region="Tel Aviv" to get alerts for a specific region.
Use get_alert_history with cities=["תל אביב"] to get alerts for Tel Aviv (all areas).
Use get_alert_history with cities=["תל אביב", "חיפה"] to get alerts for multiple cities.
Use get_alert_history with cities=["תל אביב מרכז"] for specific areas with fuzzy matching.

Ejemplos de Filtrado por Ciudad:

  • cities=["תל אביב"] - Encuentra todas las áreas de Tel Aviv (דרום העיר ויפו, מזרח, מרכז העיר, עבר הירקון)
  • cities=["חיפה"] - Encuentra todas las alertas relacionadas con Haifa
  • cities=["תל אביב", "חיפה", "ירושלים"] - Múltiples ciudades simultáneamente
  • cities=["תל אביב מרכז"] - Coincidencia difusa con "תל אביב - מרכז העיר"
  • cities=["all"] - Sin filtrado por ciudad (muestra todas las alertas)

Verificar Estado de Conexión

Use get_connection_status to verify the SSE subscription connection and see system health.

Arquitectura

El sistema utiliza una arquitectura de publicación-suscripción con los siguientes componentes:

  1. API de Pikud Haoref - Fuente de datos externa (alertas de emergencia gubernamentales)
  2. Middleware FastAPI - Sondeo de fuente única + publicador SSE (consulta cada 2 segundos)
  3. Servidor MCP - Suscriptor SSE + proveedor de herramientas para asistentes de IA
  4. Aplicaciones Cliente - Frontends web, aplicaciones móviles, asistentes de IA u otros servicios
Pikud Haoref API ←→ [Single Poller] ←→ FastAPI Middleware ←→ [SSE Stream] ←→ MCP Server → AI Assistants
                                              ↓
                                          [SSE Stream] ←→ Web Clients

Beneficios Clave:

  • ✅ Reducción del 50% en llamadas API (fuente de sondeo única)
  • ✅ Propagación en tiempo real de alertas vía SSE
  • ✅ Arquitectura basada en eventos para mejor escalabilidad
  • ✅ Reconexión automática para conexiones SSE robustas

Diagrama Visual: Ejecutar python diagram.py para generar poha_sse_architecture.png mostrando la arquitectura completa del sistema.

Características de Seguridad

Autenticación con Clave API (Requerida para Todos los Endpoints)

Importante: La autenticación con clave API es requerida para ambos endpoints SSE por seguridad.

  • Ambos endpoints SSE requieren autenticación con clave API vía encabezado X-API-Key
  • El servidor MCP se conecta con autenticación al endpoint interno de webhook
  • Misma clave API utilizada tanto para autenticación de cliente como de servicio interno

Restricción Geográfica (Opcional)

Configurar GEOIP_DB_PATH para restringir el acceso solo a direcciones IP israelíes:

  1. Regístrese en MaxMind
  2. Descargue GeoLite2-Country.mmdb
  3. Establezca GEOIP_DB_PATH en su archivo .env

Desarrollo

Estructura del Proyecto

poha-real-time-alert-system/
├── src/                     # Main source code
│   ├── core/               # Core MCP functionality
│   │   ├── mcp_server.py   # MCP server implementation
│   │   ├── state.py        # Application state management
│   │   └── alert_queue.py  # Alert queue management
│   ├── api/                # FastAPI services
│   │   ├── main.py         # FastAPI application entry point
│   │   └── sse_gateway.py  # SSE gateway for VSCode extension
│   ├── services/           # Business logic
│   │   ├── polling.py      # Core API polling logic
│   │   └── sse.py          # Server-Sent Events implementation
│   └── utils/              # Utilities
│       ├── security.py     # Authentication and geo-restriction
│       └── geolocation.py  # Geo-IP functionality
├── docker/                 # Docker configuration
│   ├── Dockerfile         # Main FastAPI container
│   ├── mcp.Dockerfile     # MCP server container
│   └── docker-compose.yml # Multi-service setup
├── scripts/               # Utility scripts
│   ├── start_mcp.sh       # MCP server startup script
│   └── diagram.py         # Architecture diagram generator
├── tests/                 # Comprehensive test suite
├── vscode-extension/      # VSCode extension for alerts
├── conftest.py           # Test configuration
├── pytest.ini           # Test settings
├── Makefile             # Docker management commands
├── requirements.txt     # Python dependencies
├── README.md           # This file
└── .gitignore         # Git ignore rules

Pruebas

# Run tests in Docker
make test

# Or run tests locally
pytest -v

Dependencias

  • Núcleo: fastapi, uvicorn, httpx, python-dotenv
  • Seguridad: geoip2, slowapi
  • MCP: fastmcp, fuzzywuzzy, python-Levenshtein
  • Pruebas: pytest, pytest-asyncio, respx

Implementación Docker

Descripción General de Servicios

El sistema ejecuta 3 contenedores Docker:

ServicioContenedorPuertoDescripción
Sondeador de Alertaspoha-alert-poller8000API principal: sondeo, transmisión SSE, endpoints REST, alertas de prueba
Servidor MCPpoha-mcp-tools8001Herramientas MCP para LLMs (fastmcp, streamable-http)
Puerta de enlace SSEpoha-sse-relay8002Retransmisión SSE para extensión de VS Code

Comandos Docker

make deploy     # One-command deploy (build + start + health-check)
make up         # Start all 3 services
make down       # Stop all services
make restart    # Rebuild and restart
make logs       # View all logs
make status     # Show container status
make clean      # Remove containers and volumes

Implementación en Producción (GCP me-west1)

La API de oref.org.il bloquea geográficamente IPs no israelíes. Para producción, implemente en una VM e2-micro de GCP en me-west1 (Tel Aviv) — elegible para nivel gratuito con IP israelí.

Configuración

# 1. Create free VM in Tel Aviv
gcloud compute instances create pikud-haoref \
  --zone=me-west1-a \
  --machine-type=e2-micro \
  --image-family=debian-12 \
  --image-project=debian-cloud \
  --tags=http-server

# 2. Allow ports 8000-8002
gcloud compute firewall-rules create allow-pikud-haoref \
  --allow=tcp:8000-8002 --target-tags=http-server

# 3. SSH and install Docker
gcloud compute ssh pikud-haoref --zone=me-west1-a
sudo apt update && sudo apt install -y docker.io docker-compose
sudo usermod -aG docker $USER && newgrp docker

# 4. Clone, configure, and deploy
git clone <repo-url> && cd pikud-a-oref-mcp
cp .env.example .env  # Edit API_KEY for production!
make deploy

URLs de Servicio GCP

Reemplace <GCP_VM_IP> con la IP externa de su VM:

ServicioURL
Sondeador de Alertas (REST + SSE)http://<GCP_VM_IP>:8000
Herramientas MCPhttp://<GCP_VM_IP>:8001/mcp
Retransmisión SSE (VS Code)http://<GCP_VM_IP>:8002/api/alerts-stream

¿Por qué GCP me-west1?

  • Gratis para siempre (e2-micro es nivel siempre gratuito)
  • IP israelí del centro de datos de Tel Aviv — oref.org.il no lo bloqueará
  • Baja latencia hacia oref.org.il (mismo país)
  • Docker funciona de inmediato en Debian

Fuente de Datos

  • API: https://www.oref.org.il/WarningMessages/alert/alerts.json
  • Proveedor: Gobierno israelí (Pikud Haoref - Comando del Frente Interior)
  • Cobertura: Todas las alertas de emergencia en Israel
  • Frecuencia de Actualización: Cada 2 segundos
  • Tipos de Datos: Alertas de cohetes, intrusiones aéreas, terremotos, anuncios de emergencia

Casos de Uso

  • Equipos de Respuesta a Emergencias - Monitoreo de alertas en tiempo real
  • Organizaciones de Noticias - Automatización de noticias de última hora
  • Residentes Israelíes - Notificaciones de seguridad personal
  • Investigadores - Análisis de patrones de emergencia
  • Asistentes de IA - Información contextual de emergencias
  • Aplicaciones Móviles - Servicios de notificaciones push
  • Sistemas de Hogar Inteligente - Respuestas automatizadas a alertas

Persistencia SQLite

Las alertas se persisten en una base de datos SQLite local (vía aiosqlite) para consultas históricas. La base de datos se crea automáticamente al inicio.

  • Ruta predeterminada: data/alerts.db (configurable vía variable de entorno DATABASE_PATH)
  • Tablas: alerts (datos completos de alerta) + city_alerts (desnormalizada para búsqueda rápida de ciudades)
  • Indexada por nombre de ciudad y marca de tiempo para consultas rápidas

Endpoints de API REST

Además de los endpoints de transmisión SSE, están disponibles los siguientes endpoints REST:

EndpointDescripción
GET /healthVerificación de salud (devuelve {"status": "ok"})
GET /api/alerts/currentEstado actual de alertas activas
GET /api/alerts/history?city=&limit=&since=Historial de alertas desde SQLite
GET /api/alerts/city/{city_name}Alertas para una ciudad específica
GET /api/alerts/statsEstadísticas agregadas de alertas

Ejemplos:

curl http://localhost:8000/health
curl "http://localhost:8000/api/alerts/history?city=תל אביב&limit=10"
curl http://localhost:8000/api/alerts/city/חיפה
curl http://localhost:8000/api/alerts/stats

Integración con OpenClaw

Para usar el servidor MCP de Pikud HaOref con OpenClaw, agregue a su openclaw.json:

{
  "mcpServers": {
    "pikud-haoref": {
      "url": "http://127.0.0.1:8001/mcp"
    }
  }
}

Consulte openclaw-config-example.json y skills/pikud-haoref/SKILL.md para detalles completos.

Herramientas MCP Adicionales (respaldadas por SQLite)

HerramientaDescripción
get_city_alerts(city, limit)Consultar BD local para alertas en una ciudad específica
get_db_stats()Obtener estadísticas de la base de datos de alertas

Ejemplos de Configuración

Archivo .env del Servicio FastAPI

# Required for FastAPI SSE endpoints
API_KEY=poha-test-key-2024-secure

# Optional - Enable geo-restriction
GEOIP_DB_PATH=/path/to/GeoLite2-Country.mmdb

Solución de Problemas

Problemas Comunes

  1. "Falta la clave API" - Asegúrese de que el encabezado X-API-Key esté configurado tanto para endpoints de cliente como de webhook
  2. La conexión MCP falla - Verifique:
    • Ruta de Python en la configuración MCP (use ruta completa de venv si es necesario: /path/to/venv/bin/python)
    • La variable de entorno API_KEY esté configurada correctamente
    • El servicio FastAPI se esté ejecutando en localhost:8000
    • Reinicie su cliente MCP (Cursor, Claude Desktop, etc.)
    • Alternativa: Use el script start_mcp.sh proporcionado como comando
  3. Tiempos de espera de conexión - Verifique su conexión a internet y configuración de firewall
  4. Errores de restricción geográfica - Verifique la ruta de GeoLite2-Country.mmdb y los permisos de archivo
  5. La autenticación SSE falla - Verifique que la clave API coincida entre el servicio FastAPI y la configuración MCP
  6. El filtrado por ciudad no funciona -
    • Use nombres de ciudades en hebreo (ej., "תל אביב" no "Tel Aviv")
    • Verifique primero los nombres exactos de ciudades en el historial de alertas: cities=["all"]
    • Pruebe nombres más amplios para coincidencia difusa: "תל אביב" en lugar de "תל אביב - מרכז העיר"
  7. ModuleNotFoundError: No module named 'fuzzywuzzy' -
    • Reconstruya los contenedores Docker: docker-compose build --no-cache
    • Instale dependencias: pip install fuzzywuzzy python-Levenshtein

Registros

Ambos servicios proporcionan registro detallado. Verifique los registros para:

  • Estado del sondeo de API
  • Conexiones de cliente SSE y autenticación
  • Estado de conexión del webhook del servidor MCP
  • Mensajes de error
  • Eventos de seguridad

Contribuciones

  1. Haga un fork del repositorio
  2. Cree una rama de características
  3. Agregue pruebas para nueva funcionalidad
  4. Asegúrese de que todas las pruebas pasen
  5. Envíe una solicitud de extracción

Licencia

Este proyecto accede a datos públicos de alertas de emergencia del gobierno israelí. El servicio está diseñado para fines legítimos de preparación para emergencias y reportes de noticias.

Aviso Legal

Este servicio proporciona acceso a datos oficiales de alertas de emergencia israelíes pero no está afiliado ni respaldado por el gobierno israelí o Pikud Haoref. Siempre siga los procedimientos oficiales de emergencia y consulte fuentes oficiales para información crítica de seguridad.