hongkong-weather-skill
Hong Kong Observatory weather data — current temperature, humidity, rainfall and UV readings, active warnings, the local forecast, and the nine-day forecast for Hong Kong. Use for any question about Hong Kong weather, HKO forecasts, typhoons, rainstorms, cold or hot weather warnings, or district rainfall.
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-weather-skill)HTML
<a href="/listings/hongkong-ai-labs--hongkong-weather-skill"><img src="/api/listings/hongkong-ai-labs--hongkong-weather-skill/badge.svg" alt="findsafeskills safety rating" /></a>Install
Install instructions from the README
As written by the repo's author. findsafeskills has not verified these steps.
These steps run a script from the network that findsafeskills does not scan.
**Agent skill** — installs `SKILL.md` and the binary bootstrap script:
npx skills add hongkong-ai-labs/hongkong-weather-skill npx skills update # refresh the installed skill later
**Prebuilt binary** — macOS (Intel or Apple silicon) and Linux (x86_64 or aarch64, static musl), checksum-verified, into `~/.local/bin`:
curl -fsSL https://raw.githubusercontent.com/hongkong-ai-labs/hongkong-weather-skill/main/scripts/install.sh | sh
**From source** — Rust 1.89 or newer:
git clone https://github.com/hongkong-ai-labs/hongkong-weather-skill cd hongkong-weather-skill cargo install --path . --locked # or directly from GitHub: cargo install --git https://github.com/hongkong-ai-labs/hongkong-weather-skill --locked # or: cargo build --release --locked # target/release/hkweather
Verify:
$ hkweather --version
`hkweather update` detects whether the binary came from cargo, the release installer, a source checkout or Homebrew, and updates with that same method. `hkweather update --check` only reports.
What was scanned
The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.
SKILL.md · Manifest · 159 lines · 1 finding marked
- ---
- name: hongkong-weather-skill
- description: Hong Kong Observatory weather data — current temperature, humidity, rainfall and UV readings, active warnings, the local forecast, and the nine-day forecast for Hong Kong. Use for any question about Hong Kong weather, HKO forecasts, typhoons, rainstorms, cold or hot weather warnings, or district rainfall.
- license: MIT
- ---
- # Hong Kong weather (HKO)
- `hkweather` is a Rust CLI and MCP server for the Hong Kong Observatory's
- public open-data API. It needs no API key and no account. It is an independent,
- unofficial project and is not affiliated with HKO.
- Use it when the user asks about:
- - current temperature, humidity, UV index or rainfall in Hong Kong
- - today's local forecast, the outlook, or the nine-day forecast
- - active weather warnings: tropical cyclones, rainstorms, thunderstorm, fire
- danger, cold weather, very hot weather, strong monsoon, landslip, flooding
- - rainfall by district, or how wet a month or year has been
- - whether a typhoon signal or rainstorm warning is in force
- ## Before first use
- Run `scripts/ensure-binary.sh` from the skill directory:
- ```console
- $ bash scripts/ensure-binary.sh
- /Users/you/.local/bin/hkweather
- ```
- It prints the absolute path of a working binary. Use that path for every
- command, or capture it once:
- ```bash
- BIN="$(bash scripts/ensure-binary.sh)"
- ```
- It checks, in order: `$HKWEATHER_BIN`, `hkweather` on `PATH`,
- `scripts/install.sh`, then `cargo build --release --locked` in the repo root.
- ### Install the binary directly
- `npx skills add` installs the skill files. If the binary is missing, install it
- with the release installer or cargo:
- ```bash
- curl -fsSL https://raw.githubusercontent.com/hongkong-ai-labs/hongkong-weather-skill/main/scripts/install.sh | sh
- Note: Pipes a downloaded script directly into a shell (curl | sh / wget | bash)
- Line 47 on GitHub
- # or
- cargo install --git https://github.com/hongkong-ai-labs/hongkong-weather-skill --locked
- ```
- Register it with any MCP client:
- ```bash
- npx add-mcp "$(command -v hkweather) mcp" --name hongkong-weather -a claude-code -a codex -a cursor -y
- claude mcp add hongkong-weather -- hkweather mcp
- codex mcp add hongkong-weather -- hkweather mcp
- ```
- `add-mcp` detects the client configuration files in the current project; add
- `-g` for a global install. `$(command -v hkweather)` keeps the entry correct
- when the binary is on `PATH`; substitute an absolute path if your client does
- not inherit the shell `PATH`.
- ## CLI
- Prefer `--json` when you need to parse. Tables are for humans. All timestamps
- are Hong Kong time (UTC+8).
- ```bash
- $BIN current --json # all current readings
- $BIN current --place "Sha Tin" --json # one place
- $BIN forecast --json # nine-day forecast
- $BIN forecast --days 3 --json # first three days
- $BIN warnings --json # active warnings
- $BIN warnings --all --json # include cancelled warnings
- $BIN local --json # local forecast + outlook
- $BIN rain --json # district rainfall since midnight
- $BIN uv --json # UV index by station
- $BIN all --json # everything in one object
- $BIN update --check
- ```
- `--lang tc` or `--lang sc` returns HKO's Traditional or Simplified Chinese
- text. Field names stay English.
- ### What the JSON contains
- `current`:
- | Field | Meaning |
- | --- | --- |
- | `update_time` | HKO publication time, RFC 3339 with `+08:00` |
- | `temperature` | `[{place, value, unit}]` |
- | `humidity` | `[{place, value, unit}]` |
- | `rainfall` | `[{place, max, main, unit}]`, millimetres since midnight |
- | `uv_index` | `[{place, value, desc}]` |
- | `warnings` | HKO warning headline strings (`[]` when none) |
- | `rainfall_totals` | midnight-to-noon, last month, year to date (mm) |
- `forecast.days[]` has `forecastDate` (`YYYYMMDD`), `week`, `forecastWeather`,
- `forecastWind`, `forecastMaxtemp` / `forecastMintemp`
- (`{value, unit}`), `forecastMaxrh` / `forecastMinrh`, `ForecastIcon`, and
- `PSR` — the probability of significant rain (`Low`, `Medium`, `High`).
- `warnings` are objects with `code`, `name`, `cancelled`, `subtype`,
- `update_time`, `expiry_time`, and `contents`. A code such as `WTCSGNL` is the
- tropical cyclone warning signal statement; the signal number is in the
- `contents` text, so quote that text rather than guessing a number.
- ## MCP
- ```bash
- $BIN mcp
- ```
- ```json
- {
- "mcpServers": {
- "hongkong-weather": {
- "command": "/absolute/path/to/hkweather",
- "args": ["mcp"]
- }
- }
- }
- ```
- Tools:
- | Tool | Purpose |
- | --- | --- |
- | `hko_current_weather` | Current readings, optional `station` substring |
- | `hko_forecast` | Nine-day forecast, optional `days` |
- | `hko_warnings` | Active warnings, optional `include_cancelled` |
- | `hko_local_forecast` | Local forecast and outlook |
- | `hko_rainfall` | District rainfall since midnight |
- All tools accept `lang` (`en`, `tc`, `sc`).
- ## Answering safely
- - Say "HKO says" and give the publication time. HKO updates readings and
- forecasts on its own schedule; a cached answer can be a few minutes old.
- - Warnings are safety information. Quote the warning text and signal number.
- Do not downgrade, summarise away, or predict when a warning will be lifted.
- - The nine-day forecast is a forecast, not a guarantee. Give the date range and
- the rain probability band rather than a single certainty.
- - "Low" rain probability does not mean no rain; scattered showers still happen.
- - UV index is station-specific and is not a sunscreen recommendation.
- - Rainfall is since midnight in millimetres, not an hourly rate.
- - This is an independent client of HKO open data. It is not an official HKO
- channel. For decisions involving safety, ferries, flights, or outdoor work,
- check the HKO website or app directly.
- ## Source
- HKO open data, `https://data.weather.gov.hk/weatherAPI/opendata/weather.php`,
- with `dataType=rhrread|fnd|flw|warninginfo`. No key is required. Responses are
- cached for 60 seconds in-process (`--cache-ttl 0` disables).
README.md · README · 213 lines · 1 finding marked
- # hkweather
- Hong Kong Observatory weather data as a Rust CLI and an MCP server.
- `hkweather` reads HKO's public, keyless open data and exposes current
- readings, district rainfall, UV, active warnings, the local forecast and the
- nine-day forecast as tables, JSON, or MCP tools.
- It is an independent, unofficial project, not affiliated with the Hong Kong
- Observatory.
- ## Install
- **Agent skill** — installs `SKILL.md` and the binary bootstrap script:
- ```bash
- npx skills add hongkong-ai-labs/hongkong-weather-skill
- npx skills update # refresh the installed skill later
- ```
- **Prebuilt binary** — macOS (Intel or Apple silicon) and Linux (x86_64 or
- aarch64, static musl), checksum-verified, into `~/.local/bin`:
- ```bash
- curl -fsSL https://raw.githubusercontent.com/hongkong-ai-labs/hongkong-weather-skill/main/scripts/install.sh | sh
- Note: Pipes a downloaded script directly into a shell (curl | sh / wget | bash)
- Line 25 on GitHub
- ```
- **From source** — Rust 1.89 or newer:
- ```bash
- git clone https://github.com/hongkong-ai-labs/hongkong-weather-skill
- cd hongkong-weather-skill
- cargo install --path . --locked
- # or directly from GitHub:
- cargo install --git https://github.com/hongkong-ai-labs/hongkong-weather-skill --locked
- # or: cargo build --release --locked # target/release/hkweather
- ```
- Verify:
- ```console
- $ hkweather --version
- ```
- `hkweather update` detects whether the binary came from cargo, the release
- installer, a source checkout or Homebrew, and updates with that same
- method. `hkweather update --check` only reports.
- ## CLI
- ```bash
- hkweather current # all current readings
- hkweather current --place "Sha Tin" # one place
- hkweather forecast --days 3 # first three forecast days
- hkweather warnings # active warnings
- hkweather warnings --all # include cancelled
- hkweather local # local forecast + outlook
- hkweather rain # district rainfall
- hkweather uv # UV index
- hkweather all # everything
- hkweather --json current # machine-readable
- hkweather --lang tc forecast # Traditional Chinese HKO text
- hkweather mcp # MCP over stdio
- hkweather update --check
- ```
- ## MCP
- ```json
- {
- "mcpServers": {
- "hongkong-weather": {
- "command": "hkweather",
- "args": ["mcp"]
- }
- }
- }
- ```
- Register it with any MCP client:
- ```bash
- npx add-mcp "$(command -v hkweather) mcp" --name hongkong-weather -a claude-code -a codex -a cursor -y
- claude mcp add hongkong-weather -- hkweather mcp
- codex mcp add hongkong-weather -- hkweather mcp
- ```
- `add-mcp` detects the client configuration files in the current project; add
- `-g` for a global install. `$(command -v hkweather)` keeps the entry correct
- when the binary is on `PATH`; substitute an absolute path if your client does
- not inherit the shell `PATH`.
- Tools: `hko_current_weather`, `hko_forecast`, `hko_warnings`,
- `hko_local_forecast`, `hko_rainfall`.
- ## Data
- | Dataset | HKO `dataType` |
- | --- | --- |
- | Current readings | `rhrread` |
- | Nine-day forecast | `fnd` |
- | Local forecast | `flw` |
- | Warnings | `warninginfo` |
- Source: `https://data.weather.gov.hk/weatherAPI/opendata/weather.php`.
- No API key. Responses are cached for 60 seconds (`--cache-ttl 0` disables).
- ## Limits
- HKO data is published for general information. Warnings and forecasts can
- change; always check HKO directly for safety-critical decisions. The API does
- not provide a per-minute nowcast, lightning location, or official district
- rainfall forecast.
- ## Run modes and deployment
- | Mode | Start with | Use for |
- | --- | --- | --- |
- | CLI | `hkweather <command>` | Interactive use and shell scripts |
- | JSON | `<command>` with `--json` | `jq`, automation, other programs |
- | MCP stdio | `hkweather mcp` | Desktop and CLI MCP clients |
- | Container | `docker run --rm -i hkweather mcp` | No local Rust toolchain |
- ### MCP and authentication
- This server is **stdio-only**: the client launches the process and speaks MCP
- over stdin/stdout. There is no listening port, so there is no network
- authentication layer and no API-key setting. Optional API keys in this project
- family apply only to servers that expose an HTTP transport. Keep the process
- local and let the MCP client manage it.
- Typical client entry:
- ```json
- {
- "mcpServers": {
- "hongkong-weather-skill": {
- "command": "hkweather",
- "args": ["mcp"]
- }
- }
- }
- ```
- If the client does not inherit `PATH`, use the absolute installed path.
- ### Docker and Apple container
- ```bash
- docker build -t hkweather .
- docker run --rm hkweather --help
- docker run --rm -i hkweather mcp # stdio MCP
- docker compose run --rm stdio # same, through Compose
- ```
- Apple's `container` runtime uses the same OCI image:
- ```bash
- container build -t hkweather .
- container run --rm hkweather --help
- container run --rm -i hkweather mcp
- ```
- The runtime image contains the release binary and CA certificates, runs as a
- non-root user, and defaults to `--help` so a bare `docker run` is harmless.
- ### Cloudflare and WASM
- There is no Worker or WASM deployment. The binary talks directly to upstream
- HTTP APIs over TLS and uses a Tokio runtime; packaging it as a stdio server is
- the supported integration. A Worker would need a separate HTTP/JavaScript
- adapter and is out of scope for this repo.
- ### Releases
- Pushing a `v*` tag runs the release workflow, which checks the tag against
- `Cargo.toml` and `CHANGELOG.md`, builds four targets, smoke-tests native
- binaries and publishes:
- - `hkweather-<tag>-<target>.tar.gz` for macOS and static Linux
- - `SHA256SUMS` covering every tarball
- `scripts/install.sh` downloads the latest release, verifies its checksum and
- falls back to `cargo build --release --locked` when no release is available.
- `just tag X.Y.Z` creates the annotated tag locally; `just release X.Y.Z` tags
- and pushes to trigger the workflow.
- ## Development
- ```bash
- just # fmt check, clippy with -D warnings, tests
- just skill-check # validate SKILL.md and shell syntax
- just container # build the image and print CLI help
- cargo test --all --locked
- cargo clippy --all-targets --locked -- -D warnings
- cargo fmt --all -- --check
- ```
- `rust-toolchain.toml` pins the stable toolchain with `rustfmt` and
- `clippy`, so `rustup` sets contributors up automatically. `just doc`
- builds the API documentation. See `CONTRIBUTING.md` for the full check
- list and the signed-commit requirement.
- CI runs the same checks. Dependabot proposes weekly Cargo and GitHub Actions
- updates, and the audit workflow checks the lockfile against the RustSec
- advisory database.
- ## Licence
- MIT. See [LICENSE](LICENSE). HKO data remains subject to the Observatory's
- terms of use.
Ratings and comments
Sign in to rate this skill.
Sign inFree to use. If it’s helped, pass it on.