@kaminari-ad/mcp 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,383 @@
+# Changelog
+
+All notable changes to `@kaminari-ad/mcp` are documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.1.0] - 2026-05-17
+
+First public release of `@kaminari-ad/mcp`.
+
+Bundles the full pre-release development arc that lived on a private
+GitLab instance: HTTP + stdio transports, 82 MCP tools spanning scans /
+campaigns / policies / alerts / webhooks / billing / accounts, tenant-
+isolation suite, schema-backed parsers, openapi-fetch gateway, the
+`prod:smoke` CI job, and the OSS bootstrap (LICENSE, SECURITY,
+CONTRIBUTING, CODE_OF_CONDUCT, issue / PR templates).
+
+See the GitHub release notes for the auto-generated commit summary;
+the per-area changelog entries below capture the substantive engineering
+work since the project was scaffolded.
+
+### Fixed (parser-drift phase 5 — post-review hardening)
+
+- **`list_policy_sets` regression introduced by phase 2b.** The
+  schema-strict parser required `entries`, but `GET /api/v1/policy-sets`
+  returns `PolicySetListItem` (a slim per-item shape WITHOUT entries —
+  entries are loaded on demand via `get_policy_set(id)`). Every real
+  list call after the phase 2b roll-out returned
+  `"malformed policy-sets: 0.entries: Required"`. Now:
+  - New port DTO `PolicySetListItemResponse` (no `entries`).
+  - New `PolicySetListItemSchema` in `parse-policy-set.ts` backed by
+    the generated `schemas.PolicySetListItem`.
+  - `list_policy_sets` tool now exposes the slim shape and its
+    description tells the agent to follow up with `get_policy_set`
+    when it needs the entries.
+  - HTTP gateway test stub + fake fixture updated to the slim shape.
+  - Verified against prod API via end-to-end smoke against a sandbox
+    org: parser now accepts the real response.
+- **`set_alert_destination_version` was parsing a 204 No Content as
+  JSON.** Pre-existing on `main` but surfaced more loudly under strict
+  zod. Now uses `parseEmpty`; port returns `Result<null>`; tool emits
+  `{ updated: true }` like the other 204 mutators. HTTP gateway test
+  updated to a 204 stub (the previous 200-with-body fixture masked
+  the real contract).
+- **`create_api_key` rejected `expires_at: null`.** Common JSON-client
+  convention is to send `null` explicitly for "no expiry". Input
+  schema now accepts both `null` and omit; the gateway sees them as
+  equivalent (no `expires_at` field on the request body).
+- **Dist bundle ~770 KB → ~210 KB.** The `openapi-zod-client`
+  generator emits a Zodios endpoints catalogue + `axios` client at
+  the tail of `zod-schemas.ts`. We use only the `schemas` bag for
+  runtime validation; the MCP gateway is `openapi-fetch`-based, not
+  Zodios. `scripts/gen-api-types.ts` now post-processes the generated
+  output to strip the Zodios runtime (imports, `endpoints` array,
+  `api` instance, `createApiClient` helper). Axios + `form-data` (which
+  use CJS `require("util")`) no longer reach the bundle — this also
+  fixes a `"Dynamic require of util is not supported"` crash on
+  `node dist/bin.js` startup that the integration smoke test caught.
+  `check:bundle-size` reverted to the original 500 KB ceiling.
+- **`{set_id}` path templates corrected to `{policy_set_id}`** in
+  `http-api-gateway.ts` to match the OpenAPI spec. Runtime URLs are
+  identical (openapi-fetch substitutes by key name), but the literal
+  now lines up with the spec for future-readers.
+- **CONTRIBUTING.md "Tenant isolation" §9** added — the pinned 5-key
+  outbound header allowlist (authorization / content-type / accept /
+  user-agent / x-request-id) is now an explicit numbered rule, not
+  an implicit one referenced from inline comments. Stale §8/§11
+  references in `http-api-gateway.ts`, `pino-logger.ts`, and the
+  isolation test headers updated to point at the correct sections.
+- **Empty-body JSDocs filled in.** `parse-empty.ts::parseEmpty` and
+  `parse-count-envelope.ts::parseIntField` now document the contract
+  (204 No Content vs single-int envelope) instead of shipping
+  placeholder `/** * */` stubs.
+- **Tool-test success-payload assertions.** Several 204-mutator tool
+  tests (`set_alert_destination_version`, `set_campaign_alert_overrides`,
+  `request_policy_set_approval`, `update_user_role`) only asserted
+  `isOk()` and never checked the synthetic `{ updated: true }` /
+  `{ requested: true }` payload — a regression that silently changed
+  the success shape would have slipped through. Each now asserts
+  both the call body AND the success payload.
+- **Per-DTO parser error coverage gaps closed.** `parseScanTag`,
+  `parseUsage`, `parseUsageSummary`, `parseBalanceTx`, `parseInvoice`,
+  `parseAlertDestination`, `parseBulkReplay` were happy-path only.
+  Added missing-required + wrong-type cases to each. Coverage stays
+  100% lines + 100% statements + 98.48% branches.
+
+### Fixed (parser-drift phase 1)
+
+Production smoke against a fresh test org found 8 of the 82 tools
+broken on 4 distinct root-cause patterns. All fixed; the global
+masking bug that hid the real failure mode is fixed too.
+
+- **API returns 204 No Content, parser expected entity.** Four tools
+  hit this — `set_campaign_alert_overrides`, `request_policy_set_approval`,
+  `update_tag_definition`, `update_user_role` — with errors like
+  `malformed user` / `malformed tag detail` / `malformed policy-set`.
+  Parsers now use `parseEmpty`; port DTOs return `null`; the tool
+  output is `{ updated: true }` / `{ requested: true }` so JSON output
+  stays a plain object. Tool descriptions updated to point at the
+  follow-up GET when the caller needs the new state echoed.
+- **Action endpoint returns `GroupActionResponse` summary, parser
+  expected the group entity.** `archive_campaign_group` and
+  `unarchive_campaign_group` both POST endpoints return
+  `{ group_id, affected_campaigns, cancelled_count, run_ids,
+  failures }` like `run_campaign_group` / `cancel_campaign_group`.
+  Parsers now use the existing `parseGroupAction`; port DTO is
+  `GroupActionResponse`.
+- **Paginated envelope vs bare array (inverted from last week).**
+  `list_campaign_groups` — OpenAPI documents the response as a bare
+  `CampaignGroupResponse[]` but the parser was `parseCampaignGroupPage`
+  expecting `{items, total, page, limit}`. New
+  `parseCampaignGroupArray` accepts both shapes defensively (same
+  `unwrapItems` pattern used in `parsePolicySetList`). Tool DTO becomes
+  `readonly CampaignGroupResponse[]` and the bogus `page` / `limit`
+  query params (the endpoint only documents `archived?`) are dropped.
+- **Missing required request body + ignored response.** `test_webhook`
+  sent `undefined` body, but the API requires `{event_type: string}`
+  (422 without). The rich `TestWebhookResponse` was dropped via
+  `parseEmpty`. The gateway now sends the body; new
+  `parseTestWebhookResponse` decodes
+  `{ success, response_status, elapsed_ms, error_code, response_body }`
+  so the agent can diagnose a receiver failure from one call.
+- **`error-mapping.ts::detail()` only handled string `detail`.**
+  FastAPI 422 returns `detail: ValidationError[]`. Every 422 across
+  every tool degraded to opaque `"Upstream error"` — which masked the
+  real `test_webhook` failure mode. The detail extractor now walks
+  the array, formats each entry as `"<loc>: <msg>"`, joins with
+  `; `, surfaces field-level RCA in the tool error string.
+
+### Added (parser-drift phase 2a — infrastructure for the rest)
+
+- **Generated zod runtime schemas** at `src/shared/api/zod-schemas.ts`.
+  `scripts/gen-api-types.ts` now emits both
+  `src/shared/api/openapi.ts` (types, via `openapi-typescript`) and
+  `src/shared/api/zod-schemas.ts` (runtime schemas + Zodios endpoint
+  catalogue, via `openapi-zod-client`) from the SAME live OpenAPI
+  document — so the two files cannot drift relative to each other,
+  and the existing CI drift-check on the committed copies covers
+  both. Source URL changed from `https://kaminari.ad/openapi.json`
+  (returns a Next.js 404) to `https://app.kaminari.ad/openapi.json`
+  (the actual API host).
+- **`parseWithSchema` helper** at
+  `src/infrastructure/api/parsers/parse-with-schema.ts` — wraps
+  `schema.safeParse()` with typed `ApiError` failure mapping AND
+  strips explicit-`undefined` keys from the parsed object so the
+  output matches the port DTO's `exactOptionalPropertyTypes` style.
+  Foundation for Phase 2b (converting each hand-written
+  `parse-*.ts` to a one-liner backed by `schemas.X.pick({...})`).
+
+### Added (parser-drift phase 4 — production observability)
+
+- **`scripts/prod-smoke.ts`** + **`npm run prod:smoke`** + a manual
+  `prod:smoke` GitLab CI job. Fires a read-only subset of MCP tools
+  at the hosted endpoint using a long-lived sandbox-org bearer
+  (`KAMINARI_AD_MCP_PROD_TOKEN` CI variable, Masked + Protected).
+  Catches drifts that escape compile-time gates — API shape changes,
+  feature-flag-gated routes flipping on/off, parser regressions.
+  Manual trigger by default; flip to a daily schedule once the
+  sandbox org + token are provisioned.
+
+### Added (parser-drift phase 2b — full conversion)
+
+- **Every `parse-*.ts` rewritten as a `parseWithSchema(schemas.X.pick
+  ({...}).strip())` one-liner.** All 17 hand-written parsers now
+  delegate to zod schemas generated from the live OpenAPI spec. A
+  field rename / removal upstream surfaces as a `tsc` error on the
+  `.pick({…})` mask (drift fails at compile time, not at the first
+  production request). A wrong-shape runtime payload degrades to a
+  typed `upstream` MCP error with the zod issue chain — never to an
+  `undefined.x` crash.
+- **Test fixtures hardened.** ~30 fixtures across
+  `tests/unit/infrastructure/api/**` migrated from the old loose
+  hand-parser stubs (`id: "u1"`, `created_at: "t"`,
+  `status: "done"`) to schema-valid values
+  (`id: "00000000-0000-0000-0000-…"`, ISO datetimes, enum members
+  from the OpenAPI source like `"completed"` / `"api"`). Tests now
+  assert the same contract the production API enforces.
+- **Two exempt files**, both documented in
+  `scripts/check-no-handwritten-parsers.ts`:
+  - `parse-empty.ts` — `204 No Content`, no body to validate.
+  - `parse-count-envelope.ts::parseIntField(raw, "x")` — generic
+    one-field-int extractor used by ad-hoc envelopes like
+    `{queued_count}` / `{cancelled_count}` that have no dedicated DTO
+    in the spec.
+
+### Added (parser-drift phase 3 — typed HTTP client)
+
+- **`src/infrastructure/api/http-api-gateway.ts` ported to
+  `openapi-fetch`.** Every endpoint path is now a literal type
+  constrained by `paths` from `src/shared/api/openapi.ts`; path /
+  query / body shapes are validated by the same generated types,
+  with the agent-facing `Pick<S[K], …>` projections in
+  `domain/ports/api-gateway.ts` narrowing the surface. Renaming or
+  removing an endpoint on the API side fails the gateway at
+  `tsc --noEmit` immediately — no runtime drift.
+- **Tenant-isolation contract preserved.** Pinned 5-key outbound
+  header allowlist (authorization / content-type / accept /
+  user-agent / x-request-id) — same shape the existing
+  `tests/isolation/header-injection-e2e.test.ts` AST gate already
+  enforces. Per-request `Dispatcher` injection (used by tests with
+  `MockAgent`; production uses the global agent) is forwarded through
+  a thin `fetchImpl` wrapper that splices `input.headers` /
+  `input.body` from openapi-fetch's `Request` onto the undici init
+  bag — without this the auth header silently vanishes (because
+  undici.fetch ignores `Request` and reads only `init`).
+- **Removed `buildQuery` and the manual `${enc(id)}` interpolation.**
+  Query / path params now go through openapi-fetch's typed
+  `params.query` / `params.path` — typed key names per endpoint,
+  enforced at compile time (`scan_id` for `/scans/{scan_id}`,
+  `endpoint_id` for `/webhooks/{endpoint_id}`, etc.). A key typo
+  fails `tsc` rather than producing a silently-wrong URL.
+
+### Added (parser-drift phase 4 — production observability)
+
+- **`scripts/prod-smoke.ts`** + **`npm run prod:smoke`** + a manual
+  `prod:smoke` GitLab CI job (description retained from phase 2a).
+- **`npm run check:no-handwritten-parsers`** + new
+  `check:no-handwritten-parsers` GitLab CI job in `arch_gates`.
+  Belt-and-suspenders gate: parses every `src/infrastructure/api/
+  parsers/*.ts` and fails if a parser does NOT import `{ schemas }
+  from "../../shared/api/zod-schemas"` (or one of the two documented
+  exemptions). A future contributor who adds a hand-rolled
+  `typeof raw === "object" && "field" in raw` parser hits this gate
+  immediately, with a pointer to `parse-org` / `parse-scan` as the
+  canonical schema-backed shape.
+
+### Changed (breaking — pre-release, no API consumers yet)
+
+- **Env vars now carry the `KAMINARI_AD_` namespace prefix.** Generic
+  names (`API_BASE_URL`, `LOG_LEVEL`, `HTTP_PORT`, `SESSION_TTL_SEC`,
+  `RATE_LIMIT_RPM`, `TRANSPORT`) were trivially poisonable by any
+  other tool in the same shell or container that set the same name.
+  All env vars are now `KAMINARI_AD_*`:
+  - `API_BASE_URL` → `KAMINARI_AD_API_URL`
+  - `LOG_LEVEL` → `KAMINARI_AD_LOG_LEVEL`
+  - `HTTP_PORT` → `KAMINARI_AD_HTTP_PORT`
+  - `SESSION_TTL_SEC` → `KAMINARI_AD_SESSION_TTL_SEC`
+  - `RATE_LIMIT_RPM` → `KAMINARI_AD_RATE_LIMIT_RPM`
+  - `TRANSPORT` → `KAMINARI_AD_TRANSPORT`
+  - `KAMINARI_AD_API_KEY` — unchanged.
+  Old unprefixed names are no longer read. `env | grep KAMINARI_AD_`
+  now enumerates every config input.
+
+### Added
+
+- **`KAMINARI_AD_LOG_FORMAT`** env var (`pretty` | `json`) — was
+  previously hard-coded per transport (stdio = pretty, http = json).
+  Now operator-controllable. Default remains transport-dependent.
+  MCP hosts that capture stderr (Cursor, Claude Desktop) should set
+  this to `json` for parseable structured logs.
+- **`pino-pretty`** moved to runtime `dependencies` so the default
+  `stdio + pretty` path no longer crashes on `npx -y @kaminari-ad/mcp`
+  with "unable to determine transport target".
+- **Pino sink hardening**: `pretty` format now uses a sync
+  `pino-pretty` write stream wired to `process.stderr` directly,
+  instead of the `transport` worker option. The worker silently
+  ignores any `destination` argument and defaults to stdout, which
+  would corrupt the MCP JSON-RPC channel in stdio mode.
+
+### Fixed
+
+- **Paginated list parsers (custom-rules, policy-sets) accept the
+  FastAPI envelope.** Both `parseCustomRuleArray` and
+  `parsePolicySetList` expected a bare `T[]`, but the API returns the
+  standard `{ items, total, page, limit, pages }` envelope — every
+  call to `list_custom_rules` / `list_policy_sets` returned `Upstream
+  error: expected array of …`. Parsers now accept both shapes
+  (envelope is unwrapped to the inner array; pagination metadata is
+  discarded since the tool DTOs return `readonly T[]`). Bug
+  surfaced by a real-org smoke run against a fresh
+  `/api/v1/custom-rules` instance. Other list parsers
+  (`parseScanPage`, `parseCampaignPage`, `parseAlertPage`) were
+  already envelope-aware; this brings the remaining two in line.
+
+- **HTTP transport: Streamable HTTP session continuity.** The
+  per-request handler used to spin up a fresh `McpServer` +
+  `StreamableHTTPServerTransport` on every POST, so the SDK state
+  built by `initialize` evaporated before `initialized` arrived and
+  every subsequent request returned 400 "Server not initialized".
+  The handler now caches the SDK transport keyed by session id and
+  swaps a per-request `ApiGateway` into a `ctxRef` indirection so the
+  bearer stays request-scoped (tenant-isolation rule #9 enforced via
+  the existing `SessionStore` bearer-hash equality check). Refactored
+  into three files (`http-request-handler.ts`,
+  `session-resolver.ts`, `mcp-session-factory.ts`) to stay under the
+  200-effective-line cap.
+- **HTTP transport: SIGTERM/SIGINT crash on startup.** Both
+  bootstraps used `import * as process from "node:process"`; the
+  namespace import does not expose `process.once` (it's on the
+  default export only), so the HTTP transport crashed immediately
+  with "process.once is not a function" — and no unit/isolation test
+  caught it because none of them spawned the real bootstrap.
+  Switched all three entrypoints (`bin.ts`, `stdio-bootstrap.ts`,
+  `http-bootstrap.ts`) to default `import process from "node:process"`
+  and added a CLI-smoke integration test that boots the built
+  `dist/bin.js` and probes `/healthz` + the full
+  `initialize → initialized → tools/list` session flow.
+- **stdio transport: pretty logs polluted the JSON-RPC stdout channel.**
+  Pino's `transport: { target: "pino-pretty" }` option spawns a worker
+  that defaults to `process.stdout` and ignores the destination
+  argument we passed to `pino()`. In stdio mode (MCP host reads
+  JSON-RPC from stdout) this corrupted every response. The pretty
+  format now uses a synchronous `pino-pretty` write stream wired to
+  `process.stderr` directly.
+- `pino-pretty` moved from `devDependencies` to `dependencies` so a
+  fresh `npx -y @kaminari-ad/mcp` install no longer crashes with
+  "unable to determine transport target".
+- `zod` pinned to `3.25.76` (was `3.24.1`). MCP SDK 1.29 ships a
+  transitive `zod-to-json-schema` that imports `zod/v3`, an export
+  introduced in zod 3.25 — the old pin would crash any consumer on
+  first import with `ERR_PACKAGE_PATH_NOT_EXPORTED`.
+
+## [0.1.0] - TBD
+
+Initial public release. The first version that ships to npm under
+`@kaminari-ad/mcp`.
+
+### Added
+
+- **MCP server** with two transports:
+  - **stdio** for local clients (Cursor, Claude Desktop, Cline, ...).
+    API key from `KAMINARI_AD_API_KEY` env var.
+  - **Streamable HTTP** for the hosted endpoint at
+    `https://mcp.kaminari.ad/mcp`. Per-request Bearer, per-request
+    `ApiGateway` closure, in-memory session store keyed by `SessionId`
+    (value: `sha256(bearer)`), leaky-bucket rate limit keyed by
+    `sha256(bearer)`.
+- **82 tools** spanning most of the `/api/v1` surface — account,
+  scans, campaigns, runs, campaign-groups, tag-definitions,
+  custom-rules, policy-sets, alerts, alert-notifications, webhooks,
+  billing, invoicing, geos, emulators. Every tool carries the
+  Anthropic Software Directory annotations (`title`, `readOnlyHint`,
+  `destructiveHint`, `idempotentHint`, `openWorldHint`).
+- **Tenant-isolation discipline** for the hosted HTTP mode, codified
+  as 16 rules in `CONTRIBUTING.md` and enforced by `tests/isolation/`
+  (bearer-swap, header-injection, env-fallback disabled, missing
+  auth, concurrent bearers, no-shared-state AST gate, token-not-in-
+  logs, error-path isolation).
+- **Type-safety**: every port DTO is a `Pick<components["schemas"][X],
+  ...>` projection over the generated `src/shared/api/openapi.ts`. A
+  future API field rename surfaces as a compile error in the parser.
+- **Quality gates** (all enforced by CI):
+  - TypeScript strict + 8 ESLint plugins.
+  - 4 custom architecture gates: file size (200 LOC), import
+    boundaries (dependency-cruiser with `tsPreCompilationDeps`),
+    no-shared-state (ts-morph AST walk), tool-naming.
+  - 100% lines / 100% functions / 100% statements coverage,
+    97% branches.
+  - Bundle size cap (500 KB on `dist/bin.js`, currently ~180 KB).
+  - `npm audit` with 0 vulnerabilities.
+- **Packaging**: ESM dist with shebang for `npx`, sourcemaps, type
+  declarations, npm provenance on release.
+
+### Security
+
+- `KAMINARI_AD_API_KEY` env var is **rejected on startup** in HTTP
+  mode (stdio only) — no fallback token can exist on a hosted server.
+- Bearer tokens are **never logged**. The `BearerToken` value object
+  overrides `toString` / `toJSON` /
+  `Symbol.for("nodejs.util.inspect.custom")` to return
+  `[BearerToken redacted]`.
+- pino is configured with redaction paths covering
+  `authorization` / `bearer` / `*.token` etc.
+- Outbound API calls carry an **explicit 5-key header allowlist**
+  (`authorization`, `content-type`, `accept`, `user-agent`,
+  `x-request-id`). No spread of inbound request headers.
+
+### Not yet (tracked as follow-ups)
+
+- **OAuth 2.1 + Dynamic Client Registration + PKCE** on the hosted
+  `mcp.kaminari.ad` endpoint, required by the Anthropic Software
+  Directory (§5.D) for remote MCP servers. v0.1.0 ships with raw
+  Bearer; OAuth lands in a follow-up MR.
+- Binary scan-screenshot fetchers (`/api/v1/scans/{id}/screenshot`
+  etc.) — agents rarely consume images directly. Reach out if you
+  need them.
+- Invoice PDF fetcher — same reason.
+
+[Unreleased]: https://github.com/kaminari-ad/mcp/compare/v0.1.0...HEAD
+[0.1.0]: https://github.com/kaminari-ad/mcp/releases/tag/v0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Kaminari Ad
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,159 @@
+# `@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).
+
+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)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+[![Provenance](https://img.shields.io/npm/v/@kaminari-ad/mcp?label=provenance&logo=github)](https://www.npmjs.com/package/@kaminari-ad/mcp)
+
+---
+
+## Quick start
+
+### 1. Sign up & get an API key
+
+1. Sign up at [https://app.kaminari.ad/signup](https://app.kaminari.ad/signup) (free tier, no card required).
+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.
+
+> 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)
+
+Add to your MCP client config (Cursor: `~/.cursor/mcp.json`; Claude Desktop: `~/Library/Application Support/Claude/claude_desktop_config.json`):
+
+```jsonc
+{
+  "mcpServers": {
+    "kaminari-ad": {
+      "command": "npx",
+      "args": ["-y", "@kaminari-ad/mcp"],
+      "env": {
+        "KAMINARI_AD_API_KEY": "kad_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
+      },
+    },
+  },
+}
+```
+
+Restart your client. You should see `kaminari-ad` in the MCP servers list with 82 tools exposed.
+
+### 2b. Hosted HTTP transport (no install)
+
+For cloud agents or clients without a local Node runtime, point at the hosted endpoint:
+
+```jsonc
+{
+  "mcpServers": {
+    "kaminari-ad": {
+      "url": "https://mcp.kaminari.ad/mcp",
+      "headers": {
+        "Authorization": "Bearer kad_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
+      },
+    },
+  },
+}
+```
+
+---
+
+## 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:
+
+- **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`
+- **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`
+- **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`
+- **Webhooks** (11) — `list_webhooks`, `get_webhook`, `create_webhook`, `update_webhook`, `delete_webhook`, `list_webhook_event_types`, `list_webhook_deliveries`, `test_webhook`, `rotate_webhook_secret`, `replay_webhook_delivery`, `bulk_replay_webhook`
+- **Billing** (4) — `get_billing_summary`, `list_usage`, `get_usage_summary`, `list_balance_history`
+- **Invoicing** (1) — `list_invoices`
+- **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.
+
+## Example agent prompts
+
+These three prompts each exercise a different cross-section of tools and demonstrate the typical agent workflow:
+
+1. **"Scan https://news.example.com/article-promo across US, UK, DE on mobile profiles, flag anything that redirects to a paywall."** Touches `list_emulators` → `create_bulk_scans` → wait → `list_scans` (status=completed) → `get_scan` → `list_scan_tags`.
+2. **"Create a campaign that re-checks the homepage of brand-x.com every hour from JP and US; alert me on Slack if it ever shows a malware tag."** Touches `list_emulators` → `list_policy_sets` (find one with `malware`) → `create_campaign` (schedule_enabled=true) → `list_alert_destinations` → `set_campaign_alert_overrides`.
+3. **"What did I spend on ad verification last month, and which campaigns drove the cost?"** Touches `get_usage_summary` → `list_usage` (with date_from/date_to) → group by `scan_id` → `get_scan` → `get_campaign` for attribution.
+
+Full machine-readable tool listing is exposed by the server itself — connect with any MCP client and call `tools/list`.
+
+---
+
+## Security & tenant isolation
+
+The hosted HTTP endpoint serves many organizations from a single process. We take cross-tenant isolation very seriously:
+
+- The MCP server is a strict, stateless, per-request pass-through. It forwards your `Authorization` header to the Kaminari Ad API verbatim and stores no per-tenant state between requests.
+- No caches, no in-memory data indexed by anything tenant-related.
+- `KAMINARI_AD_API_KEY` env var is rejected on startup in HTTP mode (stdio only) — no default fallback token exists.
+- Session IDs are bound to the SHA-256 of the Bearer that initialized them; reuse with a different Bearer is rejected.
+- Bearers are never logged. Only their 8-character hash prefix is recorded for correlation.
+- See [`tests/isolation/`](tests/isolation) for the regression suite that enforces every rule above on each CI run.
+
+To report a security issue, see [SECURITY.md](SECURITY.md).
+
+---
+
+## Development
+
+The Docker path (no local Node required for the build, but see [CONTRIBUTING](CONTRIBUTING.md) for the host-side commit hooks):
+
+```bash
+make check           # lint + format-check + typecheck + arch-gates + test-cov
+make test            # full test suite
+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`):
+
+```bash
+npm ci --legacy-peer-deps
+npm run lint && npm run typecheck && npm test
+```
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for the development workflow and how to add a tool.
+
+> The maintainers run the full development gate (integration tests, deploy automation, prod smoke) on a private GitLab instance and mirror the repo to GitHub. The public CI on GitHub Actions ([`.github/workflows/ci.yml`](.github/workflows/ci.yml)) runs lint + typecheck + unit tests + build + bundle-size check on every community PR, so contributors get fast green/red feedback without needing access to the internal infra. Tag pushes (`v*.*.*`) trigger [`.github/workflows/release.yml`](.github/workflows/release.yml), which publishes the package to npm with OIDC provenance and creates the GitHub Release.
+
+---
+
+## Stability
+
+The **public surface** of this package is:
+
+1. The **CLI binary** `kaminari-ad-mcp` and its `--transport stdio|http` flag, the env vars documented in `.env.example`, and the exit codes (0 / 1 fatal / 2 invalid config).
+2. The **MCP wire protocol** as implemented by every registered tool (tool names, input schemas, output shapes, annotations). Tools deprecated in a future major version will keep working for at least one minor version with a console warning.
+
+Everything else — the TypeScript types exported from `dist/bin.d.ts`, deep imports, internal class shapes — is **not** part of the public contract and may change in any release. Treat this package as a CLI, not a library.
+
+We follow [Semantic Versioning](https://semver.org/spec/v2.0.0.html) for the two items above. See [`CHANGELOG.md`](CHANGELOG.md) for the per-release record.
+
+---
+
+## Privacy
+
+- **Data collected by the MCP server itself:** none beyond the `Authorization` header it forwards. In HTTP mode, only ephemeral per-request scoped state (session id ↔ Bearer hash, leaky-bucket rate limit by Bearer hash) is held in memory.
+- **Data forwarded to Kaminari Ad:** every tool call is a thin pass-through to `/api/v1` over HTTPS. The Kaminari Ad privacy policy applies: [https://kaminari.ad/legal/privacy](https://kaminari.ad/legal/privacy).
+- **Logs:** structured pino output, JSON in HTTP mode. The full Bearer token is redacted; only `bearer_hash = sha256(token).slice(0,8)` makes it into a log line, alongside `request_id`, `tool_name`, `api_status`, `elapsed_ms`. Tool inputs (which may contain customer scan IDs / URLs) are NOT logged.
+- **Telemetry:** none. The OSS build ships a `NoopErrorReporter`. We do not bundle Sentry, OpenTelemetry exporters, or PostHog.
+
+To report a security or privacy issue, see [SECURITY.md](SECURITY.md).
+
+## License
+
+MIT — see [LICENSE](LICENSE).

package/SECURITY.md

@@ -0,0 +1,51 @@
+# Security Policy
+
+## Reporting a Vulnerability
+
+If you discover a security vulnerability in `@kaminari-ad/mcp` — particularly anything related to **cross-tenant data leakage** in the hosted HTTP endpoint — please report it privately.
+
+**Do NOT** open a public GitHub or GitLab issue, and do not discuss it in chat channels.
+
+### How to report
+
+Email **security@kaminari.ad** with:
+
+- A clear description of the issue.
+- Steps to reproduce (minimal repro preferred).
+- Affected version(s) (`npm view @kaminari-ad/mcp version` and/or the `mcp.kaminari.ad` deployment time, if known).
+- Your assessment of impact (data leak, auth bypass, DoS, etc.).
+- Whether you would like to be credited in the security advisory.
+
+You should receive an acknowledgement within 2 business days.
+
+### Disclosure timeline
+
+We follow a coordinated 90-day disclosure window:
+
+- **Day 0**: report received and acknowledged.
+- **Day 0-14**: triage and reproduction; severity assessment.
+- **Day 14-60**: fix developed, reviewed, tested, including a regression test in `tests/isolation/`.
+- **Day 60-90**: patched release published to npm; deployed to `mcp.kaminari.ad`; coordinated public disclosure with the reporter.
+- After **Day 90**, we will publish a security advisory regardless of whether a fix has shipped, so users can take their own mitigations.
+
+If the issue is being actively exploited in the wild, the timeline is compressed and we coordinate the disclosure with the reporter directly.
+
+## Scope
+
+Vulnerabilities of particular interest:
+
+- **Tenant isolation breaches** in the HTTP transport: any way for one client's request to receive data from another client's session, log, cache, or in-flight request.
+- **Token leakage**: any way a Bearer token can be reconstructed from logs, error responses, telemetry, or process memory exposed to operators.
+- **Auth bypass**: any way to call a tool without a valid `Authorization` header or with a header that has been mutated by the MCP server.
+- **Header injection**: any way to influence the outbound request to the Kaminari Ad API by injecting `X-*` headers, cookies, or other channels.
+- **Supply-chain compromise**: any anomaly in the published npm package, the Docker image, or the GitLab/GitHub release pipeline.
+
+Out of scope:
+
+- Issues in the Kaminari Ad API itself (`/api/v1`). The API enforces its own authorization. Report API issues to the same `security@kaminari.ad` address, but note they live in the `api/` repository, not here.
+- Issues in third-party MCP clients (Cursor, Claude Desktop, etc.).
+- Theoretical issues with no demonstrable exploit path.
+
+## Recognition
+
+With your permission, we will acknowledge your contribution in the [`CHANGELOG.md`](CHANGELOG.md) and in the GitHub security advisory.

package/dist/bin.d.ts

@@ -0,0 +1,2 @@
+
+export {  }