Skip to content
Back to search

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
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/hongkong-ai-labs--hongkong-mtr-skill/badge.svg)](/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

i

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
  1. ---
  2. name: hongkong-mtr-skill
  3. 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.
  4. ---
  5. # Hong Kong MTR and ferries
  6. 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).
  7. 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.
  8. ## Install (Rust)
  9. The server and CLI are Rust binaries. Node/npm are **not** required.
  10. Prerequisites:
  11. - Rust 1.89 or newer, including `cargo` (`rustup` is the easiest install: <https://rustup.rs>).
  12. - `~/.cargo/bin` on `PATH` (the Rust installer normally adds it).
  13. From the repository root:
  14. ```bash
  15. cargo install --path .
  16. ```
  17. This installs three binaries into `~/.cargo/bin`:
  18. ```bash
  19. mtr-hk-mcp # MCP stdio server
  20. mtr-hk-mcp-http # MCP Streamable HTTP/SSE server
  21. mtr-hk # human/JSON CLI
  22. ```
  23. Verify:
  24. ```bash
  25. mtr-hk status
  26. mtr-hk ferries
  27. command -v mtr-hk-mcp
  28. ```
  29. If `mtr-hk` is not found, add Cargo's bin directory to your shell profile:
  30. ```bash
  31. export PATH="$HOME/.cargo/bin:$PATH"
  32. ```
  33. For development without installing:
  34. ```bash
  35. cargo build --release
  36. ./target/release/mtr-hk status
  37. ./target/release/mtr-hk-mcp
  38. ```
  39. ### Register the MCP server
  40. Use the installed binary in Claude Code, Claude Desktop, Cursor or any stdio MCP client:
  41. ```json
  42. {
  43. "mcpServers": {
  44. "mtr-hk": {
  45. "command": "mtr-hk-mcp",
  46. "args": []
  47. }
  48. }
  49. }
  50. ```
  51. 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"`.
  52. ### Remote HTTP/SSE MCP
  53. For a remote or container deployment, run:
  54. ```bash
  55. MTR_HTTP_ADDR=0.0.0.0:8080 mtr-hk-mcp-http
  56. ```
  57. and point an HTTP MCP client at `http://localhost:8080/mcp`. The endpoint
  58. supports Streamable HTTP and SSE-framed responses. Set an optional static key
  59. with `MTR_MCP_API_KEY` (aliases `MTR_API_KEY`, `MTR_AUTH_TOKEN`) or `--api-key`;
  60. requests then need `Authorization: Bearer <key>` or `X-API-Key: <key>`, while
  61. `/health` stays public. Without a key there is no authentication, so do not
  62. expose it directly to the public internet.
  63. The repository also contains a `Dockerfile`, `compose.yaml`, and a pure
  64. Cloudflare Workers (V8 isolate) deployment rooted at `wrangler.jsonc` with the
  65. Rust Worker in `worker/`. The Worker exposes the same 15 tools at `/mcp`; see
  66. `README.md` and `cloudflare/README.md` for deployment and authentication
  67. details.
  68. ### Install the agent skill
  69. Link this directory into your client's skills folder:
  70. ```bash
  71. mkdir -p ~/.claude/skills
  72. ln -sfn "$PWD/skills/mtr" ~/.claude/skills/mtr
  73. ```
  74. The repository also has `.claude/skills/mtr` linked to `../../skills/mtr` for project-local discovery.
  75. ### CLI fallback
  76. If MCP tools are unavailable, use the installed CLI or the repository wrapper:
  77. ```bash
  78. mtr-hk status
  79. mtr-hk next "Tsim Sha Tsui" --line=TWL
  80. mtr-hk journey Admiralty "Tung Chung"
  81. mtr-hk ferries "Cheung Chau"
  82. skills/mtr/scripts/mtr status
  83. mtr-hk update --check
  84. ```
  85. 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`.
  86. ## Choose the right tool
  87. | Question | MCP tool | CLI fallback |
  88. |---|---|---|
  89. | Is the MTR running normally? Any delays? | `mtr_status` | `mtr-hk status` |
  90. | What do the current traffic notices say? | `mtr_alerts` | `mtr-hk alerts` |
  91. | Next trains at a station | `mtr_next_trains` | `mtr-hk next "<station>"` |
  92. | Best route between two MTR stations | `mtr_plan_journey` | `mtr-hk journey "<from>" "<to>"` |
  93. | Fare between two MTR stations | `mtr_fares` | `mtr-hk fares "<from>" "<to>"` |
  94. | Find a station code / disambiguate a name | `mtr_stations` | `mtr-hk stations "<query>"` |
  95. | List lines and stations, including Light Rail | `mtr_lines` | `mtr-hk lines [--stations]` |
  96. | Lifts, ramps, accessible toilets, step-free exits | `mtr_station_facilities` | `mtr-hk facilities "<station>"` |
  97. | Light Rail arrivals | `mtr_light_rail_next_trains` | `mtr-hk lr-next "<stop>"` |
  98. | Light Rail routes and stops | `mtr_light_rail_routes` | `mtr-hk lr-routes [query]` |
  99. | Light Rail fares | `mtr_light_rail_fares` | `mtr-hk lr-fares "<from>" "<to>"` |
  100. | MTR Bus / feeder bus arrivals | `mtr_bus_next_trains` | `mtr-hk bus-next <route>` |
  101. | MTR Bus routes and stops | `mtr_bus_routes` | `mtr-hk bus-routes [query]` |
  102. | Ferry operators, routes, piers and fares | `mtr_ferries` | `mtr-hk ferries [query]` |
  103. | Live ferry ETA | `mtr_ferry_eta` | `mtr-hk ferry-eta <operator> <route>` |
  104. ## Workflows
  105. ### 1. MTR service status and delays
  106. 1. Call `mtr_status` with no line for a network-wide answer, or with a line code/name when the user named one.
  107. 2. Read `overall` plus `summary`: `delayedLines`, `disruptedLines`, `typhoonLines`, `specialLines`, `nonServiceLines` and `noticeCount`. `overall` can be `normal`, `delay`, `disruption`, `special`, `typhoon` or `non-service`.
  108. 3. If any line is `yellow`/`red`/`pink`/`typhoon`, call `mtr_alerts` for that line to get the cause and advice.
  109. 4. Answer with: overall condition, affected line(s), what passengers should expect, and any alternative arrangement mentioned in the notice.
  110. 5. Include the feed's last-updated time (`updatedAtHkt`). Do not describe a line as delayed if `mtr_status` says normal.
  111. `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.
  112. 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.
  113. ### 2. Next trains
  114. 1. If the station name is ambiguous, call `mtr_stations` first.
  115. 2. Call `mtr_next_trains` with the station; add `line` for interchanges.
  116. 3. Present the next 2–3 trains per direction with destination, minutes away and platform. Mention the line name, not just the code.
  117. 4. If the result says `delayed: true`, mention it and check `mtr_status`/`mtr_alerts`.
  118. 5. A station can be served by several lines; report each separately.
  119. 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.
  120. Direction is expressed by destination. `UP`/`DOWN` alone is not useful to a passenger.
  121. ### 3. Journey planning
  122. 1. Call `mtr_plan_journey` with origin and destination names or codes.
  123. 2. Present the fastest route first: total minutes, number of interchanges, fare, then the legs in order.
  124. 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.
  125. 4. Offer an alternative route only when it is meaningfully different (different line, fewer interchanges, or much cheaper).
  126. 5. State that the journey time is a weekday-morning estimate and that actual times vary.
  127. Use `mtr_fares` for a standalone fare question; it gives the full passenger-category matrix from open data.
  128. ### 4. Light Rail and MTR Bus
  129. - 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.
  130. - 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).
  131. - 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.
  132. - `mtr_light_rail_routes` accepts a route number (partial when unambiguous), stop name, stop code or numeric stop ID.
  133. - 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.
  134. - `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.
  135. - MTR Bus route variants can run in different directions; report the direction name (origin → destination), not just the `O`/`I` code.
  136. - If the user has not named a stop, show the first relevant stops and ask which one they mean rather than dumping every stop.
  137. ### 5. Ferries
  138. `mtr_ferries` is the ferry directory. It covers:
  139. - **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.
  140. - **Kaito and water taxi:** licensed small ferries and Hong Kong Water Taxi.
  141. - **Cross-boundary:** TurboJET, Cotai Water Jet and Chu Kong Passenger Transport (Macao and Guangdong ports).
  142. - **Dangerous-goods-only:** Hongkong & Yaumati Ferry (not a normal passenger service).
  143. Typical calls:
  144. ```text
  145. mtr_ferries
  146. mtr_ferries query="Cheung Chau"
  147. mtr_ferries operator="hkkf"
  148. mtr_ferries query="Macao"
  149. mtr_ferries include_routes=true
  150. ```
  151. What to report:
  152. 1. Operator name, route (origin → destination), journey time and full adult fare when present.
  153. 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.
  154. 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.
  155. 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.
  156. 5. Kaito/water-taxi services can be seasonal, bookable or demand-responsive. Say so rather than implying a turn-up-and-go commuter service.
  157. 6. Cross-boundary ferry questions involve immigration/terminal requirements; route data is a directory, not a booking or border-advice service.
  158. Examples:
  159. ```bash
  160. mtr-hk ferries
  161. mtr-hk ferries "Cheung Chau"
  162. mtr-hk ferries --operator=sun-ferry
  163. mtr-hk ferry-eta sun-ferry CECC
  164. mtr-hk ferry-eta hkkf 1 --direction=outbound
  165. ```
  166. ### 6. Accessibility
  167. `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.
  168. ## Handling input and errors
  169. - Accept English, Traditional Chinese, Simplified Chinese and station codes (e.g. `ADM`, `金鐘`, `Admiralty`).
  170. - 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.
  171. - If an upstream call fails, report the failure plainly. Do not fall back to guessed schedules.
  172. - Do not call every tool for a simple question. One status call is enough for "is the MTR normal?".
  173. ## Data freshness and limits
  174. - Service status: refreshed roughly every 3 minutes upstream (`refreshSeconds` says 180); cached about 20 seconds. It exposes both GMT and HKT timestamps.
  175. - 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.
  176. - Traffic notices: cached about 1 minute; `counts` breaks down active/disruption/delay/notice/record items.
  177. - Fares, routes, stops and facilities: static open data, refreshed every few hours.
  178. - Ferry routes/fares: Transport Department dataset, cached 6 hours. Live HKKF/Sun Ferry ETAs are fetched per request.
  179. - Journey times are estimates based on weekday morning traffic.
  180. - Fares are in HKD; distinguish Octopus from single-journey tickets.
  181. - Airport Express fares come from the trip planner because the open-data fare matrix excludes AEL.
  182. - High Speed Rail (West Kowloon) is listed but is not covered by the metro next-train or journey tools.
  183. - 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.
  184. - These endpoints are unofficial. Do not scrape aggressively, and do not present the data as an official MTR, ferry operator or Transport Department service.
  185. ## Response style
  186. - Lead with the answer, then the detail.
  187. - Use Hong Kong local time and `minutes` for imminent arrivals; use clock times only when the source provides them.
  188. - For disruptions, be factual: line, status, cause if given, expected impact, alternative if given.
  189. - Mention the data timestamp when reporting service status.
  190. - 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.
  191. - State the mode clearly: heavy rail, Light Rail, MTR Bus or ferry.
  192. ## References
  193. - `references/api-notes.md` — endpoints, parameters, response shapes, ferry sources and limitations.
  194. - `references/cli.md` — full CLI reference and examples.
  195. ### Install the binary directly
  196. `npx skills add` installs the skill files. If the binary is missing, install it
  197. with the release installer or cargo:
  198. ```bash
  199. 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
  200. # or
  201. cargo install --git https://github.com/hongkong-ai-labs/hongkong-mtr-skill --locked
  202. ```
  203. Register it with any MCP client:
  204. ```bash
  205. npx add-mcp "$(command -v mtr-hk-mcp)" --name mtr-hk -a claude-code -a codex -a cursor -y
  206. claude mcp add mtr-hk -- mtr-hk-mcp
  207. codex mcp add mtr-hk -- mtr-hk-mcp
  208. ```
  209. `add-mcp` detects the client configuration files in the current project; add
  210. `-g` for a global install. `$(command -v mtr-hk-mcp)` keeps the entry correct
  211. when the binary is on `PATH`; substitute an absolute path if your client does
  212. not inherit the shell `PATH`.
README.md · README · 464 lines · 1 finding marked
  1. # Hong Kong MTR + ferry — MCP server + agent skill
  2. A comprehensive Hong Kong transport integration for AI agents, written in Rust:
  3. - **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.
  4. - **Agent skill** (`skills/mtr/SKILL.md`) that teaches an agent when and how to use each tool, with a CLI fallback.
  5. - **CLI** sharing the same service layer for scripting and manual checks.
  6. 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.
  7. ## Quick start
  8. Requires **Rust 1.89+** (`rustup` recommended).
  9. ```bash
  10. cargo install --path .
  11. # or directly from GitHub:
  12. cargo install --git https://github.com/hongkong-ai-labs/hongkong-mtr-skill --locked
  13. mtr-hk status
  14. mtr-hk ferries
  15. ```
  16. This installs three binaries into `~/.cargo/bin`:
  17. - `mtr-hk-mcp` — MCP stdio server
  18. - `mtr-hk-mcp-http` — MCP Streamable HTTP/SSE server
  19. - `mtr-hk` — CLI
  20. If the commands are not found, add Cargo's bin directory to `PATH`:
  21. ```bash
  22. export PATH="$HOME/.cargo/bin:$PATH"
  23. ```
  24. For development without installing:
  25. ```bash
  26. cargo build --release --bins
  27. ./target/release/mtr-hk status
  28. ./target/release/mtr-hk-mcp
  29. ```
  30. ### Other install routes
  31. Prebuilt binaries for macOS (Intel or Apple silicon) and Linux (x86_64 or
  32. aarch64, static musl) are checksum-verified by the installer:
  33. ```bash
  34. 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
  35. ```
  36. As an agent skill:
  37. ```bash
  38. npx skills add hongkong-ai-labs/hongkong-mtr-skill
  39. npx skills update # refresh the installed skill later
  40. ```
  41. Docker, Apple container and a pure Cloudflare Workers (V8 isolate) deployment
  42. are described below. The native binaries keep stdio and Streamable HTTP/SSE;
  43. the Worker reuses the same Rust service layer through a Workers `fetch` backend.
  44. ### Register the MCP server
  45. The included `.mcp.json` uses the installed binary:
  46. ```json
  47. {
  48. "mcpServers": {
  49. "mtr-hk": {
  50. "command": "mtr-hk-mcp",
  51. "args": []
  52. }
  53. }
  54. }
  55. ```
  56. Register it with any MCP client:
  57. ```bash
  58. npx add-mcp "$(command -v mtr-hk-mcp)" --name mtr-hk -a claude-code -a codex -a cursor -y
  59. claude mcp add mtr-hk -- mtr-hk-mcp
  60. codex mcp add mtr-hk -- mtr-hk-mcp
  61. ```
  62. `add-mcp` detects the client configuration files in the current project; add
  63. `-g` for a global install. Substitute an absolute path if your client does not
  64. inherit the shell `PATH`.
  65. 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`.
  66. ### Remote HTTP/SSE MCP
  67. The HTTP binary exposes the same 15 tools over Streamable HTTP at `/mcp`, with a `/health` endpoint:
  68. ```bash
  69. MTR_HTTP_ADDR=0.0.0.0:8080 MTR_MCP_API_KEY="$SECRET" mtr-hk-mcp-http
  70. ```
  71. ```bash
  72. claude mcp add --transport http mtr-hk http://localhost:8080/mcp
  73. ```
  74. 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.
  75. ### Containers
  76. Build one image containing the CLI and both MCP transports:
  77. ```bash
  78. docker build -t mtr-hk-mcp .
  79. docker run --rm -p 8080:8080 mtr-hk-mcp
  80. ```
  81. Run the stdio server instead:
  82. ```bash
  83. docker run --rm -i --entrypoint mtr-hk-mcp mtr-hk-mcp
  84. ```
  85. Or use Compose:
  86. ```bash
  87. docker compose up --build http
  88. ```
  89. Apple's `container` runtime uses the same OCI image:
  90. ```bash
  91. container build -t mtr-hk-mcp .
  92. container run --rm -p 8080:8080 mtr-hk-mcp
  93. container run --rm -i --entrypoint mtr-hk-mcp mtr-hk-mcp
  94. ```
  95. The image defaults to the HTTP server on port 8080. It runs as a non-root user and includes a `/health` check.
  96. ### Cloudflare Workers (pure WASM)
  97. The root `wrangler.jsonc` deploys a true `wasm32-unknown-unknown` Worker on the
  98. Cloudflare V8 isolate runtime. It does not use a Container, Docker, Tokio or
  99. TCP; the shared service layer talks to MTR through the Workers `fetch` API and
  100. exposes the same 15 MCP tools at `/mcp`. Native stdio and the full
  101. Streamable HTTP/SSE server remain available from the binaries above.
  102. Prerequisites: Rust 1.89 with the WASM target, `worker-build`, Node.js and a
  103. Cloudflare account.
  104. ```bash
  105. rustup target add wasm32-unknown-unknown --toolchain 1.89.0
  106. cargo install worker-build@0.8.0
  107. npx wrangler login
  108. npx wrangler secret put MTR_MCP_API_KEY # optional
  109. npx wrangler deploy
  110. ```
  111. The MCP endpoint is:
  112. ```text
  113. https://<worker-name>.<account>.workers.dev/mcp
  114. ```
  115. ```bash
  116. claude mcp add --transport http mtr-hk \
  117. https://<worker-name>.<account>.workers.dev/mcp
  118. ```
  119. When `MTR_MCP_API_KEY` is set, `/mcp` requires `Authorization: Bearer <key>` or
  120. `X-API-Key: <key>`; `/health` stays public. The Worker is stateless across
  121. requests except for per-isolate caches, and it accepts POST requests at `/mcp`
  122. (Streamable HTTP JSON responses). It intentionally has no stdio, CLI or legacy
  123. SSE endpoint.
  124. Run the Worker locally without Docker:
  125. ```bash
  126. npx wrangler dev --port 8787
  127. curl http://localhost:8787/health
  128. ```
  129. Use `--var MTR_MCP_API_KEY:test-key` to exercise authentication locally. See
  130. [`cloudflare/README.md`](cloudflare/README.md) for the Worker layout and
  131. operational notes.
  132. ### Cloudflare Container (legacy fallback)
  133. The earlier container-backed Worker is still available for accounts that need
  134. the native HTTP server inside a Cloudflare Container. It requires Docker and
  135. Containers enabled on the account:
  136. ```bash
  137. cd cloudflare
  138. npx wrangler secret put MTR_MCP_API_KEY -c wrangler.container.jsonc # optional
  139. npx wrangler deploy -c wrangler.container.jsonc
  140. ```
  141. ### Install the skill
  142. ```bash
  143. mkdir -p ~/.claude/skills
  144. ln -sfn "$PWD/skills/mtr" ~/.claude/skills/mtr
  145. ```
  146. The repository also contains `.claude/skills/mtr` as a symlink, so project-local clients discover it.
  147. ## Tools
  148. | Tool | What it returns |
  149. |---|---|
  150. | `mtr_status` | Live line status for all 10 metro lines + Light Rail, overall condition, delay/disruption summary, HKT last update, matching notices |
  151. | `mtr_alerts` | Current traffic news with severity, affected line names, full content, disruption PDFs and planned works |
  152. | `mtr_next_trains` | Next up to 4 trains per direction at a station, destination, platform, delay flag |
  153. | `mtr_plan_journey` | Fastest routes with time, interchange count, fares and step-by-step legs |
  154. | `mtr_fares` | Heavy-rail fare matrix by passenger category, Octopus vs single journey |
  155. | `mtr_stations` | Search stations by English/Chinese name or code, with lines and coordinates |
  156. | `mtr_lines` | Line codes, bilingual names, colours, station counts, real-time availability, plus a Light Rail summary |
  157. | `mtr_station_facilities` | Barrier-free facilities: lifts, ramps, wide gates, accessible toilets, tactile guidance |
  158. | `mtr_light_rail_next_trains` | Light Rail predictions by platform, route, destination, special-route flag and remarks |
  159. | `mtr_light_rail_routes` | All Light Rail routes, ordered stops, partial route lookup, or routes serving a stop |
  160. | `mtr_light_rail_fares` | Light Rail Octopus and single-journey fares |
  161. | `mtr_bus_next_trains` | MTR Bus/feeder bus arrival estimates, route status, suspension flags and fares |
  162. | `mtr_bus_routes` | Bus route or stop search, variants, fares and stops in both directions |
  163. | `mtr_ferries` | 16 ferry operators and 58 TD routes; search by route, pier, island, district or operator |
  164. | `mtr_ferry_eta` | Live next sailings for HKKF and Sun Ferry; timetable/source guidance for other operators |
  165. 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.
  166. ## Light Rail and MTR Bus coverage
  167. **Light Rail (LR)**
  168. - Live LR line status and delay notices via `mtr_status` / `mtr_alerts` (`LR`).
  169. - Next trains at any of the 68 stops, grouped by platform, including special routes.
  170. - All 11 routes and 22 directions with ordered stops; partial route lookup (`51` → 751) and stop-based route discovery.
  171. - Octopus and single-journey LR fares between any two stops.
  172. **MTR Bus and feeder buses**
  173. - All MTR Bus/feeder routes from the open-data route, stop and fare datasets.
  174. - Next-bus estimates per stop, with direction, delay flag, scheduled flag, suspension status and route-level service remarks.
  175. - Route discovery by route number/name **or stop name** (e.g. “Melody Garden” → route 506).
  176. - Route variants, both directions, ordered stops, coordinates and fares.
  177. 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.
  178. ## Ferry coverage
  179. `mtr_ferries` combines the Transport Department's franchised/licensed ferry route and fare dataset with a curated operator directory.
  180. **16 operators covered:**
  181. - 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.
  182. - Kaito/water taxi: Kaito / licensed small ferries, Hong Kong Water Taxi.
  183. - Cross-boundary: TurboJET, Cotai Water Jet, Chu Kong Passenger Transport.
  184. - Dangerous-goods-only: Hongkong & Yaumati Ferry.
  185. **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.
  186. **Live ETAs:** only HKKF and Sun Ferry expose public ETA APIs integrated here.
  187. ```bash
  188. mtr-hk ferry-eta sun-ferry CECC
  189. mtr-hk ferry-eta hkkf 1 --direction=outbound
  190. ```
  191. 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.
  192. ## Real-time news and delays
  193. - **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.
  194. - **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.
  195. - **Next-train delay flags** are surfaced by `mtr_next_trains` (`delayed`), and Light Rail status/notices use the same LR status feed.
  196. - **Bus service status** is surfaced by `mtr_bus_next_trains`: route status code/colour/remarks, refresh time, per-stop suspension flags and `suspendedStopCount`.
  197. - 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.
  198. `mtr-hk update` detects whether the binary came from cargo, the release
  199. installer, a source checkout or Homebrew, and updates with that same
  200. method. `mtr-hk update --check` only reports.
  201. ## CLI
  202. ```bash
  203. mtr-hk status
  204. mtr-hk alerts --lang=tc
  205. mtr-hk next "Tsim Sha Tsui" --line=TWL
  206. mtr-hk journey Admiralty "Tung Chung"
  207. mtr-hk fares "Hong Kong" Airport
  208. mtr-hk stations 金鐘
  209. mtr-hk lines --stations
  210. mtr-hk facilities Admiralty
  211. mtr-hk lr-next "Tuen Mun Ferry Pier" --route=507
  212. mtr-hk lr-routes 507
  213. mtr-hk lr-routes "Tin King"
  214. mtr-hk lr-fares "Tuen Mun Ferry Pier" "Tin King"
  215. mtr-hk bus-next 506 --stop="Tuen Mun Ferry Pier"
  216. mtr-hk bus-routes K12
  217. mtr-hk bus-routes "Melody Garden"
  218. mtr-hk ferries
  219. mtr-hk ferries "Cheung Chau"
  220. mtr-hk ferries --operator=sun-ferry
  221. mtr-hk ferry-eta sun-ferry CECC
  222. mtr-hk ferry-eta hkkf 1
  223. mtr-hk update --check
  224. ```
  225. Add `--json` for structured output. From the skill, use the wrapper:
  226. ```bash
  227. skills/mtr/scripts/mtr status
  228. ```
  229. Full CLI reference: [`skills/mtr/references/cli.md`](skills/mtr/references/cli.md).
  230. ## Data sources
  231. | Data | Source |
  232. |---|---|
  233. | Heavy-rail next trains | `https://rt.data.gov.hk/v1/transport/mtr/getSchedule.php` (data.gov.hk) |
  234. | Light Rail next trains | `https://rt.data.gov.hk/v1/transport/mtr/lrt/getSchedule` |
  235. | MTR Bus ETA | `https://rt.data.gov.hk/v1/transport/mtr/bus/getSchedule` |
  236. | Live line status | `https://tnews.mtr.com.hk/alert/ryg_line_status.xml` — the feed behind MTR's service-status page |
  237. | Traffic news / disruption notices | `https://tnews.mtr.com.hk/alert/alert.json` + `latecert.json` |
  238. | Journey planner | `https://proxy001.api.mtr.com.hk/ttp-api/v2/api/Path/HRRoutes/` — the API used by MTR's web trip planner |
  239. | Station/line catalogue | `HRStations/` trip-planner API, with CSV fallback |
  240. | MTR fares, routes, stops, accessibility | MTR open-data CSVs under `https://opendata.mtr.com.hk/data/` |
  241. | Ferry routes and full fares | `https://static.data.gov.hk/td/routes-fares-xml/ROUTE_FERRY.xml` |
  242. | HKKF live ETA | `https://www.hkkfeta.com/opendata/route/` and `/opendata/eta/{route_id}/{direction}` |
  243. | Sun Ferry live ETA | `https://www.sunferry.com.hk/eta/?route={route_code}` |
  244. Official datasets:
  245. - [Real-time MTR train information](https://data.gov.hk/en-data/dataset/mtr-data2-nexttrain-data)
  246. - [MTR routes, fares and barrier-free facilities](https://data.gov.hk/en-data/dataset/mtr-data-routes-fares-barrier-free-facilities)
  247. - [Real-time MTR Bus and feeder bus schedule](https://data.gov.hk/en-data/dataset/mtr-mtr_bus-mtr-bus-eta-data)
  248. - [Transport Department ferry routes and fares](https://data.gov.hk/en-data/dataset/hk-td-tis_14-routes-fares-xml)
  249. Detailed endpoint notes, response shapes, ferry sources and caveats: [`skills/mtr/references/api-notes.md`](skills/mtr/references/api-notes.md).
  250. ## Configuration
  251. Every endpoint can be overridden with environment variables:
  252. | Variable | Default |
  253. |---|---|
  254. | `MTR_NEXT_TRAIN_URL` | `https://rt.data.gov.hk/v1/transport/mtr/getSchedule.php` |
  255. | `MTR_LIGHT_RAIL_URL` | `https://rt.data.gov.hk/v1/transport/mtr/lrt/getSchedule` |
  256. | `MTR_BUS_URL` | `https://rt.data.gov.hk/v1/transport/mtr/bus/getSchedule` |
  257. | `MTR_STATUS_URL` | `https://tnews.mtr.com.hk/alert/ryg_line_status.xml` |
  258. | `MTR_LEGEND_URL` | `https://tnews.mtr.com.hk/alert/legend_remarks_v2.xml` |
  259. | `MTR_ALERTS_URL` | `https://tnews.mtr.com.hk/alert/alert.json` |
  260. | `MTR_LATECERT_URL` | `https://tnews.mtr.com.hk/alert/latecert.json` |
  261. | `MTR_LINE_CONFIG_URL` | `https://tnews.mtr.com.hk/alert/lineconfig.json` |
  262. | `MTR_STATIONS_API` | `https://proxy001.api.mtr.com.hk/ttp-api/v2/api/StationBaseInfo/HRStations/` |
  263. | `MTR_JOURNEY_API` | `https://proxy001.api.mtr.com.hk/ttp-api/v2/api/Path/HRRoutes/` |
  264. | `MTR_FERRY_ROUTES_URL` | `https://static.data.gov.hk/td/routes-fares-xml/ROUTE_FERRY.xml` |
  265. | `MTR_HKKF_ETA_BASE` | `https://www.hkkfeta.com/opendata/eta` |
  266. | `MTR_SUN_FERRY_ETA` | `https://www.sunferry.com.hk/eta/` |
  267. | `MTR_TTP_API_KEY` | Public key from MTR's front-end config (override if rotated) |
  268. | `MTR_HTTP_TIMEOUT_MS` | `12000` |
  269. 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.
  270. ## Architecture
  271. ```
  272. src/
  273. config.rs endpoint + cache configuration
  274. constants.rs stable MTR line metadata
  275. model.rs normalized domain types
  276. app.rs shared app object and TTL caches
  277. http.rs HTTP backend trait + native reqwest client
  278. cache.rs typed TTL cache and de-duplication
  279. csvutil.rs RFC-4180 CSV helpers
  280. text.rs alert HTML -> readable text
  281. network.rs station/line catalogue + CSV fallback
  282. fares.rs heavy-rail fare matrix
  283. light_rail.rs Light Rail routes/stops/fares
  284. bus.rs MTR Bus routes/stops/fares
  285. facilities.rs barrier-free facilities
  286. alerts.rs traffic news and LateCert records
  287. status.rs live service status + notice merge
  288. next_train.rs heavy-rail next trains
  289. journey.rs trip planner + leg grouping
  290. services.rs shared high-level MTR tool services
  291. ferries.rs ferry operators, TD routes/fares, live HKKF/Sun ETA
  292. server.rs MCP tool registration + stdio/HTTP transports
  293. cli.rs CLI
  294. bin/mtr-hk-mcp.rs MCP stdio entry point
  295. bin/mtr-hk-mcp-http.rs MCP Streamable HTTP/SSE entry point
  296. bin/mtr-hk.rs CLI entry point
  297. src/lib.rs library root (native modules feature-gated)
  298. worker/ pure Workers WASM crate + MCP JSON-RPC handler
  299. worker/build.sh WASM build pinned to Rust 1.89
  300. wrangler.jsonc pure Cloudflare Workers config
  301. Dockerfile OCI image for CLI + stdio + HTTP MCP
  302. compose.yaml local HTTP and stdio container profiles
  303. cloudflare/src/ legacy Container front door and lifecycle
  304. cloudflare/README.md Worker deployment notes
  305. cloudflare/wrangler.container.jsonc legacy Container config
  306. skills/mtr/
  307. SKILL.md agent instructions
  308. references/ API and CLI documentation
  309. scripts/mtr CLI wrapper
  310. scripts/
  311. smoke.sh live checks for every data source
  312. mcp_smoke.py MCP stdio handshake + tool-call check
  313. mcp_http_smoke.py MCP Streamable HTTP/SSE handshake + tool-call check
  314. ```
  315. 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.
  316. ## Releasing
  317. CI runs formatting, clippy with warnings as errors, tests, a release build of all
  318. three binaries, a `wasm32-unknown-unknown` check of `worker/`, and validates both
  319. `SKILL.md` files plus the shell scripts.
  320. Dependabot proposes weekly Cargo and GitHub Actions updates, and the audit
  321. workflow checks the lockfile against the RustSec advisory database.
  322. `just release 1.0.0` creates and pushes the annotated tag `v1.0.0`; the release
  323. workflow checks it against `Cargo.toml` and `CHANGELOG.md`, builds four targets,
  324. smoke-tests native binaries and publishes one tarball per target containing
  325. `mtr-hk`, `mtr-hk-mcp`, `mtr-hk-mcp-http` and `LICENSE`, plus `SHA256SUMS`.
  326. `scripts/install.sh` verifies the checksum and installs all three binaries, with
  327. a `cargo build --release --locked --bins` fallback.
  328. ## Development
  329. ```bash
  330. just # fmt check, clippy with -D warnings, tests
  331. just skill-check # validate both SKILL.md files and shell syntax
  332. just worker-check # type-check the pure-WASM Worker
  333. cargo build --release --locked --bins
  334. scripts/smoke.sh
  335. python3 scripts/mcp_smoke.py
  336. MTR_HTTP_ADDR=127.0.0.1:8080 ./target/release/mtr-hk-mcp-http &
  337. python3 scripts/mcp_http_smoke.py
  338. ```
  339. `rust-toolchain.toml` pins the stable toolchain with `rustfmt` and
  340. `clippy`, so `rustup` sets contributors up automatically. `just doc`
  341. builds the API documentation. See `CONTRIBUTING.md` for the full check
  342. list and the signed-commit requirement.
  343. `cargo test` is offline and covers CSV/HTML/network canonicalization/fares/routes/journey legs/status severity/ferry classification. The smoke scripts need network access.
  344. ## Limitations
  345. - **Unofficial.** These are public/observed endpoints, not a supported MTR, ferry operator or Transport Department API contract. They can change or rate-limit.
  346. - **Not safety-critical.** Arrival times, journey times and fares are estimates.
  347. - **Live lift outages are not available.** `mtr_station_facilities` is static open data.
  348. - **Journey times** are based on weekday morning traffic, per MTR's own disclaimer.
  349. - **Airport Express fares** come from the trip planner because the open-data fare matrix excludes AEL.
  350. - **High Speed Rail (West Kowloon)** appears in the line list but is not covered by metro next-train or journey tools.
  351. - **LateCert records** are disruption PDFs kept after service normalises. The live status feed is the authoritative signal for current delays.
  352. - **Ferry live ETA is limited to HKKF and Sun Ferry.** Other operators expose timetables or booking pages, not a public ETA API.
  353. - **Ferry full fares** are the published adult single fare from TD; concessions, monthly passes and resident fares are not exhaustive.
  354. - **Kaito/water-taxi/cross-boundary** services can be seasonal, bookable or subject to immigration/terminal rules.
  355. - **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.
  356. - **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.
  357. - **Traditional/Simplified Chinese** matching is exact for Chinese names; use `mtr_stations` if a name variant is not found.
  358. ## License
  359. 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 in

Free to use. If it’s helped, pass it on.