@kaminari-ad/mcp 0.24.1 → 0.25.0

package/CHANGELOG.md

@@ -7,6 +7,42 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.25.0] - 2026-10-04
+
+> Requires the API-side batch rule test deploy. Until it lands, the tool
+> gets 404 from `POST /api/v1/custom-rules/test-batch`. Do not tag this
+> release ahead of the API.
+
+### Added
+
+- **`test_custom_rules_batch`.** Preview up to 20 unsaved rule definitions
+  against up to 50 stored scans in one call, instead of chaining
+  `test_custom_rule`. The reply is one cell per rule and scan plus counts.
+  A cell that could not run carries `error` and `error_code` without
+  failing the rest. `deadline_exceeded` means the call ran out of time
+  before that cell, and the agent re-sends just those cells. A
+  rate-limited error means the organization already has a batch running.
+  Request and response schemas are regenerated from the API. The scan cap
+  comes from the generated schema; the 20-rule cap is restated in the tool
+  because each rule carries its own agent-facing field descriptions.
+
+## [0.24.2] - 2026-10-03
+
+### Added
+
+- **Listed in the official MCP Registry.** Every release tag now publishes
+  `server.json` to `registry.modelcontextprotocol.io` as
+  `io.github.kaminari-ad/mcp`, with both the npm package and the hosted
+  `https://mcp.kaminari.ad/mcp` endpoint. `package.json` carries the matching
+  `mcpName` the registry uses to verify package ownership.
+
+### Fixed
+
+- **README privacy link.** It pointed at `kaminari.ad/legal/privacy`, which
+  returns 404; it now points at `kaminari.ad/privacy`.
+- **npm homepage** now points at `https://kaminari.ad/mcp` instead of the
+  GitHub repository.
+
 ## [0.24.1] - 2026-10-02
 
 ### Fixed

package/README.md

@@ -10,7 +10,7 @@ Lets AI agents (Cursor, Claude Desktop, Cline, and any MCP-compatible client) la
 [![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)
+[![MCP Registry](https://img.shields.io/badge/MCP_Registry-listed-blue)](https://registry.modelcontextprotocol.io/v0/servers?search=io.github.kaminari-ad/mcp)
 
 ## Install (one click)
 
@@ -18,6 +18,8 @@ Lets AI agents (Cursor, Claude Desktop, Cline, and any MCP-compatible client) la
 
 <a href="https://kaminari.ad/mcp/install"><img alt="Install in Cursor" src="https://cursor.com/deeplink/mcp-install-dark.png" height="32" /></a>
 
+What the server can do and how to connect any client: [Kaminari Ad MCP overview](https://kaminari.ad/mcp).
+
 ### 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.
@@ -113,7 +115,7 @@ which decides which credential type minted it.
 
 ## Tools
 
-108 tools covering 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. The complete list, by domain:
+109 tools covering 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. The complete list, by domain:
 
 - **Account** (14) — `get_account`, `update_org`, `list_org_users`, `invite_user`, `update_user_role`, `remove_user`, `transfer_ownership`, `list_org_roles`, `create_custom_role`, `list_account_labels`, `update_account_labels`, `list_api_keys`, `create_api_key`, `revoke_api_key`
 - **Scans** (13) — `list_scans`, `get_scan`, `list_scan_children`, `create_scan`, `create_bulk_scans`, `recheck_scans`, `cancel_scan`, `get_scan_screenshot`, `get_scan_creative_screenshot`, `get_scan_landing_screenshot`, `get_scan_creative_html`, `get_scan_creative_video`, `get_scan_vast_xml`
@@ -121,7 +123,7 @@ which decides which credential type minted it.
 - **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** (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`
+- **Custom rules** (7) — `list_custom_rules`, `get_custom_rule`, `create_custom_rule`, `update_custom_rule`, `delete_custom_rule`, `test_custom_rule`, `test_custom_rules_batch`
 - **Custom taxonomies** (7) — `list_custom_taxonomies`, `get_custom_taxonomy`, `create_custom_taxonomy`, `update_custom_taxonomy`, `delete_custom_taxonomy`, `restore_custom_taxonomy`, `parse_custom_taxonomy_text`
 - **Policy sets** (11) — `list_policy_sets`, `get_policy_set`, `create_policy_set`, `update_policy_set`, `delete_policy_set`, `request_policy_set_approval`, `unpublish_policy_set`, `set_default_policy_set`, `list_policy_set_campaigns`, `attach_policy_set_campaigns`, `detach_policy_set_campaigns`
 - **Alerts** (4) — `list_alerts`, `update_alert_status`, `bulk_update_alert_status`, `get_alert_stats`
@@ -182,7 +184,7 @@ 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.
+> 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, creates the GitHub Release and publishes [`server.json`](server.json) to the official MCP Registry.
 
 ---
 
@@ -202,12 +204,20 @@ We follow [Semantic Versioning](https://semver.org/spec/v2.0.0.html) for the two
 ## Privacy
 
 - **Data collected by the MCP server itself:** none beyond the `Authorization` header it forwards. The HTTP transport is stateless — no sessions are persisted; each request is authenticated independently by its own Bearer. The only in-memory state is the leaky-bucket rate limiter keyed by `sha256(bearer)`.
-- **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).
+- **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/privacy](https://kaminari.ad/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).
 
+## Learn more
+
+- [Kaminari Ad MCP overview](https://kaminari.ad/mcp) — what agents can do with the server, with setup for every client.
+- [MCP server developer docs](https://kaminari.ad/docs/developers/mcp-server) — transports, authentication and OAuth connected apps.
+- [REST API quickstart](https://kaminari.ad/docs/developers/rest-quickstart) — the `/api/v1` surface every tool calls.
+- [Malvertising, auto-redirect and cloaking detections](https://kaminari.ad/detections) — what a scan verdict can flag.
+- [DarkSword in the ad stack: an iOS exploit chain](https://kaminari.ad/blog/darksword-ios-exploit-chain-in-ad-traffic) — research from the Kaminari Ad team.
+
 ## License
 
 MIT — see [LICENSE](LICENSE).

package/dist/bin.js

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-import { NAME, VERSION, err, ok } from './chunk-3G2F3FOW.js';
+import { NAME, VERSION, err, ok } from './chunk-IG36AHO3.js';
 import process from 'process';
 import { z } from 'zod';
 
@@ -162,10 +162,10 @@ async function main() {
   }
   const config = configResult.value;
   if (config.transport === "stdio") {
-    const { bootstrapStdio } = await import('./stdio-bootstrap-VGOUNXAK.js');
+    const { bootstrapStdio } = await import('./stdio-bootstrap-3IOUWYG3.js');
     return bootstrapStdio(config);
   }
-  const { bootstrapHttp } = await import('./http-bootstrap-6PQSTYXB.js');
+  const { bootstrapHttp } = await import('./http-bootstrap-6L4VQJRM.js');
   return bootstrapHttp(config);
 }
 main().then(

package/dist/{chunk-3G2F3FOW.js → chunk-IG36AHO3.js}

@@ -3,8 +3,8 @@ export { err, ok } from 'neverthrow';
 
 // src/shared/version.ts
 var NAME = "@kaminari-ad/mcp";
-var VERSION = "0.24.1";
+var VERSION = "0.25.0";
 
 export { NAME, VERSION };
-//# sourceMappingURL=chunk-3G2F3FOW.js.map
-//# sourceMappingURL=chunk-3G2F3FOW.js.map
+//# sourceMappingURL=chunk-IG36AHO3.js.map
+//# sourceMappingURL=chunk-IG36AHO3.js.map

package/dist/{chunk-3G2F3FOW.js.map → chunk-IG36AHO3.js.map}

@@ -1 +1 @@
-{"version":3,"sources":["../src/shared/version.ts"],"names":[],"mappings":";;;;AASO,IAAM,IAAA,GAAO;AACb,IAAM,OAAA,GAAU","file":"chunk-3G2F3FOW.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.24.1\";\n"]}
+{"version":3,"sources":["../src/shared/version.ts"],"names":[],"mappings":";;;;AASO,IAAM,IAAA,GAAO;AACb,IAAM,OAAA,GAAU","file":"chunk-IG36AHO3.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.25.0\";\n"]}

package/dist/{chunk-LPABQWHJ.js → chunk-MIDK3IA2.js}

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-import { err, ok } from './chunk-3G2F3FOW.js';
+import { err, ok } from './chunk-IG36AHO3.js';
 import { createHash, randomUUID } from 'crypto';
 import createClient from 'openapi-fetch';
 import { fetch } from 'undici';
@@ -789,6 +789,37 @@ var RuleTestResponse = z.object({
   llm_prompt_url: z.string().optional().default(""),
   llm_response_url: z.string().optional().default("")
 }).passthrough();
+var RuleTestBatchRule = z.object({
+  id: z.union([z.string(), z.null()]).optional(),
+  rule_type: z.string(),
+  config: z.object({}).partial().passthrough(),
+  target: z.string().optional().default("page"),
+  name: z.string().optional().default("Test Rule")
+}).passthrough();
+var RuleTestBatchRequest = z.object({
+  rules: z.array(RuleTestBatchRule).min(1).max(20),
+  scan_ids: z.array(z.string().uuid()).min(1).max(50)
+}).passthrough();
+var RuleTestBatchCell = z.object({
+  index: z.number().int(),
+  rule_id: z.union([z.string(), z.null()]).optional(),
+  scan_id: z.string().uuid(),
+  matched: z.boolean(),
+  tags: z.array(RuleTestTagResult),
+  elapsed_ms: z.number().int(),
+  error: z.union([z.string(), z.null()]).optional(),
+  error_code: z.union([z.string(), z.null()]).optional()
+}).passthrough();
+var RuleTestBatchSummary = z.object({
+  total: z.number().int(),
+  matched: z.number().int(),
+  failed: z.number().int(),
+  deadline_exceeded: z.number().int()
+}).passthrough();
+var RuleTestBatchResponse = z.object({
+  results: z.array(RuleTestBatchCell),
+  summary: RuleTestBatchSummary
+}).passthrough();
 var IabV3PolicyCategoryRequest = z.object({
   tier1: z.string().min(1).max(200),
   tier2: z.union([z.string(), z.null()]).optional(),
@@ -1265,6 +1296,8 @@ var schemas = {
   TagDefinitionDetailResponse,
   CustomRuleResponse,
   RuleTestResponse,
+  RuleTestBatchRequest,
+  RuleTestBatchResponse,
   PolicyEntryResponse,
   LinkedCampaignResponse,
   PolicySetResponse,
@@ -1628,6 +1661,7 @@ var RuleTestSchema = schemas.RuleTestResponse.pick({
   tags: true
 }).strip();
 var parseRuleTest = (raw) => parseWithSchema(RuleTestSchema, raw, "rule-test");
+var parseRuleTestBatch = (raw) => parseWithSchema(schemas.RuleTestBatchResponse.strip(), raw, "rule-test-batch");
 var AlertStatsSchema = schemas.AlertStatsResponse.pick({
   open: true,
   escalated: true,
@@ -2529,6 +2563,9 @@ function createHttpApiGateway(config) {
     async testCustomRule(body) {
       return call("POST", "/api/v1/custom-rules/test", { body }, parseRuleTest);
     },
+    async testCustomRulesBatch(body) {
+      return call("POST", "/api/v1/custom-rules/test-batch", { body }, parseRuleTestBatch);
+    },
     // ── Policy sets ───────────────────────────────────────────────
     async listPolicySets(filters) {
       return call("GET", "/api/v1/policy-sets", { params: { query: filters } }, parsePolicySetPage);
@@ -4533,6 +4570,65 @@ var testCustomRuleTool = {
     return ok(result.value);
   }
 };
+var TestCustomRulesBatchInputShape = {
+  rules: z.array(
+    z.object({
+      id: z.string().uuid().optional().describe(
+        "Optional UUID you choose to tell rules apart in the reply; echoed back as rule_id. The API accepts only a UUID here. It is not looked up and does not select a saved rule."
+      ),
+      rule_type: z.string().max(50).describe(
+        "Rule engine type. Same set as `test_custom_rule`: `stopword_content`, `stopword_url`, `regexp_content`, `regexp_url`, `regexp_request_url`, `regexp_request_body`, `blacklist_domain`, `combo`, `llm`."
+      ),
+      config: patternAwareRuleConfigField.describe(
+        "Rule-type-specific config. Same shape as `test_custom_rule`'s `config`. " + PATTERN_RULE_CONFIG_DOC + " " + COMBO_MATCH_SCOPE_DOC
+      ),
+      target: z.string().max(30).default("page").describe(
+        "Where to apply the rule. Defaults to 'page'. `regexp_request_url` and `regexp_request_body` also accept 'creative' and 'creative_and_page'."
+      ),
+      name: z.string().min(1).max(200).default("Test Rule").describe(
+        "Label the LLM prompt quotes as [USER RULE: \"<name>\"]. Same field as the single test. Defaults to 'Test Rule', which is what that test sends when name is omitted. Capped at 200 like `create_custom_rule`'s name, so a draft that tests well can be saved as is."
+      )
+    })
+  ).min(1).max(20).describe("Up to 20 rules. Every rule runs against every scan in `scan_ids`."),
+  scan_ids: schemas.RuleTestBatchRequest.shape.scan_ids.describe(
+    "Up to 50 stored scan UUIDs. Testing one rule against many scans is the usual case."
+  )
+};
+var testCustomRulesBatchTool = {
+  name: "test_custom_rules_batch",
+  description: "Preview-test up to 20 rule definitions against up to 50 stored scans in one call, without saving them. Returns one cell per rule and scan; a cell's `index` is the rule's position in `rules`, so pair it with `scan_id` to identify the cell. A rule definition the API rejects fails the whole call as invalid input before anything runs. Otherwise a cell that could not run has `error` and `error_code` and never fails the rest: `deadline_exceeded` means the call ran out of time before that cell (about 110s per call) \u2014 call again with just those rules and scans; others are `timed_out`, `llm_failed`, `content_prohibited`, `scan_not_found`, `invalid_rule`, `failed`. `summary.failed` counts every cell with an error and `summary.deadline_exceeded` is the part of them the deadline cut off. A rate-limited error means this organization already has a batch running; wait for it. Many AI (`llm`) rules over many scans are better split across calls. Historical limits match `test_custom_rule`: `regexp_request_body` only has captured bodies for the last day, and `regexp_request_url` on a stored scan is best-effort.",
+  annotations: {
+    title: "Test Custom Rules Batch",
+    readOnlyHint: true,
+    destructiveHint: false,
+    idempotentHint: true,
+    openWorldHint: false
+  },
+  inputSchema: z.object(TestCustomRulesBatchInputShape),
+  handler: async (input, ctx) => {
+    for (const [index, rule] of input.rules.entries()) {
+      const inputError = patternRuleInputError(rule);
+      if (inputError?.kind === "invalid-input") {
+        const message = "rules[" + String(index) + "]: " + inputError.message;
+        return err(
+          inputError.fieldErrors === void 0 ? { kind: "invalid-input", message } : { kind: "invalid-input", message, fieldErrors: inputError.fieldErrors }
+        );
+      }
+    }
+    const result = await ctx.api.testCustomRulesBatch({
+      rules: input.rules.map((rule) => ({
+        rule_type: rule.rule_type,
+        config: rule.config,
+        target: rule.target,
+        name: rule.name,
+        ...rule.id === void 0 ? {} : { id: rule.id }
+      })),
+      scan_ids: input.scan_ids
+    });
+    if (result.isErr()) return err(mapApiError(result.error));
+    return ok(result.value);
+  }
+};
 var UpdateCustomRuleInputShape = {
   rule_id: z.string().uuid().describe("Rule UUID to update."),
   name: z.string().min(1).max(200).optional().describe(
@@ -6263,6 +6359,7 @@ function registerAllTools(register) {
   register(updateCustomRuleTool);
   register(deleteCustomRuleTool);
   register(testCustomRuleTool);
+  register(testCustomRulesBatchTool);
   register(listCustomTaxonomiesTool);
   register(getCustomTaxonomyTool);
   register(createCustomTaxonomyTool);
@@ -6387,5 +6484,5 @@ function formatToolError(error) {
 }
 
 export { BearerToken, SERVER_INSTRUCTIONS, createHttpApiGateway, createPinoLogger, declareEmptyResourcesAndPrompts, newRequestId, wireToolsIntoMcpServer };
-//# sourceMappingURL=chunk-LPABQWHJ.js.map
-//# sourceMappingURL=chunk-LPABQWHJ.js.map
+//# sourceMappingURL=chunk-MIDK3IA2.js.map
+//# sourceMappingURL=chunk-MIDK3IA2.js.map