Skip to content
Back to search

hongkong-ferry-skill

Hong Kong ferry routes, live next-sailing ETAs and published timetables for Hong Kong & Kowloon Ferry (HKKF: Central–Lamma, Peng Chau, Hei Ling Chau) and Sun Ferry (Central–Cheung Chau, Central–Mui Wo, North Point–Hung Hom, North Point–Kowloon City). Use for any question about Hong Kong ferries, outlying islands, piers, sailing times or the next boat.

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

HTML

<a href="/listings/hongkong-ai-labs--hongkong-ferry-skill"><img src="/api/listings/hongkong-ai-labs--hongkong-ferry-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` and the binary bootstrap script:

npx skills add hongkong-ai-labs/hongkong-ferry-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-ferry-skill/main/scripts/install.sh | sh

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

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

Verify:

$ hkferry --version

`hkferry update` detects whether the binary came from cargo, the release installer, a source checkout or Homebrew, and updates with that same method. `hkferry 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 · 168 lines · 1 finding marked
  1. ---
  2. name: hongkong-ferry-skill
  3. description: Hong Kong ferry routes, live next-sailing ETAs and published timetables for Hong Kong & Kowloon Ferry (HKKF: Central–Lamma, Peng Chau, Hei Ling Chau) and Sun Ferry (Central–Cheung Chau, Central–Mui Wo, North Point–Hung Hom, North Point–Kowloon City). Use for any question about Hong Kong ferries, outlying islands, piers, sailing times or the next boat.
  4. license: MIT
  5. ---
  6. # Hong Kong ferries
  7. `hkferry` is a Rust CLI and MCP server for the public HKKF and Sun Ferry open
  8. data feeds. It needs no API key and no account. It is an independent,
  9. unofficial project.
  10. Use it when the user asks about:
  11. - the next ferry from Central to Cheung Chau, Mui Wo, Yung Shue Wan, Sok Kwu
  12. Wan, Peng Chau or Hei Ling Chau
  13. - the next North Point ferry to Hung Hom or Kowloon City
  14. - a ferry timetable for a weekday, Saturday, Sunday or public holiday
  15. - which pier a route leaves from
  16. - whether a live ETA exists or only a published timetable
  17. ## Before first use
  18. Run `scripts/ensure-binary.sh` from the skill directory:
  19. ```console
  20. $ bash scripts/ensure-binary.sh
  21. /Users/you/.local/bin/hkferry
  22. ```
  23. It prints the absolute path of a working binary. Use it for every command:
  24. ```bash
  25. BIN="$(bash scripts/ensure-binary.sh)"
  26. ```
  27. It checks, in order: `$HKFERRY_BIN`, `hkferry` on `PATH`,
  28. `scripts/install.sh`, then `cargo build --release --locked` in the repo root.
  29. ### Install the binary directly
  30. `npx skills add` installs the skill files. If the binary is missing, install it
  31. with the release installer or cargo:
  32. ```bash
  33. curl -fsSL https://raw.githubusercontent.com/hongkong-ai-labs/hongkong-ferry-skill/main/scripts/install.sh | sh
    • Note: Pipes a downloaded script directly into a shell (curl | sh / wget | bash)
    • Line 46 on GitHub
  34. # or
  35. cargo install --git https://github.com/hongkong-ai-labs/hongkong-ferry-skill --locked
  36. ```
  37. Register it with any MCP client:
  38. ```bash
  39. npx add-mcp "$(command -v hkferry) mcp" --name hongkong-ferry -a claude-code -a codex -a cursor -y
  40. claude mcp add hongkong-ferry -- hkferry mcp
  41. codex mcp add hongkong-ferry -- hkferry mcp
  42. ```
  43. `add-mcp` detects the client configuration files in the current project; add
  44. `-g` for a global install. `$(command -v hkferry)` keeps the entry correct
  45. when the binary is on `PATH`; substitute an absolute path if your client does
  46. not inherit the shell `PATH`.
  47. ## CLI
  48. Prefer `--json` when you need to parse. Times are operator-local clock times
  49. in Hong Kong (UTC+8).
  50. ```bash
  51. $BIN routes # both operators
  52. $BIN routes --operator hkkf
  53. $BIN routes --operator sunferry --json
  54. $BIN eta hkkf 2 # Central -> Yung Shue Wan
  55. $BIN eta hkkf 2 --direction inbound # Yung Shue Wan -> Central
  56. $BIN eta hkkf "sok kwu" --json
  57. $BIN eta sunferry CECC # Central -> Cheung Chau
  58. $BIN eta sunferry "mui wo" --json
  59. $BIN timetable hkkf 1 --direction outbound
  60. $BIN timetable sunferry CECC --json
  61. $BIN update --check
  62. ```
  63. Routes can be selected by operator id (`2`), Sun Ferry code (`CECC`), timetable
  64. slug (`central_cheungchau`) or a name substring (`cheung chau`). If a name
  65. matches more than one route, the first match wins; use the id for certainty.
  66. ### Covered operators
  67. | Operator | Routes | Live ETA | Timetable |
  68. | --- | --- | --- | --- |
  69. | HKKF | 1 Central–Sok Kwu Wan, 2 Central–Yung Shue Wan, 3 Central–Peng Chau, 4 Peng Chau–Hei Ling Chau | yes | yes |
  70. | Sun Ferry | CECC Central–Cheung Chau, CEMW Central–Mui Wo, NPHH North Point–Hung Hom, NPKC North Point–Kowloon City | yes | yes |
  71. `--direction outbound` means away from the route's origin pier and `inbound`
  72. means towards it, as HKKF publishes them. Sun Ferry's ETA feed does not publish
  73. a direction, so both directions appear together.
  74. HKKF's published timetable encodes markers on some sailings: `*` (for example
  75. only on Saturdays), `#` (freight or advance-booking condition) and `^` (last
  76. sailing). Sun Ferry timetables use numeric remark codes; `1` and similar refer
  77. to the footnotes in the operator's published timetable.
  78. ## Reading results
  79. `eta` returns:
  80. | Field | Meaning |
  81. | --- | --- |
  82. | `depart` | Scheduled departure, `HH:MM` |
  83. | `eta` | Estimated arrival time as published, `HH:MM` |
  84. | `eta_at` | Full ETA timestamp when HKKF publishes one |
  85. | `vessel` | Vessel code when Sun Ferry publishes one |
  86. | `remark` | Operator remark, when present |
  87. An empty `sailings` array means the operator currently publishes no upcoming
  88. sailing — commonly after the last boat. Say that, and give the first published
  89. sailing from `timetable` rather than inventing one.
  90. Sun Ferry's live feed can include a sailing with a departure time but no `eta`
  91. yet. That is a scheduled sailing, not a confirmed arrival.
  92. ## MCP
  93. ```bash
  94. $BIN mcp
  95. ```
  96. ```json
  97. {
  98. "mcpServers": {
  99. "hongkong-ferry": {
  100. "command": "/absolute/path/to/hkferry",
  101. "args": ["mcp"]
  102. }
  103. }
  104. }
  105. ```
  106. Tools:
  107. | Tool | Arguments |
  108. | --- | --- |
  109. | `list_ferry_routes` | `{ "operator"?: "all"\|"hkkf"\|"sunferry" }` |
  110. | `get_ferry_eta` | `{ "operator": "hkkf"\|"sunferry", "route": string, "direction"?: "outbound"\|"inbound" }` |
  111. | `get_ferry_timetable` | `{ "operator": "hkkf"\|"sunferry", "route": string, "direction"?: "outbound"\|"inbound" }` |
  112. ## Cautions
  113. - Live ETAs are predictions. Typhoon, rainstorm, fog and special traffic
  114. arrangements can suspend or change sailings without a live update.
  115. - Not every Hong Kong ferry is here. Star Ferry, Fortune Ferry, Coral Ferry and
  116. the Discovery Bay / Park Island ferries are separate services.
  117. - The HKKF timetable feed sometimes embeds HTML in its remark columns. This
  118. tool extracts the sailing times and markers, not the full styled notice.
  119. - Do not present this as an official operator channel. For a disruption, check
  120. the operator's website or pier notice.
  121. ## Sources
  122. - HKKF: `https://www.hkkfeta.com/opendata/route/`, `/eta/{route}/{direction}`,
  123. `/time_table/{route}/{direction}`
  124. - Sun Ferry: `https://www.sunferry.com.hk/eta/?route={code}` and
  125. `/eta/timetable/SunFerry_{slug}_timetable_eng.csv`
  126. Both are published under DATA.GOV.HK. Responses are cached briefly in-process
  127. (30 seconds for ETA, 6 hours for routes and timetables).
README.md · README · 194 lines · 1 finding marked
  1. # hkferry
  2. Hong Kong ferry routes, live ETAs and timetables as a Rust CLI and MCP server.
  3. Covers Hong Kong & Kowloon Ferry (HKKF) and Sun Ferry via their public,
  4. keyless open data.
  5. ## Install
  6. **Agent skill** — installs `SKILL.md` and the binary bootstrap script:
  7. ```bash
  8. npx skills add hongkong-ai-labs/hongkong-ferry-skill
  9. npx skills update # refresh the installed skill later
  10. ```
  11. **Prebuilt binary** — macOS (Intel or Apple silicon) and Linux (x86_64 or
  12. aarch64, static musl), checksum-verified, into `~/.local/bin`:
  13. ```bash
  14. curl -fsSL https://raw.githubusercontent.com/hongkong-ai-labs/hongkong-ferry-skill/main/scripts/install.sh | sh
    • Note: Pipes a downloaded script directly into a shell (curl | sh / wget | bash)
    • Line 21 on GitHub
  15. ```
  16. **From source** — Rust 1.89 or newer:
  17. ```bash
  18. git clone https://github.com/hongkong-ai-labs/hongkong-ferry-skill
  19. cd hongkong-ferry-skill
  20. cargo install --path . --locked
  21. # or directly from GitHub:
  22. cargo install --git https://github.com/hongkong-ai-labs/hongkong-ferry-skill --locked
  23. # or: cargo build --release --locked # target/release/hkferry
  24. ```
  25. Verify:
  26. ```console
  27. $ hkferry --version
  28. ```
  29. `hkferry update` detects whether the binary came from cargo, the release
  30. installer, a source checkout or Homebrew, and updates with that same
  31. method. `hkferry update --check` only reports.
  32. ## CLI
  33. ```bash
  34. hkferry routes
  35. hkferry routes --operator hkkf
  36. hkferry eta hkkf 2
  37. hkferry eta hkkf 2 --direction inbound
  38. hkferry eta sunferry CECC --json
  39. hkferry timetable hkkf 1 --direction outbound
  40. hkferry timetable sunferry CECC
  41. hkferry mcp
  42. hkferry update --check
  43. ```
  44. ## Routes
  45. | Operator | Routes |
  46. | --- | --- |
  47. | HKKF | Central–Sok Kwu Wan, Central–Yung Shue Wan, Central–Peng Chau, Peng Chau–Hei Ling Chau |
  48. | Sun Ferry | Central–Cheung Chau, Central–Mui Wo, North Point–Hung Hom, North Point–Kowloon City |
  49. ## MCP
  50. ```json
  51. {
  52. "mcpServers": {
  53. "hongkong-ferry": { "command": "hkferry", "args": ["mcp"] }
  54. }
  55. }
  56. ```
  57. Register it with any MCP client:
  58. ```bash
  59. npx add-mcp "$(command -v hkferry) mcp" --name hongkong-ferry -a claude-code -a codex -a cursor -y
  60. claude mcp add hongkong-ferry -- hkferry mcp
  61. codex mcp add hongkong-ferry -- hkferry mcp
  62. ```
  63. `add-mcp` detects the client configuration files in the current project; add
  64. `-g` for a global install. `$(command -v hkferry)` keeps the entry correct
  65. when the binary is on `PATH`; substitute an absolute path if your client does
  66. not inherit the shell `PATH`.
  67. Tools: `list_ferry_routes`, `get_ferry_eta`, `get_ferry_timetable`.
  68. ## Limits
  69. Live ETA is a prediction and can lag special arrangements. Star Ferry, Fortune
  70. Ferry and the Discovery Bay / Park Island ferries are not included. Timetable
  71. remarks are operator text; read the operator notice for a disruption.
  72. ## Run modes and deployment
  73. | Mode | Start with | Use for |
  74. | --- | --- | --- |
  75. | CLI | `hkferry <command>` | Interactive use and shell scripts |
  76. | JSON | `<command>` with `--json` | `jq`, automation, other programs |
  77. | MCP stdio | `hkferry mcp` | Desktop and CLI MCP clients |
  78. | Container | `docker run --rm -i hkferry mcp` | No local Rust toolchain |
  79. ### MCP and authentication
  80. This server is **stdio-only**: the client launches the process and speaks MCP
  81. over stdin/stdout. There is no listening port, so there is no network
  82. authentication layer and no API-key setting. Optional API keys in this project
  83. family apply only to servers that expose an HTTP transport. Keep the process
  84. local and let the MCP client manage it.
  85. Typical client entry:
  86. ```json
  87. {
  88. "mcpServers": {
  89. "hongkong-ferry-skill": {
  90. "command": "hkferry",
  91. "args": ["mcp"]
  92. }
  93. }
  94. }
  95. ```
  96. If the client does not inherit `PATH`, use the absolute installed path.
  97. ### Docker and Apple container
  98. ```bash
  99. docker build -t hkferry .
  100. docker run --rm hkferry --help
  101. docker run --rm -i hkferry mcp # stdio MCP
  102. docker compose run --rm stdio # same, through Compose
  103. ```
  104. Apple's `container` runtime uses the same OCI image:
  105. ```bash
  106. container build -t hkferry .
  107. container run --rm hkferry --help
  108. container run --rm -i hkferry mcp
  109. ```
  110. The runtime image contains the release binary and CA certificates, runs as a
  111. non-root user, and defaults to `--help` so a bare `docker run` is harmless.
  112. ### Cloudflare and WASM
  113. There is no Worker or WASM deployment. The binary talks directly to upstream
  114. HTTP APIs over TLS and uses a Tokio runtime; packaging it as a stdio server is
  115. the supported integration. A Worker would need a separate HTTP/JavaScript
  116. adapter and is out of scope for this repo.
  117. ### Releases
  118. Pushing a `v*` tag runs the release workflow, which checks the tag against
  119. `Cargo.toml` and `CHANGELOG.md`, builds four targets, smoke-tests native
  120. binaries and publishes:
  121. - `hkferry-<tag>-<target>.tar.gz` for macOS and static Linux
  122. - `SHA256SUMS` covering every tarball
  123. `scripts/install.sh` downloads the latest release, verifies its checksum and
  124. falls back to `cargo build --release --locked` when no release is available.
  125. `just tag X.Y.Z` creates the annotated tag locally; `just release X.Y.Z` tags
  126. and pushes to trigger the workflow.
  127. ## Development
  128. ```bash
  129. just # fmt check, clippy with -D warnings, tests
  130. just skill-check # validate SKILL.md and shell syntax
  131. just container # build the image and print CLI help
  132. cargo test --all --locked
  133. cargo clippy --all-targets --locked -- -D warnings
  134. cargo fmt --all -- --check
  135. ```
  136. `rust-toolchain.toml` pins the stable toolchain with `rustfmt` and
  137. `clippy`, so `rustup` sets contributors up automatically. `just doc`
  138. builds the API documentation. See `CONTRIBUTING.md` for the full check
  139. list and the signed-commit requirement.
  140. CI runs the same checks. Dependabot proposes weekly Cargo and GitHub Actions
  141. updates, and the audit workflow checks the lockfile against the RustSec
  142. advisory database.
  143. ## Licence
  144. MIT. Ferry data remains subject to the operators' terms and DATA.GOV.HK terms.

Ratings and comments

Sign in to rate this skill.

Sign in

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