Pikud Haoref Real-Time Alert System

Add to VS Codemcp.json, Claude Desktop config, or Cursor config:

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

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

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

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

Server-Sent Events stream for real-time alerts (authenticated endpoint). Returns:

- event: new_alert- When a new alert is detected
- : keep-alive- Periodic keep-alive messages

Internal SSE webhook endpoint for services like the MCP server. Streams the same alert data as the client endpoint and requires the same API key authentication for security. Designed for server-to-server communication.

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

# Run tests in Docker make test # Or run tests locally pytest -v

- Core:fastapi,uvicorn,httpx,python-dotenv
- Security:geoip2,slowapi
- MCP:fastmcp,fuzzywuzzy,python-Levenshtein
- Testing:pytest,pytest-asyncio,respx

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

The oref.org.il APIgeo-blocks non-Israeli IPs. For production, deploy on aGCP e2-micro VM inme-west1(Tel Aviv)— free-tier eligible with an Israeli IP.

# 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

Replace<GCP_VM_IP>with your VM's external IP:

- Free forever(e2-micro is always-free tier)
- Israeli IPfrom Tel Aviv data center — oref.org.il won't block it
- Low latencyto oref.org.il (same country)
- Docker works out of the boxon Debian

- API:https://www.oref.org.il/WarningMessages/alert/alerts.json
- Provider:Israeli Government (Pikud Haoref - Home Front Command)
- Coverage:All emergency alerts in Israel
- Update Frequency:Every 2 seconds
- Data Types:Rocket alerts, aerial intrusions, earthquakes, emergency announcements

- Emergency Response Teams- Real-time alert monitoring
- News Organizations- Breaking news automation
- Israeli Residents- Personal safety notifications
- Researchers- Emergency pattern analysis
- AI Assistants- Contextual emergency information
- Mobile Apps- Push notification services
- Smart Home Systems- Automated responses to alerts

Alerts are persisted to a local SQLite database (viaaiosqlite) for historical queries. The database is created automatically on startup.

- Default path:data/alerts.db(configurable viaDATABASE_PATHenv var)
- Tables:alerts(full alert data) +city_alerts(denormalized for fast city lookup)
- Indexedon city name and timestamp for fast queries

In addition to the SSE streaming endpoints, the following REST endpoints are available:

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

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

# Required for FastAPI SSE endpoints API_KEY=poha-test-key-2024-secure # Optional - Enable geo-restriction GEOIP_DB_PATH=/path/to/GeoLite2-Country.mmdb

- "API key is missing"- EnsureX-API-Keyheader is set for both client and webhook endpoints
- MCP connection fails- Check:

- Python path in MCP config (use full venv path if needed:/path/to/venv/bin/python)
- API_KEY environment variable is set correctly
- FastAPI service is running on localhost:8000
- Restart your MCP client (Cursor, Claude Desktop, etc.)
- Alternative: Use the providedstart_mcp.shscript as the command