@kaminari-ad/mcp 0.24.2 → 0.26.0

package/CHANGELOG.md

@@ -7,6 +7,45 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.26.0] - 2026-10-06
+
+> Requires the API-side bulk parity deploy. Until it lands, the API
+> silently ignores the new `create_bulk_scans` fields. Do not tag this
+> release ahead of the API.
+
+### Added
+
+- **`create_bulk_scans` takes the same optional fields as `create_scan`.**
+  `campaign_id`, `run_id`, `ad_discovery`, `max_discovered_ads` and
+  `ad_formats` apply to every country in the batch. With a `campaign_id`,
+  bulk scans can raise alerts.
+
+### Changed
+
+- **`campaign_id` explains that alerts depend on it**, on both scan tools.
+  The three shared fields now live in one module, so the two tools'
+  descriptions cannot drift. Request schemas are regenerated from the API,
+  and country codes are documented as case-insensitive.
+
+## [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

package/README.md

@@ -115,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`
@@ -123,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`

package/dist/bin.js

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-import { NAME, VERSION, err, ok } from './chunk-4P6CNASK.js';
+import { NAME, VERSION, err, ok } from './chunk-DZ5IF6SC.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-M4TOIBTL.js');
+    const { bootstrapStdio } = await import('./stdio-bootstrap-SD25OPK7.js');
     return bootstrapStdio(config);
   }
-  const { bootstrapHttp } = await import('./http-bootstrap-KBFALUIO.js');
+  const { bootstrapHttp } = await import('./http-bootstrap-AR3RJBCT.js');
   return bootstrapHttp(config);
 }
 main().then(

package/dist/{chunk-4P6CNASK.js → chunk-DZ5IF6SC.js}

@@ -3,8 +3,8 @@ export { err, ok } from 'neverthrow';
 
 // src/shared/version.ts
 var NAME = "@kaminari-ad/mcp";
-var VERSION = "0.24.2";
+var VERSION = "0.26.0";
 
 export { NAME, VERSION };
-//# sourceMappingURL=chunk-4P6CNASK.js.map
-//# sourceMappingURL=chunk-4P6CNASK.js.map
+//# sourceMappingURL=chunk-DZ5IF6SC.js.map
+//# sourceMappingURL=chunk-DZ5IF6SC.js.map

package/dist/{chunk-4P6CNASK.js.map → chunk-DZ5IF6SC.js.map}

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

package/dist/{chunk-GPJ6BQNP.js → chunk-G5DUWW6D.js}

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-import { err, ok } from './chunk-4P6CNASK.js';
+import { err, ok } from './chunk-DZ5IF6SC.js';
 import { createHash, randomUUID } from 'crypto';
 import createClient from 'openapi-fetch';
 import { fetch } from 'undici';
@@ -262,7 +262,6 @@ z.object({
   vast_tag: z.union([z.string(), z.null()]).optional(),
   referrer: z.union([z.string(), z.null()]).optional(),
   ignore_first_n_domains: z.number().int().gte(0).lte(5).optional().default(0),
-  country_code: z.string().min(2).max(2),
   emulator_id: z.string().min(1).max(100),
   proxy: ProxyTargetRequest.optional(),
   labels: z.record(z.string()).optional(),
@@ -273,7 +272,8 @@ z.object({
   ad_formats: z.union([z.array(AdKind), z.null()]).optional(),
   repeat_count: z.number().int().gte(1).optional().default(1),
   repeat_mode: RepeatModeType.optional(),
-  retry_max_attempts: z.number().int().gte(0).optional().default(0)
+  retry_max_attempts: z.number().int().gte(0).optional().default(0),
+  country_code: z.string().min(2).max(2)
 }).passthrough();
 var ScanStatus = z.enum([
   "pending",
@@ -461,13 +461,18 @@ z.object({
   vast_tag: z.union([z.string(), z.null()]).optional(),
   referrer: z.union([z.string(), z.null()]).optional(),
   ignore_first_n_domains: z.number().int().gte(0).lte(5).optional().default(0),
-  country_codes: z.array(z.string()).min(1),
   emulator_id: z.string().min(1).max(100),
   proxy: ProxyTargetRequest.optional(),
   labels: z.record(z.string()).optional(),
+  campaign_id: z.union([z.string(), z.null()]).optional(),
+  run_id: z.union([z.string(), z.null()]).optional(),
+  ad_discovery: z.boolean().optional().default(false),
+  max_discovered_ads: z.union([z.number(), z.null()]).optional(),
+  ad_formats: z.union([z.array(AdKind), z.null()]).optional(),
   repeat_count: z.number().int().gte(1).optional().default(1),
   repeat_mode: RepeatModeType.optional(),
-  retry_max_attempts: z.number().int().gte(0).optional().default(0)
+  retry_max_attempts: z.number().int().gte(0).optional().default(0),
+  country_codes: z.array(z.string().min(2).max(2)).min(1)
 }).passthrough();
 z.object({
   scope_type: z.enum(["last_n", "hours"]),
@@ -789,6 +794,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 +1301,8 @@ var schemas = {
   TagDefinitionDetailResponse,
   CustomRuleResponse,
   RuleTestResponse,
+  RuleTestBatchRequest,
+  RuleTestBatchResponse,
   PolicyEntryResponse,
   LinkedCampaignResponse,
   PolicySetResponse,
@@ -1628,6 +1666,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 +2568,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 +4575,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(
@@ -5381,6 +5482,15 @@ var cancelScanTool = {
     return ok(result.value);
   }
 };
+var scanCampaignIdField = z.string().uuid().optional().describe(
+  "Optional campaign UUID to attribute the scan to. Required for alerts: policies are attached to campaigns, so a scan without a campaign is checked and tagged but never raises an alert."
+);
+var scanRunIdField = z.string().uuid().optional().describe(
+  "Optional run UUID inside the campaign. Omit it to join the campaign's API run for the day."
+);
+var scanAdDiscoveryField = z.boolean().optional().describe(
+  "Publisher ad discovery: detect ad blocks on the page and spawn one child scan per detected ad (banner/video/pop). Only valid with `url`. Each child is a separate billed scan; list them with `list_scan_children`."
+);
 var scanProxyField = z.object({
   proxy_type: z.enum(["residential", "mobile"]).optional().describe(
     "Proxy network type. Default: residential. Residential and mobile are separate pools with separate catalogues, so pass the same value to `get_proxy_targeting` that you send here."
@@ -5412,15 +5522,22 @@ var CreateBulkScansInputShape = {
   ),
   referrer: scanReferrerField,
   ignore_first_n_domains: ignoreFirstNDomainsScanField,
-  country_codes: z.array(z.string().length(2)).min(1).max(50).describe("List of ISO 3166-1 alpha-2 country codes; one scan per country is created."),
+  country_codes: z.array(z.string().length(2)).min(1).max(50).describe(
+    "List of ISO 3166-1 alpha-2 country codes, any case; one scan per country is created."
+  ),
   emulator_id: z.string().min(1).max(100).describe("Device/OS profile slug; same for every country in the batch."),
   proxy: scanProxyField,
   labels: z.record(z.string()).optional().describe("Arbitrary metadata copied onto every created scan."),
+  campaign_id: scanCampaignIdField,
+  run_id: scanRunIdField,
+  ad_discovery: scanAdDiscoveryField,
+  max_discovered_ads: maxDiscoveredAdsField,
+  ad_formats: adFormatsField,
   ...repeatRetryFields
 };
 var createBulkScansTool = {
   name: "create_bulk_scans",
-  description: "Queue one new scan per country in a single call (e.g. test the same URL, ad-tag, or VAST video tag from US + DE + JP). COSTS N CREDITS where N = number of countries times `repeat_count`. Returns one entry per country; each entry's `repeat_scan_ids` lists that country's extra repeats.",
+  description: "Queue one new scan per country in a single call (e.g. test the same URL, ad-tag, or VAST video tag from US + DE + JP). Every other field applies to each country, `campaign_id` included. COSTS N CREDITS where N = number of countries times `repeat_count`. Returns one entry per country; each entry's `repeat_scan_ids` lists that country's extra repeats.",
   annotations: {
     title: "Create Bulk Scans",
     readOnlyHint: false,
@@ -5440,6 +5557,11 @@ var createBulkScansTool = {
       ...input.ignore_first_n_domains !== void 0 ? { ignore_first_n_domains: input.ignore_first_n_domains } : {},
       ...input.proxy !== void 0 ? { proxy: input.proxy } : {},
       ...input.labels !== void 0 ? { labels: input.labels } : {},
+      ...input.campaign_id !== void 0 ? { campaign_id: input.campaign_id } : {},
+      ...input.run_id !== void 0 ? { run_id: input.run_id } : {},
+      ...input.ad_discovery !== void 0 ? { ad_discovery: input.ad_discovery } : {},
+      ...input.max_discovered_ads !== void 0 ? { max_discovered_ads: input.max_discovered_ads } : {},
+      ...input.ad_formats !== void 0 ? { ad_formats: input.ad_formats } : {},
       ...pickRepeatRetryBody(input)
     };
     const result = await ctx.api.createBulkScans(body);
@@ -5463,11 +5585,9 @@ var CreateScanInputShape = {
   emulator_id: z.string().min(1).max(100).describe("Device/OS profile slug; use `list_emulators` to discover valid values."),
   proxy: scanProxyField,
   labels: z.record(z.string()).optional().describe("Arbitrary string -> string metadata attached to the scan."),
-  campaign_id: z.string().uuid().optional().describe("Optional campaign UUID to attribute the scan to."),
-  run_id: z.string().uuid().optional().describe("Optional run UUID inside the campaign."),
-  ad_discovery: z.boolean().optional().describe(
-    "Publisher ad discovery: detect ad blocks on the page and spawn one child scan per detected ad (banner/video/pop). Only valid with `url`. Each child is a separate billed scan; list them with `list_scan_children`."
-  ),
+  campaign_id: scanCampaignIdField,
+  run_id: scanRunIdField,
+  ad_discovery: scanAdDiscoveryField,
   max_discovered_ads: maxDiscoveredAdsField,
   ad_formats: adFormatsField,
   ...repeatRetryFields
@@ -6263,6 +6383,7 @@ function registerAllTools(register) {
   register(updateCustomRuleTool);
   register(deleteCustomRuleTool);
   register(testCustomRuleTool);
+  register(testCustomRulesBatchTool);
   register(listCustomTaxonomiesTool);
   register(getCustomTaxonomyTool);
   register(createCustomTaxonomyTool);
@@ -6387,5 +6508,5 @@ function formatToolError(error) {
 }
 
 export { BearerToken, SERVER_INSTRUCTIONS, createHttpApiGateway, createPinoLogger, declareEmptyResourcesAndPrompts, newRequestId, wireToolsIntoMcpServer };
-//# sourceMappingURL=chunk-GPJ6BQNP.js.map
-//# sourceMappingURL=chunk-GPJ6BQNP.js.map
+//# sourceMappingURL=chunk-G5DUWW6D.js.map
+//# sourceMappingURL=chunk-G5DUWW6D.js.map