# 🇸🇬 SG Gov MCP Server

A unified MCP server that gives AI agents access to **30 tools** covering Singapore government and public data — weather, transport, education, property, companies, and 2000+ datasets.

**Works immediately with zero API keys.** Transport and mapping tools unlock with free registration.

## Quick Start

```bash
npm install
npm run build
```

### Use with Kiro

Add to your agent config or `.kiro/settings/mcp.json`:

```json
{
  "mcpServers": {
    "sg-gov": {
      "command": "node",
      "args": ["/path/to/sg-gov-mcp/dist/index.js"]
    }
  }
}
```

### Use with Claude Desktop

Add to `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "sg-gov": {
      "command": "node",
      "args": ["/path/to/sg-gov-mcp/dist/index.js"],
      "env": {
        "SG_LTA_KEY": "your_key_here",
        "SG_ONEMAP_EMAIL": "your_email",
        "SG_ONEMAP_PASSWORD": "your_password"
      }
    }
  }
}
```

## Available Tools (30)

### Tier 1 — No API Key Required ✅

| Tool | Description |
|------|-------------|
| `sg_setup_status` | Check which API keys are configured |
| `sg_weather` | 2-hour, 24-hour, or 4-day weather forecast |
| `sg_air_quality` | PSI and PM2.5 readings by region |
| `sg_uv_index` | Current UV index |
| `sg_dengue` | Active dengue cluster locations |
| `sg_rainfall` | Real-time rainfall across 76 stations |
| `sg_dataset_search` | Find data.gov.sg datasets |
| `sg_dataset_fetch` | Fetch rows from any dataset |
| `sg_hdb_prices` | HDB resale flat prices (1990-2025) |
| `sg_coe_prices` | COE bidding results and premiums |
| `sg_schools` | School directory (subjects, CCAs, programmes) |
| `sg_holidays` | Singapore public holidays |
| `sg_hawker_centres` | Hawker centre locations |
| `sg_nus_modules` | NUS module search (via NUSMods) |
| `sg_ntu_modules` | NTU module search (via ModGod API) |
| `sg_taxi_availability` | Real-time taxi locations |
| `sg_company_search` | ACRA company/business search by name |
| `sg_neighbourhood_report` | Combined area report (HDB prices, schools, weather, air quality) |

### Tier 2 — Free API Key Required 🔑

| Tool | Requires | Description |
|------|----------|-------------|
| `sg_bus_arrival` | `SG_LTA_KEY` | Real-time bus arrival times |
| `sg_train_alerts` | `SG_LTA_KEY` | MRT/LRT service disruptions |
| `sg_traffic_incidents` | `SG_LTA_KEY` | Current road incidents |
| `sg_traffic_images` | `SG_LTA_KEY` | Live traffic camera feeds |
| `sg_carpark` | `SG_LTA_KEY` | Real-time carpark availability |
| `sg_ev_charging` | `SG_LTA_KEY` | EV charging point availability |
| `sg_flood_alerts` | `SG_LTA_KEY` | PUB flood alerts |
| `sg_mrt_crowd` | `SG_LTA_KEY` | MRT station crowd density |
| `sg_geocode` | `SG_ONEMAP_*` | Address → coordinates |
| `sg_reverse_geocode` | `SG_ONEMAP_*` | Coordinates → address |
| `sg_route` | `SG_ONEMAP_*` | Route planning (drive/walk/PT) |
| `sg_nearby` | `SG_ONEMAP_*` | Find nearby amenities |

## API Key Setup

All keys are free. Registration takes ~2 minutes each.

### LTA DataMall (bus, train, traffic)

1. Go to https://datamall.lta.gov.sg/content/datamall/en/request-for-api.html
2. Fill in the form — you get the key via email instantly
3. Set `export SG_LTA_KEY=your_key`

### OneMap (geocoding, routing)

1. Go to https://www.onemap.gov.sg and register
2. Set `export SG_ONEMAP_EMAIL=your_email`
3. Set `export SG_ONEMAP_PASSWORD=your_password`

The server handles token refresh automatically.

## Data Sources

| Source | What It Provides |
|--------|-----------------|
| [data.gov.sg](https://data.gov.sg) | 2000+ government datasets + real-time APIs |
| [LTA DataMall](https://datamall.lta.gov.sg) | Bus, train, traffic, carpark, taxi, EV charging |
| [OneMap (SLA)](https://www.onemap.gov.sg) | Geocoding, routing, demographics, nearby amenities |
| [NUSMods](https://nusmods.com) | NUS modules and timetables |
| [NTU ModGod](https://ntumodgodapi.vercel.app) | NTU modules, venues, graduation requirements |

## Examples

Ask your AI agent:
- "What's the weather forecast for the next 2 hours?"
- "When's the next bus at stop 83139?"
- "Show me HDB resale prices in Tampines for 4-room flats"
- "Find NUS computer science modules about machine learning"
- "Are there any MRT service disruptions right now?"
- "What hawker centres are near Bishan?"
- "Plan a driving route from Changi Airport to NUS"

## Development

```bash
npm run dev     # Watch mode
npm run build   # Compile TypeScript
npm start       # Run the server
```

## Architecture

```
stdio (JSON-RPC) ←→ MCP Server ←→ API Clients ←→ External APIs
                                    ├── data.gov.sg (no key)
                                    ├── NUSMods (no key)
                                    ├── NTU ModGod (no key)
                                    ├── LTA DataMall (key)
                                    └── OneMap (key)
```

## License

MIT