Skip to content
Back to search

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
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/hongkong-ai-labs--hongkong-weather-skill/badge.svg)](/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

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

These steps run a script from the network that findsafeskills does not scan.

**Agent skill** — installs `SKILL.md` and the binary bootstrap script:

npx skills add hongkong-ai-labs/hongkong-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
  1. ---
  2. name: hongkong-weather-skill
  3. 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.
  4. license: MIT
  5. ---
  6. # Hong Kong weather (HKO)
  7. `hkweather` is a Rust CLI and MCP server for the Hong Kong Observatory's
  8. public open-data API. It needs no API key and no account. It is an independent,
  9. unofficial project and is not affiliated with HKO.
  10. Use it when the user asks about:
  11. - current temperature, humidity, UV index or rainfall in Hong Kong
  12. - today's local forecast, the outlook, or the nine-day forecast
  13. - active weather warnings: tropical cyclones, rainstorms, thunderstorm, fire
  14. danger, cold weather, very hot weather, strong monsoon, landslip, flooding
  15. - rainfall by district, or how wet a month or year has been
  16. - whether a typhoon signal or rainstorm warning is in force
  17. ## Before first use
  18. Run `scripts/ensure-binary.sh` from the skill directory:
  19. ```console
  20. $ bash scripts/ensure-binary.sh
  21. /Users/you/.local/bin/hkweather
  22. ```
  23. It prints the absolute path of a working binary. Use that path for every
  24. command, or capture it once:
  25. ```bash
  26. BIN="$(bash scripts/ensure-binary.sh)"
  27. ```
  28. It checks, in order: `$HKWEATHER_BIN`, `hkweather` on `PATH`,
  29. `scripts/install.sh`, then `cargo build --release --locked` in the repo root.
  30. ### Install the binary directly
  31. `npx skills add` installs the skill files. If the binary is missing, install it
  32. with the release installer or cargo:
  33. ```bash
  34. 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
  35. # or
  36. cargo install --git https://github.com/hongkong-ai-labs/hongkong-weather-skill --locked
  37. ```
  38. Register it with any MCP client:
  39. ```bash
  40. npx add-mcp "$(command -v hkweather) mcp" --name hongkong-weather -a claude-code -a codex -a cursor -y
  41. claude mcp add hongkong-weather -- hkweather mcp
  42. codex mcp add hongkong-weather -- hkweather mcp
  43. ```
  44. `add-mcp` detects the client configuration files in the current project; add
  45. `-g` for a global install. `$(command -v hkweather)` keeps the entry correct
  46. when the binary is on `PATH`; substitute an absolute path if your client does
  47. not inherit the shell `PATH`.
  48. ## CLI
  49. Prefer `--json` when you need to parse. Tables are for humans. All timestamps
  50. are Hong Kong time (UTC+8).
  51. ```bash
  52. $BIN current --json # all current readings
  53. $BIN current --place "Sha Tin" --json # one place
  54. $BIN forecast --json # nine-day forecast
  55. $BIN forecast --days 3 --json # first three days
  56. $BIN warnings --json # active warnings
  57. $BIN warnings --all --json # include cancelled warnings
  58. $BIN local --json # local forecast + outlook
  59. $BIN rain --json # district rainfall since midnight
  60. $BIN uv --json # UV index by station
  61. $BIN all --json # everything in one object
  62. $BIN update --check
  63. ```
  64. `--lang tc` or `--lang sc` returns HKO's Traditional or Simplified Chinese
  65. text. Field names stay English.
  66. ### What the JSON contains
  67. `current`:
  68. | Field | Meaning |
  69. | --- | --- |
  70. | `update_time` | HKO publication time, RFC 3339 with `+08:00` |
  71. | `temperature` | `[{place, value, unit}]` |
  72. | `humidity` | `[{place, value, unit}]` |
  73. | `rainfall` | `[{place, max, main, unit}]`, millimetres since midnight |
  74. | `uv_index` | `[{place, value, desc}]` |
  75. | `warnings` | HKO warning headline strings (`[]` when none) |
  76. | `rainfall_totals` | midnight-to-noon, last month, year to date (mm) |
  77. `forecast.days[]` has `forecastDate` (`YYYYMMDD`), `week`, `forecastWeather`,
  78. `forecastWind`, `forecastMaxtemp` / `forecastMintemp`
  79. (`{value, unit}`), `forecastMaxrh` / `forecastMinrh`, `ForecastIcon`, and
  80. `PSR` — the probability of significant rain (`Low`, `Medium`, `High`).
  81. `warnings` are objects with `code`, `name`, `cancelled`, `subtype`,
  82. `update_time`, `expiry_time`, and `contents`. A code such as `WTCSGNL` is the
  83. tropical cyclone warning signal statement; the signal number is in the
  84. `contents` text, so quote that text rather than guessing a number.
  85. ## MCP
  86. ```bash
  87. $BIN mcp
  88. ```
  89. ```json
  90. {
  91. "mcpServers": {
  92. "hongkong-weather": {
  93. "command": "/absolute/path/to/hkweather",
  94. "args": ["mcp"]
  95. }
  96. }
  97. }
  98. ```
  99. Tools:
  100. | Tool | Purpose |
  101. | --- | --- |
  102. | `hko_current_weather` | Current readings, optional `station` substring |
  103. | `hko_forecast` | Nine-day forecast, optional `days` |
  104. | `hko_warnings` | Active warnings, optional `include_cancelled` |
  105. | `hko_local_forecast` | Local forecast and outlook |
  106. | `hko_rainfall` | District rainfall since midnight |
  107. All tools accept `lang` (`en`, `tc`, `sc`).
  108. ## Answering safely
  109. - Say "HKO says" and give the publication time. HKO updates readings and
  110. forecasts on its own schedule; a cached answer can be a few minutes old.
  111. - Warnings are safety information. Quote the warning text and signal number.
  112. Do not downgrade, summarise away, or predict when a warning will be lifted.
  113. - The nine-day forecast is a forecast, not a guarantee. Give the date range and
  114. the rain probability band rather than a single certainty.
  115. - "Low" rain probability does not mean no rain; scattered showers still happen.
  116. - UV index is station-specific and is not a sunscreen recommendation.
  117. - Rainfall is since midnight in millimetres, not an hourly rate.
  118. - This is an independent client of HKO open data. It is not an official HKO
  119. channel. For decisions involving safety, ferries, flights, or outdoor work,
  120. check the HKO website or app directly.
  121. ## Source
  122. HKO open data, `https://data.weather.gov.hk/weatherAPI/opendata/weather.php`,
  123. with `dataType=rhrread|fnd|flw|warninginfo`. No key is required. Responses are
  124. cached for 60 seconds in-process (`--cache-ttl 0` disables).
README.md · README · 213 lines · 1 finding marked
  1. # hkweather
  2. Hong Kong Observatory weather data as a Rust CLI and an MCP server.
  3. `hkweather` reads HKO's public, keyless open data and exposes current
  4. readings, district rainfall, UV, active warnings, the local forecast and the
  5. nine-day forecast as tables, JSON, or MCP tools.
  6. It is an independent, unofficial project, not affiliated with the Hong Kong
  7. Observatory.
  8. ## Install
  9. **Agent skill** — installs `SKILL.md` and the binary bootstrap script:
  10. ```bash
  11. npx skills add hongkong-ai-labs/hongkong-weather-skill
  12. npx skills update # refresh the installed skill later
  13. ```
  14. **Prebuilt binary** — macOS (Intel or Apple silicon) and Linux (x86_64 or
  15. aarch64, static musl), checksum-verified, into `~/.local/bin`:
  16. ```bash
  17. 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
  18. ```
  19. **From source** — Rust 1.89 or newer:
  20. ```bash
  21. git clone https://github.com/hongkong-ai-labs/hongkong-weather-skill
  22. cd hongkong-weather-skill
  23. cargo install --path . --locked
  24. # or directly from GitHub:
  25. cargo install --git https://github.com/hongkong-ai-labs/hongkong-weather-skill --locked
  26. # or: cargo build --release --locked # target/release/hkweather
  27. ```
  28. Verify:
  29. ```console
  30. $ hkweather --version
  31. ```
  32. `hkweather update` detects whether the binary came from cargo, the release
  33. installer, a source checkout or Homebrew, and updates with that same
  34. method. `hkweather update --check` only reports.
  35. ## CLI
  36. ```bash
  37. hkweather current # all current readings
  38. hkweather current --place "Sha Tin" # one place
  39. hkweather forecast --days 3 # first three forecast days
  40. hkweather warnings # active warnings
  41. hkweather warnings --all # include cancelled
  42. hkweather local # local forecast + outlook
  43. hkweather rain # district rainfall
  44. hkweather uv # UV index
  45. hkweather all # everything
  46. hkweather --json current # machine-readable
  47. hkweather --lang tc forecast # Traditional Chinese HKO text
  48. hkweather mcp # MCP over stdio
  49. hkweather update --check
  50. ```
  51. ## MCP
  52. ```json
  53. {
  54. "mcpServers": {
  55. "hongkong-weather": {
  56. "command": "hkweather",
  57. "args": ["mcp"]
  58. }
  59. }
  60. }
  61. ```
  62. Register it with any MCP client:
  63. ```bash
  64. npx add-mcp "$(command -v hkweather) mcp" --name hongkong-weather -a claude-code -a codex -a cursor -y
  65. claude mcp add hongkong-weather -- hkweather mcp
  66. codex mcp add hongkong-weather -- hkweather mcp
  67. ```
  68. `add-mcp` detects the client configuration files in the current project; add
  69. `-g` for a global install. `$(command -v hkweather)` keeps the entry correct
  70. when the binary is on `PATH`; substitute an absolute path if your client does
  71. not inherit the shell `PATH`.
  72. Tools: `hko_current_weather`, `hko_forecast`, `hko_warnings`,
  73. `hko_local_forecast`, `hko_rainfall`.
  74. ## Data
  75. | Dataset | HKO `dataType` |
  76. | --- | --- |
  77. | Current readings | `rhrread` |
  78. | Nine-day forecast | `fnd` |
  79. | Local forecast | `flw` |
  80. | Warnings | `warninginfo` |
  81. Source: `https://data.weather.gov.hk/weatherAPI/opendata/weather.php`.
  82. No API key. Responses are cached for 60 seconds (`--cache-ttl 0` disables).
  83. ## Limits
  84. HKO data is published for general information. Warnings and forecasts can
  85. change; always check HKO directly for safety-critical decisions. The API does
  86. not provide a per-minute nowcast, lightning location, or official district
  87. rainfall forecast.
  88. ## Run modes and deployment
  89. | Mode | Start with | Use for |
  90. | --- | --- | --- |
  91. | CLI | `hkweather <command>` | Interactive use and shell scripts |
  92. | JSON | `<command>` with `--json` | `jq`, automation, other programs |
  93. | MCP stdio | `hkweather mcp` | Desktop and CLI MCP clients |
  94. | Container | `docker run --rm -i hkweather mcp` | No local Rust toolchain |
  95. ### MCP and authentication
  96. This server is **stdio-only**: the client launches the process and speaks MCP
  97. over stdin/stdout. There is no listening port, so there is no network
  98. authentication layer and no API-key setting. Optional API keys in this project
  99. family apply only to servers that expose an HTTP transport. Keep the process
  100. local and let the MCP client manage it.
  101. Typical client entry:
  102. ```json
  103. {
  104. "mcpServers": {
  105. "hongkong-weather-skill": {
  106. "command": "hkweather",
  107. "args": ["mcp"]
  108. }
  109. }
  110. }
  111. ```
  112. If the client does not inherit `PATH`, use the absolute installed path.
  113. ### Docker and Apple container
  114. ```bash
  115. docker build -t hkweather .
  116. docker run --rm hkweather --help
  117. docker run --rm -i hkweather mcp # stdio MCP
  118. docker compose run --rm stdio # same, through Compose
  119. ```
  120. Apple's `container` runtime uses the same OCI image:
  121. ```bash
  122. container build -t hkweather .
  123. container run --rm hkweather --help
  124. container run --rm -i hkweather mcp
  125. ```
  126. The runtime image contains the release binary and CA certificates, runs as a
  127. non-root user, and defaults to `--help` so a bare `docker run` is harmless.
  128. ### Cloudflare and WASM
  129. There is no Worker or WASM deployment. The binary talks directly to upstream
  130. HTTP APIs over TLS and uses a Tokio runtime; packaging it as a stdio server is
  131. the supported integration. A Worker would need a separate HTTP/JavaScript
  132. adapter and is out of scope for this repo.
  133. ### Releases
  134. Pushing a `v*` tag runs the release workflow, which checks the tag against
  135. `Cargo.toml` and `CHANGELOG.md`, builds four targets, smoke-tests native
  136. binaries and publishes:
  137. - `hkweather-<tag>-<target>.tar.gz` for macOS and static Linux
  138. - `SHA256SUMS` covering every tarball
  139. `scripts/install.sh` downloads the latest release, verifies its checksum and
  140. falls back to `cargo build --release --locked` when no release is available.
  141. `just tag X.Y.Z` creates the annotated tag locally; `just release X.Y.Z` tags
  142. and pushes to trigger the workflow.
  143. ## Development
  144. ```bash
  145. just # fmt check, clippy with -D warnings, tests
  146. just skill-check # validate SKILL.md and shell syntax
  147. just container # build the image and print CLI help
  148. cargo test --all --locked
  149. cargo clippy --all-targets --locked -- -D warnings
  150. cargo fmt --all -- --check
  151. ```
  152. `rust-toolchain.toml` pins the stable toolchain with `rustfmt` and
  153. `clippy`, so `rustup` sets contributors up automatically. `just doc`
  154. builds the API documentation. See `CONTRIBUTING.md` for the full check
  155. list and the signed-commit requirement.
  156. CI runs the same checks. Dependabot proposes weekly Cargo and GitHub Actions
  157. updates, and the audit workflow checks the lockfile against the RustSec
  158. advisory database.
  159. ## Licence
  160. MIT. See [LICENSE](LICENSE). HKO data remains subject to the Observatory's
  161. terms of use.

Ratings and comments

Sign in to rate this skill.

Sign in

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