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
Markdown
[](/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
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
- ---
- name: hongkong-ferry-skill
- 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.
- license: MIT
- ---
- # Hong Kong ferries
- `hkferry` is a Rust CLI and MCP server for the public HKKF and Sun Ferry open
- data feeds. It needs no API key and no account. It is an independent,
- unofficial project.
- Use it when the user asks about:
- - the next ferry from Central to Cheung Chau, Mui Wo, Yung Shue Wan, Sok Kwu
- Wan, Peng Chau or Hei Ling Chau
- - the next North Point ferry to Hung Hom or Kowloon City
- - a ferry timetable for a weekday, Saturday, Sunday or public holiday
- - which pier a route leaves from
- - whether a live ETA exists or only a published timetable
- ## Before first use
- Run `scripts/ensure-binary.sh` from the skill directory:
- ```console
- $ bash scripts/ensure-binary.sh
- /Users/you/.local/bin/hkferry
- ```
- It prints the absolute path of a working binary. Use it for every command:
- ```bash
- BIN="$(bash scripts/ensure-binary.sh)"
- ```
- It checks, in order: `$HKFERRY_BIN`, `hkferry` on `PATH`,
- `scripts/install.sh`, then `cargo build --release --locked` in the repo root.
- ### Install the binary directly
- `npx skills add` installs the skill files. If the binary is missing, install it
- with the release installer or cargo:
- ```bash
- curl -fsSL https://raw.githubusercontent.com/hongkong-ai-labs/hongkong-ferry-skill/main/scripts/install.sh | sh
- Note: Pipes a downloaded script directly into a shell (curl | sh / wget | bash)
- Line 46 on GitHub
- # or
- cargo install --git https://github.com/hongkong-ai-labs/hongkong-ferry-skill --locked
- ```
- Register it with any MCP client:
- ```bash
- npx add-mcp "$(command -v hkferry) mcp" --name hongkong-ferry -a claude-code -a codex -a cursor -y
- claude mcp add hongkong-ferry -- hkferry mcp
- codex mcp add hongkong-ferry -- hkferry mcp
- ```
- `add-mcp` detects the client configuration files in the current project; add
- `-g` for a global install. `$(command -v hkferry)` keeps the entry correct
- when the binary is on `PATH`; substitute an absolute path if your client does
- not inherit the shell `PATH`.
- ## CLI
- Prefer `--json` when you need to parse. Times are operator-local clock times
- in Hong Kong (UTC+8).
- ```bash
- $BIN routes # both operators
- $BIN routes --operator hkkf
- $BIN routes --operator sunferry --json
- $BIN eta hkkf 2 # Central -> Yung Shue Wan
- $BIN eta hkkf 2 --direction inbound # Yung Shue Wan -> Central
- $BIN eta hkkf "sok kwu" --json
- $BIN eta sunferry CECC # Central -> Cheung Chau
- $BIN eta sunferry "mui wo" --json
- $BIN timetable hkkf 1 --direction outbound
- $BIN timetable sunferry CECC --json
- $BIN update --check
- ```
- Routes can be selected by operator id (`2`), Sun Ferry code (`CECC`), timetable
- slug (`central_cheungchau`) or a name substring (`cheung chau`). If a name
- matches more than one route, the first match wins; use the id for certainty.
- ### Covered operators
- | Operator | Routes | Live ETA | Timetable |
- | --- | --- | --- | --- |
- | HKKF | 1 Central–Sok Kwu Wan, 2 Central–Yung Shue Wan, 3 Central–Peng Chau, 4 Peng Chau–Hei Ling Chau | yes | yes |
- | Sun Ferry | CECC Central–Cheung Chau, CEMW Central–Mui Wo, NPHH North Point–Hung Hom, NPKC North Point–Kowloon City | yes | yes |
- `--direction outbound` means away from the route's origin pier and `inbound`
- means towards it, as HKKF publishes them. Sun Ferry's ETA feed does not publish
- a direction, so both directions appear together.
- HKKF's published timetable encodes markers on some sailings: `*` (for example
- only on Saturdays), `#` (freight or advance-booking condition) and `^` (last
- sailing). Sun Ferry timetables use numeric remark codes; `1` and similar refer
- to the footnotes in the operator's published timetable.
- ## Reading results
- `eta` returns:
- | Field | Meaning |
- | --- | --- |
- | `depart` | Scheduled departure, `HH:MM` |
- | `eta` | Estimated arrival time as published, `HH:MM` |
- | `eta_at` | Full ETA timestamp when HKKF publishes one |
- | `vessel` | Vessel code when Sun Ferry publishes one |
- | `remark` | Operator remark, when present |
- An empty `sailings` array means the operator currently publishes no upcoming
- sailing — commonly after the last boat. Say that, and give the first published
- sailing from `timetable` rather than inventing one.
- Sun Ferry's live feed can include a sailing with a departure time but no `eta`
- yet. That is a scheduled sailing, not a confirmed arrival.
- ## MCP
- ```bash
- $BIN mcp
- ```
- ```json
- {
- "mcpServers": {
- "hongkong-ferry": {
- "command": "/absolute/path/to/hkferry",
- "args": ["mcp"]
- }
- }
- }
- ```
- Tools:
- | Tool | Arguments |
- | --- | --- |
- | `list_ferry_routes` | `{ "operator"?: "all"\|"hkkf"\|"sunferry" }` |
- | `get_ferry_eta` | `{ "operator": "hkkf"\|"sunferry", "route": string, "direction"?: "outbound"\|"inbound" }` |
- | `get_ferry_timetable` | `{ "operator": "hkkf"\|"sunferry", "route": string, "direction"?: "outbound"\|"inbound" }` |
- ## Cautions
- - Live ETAs are predictions. Typhoon, rainstorm, fog and special traffic
- arrangements can suspend or change sailings without a live update.
- - Not every Hong Kong ferry is here. Star Ferry, Fortune Ferry, Coral Ferry and
- the Discovery Bay / Park Island ferries are separate services.
- - The HKKF timetable feed sometimes embeds HTML in its remark columns. This
- tool extracts the sailing times and markers, not the full styled notice.
- - Do not present this as an official operator channel. For a disruption, check
- the operator's website or pier notice.
- ## Sources
- - HKKF: `https://www.hkkfeta.com/opendata/route/`, `/eta/{route}/{direction}`,
- `/time_table/{route}/{direction}`
- - Sun Ferry: `https://www.sunferry.com.hk/eta/?route={code}` and
- `/eta/timetable/SunFerry_{slug}_timetable_eng.csv`
- Both are published under DATA.GOV.HK. Responses are cached briefly in-process
- (30 seconds for ETA, 6 hours for routes and timetables).
README.md · README · 194 lines · 1 finding marked
- # hkferry
- Hong Kong ferry routes, live ETAs and timetables as a Rust CLI and MCP server.
- Covers Hong Kong & Kowloon Ferry (HKKF) and Sun Ferry via their public,
- keyless open data.
- ## Install
- **Agent skill** — installs `SKILL.md` and the binary bootstrap script:
- ```bash
- 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`:
- ```bash
- 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
- ```
- **From source** — Rust 1.89 or newer:
- ```bash
- 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:
- ```console
- $ 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.
- ## CLI
- ```bash
- hkferry routes
- hkferry routes --operator hkkf
- hkferry eta hkkf 2
- hkferry eta hkkf 2 --direction inbound
- hkferry eta sunferry CECC --json
- hkferry timetable hkkf 1 --direction outbound
- hkferry timetable sunferry CECC
- hkferry mcp
- hkferry update --check
- ```
- ## Routes
- | Operator | Routes |
- | --- | --- |
- | HKKF | Central–Sok Kwu Wan, Central–Yung Shue Wan, Central–Peng Chau, Peng Chau–Hei Ling Chau |
- | Sun Ferry | Central–Cheung Chau, Central–Mui Wo, North Point–Hung Hom, North Point–Kowloon City |
- ## MCP
- ```json
- {
- "mcpServers": {
- "hongkong-ferry": { "command": "hkferry", "args": ["mcp"] }
- }
- }
- ```
- Register it with any MCP client:
- ```bash
- npx add-mcp "$(command -v hkferry) mcp" --name hongkong-ferry -a claude-code -a codex -a cursor -y
- claude mcp add hongkong-ferry -- hkferry mcp
- codex mcp add hongkong-ferry -- hkferry mcp
- ```
- `add-mcp` detects the client configuration files in the current project; add
- `-g` for a global install. `$(command -v hkferry)` keeps the entry correct
- when the binary is on `PATH`; substitute an absolute path if your client does
- not inherit the shell `PATH`.
- Tools: `list_ferry_routes`, `get_ferry_eta`, `get_ferry_timetable`.
- ## Limits
- Live ETA is a prediction and can lag special arrangements. Star Ferry, Fortune
- Ferry and the Discovery Bay / Park Island ferries are not included. Timetable
- remarks are operator text; read the operator notice for a disruption.
- ## Run modes and deployment
- | Mode | Start with | Use for |
- | --- | --- | --- |
- | CLI | `hkferry <command>` | Interactive use and shell scripts |
- | JSON | `<command>` with `--json` | `jq`, automation, other programs |
- | MCP stdio | `hkferry mcp` | Desktop and CLI MCP clients |
- | Container | `docker run --rm -i hkferry mcp` | No local Rust toolchain |
- ### MCP and authentication
- This server is **stdio-only**: the client launches the process and speaks MCP
- over stdin/stdout. There is no listening port, so there is no network
- authentication layer and no API-key setting. Optional API keys in this project
- family apply only to servers that expose an HTTP transport. Keep the process
- local and let the MCP client manage it.
- Typical client entry:
- ```json
- {
- "mcpServers": {
- "hongkong-ferry-skill": {
- "command": "hkferry",
- "args": ["mcp"]
- }
- }
- }
- ```
- If the client does not inherit `PATH`, use the absolute installed path.
- ### Docker and Apple container
- ```bash
- docker build -t hkferry .
- docker run --rm hkferry --help
- docker run --rm -i hkferry mcp # stdio MCP
- docker compose run --rm stdio # same, through Compose
- ```
- Apple's `container` runtime uses the same OCI image:
- ```bash
- container build -t hkferry .
- container run --rm hkferry --help
- container run --rm -i hkferry mcp
- ```
- The runtime image contains the release binary and CA certificates, runs as a
- non-root user, and defaults to `--help` so a bare `docker run` is harmless.
- ### Cloudflare and WASM
- There is no Worker or WASM deployment. The binary talks directly to upstream
- HTTP APIs over TLS and uses a Tokio runtime; packaging it as a stdio server is
- the supported integration. A Worker would need a separate HTTP/JavaScript
- adapter and is out of scope for this repo.
- ### Releases
- Pushing a `v*` tag runs the release workflow, which checks the tag against
- `Cargo.toml` and `CHANGELOG.md`, builds four targets, smoke-tests native
- binaries and publishes:
- - `hkferry-<tag>-<target>.tar.gz` for macOS and static Linux
- - `SHA256SUMS` covering every tarball
- `scripts/install.sh` downloads the latest release, verifies its checksum and
- falls back to `cargo build --release --locked` when no release is available.
- `just tag X.Y.Z` creates the annotated tag locally; `just release X.Y.Z` tags
- and pushes to trigger the workflow.
- ## Development
- ```bash
- just # fmt check, clippy with -D warnings, tests
- just skill-check # validate SKILL.md and shell syntax
- just container # build the image and print CLI help
- cargo test --all --locked
- cargo clippy --all-targets --locked -- -D warnings
- cargo fmt --all -- --check
- ```
- `rust-toolchain.toml` pins the stable toolchain with `rustfmt` and
- `clippy`, so `rustup` sets contributors up automatically. `just doc`
- builds the API documentation. See `CONTRIBUTING.md` for the full check
- list and the signed-commit requirement.
- CI runs the same checks. Dependabot proposes weekly Cargo and GitHub Actions
- updates, and the audit workflow checks the lockfile against the RustSec
- advisory database.
- ## Licence
- MIT. Ferry data remains subject to the operators' terms and DATA.GOV.HK terms.
Ratings and comments
Sign in to rate this skill.
Sign inFree to use. If it’s helped, pass it on.