Hugging Face's logo

Spaces:
MCP-1st-Birthday
/
philippines-disaster-risk-mcp
Running

App Files Community
1
philippines-disaster-risk-mcp / README.md
dexteredep's picture
dexteredep
Add social posts
3939971
preview code
|
raw
history blame contribute delete
10.7 kB

A newer version of the Gradio SDK is available: 6.1.0

Upgrade
metadata
title: PH Disaster Risk Assessment
emoji: 🌋
colorFrom: red
colorTo: green
sdk: gradio
sdk_version: 5.49.1
app_file: app.py
pinned: false
license: mit
short_description: Philippine disaster risk assessment MCP server
tags:
  - building-mcp-track-enterprise
  - building-mcp-track-customer
  - disaster-risk-management
  - philippines
  - geospatial
  - hazard-assessment
python_version: '3.13'

Built with:

📺 Watch Demo Video

💼 LinkedIn Post

Philippines Disaster Risk Assessment MCP Server

An MCP (Model Context Protocol) server that provides comprehensive disaster risk assessment data for locations in the Philippines. This server wraps the Hazard Hunter PH Service to deliver structured, machine-readable hazard information optimized for LLM consumption, including earthquake risks, volcanic hazards, flood susceptibility, landslides, and other natural disaster assessments through both an interactive web interface and structured API responses.

Features

🚀 MCP Optimization

  • Structured Data Output: Returns organized JSON with summary statistics, risk levels, and categorized hazards
  • Automatic Risk Categorization: Hazards automatically classified by severity (HIGH/MODERATE/LOW)
  • Overall Risk Assessment: Calculated risk level (CRITICAL/HIGH/MODERATE/LOW) based on hazard analysis
  • Summary Statistics: Total hazards assessed, high-risk count, critical hazard list
  • LLM-Friendly Format: Optimized for easy parsing and consumption by AI agents

🌐 Core Features

  • Interactive Web Interface: Beautiful Gradio UI with color-coded risk summary banner
  • Comprehensive Hazard Data: Access information on active faults, ground shaking, liquefaction, tsunami risks, volcanic hazards, floods, landslides, storm surge, and severe winds
  • Nearby Facilities: Get distances to critical infrastructure like schools, hospitals, and road networks
  • Smart Caching: 1-hour response cache to reduce API load and improve performance
  • Automatic Authentication: Handles GeoRisk API authentication tokens automatically
  • Error Handling: Graceful error handling with structured error responses

Local Development

Setup 

# Clone the repository
git clone https://github.com/yourusername/ph-disaster-risk-gradio.git
cd ph-disaster-risk-gradio

# Install dependencies
pip install -r requirements.txt

Running Locally 

python app.py

The MCP server will start with the Gradio interface at http://localhost:7860.

MCP Mode: The server automatically launches with mcp_server=True, enabling both:

  • Web UI access at the local URL
  • Structured JSON API responses for MCP consumption

Usage

Input Parameters

  • Latitude: Coordinate between -90 and 90 degrees
  • Longitude: Coordinate between -180 and 180 degrees

Example Coordinates

Try these Philippine locations:

  • Manila: Latitude 14.5995, Longitude 120.9842
  • Cebu City: Latitude 10.3157, Longitude 123.8854
  • Davao City: Latitude 7.1907, Longitude 125.4553
  • Baguio City: Latitude 16.4023, Longitude 120.5960
  • Tacloban City: Latitude 11.2500, Longitude 125.0000

Output Format

The MCP server returns structured JSON data optimized for LLM consumption:

{
  "success": true,
  "summary": {
    "total_hazards_assessed": 24,
    "high_risk_count": 1,
    "moderate_risk_count": 1,
    "low_risk_count": 22,
    "critical_hazards": [
      {"name": "liquefaction", "assessment": "High Potential"}
    ],
    "overall_risk_level": "HIGH"
  },
  "location": {
    "latitude": 14.5995,
    "longitude": 120.9842,
    "name": "City of Manila - Quiapo, NCR"
  },
  "hazards": {
    "seismic": { /* Active faults, ground shaking, liquefaction, tsunami */ },
    "volcanic": { /* Volcanoes, pyroclastic flows, ashfall, lahar */ },
    "hydrometeorological": { /* Floods, landslides, storm surge, winds */ }
  },
  "facilities": {
    "schools": { "elementary": {...}, "secondary": {...} },
    "hospitals": { "government": {...}, "private": {...} },
    "roads": { "primary": {...}, "secondary": {...} }
  },
  "metadata": {
    "from_cache": false,
    "timestamp": "2025-11-17T20:04:57Z",
    "source": "GeoRisk Philippines API",
    "cache_ttl_seconds": 3600
  }
}

UI Output

The web interface displays:

  • Risk Summary Banner: Color-coded overall risk level with hazard counts
    • 🔴 Red: CRITICAL (3+ high-risk hazards)
    • 🟡 Yellow: HIGH (1+ high-risk hazards)
    • 🟢 Green: LOW/MODERATE risk
  • Seismic Hazards: Active faults, ground shaking, liquefaction, tsunami risks
  • Volcanic Hazards: Active, potentially active, and inactive volcanoes with distances
  • Hydrometeorological Hazards: Floods, landslides, storm surge, severe winds
  • Critical Facilities: Distances to schools, hospitals, and road networks
  • Location Information: Place name and coordinates

MCP Usage Examples

For LLMs and AI Agents 

from app import get_disaster_risk

# Get structured risk assessment
risk_data = get_disaster_risk(14.5995, 120.9842)

# Quick risk check
if risk_data["summary"]["overall_risk_level"] in ["HIGH", "CRITICAL"]:
    high_risk_count = risk_data["summary"]["high_risk_count"]
    print(f"⚠️ Warning: {high_risk_count} high-risk hazards detected!")

# Access specific hazards
seismic = risk_data["hazards"]["seismic"]
if "activeFault" in seismic:
    fault_info = seismic["activeFault"]
    print(f"Active Fault: {fault_info['assessment']}")
    if "distance" in fault_info:
        print(f"Distance: {fault_info['distance']} {fault_info['units']}")

# Find critical hazards
for hazard in risk_data["summary"]["critical_hazards"]:
    print(f"🚨 {hazard['name']}: {hazard['assessment']}")

# Check nearby facilities
hospitals = risk_data["facilities"]["hospitals"]
govt_hospital = hospitals["government"]
if govt_hospital and "distance" in govt_hospital:
    print(f"Nearest hospital: {govt_hospital['distance']} {govt_hospital['units']}")

Response Structure Benefits

  • Easy Filtering: hazards["seismic"] returns only seismic hazards
  • Risk Prioritization: summary["critical_hazards"] lists most important items
  • Quick Assessment: summary["overall_risk_level"] gives immediate risk context
  • Metadata Tracking: metadata["from_cache"] and metadata["timestamp"] for debugging
  • Organized Facilities: Grouped by type (schools, hospitals, roads) for easy access

How It Works

  1. Input Validation: Coordinates are validated before making API requests
  2. Authentication: The server automatically obtains and caches authentication tokens from the GeoRisk passport endpoint
  3. Caching: Responses are cached for 1 hour to reduce API load and improve performance
  4. API Request: If not cached, the server makes a POST request to the GeoRisk hazards endpoint
  5. Data Structuring: Raw API response is transformed into structured format:
    • Hazards categorized by type (seismic, volcanic, hydrometeorological)
    • Risk levels automatically calculated (HIGH/MODERATE/LOW)
    • Summary statistics generated (hazard counts, critical items)
    • Overall risk level determined (CRITICAL/HIGH/MODERATE/LOW)
  6. MCP Response: Structured JSON data returned for LLM/agent consumption
  7. UI Formatting: For web interface, structured data is formatted as HTML with color-coded summary banner
  8. Display: Results shown in the Gradio interface with enhanced visual indicators

API Endpoints Used

  • Passport Token: https://hazardhunter.georisk.gov.ph/passport-token
  • Hazard Assessment: https://api.georisk.gov.ph/api/assessments/hazards

Requirements

  • Python 3.13 or higher (tested with 3.13)
  • gradio >= 5.49.1
  • requests >= 2.31.0
  • Internet connection to access GeoRisk Philippines API

MCP Server Requirements

The server is optimized for use as an MCP (Model Context Protocol) server:

  • Returns structured JSON data by default
  • Compatible with LLM agents and AI assistants
  • Maintains beautiful UI for direct web access
  • Supports both programmatic and interactive usage

Project Structure 

philippines-disaster-risk-mcp/
├── src/
│   └── ph_disaster_risk_mcp/
│       ├── __init__.py
│       ├── api_client.py       # API communication
│       ├── auth.py              # Authentication management
│       ├── cache.py             # Response caching
│       ├── validation.py        # Input validation
│       ├── formatter.py         # Response formatting (HTML generation)
│       └── exceptions.py        # Custom exceptions
├── tests/                       # Unit and integration tests
├── app.py                       # Main MCP server & Gradio application
├── requirements.txt             # Python dependencies
├── pyproject.toml               # Project configuration
├── OPTIMIZATION_NOTES.md        # Detailed MCP optimization documentation
└── README.md                    # This file

Development

Running Tests 

pip install pytest pytest-asyncio pytest-mock
pytest

Code Formatting 

pip install black
black src tests app.py

License

MIT License - see LICENSE file for details

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Documentation

Additional Resources

  • OPTIMIZATION_NOTES.md: Comprehensive documentation on MCP optimization, structured data format, and usage examples
  • API Documentation: See inline docstrings in app.py for function signatures and return types
  • Test Suite: Run pytest to validate functionality and see usage examples

Acknowledgments

This project uses data from the GeoRisk Philippines platform, provided by the Philippine government for disaster risk assessment and management.

MCP Optimization: This server has been optimized for the Model Context Protocol to provide structured, machine-readable disaster risk data for LLM agents and AI assistants.

Support

For issues, questions, or contributions, please visit the GitHub repository or Hugging Face Space.