Skip to content
Back to search

hongkong-events-skill

Hong Kong LCSD cultural programmes — concerts, theatre, dance, exhibitions, film, workshops and free entertainment in LCSD venues. Use for questions about what's on in Hong Kong, event dates, venues, ticket prices, or upcoming cultural performances.

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

HTML

<a href="/listings/hongkong-ai-labs--hongkong-events-skill"><img src="/api/listings/hongkong-ai-labs--hongkong-events-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-events-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-events-skill/main/scripts/install.sh | sh

**From source** — Rust 1.89 or newer:

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

Verify:

$ hkevents --version

`hkevents update` detects whether the binary came from cargo, the release installer, a source checkout or Homebrew, and updates with that same method. `hkevents 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 · 157 lines · 1 finding marked
  1. ---
  2. name: hongkong-events-skill
  3. description: Hong Kong LCSD cultural programmes — concerts, theatre, dance, exhibitions, film, workshops and free entertainment in LCSD venues. Use for questions about what's on in Hong Kong, event dates, venues, ticket prices, or upcoming cultural performances.
  4. license: MIT
  5. ---
  6. # Hong Kong cultural events
  7. `hkevents` is a Rust CLI and MCP server for the Leisure and Cultural Services
  8. Department's Cultural Programmes open data. It needs no API key and no account.
  9. It is an independent, unofficial project.
  10. Use it when the user asks about:
  11. - what's on in Hong Kong this week, this month or on a date
  12. - a concert, play, dance, opera, film, exhibition or workshop
  13. - events at a venue such as the Cultural Centre, City Hall, a town hall or a
  14. public library
  15. - free cultural programmes
  16. - ticket price, age limit, presenter, enquiry number or the organiser's link
  17. The feed covers **current and forthcoming LCSD cultural programmes**. It is
  18. not a complete list of every event in Hong Kong: commercial concerts, private
  19. gallery shows, district festivals and venue-hire events may be absent.
  20. ## Before first use
  21. ```console
  22. $ bash scripts/ensure-binary.sh
  23. /Users/you/.local/bin/hkevents
  24. ```
  25. Use the printed path:
  26. ```bash
  27. BIN="$(bash scripts/ensure-binary.sh)"
  28. ```
  29. It checks `$HKEVENTS_BIN`, `hkevents` on `PATH`, `scripts/install.sh`, then
  30. `cargo build --release --locked` in the repo root.
  31. ### Install the binary directly
  32. `npx skills add` installs the skill files. If the binary is missing, install it
  33. with the release installer or cargo:
  34. ```bash
  35. curl -fsSL https://raw.githubusercontent.com/hongkong-ai-labs/hongkong-events-skill/main/scripts/install.sh | sh
    • Note: Pipes a downloaded script directly into a shell (curl | sh / wget | bash)
    • Line 48 on GitHub
  36. # or
  37. cargo install --git https://github.com/hongkong-ai-labs/hongkong-events-skill --locked
  38. ```
  39. Register it with any MCP client:
  40. ```bash
  41. npx add-mcp "$(command -v hkevents) mcp" --name hongkong-events -a claude-code -a codex -a cursor -y
  42. claude mcp add hongkong-events -- hkevents mcp
  43. codex mcp add hongkong-events -- hkevents mcp
  44. ```
  45. `add-mcp` detects the client configuration files in the current project; add
  46. `-g` for a global install. `$(command -v hkevents)` keeps the entry correct
  47. when the binary is on `PATH`; substitute an absolute path if your client does
  48. not inherit the shell `PATH`.
  49. ## CLI
  50. ```bash
  51. $BIN list # next 30 days, first 30
  52. $BIN list --days 7 --limit 10 # this week
  53. $BIN list --from 2026-12-01 --days 31
  54. $BIN list --venue "Cultural Centre"
  55. $BIN list --query jazz
  56. $BIN list --free
  57. $BIN list --json
  58. $BIN show 188273 # full details
  59. $BIN venues --query "Town Hall" # venue ids and coordinates
  60. $BIN mcp
  61. $BIN update --check
  62. ```
  63. Dates are Hong Kong dates. `--days 0` means no upper date bound; `--limit 0`
  64. means no row limit. `--query` searches the English and Chinese titles, the
  65. description and the presenter.
  66. ### What a listing contains
  67. | Field | Meaning |
  68. | --- | --- |
  69. | `next_date` | First performance on or after today |
  70. | `dates` | Every performance date in the current run |
  71. | `date_text` | Original LCSD date text, including times |
  72. | `venue` | Venue name resolved from the venue id |
  73. | `price` | Published price text, or `Free` / `Free Activities` |
  74. | `category`, `subcategory` | Raw LCSD category codes |
  75. | `duration` | Running time or duration text |
  76. | `age_limit` | Age guidance |
  77. | `presenter` | Presenter or organiser |
  78. | `enquiry` | Enquiry phone number |
  79. | `url` | Presenter or ticketing link |
  80. | `description` | Full English description |
  81. `category` is the raw code (`inc4`, etc.) because LCSD does not publish a
  82. stable label table in the feed. Do not guess a human category from the code;
  83. use the title, description and venue instead.
  84. ## MCP
  85. ```json
  86. {
  87. "mcpServers": {
  88. "hongkong-events": {
  89. "command": "/absolute/path/to/hkevents",
  90. "args": ["mcp"]
  91. }
  92. }
  93. }
  94. ```
  95. Tools:
  96. | Tool | Arguments |
  97. | --- | --- |
  98. | `list_hk_events` | `{ from?, days?, venue?, query?, free?, limit? }` |
  99. | `get_hk_event` | `{ id }` |
  100. | `list_event_venues` | `{ query? }` |
  101. ## Answering patterns
  102. - "What's on this weekend?" → `list --days 7 --limit 20`; mention the date,
  103. venue and price, not just the title.
  104. - "Anything free?" → `list --free`.
  105. - "Is there a concert at the Cultural Centre?" → `list --venue "Cultural
  106. Centre" --query concert`.
  107. - "How much are tickets?" → quote `price` exactly; it can be a range or a list
  108. of tiers, and does not include booking fees.
  109. - "Tell me more about event N" → `show N`.
  110. - "Where is that venue?" → `venues --query "<name>"` for the coordinates.
  111. ## Cautions
  112. - Dates and line-ups change. The feed is a snapshot; a cancelled or sold-out
  113. performance may still appear.
  114. - A programme with `next_date: null` has no performance today or later in the
  115. current published run. It can still be in the feed as a past or undated item.
  116. - Ticket links point to the presenter or URBTIX. This tool does not check
  117. availability, sell tickets or hold seats.
  118. - `price` is published text, not a live inventory.
  119. - The list is LCSD programmes, not all Hong Kong events.
  120. - Not an official LCSD channel. Check the venue or URBTIX for confirmation.
  121. ## Source
  122. `https://www.lcsd.gov.hk/datagovhk/event/events.xml`,
  123. `eventDates.xml` and `venues.xml`, published under DATA.GOV.HK. Responses are
  124. cached for 10 minutes in-process.
README.md · README · 191 lines · 1 finding marked
  1. # hkevents
  2. Hong Kong LCSD cultural programmes as a Rust CLI and MCP server.
  3. Reads the official, keyless LCSD Cultural Programmes dataset: programme
  4. details, exact performance dates and venue names.
  5. ## Install
  6. **Agent skill** — installs `SKILL.md` and the binary bootstrap script:
  7. ```bash
  8. npx skills add hongkong-ai-labs/hongkong-events-skill
  9. npx skills update # refresh the installed skill later
  10. ```
  11. **Prebuilt binary** — macOS (Intel or Apple silicon) and Linux (x86_64 or
  12. aarch64, static musl), checksum-verified, into `~/.local/bin`:
  13. ```bash
  14. curl -fsSL https://raw.githubusercontent.com/hongkong-ai-labs/hongkong-events-skill/main/scripts/install.sh | sh
    • Note: Pipes a downloaded script directly into a shell (curl | sh / wget | bash)
    • Line 21 on GitHub
  15. ```
  16. **From source** — Rust 1.89 or newer:
  17. ```bash
  18. git clone https://github.com/hongkong-ai-labs/hongkong-events-skill
  19. cd hongkong-events-skill
  20. cargo install --path . --locked
  21. # or directly from GitHub:
  22. cargo install --git https://github.com/hongkong-ai-labs/hongkong-events-skill --locked
  23. # or: cargo build --release --locked # target/release/hkevents
  24. ```
  25. Verify:
  26. ```console
  27. $ hkevents --version
  28. ```
  29. `hkevents update` detects whether the binary came from cargo, the release
  30. installer, a source checkout or Homebrew, and updates with that same
  31. method. `hkevents update --check` only reports.
  32. ## CLI
  33. ```bash
  34. hkevents list
  35. hkevents list --days 7 --limit 10
  36. hkevents list --from 2026-12-01 --days 31
  37. hkevents list --venue "Cultural Centre" --query concert
  38. hkevents list --free
  39. hkevents list --json
  40. hkevents show 188273
  41. hkevents venues --query "Town Hall"
  42. hkevents mcp
  43. hkevents update --check
  44. ```
  45. ## MCP
  46. ```json
  47. {
  48. "mcpServers": {
  49. "hongkong-events": { "command": "hkevents", "args": ["mcp"] }
  50. }
  51. }
  52. ```
  53. Register it with any MCP client:
  54. ```bash
  55. npx add-mcp "$(command -v hkevents) mcp" --name hongkong-events -a claude-code -a codex -a cursor -y
  56. claude mcp add hongkong-events -- hkevents mcp
  57. codex mcp add hongkong-events -- hkevents mcp
  58. ```
  59. `add-mcp` detects the client configuration files in the current project; add
  60. `-g` for a global install. `$(command -v hkevents)` keeps the entry correct
  61. when the binary is on `PATH`; substitute an absolute path if your client does
  62. not inherit the shell `PATH`.
  63. Tools: `list_hk_events`, `get_hk_event`, `list_event_venues`.
  64. ## Data
  65. - `https://www.lcsd.gov.hk/datagovhk/event/events.xml`
  66. - `https://www.lcsd.gov.hk/datagovhk/event/eventDates.xml`
  67. - `https://www.lcsd.gov.hk/datagovhk/event/venues.xml`
  68. Coverage is current and forthcoming LCSD cultural programmes, not every event
  69. in Hong Kong. Dates, prices and line-ups can change; check URBTIX or the venue.
  70. ## Run modes and deployment
  71. | Mode | Start with | Use for |
  72. | --- | --- | --- |
  73. | CLI | `hkevents <command>` | Interactive use and shell scripts |
  74. | JSON | `<command>` with `--json` | `jq`, automation, other programs |
  75. | MCP stdio | `hkevents mcp` | Desktop and CLI MCP clients |
  76. | Container | `docker run --rm -i hkevents mcp` | No local Rust toolchain |
  77. ### MCP and authentication
  78. This server is **stdio-only**: the client launches the process and speaks MCP
  79. over stdin/stdout. There is no listening port, so there is no network
  80. authentication layer and no API-key setting. Optional API keys in this project
  81. family apply only to servers that expose an HTTP transport. Keep the process
  82. local and let the MCP client manage it.
  83. Typical client entry:
  84. ```json
  85. {
  86. "mcpServers": {
  87. "hongkong-events-skill": {
  88. "command": "hkevents",
  89. "args": ["mcp"]
  90. }
  91. }
  92. }
  93. ```
  94. If the client does not inherit `PATH`, use the absolute installed path.
  95. ### Docker and Apple container
  96. ```bash
  97. docker build -t hkevents .
  98. docker run --rm hkevents --help
  99. docker run --rm -i hkevents mcp # stdio MCP
  100. docker compose run --rm stdio # same, through Compose
  101. ```
  102. Apple's `container` runtime uses the same OCI image:
  103. ```bash
  104. container build -t hkevents .
  105. container run --rm hkevents --help
  106. container run --rm -i hkevents mcp
  107. ```
  108. The runtime image contains the release binary and CA certificates, runs as a
  109. non-root user, and defaults to `--help` so a bare `docker run` is harmless.
  110. ### Cloudflare and WASM
  111. There is no Worker or WASM deployment. The binary talks directly to upstream
  112. HTTP APIs over TLS and uses a Tokio runtime; packaging it as a stdio server is
  113. the supported integration. A Worker would need a separate HTTP/JavaScript
  114. adapter and is out of scope for this repo.
  115. ### Releases
  116. Pushing a `v*` tag runs the release workflow, which checks the tag against
  117. `Cargo.toml` and `CHANGELOG.md`, builds four targets, smoke-tests native
  118. binaries and publishes:
  119. - `hkevents-<tag>-<target>.tar.gz` for macOS and static Linux
  120. - `SHA256SUMS` covering every tarball
  121. `scripts/install.sh` downloads the latest release, verifies its checksum and
  122. falls back to `cargo build --release --locked` when no release is available.
  123. `just tag X.Y.Z` creates the annotated tag locally; `just release X.Y.Z` tags
  124. and pushes to trigger the workflow.
  125. ## Development
  126. ```bash
  127. just # fmt check, clippy with -D warnings, tests
  128. just skill-check # validate SKILL.md and shell syntax
  129. just container # build the image and print CLI help
  130. cargo test --all --locked
  131. cargo clippy --all-targets --locked -- -D warnings
  132. cargo fmt --all -- --check
  133. ```
  134. `rust-toolchain.toml` pins the stable toolchain with `rustfmt` and
  135. `clippy`, so `rustup` sets contributors up automatically. `just doc`
  136. builds the API documentation. See `CONTRIBUTING.md` for the full check
  137. list and the signed-commit requirement.
  138. CI runs the same checks. Dependabot proposes weekly Cargo and GitHub Actions
  139. updates, and the audit workflow checks the lockfile against the RustSec
  140. advisory database.
  141. ## Licence
  142. MIT. Event data remains subject to DATA.GOV.HK and LCSD terms.

Ratings and comments

Sign in to rate this skill.

Sign in

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