@kaminari-ad/mcp 0.1.5 → 0.2.0

package/CHANGELOG.md

@@ -7,6 +7,108 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [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

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