@kaminari-ad/mcp 0.10.0 → 0.12.0

package/CHANGELOG.md

@@ -7,6 +7,97 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.12.0] - 2026-08-07
+
+### Security
+
+- **Bump `undici` 8.5.0 to 8.10.0** to clear the npm-audit gate after the
+  upstream disclosure of one high-severity advisory
+  (GHSA-4cwx-7wf7-3272 — a malformed `private` Cache-Control directive
+  makes a shared cache store a per-user response and serve it to other
+  users) and four medium ones (GHSA-jr45-8vmc-qm54,
+  GHSA-m8rv-5g2x-5cg5, GHSA-8xcm-r25x-g524, GHSA-v3r7-h72x-cjcm). All
+  five are fixed in 8.9.0. `undici` is a direct dependency.
+
+### Changed
+
+- **Requires api >= v1.33.0 for the webhook tools.** The regenerated zod
+  schemas make `failing_since` and `paused_until` required on
+  `EndpointHealthResponse`, and the webhook parser picks the whole nested
+  `health` object, so against an older API every webhook tool
+  (`list_webhooks`, `get_webhook`, `create_webhook`, `update_webhook`,
+  `rotate_webhook_secret`) fails with
+  `upstream: malformed webhook: health.failing_since: Invalid input`.
+- **README tool list matches the registry again.** It documented 83 tools
+  and had drifted 15 behind: the custom-taxonomy domain, the three
+  screenshot fetchers, `get_invoice_pdf`, `list_scan_children`,
+  `create_custom_role`, and the two account-label tools were all
+  registered but undocumented — and the screenshot fetchers and invoice
+  PDF were still listed as deliberately not exposed.
+- **`get_alert_stats` counts all time.** The API used to count only the last
+  30 days when no dates were given, while `list_alerts` listed all time, so
+  the four buckets never summed to the list's `total`. The API now defaults
+  both to all time; the tool description says so, so a model comparing the
+  two no longer has to guess which window it got. Requires the API deploy
+  that ships the new default — against an older API the counts still cover
+  30 days.
+- **Regenerated `/api/v1` types and zod schemas.** Picks up the new alert
+  filters (`policy_set_id`, `tag`, `country_code`, `date_from`, `date_to`,
+  `timezone` on list + stats, and the matching `filter_*` fields on
+  bulk-status), `policy_set_name` on `AlertResponse`, plus drift that had
+  accumulated since the last regen: `last_run_at` on campaign groups,
+  campaign/group date filters, and `failing_since` / `paused_until` on
+  webhook endpoint health.
+
+## [0.11.0] - 2026-07-28
+
+### Added
+
+- **Combo-rule match scope.** `create_custom_rule`, `update_custom_rule`, and
+  `test_custom_rule` now document the rule-level `config.match_scope` key used
+  by `rule_type='combo'`: `"scan"` (the default, and the behaviour when the key
+  is absent) counts conditions across the union of all tags on the scan, while
+  `"url"` requires every condition to be satisfied by tags on the same link and
+  assigns the output tag to that link. The description warns about the traps a
+  per-link rule falls into: a combo built only from link-less tags (AI verdicts,
+  crawler behaviour) has no link to attach to and never matches, AI verdicts and
+  per-link detections are not evaluated together today, and a per-link rule needs
+  at least one positive condition. Any other `match_scope` value is rejected
+  before the request is sent, so a misspelled scope surfaces as a tool-input
+  error instead of a round trip; the API validates `match_scope` on create,
+  update, and the rule-test preview as well, so this is early feedback rather
+  than the durable guarantee. The rest of a combo config is still validated only
+  for admin-authored system rules, which is why the per-link traps are documented
+  rather than enforced. `get_custom_rule` and `list_custom_rules` now flag that
+  the returned `config` may carry `match_scope` and that it must be resent
+  verbatim, since `update_custom_rule` replaces `config` wholesale.
+- **`referrer` on scan and campaign creation.** `create_scan`,
+  `create_bulk_scans`, `create_campaign`, and `update_campaign` accept an
+  optional http(s) page URL the check is performed from. With `ad_tag` or
+  `vast_tag` it is the publisher page the tag is embedded in: the browser
+  commits the page document on that URL without fetching the publisher, so the
+  creative renders as if embedded there. With `url` or `ad_discovery` it is
+  where the visitor came from, sent as the `Referer` of the page request.
+  `update_campaign` also accepts `referrer: null` to clear a stored one.
+  Scan and campaign responses surface `referrer` too, so an agent can confirm
+  what a scan actually ran with.
+
+  **Release ordering — this depends on an unreleased API.** The snapshots were
+  generated from api `feat/scan-referrer`
+  ([api!341](https://gitlab.sdev.pw/adverif/api/-/merge_requests/341)). API
+  request DTOs are `extra="ignore"`, so an API without the field drops
+  `referrer` silently: no 422, the scan runs with no referrer, and the response
+  carries no `referrer` key — the agent gets a green result for a check it
+  believes ran from a publisher page. **Do not cut the npm tag or the
+  `kaminariad-mcp` image until api!341 is merged and deployed to
+  `kaminariadprod1`.** Nothing automated enforces this.
+
+### Changed
+
+- Regenerated the OpenAPI type + zod-schema snapshots so the `/api/v1` surface
+  they describe carries `referrer`. That field is their only delta versus the
+  0.10.0 snapshots.
+
 ## [0.10.0] - 2026-07-28
 
 ### Added
@@ -934,7 +1025,16 @@ Initial public release. The first version that ships to npm under
   need them.
 - Invoice PDF fetcher — same reason.
 
-[Unreleased]: https://github.com/kaminari-ad/mcp/compare/v0.2.1...HEAD
+[Unreleased]: https://github.com/kaminari-ad/mcp/compare/v0.12.0...HEAD
+[0.12.0]: https://github.com/kaminari-ad/mcp/compare/v0.11.0...v0.12.0
+[0.11.0]: https://github.com/kaminari-ad/mcp/compare/v0.10.0...v0.11.0
+[0.10.0]: https://github.com/kaminari-ad/mcp/compare/v0.8.0...v0.10.0
+[0.8.0]: https://github.com/kaminari-ad/mcp/compare/v0.6.0...v0.8.0
+[0.6.0]: https://github.com/kaminari-ad/mcp/compare/v0.5.2...v0.6.0
+[0.5.2]: https://github.com/kaminari-ad/mcp/compare/v0.5.0...v0.5.2
+[0.5.0]: https://github.com/kaminari-ad/mcp/compare/v0.3.0...v0.5.0
+[0.3.0]: https://github.com/kaminari-ad/mcp/compare/v0.2.2...v0.3.0
+[0.2.2]: https://github.com/kaminari-ad/mcp/compare/v0.2.1...v0.2.2
 [0.2.1]: https://github.com/kaminari-ad/mcp/compare/v0.2.0...v0.2.1
 [0.2.0]: https://github.com/kaminari-ad/mcp/compare/v0.1.5...v0.2.0
 [0.1.5]: https://github.com/kaminari-ad/mcp/compare/v0.1.0...v0.1.5

package/README.md

@@ -63,7 +63,7 @@ Add to your MCP client config (Cursor: `~/.cursor/mcp.json`; Claude Desktop: `~/
 }
 ```
 
-Restart your client. You should see `kaminari-ad` in the MCP servers list with 83 tools exposed.
+Restart your client. You should see `kaminari-ad` in the MCP servers list with 98 tools exposed.
 
 ### 2b. Hosted HTTP transport (no install)
 
@@ -113,24 +113,27 @@ which decides which credential type minted it.
 
 ## Tools
 
-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:
+98 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. The complete list, by domain:
 
-- **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** (6) — `list_scans`, `get_scan`, `create_scan`, `create_bulk_scans`, `recheck_scans`, `cancel_scan`
+- **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** (10) — `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`
 - **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** (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 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** (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`
+- **Invoicing** (2) — `list_invoices`, `get_invoice_pdf`
 - **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, and the public marketing forms (`/contact`, `/demo-inquiries`). Open an issue if you need one of those.
+Screenshots (`get_scan_screenshot`, `get_scan_creative_screenshot`, `get_scan_landing_screenshot`) come back as inline MCP `image` blocks and `get_invoice_pdf` as an inline resource block — no second fetch, no presigned URL.
+
+Not exposed (intentionally): the raw creative artifacts (`creative-html`, `creative-video`, `vast-xml`) and the public marketing forms (`/contact`, `/demo-inquiries`). Open an issue if you need one of those.
 
 ## Example agent prompts
 

package/dist/bin.js

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-import { NAME, VERSION, err, ok } from './chunk-KFVVS55N.js';
+import { NAME, VERSION, err, ok } from './chunk-TMUGAKI2.js';
 import process from 'process';
 import { z } from 'zod';
 
@@ -160,10 +160,10 @@ async function main() {
   }
   const config = configResult.value;
   if (config.transport === "stdio") {
-    const { bootstrapStdio } = await import('./stdio-bootstrap-7EXISZ66.js');
+    const { bootstrapStdio } = await import('./stdio-bootstrap-JW6I4H3U.js');
     return bootstrapStdio(config);
   }
-  const { bootstrapHttp } = await import('./http-bootstrap-3MGAQHND.js');
+  const { bootstrapHttp } = await import('./http-bootstrap-Y4YKT7KV.js');
   return bootstrapHttp(config);
 }
 main().then(

package/dist/{chunk-5UVZYMC3.js → chunk-T6GEYHLP.js}

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-import { err, ok } from './chunk-KFVVS55N.js';
+import { err, ok } from './chunk-TMUGAKI2.js';
 import { createHash, randomUUID } from 'crypto';
 import createClient from 'openapi-fetch';
 import { fetch } from 'undici';
@@ -245,6 +245,7 @@ z.object({
   url: z.union([z.string(), z.null()]).optional(),
   ad_tag: z.union([z.string(), z.null()]).optional(),
   vast_tag: z.union([z.string(), z.null()]).optional(),
+  referrer: z.union([z.string(), z.null()]).optional(),
   country_code: z.string().min(2).max(2),
   emulator_id: z.string().min(1).max(100),
   proxy: ProxyTargetRequest.optional(),
@@ -362,6 +363,7 @@ var ScanResponse = z.object({
   public_report_url: z.string().optional().default(""),
   ad_tag: z.union([z.string(), z.null()]).optional(),
   vast_tag: z.union([z.string(), z.null()]).optional(),
+  referrer: z.union([z.string(), z.null()]).optional(),
   creative_kind: z.enum(["banner", "video"]).optional().default("banner"),
   creative_screenshot_url: z.string().optional().default(""),
   creative_video_url: z.string().optional().default(""),
@@ -433,6 +435,7 @@ z.object({
   url: z.union([z.string(), z.null()]).optional(),
   ad_tag: z.union([z.string(), z.null()]).optional(),
   vast_tag: z.union([z.string(), z.null()]).optional(),
+  referrer: z.union([z.string(), z.null()]).optional(),
   country_codes: z.array(z.string()).min(1),
   emulator_id: z.string().min(1).max(100),
   proxy: ProxyTargetRequest.optional(),
@@ -468,7 +471,8 @@ var CampaignGroupResponse = z.object({
   is_archived: z.boolean(),
   schedule_paused: z.boolean(),
   created_at: z.string().datetime({ offset: true }),
-  campaign_count: z.union([z.number(), z.null()]).optional()
+  campaign_count: z.union([z.number(), z.null()]).optional(),
+  last_run_at: z.union([z.string(), z.null()]).optional()
 }).passthrough();
 z.object({ name: z.union([z.string(), z.null()]) }).partial().passthrough();
 var BulkCampaignFailure = z.object({
@@ -490,6 +494,7 @@ z.object({
   url: z.union([z.string(), z.null()]).optional(),
   ad_tag: z.union([z.string(), z.null()]).optional(),
   vast_tag: z.union([z.string(), z.null()]).optional(),
+  referrer: z.union([z.string(), z.null()]).optional(),
   country_codes: z.array(z.string()).min(1),
   group_id: z.union([z.string(), z.null()]).optional(),
   emulator_categories: z.array(z.string()).optional(),
@@ -522,6 +527,7 @@ var CampaignResponse = z.object({
   url: z.string(),
   ad_tag: z.union([z.string(), z.null()]).optional(),
   vast_tag: z.union([z.string(), z.null()]).optional(),
+  referrer: z.union([z.string(), z.null()]).optional(),
   country_codes: z.array(z.string()),
   group_id: z.string().uuid(),
   emulator_selection: EmulatorSelectionResponse,
@@ -562,6 +568,7 @@ z.object({
   url: z.union([z.string(), z.null()]),
   ad_tag: z.union([z.string(), z.null()]),
   vast_tag: z.union([z.string(), z.null()]),
+  referrer: z.union([z.string(), z.null()]),
   country_codes: z.union([z.array(z.string()), z.null()]),
   group_id: z.union([z.string(), z.null()]),
   emulator_categories: z.union([z.array(z.string()), z.null()]),
@@ -861,6 +868,7 @@ var AlertResponse = z.object({
   scan_url: z.string(),
   offer_url: z.string(),
   tag_display_name: z.string(),
+  policy_set_name: z.union([z.string(), z.null()]).optional(),
   rule_type: z.string().optional().default("tag"),
   matched_value: z.union([z.string(), z.null()]).optional()
 }).passthrough();
@@ -877,7 +885,13 @@ z.object({
   ids: z.union([z.array(z.string().uuid()), z.null()]).optional(),
   all_matching: z.boolean().optional().default(false),
   filter_status: z.union([AlertStatus, z.null()]).optional(),
-  filter_campaign_id: z.union([z.string(), z.null()]).optional()
+  filter_campaign_id: z.union([z.string(), z.null()]).optional(),
+  filter_policy_set_ids: z.union([z.array(z.string().uuid()), z.null()]).optional(),
+  filter_tag_slugs: z.union([z.array(z.string()), z.null()]).optional(),
+  filter_country_codes: z.union([z.array(z.string()), z.null()]).optional(),
+  filter_date_from: z.union([z.string(), z.null()]).optional(),
+  filter_date_to: z.union([z.string(), z.null()]).optional(),
+  filter_timezone: z.union([z.string(), z.null()]).optional()
 }).passthrough();
 z.object({ updated: z.number().int(), skipped: z.number().int() }).passthrough();
 var AlertStatsResponse = z.object({
@@ -968,7 +982,9 @@ var EndpointHealthResponse = z.object({
   consecutive_failures: z.number().int(),
   last_delivery_at: z.union([z.string(), z.null()]),
   last_delivery_status: z.union([z.number(), z.null()]),
-  success_rate_7d: z.number()
+  success_rate_7d: z.number(),
+  failing_since: z.union([z.string(), z.null()]),
+  paused_until: z.union([z.string(), z.null()])
 }).passthrough();
 var WebhookResponse = z.object({
   id: z.string().uuid(),
@@ -1339,6 +1355,7 @@ var CampaignSchema = schemas.CampaignResponse.pick({
   url: true,
   ad_tag: true,
   vast_tag: true,
+  referrer: true,
   country_codes: true,
   group_id: true,
   emulator_selection: true,
@@ -1772,6 +1789,7 @@ var ScanSchema = schemas.ScanResponse.pick({
   public_report_url: true,
   ad_tag: true,
   vast_tag: true,
+  referrer: true,
   creative_kind: true,
   video: true,
   creative_screenshot_url: true,
@@ -3179,7 +3197,7 @@ var setCampaignAlertOverridesTool = {
 var GetAlertStatsInputShape = {};
 var getAlertStatsTool = {
   name: "get_alert_stats",
-  description: "Get alert counts grouped by status: open, escalated, resolved, dismissed (total is implicit in the sum). Status names match the canonical AlertStatus enum used by `list_alerts` and `update_alert_status`.",
+  description: "Get alert counts grouped by status: open, escalated, resolved, dismissed. Counts cover the caller's organization over all time and are not filtered, so the four sum to the `total` an unfiltered `list_alerts` reports. Status names match the canonical AlertStatus enum used by `list_alerts` and `update_alert_status`.",
   annotations: {
     title: "Get Alert Stats",
     readOnlyHint: true,
@@ -3672,6 +3690,10 @@ function pickCampaignConfigBody(input) {
   if (input.schedule_timezone !== void 0) body.schedule_timezone = input.schedule_timezone;
   return body;
 }
+var campaignReferrerUrl = z.string().url().regex(/^https?:\/\//i, "Must be an http(s) URL.").max(2048);
+var CAMPAIGN_REFERRER_DESCRIPTION = "Optional http(s) page URL every scan of this campaign is checked from. For `ad_tag` and `vast` campaigns this is the publisher page the tag is embedded in \u2014 NOT the creative and NOT its landing page; the browser commits the page document on this URL without fetching the publisher, so the creative renders as if embedded there, and its cross-origin subrequests receive the origin only (https://publisher.example/, no path). For `url` and `ad_discovery` campaigns this is where the visitor came from, sent in full as the Referer of the page request.";
+var campaignReferrerField = campaignReferrerUrl.optional().describe(CAMPAIGN_REFERRER_DESCRIPTION);
+var campaignReferrerUpdateField = campaignReferrerUrl.nullable().optional().describe(`${CAMPAIGN_REFERRER_DESCRIPTION} Pass null to clear it.`);
 
 // src/application/tools/campaigns/create-campaign.tool.ts
 var CreateCampaignInputShape = {
@@ -3686,6 +3708,7 @@ var CreateCampaignInputShape = {
   vast_tag: z.string().optional().describe(
     "VAST video ad tag: an http(s) URL of a VAST endpoint OR raw VAST XML (required if campaign_type=vast)."
   ),
+  referrer: campaignReferrerField,
   country_codes: z.array(z.string().length(2)).min(1).describe("ISO 3166-1 alpha-2 codes \u2014 one scan per country per run."),
   group_id: z.string().uuid().optional().describe("Parent group UUID; defaults to the org's default group."),
   ...campaignConfigFields,
@@ -3712,6 +3735,7 @@ var createCampaignTool = {
       ...input.url !== void 0 ? { url: input.url } : {},
       ...input.ad_tag !== void 0 ? { ad_tag: input.ad_tag } : {},
       ...input.vast_tag !== void 0 ? { vast_tag: input.vast_tag } : {},
+      ...input.referrer !== void 0 ? { referrer: input.referrer } : {},
       ...input.group_id !== void 0 ? { group_id: input.group_id } : {},
       ...input.labels !== void 0 ? { labels: input.labels } : {},
       ...input.policy_set_id !== void 0 ? { policy_set_id: input.policy_set_id } : {},
@@ -3882,6 +3906,7 @@ var UpdateCampaignInputShape = {
   vast_tag: z.string().optional().describe(
     "New VAST video ad tag: an http(s) URL of a VAST endpoint OR raw VAST XML (vast-type campaigns)."
   ),
+  referrer: campaignReferrerUpdateField,
   country_codes: z.array(z.string().length(2)).optional().describe("Replace the country list."),
   group_id: z.string().uuid().optional().describe("Move the campaign to another group."),
   ...campaignConfigFields,
@@ -3891,7 +3916,7 @@ var UpdateCampaignInputShape = {
 };
 var updateCampaignTool = {
   name: "update_campaign",
-  description: "Update one or more fields of a campaign. Fields not supplied are left unchanged. `policy_set_id` accepts null to clear the binding.",
+  description: "Update one or more fields of a campaign. Fields not supplied are left unchanged. `policy_set_id` accepts null to clear the binding, and `referrer` accepts null to clear the publisher page scans are checked from.",
   annotations: {
     title: "Update Campaign",
     readOnlyHint: false,
@@ -3906,6 +3931,7 @@ var updateCampaignTool = {
       ...input.url !== void 0 ? { url: input.url } : {},
       ...input.ad_tag !== void 0 ? { ad_tag: input.ad_tag } : {},
       ...input.vast_tag !== void 0 ? { vast_tag: input.vast_tag } : {},
+      ...input.referrer !== void 0 ? { referrer: input.referrer } : {},
       ...input.country_codes !== void 0 ? { country_codes: input.country_codes } : {},
       ...input.group_id !== void 0 ? { group_id: input.group_id } : {},
       ...input.labels !== void 0 ? { labels: input.labels } : {},
@@ -3918,6 +3944,21 @@ var updateCampaignTool = {
     return ok(result.value);
   }
 };
+var COMBO_MATCH_SCOPE_DOC = 'For `rule_type=\'combo\'` the optional rule-level key `match_scope` decides where conditions are counted. `"scan"` (the default, and the behaviour when the key is absent) checks them against the union of all tags on the scan. With `"url"`, every condition must be satisfied by tags on the same link, and the tag is assigned to that link \u2014 so a rule built only from link-less tags (AI verdicts, crawler behaviour) has no link to attach to and will never match; keep those on the whole scan. Mixing the two kinds does not help either: AI verdicts and per-link detections reach the engine in different scan parts and are not evaluated together today, so such a combo fires under neither scope. Give a `"url"` rule at least one positive condition (`all_of` / `any_of` / `tag_category` + `count_gte`) \u2014 a config carrying only `none_of` matches every link that merely lacks those tags, and the API does not reject that on this path. Thresholds stay "N or more" (`count_gte` / `any_of_min`) in both scopes; no other `match_scope` value is accepted.';
+var COMBO_MATCH_SCOPE_READ_DOC = 'For `rule_type=\'combo\'` the returned `config` may carry the rule-level key `match_scope` ("scan" = count conditions across the whole scan, "url" = every condition must be satisfied by tags on the same link). Resend it verbatim when updating: `update_custom_rule` replaces `config` wholesale, so dropping the key reverts the rule to whole-scan matching.';
+var ruleConfigField = z.record(z.unknown()).superRefine((config, ctx) => {
+  const scope = config["match_scope"];
+  if (scope === void 0 || scope === "scan" || scope === "url") {
+    return;
+  }
+  ctx.addIssue({
+    code: z.ZodIssueCode.custom,
+    path: ["match_scope"],
+    message: 'config.match_scope must be "scan" or "url". Omit the key for scan-wide matching (the default).'
+  });
+});
+
+// src/application/tools/custom-rules/create-custom-rule.tool.ts
 var CreateCustomRuleInputShape = {
   name: z.string().min(1).max(200).describe(
     "Display name. For non-LLM rules this also becomes the `display_name` of the auto-registered tag definition (see `tag_slug`)."
@@ -3928,8 +3969,8 @@ var CreateCustomRuleInputShape = {
   rule_type: z.string().max(50).describe(
     "Rule engine. One of: `stopword_content`, `stopword_url`, `regexp_content`, `regexp_url`, `blacklist_domain`, `combo`, `llm`. The API validates."
   ),
-  config: z.record(z.unknown()).describe(
-    "Rule-type-specific configuration object. Shape depends on `rule_type`. For `rule_type='llm'` the shape is `{ prompt: string, tags: { <tag_slug>: <description>, ... } }`; each key in `config.tags` is auto-registered as a custom tag definition AND must not collide with a system slug (same 422 contract as `tag_slug`)."
+  config: ruleConfigField.describe(
+    "Rule-type-specific configuration object. Shape depends on `rule_type`. For `rule_type='llm'` the shape is `{ prompt: string, tags: { <tag_slug>: <description>, ... } }`; each key in `config.tags` is auto-registered as a custom tag definition AND must not collide with a system slug (same 422 contract as `tag_slug`). " + COMBO_MATCH_SCOPE_DOC
   ),
   target: z.string().max(30).optional().describe(
     "Where to apply the rule (e.g. 'page' for landing HTML). Default: page. See API docs for the full set of valid values."
@@ -3937,7 +3978,7 @@ var CreateCustomRuleInputShape = {
 };
 var createCustomRuleTool = {
   name: "create_custom_rule",
-  description: "Define a custom tag-detection rule. The API auto-registers a tag definition for each slug the rule emits (`tag_slug` for non-LLM rules; `config.tags` keys for `rule_type='llm'`); slugs that collide with a built-in system tag are rejected with HTTP 422 / code `checking.system_slug_reserved`. Matches tag every future scan; existing scans are untouched until you call `recheck_scans`.",
+  description: "Define a custom tag-detection rule. The API auto-registers a tag definition for each slug the rule emits (`tag_slug` for non-LLM rules; `config.tags` keys for `rule_type='llm'`); slugs that collide with a built-in system tag are rejected with HTTP 422 / code `checking.system_slug_reserved`. For `rule_type='combo'` set `config.match_scope='url'` when the thresholds must be met inside one link instead of anywhere on the scan (default `'scan'`). Matches tag every future scan; existing scans are untouched until you call `recheck_scans`.",
   annotations: {
     title: "Create Custom Rule",
     readOnlyHint: false,
@@ -3982,7 +4023,7 @@ var deleteCustomRuleTool = {
 var GetCustomRuleInputShape = { rule_id: z.string().uuid().describe("Rule UUID.") };
 var getCustomRuleTool = {
   name: "get_custom_rule",
-  description: "Get one custom rule by UUID with name, tag-slug, type, config object, target, active flag.",
+  description: "Get one custom rule by UUID with name, tag-slug, type, config object, target, active flag. " + COMBO_MATCH_SCOPE_READ_DOC,
   annotations: {
     title: "Get Custom Rule",
     readOnlyHint: true,
@@ -4003,7 +4044,7 @@ var ListCustomRulesInputShape = {
 };
 var listCustomRulesTool = {
   name: "list_custom_rules",
-  description: "Paginated list of the organization's custom tag-detection rules (regex / heuristics) with their config, target, and active flag. Returns `{items, total, page, limit}`. To iterate: there is a next page iff `page * limit < total` (or equivalently `items.length === limit` until the last page). `page` is 1-indexed.",
+  description: "Paginated list of the organization's custom tag-detection rules (regex / heuristics) with their config, target, and active flag. Returns `{items, total, page, limit}`. To iterate: there is a next page iff `page * limit < total` (or equivalently `items.length === limit` until the last page). `page` is 1-indexed. " + COMBO_MATCH_SCOPE_READ_DOC,
   annotations: {
     title: "List Custom Rules",
     readOnlyHint: true,
@@ -4022,8 +4063,8 @@ var TestCustomRuleInputShape = {
   rule_type: z.string().max(50).describe(
     "Rule engine type. One of: `stopword_content`, `stopword_url`, `regexp_content`, `regexp_url`, `blacklist_domain`, `combo`, `llm`."
   ),
-  config: z.record(z.unknown()).describe(
-    "Rule-type-specific config to test. Same shape as `create_custom_rule`'s `config`. NOTE: `test_custom_rule` evaluates the rule against a scan WITHOUT persisting it, so slug-collision validation does NOT run here \u2014 verify slugs against `list_tags` (`scope=system`) before promoting to `create_custom_rule`."
+  config: ruleConfigField.describe(
+    "Rule-type-specific config to test. Same shape as `create_custom_rule`'s `config`. NOTE: `test_custom_rule` evaluates the rule against a scan WITHOUT persisting it, so slug-collision validation does NOT run here \u2014 verify slugs against `list_tags` (`scope=system`) before promoting to `create_custom_rule`. " + COMBO_MATCH_SCOPE_DOC
   ),
   target: z.string().max(30).describe(
     "Where to apply the rule (e.g. 'page' for landing HTML). See API docs for the full set of valid values."
@@ -4032,7 +4073,7 @@ var TestCustomRuleInputShape = {
 };
 var testCustomRuleTool = {
   name: "test_custom_rule",
-  description: "Preview-test a rule definition against an existing scan WITHOUT persisting the rule. Returns `matched: bool`, evaluation time, and per-tag-slug details. Use to validate config before `create_custom_rule`. NOTE: slug-collision validation does NOT run in preview mode \u2014 verify any `tag_slug` (or LLM `config.tags` keys) against `list_tags` (`scope=system`) before promoting to `create_custom_rule`, which would otherwise reject the same payload with HTTP 422 / code `checking.system_slug_reserved`.",
+  description: "Preview-test a rule definition against an existing scan WITHOUT persisting the rule. Returns `matched: bool`, evaluation time, and per-tag-slug details. Use to validate config before `create_custom_rule`. Combo rules are evaluated against the scan's existing tags, so `config.match_scope` is honoured \u2014 but per-URL hits are collapsed to one row per tag slug, so the result says whether the rule fires, not which URLs it would tag. NOTE: slug-collision validation does NOT run in preview mode \u2014 verify any `tag_slug` (or LLM `config.tags` keys) against `list_tags` (`scope=system`) before promoting to `create_custom_rule`, which would otherwise reject the same payload with HTTP 422 / code `checking.system_slug_reserved`.",
   annotations: {
     title: "Test Custom Rule",
     readOnlyHint: true,
@@ -4060,8 +4101,8 @@ var UpdateCustomRuleInputShape = {
   tag_slug: z.string().max(100).optional().describe(
     "New tag slug to assign on match. **MUST NOT collide with a built-in system tag slug** (see `list_tags` where `scope=system`); colliding requests return 422 with code `checking.system_slug_reserved`. Re-registering an existing custom slug refreshes its tag definition's `display_name` / `description`."
   ),
-  config: z.record(z.unknown()).optional().describe(
-    "New rule-type-specific config object. For `rule_type='llm'` the keys of `config.tags` are auto-registered as tag definitions; any key that collides with a system slug returns the same 422 contract."
+  config: ruleConfigField.optional().describe(
+    "New rule-type-specific config object. Replaces the stored config wholesale \u2014 resend every key you want to keep, including a combo rule's `match_scope`. For `rule_type='llm'` the keys of `config.tags` are auto-registered as tag definitions; any key that collides with a system slug returns the same 422 contract. " + COMBO_MATCH_SCOPE_DOC
   ),
   target: z.string().max(30).optional().describe(
     "Where to apply the rule (e.g. 'page' for landing HTML). See API docs for the full set of valid values."
@@ -4070,7 +4111,7 @@ var UpdateCustomRuleInputShape = {
 };
 var updateCustomRuleTool = {
   name: "update_custom_rule",
-  description: "Update a custom tag-detection rule. Only supplied fields are sent. Changing `tag_slug` (or `config.tags` keys for `rule_type='llm'`) onto a built-in system slug returns HTTP 422 / code `checking.system_slug_reserved`. To toggle activation, pass `is_active`. Existing tagged scans are NOT re-evaluated \u2014 call `recheck_scans` for that. (Rule engine `rule_type` cannot be changed after creation; create a new rule instead.)",
+  description: "Update a custom tag-detection rule. Only supplied fields are sent, but a supplied `config` replaces the stored one wholesale (omitting a combo rule's `match_scope` reverts it to the scan-wide default). Changing `tag_slug` (or `config.tags` keys for `rule_type='llm'`) onto a built-in system slug returns HTTP 422 / code `checking.system_slug_reserved`. To toggle activation, pass `is_active`. Existing tagged scans are NOT re-evaluated \u2014 call `recheck_scans` for that. (Rule engine `rule_type` cannot be changed after creation; create a new rule instead.)",
   annotations: {
     title: "Update Custom Rule",
     readOnlyHint: false,
@@ -4733,6 +4774,9 @@ var scanProxyField = z.object({
   city: z.string().optional().describe("Proxy city targeting."),
   isp: z.string().optional().describe("Proxy ISP targeting.")
 }).optional().describe("Optional proxy geo targeting for the crawl. Omit to use the org default.");
+var scanReferrerField = z.string().url().regex(/^https?:\/\//i, "Must be an http(s) URL.").max(2048).optional().describe(
+  "Optional http(s) page URL the check is performed from. With `ad_tag` or `vast_tag` this is the publisher page the tag is embedded in \u2014 NOT the creative and NOT its landing page; the browser commits the page document on this URL without fetching the publisher, so the creative renders as if embedded there, and its cross-origin subrequests receive the origin only (https://publisher.example/, no path). With a `url` target this is where the visitor came from, sent in full as the Referer of the page request."
+);
 
 // src/application/tools/scans/create-bulk-scans.tool.ts
 var CreateBulkScansInputShape = {
@@ -4743,6 +4787,7 @@ var CreateBulkScansInputShape = {
   vast_tag: z.string().optional().describe(
     "VAST video ad tag: an http(s) URL of a VAST endpoint OR raw VAST XML. Provide exactly one of `url`, `ad_tag`, or `vast_tag`."
   ),
+  referrer: scanReferrerField,
   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."),
   emulator_id: z.string().min(1).max(100).describe("Device/OS profile slug; same for every country in the batch."),
   proxy: scanProxyField,
@@ -4767,6 +4812,7 @@ var createBulkScansTool = {
       ...input.url !== void 0 ? { url: input.url } : {},
       ...input.ad_tag !== void 0 ? { ad_tag: input.ad_tag } : {},
       ...input.vast_tag !== void 0 ? { vast_tag: input.vast_tag } : {},
+      ...input.referrer !== void 0 ? { referrer: input.referrer } : {},
       ...input.proxy !== void 0 ? { proxy: input.proxy } : {},
       ...input.labels !== void 0 ? { labels: input.labels } : {},
       ...pickRepeatRetryBody(input)
@@ -4786,6 +4832,7 @@ var CreateScanInputShape = {
   vast_tag: z.string().optional().describe(
     "VAST video ad tag: an http(s) URL of a VAST endpoint OR raw VAST XML (a document containing a <VAST> element). Fetched and played in a real browser. Provide exactly one of `url`, `ad_tag`, or `vast_tag`."
   ),
+  referrer: scanReferrerField,
   country_code: z.string().length(2).describe("ISO 3166-1 alpha-2 country code, e.g. US, DE, JP. Determines proxy geo."),
   emulator_id: z.string().min(1).max(100).describe("Device/OS profile slug; use `list_emulators` to discover valid values."),
   proxy: scanProxyField,
@@ -4815,6 +4862,7 @@ var createScanTool = {
       ...input.url !== void 0 ? { url: input.url } : {},
       ...input.ad_tag !== void 0 ? { ad_tag: input.ad_tag } : {},
       ...input.vast_tag !== void 0 ? { vast_tag: input.vast_tag } : {},
+      ...input.referrer !== void 0 ? { referrer: input.referrer } : {},
       ...input.proxy !== void 0 ? { proxy: input.proxy } : {},
       ...input.labels !== void 0 ? { labels: input.labels } : {},
       ...input.campaign_id !== void 0 ? { campaign_id: input.campaign_id } : {},
@@ -5611,5 +5659,5 @@ function formatToolError(error) {
 }
 
 export { BearerToken, SERVER_INSTRUCTIONS, createHttpApiGateway, createPinoLogger, declareEmptyResourcesAndPrompts, newRequestId, wireToolsIntoMcpServer };
-//# sourceMappingURL=chunk-5UVZYMC3.js.map
-//# sourceMappingURL=chunk-5UVZYMC3.js.map
+//# sourceMappingURL=chunk-T6GEYHLP.js.map
+//# sourceMappingURL=chunk-T6GEYHLP.js.map