Skip to content
Back to search

hongkong-airport-skill

Live Hong Kong International Airport (HKG) flight information — departures, arrivals, delays, cancellations, terminal/gate/check-in/aisle/baggage guidance, disruption alerts, watchlists, historical on-time analytics, HKO weather context, and airport access (Airport Express, in-town check-in, A-route buses). Use for any question about HKG flights, real-time status, airport delays, terminals, on-time performance, or getting to and from the airport.

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

HTML

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

The skill teaches an agent when to use the CLI or call the MCP tools. It needs the `hkia` binary at runtime; `scripts/ensure-binary.sh` finds or installs it.

Official skills CLI (Node.js 22.20+):

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

Rust-only alternative ([community `skills-cli`](https://crates.io/crates/skills-cli), not maintained by this project):

cargo install skills-cli --locked
skills add hongkong-ai-labs/hongkong-airport-skill

Manual install without either CLI:

git clone --depth 1 https://github.com/hongkong-ai-labs/hongkong-airport-skill /tmp/hkia-skill
mkdir -p .agents/skills
cp -R /tmp/hkia-skill .agents/skills/hongkong-airport-skill
rm -rf .agents/skills/hongkong-airport-skill/.git

bash .agents/skills/hongkong-airport-skill/scripts/ensure-binary.sh

Use `~/.agents/skills` instead of `.agents/skills` for a user-wide install. Claude Code also reads `~/.claude/skills`; other agents use their own skills directory. `.agents/skills` is the portable layout used by both skills CLIs.

Before first use, the skill runs `scripts/ensure-binary.sh`. It checks `$HKIA_BIN`, then `hkia` on `PATH`, then `scripts/install.sh`, then a local `cargo build --release --locked`, and prints the absolute binary path to use.

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-airport-skill/main/scripts/install.sh | sh

Or from a checkout:

sh scripts/install.sh
# override with HKIA_BIN_DIR, HKIA_VERSION or HKIA_FORCE_INSTALL=1

Releases publish `hkia-vX.Y.Z-<target>.tar.gz` plus `SHA256SUMS`. The installer verifies the checksum, replaces an older binary atomically, and falls back to a source build if a release asset is unavailable.

From source

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

Requires Rust 1.89 or newer. SQLite is bundled, so there is no system `libsqlite3` dependency.

Docker

docker build -t hkia .
docker run --rm hkia departures --limit 10

# Streamable HTTP MCP, with persistent history and config
docker run --rm -p 8787:8787 \
  -v hkia-data:/data -v hkia-config:/config \
  -e HKIA_DATA_DIR=/data -e HKIA_CONFIG=/config/config.toml \
  hkia mcp --transport http --host 0.0.0.0 --port 8787

For a stdio MCP client, use the container as the server process:

docker run --rm -i -v hkia-data:/data hkia mcp

Apple's `container` runtime uses the same OCI image:

container build -t hkia .
container run --rm hkia departures --limit 10
container run --rm -p 8787:8787 -e HKIA_MCP_API_KEY="$SECRET" \
  hkia mcp --transport http --host 0.0.0.0 --port 8787

Or `docker compose up --build`. The compose file exposes port 8787 and mounts named volumes for the SQLite store and watchlist. If you expose the HTTP MCP transport beyond localhost, set `HKIA_MCP_API_KEY` (or use `--api-key`).

Cloudflare Worker + Container

`wrangler.jsonc` and `cloudflare/` deploy the HTTP MCP server as a Worker front door plus a Cloudflare Container. Wrangler builds the `linux/amd64` image from the root `Dockerfile`; a Docker-compatible engine is required. Set the optional key and deploy from the repository root:

npx wrangler secret put HKIA_MCP_API_KEY
npx wrangler deploy

Cloudflare's remote MCP transport is Streamable HTTP at `/mcp`; `/health` stays public. A pure WASM Worker is deliberately not included: the server needs TCP/TLS, a Tokio runtime and bundled SQLite. See [`cloudflare/README.md`](cloudflare/README.md).

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 · 449 lines
  1. ---
  2. name: hongkong-airport-skill
  3. description: Live Hong Kong International Airport (HKG) flight information — departures, arrivals, delays, cancellations, terminal/gate/check-in/aisle/baggage guidance, disruption alerts, watchlists, historical on-time analytics, HKO weather context, and airport access (Airport Express, in-town check-in, A-route buses). Use for any question about HKG flights, real-time status, airport delays, terminals, on-time performance, or getting to and from the airport.
  4. license: MIT
  5. ---
  6. # HKIA flights
  7. `hkia` is a Rust CLI and MCP server for the public Hong Kong International Airport
  8. flight-information feed. It needs no data API key and no account; the HTTP MCP
  9. transport can optionally require a static API key. It is an
  10. independent, unofficial project and is not affiliated with the airport.
  11. Use it when the user asks about:
  12. - a flight arriving at or departing from Hong Kong (CX, UO, HX, NH, BA, QR, ...)
  13. - delays, cancellations, estimated or actual times
  14. - which terminal, check-in aisle, gate, stand, baggage belt, or arrival hall to use
  15. - disruption alerts, a specific flight, an airport, or an airline
  16. - on-time performance for a day or a historical date range
  17. - watching a board for changes, or a persistent timeline of what was observed
  18. - weather warnings affecting airport operations
  19. - Airport Express trains, in-town check-in, or airport A-route buses
  20. ## Before first use
  21. Run `scripts/ensure-binary.sh` from the skill directory:
  22. ```console
  23. $ bash scripts/ensure-binary.sh
  24. /Users/you/.local/bin/hkia
  25. ```
  26. It prints the absolute path of a working `hkia` binary and exits non-zero only
  27. if it could not download or build one. Use the printed path for every later
  28. command, for example `BIN="$(bash scripts/ensure-binary.sh)"`, and do not assume
  29. `hkia` is on `PATH`.
  30. It checks, in order: `$HKIA_BIN`, `hkia` on `PATH`, `scripts/install.sh`, then
  31. `cargo build --release --locked` in the repo root.
  32. ## Install
  33. Skill only (teaches the agent to use the CLI):
  34. ```bash
  35. npx skills add hongkong-ai-labs/hongkong-airport-skill
  36. ```
  37. Rust-only alternative (community port):
  38. ```bash
  39. cargo install skills-cli --locked
  40. skills add hongkong-ai-labs/hongkong-airport-skill
  41. ```
  42. Manual install: copy this directory, or just `SKILL.md` plus `scripts/`, into
  43. the agent's skills directory (for example `.agents/skills/hongkong-airport-skill`
  44. or `~/.claude/skills/hongkong-airport-skill`). Then run
  45. `scripts/ensure-binary.sh` from that directory.
  46. The binary (choose one):
  47. ```bash
  48. sh scripts/install.sh # from the skill directory; checksum-verified
  49. cargo install --path . # from a clone of this repo
  50. cargo install --git https://github.com/hongkong-ai-labs/hongkong-airport-skill --bin hkia --locked
  51. ```
  52. ## Run modes
  53. Use the CLI for one-shot queries and MCP when a client should call tools
  54. directly. The transport changes how a client connects, not the data or tools.
  55. | Mode | Start with | Use for |
  56. | --- | --- | --- |
  57. | CLI table | `hkia departures` | Human-readable board |
  58. | JSON | `hkia departures --json` | Parsing and summarising |
  59. | CSV | `hkia departures --csv` | Spreadsheet or pipeline output |
  60. | Watch | `hkia watch --interval 60` | Change-only output |
  61. | MCP stdio | `hkia mcp` | Client launches the process |
  62. | MCP HTTP | `hkia mcp --transport http` | Shared long-lived server |
  63. | MCP SSE | `hkia mcp --transport sse` | Legacy SSE clients |
  64. | Docker | `docker run --rm hkia departures` | No local binary |
  65. ## CLI
  66. Prefer `--json` when you need to parse or summarise output. Tables are for
  67. humans. Times are Hong Kong time (UTC+8); JSON timestamps are RFC 3339 with
  68. `+08:00`.
  69. ```bash
  70. # Today's boards
  71. hkia departures --json
  72. hkia arrivals --json
  73. # A date (YYYY-MM-DD, today, yesterday, tomorrow)
  74. hkia flights --direction departure --date 2026-11-21 --json
  75. # One flight, both boards and all codeshares
  76. hkia flight CX251 --json
  77. hkia flight "CX 251" --date tomorrow --json
  78. # Delays and disruption alerts
  79. hkia delays --min-delay 15 --json
  80. hkia alerts --min-delay 30 --no-cancelled --json
  81. hkia alerts --watchlist --weather --json
  82. # On-time stats: single day, or a historical range
  83. hkia stats --json
  84. hkia stats --from 2026-11-01 --to 2026-11-14 --group-by airline --json
  85. hkia stats --from 2026-09-01 --group-by weekday --json
  86. # Locally observed timeline
  87. hkia history CX251 --json
  88. # Live changes: baseline, then only differences
  89. hkia watch --interval 60
  90. hkia watch --direction arrival --min-delay 20 --json # NDJSON ticks
  91. # Filters and formats
  92. hkia departures --airport LHR --terminal T1 --airline CPA --limit 20 --json
  93. hkia departures --status disrupted --csv
  94. hkia departures --lang zh_HK --limit 10 --json
  95. hkia departures --cargo --limit 10 --json
  96. # Airport access
  97. hkia access ael --station HOK --json
  98. hkia access ael --station AIR --direction from-airport --json
  99. hkia access status --json
  100. hkia access checkin --airline CX --json
  101. hkia access bus --route A11 --json
  102. hkia access bus --route A35 --direction to-airport --json
  103. hkia access trip --airline CX --time 23:59 --date tomorrow --json
  104. hkia update --check
  105. ```
  106. Run `hkia <command> --help` for per-command filters such as `--flight`,
  107. `--airport`, `--airline`, `--terminal`, `--status`, `--delayed-over`, and `--sort`.
  108. The range endpoint covers D-91 through D+14. Historical range reports include
  109. `by_day`, `by_airline`, `by_route`, `by_weekday`, and `by_hour`; failed days
  110. appear in `failures`.
  111. `--lang` accepts `en`, `zh_HK`, or `zh_CN` (default `en`). It changes the raw
  112. status text, not JSON field names or `guidance`, which stay English. All three
  113. languages are parsed for status type, delay basis, and cancellations.
  114. ## Terminal and gate guidance
  115. Each flight JSON object has the airport's operational fields plus a derived
  116. `guidance` string:
  117. | Field | Meaning |
  118. | --- | --- |
  119. | `terminal` | Terminal, usually `T1` or `T2` |
  120. | `gate` | Departure gate, or arrival gate when published |
  121. | `stand` | Arrival stand when the airport publishes a remote stand |
  122. | `check_in_aisle` | Departure check-in aisle letter |
  123. | `baggage_belt` | Arrival reclaim belt |
  124. | `arrival_hall` | Arrival hall |
  125. | `guidance` | Human-readable instruction built only from the above |
  126. Examples:
  127. - `Depart from Terminal 1, check-in aisle C, gate 30`
  128. - `Arrive at Terminal 1, gate 30; baggage belt 12, arrival hall A`
  129. - `Depart from Terminal 1, check-in aisle C` when the gate is not yet assigned
  130. When answering “which terminal?”, lead with `guidance` if present, then the raw
  131. `terminal`, `gate`, `check_in_aisle`, `baggage_belt`, and `arrival_hall` fields.
  132. If a field is `null`, say it has not been published yet; never fill it from a
  133. different flight or a previous day. Gates and terminals can change, so include
  134. `fetched_at` or `lastUpdated` when the user needs current information.
  135. The feed does **not** provide airline counter rows, security queue times,
  136. walking times between gates, or a per-flight ATC transcript.
  137. ## Other fields
  138. | Field | Meaning |
  139. | --- | --- |
  140. | `flight_number`, `codeshares` | Operating number first; other marketing numbers after |
  141. | `airline`, `airline_name` | ICAO code and resolved airline name |
  142. | `direction`, `date` | `departure`/`arrival`, board date |
  143. | `scheduled_time`, `scheduled_at` | Timetable time; RFC 3339 timestamp |
  144. | `status`, `status_type` | Raw airport text; `departed`, `arrived`, `estimated`, `cancelled`, `scheduled`, `other` |
  145. | `status_published` | Whether a non-scheduled status is present |
  146. | `actual_at`, `estimated_at` | Parsed event time when published |
  147. | `delay_minutes`, `delay_basis` | Event time minus schedule; `actual`, `estimated`, or null |
  148. | `state` | `cancelled`, `delayed` (>=15 min), `on_time`, `early`, `scheduled` |
  149. | `origin`, `destination` | IATA code lists; multi-leg flights list every stop |
  150. | `origin_details`, `destination_details` | Resolved airport name, city, country |
  151. | `fetched_at` | When this observation was fetched |
  152. Delay minutes are computed from the airport's free-text status against the
  153. scheduled time. English, Traditional Chinese, and Simplified Chinese status
  154. terms are recognised. They are not airline cause codes and do not distinguish
  155. weather, crew, slot, or maintenance reasons. `guidance` is always English.
  156. ## Airport access
  157. Use `hkia access` for getting to or from HKG. It is separate from the flight
  158. commands and keeps the same `--json` / `--csv` conventions.
  159. ```bash
  160. hkia access ael --station HOK
  161. hkia access ael --station KOW --direction both --json
  162. hkia access status
  163. hkia access checkin --airline CX
  164. hkia access checkin --airline CPA --json
  165. hkia access bus --route A11
  166. hkia access bus --route A11 --direction from-airport --no-live
  167. hkia access bus --csv
  168. hkia access trip --station KOW --airline CX --time 07:40 --terminal T1 --buffer 15
  169. # Runway in use
  170. hkia runway
  171. hkia runway --json
  172. hkia runway --history
  173. ```
  174. - `ael` is **live** from the MTR Next Train API. Stations: `HOK`, `KOW`, `TSY`,
  175. `AIR`, `AWE`. Direction is `to-airport`, `from-airport`, or `both`; it
  176. defaults from the station. Each response has `trains`, plus `service` with
  177. journey times, first/last windows, official fares, `checked_on`, and sources.
  178. - `status` is **live** from the same API's `isdelay` flag at HOK and AIR. Use it
  179. for "is the Airport Express disrupted" questions; it reports only whether MTR
  180. flagged a delay, not a cause or duration. `alerts` and `watch` include it by
  181. default (`--no-ael` disables), and watch notifies when the flag changes.
  182. - `checkin` is a **dated snapshot** of MTR's published in-town check-in list.
  183. It matches IATA (`CX`), ICAO (`CPA`) or name. Returns station hours,
  184. eligibility, baggage limits, `source`, and `checked_on`. It is not live
  185. availability and does not confirm a specific flight is accepted.
  186. - `bus` is a **dated snapshot** of the 30 HKIA A-routes in both directions,
  187. with destination, operator, adult fares and city-to-airport and from-airport
  188. windows. With `--route` it adds **live** Citybus/LWB/KMB/NLB ETAs for the
  189. published terminus stop; `--direction` selects the direction and `--no-live`
  190. keeps it static. ETAs are for the terminus, not the airport kerb.
  191. - `trip` plans the latest AEL departure for a flight: 90-minute check-in cutoff,
  192. explicit `--buffer` (default 0), published journey time, rounded down to the
  193. 10-minute headway, plus the airport deadline and in-town check-in hours. It
  194. never assumes security, immigration or walking time. The time must be in the
  195. future Hong Kong time; `--date tomorrow` handles late-night flights today.
  196. The reference snapshot was checked on `2026-11-22`. Always pass through
  197. `checked_on` and the source URL, and tell the user to confirm with MTR, the
  198. airline, or the bus operator before travel. `scripts/refresh_access_data.py
  199. --check` verifies the snapshots against the official sources.
  200. ## Runway in use
  201. `hkia runway` reports the runway in use for arrivals and departures, the ATIS
  202. letter and issue time, and the airport wind with computed head/tailwind and
  203. crosswind for the arrival runway. The source is the official CAD ATIS page on
  204. `hkatc.gov.hk`, not a guess from wind.
  205. - Runway `07` means aircraft land heading eastbound, approaching from the west;
  206. runway `25` means westbound approaches from the east. Use this for questions
  207. about which side aircraft are coming in over, or aircraft noise.
  208. - Arrivals and departures can use different runways; report both.
  209. - Runway 07 is preferred when the tailwind is 5 knots or less (AIP VHHH
  210. AD 2.22), but ATC can use 25 when required. Do not predict the runway from
  211. wind when the ATIS is available.
  212. - If the ATIS page is unavailable, the command falls back to the HKO 10-minute
  213. wind at Chek Lap Kok: `atis_available` is false, `wind` holds the observation
  214. and `wind_favours` applies the AIP rule. Say the runway is not confirmed and
  215. do not present the favoured runway as the runway in use. If both feeds fail,
  216. report the error.
  217. - The live output also shows the last switch this machine observed
  218. (`last_observed` in JSON, null if none), so you can say how long the current
  219. runway has held. It is local observation, not part of the ATIS.
  220. - `hkia watch` prints and notifies when the runway changes; `--no-runway`
  221. disables that check. Each observed switch is stored in SQLite, and
  222. `hkia runway --history [--limit N] [--daily]` lists them oldest first, or
  223. grouped per day with the switch count and first/last runway. History only
  224. covers periods when `watch` was running; it is not an official record. The
  225. same rows are available as `get_runway_history` (`limit` keeps the most
  226. recent N, default 20; `daily` groups them by date) and as the
  227. `hkia://runway/history` resource (last 20).
  228. ## Watchlist and notifications
  229. The watchlist is TOML at `$HKIA_CONFIG`, `$XDG_CONFIG_HOME/hkia/config.toml`, or
  230. `~/.config/hkia/config.toml`:
  231. ```toml
  232. [watchlist]
  233. flights = ["CX251"]
  234. airports = ["LHR"]
  235. airlines = ["CPA"]
  236. direction = "departure"
  237. min_delay = 10
  238. include_cancelled = true
  239. [notify]
  240. desktop = false
  241. webhook = "https://example.test/hook"
  242. ```
  243. Manage it with `hkia watchlist add --flight CX251`,
  244. `hkia watchlist add --airport LHR`, `hkia watchlist set --min-delay 10`,
  245. `hkia watchlist show`, and `hkia watchlist remove --flight CX251`.
  246. Use `--watchlist` with `alerts` or `watch` to restrict output to the watchlist.
  247. `--notify` sends desktop notifications; `--webhook URL` POSTs JSON. `watch` also
  248. reports AEL delay changes (`--no-ael` disables) and runway-in-use changes
  249. (`--no-runway` disables), each with its own notification kind. Alert
  250. notifications are deduplicated by fingerprint in SQLite, so a restart does not
  251. resend the same alert. Empty selectors match everything.
  252. ## Persistence and history
  253. The local SQLite store is at `$HKIA_DATA_DIR/hkia.db`,
  254. `$XDG_DATA_HOME/hkia/hkia.db`, or `~/.local/share/hkia/hkia.db`. Watch ticks,
  255. `history`, notification-enabled alert checks, and MCP history/watch calls record
  256. observations. Events are appended only when status, delay, gate, terminal, belt,
  257. or stand changes. `history` shows what this machine observed, not an official airport audit trail.
  258. The same applies to `hkia runway --history`, which stores one row per observed
  259. runway switch. Data older than `--keep-days` (default 90) is pruned
  260. opportunistically; `watch` starts with a one-line summary of the stored
  261. history, and `alerts` prints the last observed switch with the live runway.
  262. ## MCP
  263. ```bash
  264. hkia mcp # stdio (Claude Desktop, Cursor, Codex, ...)
  265. hkia mcp --transport http # streamable HTTP on http://127.0.0.1:8787/mcp
  266. hkia mcp --transport sse # legacy SSE on http://127.0.0.1:8787/sse
  267. ```
  268. Client config for stdio:
  269. ```json
  270. {
  271. "mcpServers": {
  272. "hkia": {
  273. "command": "hkia",
  274. "args": ["mcp"]
  275. }
  276. }
  277. }
  278. ```
  279. If `hkia` is not on the MCP client's `PATH`, use the absolute path printed by
  280. `scripts/ensure-binary.sh` as `command`. Restart the client after editing its
  281. configuration.
  282. Claude Code and Codex can register the stdio server themselves:
  283. ```bash
  284. claude mcp add hkia -- /absolute/path/to/hkia mcp
  285. codex mcp add hkia -- /absolute/path/to/hkia mcp
  286. ```
  287. `npx add-mcp /absolute/path/to/hkia --args mcp --name hkia -a claude-code -y`
  288. is a third-party helper that writes the same entry for many clients. For HTTP,
  289. point the client at `http://127.0.0.1:8787/mcp`; for SSE, use
  290. `http://127.0.0.1:8787/sse` (messages are POSTed to the endpoint URL the server
  291. sends in the `endpoint` event). `GET /health` is available on both network
  292. transports. `--path` changes the streamable HTTP endpoint.
  293. For non-loopback use, set an API key with `--api-key` (alias `--auth-token`)
  294. or `HKIA_MCP_API_KEY`; requests then need `Authorization: Bearer <key>` or
  295. `X-API-Key: <key>`. `HKIA_API_KEY` and `HKIA_AUTH_TOKEN` are aliases.
  296. `--rate-limit` caps HTTP/SSE requests per minute (default 240, `0` disables).
  297. The server has no TLS of its own and uses one shared static token; bind loopback
  298. or terminate TLS at a reverse proxy before exposing it.
  299. MCP tools:
  300. - `list_flights` — board listing with airport, airline, terminal, state, delay,
  301. sort, and limit filters
  302. - `search_flight` — one flight number across both boards
  303. - `get_delays` — flights delayed beyond a threshold
  304. - `get_alerts` — cancellations and delays as severity-ranked alerts, with
  305. optional weather, AEL status and runway in use (`include_ael`, `include_runway`)
  306. - `get_stats` — single-day on-time performance and hourly breakdown
  307. - `get_watchlist_alerts` — disruptions filtered to the local watchlist
  308. - `get_flight_history` — locally observed status/gate/belt timeline
  309. - `get_historical_stats` — historical range analytics
  310. - `wait_for_changes` — long-poll for new recorded changes; pass the returned timestamp as `after`
  311. - `get_airport_access` — modes `airport-express`, `airport-express-status`,
  312. `in-town-checkin`, `airport-bus`, `trip` (`station`, `direction`, `airline`,
  313. `route`, `time`, `date`, `terminal`, `buffer_minutes`, `no_live`)
  314. - `get_weather` — current Hong Kong Observatory warnings
  315. - `get_runway_status` — runway in use for arrivals/departures, ATIS wind, wind
  316. components and the last locally observed switch, no arguments
  317. - `get_runway_history` — locally observed switches, oldest first; optional
  318. `limit` (default 20, 0 returns all) and `daily` grouping
  319. Most flight tools take `date`, `direction`, `cargo`, and `lang`; check the tool
  320. schema for exact parameter names.
  321. MCP resources:
  322. - `hkia://board/today/departures`
  323. - `hkia://board/today/arrivals`
  324. - `hkia://alerts/today`
  325. - `hkia://access/ael/status`
  326. - `hkia://access/ael/HOK` (any station code)
  327. - `hkia://access/checkin/CX` (any airline code)
  328. - `hkia://access/bus/A11` (any A-route)
  329. - `hkia://runway/status`
  330. - `hkia://runway/history` (locally observed switches, last 20)
  331. Resources are JSON and support read plus legacy subscribe/unsubscribe; updates
  332. are polled every 30 seconds. Prefer `wait_for_changes` for push-style clients.
  333. ## Troubleshooting
  334. - `ensure-binary.sh` needs either a published release, a checkout with
  335. `Cargo.toml`, or `$HKIA_BIN`. If it fails, ask the user for an `hkia` path
  336. rather than inventing one.
  337. - MCP `401` means the bearer token is missing or wrong; `429` means the
  338. process-wide rate limit was hit. Read `Retry-After` before retrying.
  339. - Webhook delivery has a 15-second timeout and no retry queue. Errors are
  340. warnings; the watch loop continues.
  341. ## Rules and limits
  342. - Never invent a flight, terminal, gate, aisle, belt, delay, or cause. If the
  343. tool returns no match, say so and offer the nearest board or date.
  344. - Never present computed delay minutes as an official airline metric.
  345. - The feed is published per calendar day. Future dates may be empty or missing;
  346. querying tomorrow early in the day can legitimately return no board.
  347. - Cargo flights live on a separate board: pass `--cargo` / `"cargo": true`.
  348. - Never invent an Airport Express time, check-in hour, bus route, fare, ETAs,
  349. or departure window. If a lookup fails, say so. In-town check-in, fare and
  350. bus facts are dated snapshots, not live availability; quote `checked_on`.
  351. AEL trains, the delay flag and bus ETAs are live and can be unavailable.
  352. - The AEL delay flag is a coarse signal. Do not convert it into a delay length,
  353. cause, or recommendation to rebook. The trip planner's output is a plan based
  354. on published timetables and the stated buffer, not a guarantee of on-time
  355. arrival.
  356. - Never invent a runway. Quote the ATIS arrival/departure runways separately.
  357. The approach side follows from the runway designator; it is not an observed
  358. flight track, and runway use can change at any time.
  359. - The live feed may include the previous day's tail; this tool selects the
  360. requested date. Keep request rates reasonable; responses cache for 20 seconds
  361. by default (`--cache-ttl 0` disables, `watch` is uncached).
  362. - **ATC/tower text is not available.** HKIA tower communications are voice
  363. radio; there is no public per-flight ATC text or transcription endpoint. Do
  364. not claim to quote tower instructions. You can report published delays,
  365. cancellations, weather warnings, and gate changes, and clearly label any
  366. outside audio/transcript as unverified and unofficial.
  367. - Flight reference data comes from OurAirports (public domain) and OpenFlights
  368. (ODbL). Airport access facts come from MTR and HKIA public pages. See
  369. `NOTICE`.
README.md · README · 856 lines · 1 finding marked
  1. <div align="center">
  2. # hkia
  3. **Live Hong Kong International Airport flight data in one binary.**
  4. [![CI](https://github.com/hongkong-ai-labs/hongkong-airport-skill/actions/workflows/ci.yml/badge.svg)](https://github.com/hongkong-ai-labs/hongkong-airport-skill/actions/workflows/ci.yml)
  5. [![Release](https://img.shields.io/github/v/release/hongkong-ai-labs/hongkong-airport-skill?style=flat-square&color=0e9488)](https://github.com/hongkong-ai-labs/hongkong-airport-skill/releases/latest)
  6. [![License](https://img.shields.io/badge/license-MIT-0e9488?style=flat-square)](LICENSE)
  7. [![Rust](https://img.shields.io/badge/rust-1.89%2B-0e9488?style=flat-square&logo=rust&logoColor=white)](Cargo.toml)
  8. [![MCP](https://img.shields.io/badge/MCP-stdio%20%7C%20HTTP%20%7C%20SSE-0e9488?style=flat-square)](https://modelcontextprotocol.io)
  9. </div>
  10. Live Hong Kong International Airport flight data from your terminal, your MCP
  11. client, or your agent.
  12. `hkia` reads the airport's public flight-information feed — the same feed behind
  13. the HKIA app and website — and turns it into:
  14. - a Rust CLI with tables, JSON, CSV and colour
  15. - an MCP server over **stdio**, **streamable HTTP**, or **legacy SSE**
  16. - a locally persisted timeline of what the airport actually published
  17. - targeted watchlists with desktop and webhook notifications
  18. - historical on-time analytics for the feed's D-91 to D+14 window
  19. - live Airport Express trains and delay status, a trip planner, in-town check-in
  20. reference, and A-route bus data with live ETAs
  21. - the runway in use with the airport wind and computed wind components
  22. - an installable agent skill (`SKILL.md`)
  23. No data API key, no scraping, no browser automation. The HTTP MCP transport can
  24. optionally require a static API key.
  25. This is an independent, unofficial project. It is not affiliated with Airport
  26. Authority Hong Kong or HKIA, it sends no telemetry, and the underlying feed
  27. remains subject to the airport's own terms.
  28. ## What you get
  29. Schedules, estimated and actual times, computed delays, cancellations, terminal,
  30. gate or stand, check-in aisle, baggage belt, arrival hall, codeshares, airline
  31. and airport names, and ready-to-read terminal guidance. Plus disruption alerts,
  32. hourly and multi-day statistics, a restart-safe watchlist, and Hong Kong
  33. Observatory weather warnings as operational context. All times are normalised
  34. to Hong Kong time (UTC+8).
  35. ### Terminal, gate and arrival guidance
  36. Every flight carries the raw airport fields and a derived `guidance` string:
  37. - departure: `Depart from Terminal 1, check-in aisle C, gate 30`
  38. - arrival: `Arrive at Terminal 1, gate 30; baggage belt 12, arrival hall A`
  39. - partial data produces partial guidance rather than an invented instruction
  40. - cancelled flights say so instead of sending you to a gate
  41. The airport feed does not publish airline check-in counter rows, security wait
  42. times, or a per-flight air-traffic-control transcript. See
  43. [Data limits and ATC](#data-limits-and-atc).
  44. ## Install
  45. ### Agent skill
  46. The skill teaches an agent when to use the CLI or call the MCP tools. It needs
  47. the `hkia` binary at runtime; `scripts/ensure-binary.sh` finds or installs it.
  48. Official skills CLI (Node.js 22.20+):
  49. ```bash
  50. npx skills add hongkong-ai-labs/hongkong-airport-skill
  51. npx skills update # refresh the installed skill later
  52. ```
  53. Rust-only alternative ([community `skills-cli`](https://crates.io/crates/skills-cli),
  54. not maintained by this project):
  55. ```bash
  56. cargo install skills-cli --locked
  57. skills add hongkong-ai-labs/hongkong-airport-skill
  58. ```
  59. Manual install without either CLI:
  60. ```bash
  61. git clone --depth 1 https://github.com/hongkong-ai-labs/hongkong-airport-skill /tmp/hkia-skill
  62. mkdir -p .agents/skills
  63. cp -R /tmp/hkia-skill .agents/skills/hongkong-airport-skill
  64. rm -rf .agents/skills/hongkong-airport-skill/.git
  65. bash .agents/skills/hongkong-airport-skill/scripts/ensure-binary.sh
  66. ```
  67. Use `~/.agents/skills` instead of `.agents/skills` for a user-wide install.
  68. Claude Code also reads `~/.claude/skills`; other agents use their own skills
  69. directory. `.agents/skills` is the portable layout used by both skills CLIs.
  70. Before first use, the skill runs `scripts/ensure-binary.sh`. It checks
  71. `$HKIA_BIN`, then `hkia` on `PATH`, then `scripts/install.sh`, then a local
  72. `cargo build --release --locked`, and prints the absolute binary path to use.
  73. ### Prebuilt binary
  74. macOS (Intel or Apple silicon) and Linux (x86_64 or aarch64, static musl),
  75. checksum-verified into `~/.local/bin`:
  76. ```bash
  77. curl -fsSL https://raw.githubusercontent.com/hongkong-ai-labs/hongkong-airport-skill/main/scripts/install.sh | sh
    • Note: Pipes a downloaded script directly into a shell (curl | sh / wget | bash)
    • Line 107 on GitHub
  78. ```
  79. Or from a checkout:
  80. ```bash
  81. sh scripts/install.sh
  82. # override with HKIA_BIN_DIR, HKIA_VERSION or HKIA_FORCE_INSTALL=1
  83. ```
  84. Releases publish `hkia-vX.Y.Z-<target>.tar.gz` plus `SHA256SUMS`. The installer
  85. verifies the checksum, replaces an older binary atomically, and falls back to a
  86. source build if a release asset is unavailable.
  87. ### From source
  88. ```bash
  89. git clone https://github.com/hongkong-ai-labs/hongkong-airport-skill
  90. cd hongkong-airport-skill
  91. cargo install --path . --locked
  92. # or directly from GitHub:
  93. cargo install --git https://github.com/hongkong-ai-labs/hongkong-airport-skill --locked
  94. # or: cargo build --release --locked # target/release/hkia
  95. ```
  96. Requires Rust 1.89 or newer. SQLite is bundled, so there is no system
  97. `libsqlite3` dependency.
  98. ### Docker
  99. ```bash
  100. docker build -t hkia .
  101. docker run --rm hkia departures --limit 10
  102. # Streamable HTTP MCP, with persistent history and config
  103. docker run --rm -p 8787:8787 \
  104. -v hkia-data:/data -v hkia-config:/config \
  105. -e HKIA_DATA_DIR=/data -e HKIA_CONFIG=/config/config.toml \
  106. hkia mcp --transport http --host 0.0.0.0 --port 8787
  107. ```
  108. For a stdio MCP client, use the container as the server process:
  109. ```bash
  110. docker run --rm -i -v hkia-data:/data hkia mcp
  111. ```
  112. Apple's `container` runtime uses the same OCI image:
  113. ```bash
  114. container build -t hkia .
  115. container run --rm hkia departures --limit 10
  116. container run --rm -p 8787:8787 -e HKIA_MCP_API_KEY="$SECRET" \
  117. hkia mcp --transport http --host 0.0.0.0 --port 8787
  118. ```
  119. Or `docker compose up --build`. The compose file exposes port 8787 and mounts
  120. named volumes for the SQLite store and watchlist. If you expose the HTTP MCP
  121. transport beyond localhost, set `HKIA_MCP_API_KEY` (or use `--api-key`).
  122. ### Cloudflare Worker + Container
  123. `wrangler.jsonc` and `cloudflare/` deploy the HTTP MCP server as a Worker front
  124. door plus a Cloudflare Container. Wrangler builds the `linux/amd64` image from
  125. the root `Dockerfile`; a Docker-compatible engine is required. Set the optional
  126. key and deploy from the repository root:
  127. ```bash
  128. npx wrangler secret put HKIA_MCP_API_KEY
  129. npx wrangler deploy
  130. ```
  131. Cloudflare's remote MCP transport is Streamable HTTP at `/mcp`; `/health` stays
  132. public. A pure WASM Worker is deliberately not included: the server needs
  133. TCP/TLS, a Tokio runtime and bundled SQLite. See
  134. [`cloudflare/README.md`](cloudflare/README.md).
  135. ## Run modes
  136. One binary covers interactive use, scripts, live watching, MCP clients, and
  137. containers. The skill is optional; it teaches an agent which mode to use.
  138. | Mode | Start with | Best for |
  139. | --- | --- | --- |
  140. | CLI table | `hkia departures` | Reading a board in a terminal |
  141. | JSON | `hkia departures --json` | `jq`, scripts, other programs |
  142. | CSV | `hkia departures --csv` | Spreadsheets and data pipelines |
  143. | Watch | `hkia watch --interval 60` | Change-only output and alerts |
  144. | MCP stdio | `hkia mcp` | Desktop and CLI MCP clients that launch a process |
  145. | MCP HTTP | `hkia mcp --transport http` | One long-lived server for several clients |
  146. | MCP SSE | `hkia mcp --transport sse` | Clients that only support legacy SSE |
  147. | Docker | `docker run --rm hkia departures` | No local Rust install |
  148. | Agent skill | `SKILL.md` from the install section | Teaching an agent when to use the tool |
  149. The same board in three styles:
  150. ```bash
  151. hkia departures --limit 5
  152. hkia departures --limit 5 --json | jq '.flights[] | {flight_number, status}'
  153. hkia departures --limit 5 --csv
  154. ```
  155. For MCP, the transport changes how the client connects, not the tools or data:
  156. ```bash
  157. hkia mcp # stdio
  158. hkia mcp --transport http --port 8787 # http://127.0.0.1:8787/mcp
  159. hkia mcp --transport sse --port 8787 # http://127.0.0.1:8787/sse
  160. ```
  161. `hkia update` detects whether the binary came from cargo, the release
  162. installer, a source checkout or Homebrew, and updates with that same
  163. method. `hkia update --check` only reports.
  164. ## CLI
  165. ```bash
  166. hkia departures # today's departures, table
  167. hkia arrivals --limit 20 # first 20 arrivals
  168. hkia flights -D arrival # explicit direction
  169. hkia flight CX251 # both boards and codeshares, plus guidance
  170. hkia flight "CX 251" --date tomorrow
  171. hkia delays # 15+ minute delays, both boards
  172. hkia delays -D departure --min-delay 45
  173. hkia alerts # severity-ranked cancellations and delays
  174. hkia alerts --no-cancelled --min-delay 30
  175. hkia alerts --watchlist --weather --notify
  176. hkia stats # on-time performance and hourly counts
  177. hkia stats -D arrival --date yesterday
  178. hkia stats --from 2026-11-01 --to 2026-11-14 --group-by airline
  179. hkia stats --from 2026-09-01 --group-by weekday --csv
  180. hkia history CX251 # observed status/gate timeline from SQLite
  181. hkia watch --interval 60 # poll and print only changes
  182. hkia watch --watchlist --notify --webhook https://example.test/hook
  183. hkia departures --airport LHR --terminal T1 --airline CPA --status disrupted --json
  184. hkia departures --lang zh_HK --limit 5
  185. hkia departures --cargo --limit 10
  186. hkia access ael --station HOK # live Airport Express next trains
  187. hkia access ael --station AIR --direction from-airport --json
  188. hkia access status # live AEL delay status
  189. hkia access checkin --airline CX # dated in-town check-in reference
  190. hkia access bus --route A11 # dated windows plus live ETAs
  191. hkia access trip --airline CX --time 23:59 --date tomorrow --terminal T1
  192. hkia access bus --route A35 --direction to-airport --json
  193. hkia update --check
  194. ```
  195. Dates accept `YYYY-MM-DD`, `today`, `yesterday`, and `tomorrow`, resolved in
  196. Hong Kong time. `--limit 0` returns every match. Run `hkia <command> --help` for
  197. the complete flag set, including per-command filters such as `--flight`,
  198. `--airport`, `--airline`, `--terminal`, `--status`, `--delayed-over` and
  199. `--sort`.
  200. ### Commands
  201. | Command | Purpose |
  202. | --- | --- |
  203. | `departures` / `arrivals` | One board, table/JSON/CSV |
  204. | `flights` | Board with `-D/--direction` |
  205. | `flight <number>` | One flight across both boards and codeshares, with guidance |
  206. | `delays` | Flights delayed beyond a threshold |
  207. | `alerts` | Cancellations and delays, with optional watchlist, weather, AEL status and runway |
  208. | `watch` | Poll and print status/gate/belt changes, plus AEL status and runway changes |
  209. | `stats` | Single-day stats, or historical range analytics |
  210. | `history <number>` | Locally observed status/gate timeline |
  211. | `access` | `ael`, `status`, `checkin`, `bus`, `trip` airport-access queries |
  212. | `runway` | Runway in use for arrivals and departures, with the airport wind |
  213. | `watchlist` | `show`, `add`, `remove`, `set`, `clear` |
  214. | `mcp` | MCP server over stdio, HTTP, or SSE |
  215. ### Common flags
  216. | Flag | Meaning |
  217. | --- | --- |
  218. | `--json` | Machine-readable JSON; wins over table output |
  219. | `--csv` | CSV for board, flight, delays, alerts, stats, range, and history |
  220. | `--no-header` | Omit the CSV header |
  221. | `--color auto\|always\|never` | Table colour policy (default `auto`) |
  222. | `--sort time\|delay\|flight\|state` | Board sort order (`departures`, `arrivals`, `flights`, `watch`) |
  223. | `--cache-ttl 20` | API cache seconds (HKIA and MTR); `0` disables |
  224. | `--keep-days 90` | Days of flight and runway history kept when the store is pruned |
  225. | `--cargo` | Read the cargo board instead of passenger flights |
  226. | `--lang en\|zh_HK\|zh_CN` | Raw feed language (default `en`); localized status text is parsed |
  227. | `--db PATH` | Override the SQLite history database |
  228. | `--config PATH` | Override the watchlist TOML path |
  229. `--lang` changes the airport's raw status text, not the derived field names or
  230. `guidance` text, which remain English. All three languages are parsed for status
  231. type, delay basis and cancellations.
  232. ### JSON
  233. Add `--json` to any command. A board looks like:
  234. ```json
  235. {
  236. "date": "2026-11-21",
  237. "direction": "departure",
  238. "lastUpdated": "2026-11-21T20:07:01+08:00",
  239. "fetchedAt": "2026-11-21T20:07:03+08:00",
  240. "totalOnBoard": 431,
  241. "count": 1,
  242. "flights": [
  243. {
  244. "flight_number": "CX 251",
  245. "airline": "CPA",
  246. "airline_name": "Cathay Pacific",
  247. "codeshares": [],
  248. "direction": "departure",
  249. "date": "2026-11-21",
  250. "scheduled_time": "23:00",
  251. "scheduled_at": "2026-11-21T23:00:00+08:00",
  252. "status": "Dep 00:00 (22/11/2026)",
  253. "status_type": "departed",
  254. "status_published": true,
  255. "actual_at": "2026-11-22T00:00:00+08:00",
  256. "delay_minutes": 60,
  257. "delay_basis": "actual",
  258. "state": "delayed",
  259. "terminal": "T1",
  260. "gate": "30",
  261. "check_in_aisle": "C",
  262. "guidance": "Depart from Terminal 1, check-in aisle C, gate 30",
  263. "destination": ["LHR"],
  264. "destination_details": [{ "iata": "LHR", "name": "London Heathrow Airport", "city": "London", "country": "United Kingdom" }]
  265. }
  266. ]
  267. }
  268. ```
  269. Every flight includes `origin`, `destination`, `origin_details`,
  270. `destination_details`, `terminal`, `gate`, `stand`, `check_in_aisle`,
  271. `baggage_belt`, `arrival_hall`, `status_published`, `delay_basis`, `guidance`,
  272. and `fetched_at`. Unknown operational fields are `null`, never guessed.
  273. ### Watchlist and notifications
  274. The watchlist is TOML at `$HKIA_CONFIG`, `$XDG_CONFIG_HOME/hkia/config.toml`, or
  275. `~/.config/hkia/config.toml`.
  276. ```bash
  277. hkia watchlist add --flight CX251
  278. hkia watchlist add --airport LHR
  279. hkia watchlist add --airline CPA
  280. hkia watchlist set --min-delay 10 --direction departure
  281. hkia watchlist set --desktop true --webhook https://example.test/hook
  282. hkia watchlist show
  283. ```
  284. ```toml
  285. [watchlist]
  286. flights = ["CX251"]
  287. airports = ["LHR"]
  288. airlines = ["CPA"]
  289. direction = "departure"
  290. min_delay = 10
  291. include_cancelled = true
  292. [notify]
  293. desktop = false
  294. webhook = "https://example.test/hook"
  295. ```
  296. Empty selectors match every flight. Flights match operating numbers and
  297. codeshares; airports match either endpoint of the route. Webhooks receive JSON
  298. with `source`, `kind`, `timestamp`, `changes` or `alerts`, and the watchlist
  299. that produced them. Notifications are deduplicated by alert fingerprint in
  300. SQLite, so restarting `watch` does not resend the same alert; pass
  301. `--force-notify` on `alerts` to bypass dedupe.
  302. ### History and persistence
  303. SQLite lives at `$HKIA_DATA_DIR/hkia.db`, `$XDG_DATA_HOME/hkia/hkia.db`, or
  304. `~/.local/share/hkia/hkia.db`. Watch ticks, `history`,
  305. notification-enabled `alerts`, and MCP history/watch calls record observations;
  306. a plain board read does not. Observations append an event only when status,
  307. delay, gate, terminal, belt, or stand changes. Events older than 90 days are
  308. pruned opportunistically. `hkia history CX251` is therefore limited to what this
  309. machine has actually observed — it is not an airport-provided audit log.
  310. ## Historical analytics
  311. `stats --from` uses the airport's historical endpoint, valid from D-91 through
  312. D+14. Weekends and future days may be unavailable; failed days are reported in
  313. `failures` instead of being silently dropped.
  314. ```bash
  315. hkia stats --from 2026-11-01 --to 2026-11-14 --group-by route --json
  316. ```
  317. The range report includes a flattened summary (`flights`, `cancelled`,
  318. `delayed`, `on_time`, `early`, `scheduled`, `tracked`,
  319. `average_delay_minutes`, `max_delay_minutes`, `on_time_percent`) plus `by_day`,
  320. `by_airline`, `by_route`, `by_weekday`, and `by_hour`. `--group-by` is only
  321. valid with `--from` and selects the table/CSV focus.
  322. ## Airport access
  323. `hkia access` covers getting to and from the airport without changing the
  324. flight commands. It is a separate surface with explicit data provenance.
  325. ```bash
  326. hkia access ael --station HOK
  327. hkia access ael --station AIR --direction from-airport --json
  328. hkia access ael --station KOW --direction both --csv
  329. hkia access status --json
  330. hkia access checkin --airline CX
  331. hkia access checkin --airline CPA --json
  332. hkia access bus --route A11
  333. hkia access bus --route A35 --json
  334. hkia access bus --route A31 --direction to-airport --csv
  335. hkia access bus --route A11 --no-live
  336. hkia access bus --csv
  337. hkia access trip --airline CX --time 23:59 --date tomorrow
  338. hkia access trip --station KOW --airline CX --time 07:40 --terminal T1 --buffer 15 --json
  339. hkia runway # arrival/departure runway in use
  340. hkia runway --json
  341. hkia runway --csv
  342. hkia runway --history # locally observed switches (from watch)
  343. ```
  344. `ael` is live: it reads the MTR Next Train API through data.gov.hk and returns
  345. upcoming trains, destination, platform and minutes to departure. Stations are
  346. `HOK`, `KOW`, `TSY`, `AIR` and `AWE`. The direction defaults to `to-airport`
  347. from Hong Kong, Kowloon and Tsing Yi, and `from-airport` at Airport and
  348. AsiaWorld-Expo. Each response includes the AEL journey times, first/last train
  349. windows and the official MTR fares (Octopus, single and 30-day round trip,
  350. adult and child), with `checked_on` and source URLs.
  351. `status` checks the same live API for the `isdelay` flag at Hong Kong and
  352. Airport and reports whether MTR has flagged an Airport Express delay. It is a
  353. coarse line-status signal, not a cause or an estimate of how long a delay will
  354. last. `alerts` and `watch` include this status by default (`--no-ael` skips it),
  355. and watch mode prints and notifies when the flag changes.
  356. `checkin` is a dated snapshot of MTR's published in-town check-in list, not live
  357. availability. It matches IATA codes, ICAO codes or airline names and returns
  358. Hong Kong and Kowloon station hours, the check-in window, eligibility and
  359. baggage limits.
  360. `bus` is a dated snapshot of the 30 HKIA A-routes with both directions:
  361. destination, operator, adult fares (weekday plus published holiday notes) and
  362. the city-to-airport and from-airport departure windows. With `--route`, it also
  363. queries the Citybus, Long Win/KMB or New Lantao live ETA API for the published
  364. terminus stop; `--direction` picks the direction (default `both`) and
  365. `--no-live` keeps the output static.
  366. `trip` plans the latest Airport Express departure for a flight. It applies MTR's
  367. published 90-minute check-in cutoff, adds an explicit `--buffer` (default 0),
  368. uses the station's published journey time, rounds down to the 10-minute
  369. headway, and reports the airport arrival deadline and latest train with the
  370. published first/last train window. It does **not** invent security, immigration
  371. or walking times, and it shows in-town check-in hours for the station without
  372. shortening the airport buffer. The flight time must be in the future Hong Kong
  373. time; use `--date tomorrow` for late-night flights already passed today.
  374. The reference data was checked on **2026-11-22**. Hours, fares and participating
  375. airlines can change; confirm with MTR, the airline or the bus operator before
  376. travel. Sources: the MTR Next Train API, MTR Airport Express timetable, fares
  377. CSV and frequency pages, MTR's in-town check-in page, HKIA's public-bus page,
  378. and the Citybus/LWB/KMB/NLB live ETA APIs; see [NOTICE](NOTICE) for the exact
  379. URLs. Use `--json` or `--csv` for scripts; `--no-header` omits the CSV header.
  380. `scripts/refresh_access_data.py --write` regenerates the embedded files and
  381. `--check` compares them with the official sources without updating anything. A
  382. scheduled GitHub Actions workflow runs the check weekly and opens an issue when
  383. the data drifts.
  384. ## Runway in use
  385. `hkia runway` answers which direction aircraft are landing and departing. It
  386. reads the Civil Aviation Department's public ATIS page on `hkatc.gov.hk`, which
  387. is the official runway-in-use broadcast, and reports the arrival and departure
  388. runway separately along with the ATIS letter and issue time.
  389. ```bash
  390. hkia runway
  391. hkia runway --json
  392. hkia runway --csv
  393. hkia runway --history
  394. ```
  395. The output also gives the airport wind from the ATIS and the computed
  396. head/tailwind and crosswind components for the arrival runway, plus the approach
  397. side implied by the runway designator: runway 07 means aircraft land heading
  398. eastbound, approaching from the west, while runway 25 means the opposite. This
  399. is what residents around the flight paths usually want when asking whether
  400. aircraft are coming in over their side of the airport.
  401. Runway 07 is preferred at HKG whenever the tailwind component is 5 knots or less
  402. (AIP VHHH AD 2.22), but ATC can use runway 25 when required, and arrivals and
  403. departures can differ. The tool therefore reports the ATIS statement rather than
  404. predicting from wind. Wind components are derived from the reported wind, not
  405. threshold measurements, and the ATIS page can be briefly unavailable while a
  406. bulletin updates.
  407. When the ATIS page cannot be read, `hkia runway` falls back to the Hong Kong
  408. Observatory's 10-minute wind at Chek Lap Kok and says plainly that the runway is
  409. not confirmed. In that mode the JSON has `atis_available: false`, a `wind`
  410. object with the compass direction and knots, and `wind_favours`, which applies
  411. the AIP rule (runway 07 when the tailwind is 5 knots or less). The wind favour
  412. is an indication, not the runway in use, and the command never invents one. If
  413. both the ATIS and the HKO feed fail, it returns an error instead.
  414. In table mode, `hkia runway` also prints the most recent switch this machine
  415. recorded while `watch` was running, so the current runway can be read together
  416. with when it last changed. JSON carries the same as `last_observed`, which is
  417. `null` until something has been observed; that line is local observation, not
  418. part of the official ATIS.
  419. `hkia watch` polls the runway with the rest of the board and prints, notifies
  420. and webhooks when the arrival or departure runway changes (`--no-runway` skips
  421. those checks, `--no-ael` skips the AEL status). `hkia alerts` includes the
  422. current runway and AEL status too, with the same `--no-runway` / `--no-ael`
  423. opt-outs. `watch` opens with a one-line summary of the recorded runway history,
  424. and `alerts` prints the last observed switch beneath the live runway (JSON
  425. `last_observed`).
  426. Every observed switch is also written to the local SQLite store, so
  427. `hkia runway --history` shows what this machine actually saw, oldest first:
  428. ```bash
  429. hkia runway --history
  430. hkia runway --history --limit 50 --json
  431. hkia runway --history --csv
  432. hkia runway --history --daily
  433. ```
  434. `--daily` groups the rows by local date and shows how many switches were seen
  435. that day with the first and last arrival/departure runway (`--limit` then caps
  436. the number of days). History is pruned to the last `--keep-days` days (default
  437. 90) whenever a command opens the store; raise it to keep more, or set `0` to
  438. keep none.
  439. ```
  440. Observed runway switches by day | 1 day(s) | local store
  441. DATE SWITCHES FIRST LAST
  442. 2026-11-22 1 07C/07R 07C/07R
  443. ```
  444. There is no public historical runway feed; the history only covers periods when
  445. `hkia watch` was running, and a switch is recorded once per change, not per
  446. poll. The same rows are available to agents as the `hkia://runway/history`
  447. resource (last 20 switches).
  448. ## MCP
  449. ### stdio
  450. ```json
  451. {
  452. "mcpServers": {
  453. "hkia": {
  454. "command": "hkia",
  455. "args": ["mcp"]
  456. }
  457. }
  458. }
  459. ```
  460. Register it with any MCP client:
  461. ```bash
  462. npx add-mcp "$(command -v hkia) mcp" --name hkia -a claude-code -a codex -a cursor -y
  463. claude mcp add hkia -- hkia mcp
  464. codex mcp add hkia -- hkia mcp
  465. ```
  466. `add-mcp` detects the client configuration files in the current project; add
  467. `-g` for a global install. Substitute an absolute path if your client does not
  468. inherit the shell `PATH`.
  469. If `hkia` is not on the MCP client's `PATH`, replace `"command": "hkia"` with
  470. an absolute path. `scripts/ensure-binary.sh` prints the path to use. Restart the
  471. client after changing its MCP configuration.
  472. #### Client setup
  473. Claude Code and Codex can write the stdio entry themselves:
  474. ```bash
  475. claude mcp add hkia -- /absolute/path/to/hkia mcp
  476. codex mcp add hkia -- /absolute/path/to/hkia mcp
  477. ```
  478. Cursor reads `.cursor/mcp.json` (project) or `~/.cursor/mcp.json` (user).
  479. Claude Desktop uses `claude_desktop_config.json` in its application-support
  480. directory. Paste the `mcpServers` block above into either file and restart the
  481. client.
  482. ### Streamable HTTP
  483. ```bash
  484. hkia mcp --transport http --port 8787
  485. # endpoint: http://127.0.0.1:8787/mcp
  486. # health: http://127.0.0.1:8787/health
  487. ```
  488. ```json
  489. {
  490. "mcpServers": {
  491. "hkia": {
  492. "type": "http",
  493. "url": "http://127.0.0.1:8787/mcp"
  494. }
  495. }
  496. }
  497. ```
  498. ### SSE
  499. ```bash
  500. hkia mcp --transport sse --port 8787
  501. # stream: http://127.0.0.1:8787/sse
  502. # messages: POST to the endpoint URL announced by the server
  503. ```
  504. ```json
  505. {
  506. "mcpServers": {
  507. "hkia": {
  508. "type": "sse",
  509. "url": "http://127.0.0.1:8787/sse"
  510. }
  511. }
  512. }
  513. ```
  514. Use `--host 0.0.0.0` to listen beyond loopback. Both network transports expose
  515. `GET /health` and permissive CORS for local tooling; `--path` changes the
  516. streamable HTTP endpoint. `/health` stays public, while `/mcp`, `/sse`, and
  517. `/messages` are protected when auth is enabled.
  518. The server does not terminate TLS, and the bearer token is one shared static
  519. secret. Keep the default loopback bind, or put it behind a TLS reverse proxy
  520. before exposing it to another machine.
  521. ### Auth and rate limiting
  522. ```bash
  523. hkia mcp --transport http --api-key "$SECRET"
  524. # --auth-token is an alias; either env var works:
  525. # HKIA_MCP_API_KEY="$SECRET" hkia mcp --transport http
  526. # HKIA_AUTH_TOKEN="$SECRET" hkia mcp --transport http
  527. ```
  528. Protected routes require `Authorization: Bearer $SECRET` or
  529. `X-API-Key: $SECRET`. Requests are limited
  530. to 240 per minute by default across the process (`--rate-limit 0` disables,
  531. `--rate-limit N` changes the cap); over-limit requests receive HTTP 429 with
  532. `Retry-After: 60`. This is a single-process guard, not a multi-tenant quota.
  533. ```json
  534. {
  535. "mcpServers": {
  536. "hkia": {
  537. "type": "http",
  538. "url": "http://127.0.0.1:8787/mcp",
  539. "headers": { "Authorization": "Bearer <token>" }
  540. }
  541. }
  542. }
  543. ```
  544. Keep the token in your client's secret store or an environment variable where
  545. the client supports interpolation; do not commit it to a shared config file.
  546. `/health` remains public so container and Worker readiness probes do not need
  547. the key.
  548. ### Tools
  549. | Tool | Purpose |
  550. | --- | --- |
  551. | `list_flights` | Board listing with airport, airline, terminal, state, delay, sort and limit filters |
  552. | `search_flight` | One flight number across departures, arrivals, and codeshares |
  553. | `get_delays` | Flights delayed beyond a threshold |
  554. | `get_alerts` | Cancellations and delays as severity-ranked alerts, with weather, AEL status and runway in use |
  555. | `get_stats` | Single-day on-time performance and hourly breakdown |
  556. | `get_watchlist_alerts` | Disruptions filtered to the local watchlist, optional weather |
  557. | `get_flight_history` | Locally observed status/gate/belt timeline for a flight |
  558. | `get_historical_stats` | Multi-day range analytics with airline/route/hour/weekday groups |
  559. | `wait_for_changes` | Long-poll for new recorded changes; use the returned timestamp as the next `after` |
  560. | `get_weather` | Current Hong Kong Observatory warnings |
  561. | `get_runway_status` | Runway in use for arrivals and departures, ATIS wind, wind components and last observed switch |
  562. | `get_runway_history` | Locally observed runway switches, oldest first, with an optional `limit` (default 20, 0 for all) and `daily` grouping |
  563. | `get_airport_access` | Live AEL trains and status, trip planning, dated in-town check-in hours, or A-route bus data with live ETAs |
  564. Watchlist and history tools use the local SQLite store and config, so the same
  565. `--db`, `--config` and `--keep-days` global flags apply. Most flight tools accept `date`,
  566. `direction`, `cargo`, and `lang`; `get_airport_access` takes `mode`, `station`,
  567. `direction`, `airline`, `route`, `time`, `date`, `terminal`, `buffer_minutes` and
  568. `no_live`. Its modes are `airport-express`, `airport-express-status`,
  569. `in-town-checkin`, `airport-bus` and `trip`. `get_alerts` takes `include_ael` and
  570. `include_runway` (both default true). See each tool's schema for exact names.
  571. ### Resources
  572. | URI | Content |
  573. | --- | --- |
  574. | `hkia://board/today/departures` | Today's departure board JSON |
  575. | `hkia://board/today/arrivals` | Today's arrival board JSON |
  576. | `hkia://alerts/today` | Today's cancellations and 15+ minute delays |
  577. | `hkia://access/ael/status` | Live Airport Express delay flag |
  578. | `hkia://access/ael/HOK` | Live AEL departures, fares and journey times (use any station code) |
  579. | `hkia://access/checkin/CX` | Dated in-town check-in hours (use any airline code) |
  580. | `hkia://access/bus/A11` | Dated A-route windows and fares plus live ETAs (use any route) |
  581. | `hkia://runway/status` | Official ATIS runway in use and airport wind |
  582. | `hkia://runway/history` | Locally observed runway switches, last 20 |
  583. Resources support read and the legacy subscribe/unsubscribe flow. Subscriptions
  584. poll every 30 seconds and emit `notifications/resources/updated` when the
  585. serialized resource changes. For reliable push-style integrations, prefer
  586. `wait_for_changes`.
  587. ## Troubleshooting
  588. - **Installer cannot find a release:** the script needs a `v*` release with a
  589. matching `<target>.tar.gz`. From a clone, build with
  590. `cargo build --release --locked`; setting `HKIA_VERSION` only selects an
  591. existing release tag.
  592. - **Unsupported platform:** prebuilt binaries cover macOS x86_64/arm64 and Linux
  593. x86_64/aarch64. Use `cargo install --path . --locked` elsewhere.
  594. - **MCP returns 401:** the client must send `Authorization: Bearer <key>` (or
  595. `X-API-Key`) when `--api-key`, `HKIA_MCP_API_KEY` or an alias is set. `/health`
  596. stays public.
  597. - **MCP returns 429:** the process-wide rate limit was reached; raise
  598. `--rate-limit` or wait for `Retry-After`.
  599. - **Webhook delivery fails:** the request times out after 15 seconds, non-2xx
  600. responses are errors, and there is no retry queue. Delivery errors are printed
  601. as warnings; the watch loop continues.
  602. ## Configuration
  603. | Variable | Meaning |
  604. | --- | --- |
  605. | `HKIA_API_BASE` | Override the feed base URL (default `https://www.hongkongairport.com/flightinfo-rest/rest`) |
  606. | `HKIA_WEATHER_URL` | Override the HKO warning endpoint |
  607. | `HKIA_MCP_API_KEY` | API key for HTTP/SSE MCP (`HKIA_API_KEY` and `HKIA_AUTH_TOKEN` are aliases) |
  608. | `HKIA_DATA_DIR` | Directory containing `hkia.db` |
  609. | `HKIA_CONFIG` | Watchlist TOML path |
  610. ## Data limits and ATC
  611. - Source: the airport's public REST feed. The live board is
  612. `flights?date=YYYY-MM-DD&lang=en&cargo=false&arrival=false`; history uses
  613. `flights/past` for the same date window.
  614. - The feed publishes one board per calendar day and may include the previous
  615. day's tail; only the requested date is used.
  616. - `delay_minutes` is derived from free-text status (`Dep HH:MM`,
  617. `Est at HH:MM`, `At gate HH:MM`, `Cancelled`) against the scheduled time.
  618. A flight is `delayed` at 15 minutes or more and `early` at 15 minutes or less.
  619. This is not an airline cause code and does not distinguish weather, crew, or
  620. slot delays.
  621. - Terminal and gate assignments can change or be blank until close to
  622. departure. `guidance` reflects the currently published fields only.
  623. - Future dates may return no board until the airport publishes them. Very old
  624. dates outside D-91 and dates beyond D+14 return a range error.
  625. - Airport Express train data, the delay flag and bus ETAs are live from MTR,
  626. Citybus, LWB/KMB and NLB APIs. In-town check-in, AEL fare and A-route bus
  627. facts are dated reference snapshots checked `2026-11-22`, not live
  628. availability. Bus windows are published terminus departure windows, not
  629. frequency guarantees, and live ETAs cover the terminus stop only. The trip
  630. planner uses the 90-minute cutoff, an explicit buffer and the published
  631. journey time; it does not model security, immigration or walking time.
  632. - Runway in use is live from the CAD ATIS. It is the official broadcast, but it
  633. changes with wind and operations, arrivals and departures can use different
  634. runways, and the ATIS can be briefly unavailable while updating. The approach
  635. side is derived from the runway designator, not from observed flight tracks.
  636. - Responses are cached for 20 seconds (`--cache-ttl 0` disables it; `watch` is
  637. uncached). Delay/alert data is only as fresh as the airport feed itself; the
  638. project makes no uptime or freshness guarantee.
  639. - Localized status parsing covers English, Traditional Chinese (`zh_HK`) and
  640. Simplified Chinese (`zh_CN`) terms such as `Dep`/`啟航`/`启航`,
  641. `At gate`/`到閘口`/`到闸口`, `Est`/`預計`/`预计` and
  642. `Cancelled`/`取消`. The raw status string still depends on the requested
  643. language.
  644. - **ATC/tower text:** HKIA tower communications are voice radio, and there is
  645. no public per-flight ATC text or transcription feed. This tool does not
  646. scrape or transcribe tower audio. It can surface published delays, weather
  647. warnings, cancellations, and gate changes, but it cannot tell you what a
  648. controller said to a specific flight. Treat any such transcript as
  649. unverified unless it comes from an official source.
  650. ## Development
  651. ```bash
  652. just check # fmt-check, clippy, tests
  653. just skill-check # validate SKILL.md and shell scripts the way CI does
  654. just build-release
  655. ```
  656. `rust-toolchain.toml` pins the stable toolchain with `rustfmt` and
  657. `clippy`, so `rustup` sets contributors up automatically. `just doc`
  658. builds the API documentation. See `CONTRIBUTING.md` for the full check
  659. list and the signed-commit requirement.
  660. Without `just`:
  661. ```bash
  662. cargo fmt --all -- --check
  663. cargo clippy --all-targets --locked -- -D warnings
  664. cargo test --all --locked
  665. ```
  666. Tests cover status parsing, midnight rollover, cancellations, codeshares,
  667. filters, stats/alerts, the captured board fixture, watchlist matching and
  668. dedupe, SQLite change detection and notification dedupe, weather parsing, AEL
  669. parsing and trip planning, bus data, ATIS parsing and wind components, and TOML
  670. round-tripping. Integration tests exercise the access CLI JSON/CSV shapes,
  671. station/direction errors, MCP tool mode routing and MCP access/runway
  672. resources. CI runs formatting, clippy, tests, the access data drift check, a
  673. release build and a SKILL.md/script validation job. Tagged releases verify the tag against
  674. `Cargo.toml` and `CHANGELOG.md`, build macOS and static Linux binaries, smoke
  675. test the native artifact, and publish `SHA256SUMS`.
  676. Layout: `src/api.rs` (feed client, normalisation, delays, alerts, stats),
  677. `src/analytics.rs` (historical ranges), `src/store.rs` (SQLite),
  678. `src/watchlist.rs` (config and matching), `src/notify.rs` (desktop/webhook),
  679. `src/weather.rs` (HKO), `src/access.rs` (AEL and bus live clients, trip planner
  680. and dated reference data), `src/runway.rs` (CAD ATIS runway and wind),
  681. `src/render.rs` (tables/CSV), `src/mcp.rs`
  682. (transports, tools, resources), `src/main.rs` (CLI), `scripts/install.sh`
  683. (release installer), `scripts/ensure-binary.sh` (agent resolver),
  684. `scripts/refresh_access_data.py` (access data generator/checker), and `SKILL.md`
  685. (agent skill).
  686. ## Data licences
  687. Airport and airline reference data is embedded from OurAirports (public domain)
  688. and OpenFlights (ODbL). Airport Express, in-town check-in and A-route bus
  689. reference facts come from MTR and HKIA pages listed in [NOTICE](NOTICE), and the
  690. runway/ATIS data comes from the Civil Aviation Department. Flight data, the live
  691. train feed and the ATIS page remain subject to their providers' terms; this
  692. project only reads the public endpoints.
  693. ## Licence
  694. MIT. See [LICENSE](LICENSE).

Ratings and comments

Sign in to rate this skill.

Sign in

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