@kaminari-ad/mcp 0.1.5 → 0.2.1

package/CHANGELOG.md

@@ -7,6 +7,173 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [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
+endpoints, a new tool for slim campaign selection, an MCP-client
+interop fix, and small docs polish. Semver-minor because three list
+tools changed output shape (breaking) and one new tool was added.
+
+The MCP audit covered every `/api/v1/*` list endpoint. The MCP
+already wrapped 21 of them — 18 were correctly wired, 3 had drift
+(now fixed: `list_run_scans`, `list_custom_rules`, `list_policy_sets`).
+One additional list endpoint (`/campaigns/picker`) had no MCP wrapper
+and was added as the new `list_campaigns_picker` tool. The detail
+endpoint `get_tag_definition` was also fixed to surface
+`linked_rules`. See [MIGRATION_0_2.md](https://github.com/kaminari-ad/mcp/blob/main/MIGRATION_0_2.md)
+for the agent-side migration notes.
+
+### Breaking
+
+- **`list_run_scans` output element type:** `ScanBriefResponse` →
+  `ScanTileResponse`. The slim DTO drops `url` / `created_at` /
+  `labels` / `campaign_id` / `campaign_name` / `is_ad_tag` and adds
+  `error`. The tool no longer fails on prod data with `malformed
+  scans page: items.0.url: Required`; agents needing full scan
+  details should call `get_scan` per tile.
+- **`list_custom_rules` output shape:** `readonly CustomRuleResponse[]`
+  → `PaginatedResponse<CustomRuleResponse>`. New optional
+  `page` / `limit` inputs (defaults `1` / `50`). Previously the tool
+  silently dropped pagination metadata; orgs with > 50 rules
+  appeared to have exactly 50.
+- **`list_policy_sets` output shape:** `readonly PolicySetListItemResponse[]`
+  → `PaginatedResponse<PolicySetListItemResponse>`. New optional
+  `page` / `limit` inputs (defaults `1` / `50`). Same pagination
+  drop as `list_custom_rules`.
+
+### Fixed
+
+- **`list_run_scans` failed with `malformed scans page:
+  items.0.url: Required`.** Parser wired the wrong DTO
+  (`ScanBriefResponse`) for an endpoint that returns
+  `ScanTileResponse`. Same drift class as `list_policy_sets` v0.1.1.
+- **`list_custom_rules` / `list_policy_sets` silently dropped
+  pagination metadata.** Now expose `total` / `page` / `limit` so
+  agents iterate correctly past the default page size.
+- **`get_tag_definition` now returns `linked_rules`** (the custom
+  rules currently producing this tag — `id` / `name` / `is_active`).
+  Previously silently dropped because the parser reused the list-row
+  schema. Agents no longer need to grep `list_custom_rules` by
+  `tag_slug` themselves.
+- **`invalid-input` (HTTP 400 / 422) error responses now preserve
+  the API's machine-readable `code` field.** Forward-compat for
+  `delete_policy_set` growing `code: "policies.in_use"` — agents
+  can branch programmatically as soon as the API ships the code,
+  no MCP release required.
+
+### Added
+
+- **`list_campaigns_picker`** (83rd tool — was 82, now 83) — slim
+  per-row campaign list for selection UIs (id, name, group_id,
+  is_archived). Cheaper than `list_campaigns` for orgs with thousands
+  of campaigns. Use `get_campaign(id)` after a selection.
+- **Server now declares empty `resources` and `prompts` capabilities
+  with handlers returning `[]`.** Cursor / Claude Desktop / Cline
+  probe these at session start; previously the SDK responded with
+  `-32601 Method not found`, which Cursor's client mistranslated
+  as a misleading `"MCP error -32000: Connection closed"` warning.
+  Functional impact was zero (all tools remained callable) but
+  downstream agent logs filled with false positives once per session
+  per server. Now clean.
+
+### Docs
+
+- **README:** replaced the fictional `kad_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx`
+  API-key placeholder with `<your-kaminari-ad-api-key>` + a note
+  that keys are opaque (no required prefix or fixed length).
+- **`create_custom_rule` / `update_custom_rule` / `test_custom_rule`:**
+  the `target` parameter description no longer claims a stale
+  `page | offer_url | html` enum (OpenAPI declares it as a freeform
+  string; `html` may not be currently valid). Defers to API docs.
+- **`delete_policy_set`:** description now explicitly mentions the
+  API returns `HTTP 400` if campaigns are bound, and suggests the
+  unbind-via-`update_campaign` workflow before retry.
+
+### Internal
+
+- Comprehensive parser-drift audit across all `/api/v1/*` list
+  endpoints (run via parallel `explore` subagents covering API + MCP
+  sides). 21 endpoints already had MCP wrappers — 18 clean, 3 with
+  drift (now fixed); 1 additional list endpoint had no wrapper and
+  was added as a new tool. No remaining drift.
+- New parser modules: `parse-run-scan-page.ts`, `parse-custom-rule-page.ts`,
+  `parse-policy-set-page.ts`, `parse-campaign-picker.ts`. The old
+  defensive bare-or-envelope helpers (`parseCustomRuleArray`,
+  `parsePolicySetList`) are gone; their files now expose only the
+  per-entity parsers. `parseTagDetail` moved out of `parse-generic.ts`
+  into `parse-tag.ts` because it now needs the detail schema's
+  `linked_rules` field which the list schema doesn't have.
+- New shared helper `presentation/shared/declare-empty-caps.ts`
+  used by both stdio and HTTP bootstraps. Unit test against an
+  in-memory `Client` + `InMemoryTransport.createLinkedPair()` pair,
+  plus an end-to-end probe in the CLI smoke that hits a real HTTP
+  RPC after the `initialize` handshake.
+
 ## [0.1.5] - 2026-05-17
 
 Re-release of v0.1.4 — the Corepack-based npm upgrade in v0.1.4
@@ -469,7 +636,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/MIGRATION_0_2.md

@@ -0,0 +1,139 @@
+# Migrating from `@kaminari-ad/mcp` 0.1.x to 0.2.0
+
+Two tools changed output shape and one tool changed its element type.
+Everything else is wire-compatible.
+
+If your agent calls **only** the unchanged tools, **no action is
+required** — drop in v0.2.0 and continue.
+
+## Breaking changes
+
+### 1. `list_custom_rules` — bare array → paginated envelope
+
+Before (≤ 0.1.5):
+
+```jsonc
+[
+  { "id": "…", "name": "…", "tag_slug": "…", "rule_type": "…", "config": {...},
+    "target": "…", "is_active": true, "organization_id": "…", "created_at": "…" },
+  /* … */
+]
+```
+
+After (≥ 0.2.0):
+
+```jsonc
+{
+  "items": [
+    { "id": "…", "name": "…", "tag_slug": "…", "rule_type": "…", "config": {...},
+      "target": "…", "is_active": true, "organization_id": "…", "created_at": "…" }
+  ],
+  "total": 67,
+  "page": 1,
+  "limit": 50
+}
+```
+
+**Why:** the API has always returned a `PaginatedResponse[CustomRuleResponse]`
+envelope; v0.1.x silently dropped `total` / `page` / `limit`. Orgs with
+
+> 50 rules saw exactly 50 with no signal there was more.
+
+**Migration:** wherever you read `result.length` on a `list_custom_rules`
+output, replace with `result.items.length` and check `result.total >
+result.items.length` to know if you need to call the tool again with
+`page: 2`. New optional inputs:
+
+```jsonc
+{ "page": 1, "limit": 50 }
+
+
+// defaults; both optional
+```
+
+### 2. `list_policy_sets` — bare array → paginated envelope
+
+Same shape change as `list_custom_rules`, same migration. The items
+themselves are unchanged (slim — no `entries`; call `get_policy_set`
+for those).
+
+### 3. `list_run_scans` — `ScanBriefResponse` → `ScanTileResponse` per item
+
+Before (≤ 0.1.5) — crashed in production with `malformed scans page:
+items.0.url: Required`:
+
+```jsonc
+{ "items": [{ "id": "…", "url": "…", "country_code": "…", "status": "…",
+              "offer_url": "…", "screenshot_url": "…", "labels": {…},
+              "elapsed_ms": 1234, "campaign_id": "…", "campaign_name": "…",
+              "is_ad_tag": false, "created_at": "…" }], … }
+```
+
+After (≥ 0.2.0):
+
+```jsonc
+{ "items": [{ "id": "…", "country_code": "…", "status": "…",
+              "offer_url": "…", "screenshot_url": "…",
+              "elapsed_ms": 1234, "error": "" }], … }
+```
+
+**Why:** the API endpoint returns `ScanTileResponse` (designed for
+the run-detail UI's tile grid) — `url` / `created_at` / `labels` /
+`campaign_*` / `is_ad_tag` are intentionally omitted because the
+caller already knows the run's campaign and the tiles don't need to
+re-render input URLs. `error` (the scan-failure reason) is **added**.
+
+**Migration:** if your agent reads any of the removed fields off
+`list_run_scans` items, call `get_scan(id)` per tile to fetch the
+full `ScanResponse` (which has them all).
+
+## Additions (non-breaking)
+
+### `list_campaigns_picker` — new tool
+
+Slim per-row campaign list for selection UIs:
+
+```jsonc
+{ "id": "…", "name": "…", "group_id": "…", "is_archived": false }
+```
+
+Cheaper than `list_campaigns` for orgs with thousands of campaigns —
+the API endpoint is non-paginated and intentionally omits heavy
+fields. Use `get_campaign(id)` after a selection to fetch full
+details.
+
+### `get_tag_definition` — now returns `linked_rules`
+
+The detail endpoint always returned `linked_rules` per OpenAPI; the
+v0.1.x parser silently dropped them. v0.2.0 surfaces them:
+
+```jsonc
+{
+  "slug": "malware",
+  "category": "security",
+  /* … all existing fields … */
+  "linked_rules": [{ "id": "…", "name": "ad-detector", "is_active": true }],
+}
+```
+
+No input change. Agents that need rules linked to a tag no longer
+need to grep `list_custom_rules` by `tag_slug` themselves.
+
+### `resources/list` and `prompts/list` now return `[]`
+
+Most MCP clients (Cursor, Claude Desktop, Cline) probe these methods
+at session start. v0.1.x returned the JSON-RPC standard `-32601
+Method not found` (spec-compliant), but Cursor's client mistranslated
+that into a misleading `"Connection closed"` warning. v0.2.0 declares
+empty capabilities + handlers so the probe is silent.
+
+Functional impact for callers: zero. No tool surface changed; the
+fix is purely about client-side noise.
+
+## Internal: forward-compat for `policies.in_use`
+
+`invalid-input` MCP errors (HTTP 400 / 422) now preserve the API's
+machine-readable `code` field when present. The API does not emit
+`code` on `delete_policy_set` today, but `policies.in_use` is a known
+candidate. When the API ships it, agents can branch on the code
+without waiting for an MCP release.

package/README.md

@@ -19,6 +19,8 @@ Lets AI agents (Cursor, Claude Desktop, Cline, and any MCP-compatible client) la
 2. Once signed in, go to **Settings → API Keys** and generate a new key, OR have an existing AI assistant (with a temporary login) call the [`create_api_key`](#tools) tool — both paths produce the same result.
 3. The key is shown **once**. Copy it. The full key is hashed server-side immediately.
 
+> Keys are opaque random strings — no required prefix or fixed length. Treat the whole value as a raw secret and paste it verbatim into your client config.
+
 > Tip for evaluators / Anthropic Software Directory reviewers: ask the team at [hello@kaminari.ad](mailto:hello@kaminari.ad) for a sandboxed test account with seeded sample scans, campaigns, and alerts.
 
 ### 2a. Local install (stdio transport)
@@ -32,14 +34,14 @@ Add to your MCP client config (Cursor: `~/.cursor/mcp.json`; Claude Desktop: `~/
       "command": "npx",
       "args": ["-y", "@kaminari-ad/mcp"],
       "env": {
-        "KAMINARI_AD_API_KEY": "kad_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
+        "KAMINARI_AD_API_KEY": "<your-kaminari-ad-api-key>",
       },
     },
   },
 }
 ```
 
-Restart your client. You should see `kaminari-ad` in the MCP servers list with 82 tools exposed.
+Restart your client. You should see `kaminari-ad` in the MCP servers list with 83 tools exposed.
 
 ### 2b. Hosted HTTP transport (no install)
 
@@ -51,7 +53,7 @@ For cloud agents or clients without a local Node runtime, point at the hosted en
     "kaminari-ad": {
       "url": "https://mcp.kaminari.ad/mcp",
       "headers": {
-        "Authorization": "Bearer kad_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
+        "Authorization": "Bearer <your-kaminari-ad-api-key>",
       },
     },
   },
@@ -62,11 +64,11 @@ For cloud agents or clients without a local Node runtime, point at the hosted en
 
 ## Tools
 
-82 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:
+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`
-- **Campaigns** (9) — `list_campaigns`, `get_campaign`, `create_campaign`, `update_campaign`, `archive_campaign`, `unarchive_campaign`, `cancel_campaign`, `run_campaign`, `list_campaign_runs`
+- **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`
@@ -79,7 +81,7 @@ For cloud agents or clients without a local Node runtime, point at the hosted en
 - **Alert notifications** (5) — `list_alert_destinations`, `delete_alert_destination`, `set_alert_destination_version`, `get_campaign_alert_overrides`, `set_campaign_alert_overrides`
 - **Reference data** (2) — `list_geos`, `list_emulators`
 
-Not exposed (intentionally): binary scan-screenshot fetchers, invoice PDF, the UI-only campaign picker, and the public marketing forms (`/contact`, `/demo-inquiries`). Open an issue if you need one of those.
+Not exposed (intentionally): binary scan-screenshot fetchers, invoice PDF, and the public marketing forms (`/contact`, `/demo-inquiries`). Open an issue if you need one of those.
 
 ## Example agent prompts
 
@@ -119,7 +121,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