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
Markdown
[](/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
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
- ---
- name: hongkong-airport-skill
- 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.
- license: MIT
- ---
- # HKIA flights
- `hkia` is a Rust CLI and MCP server for the public Hong Kong International Airport
- flight-information feed. It needs no data API key and no account; the HTTP MCP
- transport can optionally require a static API key. It is an
- independent, unofficial project and is not affiliated with the airport.
- Use it when the user asks about:
- - a flight arriving at or departing from Hong Kong (CX, UO, HX, NH, BA, QR, ...)
- - delays, cancellations, estimated or actual times
- - which terminal, check-in aisle, gate, stand, baggage belt, or arrival hall to use
- - disruption alerts, a specific flight, an airport, or an airline
- - on-time performance for a day or a historical date range
- - watching a board for changes, or a persistent timeline of what was observed
- - weather warnings affecting airport operations
- - Airport Express trains, in-town check-in, or airport A-route buses
- ## Before first use
- Run `scripts/ensure-binary.sh` from the skill directory:
- ```console
- $ bash scripts/ensure-binary.sh
- /Users/you/.local/bin/hkia
- ```
- It prints the absolute path of a working `hkia` binary and exits non-zero only
- if it could not download or build one. Use the printed path for every later
- command, for example `BIN="$(bash scripts/ensure-binary.sh)"`, and do not assume
- `hkia` is on `PATH`.
- It checks, in order: `$HKIA_BIN`, `hkia` on `PATH`, `scripts/install.sh`, then
- `cargo build --release --locked` in the repo root.
- ## Install
- Skill only (teaches the agent to use the CLI):
- ```bash
- npx skills add hongkong-ai-labs/hongkong-airport-skill
- ```
- Rust-only alternative (community port):
- ```bash
- cargo install skills-cli --locked
- skills add hongkong-ai-labs/hongkong-airport-skill
- ```
- Manual install: copy this directory, or just `SKILL.md` plus `scripts/`, into
- the agent's skills directory (for example `.agents/skills/hongkong-airport-skill`
- or `~/.claude/skills/hongkong-airport-skill`). Then run
- `scripts/ensure-binary.sh` from that directory.
- The binary (choose one):
- ```bash
- sh scripts/install.sh # from the skill directory; checksum-verified
- cargo install --path . # from a clone of this repo
- cargo install --git https://github.com/hongkong-ai-labs/hongkong-airport-skill --bin hkia --locked
- ```
- ## Run modes
- Use the CLI for one-shot queries and MCP when a client should call tools
- directly. The transport changes how a client connects, not the data or tools.
- | Mode | Start with | Use for |
- | --- | --- | --- |
- | CLI table | `hkia departures` | Human-readable board |
- | JSON | `hkia departures --json` | Parsing and summarising |
- | CSV | `hkia departures --csv` | Spreadsheet or pipeline output |
- | Watch | `hkia watch --interval 60` | Change-only output |
- | MCP stdio | `hkia mcp` | Client launches the process |
- | MCP HTTP | `hkia mcp --transport http` | Shared long-lived server |
- | MCP SSE | `hkia mcp --transport sse` | Legacy SSE clients |
- | Docker | `docker run --rm hkia departures` | No local binary |
- ## CLI
- Prefer `--json` when you need to parse or summarise output. Tables are for
- humans. Times are Hong Kong time (UTC+8); JSON timestamps are RFC 3339 with
- `+08:00`.
- ```bash
- # Today's boards
- hkia departures --json
- hkia arrivals --json
- # A date (YYYY-MM-DD, today, yesterday, tomorrow)
- hkia flights --direction departure --date 2026-11-21 --json
- # One flight, both boards and all codeshares
- hkia flight CX251 --json
- hkia flight "CX 251" --date tomorrow --json
- # Delays and disruption alerts
- hkia delays --min-delay 15 --json
- hkia alerts --min-delay 30 --no-cancelled --json
- hkia alerts --watchlist --weather --json
- # On-time stats: single day, or a historical range
- hkia stats --json
- hkia stats --from 2026-11-01 --to 2026-11-14 --group-by airline --json
- hkia stats --from 2026-09-01 --group-by weekday --json
- # Locally observed timeline
- hkia history CX251 --json
- # Live changes: baseline, then only differences
- hkia watch --interval 60
- hkia watch --direction arrival --min-delay 20 --json # NDJSON ticks
- # Filters and formats
- hkia departures --airport LHR --terminal T1 --airline CPA --limit 20 --json
- hkia departures --status disrupted --csv
- hkia departures --lang zh_HK --limit 10 --json
- hkia departures --cargo --limit 10 --json
- # Airport access
- hkia access ael --station HOK --json
- hkia access ael --station AIR --direction from-airport --json
- hkia access status --json
- hkia access checkin --airline CX --json
- hkia access bus --route A11 --json
- hkia access bus --route A35 --direction to-airport --json
- hkia access trip --airline CX --time 23:59 --date tomorrow --json
- hkia update --check
- ```
- Run `hkia <command> --help` for per-command filters such as `--flight`,
- `--airport`, `--airline`, `--terminal`, `--status`, `--delayed-over`, and `--sort`.
- The range endpoint covers D-91 through D+14. Historical range reports include
- `by_day`, `by_airline`, `by_route`, `by_weekday`, and `by_hour`; failed days
- appear in `failures`.
- `--lang` accepts `en`, `zh_HK`, or `zh_CN` (default `en`). It changes the raw
- status text, not JSON field names or `guidance`, which stay English. All three
- languages are parsed for status type, delay basis, and cancellations.
- ## Terminal and gate guidance
- Each flight JSON object has the airport's operational fields plus a derived
- `guidance` string:
- | Field | Meaning |
- | --- | --- |
- | `terminal` | Terminal, usually `T1` or `T2` |
- | `gate` | Departure gate, or arrival gate when published |
- | `stand` | Arrival stand when the airport publishes a remote stand |
- | `check_in_aisle` | Departure check-in aisle letter |
- | `baggage_belt` | Arrival reclaim belt |
- | `arrival_hall` | Arrival hall |
- | `guidance` | Human-readable instruction built only from the above |
- Examples:
- - `Depart from Terminal 1, check-in aisle C, gate 30`
- - `Arrive at Terminal 1, gate 30; baggage belt 12, arrival hall A`
- - `Depart from Terminal 1, check-in aisle C` when the gate is not yet assigned
- When answering “which terminal?”, lead with `guidance` if present, then the raw
- `terminal`, `gate`, `check_in_aisle`, `baggage_belt`, and `arrival_hall` fields.
- If a field is `null`, say it has not been published yet; never fill it from a
- different flight or a previous day. Gates and terminals can change, so include
- `fetched_at` or `lastUpdated` when the user needs current information.
- The feed does **not** provide airline counter rows, security queue times,
- walking times between gates, or a per-flight ATC transcript.
- ## Other fields
- | Field | Meaning |
- | --- | --- |
- | `flight_number`, `codeshares` | Operating number first; other marketing numbers after |
- | `airline`, `airline_name` | ICAO code and resolved airline name |
- | `direction`, `date` | `departure`/`arrival`, board date |
- | `scheduled_time`, `scheduled_at` | Timetable time; RFC 3339 timestamp |
- | `status`, `status_type` | Raw airport text; `departed`, `arrived`, `estimated`, `cancelled`, `scheduled`, `other` |
- | `status_published` | Whether a non-scheduled status is present |
- | `actual_at`, `estimated_at` | Parsed event time when published |
- | `delay_minutes`, `delay_basis` | Event time minus schedule; `actual`, `estimated`, or null |
- | `state` | `cancelled`, `delayed` (>=15 min), `on_time`, `early`, `scheduled` |
- | `origin`, `destination` | IATA code lists; multi-leg flights list every stop |
- | `origin_details`, `destination_details` | Resolved airport name, city, country |
- | `fetched_at` | When this observation was fetched |
- Delay minutes are computed from the airport's free-text status against the
- scheduled time. English, Traditional Chinese, and Simplified Chinese status
- terms are recognised. They are not airline cause codes and do not distinguish
- weather, crew, slot, or maintenance reasons. `guidance` is always English.
- ## Airport access
- Use `hkia access` for getting to or from HKG. It is separate from the flight
- commands and keeps the same `--json` / `--csv` conventions.
- ```bash
- hkia access ael --station HOK
- hkia access ael --station KOW --direction both --json
- hkia access status
- hkia access checkin --airline CX
- hkia access checkin --airline CPA --json
- hkia access bus --route A11
- hkia access bus --route A11 --direction from-airport --no-live
- hkia access bus --csv
- hkia access trip --station KOW --airline CX --time 07:40 --terminal T1 --buffer 15
- # Runway in use
- hkia runway
- hkia runway --json
- hkia runway --history
- ```
- - `ael` is **live** from the MTR Next Train API. Stations: `HOK`, `KOW`, `TSY`,
- `AIR`, `AWE`. Direction is `to-airport`, `from-airport`, or `both`; it
- defaults from the station. Each response has `trains`, plus `service` with
- journey times, first/last windows, official fares, `checked_on`, and sources.
- - `status` is **live** from the same API's `isdelay` flag at HOK and AIR. Use it
- for "is the Airport Express disrupted" questions; it reports only whether MTR
- flagged a delay, not a cause or duration. `alerts` and `watch` include it by
- default (`--no-ael` disables), and watch notifies when the flag changes.
- - `checkin` is a **dated snapshot** of MTR's published in-town check-in list.
- It matches IATA (`CX`), ICAO (`CPA`) or name. Returns station hours,
- eligibility, baggage limits, `source`, and `checked_on`. It is not live
- availability and does not confirm a specific flight is accepted.
- - `bus` is a **dated snapshot** of the 30 HKIA A-routes in both directions,
- with destination, operator, adult fares and city-to-airport and from-airport
- windows. With `--route` it adds **live** Citybus/LWB/KMB/NLB ETAs for the
- published terminus stop; `--direction` selects the direction and `--no-live`
- keeps it static. ETAs are for the terminus, not the airport kerb.
- - `trip` plans the latest AEL departure for a flight: 90-minute check-in cutoff,
- explicit `--buffer` (default 0), published journey time, rounded down to the
- 10-minute headway, plus the airport deadline and in-town check-in hours. It
- never assumes security, immigration or walking time. The time must be in the
- future Hong Kong time; `--date tomorrow` handles late-night flights today.
- The reference snapshot was checked on `2026-11-22`. Always pass through
- `checked_on` and the source URL, and tell the user to confirm with MTR, the
- airline, or the bus operator before travel. `scripts/refresh_access_data.py
- --check` verifies the snapshots against the official sources.
- ## Runway in use
- `hkia runway` reports the runway in use for arrivals and departures, the ATIS
- letter and issue time, and the airport wind with computed head/tailwind and
- crosswind for the arrival runway. The source is the official CAD ATIS page on
- `hkatc.gov.hk`, not a guess from wind.
- - Runway `07` means aircraft land heading eastbound, approaching from the west;
- runway `25` means westbound approaches from the east. Use this for questions
- about which side aircraft are coming in over, or aircraft noise.
- - Arrivals and departures can use different runways; report both.
- - Runway 07 is preferred when the tailwind is 5 knots or less (AIP VHHH
- AD 2.22), but ATC can use 25 when required. Do not predict the runway from
- wind when the ATIS is available.
- - If the ATIS page is unavailable, the command falls back to the HKO 10-minute
- wind at Chek Lap Kok: `atis_available` is false, `wind` holds the observation
- and `wind_favours` applies the AIP rule. Say the runway is not confirmed and
- do not present the favoured runway as the runway in use. If both feeds fail,
- report the error.
- - The live output also shows the last switch this machine observed
- (`last_observed` in JSON, null if none), so you can say how long the current
- runway has held. It is local observation, not part of the ATIS.
- - `hkia watch` prints and notifies when the runway changes; `--no-runway`
- disables that check. Each observed switch is stored in SQLite, and
- `hkia runway --history [--limit N] [--daily]` lists them oldest first, or
- grouped per day with the switch count and first/last runway. History only
- covers periods when `watch` was running; it is not an official record. The
- same rows are available as `get_runway_history` (`limit` keeps the most
- recent N, default 20; `daily` groups them by date) and as the
- `hkia://runway/history` resource (last 20).
- ## Watchlist and notifications
- The watchlist is TOML at `$HKIA_CONFIG`, `$XDG_CONFIG_HOME/hkia/config.toml`, or
- `~/.config/hkia/config.toml`:
- ```toml
- [watchlist]
- flights = ["CX251"]
- airports = ["LHR"]
- airlines = ["CPA"]
- direction = "departure"
- min_delay = 10
- include_cancelled = true
- [notify]
- desktop = false
- webhook = "https://example.test/hook"
- ```
- Manage it with `hkia watchlist add --flight CX251`,
- `hkia watchlist add --airport LHR`, `hkia watchlist set --min-delay 10`,
- `hkia watchlist show`, and `hkia watchlist remove --flight CX251`.
- Use `--watchlist` with `alerts` or `watch` to restrict output to the watchlist.
- `--notify` sends desktop notifications; `--webhook URL` POSTs JSON. `watch` also
- reports AEL delay changes (`--no-ael` disables) and runway-in-use changes
- (`--no-runway` disables), each with its own notification kind. Alert
- notifications are deduplicated by fingerprint in SQLite, so a restart does not
- resend the same alert. Empty selectors match everything.
- ## Persistence and history
- The local SQLite store is at `$HKIA_DATA_DIR/hkia.db`,
- `$XDG_DATA_HOME/hkia/hkia.db`, or `~/.local/share/hkia/hkia.db`. Watch ticks,
- `history`, notification-enabled alert checks, and MCP history/watch calls record
- observations. Events are appended only when status, delay, gate, terminal, belt,
- or stand changes. `history` shows what this machine observed, not an official airport audit trail.
- The same applies to `hkia runway --history`, which stores one row per observed
- runway switch. Data older than `--keep-days` (default 90) is pruned
- opportunistically; `watch` starts with a one-line summary of the stored
- history, and `alerts` prints the last observed switch with the live runway.
- ## MCP
- ```bash
- hkia mcp # stdio (Claude Desktop, Cursor, Codex, ...)
- hkia mcp --transport http # streamable HTTP on http://127.0.0.1:8787/mcp
- hkia mcp --transport sse # legacy SSE on http://127.0.0.1:8787/sse
- ```
- Client config for stdio:
- ```json
- {
- "mcpServers": {
- "hkia": {
- "command": "hkia",
- "args": ["mcp"]
- }
- }
- }
- ```
- If `hkia` is not on the MCP client's `PATH`, use the absolute path printed by
- `scripts/ensure-binary.sh` as `command`. Restart the client after editing its
- configuration.
- Claude Code and Codex can register the stdio server themselves:
- ```bash
- claude mcp add hkia -- /absolute/path/to/hkia mcp
- codex mcp add hkia -- /absolute/path/to/hkia mcp
- ```
- `npx add-mcp /absolute/path/to/hkia --args mcp --name hkia -a claude-code -y`
- is a third-party helper that writes the same entry for many clients. For HTTP,
- point the client at `http://127.0.0.1:8787/mcp`; for SSE, use
- `http://127.0.0.1:8787/sse` (messages are POSTed to the endpoint URL the server
- sends in the `endpoint` event). `GET /health` is available on both network
- transports. `--path` changes the streamable HTTP endpoint.
- For non-loopback use, set an API key with `--api-key` (alias `--auth-token`)
- or `HKIA_MCP_API_KEY`; requests then need `Authorization: Bearer <key>` or
- `X-API-Key: <key>`. `HKIA_API_KEY` and `HKIA_AUTH_TOKEN` are aliases.
- `--rate-limit` caps HTTP/SSE requests per minute (default 240, `0` disables).
- The server has no TLS of its own and uses one shared static token; bind loopback
- or terminate TLS at a reverse proxy before exposing it.
- MCP tools:
- - `list_flights` — board listing with airport, airline, terminal, state, delay,
- sort, and limit filters
- - `search_flight` — one flight number across both boards
- - `get_delays` — flights delayed beyond a threshold
- - `get_alerts` — cancellations and delays as severity-ranked alerts, with
- optional weather, AEL status and runway in use (`include_ael`, `include_runway`)
- - `get_stats` — single-day on-time performance and hourly breakdown
- - `get_watchlist_alerts` — disruptions filtered to the local watchlist
- - `get_flight_history` — locally observed status/gate/belt timeline
- - `get_historical_stats` — historical range analytics
- - `wait_for_changes` — long-poll for new recorded changes; pass the returned timestamp as `after`
- - `get_airport_access` — modes `airport-express`, `airport-express-status`,
- `in-town-checkin`, `airport-bus`, `trip` (`station`, `direction`, `airline`,
- `route`, `time`, `date`, `terminal`, `buffer_minutes`, `no_live`)
- - `get_weather` — current Hong Kong Observatory warnings
- - `get_runway_status` — runway in use for arrivals/departures, ATIS wind, wind
- components and the last locally observed switch, no arguments
- - `get_runway_history` — locally observed switches, oldest first; optional
- `limit` (default 20, 0 returns all) and `daily` grouping
- Most flight tools take `date`, `direction`, `cargo`, and `lang`; check the tool
- schema for exact parameter names.
- MCP resources:
- - `hkia://board/today/departures`
- - `hkia://board/today/arrivals`
- - `hkia://alerts/today`
- - `hkia://access/ael/status`
- - `hkia://access/ael/HOK` (any station code)
- - `hkia://access/checkin/CX` (any airline code)
- - `hkia://access/bus/A11` (any A-route)
- - `hkia://runway/status`
- - `hkia://runway/history` (locally observed switches, last 20)
- Resources are JSON and support read plus legacy subscribe/unsubscribe; updates
- are polled every 30 seconds. Prefer `wait_for_changes` for push-style clients.
- ## Troubleshooting
- - `ensure-binary.sh` needs either a published release, a checkout with
- `Cargo.toml`, or `$HKIA_BIN`. If it fails, ask the user for an `hkia` path
- rather than inventing one.
- - MCP `401` means the bearer token is missing or wrong; `429` means the
- process-wide rate limit was hit. Read `Retry-After` before retrying.
- - Webhook delivery has a 15-second timeout and no retry queue. Errors are
- warnings; the watch loop continues.
- ## Rules and limits
- - Never invent a flight, terminal, gate, aisle, belt, delay, or cause. If the
- tool returns no match, say so and offer the nearest board or date.
- - Never present computed delay minutes as an official airline metric.
- - The feed is published per calendar day. Future dates may be empty or missing;
- querying tomorrow early in the day can legitimately return no board.
- - Cargo flights live on a separate board: pass `--cargo` / `"cargo": true`.
- - Never invent an Airport Express time, check-in hour, bus route, fare, ETAs,
- or departure window. If a lookup fails, say so. In-town check-in, fare and
- bus facts are dated snapshots, not live availability; quote `checked_on`.
- AEL trains, the delay flag and bus ETAs are live and can be unavailable.
- - The AEL delay flag is a coarse signal. Do not convert it into a delay length,
- cause, or recommendation to rebook. The trip planner's output is a plan based
- on published timetables and the stated buffer, not a guarantee of on-time
- arrival.
- - Never invent a runway. Quote the ATIS arrival/departure runways separately.
- The approach side follows from the runway designator; it is not an observed
- flight track, and runway use can change at any time.
- - The live feed may include the previous day's tail; this tool selects the
- requested date. Keep request rates reasonable; responses cache for 20 seconds
- by default (`--cache-ttl 0` disables, `watch` is uncached).
- - **ATC/tower text is not available.** HKIA tower communications are voice
- radio; there is no public per-flight ATC text or transcription endpoint. Do
- not claim to quote tower instructions. You can report published delays,
- cancellations, weather warnings, and gate changes, and clearly label any
- outside audio/transcript as unverified and unofficial.
- - Flight reference data comes from OurAirports (public domain) and OpenFlights
- (ODbL). Airport access facts come from MTR and HKIA public pages. See
- `NOTICE`.
README.md · README · 856 lines · 1 finding marked
- <div align="center">
- # hkia
- **Live Hong Kong International Airport flight data in one binary.**
- [](https://github.com/hongkong-ai-labs/hongkong-airport-skill/actions/workflows/ci.yml)
- [](https://github.com/hongkong-ai-labs/hongkong-airport-skill/releases/latest)
- [](LICENSE)
- [](Cargo.toml)
- [](https://modelcontextprotocol.io)
- </div>
- Live Hong Kong International Airport flight data from your terminal, your MCP
- client, or your agent.
- `hkia` reads the airport's public flight-information feed — the same feed behind
- the HKIA app and website — and turns it into:
- - a Rust CLI with tables, JSON, CSV and colour
- - an MCP server over **stdio**, **streamable HTTP**, or **legacy SSE**
- - a locally persisted timeline of what the airport actually published
- - targeted watchlists with desktop and webhook notifications
- - historical on-time analytics for the feed's D-91 to D+14 window
- - live Airport Express trains and delay status, a trip planner, in-town check-in
- reference, and A-route bus data with live ETAs
- - the runway in use with the airport wind and computed wind components
- - an installable agent skill (`SKILL.md`)
- No data API key, no scraping, no browser automation. The HTTP MCP transport can
- optionally require a static API key.
- This is an independent, unofficial project. It is not affiliated with Airport
- Authority Hong Kong or HKIA, it sends no telemetry, and the underlying feed
- remains subject to the airport's own terms.
- ## What you get
- Schedules, estimated and actual times, computed delays, cancellations, terminal,
- gate or stand, check-in aisle, baggage belt, arrival hall, codeshares, airline
- and airport names, and ready-to-read terminal guidance. Plus disruption alerts,
- hourly and multi-day statistics, a restart-safe watchlist, and Hong Kong
- Observatory weather warnings as operational context. All times are normalised
- to Hong Kong time (UTC+8).
- ### Terminal, gate and arrival guidance
- Every flight carries the raw airport fields and a derived `guidance` string:
- - departure: `Depart from Terminal 1, check-in aisle C, gate 30`
- - arrival: `Arrive at Terminal 1, gate 30; baggage belt 12, arrival hall A`
- - partial data produces partial guidance rather than an invented instruction
- - cancelled flights say so instead of sending you to a gate
- The airport feed does not publish airline check-in counter rows, security wait
- times, or a per-flight air-traffic-control transcript. See
- [Data limits and ATC](#data-limits-and-atc).
- ## Install
- ### 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+):
- ```bash
- 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):
- ```bash
- cargo install skills-cli --locked
- skills add hongkong-ai-labs/hongkong-airport-skill
- ```
- Manual install without either CLI:
- ```bash
- 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`:
- ```bash
- 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
- ```
- Or from a checkout:
- ```bash
- 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
- ```bash
- 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
- ```bash
- 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:
- ```bash
- docker run --rm -i -v hkia-data:/data hkia mcp
- ```
- Apple's `container` runtime uses the same OCI image:
- ```bash
- 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:
- ```bash
- 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).
- ## Run modes
- One binary covers interactive use, scripts, live watching, MCP clients, and
- containers. The skill is optional; it teaches an agent which mode to use.
- | Mode | Start with | Best for |
- | --- | --- | --- |
- | CLI table | `hkia departures` | Reading a board in a terminal |
- | JSON | `hkia departures --json` | `jq`, scripts, other programs |
- | CSV | `hkia departures --csv` | Spreadsheets and data pipelines |
- | Watch | `hkia watch --interval 60` | Change-only output and alerts |
- | MCP stdio | `hkia mcp` | Desktop and CLI MCP clients that launch a process |
- | MCP HTTP | `hkia mcp --transport http` | One long-lived server for several clients |
- | MCP SSE | `hkia mcp --transport sse` | Clients that only support legacy SSE |
- | Docker | `docker run --rm hkia departures` | No local Rust install |
- | Agent skill | `SKILL.md` from the install section | Teaching an agent when to use the tool |
- The same board in three styles:
- ```bash
- hkia departures --limit 5
- hkia departures --limit 5 --json | jq '.flights[] | {flight_number, status}'
- hkia departures --limit 5 --csv
- ```
- For MCP, the transport changes how the client connects, not the tools or data:
- ```bash
- hkia mcp # stdio
- hkia mcp --transport http --port 8787 # http://127.0.0.1:8787/mcp
- hkia mcp --transport sse --port 8787 # http://127.0.0.1:8787/sse
- ```
- `hkia update` detects whether the binary came from cargo, the release
- installer, a source checkout or Homebrew, and updates with that same
- method. `hkia update --check` only reports.
- ## CLI
- ```bash
- hkia departures # today's departures, table
- hkia arrivals --limit 20 # first 20 arrivals
- hkia flights -D arrival # explicit direction
- hkia flight CX251 # both boards and codeshares, plus guidance
- hkia flight "CX 251" --date tomorrow
- hkia delays # 15+ minute delays, both boards
- hkia delays -D departure --min-delay 45
- hkia alerts # severity-ranked cancellations and delays
- hkia alerts --no-cancelled --min-delay 30
- hkia alerts --watchlist --weather --notify
- hkia stats # on-time performance and hourly counts
- hkia stats -D arrival --date yesterday
- hkia stats --from 2026-11-01 --to 2026-11-14 --group-by airline
- hkia stats --from 2026-09-01 --group-by weekday --csv
- hkia history CX251 # observed status/gate timeline from SQLite
- hkia watch --interval 60 # poll and print only changes
- hkia watch --watchlist --notify --webhook https://example.test/hook
- hkia departures --airport LHR --terminal T1 --airline CPA --status disrupted --json
- hkia departures --lang zh_HK --limit 5
- hkia departures --cargo --limit 10
- hkia access ael --station HOK # live Airport Express next trains
- hkia access ael --station AIR --direction from-airport --json
- hkia access status # live AEL delay status
- hkia access checkin --airline CX # dated in-town check-in reference
- hkia access bus --route A11 # dated windows plus live ETAs
- hkia access trip --airline CX --time 23:59 --date tomorrow --terminal T1
- hkia access bus --route A35 --direction to-airport --json
- hkia update --check
- ```
- Dates accept `YYYY-MM-DD`, `today`, `yesterday`, and `tomorrow`, resolved in
- Hong Kong time. `--limit 0` returns every match. Run `hkia <command> --help` for
- the complete flag set, including per-command filters such as `--flight`,
- `--airport`, `--airline`, `--terminal`, `--status`, `--delayed-over` and
- `--sort`.
- ### Commands
- | Command | Purpose |
- | --- | --- |
- | `departures` / `arrivals` | One board, table/JSON/CSV |
- | `flights` | Board with `-D/--direction` |
- | `flight <number>` | One flight across both boards and codeshares, with guidance |
- | `delays` | Flights delayed beyond a threshold |
- | `alerts` | Cancellations and delays, with optional watchlist, weather, AEL status and runway |
- | `watch` | Poll and print status/gate/belt changes, plus AEL status and runway changes |
- | `stats` | Single-day stats, or historical range analytics |
- | `history <number>` | Locally observed status/gate timeline |
- | `access` | `ael`, `status`, `checkin`, `bus`, `trip` airport-access queries |
- | `runway` | Runway in use for arrivals and departures, with the airport wind |
- | `watchlist` | `show`, `add`, `remove`, `set`, `clear` |
- | `mcp` | MCP server over stdio, HTTP, or SSE |
- ### Common flags
- | Flag | Meaning |
- | --- | --- |
- | `--json` | Machine-readable JSON; wins over table output |
- | `--csv` | CSV for board, flight, delays, alerts, stats, range, and history |
- | `--no-header` | Omit the CSV header |
- | `--color auto\|always\|never` | Table colour policy (default `auto`) |
- | `--sort time\|delay\|flight\|state` | Board sort order (`departures`, `arrivals`, `flights`, `watch`) |
- | `--cache-ttl 20` | API cache seconds (HKIA and MTR); `0` disables |
- | `--keep-days 90` | Days of flight and runway history kept when the store is pruned |
- | `--cargo` | Read the cargo board instead of passenger flights |
- | `--lang en\|zh_HK\|zh_CN` | Raw feed language (default `en`); localized status text is parsed |
- | `--db PATH` | Override the SQLite history database |
- | `--config PATH` | Override the watchlist TOML path |
- `--lang` changes the airport's raw status text, not the derived field names or
- `guidance` text, which remain English. All three languages are parsed for status
- type, delay basis and cancellations.
- ### JSON
- Add `--json` to any command. A board looks like:
- ```json
- {
- "date": "2026-11-21",
- "direction": "departure",
- "lastUpdated": "2026-11-21T20:07:01+08:00",
- "fetchedAt": "2026-11-21T20:07:03+08:00",
- "totalOnBoard": 431,
- "count": 1,
- "flights": [
- {
- "flight_number": "CX 251",
- "airline": "CPA",
- "airline_name": "Cathay Pacific",
- "codeshares": [],
- "direction": "departure",
- "date": "2026-11-21",
- "scheduled_time": "23:00",
- "scheduled_at": "2026-11-21T23:00:00+08:00",
- "status": "Dep 00:00 (22/11/2026)",
- "status_type": "departed",
- "status_published": true,
- "actual_at": "2026-11-22T00:00:00+08:00",
- "delay_minutes": 60,
- "delay_basis": "actual",
- "state": "delayed",
- "terminal": "T1",
- "gate": "30",
- "check_in_aisle": "C",
- "guidance": "Depart from Terminal 1, check-in aisle C, gate 30",
- "destination": ["LHR"],
- "destination_details": [{ "iata": "LHR", "name": "London Heathrow Airport", "city": "London", "country": "United Kingdom" }]
- }
- ]
- }
- ```
- Every flight includes `origin`, `destination`, `origin_details`,
- `destination_details`, `terminal`, `gate`, `stand`, `check_in_aisle`,
- `baggage_belt`, `arrival_hall`, `status_published`, `delay_basis`, `guidance`,
- and `fetched_at`. Unknown operational fields are `null`, never guessed.
- ### Watchlist and notifications
- The watchlist is TOML at `$HKIA_CONFIG`, `$XDG_CONFIG_HOME/hkia/config.toml`, or
- `~/.config/hkia/config.toml`.
- ```bash
- hkia watchlist add --flight CX251
- hkia watchlist add --airport LHR
- hkia watchlist add --airline CPA
- hkia watchlist set --min-delay 10 --direction departure
- hkia watchlist set --desktop true --webhook https://example.test/hook
- hkia watchlist show
- ```
- ```toml
- [watchlist]
- flights = ["CX251"]
- airports = ["LHR"]
- airlines = ["CPA"]
- direction = "departure"
- min_delay = 10
- include_cancelled = true
- [notify]
- desktop = false
- webhook = "https://example.test/hook"
- ```
- Empty selectors match every flight. Flights match operating numbers and
- codeshares; airports match either endpoint of the route. Webhooks receive JSON
- with `source`, `kind`, `timestamp`, `changes` or `alerts`, and the watchlist
- that produced them. Notifications are deduplicated by alert fingerprint in
- SQLite, so restarting `watch` does not resend the same alert; pass
- `--force-notify` on `alerts` to bypass dedupe.
- ### History and persistence
- SQLite lives at `$HKIA_DATA_DIR/hkia.db`, `$XDG_DATA_HOME/hkia/hkia.db`, or
- `~/.local/share/hkia/hkia.db`. Watch ticks, `history`,
- notification-enabled `alerts`, and MCP history/watch calls record observations;
- a plain board read does not. Observations append an event only when status,
- delay, gate, terminal, belt, or stand changes. Events older than 90 days are
- pruned opportunistically. `hkia history CX251` is therefore limited to what this
- machine has actually observed — it is not an airport-provided audit log.
- ## Historical analytics
- `stats --from` uses the airport's historical endpoint, valid from D-91 through
- D+14. Weekends and future days may be unavailable; failed days are reported in
- `failures` instead of being silently dropped.
- ```bash
- hkia stats --from 2026-11-01 --to 2026-11-14 --group-by route --json
- ```
- The range report includes a flattened summary (`flights`, `cancelled`,
- `delayed`, `on_time`, `early`, `scheduled`, `tracked`,
- `average_delay_minutes`, `max_delay_minutes`, `on_time_percent`) plus `by_day`,
- `by_airline`, `by_route`, `by_weekday`, and `by_hour`. `--group-by` is only
- valid with `--from` and selects the table/CSV focus.
- ## Airport access
- `hkia access` covers getting to and from the airport without changing the
- flight commands. It is a separate surface with explicit data provenance.
- ```bash
- hkia access ael --station HOK
- hkia access ael --station AIR --direction from-airport --json
- hkia access ael --station KOW --direction both --csv
- hkia access status --json
- hkia access checkin --airline CX
- hkia access checkin --airline CPA --json
- hkia access bus --route A11
- hkia access bus --route A35 --json
- hkia access bus --route A31 --direction to-airport --csv
- hkia access bus --route A11 --no-live
- hkia access bus --csv
- hkia access trip --airline CX --time 23:59 --date tomorrow
- hkia access trip --station KOW --airline CX --time 07:40 --terminal T1 --buffer 15 --json
- hkia runway # arrival/departure runway in use
- hkia runway --json
- hkia runway --csv
- hkia runway --history # locally observed switches (from watch)
- ```
- `ael` is live: it reads the MTR Next Train API through data.gov.hk and returns
- upcoming trains, destination, platform and minutes to departure. Stations are
- `HOK`, `KOW`, `TSY`, `AIR` and `AWE`. The direction defaults to `to-airport`
- from Hong Kong, Kowloon and Tsing Yi, and `from-airport` at Airport and
- AsiaWorld-Expo. Each response includes the AEL journey times, first/last train
- windows and the official MTR fares (Octopus, single and 30-day round trip,
- adult and child), with `checked_on` and source URLs.
- `status` checks the same live API for the `isdelay` flag at Hong Kong and
- Airport and reports whether MTR has flagged an Airport Express delay. It is a
- coarse line-status signal, not a cause or an estimate of how long a delay will
- last. `alerts` and `watch` include this status by default (`--no-ael` skips it),
- and watch mode prints and notifies when the flag changes.
- `checkin` is a dated snapshot of MTR's published in-town check-in list, not live
- availability. It matches IATA codes, ICAO codes or airline names and returns
- Hong Kong and Kowloon station hours, the check-in window, eligibility and
- baggage limits.
- `bus` is a dated snapshot of the 30 HKIA A-routes with both directions:
- destination, operator, adult fares (weekday plus published holiday notes) and
- the city-to-airport and from-airport departure windows. With `--route`, it also
- queries the Citybus, Long Win/KMB or New Lantao live ETA API for the published
- terminus stop; `--direction` picks the direction (default `both`) and
- `--no-live` keeps the output static.
- `trip` plans the latest Airport Express departure for a flight. It applies MTR's
- published 90-minute check-in cutoff, adds an explicit `--buffer` (default 0),
- uses the station's published journey time, rounds down to the 10-minute
- headway, and reports the airport arrival deadline and latest train with the
- published first/last train window. It does **not** invent security, immigration
- or walking times, and it shows in-town check-in hours for the station without
- shortening the airport buffer. The flight time must be in the future Hong Kong
- time; use `--date tomorrow` for late-night flights already passed today.
- The reference data was checked on **2026-11-22**. Hours, fares and participating
- airlines can change; confirm with MTR, the airline or the bus operator before
- travel. Sources: the MTR Next Train API, MTR Airport Express timetable, fares
- CSV and frequency pages, MTR's in-town check-in page, HKIA's public-bus page,
- and the Citybus/LWB/KMB/NLB live ETA APIs; see [NOTICE](NOTICE) for the exact
- URLs. Use `--json` or `--csv` for scripts; `--no-header` omits the CSV header.
- `scripts/refresh_access_data.py --write` regenerates the embedded files and
- `--check` compares them with the official sources without updating anything. A
- scheduled GitHub Actions workflow runs the check weekly and opens an issue when
- the data drifts.
- ## Runway in use
- `hkia runway` answers which direction aircraft are landing and departing. It
- reads the Civil Aviation Department's public ATIS page on `hkatc.gov.hk`, which
- is the official runway-in-use broadcast, and reports the arrival and departure
- runway separately along with the ATIS letter and issue time.
- ```bash
- hkia runway
- hkia runway --json
- hkia runway --csv
- hkia runway --history
- ```
- The output also gives the airport wind from the ATIS and the computed
- head/tailwind and crosswind components for the arrival runway, plus the approach
- side implied by the runway designator: runway 07 means aircraft land heading
- eastbound, approaching from the west, while runway 25 means the opposite. This
- is what residents around the flight paths usually want when asking whether
- aircraft are coming in over their side of the airport.
- Runway 07 is preferred at HKG whenever the tailwind component is 5 knots or less
- (AIP VHHH AD 2.22), but ATC can use runway 25 when required, and arrivals and
- departures can differ. The tool therefore reports the ATIS statement rather than
- predicting from wind. Wind components are derived from the reported wind, not
- threshold measurements, and the ATIS page can be briefly unavailable while a
- bulletin updates.
- When the ATIS page cannot be read, `hkia runway` falls back to the Hong Kong
- Observatory's 10-minute wind at Chek Lap Kok and says plainly that the runway is
- not confirmed. In that mode the JSON has `atis_available: false`, a `wind`
- object with the compass direction and knots, and `wind_favours`, which applies
- the AIP rule (runway 07 when the tailwind is 5 knots or less). The wind favour
- is an indication, not the runway in use, and the command never invents one. If
- both the ATIS and the HKO feed fail, it returns an error instead.
- In table mode, `hkia runway` also prints the most recent switch this machine
- recorded while `watch` was running, so the current runway can be read together
- with when it last changed. JSON carries the same as `last_observed`, which is
- `null` until something has been observed; that line is local observation, not
- part of the official ATIS.
- `hkia watch` polls the runway with the rest of the board and prints, notifies
- and webhooks when the arrival or departure runway changes (`--no-runway` skips
- those checks, `--no-ael` skips the AEL status). `hkia alerts` includes the
- current runway and AEL status too, with the same `--no-runway` / `--no-ael`
- opt-outs. `watch` opens with a one-line summary of the recorded runway history,
- and `alerts` prints the last observed switch beneath the live runway (JSON
- `last_observed`).
- Every observed switch is also written to the local SQLite store, so
- `hkia runway --history` shows what this machine actually saw, oldest first:
- ```bash
- hkia runway --history
- hkia runway --history --limit 50 --json
- hkia runway --history --csv
- hkia runway --history --daily
- ```
- `--daily` groups the rows by local date and shows how many switches were seen
- that day with the first and last arrival/departure runway (`--limit` then caps
- the number of days). History is pruned to the last `--keep-days` days (default
- 90) whenever a command opens the store; raise it to keep more, or set `0` to
- keep none.
- ```
- Observed runway switches by day | 1 day(s) | local store
- DATE SWITCHES FIRST LAST
- 2026-11-22 1 07C/07R 07C/07R
- ```
- There is no public historical runway feed; the history only covers periods when
- `hkia watch` was running, and a switch is recorded once per change, not per
- poll. The same rows are available to agents as the `hkia://runway/history`
- resource (last 20 switches).
- ## MCP
- ### stdio
- ```json
- {
- "mcpServers": {
- "hkia": {
- "command": "hkia",
- "args": ["mcp"]
- }
- }
- }
- ```
- Register it with any MCP client:
- ```bash
- npx add-mcp "$(command -v hkia) mcp" --name hkia -a claude-code -a codex -a cursor -y
- claude mcp add hkia -- hkia mcp
- codex mcp add hkia -- hkia mcp
- ```
- `add-mcp` detects the client configuration files in the current project; add
- `-g` for a global install. Substitute an absolute path if your client does not
- inherit the shell `PATH`.
- If `hkia` is not on the MCP client's `PATH`, replace `"command": "hkia"` with
- an absolute path. `scripts/ensure-binary.sh` prints the path to use. Restart the
- client after changing its MCP configuration.
- #### Client setup
- Claude Code and Codex can write the stdio entry themselves:
- ```bash
- claude mcp add hkia -- /absolute/path/to/hkia mcp
- codex mcp add hkia -- /absolute/path/to/hkia mcp
- ```
- Cursor reads `.cursor/mcp.json` (project) or `~/.cursor/mcp.json` (user).
- Claude Desktop uses `claude_desktop_config.json` in its application-support
- directory. Paste the `mcpServers` block above into either file and restart the
- client.
- ### Streamable HTTP
- ```bash
- hkia mcp --transport http --port 8787
- # endpoint: http://127.0.0.1:8787/mcp
- # health: http://127.0.0.1:8787/health
- ```
- ```json
- {
- "mcpServers": {
- "hkia": {
- "type": "http",
- "url": "http://127.0.0.1:8787/mcp"
- }
- }
- }
- ```
- ### SSE
- ```bash
- hkia mcp --transport sse --port 8787
- # stream: http://127.0.0.1:8787/sse
- # messages: POST to the endpoint URL announced by the server
- ```
- ```json
- {
- "mcpServers": {
- "hkia": {
- "type": "sse",
- "url": "http://127.0.0.1:8787/sse"
- }
- }
- }
- ```
- Use `--host 0.0.0.0` to listen beyond loopback. Both network transports expose
- `GET /health` and permissive CORS for local tooling; `--path` changes the
- streamable HTTP endpoint. `/health` stays public, while `/mcp`, `/sse`, and
- `/messages` are protected when auth is enabled.
- The server does not terminate TLS, and the bearer token is one shared static
- secret. Keep the default loopback bind, or put it behind a TLS reverse proxy
- before exposing it to another machine.
- ### Auth and rate limiting
- ```bash
- hkia mcp --transport http --api-key "$SECRET"
- # --auth-token is an alias; either env var works:
- # HKIA_MCP_API_KEY="$SECRET" hkia mcp --transport http
- # HKIA_AUTH_TOKEN="$SECRET" hkia mcp --transport http
- ```
- Protected routes require `Authorization: Bearer $SECRET` or
- `X-API-Key: $SECRET`. Requests are limited
- to 240 per minute by default across the process (`--rate-limit 0` disables,
- `--rate-limit N` changes the cap); over-limit requests receive HTTP 429 with
- `Retry-After: 60`. This is a single-process guard, not a multi-tenant quota.
- ```json
- {
- "mcpServers": {
- "hkia": {
- "type": "http",
- "url": "http://127.0.0.1:8787/mcp",
- "headers": { "Authorization": "Bearer <token>" }
- }
- }
- }
- ```
- Keep the token in your client's secret store or an environment variable where
- the client supports interpolation; do not commit it to a shared config file.
- `/health` remains public so container and Worker readiness probes do not need
- the key.
- ### Tools
- | Tool | Purpose |
- | --- | --- |
- | `list_flights` | Board listing with airport, airline, terminal, state, delay, sort and limit filters |
- | `search_flight` | One flight number across departures, arrivals, and codeshares |
- | `get_delays` | Flights delayed beyond a threshold |
- | `get_alerts` | Cancellations and delays as severity-ranked alerts, with weather, AEL status and runway in use |
- | `get_stats` | Single-day on-time performance and hourly breakdown |
- | `get_watchlist_alerts` | Disruptions filtered to the local watchlist, optional weather |
- | `get_flight_history` | Locally observed status/gate/belt timeline for a flight |
- | `get_historical_stats` | Multi-day range analytics with airline/route/hour/weekday groups |
- | `wait_for_changes` | Long-poll for new recorded changes; use the returned timestamp as the next `after` |
- | `get_weather` | Current Hong Kong Observatory warnings |
- | `get_runway_status` | Runway in use for arrivals and departures, ATIS wind, wind components and last observed switch |
- | `get_runway_history` | Locally observed runway switches, oldest first, with an optional `limit` (default 20, 0 for all) and `daily` grouping |
- | `get_airport_access` | Live AEL trains and status, trip planning, dated in-town check-in hours, or A-route bus data with live ETAs |
- Watchlist and history tools use the local SQLite store and config, so the same
- `--db`, `--config` and `--keep-days` global flags apply. Most flight tools accept `date`,
- `direction`, `cargo`, and `lang`; `get_airport_access` takes `mode`, `station`,
- `direction`, `airline`, `route`, `time`, `date`, `terminal`, `buffer_minutes` and
- `no_live`. Its modes are `airport-express`, `airport-express-status`,
- `in-town-checkin`, `airport-bus` and `trip`. `get_alerts` takes `include_ael` and
- `include_runway` (both default true). See each tool's schema for exact names.
- ### Resources
- | URI | Content |
- | --- | --- |
- | `hkia://board/today/departures` | Today's departure board JSON |
- | `hkia://board/today/arrivals` | Today's arrival board JSON |
- | `hkia://alerts/today` | Today's cancellations and 15+ minute delays |
- | `hkia://access/ael/status` | Live Airport Express delay flag |
- | `hkia://access/ael/HOK` | Live AEL departures, fares and journey times (use any station code) |
- | `hkia://access/checkin/CX` | Dated in-town check-in hours (use any airline code) |
- | `hkia://access/bus/A11` | Dated A-route windows and fares plus live ETAs (use any route) |
- | `hkia://runway/status` | Official ATIS runway in use and airport wind |
- | `hkia://runway/history` | Locally observed runway switches, last 20 |
- Resources support read and the legacy subscribe/unsubscribe flow. Subscriptions
- poll every 30 seconds and emit `notifications/resources/updated` when the
- serialized resource changes. For reliable push-style integrations, prefer
- `wait_for_changes`.
- ## Troubleshooting
- - **Installer cannot find a release:** the script needs a `v*` release with a
- matching `<target>.tar.gz`. From a clone, build with
- `cargo build --release --locked`; setting `HKIA_VERSION` only selects an
- existing release tag.
- - **Unsupported platform:** prebuilt binaries cover macOS x86_64/arm64 and Linux
- x86_64/aarch64. Use `cargo install --path . --locked` elsewhere.
- - **MCP returns 401:** the client must send `Authorization: Bearer <key>` (or
- `X-API-Key`) when `--api-key`, `HKIA_MCP_API_KEY` or an alias is set. `/health`
- stays public.
- - **MCP returns 429:** the process-wide rate limit was reached; raise
- `--rate-limit` or wait for `Retry-After`.
- - **Webhook delivery fails:** the request times out after 15 seconds, non-2xx
- responses are errors, and there is no retry queue. Delivery errors are printed
- as warnings; the watch loop continues.
- ## Configuration
- | Variable | Meaning |
- | --- | --- |
- | `HKIA_API_BASE` | Override the feed base URL (default `https://www.hongkongairport.com/flightinfo-rest/rest`) |
- | `HKIA_WEATHER_URL` | Override the HKO warning endpoint |
- | `HKIA_MCP_API_KEY` | API key for HTTP/SSE MCP (`HKIA_API_KEY` and `HKIA_AUTH_TOKEN` are aliases) |
- | `HKIA_DATA_DIR` | Directory containing `hkia.db` |
- | `HKIA_CONFIG` | Watchlist TOML path |
- ## Data limits and ATC
- - Source: the airport's public REST feed. The live board is
- `flights?date=YYYY-MM-DD&lang=en&cargo=false&arrival=false`; history uses
- `flights/past` for the same date window.
- - The feed publishes one board per calendar day and may include the previous
- day's tail; only the requested date is used.
- - `delay_minutes` is derived from free-text status (`Dep HH:MM`,
- `Est at HH:MM`, `At gate HH:MM`, `Cancelled`) against the scheduled time.
- A flight is `delayed` at 15 minutes or more and `early` at 15 minutes or less.
- This is not an airline cause code and does not distinguish weather, crew, or
- slot delays.
- - Terminal and gate assignments can change or be blank until close to
- departure. `guidance` reflects the currently published fields only.
- - Future dates may return no board until the airport publishes them. Very old
- dates outside D-91 and dates beyond D+14 return a range error.
- - Airport Express train data, the delay flag and bus ETAs are live from MTR,
- Citybus, LWB/KMB and NLB APIs. In-town check-in, AEL fare and A-route bus
- facts are dated reference snapshots checked `2026-11-22`, not live
- availability. Bus windows are published terminus departure windows, not
- frequency guarantees, and live ETAs cover the terminus stop only. The trip
- planner uses the 90-minute cutoff, an explicit buffer and the published
- journey time; it does not model security, immigration or walking time.
- - Runway in use is live from the CAD ATIS. It is the official broadcast, but it
- changes with wind and operations, arrivals and departures can use different
- runways, and the ATIS can be briefly unavailable while updating. The approach
- side is derived from the runway designator, not from observed flight tracks.
- - Responses are cached for 20 seconds (`--cache-ttl 0` disables it; `watch` is
- uncached). Delay/alert data is only as fresh as the airport feed itself; the
- project makes no uptime or freshness guarantee.
- - Localized status parsing covers English, Traditional Chinese (`zh_HK`) and
- Simplified Chinese (`zh_CN`) terms such as `Dep`/`啟航`/`启航`,
- `At gate`/`到閘口`/`到闸口`, `Est`/`預計`/`预计` and
- `Cancelled`/`取消`. The raw status string still depends on the requested
- language.
- - **ATC/tower text:** HKIA tower communications are voice radio, and there is
- no public per-flight ATC text or transcription feed. This tool does not
- scrape or transcribe tower audio. It can surface published delays, weather
- warnings, cancellations, and gate changes, but it cannot tell you what a
- controller said to a specific flight. Treat any such transcript as
- unverified unless it comes from an official source.
- ## Development
- ```bash
- just check # fmt-check, clippy, tests
- just skill-check # validate SKILL.md and shell scripts the way CI does
- just build-release
- ```
- `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.
- Without `just`:
- ```bash
- cargo fmt --all -- --check
- cargo clippy --all-targets --locked -- -D warnings
- cargo test --all --locked
- ```
- Tests cover status parsing, midnight rollover, cancellations, codeshares,
- filters, stats/alerts, the captured board fixture, watchlist matching and
- dedupe, SQLite change detection and notification dedupe, weather parsing, AEL
- parsing and trip planning, bus data, ATIS parsing and wind components, and TOML
- round-tripping. Integration tests exercise the access CLI JSON/CSV shapes,
- station/direction errors, MCP tool mode routing and MCP access/runway
- resources. CI runs formatting, clippy, tests, the access data drift check, a
- release build and a SKILL.md/script validation job. Tagged releases verify the tag against
- `Cargo.toml` and `CHANGELOG.md`, build macOS and static Linux binaries, smoke
- test the native artifact, and publish `SHA256SUMS`.
- Layout: `src/api.rs` (feed client, normalisation, delays, alerts, stats),
- `src/analytics.rs` (historical ranges), `src/store.rs` (SQLite),
- `src/watchlist.rs` (config and matching), `src/notify.rs` (desktop/webhook),
- `src/weather.rs` (HKO), `src/access.rs` (AEL and bus live clients, trip planner
- and dated reference data), `src/runway.rs` (CAD ATIS runway and wind),
- `src/render.rs` (tables/CSV), `src/mcp.rs`
- (transports, tools, resources), `src/main.rs` (CLI), `scripts/install.sh`
- (release installer), `scripts/ensure-binary.sh` (agent resolver),
- `scripts/refresh_access_data.py` (access data generator/checker), and `SKILL.md`
- (agent skill).
- ## Data licences
- Airport and airline reference data is embedded from OurAirports (public domain)
- and OpenFlights (ODbL). Airport Express, in-town check-in and A-route bus
- reference facts come from MTR and HKIA pages listed in [NOTICE](NOTICE), and the
- runway/ATIS data comes from the Civil Aviation Department. Flight data, the live
- train feed and the ATIS page remain subject to their providers' terms; this
- project only reads the public endpoints.
- ## Licence
- MIT. See [LICENSE](LICENSE).
Ratings and comments
Sign in to rate this skill.
Sign inFree to use. If it’s helped, pass it on.