# HK Bus MCP Server

An MCP (Model Context Protocol) server that provides real-time Hong Kong public transport ETA information. It wraps the [`hk-bus-eta`](https://github.com/hkbus/hk-bus-eta) npm package, which aggregates data from DATA.GOV.HK and various transport providers.

## Supported Transport

- **KMB / Long Win Bus** (KMB)
- **Citybus** (CTB)
- **New Lantao Bus** (NLB)
- **Green Minibus** (GMB)
- **MTR Light Rail Feeder Bus** (lrtfeeder)
- **MTR Light Rail** (lightRail)
- **MTR Heavy Rail** (mtr)
- **Ferries** (Sun Ferry, Fortune Ferry, HKKF)

## Tools

| Tool | Description |
|------|-------------|
| `search_routes` | Search bus routes by route number (e.g. "968", "A21") |
| `get_route_stops` | Get all stops for a specific route |
| `get_stop_eta` | Get real-time ETA for a specific stop on a route |
| `search_by_stop` | Search for bus stops by name (English or Chinese) |
| `find_route` | Find a specific route by number + origin/destination |
| `get_route_eta_all_stops` | Get real-time ETA across all stops on a route |
| `list_companies` | List all available transport companies |

## Setup

### Install & Build

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

### Configure with Claude Desktop

Add to your `claude_desktop_config.json`:

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

### Configure with Cursor / Windsurf

Add to your MCP settings:

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

## Usage Examples

Once connected, you can ask the AI things like:

- "When is the next bus 968 from Causeway Bay?"
- "Show me all stops for bus route A21"
- "Find buses going to Tsim Sha Tsui"
- "What's the ETA for KMB route 1 at Star Ferry stop?"
- "List all routes for Citybus"

The AI will use the MCP tools to search routes, find stops, and fetch real-time ETAs.

## Data Sources

- Route/stop/fare data: [data.hkbus.app](https://data.hkbus.app/routeFareList.min.json) (daily synced from [hk-bus-crawling](https://github.com/hkbus/hk-bus-crawling))
- KMB ETA: `data.etabus.gov.hk`
- CTB ETA: `rt.data.gov.hk`
- MTR ETA: `rt.data.gov.hk`
- NLB ETA: `rt.data.gov.hk`
- GMB ETA: `data.hkbus.app`

## License

GPL-3.0-only (same as hk-bus-eta)