Skip to content
Back to search

ma-wan-bus

Live and scheduled transport for Ma Wan / Park Island, Hong Kong — PITCL buses NR330, NR332, NR334, NR338, NR338S; Sun Bus NR331 and NR331S; KMB 230R; Park Island ferries to Central and Tsuen Wan; fares; HKO weather warnings and forecasts; TD special traffic news; PITCL notices, contact details, typhoon/high-wind plans and passenger policies; combined disruption status, next departures and dataset freshness. Use for real-time arrivals, timetables, ferry sailings, stops, fares, weather, traffic, service changes, lost property, luggage/pet rules, or any question about getting to or from Ma Wan.

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-pitcl-skill/badge.svg)](/listings/hongkong-ai-labs--hongkong-pitcl-skill)

HTML

<a href="/listings/hongkong-ai-labs--hongkong-pitcl-skill"><img src="/api/listings/hongkong-ai-labs--hongkong-pitcl-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.

**Agent skill** — installs `SKILL.md` plus the binary bootstrap script:

npx skills add hongkong-ai-labs/hongkong-pitcl-skill
npx skills update        # refresh the installed skill later

**Prebuilt binary** — macOS (Intel or Apple silicon) and Linux (x86_64 or aarch64, static musl), checksum-verified, into `~/.local/bin`:

curl -fsSL https://raw.githubusercontent.com/hongkong-ai-labs/hongkong-pitcl-skill/main/scripts/install.sh | sh

**From source** — Rust 1.89 or newer:

git clone https://github.com/hongkong-ai-labs/hongkong-pitcl-skill
cd hongkong-pitcl-skill
cargo install --path . --locked
# or directly from GitHub:
cargo install --git https://github.com/hongkong-ai-labs/hongkong-pitcl-skill --locked
# or: cargo build --release --locked   # target/release/mawan

**Docker / Apple container** — the same OCI image runs the CLI, stdio MCP or HTTP MCP. See [Docker and Apple container](#docker-and-apple-container).

**Cloudflare** — `wrangler.jsonc` and `cloudflare/` deploy the HTTP server as a Worker front door plus a Cloudflare Container; see [Cloudflare Worker + Container](#cloudflare-worker--container). A pure WASM Worker is not provided because the server needs TCP/TLS, a Tokio runtime and bundled SQLite.

Verify the install:

$ mawan --version
mawan 0.1.0

`mawan update` detects whether the binary came from cargo, the release installer, a source checkout or Homebrew, and updates with that same method. `mawan update --check` only reports.

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 · 284 lines · 1 finding marked
  1. ---
  2. name: ma-wan-bus
  3. description: Live and scheduled transport for Ma Wan / Park Island, Hong Kong — PITCL buses NR330, NR332, NR334, NR338, NR338S; Sun Bus NR331 and NR331S; KMB 230R; Park Island ferries to Central and Tsuen Wan; fares; HKO weather warnings and forecasts; TD special traffic news; PITCL notices, contact details, typhoon/high-wind plans and passenger policies; combined disruption status, next departures and dataset freshness. Use for real-time arrivals, timetables, ferry sailings, stops, fares, weather, traffic, service changes, lost property, luggage/pet rules, or any question about getting to or from Ma Wan.
  4. license: MIT
  5. ---
  6. # Ma Wan transport
  7. `mawan` is a Rust CLI and MCP server for Ma Wan (Park Island) buses, ferries
  8. and PITCL notices. The CLI and stdio MCP server need no API key or account. The
  9. HTTP MCP transport accepts an optional static API key. It is an independent,
  10. unofficial project.
  11. Use it when the user asks about:
  12. - the next bus at Park Island, Ma Wan, Tsing Yi, Kwai Fong, the Airport,
  13. Central, Tsuen Wan, Tsuen Wan West, Kowloon Station, or Noah's Ark
  14. - route NR330, NR332, NR334, NR338, NR338S, NR331, NR331S or 230R
  15. - the ferry to Central Pier No. 2 or Tsuen Wan Pier
  16. - fares, including resident, child and elderly fares
  17. - weather warnings or forecasts that may suspend ferries or slow buses
  18. - road incidents, closures or special traffic arrangements near Ma Wan
  19. - the latest service changes, weather arrangements or fare notices
  20. - PITCL's hotline, email, address or resident Octopus registration
  21. - luggage, pet or on-board rules for the ferry
  22. - whether a route has real-time data or only a timetable
  23. - first/last buses, weekday vs Saturday/Sunday/public-holiday times
  24. - stops and direction of travel, including official stops missing from live predictions
  25. - the next bus or ferry from Park Island, Ma Wan, Central, Tsuen Wan or the town-side termini
  26. - a combined disruption status from weather, traffic and PITCL notices
  27. - how fresh a fare, timetable or policy is
  28. ## Before first use
  29. Run `scripts/ensure-binary.sh` from the skill directory:
  30. ```console
  31. $ bash scripts/ensure-binary.sh
  32. /Users/you/.local/bin/mawan
  33. ```
  34. It prints the absolute path of a working binary. Use that path for every
  35. command, for example:
  36. ```bash
  37. BIN="$(bash scripts/ensure-binary.sh)"
  38. ```
  39. It checks, in order: `$MAWAN_BIN`, `mawan` on `PATH`, then
  40. `cargo build --release --locked` in the repository.
  41. If only the skill files were installed (for example through `npx skills add`),
  42. there may be no checkout to build from. In that case install the binary first
  43. with `cargo install --path .` from a clone, or point `MAWAN_BIN` at a built
  44. `mawan` binary.
  45. ### Install the binary directly
  46. `npx skills add` installs the skill files. If the binary is missing, install it
  47. with the release installer or cargo:
  48. ```bash
  49. curl -fsSL https://raw.githubusercontent.com/hongkong-ai-labs/hongkong-pitcl-skill/main/scripts/install.sh | sh
    • Note: Pipes a downloaded script directly into a shell (curl | sh / wget | bash)
    • Line 63 on GitHub
  50. # or
  51. cargo install --git https://github.com/hongkong-ai-labs/hongkong-pitcl-skill --locked
  52. ```
  53. Register it with any MCP client:
  54. ```bash
  55. npx add-mcp "$(command -v mawan) mcp" --name mawan -a claude-code -a codex -a cursor -y
  56. claude mcp add mawan -- mawan mcp
  57. codex mcp add mawan -- mawan mcp
  58. ```
  59. `add-mcp` detects the client configuration files in the current project; add
  60. `-g` for a global install. `$(command -v mawan)` keeps the entry correct
  61. when the binary is on `PATH`; substitute an absolute path if your client does
  62. not inherit the shell `PATH`.
  63. ## CLI
  64. Prefer `--json` for anything you need to parse. Tables are for humans.
  65. All times are Hong Kong time (UTC+8); JSON timestamps are RFC 3339 with
  66. `+08:00`.
  67. ```bash
  68. # All routes and what data each has
  69. mawan routes --json
  70. # One route, both directions, all stops
  71. mawan route NR330 --json
  72. # Stops for a direction (1 = outbound, 2 = inbound)
  73. mawan stops NR330 --direction 1 --json
  74. mawan stops 230R --direction 2 --json
  75. # Live arrivals
  76. mawan eta NR330 --json
  77. mawan eta NR330 --direction 2 --stop "Tsing Yi" --limit 3 --json
  78. mawan eta 230R --direction 2 --json
  79. # Timetables
  80. mawan schedule NR330 --day weekday --json
  81. mawan schedule NR330 --day saturday --json
  82. mawan schedule 230R --day today --json
  83. mawan schedule NR338S --day 2026-12-25 --json
  84. # Ferries (no real-time feed)
  85. mawan ferry routes --json
  86. mawan ferry schedule central --day weekday --json
  87. mawan ferry schedule tsuen-wan --day sunday --json
  88. # PITCL notices, newest first
  89. mawan news --limit 10 --json
  90. mawan news --id 61 --json
  91. mawan news --lang tc --limit 5 --json
  92. # Weather and traffic
  93. mawan weather --json
  94. mawan weather --lang tc --json
  95. mawan traffic --json # Ma Wan-related TD messages
  96. mawan traffic --all --json # every territory-wide TD message
  97. # Combined status and next departures
  98. mawan status --json
  99. mawan next --from park-island --limit 3 --json
  100. mawan next --from ma-wan --json
  101. mawan next --from central --day tomorrow --json
  102. # Static PITCL guidance and data freshness
  103. mawan guide contact --json
  104. mawan guide weather --json # high wind / typhoon plan
  105. mawan guide policies --json # ferry luggage, pets, on-board rules
  106. mawan data-info --json
  107. mawan update --check
  108. ```
  109. `--refresh` bypasses the response cache for one run.
  110. Direction `1` is the operator's outbound direction and `2` is inbound. For
  111. 230R, `1` is Kowloon Station → Ma Wan.
  112. `--day` accepts `weekday`, `saturday`, `sunday`, `holiday`, `today`,
  113. `tomorrow`, or `YYYY-MM-DD`.
  114. ## What is live
  115. | Route | Live ETA | Timetable |
  116. | --- | --- | --- |
  117. | NR330, NR332, NR334, NR338 | yes | yes |
  118. | 230R (KMB, not PITCL) | yes | yes |
  119. | NR338S | **no** | exact published times |
  120. | NR331, NR331S | **no** | exact from Ma Wan; frequency for the return leg |
  121. Ferries: **no live feed** for either Central or Tsuen Wan. Use
  122. `mawan ferry schedule` and call the times published sailings, not arrivals.
  123. Never describe NR331, NR331S, NR338S or ferry sailings as live. `mawan eta`
  124. returns a clear error for them. Use the schedule commands instead.
  125. Weather comes live from the Hong Kong Observatory; `get_ma_wan_weather`
  126. returns active warnings, nearest-station temperatures, rainfall, regional wind
  127. and the local forecast, plus a `pitcl_impact` object with separate bus and
  128. ferry guidance. Traffic comes live from the Transport Department. The default
  129. traffic view is filtered to Ma Wan-related messages; `--all` returns every
  130. territory-wide message. A weather warning or road closure is an official
  131. advisory, not a guarantee that a specific sailing or bus is cancelled.
  132. `mawan status` combines those feeds with the latest PITCL notices. It says
  133. explicitly that no public PITCL real-time service-status feed exists. Use it
  134. before answering "are ferries running?" or "is anything disrupted?".
  135. `mawan weather` and `mawan status` apply the same optional TD bridge-stage
  136. extraction, so both report an official Stage I/II/III when one is published.
  137. `mawan route <code> --json` includes route geometry where the operator publishes
  138. it: `shape` is the encoded polyline and `geometry` is a GeoJSON `LineString`
  139. with `[longitude, latitude]` coordinates. Do not synthesise a route or a shape
  140. when those fields are absent; say the operator does not publish geometry.
  141. `mawan next` combines live bus ETAs, exact timetables and ferry sailings. Use
  142. `--from park-island`, `ma-wan`, `central`, `tsuen-wan`, `tsuen-wan-west`,
  143. `tsing-yi`, `kwai-fong`, `airport` or `kowloon-station`. Ferry times are
  144. timetable values, never live.
  145. Do **not** assume T8 means every bus is cancelled. PITCL's published plan says
  146. ferries suspend about 2 hours after T8, while buses may continue until Stage 2
  147. high-wind management on Tsing Ma Bridge (>75 km/h) suspends them. At T3,
  148. ferries may be limited or suspended but buses normally continue. The impact
  149. text follows `--lang tc`.
  150. HKO's open regional wind feed has **no Tsing Ma Bridge anemometer**. The tool
  151. returns Tsing Yi as a regional proxy and sets `bridge_wind.available` to
  152. `false`. When TD publishes a Tsing Ma Bridge high-wind traffic notice,
  153. `bridge_wind.stage` is the official Stage I/II/III and `stage_source` says so.
  154. Otherwise the stage is `unknown`. Never apply the 40/60/75 km/h thresholds from
  155. the proxy alone, and never derive Stage 1/2 from wind speed.
  156. Weekday PITCL timetables are exact clock times. Saturday, Sunday and public
  157. holiday PITCL timetables are frequency windows, because that is how the
  158. operator's feed publishes them. 230R is always frequency-based.
  159. ## Reading arrivals
  160. Each `Eta` object has:
  161. | Field | Meaning |
  162. | --- | --- |
  163. | `stop_seq` | stop order in that direction |
  164. | `stop_en`, `stop_tc` | stop name |
  165. | `direction` | 1 or 2 |
  166. | `minutes` | minutes away as published |
  167. | `at` | arrival time, RFC 3339 in UTC+8 |
  168. | `realtime` | true when the operator is predicting, false when scheduled |
  169. | `remark_en`, `remark_tc` | operator note, e.g. `Scheduled`, `Final Bus` |
  170. A `Scheduled` remark means the bus has not left the terminus yet; the time is
  171. a timetable estimate, not vehicle tracking. Say "scheduled" rather than
  172. "live" for those rows.
  173. `mawan route <code> --json` includes a `fare` object with adult, child and
  174. elderly fares where the operator publishes them, plus a note about resident
  175. Octopus fares. NR331/NR331S now carry Sun Bus fares. Ferries return the same
  176. fare shape from `mawan ferry routes --json`, plus journey minutes and pier
  177. addresses.
  178. Each route also carries `official_stops` per direction. `live_name_en` and
  179. `live_name_tc` show the matching live-feed name, or `null` when the stop is
  180. published but absent from live predictions. NR334's HZMB call and separate
  181. Terminal 1/2 stops are the main live-feed gaps.
  182. `mawan data-info --json` lists the source, printed effective date where one
  183. exists, and the last-verified date for every static dataset.
  184. PITCL notices are listed newest first with links to the official page; the
  185. site does not expose publication dates, so do not invent one. Read a notice
  186. in full with `mawan news --id <id>` (add `--lang tc` for Chinese).
  187. ## MCP
  188. ```bash
  189. mawan mcp # stdio, no auth
  190. mawan mcp --transport http --port 8788
  191. mawan mcp --transport http --port 8788 --api-key "$SECRET"
  192. ```
  193. When a key is configured, send `Authorization: Bearer <key>` or
  194. `X-API-Key: <key>` to `/mcp`. `/health` stays public. The key can also come
  195. from `MAWAN_MCP_API_KEY` or `MAWAN_API_KEY`; `--auth-token` is an alias.
  196. Tools: `list_ma_wan_routes`, `get_ma_wan_route`, `get_ma_wan_stops`,
  197. `get_ma_wan_arrivals`, `get_ma_wan_schedule`, `get_ma_wan_news`,
  198. `list_ma_wan_ferries`, `get_ma_wan_ferry_schedule`, `get_ma_wan_weather`,
  199. `get_ma_wan_traffic`, `get_ma_wan_status`, `get_ma_wan_next_departures`,
  200. `get_ma_wan_data_info`, `get_pitcl_guide`.
  201. ## Cautions
  202. - Schedules change on public holidays and during typhoon/rainstorm
  203. arrangements. For a disruption, check the operator's notice rather than
  204. assuming the timetable holds.
  205. - NR330A is a Sun Bus peak supplement under the NR330 corridor; it is not a
  206. separate timetable here.
  207. - NR331/NR331S return times are circular-service frequencies, not exact times.
  208. - Ferry times are pier gate-closing times, not departure estimates.
  209. - Weather and traffic are official feeds, but do not infer that a specific
  210. ferry or bus is cancelled from a general warning or incident.
  211. - The typhoon/high-wind plan is PITCL's published 2018 contingency notice.
  212. Present it as published guidance, not as the current operational status.
  213. - `guide policies` covers the ferry Notes to Passengers; the bus notes PDF is
  214. image-only, so link to it rather than inventing bus rules.
  215. - Do not infer Tsing Ma Bridge Stage 1/2 from the Tsing Yi wind proxy; HKO has
  216. no public bridge anemometer. `bridge_wind.available` is false by design. Use
  217. `bridge_wind.stage` only when TD has published an official high-wind notice.
  218. - Do not invent route geometry. Report `geometry`/`shape` only when present.
  219. - Traffic relevance is keyword-based; use `--all` if an incident may have
  220. knock-on effects outside the Ma Wan corridor.
  221. - `mawan next` does not invent times for frequency-only return legs; report the
  222. note and point to `mawan schedule` instead.
  223. - PITCL notices have no machine-readable dates; report them in site order and
  224. do not invent a date.
  225. - Do not present this data as official; it is an independent client of public
  226. operator feeds.
README.md · README · 476 lines · 1 finding marked
  1. # mawan
  2. **Ma Wan / Park Island transport in one binary — CLI and MCP server.**
  3. `mawan` pulls the live feeds behind the Park Island ETA app and Hong Kong's
  4. open bus data, pairs them with the operators' published timetables, ferries,
  5. fares and notices, and exposes everything over a CLI and MCP.
  6. - **Live bus ETA:** PITCL NR330, NR332, NR334, NR338; KMB 230R
  7. - **Bus timetables:** NR330, NR332, NR334, NR338, NR338S, NR331, NR331S, 230R
  8. - **Fares:** published adult, child and elderly fares, including Sun Bus NR331/NR331S
  9. - **Ferries:** Park Island ↔ Central Pier No. 2 and Park Island ↔ Tsuen Wan, with journey times and pier addresses
  10. - **Status:** one call combining weather impact, relevant TD traffic and PITCL notices
  11. - **Next departures:** next bus and ferry from Park Island, Ma Wan or the town-side termini
  12. - **Weather:** current HKO conditions, active warnings, local forecast and regional wind
  13. - **Traffic:** real-time TD special traffic news, filtered to the Ma Wan corridor
  14. - **PITCL news:** latest operator notices in English or Traditional Chinese
  15. - **PITCL guidance:** hotline, typhoon/high-wind plan and passenger policies, in English or Chinese
  16. - **Data freshness:** effective dates and last-verified dates for every static dataset
  17. - **Stops and directions** for every bus route, including structured official stop lists
  18. - **Route geometry:** the operator's published shape as an encoded polyline and a GeoJSON LineString
  19. - **Tsing Ma Bridge stage:** Stage I/II/III only when TD publishes a high-wind traffic notice
  20. - **MCP server** over stdio and streamable HTTP, with an optional API key
  21. - **Agent skill** (`SKILL.md`) plus a binary bootstrap script
  22. No API key is needed for the CLI or stdio MCP server. The HTTP transport accepts
  23. an optional static key. Times are Hong Kong time (UTC+8).
  24. ## Bus routes
  25. | Route | Operator | Service | Live data |
  26. | --- | --- | --- | --- |
  27. | NR330 | PITCL | Park Island ↔ MTR Tsing Yi Station | yes |
  28. | NR332 | PITCL | Park Island ↔ MTR Kwai Fong Station | yes |
  29. | NR334 | PITCL | Park Island ↺ Hong Kong International Airport | yes |
  30. | NR338 | PITCL | Park Island ↔ Central (Pier 2), overnight | yes |
  31. | NR338S | PITCL | Ma Wan ↔ Central via Hong Kong Station | timetable |
  32. | NR331 | Sun Bus | Ma Wan (Pak Yan Road) ↔ Tsuen Wan Station | timetable |
  33. | NR331S | Sun Bus | Ma Wan (Pak Yan Road) ↔ Tsuen Wan West | timetable |
  34. | 230R | KMB | Kowloon Station ↔ Ma Wan (Pak Yan Road) | yes |
  35. 230R is the exception to the PITCL pattern: it is operated by KMB, not Park
  36. Island Transport, and its live ETAs come from KMB's open data at
  37. `data.etabus.gov.hk`. The same commands work: `mawan eta 230R`, `mawan stops
  38. 230R`, `mawan schedule 230R`.
  39. ### Fares
  40. | Route | Adult visitor | Adult resident | Notes |
  41. | --- | --- | --- | --- |
  42. | NR330 | HK$13.80 | HK$8.50 | registered Octopus for resident fare |
  43. | NR332 | HK$14.50 | HK$9.80 | registered Octopus for resident fare |
  44. | NR334 | HK$32.50 | — | no resident fare; $2 concession not applicable |
  45. | NR338 | HK$32.00 | HK$24.50 | overnight |
  46. | NR338S | HK$39.00 | HK$24.10 | child $19.50/$12.10, elderly $12.10/$12.10; resident offer $22.00/$11.00 until 31 Dec 2026 |
  47. | NR331 | HK$15.60 | HK$9.60 | Sun Bus flat fare; child same as adult; section fare $2.00 within Ma Wan |
  48. | NR331S | HK$16.30 | HK$10.00 | Sun Bus flat fare; child same as adult; section fare $2.00 within Ma Wan |
  49. | 230R | HK$15.50 | — | KMB fare |
  50. Use `mawan route <code>` for the full fare object, including child and
  51. elderly fares. Sun Bus fares require a registered Octopus card for the
  52. resident rate; the TD sheet does not print an effective date, so
  53. `mawan data-info` records the last verification date instead.
  54. ## Ferries
  55. | Route | Other pier | Journey | Weekday sailings | Weekend/holiday sailings |
  56. | --- | --- | --- | --- | --- |
  57. | `central` | Central Pier No. 2, Man Kwong Street | about 22 min | 19 each way | 7 each way |
  58. | `tsuen-wan` | Tsuen Wan Ferry Pier | about 12 min | 3 each way | 3 each way |
  59. Boarding is at Park Island Ferry Pier, 8 Pak Lai Road, Ma Wan. Ferry times are
  60. pier gate-closing times. Fares: Central $36.00 adult visitor / $24.10 resident;
  61. Tsuen Wan $12.00 / $10.20. Child and elderly fares are roughly half and are
  62. returned in full by `mawan ferry routes --json`. `mawan ferry schedule` also
  63. returns first/last sailings and the pier addresses.
  64. ## Weather impact
  65. `mawan weather` includes a `pitcl_impact` object with `level` (`normal`,
  66. `watch`, `disruption`, `severe`) and separate bus/ferry guidance. It does not
  67. treat a T8 as an automatic bus cancellation:
  68. - **T8:** ferries suspend about 2 hours after the signal is hoisted; Tsuen Wan
  69. ferry may be strengthened until crowds clear. Buses may continue until
  70. Stage 2 high-wind management on Tsing Ma Bridge (>75 km/h) suspends them.
  71. - **T3:** ferries may be limited or suspended; buses normally continue.
  72. - **T1:** ferries may be delayed; buses normally continue.
  73. - **Rainstorm:** expect delays; PITCL's published plan has no automatic
  74. suspension.
  75. The impact text, guide and headings follow `--lang tc`.
  76. `mawan weather` also includes HKO's regional 10-minute wind observations.
  77. There is **no public Tsing Ma Bridge anemometer** in the open-data feed. The
  78. Tsing Yi station is shown as a regional proxy, but `bridge_wind.available` is
  79. `false`, so PITCL's 40/60/75 km/h thresholds are never applied automatically.
  80. `mawan weather` checks TD special traffic news in addition to HKO. When the
  81. Transport Department publishes a Tsing Ma Bridge high-wind traffic notice,
  82. `bridge_wind.stage` is set from that notice and `stage_source` names the source.
  83. This is the official stage, not an inference from nearby wind. Without such a
  84. notice the stage is `unknown`; a traffic-feed failure does not fail the weather
  85. report.
  86. ## Install
  87. **Agent skill** — installs `SKILL.md` plus the binary bootstrap script:
  88. ```bash
  89. npx skills add hongkong-ai-labs/hongkong-pitcl-skill
  90. npx skills update # refresh the installed skill later
  91. ```
  92. **Prebuilt binary** — macOS (Intel or Apple silicon) and Linux (x86_64 or
  93. aarch64, static musl), checksum-verified, into `~/.local/bin`:
  94. ```bash
  95. curl -fsSL https://raw.githubusercontent.com/hongkong-ai-labs/hongkong-pitcl-skill/main/scripts/install.sh | sh
    • Note: Pipes a downloaded script directly into a shell (curl | sh / wget | bash)
    • Line 119 on GitHub
  96. ```
  97. **From source** — Rust 1.89 or newer:
  98. ```bash
  99. git clone https://github.com/hongkong-ai-labs/hongkong-pitcl-skill
  100. cd hongkong-pitcl-skill
  101. cargo install --path . --locked
  102. # or directly from GitHub:
  103. cargo install --git https://github.com/hongkong-ai-labs/hongkong-pitcl-skill --locked
  104. # or: cargo build --release --locked # target/release/mawan
  105. ```
  106. **Docker / Apple container** — the same OCI image runs the CLI, stdio MCP or
  107. HTTP MCP. See [Docker and Apple container](#docker-and-apple-container).
  108. **Cloudflare** — `wrangler.jsonc` and `cloudflare/` deploy the HTTP server as a
  109. Worker front door plus a Cloudflare Container; see
  110. [Cloudflare Worker + Container](#cloudflare-worker--container). A pure WASM
  111. Worker is not provided because the server needs TCP/TLS, a Tokio runtime and
  112. bundled SQLite.
  113. Verify the install:
  114. ```console
  115. $ mawan --version
  116. mawan 0.1.0
  117. ```
  118. `mawan update` detects whether the binary came from cargo, the release
  119. installer, a source checkout or Homebrew, and updates with that same
  120. method. `mawan update --check` only reports.
  121. ## CLI
  122. ```bash
  123. mawan routes # every Ma Wan route and its data source
  124. mawan route NR330 # both directions and all stops
  125. mawan stops NR330 -d 1 # stops, direction 1
  126. mawan stops 230R -d 2
  127. mawan eta NR330 # live arrivals at every stop
  128. mawan eta NR330 -d 2 -s "Tsing Yi" # filter by stop name
  129. mawan eta NR331 # explains that no live feed exists
  130. mawan schedule NR330 --day weekday # exact weekday times
  131. mawan schedule NR330 --day saturday # frequency windows
  132. mawan schedule NR338 --day today
  133. mawan schedule 230R --day sunday
  134. mawan schedule NR338S --day 2026-12-25
  135. mawan news # latest PITCL notices, newest first
  136. mawan news --id 61 # read one notice in full
  137. mawan news --lang tc --limit 5
  138. mawan ferry routes # ferry routes, piers and fares
  139. mawan ferry schedule central --day weekday
  140. mawan ferry schedule tsuen-wan --day sunday --json
  141. mawan weather # HKO conditions, warnings, forecast and wind
  142. mawan weather --lang tc
  143. mawan traffic # TD news affecting Ma Wan
  144. mawan traffic --all --limit 10 # every territory-wide message
  145. mawan status # weather impact + traffic + PITCL notices
  146. mawan status --lang tc
  147. mawan next # next buses and ferries from Park Island
  148. mawan next --from ma-wan --limit 3 # NR331, NR331S, NR338S and 230R
  149. mawan next --from central --day tomorrow
  150. mawan guide contact # hotline, email, resident fare forms
  151. mawan guide weather # high-wind and typhoon arrangements
  152. mawan guide policies # ferry luggage, pets and on-board rules
  153. mawan data-info # effective and last-verified dates
  154. mawan update --check
  155. ```
  156. Global flags: `--json`, `--lang en|tc`, `--cache-ttl 30`, `--refresh`.
  157. `--refresh` bypasses the in-process cache for that run.
  158. MCP HTTP flags: `--transport http`, `--host 127.0.0.1`, `--port 8788`,
  159. `--path /mcp`, `--api-key` (or `MAWAN_MCP_API_KEY`).
  160. `mawan route <code>` always requests the operator shape. With `--json`, each
  161. direction may include `shape` (the encoded polyline) and `geometry` (a GeoJSON
  162. `LineString`). Routes without a published shape omit both fields and add a note;
  163. the command never invents coordinates.
  164. Direction `1` is the operator's outbound direction and `2` is inbound. For
  165. 230R that means `1` is Kowloon Station → Ma Wan.
  166. ### Examples
  167. ```console
  168. $ mawan eta NR332 -d 1 -s "Kwai Fong"
  169. SEQ STOP ETA IN SOURCE
  170. --- ------------------- ----- ------ --------
  171. 4 MTR Kwai Fong Station 07:42 8 min schedule
  172. ```
  173. ```console
  174. $ mawan schedule NR330 --day saturday
  175. NR330 dir 1 Park Island → MTR Tsing Yi Station [saturday / official-frequency]
  176. First 06:00 · Last 00:30
  177. 06:00–06:30 every 15 min
  178. 06:30–07:30 every 10 min
  179. ...
  180. ```
  181. ## MCP server
  182. ```bash
  183. mawan mcp # stdio
  184. mawan mcp --transport http --port 8788
  185. mawan mcp --transport http --port 8788 --api-key "$SECRET"
  186. # or: MAWAN_MCP_API_KEY="$SECRET" mawan mcp --transport http
  187. ```
  188. Client configuration for stdio:
  189. ```json
  190. {
  191. "mcpServers": {
  192. "mawan": {
  193. "command": "mawan",
  194. "args": ["mcp"]
  195. }
  196. }
  197. }
  198. ```
  199. Register it with any MCP client:
  200. ```bash
  201. npx add-mcp "$(command -v mawan) mcp" --name mawan -a claude-code -a codex -a cursor -y
  202. claude mcp add mawan -- mawan mcp
  203. codex mcp add mawan -- mawan mcp
  204. ```
  205. `add-mcp` detects the client configuration files in the current project; add
  206. `-g` for a global install. `$(command -v mawan)` keeps the entry correct
  207. when the binary is on `PATH`; substitute an absolute path if your client does
  208. not inherit the shell `PATH`.
  209. HTTP transport serves `POST /mcp` and `GET /health` on `127.0.0.1:8788`.
  210. `GET /health` stays public. When an API key is configured, `/mcp` requires
  211. `Authorization: Bearer <key>` (or `X-API-Key: <key>`); requests without it
  212. receive HTTP 401. The server has no TLS of its own, so keep the loopback bind
  213. or terminate TLS at a reverse proxy before exposing it.
  214. ```json
  215. {
  216. "mcpServers": {
  217. "mawan": {
  218. "type": "http",
  219. "url": "http://127.0.0.1:8788/mcp",
  220. "headers": { "Authorization": "Bearer <key>" }
  221. }
  222. }
  223. }
  224. ```
  225. The key comes from `--api-key`, `MAWAN_MCP_API_KEY` or `MAWAN_API_KEY`; the
  226. `--auth-token` spelling is accepted as an alias. An empty value disables auth.
  227. Tools:
  228. | Tool | Purpose |
  229. | --- | --- |
  230. | `list_ma_wan_routes` | route, operator, termini, live availability |
  231. | `get_ma_wan_route` | one route, both directions, stops, fares |
  232. | `get_ma_wan_stops` | ordered stops for a direction |
  233. | `get_ma_wan_arrivals` | live ETAs, optional stop filter |
  234. | `get_ma_wan_schedule` | exact times or frequency windows by day type |
  235. | `get_ma_wan_news` | latest PITCL notices; pass an `id` for full text |
  236. | `list_ma_wan_ferries` | ferry routes, piers and fares |
  237. | `get_ma_wan_ferry_schedule` | ferry sailings by day type |
  238. | `get_ma_wan_weather` | HKO weather, warnings, forecast, regional wind and PITCL impact |
  239. | `get_ma_wan_traffic` | TD special traffic news, Ma Wan-related by default |
  240. | `get_ma_wan_status` | combined weather impact, traffic and PITCL notices |
  241. | `get_ma_wan_next_departures` | next buses and ferries from a chosen origin |
  242. | `get_ma_wan_data_info` | effective and last-verified dates for static data |
  243. | `get_pitcl_guide` | contact, adverse-weather plan and passenger policies |
  244. ## Agent skill
  245. ```bash
  246. npx skills add <owner>/hongkong-pitcl-skill
  247. ```
  248. Then run `bash scripts/ensure-binary.sh` once. It checks `$MAWAN_BIN`, `mawan`
  249. on `PATH`, and finally builds from the checkout, printing the absolute binary
  250. path to use. `scripts/install.sh` prefers a checksum-verified GitHub release and
  251. falls back to a source build.
  252. ### Docker and Apple container
  253. ```bash
  254. docker build -t mawan .
  255. docker run --rm mawan routes # CLI
  256. docker run --rm -p 8788:8788 -e MAWAN_MCP_API_KEY="$SECRET" \
  257. mawan mcp --transport http --host 0.0.0.0 --port 8788
  258. ```
  259. For stdio, keep stdin attached:
  260. ```bash
  261. docker run --rm -i mawan mcp
  262. ```
  263. `docker compose up --build` starts the HTTP server on port 8788. Apple's
  264. `container` runtime uses the same OCI image:
  265. ```bash
  266. container build -t mawan .
  267. container run --rm -p 8788:8788 -e MAWAN_MCP_API_KEY="$SECRET" \
  268. mawan mcp --transport http --host 0.0.0.0 --port 8788
  269. ```
  270. ### Cloudflare Worker + Container
  271. The repository includes a Worker front door in `cloudflare/` and
  272. `wrangler.jsonc`. Cloudflare runs the Rust HTTP MCP server in a Cloudflare
  273. Container, not as a pure WASM isolate, because the server needs TCP/TLS and a
  274. Tokio runtime. Deploy from the repository root with
  275. `npx wrangler deploy`; Wrangler needs a Docker-compatible engine to build the
  276. image. See [`cloudflare/README.md`](cloudflare/README.md) for prerequisites and
  277. authentication guidance.
  278. ## Development and releases
  279. ```bash
  280. just # fmt check, clippy with -D warnings, tests
  281. just skill-check # validate SKILL.md and shell syntax
  282. just container # build the image and print CLI help
  283. cargo test --all --locked
  284. cargo clippy --all-targets --locked -- -D warnings
  285. cargo fmt --all -- --check
  286. ```
  287. `rust-toolchain.toml` pins the stable toolchain with `rustfmt` and
  288. `clippy`, so `rustup` sets contributors up automatically. `just doc`
  289. builds the API documentation. See `CONTRIBUTING.md` for the full check
  290. list and the signed-commit requirement.
  291. CI runs the same checks. Dependabot proposes weekly Cargo and GitHub Actions
  292. updates, and the audit workflow checks the lockfile against the RustSec
  293. advisory database.
  294. `just release 0.1.0` tags and pushes `v0.1.0`. The release workflow checks the
  295. tag against `Cargo.toml` and `CHANGELOG.md`, builds four targets, smoke-tests
  296. native binaries and publishes `mawan-<tag>-<target>.tar.gz` plus `SHA256SUMS`.
  297. `scripts/install.sh` verifies the checksum and falls back to
  298. `cargo build --release --locked`.
  299. ## Official links and feeds
  300. - Bus services: <https://www.pitcl.com.hk/en/bus_service.php>
  301. - Ferries: <https://www.pitcl.com.hk/en/ferry_service.php>
  302. - Notices: <https://www.pitcl.com.hk/en/news.php>
  303. - Weather: <https://data.weather.gov.hk/weatherAPI/opendata/weather.php>
  304. - Traffic: <https://resource.data.one.gov.hk/td/en/specialtrafficnews.xml>
  305. These replace scraping the older `traffic.td.gov.hk`, RTHK and HKO pages:
  306. HKO's open-data API and TD's special-traffic-news XML are machine-readable and
  307. update in real time.
  308. ## Data sources
  309. - **PITCL NR330/332/334/338** — the official Park Island ETA app at
  310. `eta.pitcl.com.hk` is a Socif deployment. Its public JSON API at
  311. `360-api.socif.co` exposes route metadata, stops, per-stop ETAs and
  312. weekday timetables and route `shape` values. Route IDs: NR330=249, NR332=250,
  313. NR334=252, NR338=253. The weekend/seasonal headways come from the same
  314. metadata. Signed `timestamp` values are converted to UTC+8. Shapes are decoded
  315. from the standard encoded-polyline format and emitted as GeoJSON LineStrings.
  316. `GET /api/route/{id}` now carries the shape; the separate
  317. `/api/route-network/` endpoint is not used because it currently returns a
  318. server-side `TypeError` and is unnecessary for per-route geometry.
  319. - **230R** — KMB open data (`data.etabus.gov.hk`) for route stops and live
  320. ETAs; the frequency table is the published KMB/TD timetable.
  321. - **NR338S** — PITCL leaflet *Park Island – Central (Via Hong Kong Stn.)*,
  322. Ver. 20250901, effective 1 September 2025.
  323. - **NR331 / NR331S** — Transport Department Schedule of Services (NR331en.pdf)
  324. for the exact Ma Wan departures; service hours for the circular return leg.
  325. - **Fares** — PITCL bus service leaflets linked from `pitcl.com.hk/en/bus_service.php`,
  326. effective 1 April 2025 (NR338S effective 1 September 2025).
  327. - **Ferries** — PITCL ferry timetables effective 17 August 2025, linked from
  328. `pitcl.com.hk/en/ferry_service.php`.
  329. - **Weather** — Hong Kong Observatory Open Data API (`rhrread`, `warnsum`,
  330. `flw`), selecting the stations and rainfall districts nearest Ma Wan. The
  331. regional 10-minute wind CSV supplies Tsing Yi, Chek Lap Kok, Cheung Chau,
  332. Central Pier and Waglan Island; it has no Tsing Ma Bridge station.
  333. - **Traffic** — Transport Department Special Traffic News XML. The feed is
  334. territory-wide, so messages are flagged by whether they mention Ma Wan, the
  335. ferry piers, the airport corridor, Tsing Yi/Kwai Fong/Tsuen Wan or a
  336. connecting road. Railway-only notices are excluded from the default view.
  337. An explicit Tsing Ma Bridge high-wind management notice (Stage I/II/III, in
  338. English or Chinese) supplies `bridge_wind.stage` and `stage_evidence`.
  339. Territory-wide RTIS and speed-map pages are not used for the bridge stage:
  340. the documented XML is stable, while the speed-map endpoint has been returning
  341. HTTP 503 and its segment metadata does not cleanly identify Tsing Ma Bridge.
  342. - **News** — the list and detail pages under `pitcl.com.hk/en/news.php` are
  343. parsed as HTML; there is no JSON feed. PITCL's TLS certificate does not match
  344. the hostname, so those read-only requests accept the certificate.
  345. - **Guidance** — PITCL's contact page, the high-wind/typhoon contingency PDF
  346. (PAX Notice 2018.08) and the ferry Notes to Passengers.
  347. - **Official stops** — every route/direction carries an `official_stops` list
  348. with a `live_name_en`/`live_name_tc` mapping. That makes differences
  349. machine-readable: NR334's HZMB call and separate Terminal 1/2 stops are the
  350. main live-feed gaps; NR338's Harbour Centre and Tin Liu calls are already in
  351. the inbound live list.
  352. - **Freshness** — `mawan data-info` lists the source, printed effective date
  353. where one exists, and the date this project last verified each static dataset.
  354. ## Limits
  355. - NR331, NR331S and NR338S have no public real-time feed. `mawan eta` says so
  356. instead of inventing a prediction. Their stop lists are the official TD/PITCL
  357. lists rather than live predictions.
  358. - Weekend and public-holiday PITCL timetables are frequency windows; only the
  359. weekday timetable is published as exact clock times by the feed.
  360. - The return legs of NR331/NR331S are circular services and are shown as
  361. frequencies because Sun Bus does not publish exact return times.
  362. - The Socif feed labels some values `Scheduled` (the bus has not left the
  363. terminus yet). Those rows are marked `schedule`, not `live`.
  364. - Ferries have no public real-time feed; they are timetable-only.
  365. - Weather can suspend ferries and slow buses, but the tools report official
  366. warnings and forecasts; they do not predict a specific cancellation. In
  367. particular, T8 does not automatically cancel buses — read `pitcl_impact`.
  368. - Traffic relevance is keyword-based. Use `mawan traffic --all` when a
  369. territory-wide incident may have knock-on effects not caught by the filter.
  370. - The PITCL news page does not expose publication dates, so notices are shown
  371. in the site's own order (newest first) rather than with a parsed date.
  372. - The adverse-weather plan is PITCL's published 2018 contingency notice; it is
  373. still linked from the site, but actual arrangements can change. Always check
  374. current PITCL notices and HKO warnings.
  375. - HKO publishes no Tsing Ma Bridge wind station in its open regional wind feed.
  376. The tool reports the nearest regional wind and leaves `bridge_wind.available`
  377. false. A bridge stage is reported only when TD publishes an official high-wind
  378. traffic notice; otherwise it is `unknown`. Stage 1/2 is never inferred from the
  379. Tsing Yi proxy.
  380. - Route geometry exists only where the operator publishes a shape. It is
  381. returned as-is; missing geometry is reported, not synthesised.
  382. - `mawan next` uses live ETAs where available and published times otherwise.
  383. Return legs published only as frequency windows (NR331/NR331S from town) are
  384. reported as notes, not invented departure times.
  385. - Feeds can change without notice. This is an independent, unofficial project,
  386. not affiliated with PITCL, Sun Bus, KMB or the Transport Department.
  387. ## Licence
  388. MIT. See [LICENSE](LICENSE). Bus, ferry, weather and traffic data remain subject
  389. to PITCL, Sun Bus, KMB, HKO and Transport Department terms.

Ratings and comments

Sign in to rate this skill.

Sign in

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