# Monstarx Philippines MCP (Free Sources First)

Separate Philippines MCP service for public data that requires **no account and no API key**.

This is the Philippines counterpart to [Monstarx Japan MCP](../JP-MCP).

## Free sources included

| Source | Agency | Auth | Tools |
|---|---|---|---|
| [Open-Meteo Forecast / Air Quality / Elevation](https://open-meteo.com/) | Open-Meteo | None | Weather areas/overview/warnings, 24h/4day, rain, temp, humidity, UV, air quality, elevation |
| [USGS FDSN GeoJSON](https://earthquake.usgs.gov/fdsnws/event/1/) | USGS (Philippine bounding box) | None | Earthquake list, tsunami-flagged events |
| [Nominatim](https://nominatim.openstreetmap.org/) | OpenStreetMap | None | Address search, geocode, reverse geocode |
| [Zippopotam.us](https://api.zippopotam.us/ph/1000) | Zippopotam.us | None | 4-digit postal code lookup |
| [Nager.Date](https://date.nager.at/) | Nager.Date | None | Public holidays |
| [open.er-api.com](https://open.er-api.com/v6/latest/USD) | Community FX | None | USD/PHP and other FX rates |
| [HDX CKAN](https://data.humdata.org/) | OCHA / HDX `groups:phl` | None | Dataset search, metadata, datastore query |
| [OpenStreetMap Overpass](https://overpass-api.de/) | OpenStreetMap contributors | None | Tourism, shelters, hospitals, fuel, police, schools, pharmacies |
| [PSGC JSON API](https://psgc.gitlab.io/api/) | PSA codes via community mirror | None | Regions, provinces, cities/municipalities, barangays |
| [Open-Meteo Marine / Flood](https://open-meteo.com/) | Open-Meteo | None | Coastal waves, GloFAS river discharge |
| [AviationWeather METAR](https://aviationweather.gov/) | NOAA AWC | None | Airport METAR (RPLL, RPVM, …) |
| [PHISIX](https://phisix-api3.appspot.com/) | Community PSE mirror | None | Stock quotes (not official PSE) |
| [CoinGecko](https://api.coingecko.com/api/v3/simple/price) | CoinGecko | None | Crypto prices in PHP |
| [rss2json](https://api.rss2json.com/) + publisher RSS | Rappler / Philstar / Inquirer | None | News headlines |
| [PSA OpenSTAT PX-Web](https://openstat.psa.gov.ph/) | Philippine Statistics Authority | None | Statistical catalog browse |
| Local catalogs / parsers | Monstarx | None | Airports, universities, banks, metro stations, volcanoes, LTO plate, mobile prefix, PSGC digits, TIN/SSS/PhilHealth shape |
| [World Bank API](https://api.worldbank.org/v2/) | World Bank | None | PHL indicators (population, GDP, CPI) |
| [Aladhan](https://aladhan.com/prayer-times-api) | Aladhan | None | Prayer times by city |
| [NASA EONET](https://eonet.gsfc.nasa.gov/docs/v3) | NASA | None | Open natural events in the PH box |
| [gold-api.com](https://api.gold-api.com/price/XAU) | gold-api.com | None | Spot gold XAU/USD |
| [sunrise-sunset.org](https://sunrise-sunset.org/api) | sunrise-sunset.org | None | Sunrise / sunset |

## Not included (need keys / HTML-only / not a public JSON API)

Do **not** wrap these as MCP tools — they are portals, scrapers, or keyed APIs, not stable no-key JSON:

- PAGASA TenDay / warning JSON (token)
- Official PHIVOLCS HTML
- `data.gov.ph`, OpenDataPH invented `/api/` paths
- DOE pump prices, Meralco/NGCP “grid APIs”
- PNP / PDEA / Supreme Court e-Library (HTML)
- PRC licensure, CHED/DepEd masterlist “APIs”
- OpenAQ (API key)
- OpenHolidays `countryIsoCode=PH` currently returns an empty list
- Invented GTFS/live LRT-MRT-PNR schedule endpoints
- `psgc.cloud` (duplicate of PSGC; this server uses `psgc.gitlab.io`)
- ReliefWeb API (`api.reliefweb.int`) currently returns HTTP 410
- RestCountries v3.1 is deprecated
- WorldTimeAPI (`worldtimeapi.org`) timed out from this environment

Weather uses Open-Meteo with timezone `Asia/Manila`. Earthquake/tsunami tools use USGS inside ~4.5–21.5°N, 116–127°E and are **not** official PHIVOLCS bulletins.

## Endpoints

| Path | Purpose |
|---|---|
| `GET /` | Server info + tool list |
| `GET /health` | Health check |
| `POST /mcp` | MCP Streamable HTTP |

| Environment | MCP URL |
|---|---|
| Local | `http://localhost:8789/mcp` |
| Staging | `https://ph-mcp-staging.monstarxapp.com/mcp` |
| Production | `https://ph-mcp.monstarxapp.com/mcp` |

```bash
npm run deploy:staging      # Worker + route ph-mcp-staging.monstarxapp.com
npm run deploy:production   # Worker + route ph-mcp.monstarxapp.com
npm run smoke staging       # smoke against staging /mcp
npm run smoke:local         # smoke against local wrangler dev
```

## Tools

| Tool | Purpose |
|---|---|
| `ph_weather_areas` | List starter forecast city codes |
| `ph_weather_overview` | Daily overview text |
| `ph_weather_week_overview` | 7-day overview |
| `ph_weather_warnings` | Heavy rain / thunderstorm slots (Open-Meteo, not PAGASA) |
| `ph_weather_24h` | 24-hour hourly forecast |
| `ph_weather_4day` | 4-day daily forecast |
| `ph_uv_index` | Hourly UV index |
| `ph_rainfall` | Hourly rainfall |
| `ph_air_temperature` | Hourly air temperature |
| `ph_relative_humidity` | Hourly relative humidity |
| `ph_air_quality` | Hourly air quality (PM2.5 etc.) |
| `ph_earthquake_list` | Recent earthquakes (USGS PH box) |
| `ph_tsunami_list` | Recent tsunami-flagged USGS events |
| `ph_postal_code` | Postal code → place |
| `ph_public_holidays` | Philippines public holidays |
| `ph_elevation` | Elevation at lat/lon |
| `ph_bsp_finance` | USD/PHP (and other) FX rates |
| `ph_disease_reports` | Search infectious-disease open datasets |
| `ph_evacuation_shelters` | Nearby evacuation / assembly points |
| `ph_tourism_spots` | Nearby tourism spots (OpenStreetMap) |
| `ph_address_search` | Search Philippine addresses |
| `ph_geocode` | Address → latitude/longitude |
| `ph_reverse_geocode` | Latitude/longitude → address |
| `ph_datasets_search` | Search HDX Philippines open datasets |
| `ph_dataset_show` | Dataset metadata + resource URLs by id/name |
| `ph_dataset_metadata` | Alias of `ph_dataset_show` |
| `ph_dataset_query` | Query tabular datastore records by resource_id |
| `ph_regions` | List PSGC regions |
| `ph_provinces` | List PSGC provinces |
| `ph_cities` | List cities/municipalities for a region or province |
| `ph_barangays` | List barangays for a city/municipality |
| `ph_marine` | Coastal wave forecast (Open-Meteo Marine) |
| `ph_flood` | River-discharge forecast (not PAGASA) |
| `ph_airports` | Starter IATA/ICAO airport catalog |
| `ph_metar` | Latest airport METAR |
| `ph_pse_quote` | PSE quote via PHISIX (unofficial) |
| `ph_crypto_php` | Crypto spot price in PHP |
| `ph_hospitals` | Nearby hospitals/clinics (OSM, not DOH) |
| `ph_fuel_stations` | Nearby fuel stations (OSM, not DOE prices) |
| `ph_police_stations` | Nearby police stations (OSM, not PNP crime stats) |
| `ph_news` | Rappler / Philstar / Inquirer headlines |
| `ph_psa_catalog` | Browse PSA OpenSTAT folders/tables |
| `ph_universities` | Starter HEI directory (not CHED) |
| `ph_banks` | Starter bank / SWIFT directory (not BSP) |
| `ph_metro_stations` | LRT/MRT/PNR station catalog (not live GTFS) |
| `ph_lto_plate` | Plate format → likely region (not LTO lookup) |
| `ph_mobile_network` | Mobile prefix → original carrier |
| `ph_parse_psgc` | Slice 9-digit PSGC codes |
| `ph_id_format` | TIN / SSS / PhilHealth shape check |
| `ph_next_holidays` | Upcoming holidays from today |
| `ph_long_weekend` | Long-weekend windows for a year |
| `ph_worldbank` | World Bank PHL indicators (population, GDP, …) |
| `ph_prayer_schedule` | Prayer times by city (Aladhan) |
| `ph_natural_events` | NASA EONET events in the PH box |
| `ph_gold_price` | Spot gold XAU/USD |
| `ph_sunrise` | Sunrise / sunset (UTC) |
| `ph_schools` | Nearby schools (OSM, not DepEd) |
| `ph_pharmacies` | Nearby pharmacies (OSM) |
| `ph_volcanoes` | Starter volcano catalog (not PHIVOLCS alerts) |
| `ph_historical_weather` | Open-Meteo archive daily history |
| `ph_place_search` | Open-Meteo geocoding (PH places) |
| `ph_fire_stations` | Nearby fire stations (OSM) |
| `ph_ferry_terminals` | Nearby ferry terminals (OSM) |
| `ph_bus_stops` | Nearby bus stops (OSM) |
| `ph_species` | GBIF species search |
| `ph_occurrences` | GBIF occurrence records (`country=PH`) |
| `ph_psa_table` | PSA OpenSTAT table metadata |
| `ph_psa_query` | PSA OpenSTAT json-stat2 query |

## Local development

```bash
npm install
npm run dev
```

No `.dev.vars` or API keys are required for the free sources above.

Default location is Manila (`14.5995, 120.9842`). Default weather `area_code` is `manila`.

## Checks

```bash
npm run typecheck
npm test
npm run check
```

## Smoke test (local)

With `npm run dev` running:

```bash
npm run smoke:local
```

## Example curl

```bash
curl http://localhost:8789/mcp \
  -X POST \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d "{\"jsonrpc\":\"2.0\",\"method\":\"tools/call\",\"id\":1,\"params\":{\"name\":\"ph_weather_overview\",\"arguments\":{\"area_code\":\"manila\"}}}"
```

```bash
curl http://localhost:8789/mcp \
  -X POST \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d "{\"jsonrpc\":\"2.0\",\"method\":\"tools/call\",\"id\":2,\"params\":{\"name\":\"ph_reverse_geocode\",\"arguments\":{\"latitude\":14.5995,\"longitude\":120.9842}}}"
```

## Cursor MCP config

```json
{
  "mcpServers": {
    "monstarx-philippines": {
      "type": "http",
      "url": "http://127.0.0.1:8789/mcp?reconnect=1"
    }
  }
}
```

Philippines uses **8789**. Leave Indonesia on **8788** and Japan on **8787** if those are running.

## Architecture

```text
AI client
  → POST /mcp
  → ph_* tools
  → Open-Meteo / USGS / Nominatim / HDX / PSGC (no keys)
  → normalized JSON response
```

Same Worker shell as Japan MCP. Only adapters and tools differ.