hongkong-mtr-skill
Query Hong Kong MTR live service status, delays, traffic notices, next trains, journey plans, fares, Light Rail, MTR Bus, station accessibility, and Hong Kong ferry operators/routes with live HKKF and Sun Ferry ETAs. Use when a task involves Hong Kong transport routes, arrival times, disruptions, fares, or journey planning.
Safety scan
A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.
Badge for your README
Markdown
[](/listings/hongkong-ai-labs--hongkong-mtr-skill)HTML
<a href="/listings/hongkong-ai-labs--hongkong-mtr-skill"><img src="/api/listings/hongkong-ai-labs--hongkong-mtr-skill/badge.svg" alt="findsafeskills safety rating" /></a>Install
Install instructions from the README
As written by the repo's author. findsafeskills has not verified these steps.
These steps run a script from the network that findsafeskills does not scan.
Requires **Rust 1.89+** (`rustup` recommended).
cargo install --path . # or directly from GitHub: cargo install --git https://github.com/hongkong-ai-labs/hongkong-mtr-skill --locked mtr-hk status mtr-hk ferries
This installs three binaries into `~/.cargo/bin`:
- `mtr-hk-mcp` — MCP stdio server - `mtr-hk-mcp-http` — MCP Streamable HTTP/SSE server - `mtr-hk` — CLI
If the commands are not found, add Cargo's bin directory to `PATH`:
export PATH="$HOME/.cargo/bin:$PATH"
For development without installing:
cargo build --release --bins ./target/release/mtr-hk status ./target/release/mtr-hk-mcp
Other install routes
Prebuilt binaries for macOS (Intel or Apple silicon) and Linux (x86_64 or aarch64, static musl) are checksum-verified by the installer:
curl -fsSL https://raw.githubusercontent.com/hongkong-ai-labs/hongkong-mtr-skill/main/scripts/install.sh | sh
As an agent skill:
npx skills add hongkong-ai-labs/hongkong-mtr-skill npx skills update # refresh the installed skill later
Docker, Apple container and a pure Cloudflare Workers (V8 isolate) deployment are described below. The native binaries keep stdio and Streamable HTTP/SSE; the Worker reuses the same Rust service layer through a Workers `fetch` backend.
Register the MCP server
The included `.mcp.json` uses the installed binary:
{
"mcpServers": {
"mtr-hk": {
"command": "mtr-hk-mcp",
"args": []
}
}
}Register it with any MCP client:
npx add-mcp "$(command -v mtr-hk-mcp)" --name mtr-hk -a claude-code -a codex -a cursor -y claude mcp add mtr-hk -- mtr-hk-mcp codex mcp add mtr-hk -- mtr-hk-mcp
`add-mcp` detects the client configuration files in the current project; add `-g` for a global install. Substitute an absolute path if your client does not inherit the shell `PATH`.
For Claude Code, Claude Desktop, Cursor or any stdio MCP client, use the same command. If the client does not inherit your shell `PATH`, set `command` to the absolute path, e.g. `/Users/you/.cargo/bin/mtr-hk-mcp`.
Remote HTTP/SSE MCP
The HTTP binary exposes the same 15 tools over Streamable HTTP at `/mcp`, with a `/health` endpoint:
MTR_HTTP_ADDR=0.0.0.0:8080 MTR_MCP_API_KEY="$SECRET" mtr-hk-mcp-http
claude mcp add --transport http mtr-hk http://localhost:8080/mcp
The `/mcp` endpoint returns JSON or SSE-framed responses depending on the client. Set `MTR_MCP_API_KEY` (or `MTR_API_KEY` / `MTR_AUTH_TOKEN`) to require `Authorization: Bearer <key>` or `X-API-Key: <key>`; `/health` stays public. Without a key there is no authentication, so do not expose it directly to the public internet.
Containers
Build one image containing the CLI and both MCP transports:
docker build -t mtr-hk-mcp . docker run --rm -p 8080:8080 mtr-hk-mcp
Run the stdio server instead:
docker run --rm -i --entrypoint mtr-hk-mcp mtr-hk-mcp
Or use Compose:
docker compose up --build http
Apple's `container` runtime uses the same OCI image:
container build -t mtr-hk-mcp . container run --rm -p 8080:8080 mtr-hk-mcp container run --rm -i --entrypoint mtr-hk-mcp mtr-hk-mcp
The image defaults to the HTTP server on port 8080. It runs as a non-root user and includes a `/health` check.
Cloudflare Workers (pure WASM)
The root `wrangler.jsonc` deploys a true `wasm32-unknown-unknown` Worker on the Cloudflare V8 isolate runtime. It does not use a Container, Docker, Tokio or TCP; the shared service layer talks to MTR through the Workers `fetch` API and exposes the same 15 MCP tools at `/mcp`. Native stdio and the full Streamable HTTP/SSE server remain available from the binaries above.
Prerequisites: Rust 1.89 with the WASM target, `worker-build`, Node.js and a Cloudflare account.
rustup target add wasm32-unknown-unknown --toolchain 1.89.0 cargo install worker-build@0.8.0 npx wrangler login
What was scanned
The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.
SKILL.md · Manifest · 286 lines · 1 finding marked
- ---
- name: hongkong-mtr-skill
- description: Query Hong Kong MTR live service status, delays, traffic notices, next trains, journey plans, fares, Light Rail, MTR Bus, station accessibility, and Hong Kong ferry operators/routes with live HKKF and Sun Ferry ETAs. Use when a task involves Hong Kong transport routes, arrival times, disruptions, fares, or journey planning.
- ---
- # Hong Kong MTR and ferries
- Use this skill for Hong Kong MTR questions (service status, delays, notices, next trains, journey planning, fares, Light Rail, MTR Bus, accessibility) and for Hong Kong ferry questions (operators, routes, piers, fares, timetables and live ferry ETAs).
- MTR data comes from MTR's public open-data APIs plus the traffic-news and trip-planner endpoints used by MTR's own website/app. Ferry route/fare data comes from the Transport Department's franchised and licensed ferry dataset; live ferry ETAs come from HKKF and Sun Ferry. These integrations are unofficial and can change. Never invent an arrival time, fare or service status.
- ## Install (Rust)
- The server and CLI are Rust binaries. Node/npm are **not** required.
- Prerequisites:
- - Rust 1.89 or newer, including `cargo` (`rustup` is the easiest install: <https://rustup.rs>).
- - `~/.cargo/bin` on `PATH` (the Rust installer normally adds it).
- From the repository root:
- ```bash
- cargo install --path .
- ```
- This installs three binaries into `~/.cargo/bin`:
- ```bash
- mtr-hk-mcp # MCP stdio server
- mtr-hk-mcp-http # MCP Streamable HTTP/SSE server
- mtr-hk # human/JSON CLI
- ```
- Verify:
- ```bash
- mtr-hk status
- mtr-hk ferries
- command -v mtr-hk-mcp
- ```
- If `mtr-hk` is not found, add Cargo's bin directory to your shell profile:
- ```bash
- export PATH="$HOME/.cargo/bin:$PATH"
- ```
- For development without installing:
- ```bash
- cargo build --release
- ./target/release/mtr-hk status
- ./target/release/mtr-hk-mcp
- ```
- ### Register the MCP server
- Use the installed binary in Claude Code, Claude Desktop, Cursor or any stdio MCP client:
- ```json
- {
- "mcpServers": {
- "mtr-hk": {
- "command": "mtr-hk-mcp",
- "args": []
- }
- }
- }
- ```
- The repository's `.mcp.json` already uses this command. After `cargo install --path .`, approve or restart the server in your client. If your client does not inherit your shell `PATH`, use the absolute path, e.g. `"command": "/Users/you/.cargo/bin/mtr-hk-mcp"`.
- ### Remote HTTP/SSE MCP
- For a remote or container deployment, run:
- ```bash
- MTR_HTTP_ADDR=0.0.0.0:8080 mtr-hk-mcp-http
- ```
- and point an HTTP MCP client at `http://localhost:8080/mcp`. The endpoint
- supports Streamable HTTP and SSE-framed responses. Set an optional static key
- with `MTR_MCP_API_KEY` (aliases `MTR_API_KEY`, `MTR_AUTH_TOKEN`) or `--api-key`;
- requests then need `Authorization: Bearer <key>` or `X-API-Key: <key>`, while
- `/health` stays public. Without a key there is no authentication, so do not
- expose it directly to the public internet.
- The repository also contains a `Dockerfile`, `compose.yaml`, and a pure
- Cloudflare Workers (V8 isolate) deployment rooted at `wrangler.jsonc` with the
- Rust Worker in `worker/`. The Worker exposes the same 15 tools at `/mcp`; see
- `README.md` and `cloudflare/README.md` for deployment and authentication
- details.
- ### Install the agent skill
- Link this directory into your client's skills folder:
- ```bash
- mkdir -p ~/.claude/skills
- ln -sfn "$PWD/skills/mtr" ~/.claude/skills/mtr
- ```
- The repository also has `.claude/skills/mtr` linked to `../../skills/mtr` for project-local discovery.
- ### CLI fallback
- If MCP tools are unavailable, use the installed CLI or the repository wrapper:
- ```bash
- mtr-hk status
- mtr-hk next "Tsim Sha Tsui" --line=TWL
- mtr-hk journey Admiralty "Tung Chung"
- mtr-hk ferries "Cheung Chau"
- skills/mtr/scripts/mtr status
- mtr-hk update --check
- ```
- Add `--json` to any command for raw structured output. The wrapper looks for `mtr-hk` on `PATH`, then `target/release/mtr-hk`, then `target/debug/mtr-hk`.
- ## Choose the right tool
- | Question | MCP tool | CLI fallback |
- |---|---|---|
- | Is the MTR running normally? Any delays? | `mtr_status` | `mtr-hk status` |
- | What do the current traffic notices say? | `mtr_alerts` | `mtr-hk alerts` |
- | Next trains at a station | `mtr_next_trains` | `mtr-hk next "<station>"` |
- | Best route between two MTR stations | `mtr_plan_journey` | `mtr-hk journey "<from>" "<to>"` |
- | Fare between two MTR stations | `mtr_fares` | `mtr-hk fares "<from>" "<to>"` |
- | Find a station code / disambiguate a name | `mtr_stations` | `mtr-hk stations "<query>"` |
- | List lines and stations, including Light Rail | `mtr_lines` | `mtr-hk lines [--stations]` |
- | Lifts, ramps, accessible toilets, step-free exits | `mtr_station_facilities` | `mtr-hk facilities "<station>"` |
- | Light Rail arrivals | `mtr_light_rail_next_trains` | `mtr-hk lr-next "<stop>"` |
- | Light Rail routes and stops | `mtr_light_rail_routes` | `mtr-hk lr-routes [query]` |
- | Light Rail fares | `mtr_light_rail_fares` | `mtr-hk lr-fares "<from>" "<to>"` |
- | MTR Bus / feeder bus arrivals | `mtr_bus_next_trains` | `mtr-hk bus-next <route>` |
- | MTR Bus routes and stops | `mtr_bus_routes` | `mtr-hk bus-routes [query]` |
- | Ferry operators, routes, piers and fares | `mtr_ferries` | `mtr-hk ferries [query]` |
- | Live ferry ETA | `mtr_ferry_eta` | `mtr-hk ferry-eta <operator> <route>` |
- ## Workflows
- ### 1. MTR service status and delays
- 1. Call `mtr_status` with no line for a network-wide answer, or with a line code/name when the user named one.
- 2. Read `overall` plus `summary`: `delayedLines`, `disruptedLines`, `typhoonLines`, `specialLines`, `nonServiceLines` and `noticeCount`. `overall` can be `normal`, `delay`, `disruption`, `special`, `typhoon` or `non-service`.
- 3. If any line is `yellow`/`red`/`pink`/`typhoon`, call `mtr_alerts` for that line to get the cause and advice.
- 4. Answer with: overall condition, affected line(s), what passengers should expect, and any alternative arrangement mentioned in the notice.
- 5. Include the feed's last-updated time (`updatedAtHkt`). Do not describe a line as delayed if `mtr_status` says normal.
- `mtr_alerts` classifies each item as `disruption`, `delay`, `notice` or `record`, and includes `lineNames`. Planned notices (early last trains, engineering works) are `notice`. Historical LateCert disruption PDFs are `record`, not live disruptions. Current status comes from `mtr_status`; a LateCert against a green line is a past event.
- For a typhoon, say a Tropical Cyclone Warning Signal is affecting service and report the affected lines/arrangements from the notice; do not reduce it to a generic delay.
- ### 2. Next trains
- 1. If the station name is ambiguous, call `mtr_stations` first.
- 2. Call `mtr_next_trains` with the station; add `line` for interchanges.
- 3. Present the next 2–3 trains per direction with destination, minutes away and platform. Mention the line name, not just the code.
- 4. If the result says `delayed: true`, mention it and check `mtr_status`/`mtr_alerts`.
- 5. A station can be served by several lines; report each separately.
- 6. East Rail is included in the Next Train API and currently returns live departures. MTR has intermittently disabled the EAL feed (`NT-205 ERL line is disabled in CMS`); if that happens, report the outage and use the published first/last-train and headway information. Never invent an EAL arrival time.
- Direction is expressed by destination. `UP`/`DOWN` alone is not useful to a passenger.
- ### 3. Journey planning
- 1. Call `mtr_plan_journey` with origin and destination names or codes.
- 2. Present the fastest route first: total minutes, number of interchanges, fare, then the legs in order.
- 3. For each leg give the line, boarding station and platform, direction/towards, and alighting station. Include walking interchanges (e.g. Central ↔ Hong Kong) explicitly.
- 4. Offer an alternative route only when it is meaningfully different (different line, fewer interchanges, or much cheaper).
- 5. State that the journey time is a weekday-morning estimate and that actual times vary.
- Use `mtr_fares` for a standalone fare question; it gives the full passenger-category matrix from open data.
- ### 4. Light Rail and MTR Bus
- - Light Rail stops and heavy-rail stations can share names (e.g. Tuen Mun). Use the Light Rail tools only when the user means Light Rail; say which mode you are reporting.
- - Light Rail status is part of `mtr_status` (code `LR`); `mtr_alerts LR` returns any LR-related notices. Use `mtr_light_rail_routes` for all 11 routes, 22 directions and 68 stops, and accept partial route numbers (e.g. `51` finds 751).
- - For Light Rail next trains, give route number, destination, platform and minutes. Mark special routes and include any route remark. Stops accept a name, three-letter code or numeric stop ID.
- - `mtr_light_rail_routes` accepts a route number (partial when unambiguous), stop name, stop code or numeric stop ID.
- - For MTR Bus, give route, stop, direction and next departures. `mtr_bus_next_trains` also returns route-level service status/remarks, `suspendedStopCount` and per-stop suspension flags.
- - `mtr_bus_routes` accepts a route number/name **or a stop name**. Use a stop name (e.g. “Melody Garden”) to discover every MTR Bus route serving it.
- - MTR Bus route variants can run in different directions; report the direction name (origin → destination), not just the `O`/`I` code.
- - If the user has not named a stop, show the first relevant stops and ask which one they mean rather than dumping every stop.
- ### 5. Ferries
- `mtr_ferries` is the ferry directory. It covers:
- - **Local scheduled ferries:** Star Ferry, Sun Ferry, Hong Kong & Kowloon Ferry (HKKF), Discovery Bay Transportation, Park Island Transport, Fortune Ferry, Chuen Kee, Coral Sea, Tsui Wah, Peng Chau Kai To.
- - **Kaito and water taxi:** licensed small ferries and Hong Kong Water Taxi.
- - **Cross-boundary:** TurboJET, Cotai Water Jet and Chu Kong Passenger Transport (Macao and Guangdong ports).
- - **Dangerous-goods-only:** Hongkong & Yaumati Ferry (not a normal passenger service).
- Typical calls:
- ```text
- mtr_ferries
- mtr_ferries query="Cheung Chau"
- mtr_ferries operator="hkkf"
- mtr_ferries query="Macao"
- mtr_ferries include_routes=true
- ```
- What to report:
- 1. Operator name, route (origin → destination), journey time and full adult fare when present.
- 2. Whether live ETA is available. **Only HKKF and Sun Ferry publish live ETA APIs in this integration.** Star Ferry, Fortune Ferry, Park Island, Discovery Bay, kaito and cross-boundary operators do not; give their timetable/source link instead.
- 3. For HKKF/Sun Ferry, call `mtr_ferry_eta` with the operator id and route code. HKKF accepts `outbound`/`inbound` direction. Present departure time and minutes away.
- 4. The Transport Department's `fullFare` is the published full adult fare, not every concession/round-trip/monthly fare. For exact concession or resident fares, use the operator's fare table.
- 5. Kaito/water-taxi services can be seasonal, bookable or demand-responsive. Say so rather than implying a turn-up-and-go commuter service.
- 6. Cross-boundary ferry questions involve immigration/terminal requirements; route data is a directory, not a booking or border-advice service.
- Examples:
- ```bash
- mtr-hk ferries
- mtr-hk ferries "Cheung Chau"
- mtr-hk ferries --operator=sun-ferry
- mtr-hk ferry-eta sun-ferry CECC
- mtr-hk ferry-eta hkkf 1 --direction=outbound
- ```
- ### 6. Accessibility
- `mtr_station_facilities` returns static barrier-free facility records: lifts, ramps, wide gates, accessible toilets, tactile guidance, induction loops and step-free exit information. It is not live lift/escalator outage data. If the user needs live lift status, say it is not available from these feeds and suggest checking MTR Mobile or station staff. Ferry accessibility is not consistently published; direct the user to the operator.
- ## Handling input and errors
- - Accept English, Traditional Chinese, Simplified Chinese and station codes (e.g. `ADM`, `金鐘`, `Admiralty`).
- - If a tool returns an error with suggestions, retry once with the suggested station/line/operator. If still ambiguous, ask the user which one they mean.
- - If an upstream call fails, report the failure plainly. Do not fall back to guessed schedules.
- - Do not call every tool for a simple question. One status call is enough for "is the MTR normal?".
- ## Data freshness and limits
- - Service status: refreshed roughly every 3 minutes upstream (`refreshSeconds` says 180); cached about 20 seconds. It exposes both GMT and HKT timestamps.
- - Next trains / Light Rail / Bus: near real-time; do not cache in your answer beyond the current request. East Rail is included when MTR's feed is enabled. If the upstream returns `NT-205`, the CLI prints an explicit fallback and the MCP result carries a warning instead of pretending there are no trains.
- - Traffic notices: cached about 1 minute; `counts` breaks down active/disruption/delay/notice/record items.
- - Fares, routes, stops and facilities: static open data, refreshed every few hours.
- - Ferry routes/fares: Transport Department dataset, cached 6 hours. Live HKKF/Sun Ferry ETAs are fetched per request.
- - Journey times are estimates based on weekday morning traffic.
- - Fares are in HKD; distinguish Octopus from single-journey tickets.
- - Airport Express fares come from the trip planner because the open-data fare matrix excludes AEL.
- - High Speed Rail (West Kowloon) is listed but is not covered by the metro next-train or journey tools.
- - Ferry route coverage is the TD's franchised/licensed dataset plus a curated operator directory. Private charters, hotel shuttles and unscheduled boats are out of scope.
- - These endpoints are unofficial. Do not scrape aggressively, and do not present the data as an official MTR, ferry operator or Transport Department service.
- ## Response style
- - Lead with the answer, then the detail.
- - Use Hong Kong local time and `minutes` for imminent arrivals; use clock times only when the source provides them.
- - For disruptions, be factual: line, status, cause if given, expected impact, alternative if given.
- - Mention the data timestamp when reporting service status.
- - Keep fare answers concise: adult Octopus and adult single journey are usually enough unless the user asks about concessions. For ferries, say the published full fare and point to the operator for concessions.
- - State the mode clearly: heavy rail, Light Rail, MTR Bus or ferry.
- ## References
- - `references/api-notes.md` — endpoints, parameters, response shapes, ferry sources and limitations.
- - `references/cli.md` — full CLI reference and examples.
- ### Install the binary directly
- `npx skills add` installs the skill files. If the binary is missing, install it
- with the release installer or cargo:
- ```bash
- curl -fsSL https://raw.githubusercontent.com/hongkong-ai-labs/hongkong-mtr-skill/main/scripts/install.sh | sh
- Note: Pipes a downloaded script directly into a shell (curl | sh / wget | bash)
- Line 270 on GitHub
- # or
- cargo install --git https://github.com/hongkong-ai-labs/hongkong-mtr-skill --locked
- ```
- Register it with any MCP client:
- ```bash
- npx add-mcp "$(command -v mtr-hk-mcp)" --name mtr-hk -a claude-code -a codex -a cursor -y
- claude mcp add mtr-hk -- mtr-hk-mcp
- codex mcp add mtr-hk -- mtr-hk-mcp
- ```
- `add-mcp` detects the client configuration files in the current project; add
- `-g` for a global install. `$(command -v mtr-hk-mcp)` keeps the entry correct
- when the binary is on `PATH`; substitute an absolute path if your client does
- not inherit the shell `PATH`.
README.md · README · 464 lines · 1 finding marked
- # Hong Kong MTR + ferry — MCP server + agent skill
- A comprehensive Hong Kong transport integration for AI agents, written in Rust:
- - **MCP server** (stdio and Streamable HTTP/SSE) with **15 tools** for live MTR status, delays, notices, next trains, journey planning, fares, Light Rail, MTR Bus, station accessibility, ferry operators/routes and live ferry ETAs.
- - **Agent skill** (`skills/mtr/SKILL.md`) that teaches an agent when and how to use each tool, with a CLI fallback.
- - **CLI** sharing the same service layer for scripting and manual checks.
- MTR data comes from MTR's public open data plus the traffic-news and trip-planner endpoints used by MTR's own website/app. Ferry route/fare data comes from the Transport Department; live ferry ETAs come from HKKF and Sun Ferry. No browser automation, no login and no data API key are required; the HTTP MCP transport can optionally require a static API key.
- ## Quick start
- Requires **Rust 1.89+** (`rustup` recommended).
- ```bash
- cargo install --path .
- # or directly from GitHub:
- cargo install --git https://github.com/hongkong-ai-labs/hongkong-mtr-skill --locked
- mtr-hk status
- mtr-hk ferries
- ```
- This installs three binaries into `~/.cargo/bin`:
- - `mtr-hk-mcp` — MCP stdio server
- - `mtr-hk-mcp-http` — MCP Streamable HTTP/SSE server
- - `mtr-hk` — CLI
- If the commands are not found, add Cargo's bin directory to `PATH`:
- ```bash
- export PATH="$HOME/.cargo/bin:$PATH"
- ```
- For development without installing:
- ```bash
- cargo build --release --bins
- ./target/release/mtr-hk status
- ./target/release/mtr-hk-mcp
- ```
- ### Other install routes
- Prebuilt binaries for macOS (Intel or Apple silicon) and Linux (x86_64 or
- aarch64, static musl) are checksum-verified by the installer:
- ```bash
- curl -fsSL https://raw.githubusercontent.com/hongkong-ai-labs/hongkong-mtr-skill/main/scripts/install.sh | sh
- Note: Pipes a downloaded script directly into a shell (curl | sh / wget | bash)
- Line 49 on GitHub
- ```
- As an agent skill:
- ```bash
- npx skills add hongkong-ai-labs/hongkong-mtr-skill
- npx skills update # refresh the installed skill later
- ```
- Docker, Apple container and a pure Cloudflare Workers (V8 isolate) deployment
- are described below. The native binaries keep stdio and Streamable HTTP/SSE;
- the Worker reuses the same Rust service layer through a Workers `fetch` backend.
- ### Register the MCP server
- The included `.mcp.json` uses the installed binary:
- ```json
- {
- "mcpServers": {
- "mtr-hk": {
- "command": "mtr-hk-mcp",
- "args": []
- }
- }
- }
- ```
- Register it with any MCP client:
- ```bash
- npx add-mcp "$(command -v mtr-hk-mcp)" --name mtr-hk -a claude-code -a codex -a cursor -y
- claude mcp add mtr-hk -- mtr-hk-mcp
- codex mcp add mtr-hk -- mtr-hk-mcp
- ```
- `add-mcp` detects the client configuration files in the current project; add
- `-g` for a global install. Substitute an absolute path if your client does not
- inherit the shell `PATH`.
- For Claude Code, Claude Desktop, Cursor or any stdio MCP client, use the same command. If the client does not inherit your shell `PATH`, set `command` to the absolute path, e.g. `/Users/you/.cargo/bin/mtr-hk-mcp`.
- ### Remote HTTP/SSE MCP
- The HTTP binary exposes the same 15 tools over Streamable HTTP at `/mcp`, with a `/health` endpoint:
- ```bash
- MTR_HTTP_ADDR=0.0.0.0:8080 MTR_MCP_API_KEY="$SECRET" mtr-hk-mcp-http
- ```
- ```bash
- claude mcp add --transport http mtr-hk http://localhost:8080/mcp
- ```
- The `/mcp` endpoint returns JSON or SSE-framed responses depending on the client. Set `MTR_MCP_API_KEY` (or `MTR_API_KEY` / `MTR_AUTH_TOKEN`) to require `Authorization: Bearer <key>` or `X-API-Key: <key>`; `/health` stays public. Without a key there is no authentication, so do not expose it directly to the public internet.
- ### Containers
- Build one image containing the CLI and both MCP transports:
- ```bash
- docker build -t mtr-hk-mcp .
- docker run --rm -p 8080:8080 mtr-hk-mcp
- ```
- Run the stdio server instead:
- ```bash
- docker run --rm -i --entrypoint mtr-hk-mcp mtr-hk-mcp
- ```
- Or use Compose:
- ```bash
- docker compose up --build http
- ```
- Apple's `container` runtime uses the same OCI image:
- ```bash
- container build -t mtr-hk-mcp .
- container run --rm -p 8080:8080 mtr-hk-mcp
- container run --rm -i --entrypoint mtr-hk-mcp mtr-hk-mcp
- ```
- The image defaults to the HTTP server on port 8080. It runs as a non-root user and includes a `/health` check.
- ### Cloudflare Workers (pure WASM)
- The root `wrangler.jsonc` deploys a true `wasm32-unknown-unknown` Worker on the
- Cloudflare V8 isolate runtime. It does not use a Container, Docker, Tokio or
- TCP; the shared service layer talks to MTR through the Workers `fetch` API and
- exposes the same 15 MCP tools at `/mcp`. Native stdio and the full
- Streamable HTTP/SSE server remain available from the binaries above.
- Prerequisites: Rust 1.89 with the WASM target, `worker-build`, Node.js and a
- Cloudflare account.
- ```bash
- rustup target add wasm32-unknown-unknown --toolchain 1.89.0
- cargo install worker-build@0.8.0
- npx wrangler login
- npx wrangler secret put MTR_MCP_API_KEY # optional
- npx wrangler deploy
- ```
- The MCP endpoint is:
- ```text
- https://<worker-name>.<account>.workers.dev/mcp
- ```
- ```bash
- claude mcp add --transport http mtr-hk \
- https://<worker-name>.<account>.workers.dev/mcp
- ```
- When `MTR_MCP_API_KEY` is set, `/mcp` requires `Authorization: Bearer <key>` or
- `X-API-Key: <key>`; `/health` stays public. The Worker is stateless across
- requests except for per-isolate caches, and it accepts POST requests at `/mcp`
- (Streamable HTTP JSON responses). It intentionally has no stdio, CLI or legacy
- SSE endpoint.
- Run the Worker locally without Docker:
- ```bash
- npx wrangler dev --port 8787
- curl http://localhost:8787/health
- ```
- Use `--var MTR_MCP_API_KEY:test-key` to exercise authentication locally. See
- [`cloudflare/README.md`](cloudflare/README.md) for the Worker layout and
- operational notes.
- ### Cloudflare Container (legacy fallback)
- The earlier container-backed Worker is still available for accounts that need
- the native HTTP server inside a Cloudflare Container. It requires Docker and
- Containers enabled on the account:
- ```bash
- cd cloudflare
- npx wrangler secret put MTR_MCP_API_KEY -c wrangler.container.jsonc # optional
- npx wrangler deploy -c wrangler.container.jsonc
- ```
- ### Install the skill
- ```bash
- mkdir -p ~/.claude/skills
- ln -sfn "$PWD/skills/mtr" ~/.claude/skills/mtr
- ```
- The repository also contains `.claude/skills/mtr` as a symlink, so project-local clients discover it.
- ## Tools
- | Tool | What it returns |
- |---|---|
- | `mtr_status` | Live line status for all 10 metro lines + Light Rail, overall condition, delay/disruption summary, HKT last update, matching notices |
- | `mtr_alerts` | Current traffic news with severity, affected line names, full content, disruption PDFs and planned works |
- | `mtr_next_trains` | Next up to 4 trains per direction at a station, destination, platform, delay flag |
- | `mtr_plan_journey` | Fastest routes with time, interchange count, fares and step-by-step legs |
- | `mtr_fares` | Heavy-rail fare matrix by passenger category, Octopus vs single journey |
- | `mtr_stations` | Search stations by English/Chinese name or code, with lines and coordinates |
- | `mtr_lines` | Line codes, bilingual names, colours, station counts, real-time availability, plus a Light Rail summary |
- | `mtr_station_facilities` | Barrier-free facilities: lifts, ramps, wide gates, accessible toilets, tactile guidance |
- | `mtr_light_rail_next_trains` | Light Rail predictions by platform, route, destination, special-route flag and remarks |
- | `mtr_light_rail_routes` | All Light Rail routes, ordered stops, partial route lookup, or routes serving a stop |
- | `mtr_light_rail_fares` | Light Rail Octopus and single-journey fares |
- | `mtr_bus_next_trains` | MTR Bus/feeder bus arrival estimates, route status, suspension flags and fares |
- | `mtr_bus_routes` | Bus route or stop search, variants, fares and stops in both directions |
- | `mtr_ferries` | 16 ferry operators and 58 TD routes; search by route, pier, island, district or operator |
- | `mtr_ferry_eta` | Live next sailings for HKKF and Sun Ferry; timetable/source guidance for other operators |
- All tools return JSON. Station, line and ferry arguments accept English, Traditional Chinese, Simplified Chinese and codes. Ambiguous input returns a tool error with suggestions instead of guessing.
- ## Light Rail and MTR Bus coverage
- **Light Rail (LR)**
- - Live LR line status and delay notices via `mtr_status` / `mtr_alerts` (`LR`).
- - Next trains at any of the 68 stops, grouped by platform, including special routes.
- - All 11 routes and 22 directions with ordered stops; partial route lookup (`51` → 751) and stop-based route discovery.
- - Octopus and single-journey LR fares between any two stops.
- **MTR Bus and feeder buses**
- - All MTR Bus/feeder routes from the open-data route, stop and fare datasets.
- - Next-bus estimates per stop, with direction, delay flag, scheduled flag, suspension status and route-level service remarks.
- - Route discovery by route number/name **or stop name** (e.g. “Melody Garden” → route 506).
- - Route variants, both directions, ordered stops, coordinates and fares.
- Heavy rail, Light Rail and bus data are separate modes: station/stop names can repeat (e.g. Tuen Mun), so the tool and skill state which mode is being reported.
- ## Ferry coverage
- `mtr_ferries` combines the Transport Department's franchised/licensed ferry route and fare dataset with a curated operator directory.
- **16 operators covered:**
- - Local scheduled: Star Ferry, Sun Ferry, Hong Kong & Kowloon Ferry (HKKF), Discovery Bay Transportation, Park Island Transport, Fortune Ferry, Chuen Kee, Coral Sea, Tsui Wah, Peng Chau Kai To.
- - Kaito/water taxi: Kaito / licensed small ferries, Hong Kong Water Taxi.
- - Cross-boundary: TurboJET, Cotai Water Jet, Chu Kong Passenger Transport.
- - Dangerous-goods-only: Hongkong & Yaumati Ferry.
- **Route/fare fields:** operator, route name in English/Traditional/Simplified Chinese, district, journey minutes, origin/destination, published adult full fare, TD source link and live-ETA availability. At the time of writing the dataset has 58 routes across Victoria Harbour, outlying islands, kaito and water-taxi services.
- **Live ETAs:** only HKKF and Sun Ferry expose public ETA APIs integrated here.
- ```bash
- mtr-hk ferry-eta sun-ferry CECC
- mtr-hk ferry-eta hkkf 1 --direction=outbound
- ```
- Star Ferry, Fortune Ferry, Park Island, Discovery Bay, kaito and cross-boundary operators do not provide a public live ETA API; the tool returns `live: false` with the official timetable/source link. Kaito/water-taxi services can be seasonal, bookable or demand-responsive.
- ## Real-time news and delays
- - **Line status** comes from MTR's traffic-news status feed behind its service-status page. `overall` is `normal`, `delay`, `disruption`, `special`, `typhoon` or `non-service`, with a `summary` listing the affected line codes and a notice count. Timestamps are returned in GMT and HKT, plus the upstream refresh interval.
- - **Traffic news** comes from MTR's `alert.json` and `latecert.json`. Each item is classified as `disruption`, `delay`, `notice` or `record`, includes affected line codes and names, and carries the full notice body. `hasMap`, `hasShuttleBus` and `hasAlternativeTransport` flag notices with extra arrangements; LateCert items link to MTR's disruption-notification PDF.
- - **Next-train delay flags** are surfaced by `mtr_next_trains` (`delayed`), and Light Rail status/notices use the same LR status feed.
- - **Bus service status** is surfaced by `mtr_bus_next_trains`: route status code/colour/remarks, refresh time, per-stop suspension flags and `suspendedStopCount`.
- - Historical LateCert records are kept by MTR after service normalises. They are marked `record` and are **not** treated as current disruptions; the live status feed is authoritative.
- `mtr-hk update` detects whether the binary came from cargo, the release
- installer, a source checkout or Homebrew, and updates with that same
- method. `mtr-hk update --check` only reports.
- ## CLI
- ```bash
- mtr-hk status
- mtr-hk alerts --lang=tc
- mtr-hk next "Tsim Sha Tsui" --line=TWL
- mtr-hk journey Admiralty "Tung Chung"
- mtr-hk fares "Hong Kong" Airport
- mtr-hk stations 金鐘
- mtr-hk lines --stations
- mtr-hk facilities Admiralty
- mtr-hk lr-next "Tuen Mun Ferry Pier" --route=507
- mtr-hk lr-routes 507
- mtr-hk lr-routes "Tin King"
- mtr-hk lr-fares "Tuen Mun Ferry Pier" "Tin King"
- mtr-hk bus-next 506 --stop="Tuen Mun Ferry Pier"
- mtr-hk bus-routes K12
- mtr-hk bus-routes "Melody Garden"
- mtr-hk ferries
- mtr-hk ferries "Cheung Chau"
- mtr-hk ferries --operator=sun-ferry
- mtr-hk ferry-eta sun-ferry CECC
- mtr-hk ferry-eta hkkf 1
- mtr-hk update --check
- ```
- Add `--json` for structured output. From the skill, use the wrapper:
- ```bash
- skills/mtr/scripts/mtr status
- ```
- Full CLI reference: [`skills/mtr/references/cli.md`](skills/mtr/references/cli.md).
- ## Data sources
- | Data | Source |
- |---|---|
- | Heavy-rail next trains | `https://rt.data.gov.hk/v1/transport/mtr/getSchedule.php` (data.gov.hk) |
- | Light Rail next trains | `https://rt.data.gov.hk/v1/transport/mtr/lrt/getSchedule` |
- | MTR Bus ETA | `https://rt.data.gov.hk/v1/transport/mtr/bus/getSchedule` |
- | Live line status | `https://tnews.mtr.com.hk/alert/ryg_line_status.xml` — the feed behind MTR's service-status page |
- | Traffic news / disruption notices | `https://tnews.mtr.com.hk/alert/alert.json` + `latecert.json` |
- | Journey planner | `https://proxy001.api.mtr.com.hk/ttp-api/v2/api/Path/HRRoutes/` — the API used by MTR's web trip planner |
- | Station/line catalogue | `HRStations/` trip-planner API, with CSV fallback |
- | MTR fares, routes, stops, accessibility | MTR open-data CSVs under `https://opendata.mtr.com.hk/data/` |
- | Ferry routes and full fares | `https://static.data.gov.hk/td/routes-fares-xml/ROUTE_FERRY.xml` |
- | HKKF live ETA | `https://www.hkkfeta.com/opendata/route/` and `/opendata/eta/{route_id}/{direction}` |
- | Sun Ferry live ETA | `https://www.sunferry.com.hk/eta/?route={route_code}` |
- Official datasets:
- - [Real-time MTR train information](https://data.gov.hk/en-data/dataset/mtr-data2-nexttrain-data)
- - [MTR routes, fares and barrier-free facilities](https://data.gov.hk/en-data/dataset/mtr-data-routes-fares-barrier-free-facilities)
- - [Real-time MTR Bus and feeder bus schedule](https://data.gov.hk/en-data/dataset/mtr-mtr_bus-mtr-bus-eta-data)
- - [Transport Department ferry routes and fares](https://data.gov.hk/en-data/dataset/hk-td-tis_14-routes-fares-xml)
- Detailed endpoint notes, response shapes, ferry sources and caveats: [`skills/mtr/references/api-notes.md`](skills/mtr/references/api-notes.md).
- ## Configuration
- Every endpoint can be overridden with environment variables:
- | Variable | Default |
- |---|---|
- | `MTR_NEXT_TRAIN_URL` | `https://rt.data.gov.hk/v1/transport/mtr/getSchedule.php` |
- | `MTR_LIGHT_RAIL_URL` | `https://rt.data.gov.hk/v1/transport/mtr/lrt/getSchedule` |
- | `MTR_BUS_URL` | `https://rt.data.gov.hk/v1/transport/mtr/bus/getSchedule` |
- | `MTR_STATUS_URL` | `https://tnews.mtr.com.hk/alert/ryg_line_status.xml` |
- | `MTR_LEGEND_URL` | `https://tnews.mtr.com.hk/alert/legend_remarks_v2.xml` |
- | `MTR_ALERTS_URL` | `https://tnews.mtr.com.hk/alert/alert.json` |
- | `MTR_LATECERT_URL` | `https://tnews.mtr.com.hk/alert/latecert.json` |
- | `MTR_LINE_CONFIG_URL` | `https://tnews.mtr.com.hk/alert/lineconfig.json` |
- | `MTR_STATIONS_API` | `https://proxy001.api.mtr.com.hk/ttp-api/v2/api/StationBaseInfo/HRStations/` |
- | `MTR_JOURNEY_API` | `https://proxy001.api.mtr.com.hk/ttp-api/v2/api/Path/HRRoutes/` |
- | `MTR_FERRY_ROUTES_URL` | `https://static.data.gov.hk/td/routes-fares-xml/ROUTE_FERRY.xml` |
- | `MTR_HKKF_ETA_BASE` | `https://www.hkkfeta.com/opendata/eta` |
- | `MTR_SUN_FERRY_ETA` | `https://www.sunferry.com.hk/eta/` |
- | `MTR_TTP_API_KEY` | Public key from MTR's front-end config (override if rotated) |
- | `MTR_HTTP_TIMEOUT_MS` | `12000` |
- The trip-planner key is a public client key embedded in MTR's own `config.json`; it is not a user secret. It can change, hence the override.
- ## Architecture
- ```
- src/
- config.rs endpoint + cache configuration
- constants.rs stable MTR line metadata
- model.rs normalized domain types
- app.rs shared app object and TTL caches
- http.rs HTTP backend trait + native reqwest client
- cache.rs typed TTL cache and de-duplication
- csvutil.rs RFC-4180 CSV helpers
- text.rs alert HTML -> readable text
- network.rs station/line catalogue + CSV fallback
- fares.rs heavy-rail fare matrix
- light_rail.rs Light Rail routes/stops/fares
- bus.rs MTR Bus routes/stops/fares
- facilities.rs barrier-free facilities
- alerts.rs traffic news and LateCert records
- status.rs live service status + notice merge
- next_train.rs heavy-rail next trains
- journey.rs trip planner + leg grouping
- services.rs shared high-level MTR tool services
- ferries.rs ferry operators, TD routes/fares, live HKKF/Sun ETA
- server.rs MCP tool registration + stdio/HTTP transports
- cli.rs CLI
- bin/mtr-hk-mcp.rs MCP stdio entry point
- bin/mtr-hk-mcp-http.rs MCP Streamable HTTP/SSE entry point
- bin/mtr-hk.rs CLI entry point
- src/lib.rs library root (native modules feature-gated)
- worker/ pure Workers WASM crate + MCP JSON-RPC handler
- worker/build.sh WASM build pinned to Rust 1.89
- wrangler.jsonc pure Cloudflare Workers config
- Dockerfile OCI image for CLI + stdio + HTTP MCP
- compose.yaml local HTTP and stdio container profiles
- cloudflare/src/ legacy Container front door and lifecycle
- cloudflare/README.md Worker deployment notes
- cloudflare/wrangler.container.jsonc legacy Container config
- skills/mtr/
- SKILL.md agent instructions
- references/ API and CLI documentation
- scripts/mtr CLI wrapper
- scripts/
- smoke.sh live checks for every data source
- mcp_smoke.py MCP stdio handshake + tool-call check
- mcp_http_smoke.py MCP Streamable HTTP/SSE handshake + tool-call check
- ```
- Caching: static datasets 6 hours, status 20 seconds, alerts 60 seconds, journey plans 60 seconds. Ferry routes/fares 6 hours. Next-train/LR/bus and ferry ETA predictions are not cached. Concurrent identical loads are de-duplicated.
- ## Releasing
- CI runs formatting, clippy with warnings as errors, tests, a release build of all
- three binaries, a `wasm32-unknown-unknown` check of `worker/`, and validates both
- `SKILL.md` files plus the shell scripts.
- Dependabot proposes weekly Cargo and GitHub Actions updates, and the audit
- workflow checks the lockfile against the RustSec advisory database.
- `just release 1.0.0` creates and pushes the annotated tag `v1.0.0`; the release
- workflow checks it against `Cargo.toml` and `CHANGELOG.md`, builds four targets,
- smoke-tests native binaries and publishes one tarball per target containing
- `mtr-hk`, `mtr-hk-mcp`, `mtr-hk-mcp-http` and `LICENSE`, plus `SHA256SUMS`.
- `scripts/install.sh` verifies the checksum and installs all three binaries, with
- a `cargo build --release --locked --bins` fallback.
- ## Development
- ```bash
- just # fmt check, clippy with -D warnings, tests
- just skill-check # validate both SKILL.md files and shell syntax
- just worker-check # type-check the pure-WASM Worker
- cargo build --release --locked --bins
- scripts/smoke.sh
- python3 scripts/mcp_smoke.py
- MTR_HTTP_ADDR=127.0.0.1:8080 ./target/release/mtr-hk-mcp-http &
- python3 scripts/mcp_http_smoke.py
- ```
- `rust-toolchain.toml` pins the stable toolchain with `rustfmt` and
- `clippy`, so `rustup` sets contributors up automatically. `just doc`
- builds the API documentation. See `CONTRIBUTING.md` for the full check
- list and the signed-commit requirement.
- `cargo test` is offline and covers CSV/HTML/network canonicalization/fares/routes/journey legs/status severity/ferry classification. The smoke scripts need network access.
- ## Limitations
- - **Unofficial.** These are public/observed endpoints, not a supported MTR, ferry operator or Transport Department API contract. They can change or rate-limit.
- - **Not safety-critical.** Arrival times, journey times and fares are estimates.
- - **Live lift outages are not available.** `mtr_station_facilities` is static open data.
- - **Journey times** are based on weekday morning traffic, per MTR's own disclaimer.
- - **Airport Express fares** come from the trip planner because the open-data fare matrix excludes AEL.
- - **High Speed Rail (West Kowloon)** appears in the line list but is not covered by metro next-train or journey tools.
- - **LateCert records** are disruption PDFs kept after service normalises. The live status feed is the authoritative signal for current delays.
- - **Ferry live ETA is limited to HKKF and Sun Ferry.** Other operators expose timetables or booking pages, not a public ETA API.
- - **Ferry full fares** are the published adult single fare from TD; concessions, monthly passes and resident fares are not exhaustive.
- - **Kaito/water-taxi/cross-boundary** services can be seasonal, bookable or subject to immigration/terminal rules.
- - **Cloudflare Workers is stateless and POST-only.** The pure V8-isolate Worker exposes the 15 tools over Streamable HTTP JSON at `/mcp`; use the native HTTP binary for legacy SSE. Per-isolate caches are not shared across Cloudflare instances.
- - **Remote authentication is a single static API key.** Set `MTR_MCP_API_KEY` to protect `/mcp`; put Cloudflare Access or OAuth in front of a public deployment if you need per-user identity.
- - **Traditional/Simplified Chinese** matching is exact for Chinese names; use `mtr_stations` if a name variant is not found.
- ## License
- MIT. MTR data is owned by MTR Corporation Limited. Ferry data is owned by the Transport Department and the respective operators, subject to the data.gov.hk terms of use.
Ratings and comments
Sign in to rate this skill.
Sign inFree to use. If it’s helped, pass it on.