@kaminari-ad/mcp 0.2.1 → 0.3.0

package/CHANGELOG.md

@@ -7,6 +7,126 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.3.0] - 2026-05-20
+
+Major-feature release — full parity with the API surface added in
+COOP-13940 Phase 3 (custom taxonomies + 5-kind policy rules + binary
+downloads). **Contains breaking changes for existing agents** —
+review the migration notes below before upgrading.
+
+### Breaking
+
+- **`update_tag_definition`**: input field `show_in_public_report`
+  (boolean) was removed; replaced by `visibility` (enum:
+  `hidden | internal | public`). Old payloads now fail zod
+  validation locally with a typed `invalid-input` error before
+  hitting the API. Migration: replace `show_in_public_report: true`
+  → `visibility: "public"`, and `show_in_public_report: false` →
+  `visibility: "internal"` (or `"hidden"` if you want the tag
+  fully suppressed).
+- **`list_alerts`**: `status` filter no longer accepts the legacy
+  values `"ack"` / `"ignored"`. The canonical four are
+  `"open"`, `"acknowledged"`, `"resolved"`, `"dismissed"`. Mapping:
+  `"ack"` → `"acknowledged"`, `"ignored"` → `"dismissed"`.
+- **`create_policy_set` / `update_policy_set`**: `entries[]` is now
+  a discriminated union over **five rule kinds**. Existing tag-only
+  callers MUST add `rule_type: "tag"` to every entry. Other kinds:
+  `"iab_v3"` (with `iab_v3: { tier1, tier2?, tier3?, tier4? }`),
+  `"brand"` (with `brand: string`), `"ai_category"` (with
+  `ai_category: { tier1, tier2?, tier3?, tier4? }`),
+  `"custom_taxonomy"` (with `custom_taxonomy: { taxonomy_id, tier1,
+  tier2?, tier3?, tier4? }`).
+  `country_codes` now accepts both ISO alpha-2 and alpha-3 (the
+  API normalises).
+
+### Added
+
+- **`custom_taxonomies` tool suite (7 tools).** Per-org
+  classification trees with an `is_default` fallback node:
+  `list_custom_taxonomies`, `get_custom_taxonomy`,
+  `create_custom_taxonomy`, `update_custom_taxonomy`,
+  `delete_custom_taxonomy` (soft-delete), `restore_custom_taxonomy`,
+  `parse_custom_taxonomy_text` (no-persistence preview).
+- **Account labels.** `list_account_labels` + `update_account_labels`
+  for the per-org metadata schema that backs `list_scans.labels`
+  filters. `update_account_labels` is hinted destructive — passing
+  `labels: []` wipes the catalogue.
+- **`create_custom_role`** for `/api/v1/account/roles` POST.
+- **Binary downloads** — `get_invoice_pdf` (MCP `resource` block),
+  `get_scan_screenshot`, `get_scan_creative_screenshot`,
+  `get_scan_landing_screenshot` (MCP `image` blocks). All four
+  return inline base64 with the API-supplied `mimeType` so agents
+  can save / forward without a second call.
+- **`list_alerts` rule_type + matched_value.** Each alert row now
+  carries `rule_type` (one of the five kinds) and `matched_value`
+  (the canonical text the scan matched against). Lets agents
+  branch on rule kind without re-fetching the scan.
+- **`list_policy_sets.visibility` filter.** Narrow to
+  `private` (org-owned) or `public` (Kaminari Ad-curated). Omit
+  the filter to see both combined.
+- **`list_scans` filters.** Added `run_id`, `campaign_id`,
+  `group_id`, `timezone`, `ai_category`, `iab_v3_category`,
+  `iab_category`, `brand`, plus a typed `labels` record that
+  expands to `label_<key>=<value>` query params (snake_case keys
+  enforced by zod).
+- **Misc query filters.** `list_campaigns` + `list_campaigns_picker`
+  gained `archived` / `q`; `list_invoices` gained `type` / `status`
+  enums; `list_balance_history` gained multi-select `type`;
+  `list_webhook_deliveries` gained `success` / `from_ts` / `to_ts`;
+  `list_usage` switched to ISO 8601 datetime bounds; `list_tags`
+  gained `category`.
+
+### Changed
+
+- **OpenAPI types regenerated.** `src/shared/api/openapi.ts` and
+  `src/shared/api/zod-schemas.ts` are rebuilt from the prod API and
+  capture every Phase 3 schema (custom-taxonomies, 5-kind
+  PolicyEntry, AlertResponse `rule_type` / `matched_value`, tag
+  visibility rename).
+- **Tool descriptions.** Policy-sets, alerts, and tag tools updated
+  to mention the new fields. `get_alert_stats` description uses the
+  canonical AlertStatus names.
+- **Branding.** All user-visible tool descriptions and JSDoc use the
+  canonical `Kaminari Ad` (with space) per the updated branding
+  rule. The dotted form `Kaminari.Ad` is deprecated.
+
+### Quality gates
+
+- 705 unit tests (was 623). Coverage 100% statements / 100% lines /
+  100% functions / 97.89% branches (gate is 95% branches). Every
+  new tool has at least 3 cases (success / api-error /
+  zod-rejection); policy-set tools cover all five rule kinds with
+  per-kind missing-block rejection tests.
+- All existing gates pass: lint, format, typecheck, tool-naming,
+  file-sizes (8 grandfathered, every new file <200 effective
+  lines), check-imports, check-shared-state,
+  check-no-handwritten-parsers.
+
+## [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`

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`

package/dist/bin.js

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-import { NAME, VERSION, err, ok } from './chunk-2H457UAT.js';
+import { NAME, VERSION, err, ok } from './chunk-KTQBHJUB.js';
 import process from 'process';
 import { z } from 'zod';
 
@@ -119,10 +119,10 @@ async function main() {
   }
   const config = configResult.value;
   if (config.transport === "stdio") {
-    const { bootstrapStdio } = await import('./stdio-bootstrap-V64J2Z55.js');
+    const { bootstrapStdio } = await import('./stdio-bootstrap-RBANZT6F.js');
     return bootstrapStdio(config);
   }
-  const { bootstrapHttp } = await import('./http-bootstrap-4MLE6RO4.js');
+  const { bootstrapHttp } = await import('./http-bootstrap-FGGCFLRU.js');
   return bootstrapHttp(config);
 }
 main().then(

package/dist/{chunk-2H457UAT.js → chunk-KTQBHJUB.js}

@@ -3,8 +3,8 @@ export { err, ok } from 'neverthrow';
 
 // src/shared/version.ts
 var NAME = "@kaminari-ad/mcp";
-var VERSION = "0.2.1";
+var VERSION = "0.3.0";
 
 export { NAME, VERSION };
-//# sourceMappingURL=chunk-2H457UAT.js.map
-//# sourceMappingURL=chunk-2H457UAT.js.map
+//# sourceMappingURL=chunk-KTQBHJUB.js.map
+//# sourceMappingURL=chunk-KTQBHJUB.js.map

package/dist/{chunk-2H457UAT.js.map → chunk-KTQBHJUB.js.map}

@@ -1 +1 @@
-{"version":3,"sources":["../src/shared/version.ts"],"names":[],"mappings":";;;;AASO,IAAM,IAAA,GAAO;AACb,IAAM,OAAA,GAAU","file":"chunk-2H457UAT.js","sourcesContent":["/**\n * Package version and name. Hard-coded as constants here, asserted to\n * match `package.json` by a unit test.\n *\n * Why not import `package.json`: it would force JSON-module support at\n * runtime and tsup-bundling would inline the entire manifest. Two\n * constants + one assertion test is simpler and gives the same safety.\n */\n\nexport const NAME = \"@kaminari-ad/mcp\";\nexport const VERSION = \"0.2.1\";\n"]}
+{"version":3,"sources":["../src/shared/version.ts"],"names":[],"mappings":";;;;AASO,IAAM,IAAA,GAAO;AACb,IAAM,OAAA,GAAU","file":"chunk-KTQBHJUB.js","sourcesContent":["/**\n * Package version and name. Hard-coded as constants here, asserted to\n * match `package.json` by a unit test.\n *\n * Why not import `package.json`: it would force JSON-module support at\n * runtime and tsup-bundling would inline the entire manifest. Two\n * constants + one assertion test is simpler and gives the same safety.\n */\n\nexport const NAME = \"@kaminari-ad/mcp\";\nexport const VERSION = \"0.3.0\";\n"]}