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
Markdown
[](/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
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
- ---
- name: hongkong-events-skill
- 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.
- license: MIT
- ---
- # Hong Kong cultural events
- `hkevents` is a Rust CLI and MCP server for the Leisure and Cultural Services
- Department's Cultural Programmes open data. It needs no API key and no account.
- It is an independent, unofficial project.
- Use it when the user asks about:
- - what's on in Hong Kong this week, this month or on a date
- - a concert, play, dance, opera, film, exhibition or workshop
- - events at a venue such as the Cultural Centre, City Hall, a town hall or a
- public library
- - free cultural programmes
- - ticket price, age limit, presenter, enquiry number or the organiser's link
- The feed covers **current and forthcoming LCSD cultural programmes**. It is
- not a complete list of every event in Hong Kong: commercial concerts, private
- gallery shows, district festivals and venue-hire events may be absent.
- ## Before first use
- ```console
- $ bash scripts/ensure-binary.sh
- /Users/you/.local/bin/hkevents
- ```
- Use the printed path:
- ```bash
- BIN="$(bash scripts/ensure-binary.sh)"
- ```
- It checks `$HKEVENTS_BIN`, `hkevents` 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-events-skill/main/scripts/install.sh | sh
- Note: Pipes a downloaded script directly into a shell (curl | sh / wget | bash)
- Line 48 on GitHub
- # or
- cargo install --git https://github.com/hongkong-ai-labs/hongkong-events-skill --locked
- ```
- Register it with any MCP client:
- ```bash
- npx add-mcp "$(command -v hkevents) mcp" --name hongkong-events -a claude-code -a codex -a cursor -y
- claude mcp add hongkong-events -- hkevents mcp
- codex mcp add hongkong-events -- hkevents mcp
- ```
- `add-mcp` detects the client configuration files in the current project; add
- `-g` for a global install. `$(command -v hkevents)` keeps the entry correct
- when the binary is on `PATH`; substitute an absolute path if your client does
- not inherit the shell `PATH`.
- ## CLI
- ```bash
- $BIN list # next 30 days, first 30
- $BIN list --days 7 --limit 10 # this week
- $BIN list --from 2026-12-01 --days 31
- $BIN list --venue "Cultural Centre"
- $BIN list --query jazz
- $BIN list --free
- $BIN list --json
- $BIN show 188273 # full details
- $BIN venues --query "Town Hall" # venue ids and coordinates
- $BIN mcp
- $BIN update --check
- ```
- Dates are Hong Kong dates. `--days 0` means no upper date bound; `--limit 0`
- means no row limit. `--query` searches the English and Chinese titles, the
- description and the presenter.
- ### What a listing contains
- | Field | Meaning |
- | --- | --- |
- | `next_date` | First performance on or after today |
- | `dates` | Every performance date in the current run |
- | `date_text` | Original LCSD date text, including times |
- | `venue` | Venue name resolved from the venue id |
- | `price` | Published price text, or `Free` / `Free Activities` |
- | `category`, `subcategory` | Raw LCSD category codes |
- | `duration` | Running time or duration text |
- | `age_limit` | Age guidance |
- | `presenter` | Presenter or organiser |
- | `enquiry` | Enquiry phone number |
- | `url` | Presenter or ticketing link |
- | `description` | Full English description |
- `category` is the raw code (`inc4`, etc.) because LCSD does not publish a
- stable label table in the feed. Do not guess a human category from the code;
- use the title, description and venue instead.
- ## MCP
- ```json
- {
- "mcpServers": {
- "hongkong-events": {
- "command": "/absolute/path/to/hkevents",
- "args": ["mcp"]
- }
- }
- }
- ```
- Tools:
- | Tool | Arguments |
- | --- | --- |
- | `list_hk_events` | `{ from?, days?, venue?, query?, free?, limit? }` |
- | `get_hk_event` | `{ id }` |
- | `list_event_venues` | `{ query? }` |
- ## Answering patterns
- - "What's on this weekend?" → `list --days 7 --limit 20`; mention the date,
- venue and price, not just the title.
- - "Anything free?" → `list --free`.
- - "Is there a concert at the Cultural Centre?" → `list --venue "Cultural
- Centre" --query concert`.
- - "How much are tickets?" → quote `price` exactly; it can be a range or a list
- of tiers, and does not include booking fees.
- - "Tell me more about event N" → `show N`.
- - "Where is that venue?" → `venues --query "<name>"` for the coordinates.
- ## Cautions
- - Dates and line-ups change. The feed is a snapshot; a cancelled or sold-out
- performance may still appear.
- - A programme with `next_date: null` has no performance today or later in the
- current published run. It can still be in the feed as a past or undated item.
- - Ticket links point to the presenter or URBTIX. This tool does not check
- availability, sell tickets or hold seats.
- - `price` is published text, not a live inventory.
- - The list is LCSD programmes, not all Hong Kong events.
- - Not an official LCSD channel. Check the venue or URBTIX for confirmation.
- ## Source
- `https://www.lcsd.gov.hk/datagovhk/event/events.xml`,
- `eventDates.xml` and `venues.xml`, published under DATA.GOV.HK. Responses are
- cached for 10 minutes in-process.
README.md · README · 191 lines · 1 finding marked
- # hkevents
- Hong Kong LCSD cultural programmes as a Rust CLI and MCP server.
- Reads the official, keyless LCSD Cultural Programmes dataset: programme
- details, exact performance dates and venue names.
- ## Install
- **Agent skill** — installs `SKILL.md` and the binary bootstrap script:
- ```bash
- 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`:
- ```bash
- 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
- ```
- **From source** — Rust 1.89 or newer:
- ```bash
- 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:
- ```console
- $ 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.
- ## CLI
- ```bash
- hkevents list
- hkevents list --days 7 --limit 10
- hkevents list --from 2026-12-01 --days 31
- hkevents list --venue "Cultural Centre" --query concert
- hkevents list --free
- hkevents list --json
- hkevents show 188273
- hkevents venues --query "Town Hall"
- hkevents mcp
- hkevents update --check
- ```
- ## MCP
- ```json
- {
- "mcpServers": {
- "hongkong-events": { "command": "hkevents", "args": ["mcp"] }
- }
- }
- ```
- Register it with any MCP client:
- ```bash
- npx add-mcp "$(command -v hkevents) mcp" --name hongkong-events -a claude-code -a codex -a cursor -y
- claude mcp add hongkong-events -- hkevents mcp
- codex mcp add hongkong-events -- hkevents mcp
- ```
- `add-mcp` detects the client configuration files in the current project; add
- `-g` for a global install. `$(command -v hkevents)` keeps the entry correct
- when the binary is on `PATH`; substitute an absolute path if your client does
- not inherit the shell `PATH`.
- Tools: `list_hk_events`, `get_hk_event`, `list_event_venues`.
- ## Data
- - `https://www.lcsd.gov.hk/datagovhk/event/events.xml`
- - `https://www.lcsd.gov.hk/datagovhk/event/eventDates.xml`
- - `https://www.lcsd.gov.hk/datagovhk/event/venues.xml`
- Coverage is current and forthcoming LCSD cultural programmes, not every event
- in Hong Kong. Dates, prices and line-ups can change; check URBTIX or the venue.
- ## Run modes and deployment
- | Mode | Start with | Use for |
- | --- | --- | --- |
- | CLI | `hkevents <command>` | Interactive use and shell scripts |
- | JSON | `<command>` with `--json` | `jq`, automation, other programs |
- | MCP stdio | `hkevents mcp` | Desktop and CLI MCP clients |
- | Container | `docker run --rm -i hkevents 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-events-skill": {
- "command": "hkevents",
- "args": ["mcp"]
- }
- }
- }
- ```
- If the client does not inherit `PATH`, use the absolute installed path.
- ### Docker and Apple container
- ```bash
- docker build -t hkevents .
- docker run --rm hkevents --help
- docker run --rm -i hkevents mcp # stdio MCP
- docker compose run --rm stdio # same, through Compose
- ```
- Apple's `container` runtime uses the same OCI image:
- ```bash
- container build -t hkevents .
- container run --rm hkevents --help
- container run --rm -i hkevents 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:
- - `hkevents-<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. Event data remains subject to DATA.GOV.HK and LCSD terms.
Ratings and comments
Sign in to rate this skill.
Sign inFree to use. If it’s helped, pass it on.