Pikud Haoref Real-Time Alert System

Fornece acesso em tempo real aos alertas de emergência israelenses da API oficial do Pikud Haoref.

GitHub
5
Experimente este MCPPatrocinado

Documentação

Sistema de Alertas em Tempo Real Pikud Haoref

System Architecture

Um serviço de middleware abrangente e servidor MCP para acessar alertas de emergência israelenses da API oficial do Pikud Haoref (Comando da Frente Interna de Israel).

Visão Geral

Este projeto oferece duas formas de acessar dados de alertas de emergência israelenses usando uma arquitetura de publicação-assinatura:

  1. Serviço de Middleware FastAPI - Polling de fonte única com streaming SSE em tempo real
  2. Servidor MCP - Assinante orientado a eventos para assistentes de IA (construído com FastMCP)

O serviço FastAPI consulta a API oficial do Pikud Haoref a cada https://www.oref.org.il/WarningMessages/alert/alerts.json e publica alertas via Server-Sent Events. O servidor MCP assina este stream, criando um sistema eficiente de publicação-assinatura que elimina chamadas de API duplicadas, fornecendo acesso em tempo real a alertas de emergência, incluindo alertas de foguetes, intrusões aéreas, terremotos e outras emergências.

Recursos

Recursos do Serviço FastAPI

  • Polling de fonte única de alertas de emergência (elimina chamadas de API duplicadas)
  • Streaming SSE em tempo real via endpoint público de webhook
  • Autenticação por chave de API para endpoints de clientes e restrição geográfica para Israel
  • Suporte a Docker para implantação fácil
  • Suíte de testes abrangente

Recursos do Servidor MCP

  • Cliente SSE orientado a eventos - Assina o webhook do FastAPI para alertas em tempo real
  • 3 Ferramentas para assistentes de IA:
    • check_current_alerts - Verifica alertas ativos do stream assinado
    • get_alert_history - Obtém alertas recentes com filtragem (limite: 1-50, filtro de região, correspondência inteligente de cidades)
    • get_connection_status - Verifica o status da conexão de assinatura SSE
  • 2 Recursos:
    • poha://alerts/recent - Dados JSON de alertas recentes
    • poha://alerts/current-status - Informações de status do sistema
  • Filtragem Inteligente de Cidades:
    • Correspondência exata de substring - Encontra alertas pelo nome da cidade (ex.: "תל אביב" corresponde a todas as áreas de Tel Aviv)
    • Correspondência difusa - Correspondência inteligente com limite de 60 para nomes parciais/semelhantes
    • Suporte a múltiplas cidades - Pesquisa várias cidades simultaneamente
    • Nomes de cidades em hebraico - Otimizado para nomes de locais em hebraico da API
  • Construído com FastMCP seguindo padrões comprovados
  • Reconexão automática e tratamento de erros para conexões SSE

Início Rápido

Importante: A API do Pikud HaOref (oref.org.il) bloqueia geograficamente IPs fora de Israel. Você deve executar os serviços em uma máquina com IP israelense — localmente em Israel ou em uma VM GCP me-west1 (Tel Aviv).

1. Implante com 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

Após a inicialização, os serviços estarão disponíveis em:

2. Configure seu cliente MCP

Adicione ao mcp.json do VS Code, configuração do Claude Desktop ou configuração do Cursor:

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

3. Teste alertas

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

4. Conecte-se ao stream SSE

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

Desenvolvimento Local (sem 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 da API (Serviço FastAPI)

GET /

Endpoint básico de status.

GET /api/alerts-stream

Cabeçalhos: X-API-Key: your-key

Stream de Server-Sent Events para alertas em tempo real (endpoint autenticado). Retorna:

  • event: new_alert - Quando um novo alerta é detectado
  • : keep-alive - Mensagens periódicas de keep-alive

GET /api/webhook/alerts

Cabeçalhos: X-API-Key: your-key

Endpoint interno de webhook SSE para serviços como o servidor MCP. Transmite os mesmos dados de alerta que o endpoint de cliente e requer a mesma autenticação por chave de API por segurança. Projetado para comunicação servidor a servidor.

Exemplo de resposta para ambos os endpoints:

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

: keep-alive

Uso das Ferramentas MCP

Verificar Alertas Atuais

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

Obter Histórico 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.

Exemplos de Filtragem por Cidade:

  • cities=["תל אביב"] - Encontra todas as áreas de Tel Aviv (דרום העיר ויפו, מזרח, מרכז העיר, עבר הירקון)
  • cities=["חיפה"] - Encontra todos os alertas relacionados a Haifa
  • cities=["תל אביב", "חיפה", "ירושלים"] - Várias cidades simultaneamente
  • cities=["תל אביב מרכז"] - Correspondência difusa para "תל אביב - מרכז העיר"
  • cities=["all"] - Sem filtragem por cidade (mostra todos os alertas)

Verificar Status da Conexão

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

Arquitetura

O sistema usa uma arquitetura de publicação-assinatura com os seguintes componentes:

  1. API do Pikud Haoref - Fonte de dados externa (alertas de emergência do governo)
  2. Middleware FastAPI - Polling de fonte única + publicador SSE (consulta a cada 2 segundos)
  3. Servidor MCP - Assinante SSE + provedor de ferramentas para assistentes de IA
  4. Aplicações Cliente - Frontends web, aplicativos móveis, assistentes de IA ou outros serviços
Pikud Haoref API ←→ [Single Poller] ←→ FastAPI Middleware ←→ [SSE Stream] ←→ MCP Server → AI Assistants
                                              ↓
                                          [SSE Stream] ←→ Web Clients

Benefícios Principais:

  • ✅ Redução de 50% nas chamadas de API (fonte única de polling)
  • ✅ Propagação em tempo real de alertas via SSE
  • ✅ Arquitetura orientada a eventos para melhor escalabilidade
  • ✅ Reconexão automática para conexões SSE robustas

Diagrama Visual: Execute python diagram.py para gerar poha_sse_architecture.png mostrando a arquitetura completa do sistema.

Recursos de Segurança

Autenticação por Chave de API (Obrigatória para Todos os Endpoints)

Importante: A autenticação por chave de API é obrigatória para ambos os endpoints SSE por segurança.

  • Ambos os endpoints SSE exigem autenticação por chave de API via cabeçalho X-API-Key
  • Servidor MCP conecta-se com autenticação ao endpoint interno de webhook
  • Mesma chave de API usada tanto para autenticação de clientes quanto de serviços internos

Restrição Geográfica (Opcional)

Configure GEOIP_DB_PATH para restringir o acesso apenas a endereços IP israelenses:

  1. Cadastre-se em MaxMind
  2. Baixe GeoLite2-Country.mmdb
  3. Defina GEOIP_DB_PATH no seu arquivo .env

Desenvolvimento

Estrutura do Projeto

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

Testes

# Run tests in Docker
make test

# Or run tests locally
pytest -v

Dependências

  • Núcleo: fastapi, uvicorn, httpx, python-dotenv
  • Segurança: geoip2, slowapi
  • MCP: fastmcp, fuzzywuzzy, python-Levenshtein
  • Testes: pytest, pytest-asyncio, respx

Implantação com Docker

Visão Geral dos Serviços

O sistema executa 3 contêineres Docker:

ServiçoContêinerPortaDescrição
Polling de Alertaspoha-alert-poller8000API principal: polling, streaming SSE, endpoints REST, alertas de teste
Servidor MCPpoha-mcp-tools8001Ferramentas MCP para LLMs (fastmcp, streamable-http)
Gateway SSEpoha-sse-relay8002Retransmissão SSE para extensão do 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

Implantação em Produção (GCP me-west1)

A API oref.org.il bloqueia geograficamente IPs fora de Israel. Para produção, implante em uma VM e2-micro GCP em me-west1 (Tel Aviv) — elegível para o nível gratuito com IP israelense.

Configuração

# 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 dos Serviços GCP

Substitua <GCP_VM_IP> pelo IP externo da sua VM:

ServiçoURL
Polling de Alertas (REST + SSE)http://<GCP_VM_IP>:8000
Ferramentas MCPhttp://<GCP_VM_IP>:8001/mcp
Retransmissão SSE (VS Code)http://<GCP_VM_IP>:8002/api/alerts-stream

Por que GCP me-west1?

  • Gratuito para sempre (e2-micro é nível sempre gratuito)
  • IP israelense do data center de Tel Aviv — oref.org.il não bloqueará
  • Baixa latência para oref.org.il (mesmo país)
  • Docker funciona imediatamente no Debian

Fonte de Dados

  • API: https://www.oref.org.il/WarningMessages/alert/alerts.json
  • Provedor: Governo de Israel (Pikud Haoref - Comando da Frente Interna)
  • Cobertura: Todos os alertas de emergência em Israel
  • Frequência de Atualização: A cada 2 segundos
  • Tipos de Dados: Alertas de foguetes, intrusões aéreas, terremotos, comunicados de emergência

Casos de Uso

  • Equipes de Resposta a Emergências - Monitoramento de alertas em tempo real
  • Organizações de Notícias - Automação de notícias de última hora
  • Residentes de Israel - Notificações de segurança pessoal
  • Pesquisadores - Análise de padrões de emergência
  • Assistentes de IA - Informações contextuais de emergência
  • Aplicativos Móveis - Serviços de notificação push
  • Sistemas de Casa Inteligente - Respostas automatizadas a alertas

Persistência SQLite

Os alertas são persistidos em um banco de dados SQLite local (via aiosqlite) para consultas históricas. O banco de dados é criado automaticamente na inicialização.

  • Caminho padrão: data/alerts.db (configurável via variável de ambiente DATABASE_PATH)
  • Tabelas: alerts (dados completos de alerta) + city_alerts (desnormalizada para consulta rápida por cidade)
  • Indexada por nome de cidade e timestamp para consultas rápidas

Endpoints da API REST

Além dos endpoints de streaming SSE, os seguintes endpoints REST estão disponíveis:

EndpointDescrição
GET /healthVerificação de saúde (retorna {"status": "ok"})
GET /api/alerts/currentEstado atual de alertas ativos
GET /api/alerts/history?city=&limit=&since=Histórico de alertas do SQLite
GET /api/alerts/city/{city_name}Alertas para uma cidade específica
GET /api/alerts/statsEstatísticas agregadas de alertas

Exemplos:

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

Integração com OpenClaw

Para usar o servidor MCP do Pikud HaOref com OpenClaw, adicione ao seu openclaw.json:

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

Consulte openclaw-config-example.json e skills/pikud-haoref/SKILL.md para detalhes completos.

Ferramentas MCP Adicionais (com suporte a SQLite)

FerramentaDescrição
get_city_alerts(city, limit)Consulta o banco de dados local para alertas em uma cidade específica
get_db_stats()Obtém estatísticas do banco de dados de alertas

Exemplos de Configuração

Arquivo .env do Serviço 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

Solução de Problemas

Problemas Comuns

  1. "API key is missing" - Certifique-se de que o cabeçalho X-API-Key esteja definido tanto para endpoints de cliente quanto de webhook
  2. Falha na conexão MCP - Verifique:
    • Caminho do Python na configuração MCP (use o caminho completo do venv se necessário: /path/to/venv/bin/python)
    • Variável de ambiente API_KEY definida corretamente
    • Serviço FastAPI em execução em localhost:8000
    • Reinicie seu cliente MCP (Cursor, Claude Desktop, etc.)
    • Alternativa: Use o script start_mcp.sh fornecido como comando
  3. Tempos limite de conexão - Verifique sua conexão com a internet e configurações de firewall
  4. Erros de restrição geográfica - Verifique o caminho de GeoLite2-Country.mmdb e as permissões do arquivo
  5. Falha na autenticação SSE - Verifique se a chave de API corresponde entre o serviço FastAPI e a configuração MCP
  6. Filtragem por cidade não funciona -
    • Use nomes de cidades em hebraico (ex.: "תל אביב" em vez de "Tel Aviv")
    • Verifique os nomes exatos das cidades no histórico de alertas primeiro: cities=["all"]
    • Tente nomes mais amplos para correspondência difusa: "תל אביב" em vez de "תל אביב - מרכז העיר"
  7. ModuleNotFoundError: No module named 'fuzzywuzzy' -
    • Reconstrua os contêineres Docker: docker-compose build --no-cache
    • Instale as dependências: pip install fuzzywuzzy python-Levenshtein

Logs

Ambos os serviços fornecem registro detalhado. Verifique os logs para:

  • Status do polling da API
  • Conexões de clientes SSE e autenticação
  • Status da conexão do webhook do servidor MCP
  • Mensagens de erro
  • Eventos de segurança

Contribuindo

  1. Faça um fork do repositório
  2. Crie um branch de funcionalidade
  3. Adicione testes para novas funcionalidades
  4. Certifique-se de que todos os testes passem
  5. Envie um pull request

Licença

Este projeto acessa dados públicos de alertas de emergência do governo israelense. O serviço é projetado para fins legítimos de preparação para emergências e reportagem de notícias.

Aviso Legal

Este serviço fornece acesso a dados oficiais de alertas de emergência israelenses, mas não é afiliado ou endossado pelo governo israelense ou pelo Pikud Haoref. Sempre siga os procedimentos oficiais de emergência e consulte fontes oficiais para informações críticas de segurança.