@kaminari-ad/mcp 0.2.0 → 0.2.2

package/CHANGELOG.md

@@ -7,6 +7,96 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.2.2] - 2026-05-20
+
+Minor release — adds one-click install paths for Cursor and Claude
+Desktop. No tool surface change, no breaking API behaviour change.
+
+### Added
+
+- **Claude Desktop `.mcpb` extension bundle.** Each tag release now
+  builds a single-file `kaminari-ad-mcp.mcpb` (via the new
+  `tsup.mcpb.config.ts` + `mcpb pack`) and uploads it to the GitHub
+  Release. Stable download URL:
+  <https://github.com/kaminari-ad/mcp/releases/latest/download/kaminari-ad-mcp.mcpb>.
+  Double-click installs into Claude Desktop with a config form for
+  the API key and a ToS-acceptance checkbox.
+- **Cursor one-click install badge.** README and the Kaminari Ad
+  marketing site link the official Cursor "Install in Cursor" badge
+  to a trampoline page (`https://kaminari.ad/mcp/install`) that
+  redirects to the `cursor://anysphere.cursor-deeplink/mcp/install`
+  URL with the npx-based stdio config pre-encoded.
+- **`server.json`** for [registry.modelcontextprotocol.io][mcp-reg]
+  listing. Surface (npm stdio package, env vars) mirrors what the
+  README documents.
+
+[mcp-reg]: https://registry.modelcontextprotocol.io
+
+## [0.2.1] - 2026-05-18
+
+Patch release — clear Node-version error message, correct `engines`
+declaration, and the default API URL is now the real API host. No
+tool surface change.
+
+### Fixed
+
+- **Default `KAMINARI_AD_API_URL` pointed at the wrong host.**
+  v0.2.0 defaulted to `https://kaminari.ad`, which is the marketing
+  landing page — `kaminari.ad` does NOT serve `/api/v1/*` routes
+  (returns HTTP 404 for every tool call). The actual API host is
+  `https://app.kaminari.ad` (note the `app.` subdomain).
+  Users who set `KAMINARI_AD_API_URL` explicitly were unaffected;
+  users who relied on the default got 404 on every tool call. The
+  internal `gen-api-types` script already used the correct host
+  (`app.kaminari.ad`) for OpenAPI generation — only the runtime
+  default drifted. Now corrected here, in `.env.example`, and pinned
+  by a unit test against future regressions.
+- **Cryptic `webidl.util.markAsUncloneable is not a function`
+  startup crash on Node < 22.19.** The underlying `undici@8.x`
+  removed feature probes in v8.0.3 and now imports `markAsUncloneable`
+  unconditionally — that symbol only exists on Node 22.19+. v0.2.0
+  declared `engines.node = ">=22.13.0"`, so npm warned but did not
+  block install on Node 22.13–22.18 or Node 20; users hit the
+  cryptic webidl error at first invocation.
+  - `engines.node` bumped to `>=22.19.0` to match the real floor.
+    Consumers with `engine-strict=true` (or `npm install
+    --engine-strict`) are now blocked at install time with a clear
+    `EBADENGINE` message.
+  - New runtime preflight in `bin.ts::main()` catches the case where
+    install slipped through (npx pulls fresh on every run; npx does
+    not honour `engine-strict` by default). Prints a clean message
+    and exits with code 2, BEFORE any dynamic import pulls undici:
+
+    ```
+    @kaminari-ad/mcp requires Node.js >=22.19.0 (you have v20.x.x).
+    The underlying undici 8.x HTTP client uses markAsUncloneable
+    from node:worker_threads, available only on Node 22.19+.
+    Older Node crashes at import time with the cryptic message
+    `webidl.util.markAsUncloneable is not a function`.
+
+    Please upgrade Node and re-run: https://nodejs.org/en/download
+    ```
+
+### Internal
+
+- `tsup.config.ts` flipped to `splitting: true`. Required for the
+  preflight to actually run before undici loads: without splitting
+  esbuild inlines every dynamic `await import("./presentation/...")`
+  call into the top-level bundle, eagerly importing undici/MCP SDK/
+  pino at startup. With splitting on, transport bootstraps stay as
+  separate chunks loaded only after `main()` runs the Node check.
+- `scripts/check-bundle-size.ts` rewritten to aggregate every
+  runtime `.js` chunk under `dist/` instead of just `dist/bin.js`.
+  With splitting on, `bin.js` is a thin ~5 KB preflight + dispatch
+  shim and the actual shipping cost lives in the transport / vendor
+  chunks. Total artifact: 173 KB across 5 chunks (smaller than
+  v0.2.0's 218 KB monolithic bundle thanks to tree-shaking now seeing
+  each chunk in isolation). Limit unchanged at 500 KB.
+- `src/shared/check-node-version.ts` — pure function extracted from
+  `bin.ts` so the version preflight can be unit-tested without
+  `process.exit` side effects. Test pins all boundary cases (22.18 /
+  22.19 / 22.20 / 23.x / 20.x / prerelease tags / garbage input).
+
 ## [0.2.0] - 2026-05-17
 
 Comprehensive parser-drift sweep across all `/api/v1/*` list
@@ -571,7 +661,9 @@ Initial public release. The first version that ships to npm under
   need them.
 - Invoice PDF fetcher — same reason.
 
-[Unreleased]: https://github.com/kaminari-ad/mcp/compare/v0.1.5...HEAD
+[Unreleased]: https://github.com/kaminari-ad/mcp/compare/v0.2.1...HEAD
+[0.2.1]: https://github.com/kaminari-ad/mcp/compare/v0.2.0...v0.2.1
+[0.2.0]: https://github.com/kaminari-ad/mcp/compare/v0.1.5...v0.2.0
 [0.1.5]: https://github.com/kaminari-ad/mcp/compare/v0.1.0...v0.1.5
 [0.1.4]: https://github.com/kaminari-ad/mcp/compare/v0.1.0...v0.1.4
 [0.1.3]: https://github.com/kaminari-ad/mcp/compare/v0.1.0...v0.1.3

package/README.md

@@ -1,13 +1,35 @@
 # `@kaminari-ad/mcp`
 
-Official Model Context Protocol (MCP) server for [Kaminari Ad](https://kaminari.ad) — the ad verification platform from the team behind [Kaminari.Click](https://kaminari.click).
+Official Model Context Protocol (MCP) server for [Kaminari Ad](https://kaminari.ad) — the ad verification platform from the team behind [Kaminari Click](https://kaminari.click).
 
 Lets AI agents (Cursor, Claude Desktop, Cline, and any MCP-compatible client) launch scans, inspect results, manage campaigns and policies, and read alerts directly against your Kaminari Ad workspace via your API key.
 
-[![npm](https://img.shields.io/npm/v/@kaminari-ad/mcp.svg)](https://www.npmjs.com/package/@kaminari-ad/mcp)
-[![CI](https://github.com/kaminari-ad/mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/kaminari-ad/mcp/actions/workflows/ci.yml)
+[![npm version](https://img.shields.io/npm/v/@kaminari-ad/mcp)](https://www.npmjs.com/package/@kaminari-ad/mcp)
+[![npm downloads](https://img.shields.io/npm/dm/@kaminari-ad/mcp)](https://www.npmjs.com/package/@kaminari-ad/mcp)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+[![node](https://img.shields.io/node/v/@kaminari-ad/mcp)](https://nodejs.org)
+[![CI](https://github.com/kaminari-ad/mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/kaminari-ad/mcp/actions/workflows/ci.yml)
 [![Provenance](https://img.shields.io/npm/v/@kaminari-ad/mcp?label=provenance&logo=github)](https://www.npmjs.com/package/@kaminari-ad/mcp)
+[![MCP Registry](https://img.shields.io/badge/MCP_Registry-listed-blue)](https://registry.modelcontextprotocol.io)
+
+## Install (one click)
+
+### Cursor
+
+<a href="https://kaminari.ad/mcp/install"><img alt="Install in Cursor" src="https://cursor.com/deeplink/mcp-install-dark.png" height="32" /></a>
+
+### Claude Desktop
+
+[**Download `kaminari-ad-mcp.mcpb`**](https://github.com/kaminari-ad/mcp/releases/latest/download/kaminari-ad-mcp.mcpb) → double-click to install. Claude Desktop shows a config form for your API key.
+
+### Claude Code (CLI)
+
+```bash
+claude mcp add kaminari-ad -- npx -y @kaminari-ad/mcp
+export KAMINARI_AD_API_KEY=your-key
+```
+
+Full installation docs — see [Quick start](#quick-start) below.
 
 ---
 
@@ -67,11 +89,11 @@ For cloud agents or clients without a local Node runtime, point at the hosted en
 83 tools mirroring most of the public `/api/v1` surface of Kaminari Ad. Every tool carries MCP behaviour annotations (`title`, `readOnlyHint`, `destructiveHint`, `idempotentHint`, `openWorldHint`) so MCP clients can warn before destructive actions. Highlights:
 
 - **Account** (11) — `get_account`, `update_org`, `list_org_users`, `invite_user`, `update_user_role`, `remove_user`, `transfer_ownership`, `list_org_roles`, `list_api_keys`, `create_api_key`, `revoke_api_key`
-- **Scans** (7) — `list_scans`, `get_scan`, `create_scan`, `create_bulk_scans`, `recheck_scans`, `cancel_scan`, `list_scan_tags`
+- **Scans** (6) — `list_scans`, `get_scan`, `create_scan`, `create_bulk_scans`, `recheck_scans`, `cancel_scan`
 - **Campaigns** (10) — `list_campaigns`, `list_campaigns_picker`, `get_campaign`, `create_campaign`, `update_campaign`, `archive_campaign`, `unarchive_campaign`, `cancel_campaign`, `run_campaign`, `list_campaign_runs`
 - **Campaign groups** (10) — list/get/create/update/run/cancel/archive/unarchive + `pause_campaign_group_schedule`, `resume_campaign_group_schedule`
 - **Runs** (3) — `get_run`, `list_run_scans`, `cancel_run` (use `list_campaign_runs` to enumerate runs of a campaign — the API has no standalone `/runs` index)
-- **Tags** (4) — `list_tags`, `get_tag_definition`, `update_tag_definition`, `delete_tag_definition`
+- **Tags** (5) — `list_tags`, `get_tag_definition`, `update_tag_definition`, `delete_tag_definition`, `list_scan_tags`
 - **Custom rules** (6) — `list_custom_rules`, `get_custom_rule`, `create_custom_rule`, `update_custom_rule`, `delete_custom_rule`, `test_custom_rule`
 - **Policy sets** (6) — `list_policy_sets`, `get_policy_set`, `create_policy_set`, `update_policy_set`, `delete_policy_set`, `request_policy_set_approval`
 - **Alerts** (3) — `list_alerts`, `update_alert_status`, `get_alert_stats`
@@ -121,7 +143,7 @@ make test-unit       # unit only
 make test-isolation  # tenant-isolation suite
 ```
 
-Or directly with `npm` if you have Node 22 LTS on the host (matches `.nvmrc` / `engines.node`):
+Or directly with `npm` if you have Node `>=22.19.0` on the host (matches `engines.node`; `.nvmrc` pins the minor for dev parity with CI). The package gates strictly at `22.19.0` because `undici@8.x` requires `markAsUncloneable` from `node:worker_threads` (Node 22.19+).
 
 ```bash
 npm ci --legacy-peer-deps