scrapeloop-mcp 0.7.0 → 0.7.1

package/README.md

@@ -71,7 +71,7 @@ cleaners, strategy tags, vendors, scopes, and the ordered 7 setup steps) and
 | Enrich + strategies | `list_presets`, `create_preset`, `estimate_enrich`, `run_enrich`, `test_recipe`, `get_ai_settings`, `update_ai_settings`, `list_strategies`, `create_strategy`, `assign_strategy` |
 | Campaigns + Instantly | `list_instantly_campaigns`, `list_instantly_lead_lists`, `import_instantly_campaigns`, `import_instantly_lead_list`, `list_segments`, `create_segment`, `preview_segment`, `list_campaigns`, `create_campaign`, `update_campaign`, `activate_campaign`, `pause_campaign`, `sync_campaign`, `campaign_stats`, `get_sender_config`, `update_sender_config` |
 | B2B saved collections | `get_lists`, `create_list`, `add_list_members` |
-| Campaign-ready Tables | `get_tables`, `create_table`, `get_table_columns`, `create_table_column`, `set_table_cells`, `list_table_rows` |
+| Campaign-ready Tables | `get_tables`, `create_table`, `get_table_columns`, `create_table_column`, `create_table_preset_column`, `set_table_cells`, `list_table_rows` |
 
 `import_leads`, `preview_import`, and `import_leads_csv` accept raw identities
 without placeholder emails. Each row needs an email, LinkedIn URL, external ID,
@@ -90,7 +90,16 @@ typed value, with explicit `null` reserved for clearing. `set_table_cells`
 accepts at most 500 cells and 256 KiB of JSON, validates the complete batch,
 then persists it as one atomic upsert.
 
-`create_table`, `create_table_column`, and `create_table_view` are
+`create_table_preset_column` attaches a shipped system preset or an active
+workspace preset as a real enrichment column. It requires a stable
+`operation_id`, defaults `auto_run` to false, and accepts only overrides declared
+by the preset. When auto-run would backfill existing rows, the first call returns
+the exact row and cost estimate without writing. Repeat with `confirm_auto_run`
+and that exact `confirmed_estimated_cost_usd` only after user confirmation. The
+Table master switch and workspace budget caps still gate the queued work.
+
+`create_table`, `create_table_column`, `create_table_preset_column`, and
+`create_table_view` are
 idempotent. The MCP generates one `operation_id` for the logical create and
 reuses it across transient HTTP retries. The API returns the first resource for
 the same key and normalized payload, including concurrent calls, and returns
@@ -121,28 +130,40 @@ successful only after all four conditions are true:
 
 1. The exact `mcp-v<version>` tag matches `package.json`.
 2. Tests pass and the packed tarball contains only the declared package files.
-3. npm accepts the exact tarball with provenance, or already has that same
-   version with the same integrity.
+3. npm accepts the exact tarball through Trusted Publishing, or already has
+   that same version with the same integrity.
 4. `npx scrapeloop-mcp@<version>` reports the expected version and tool count.
 
+The installed-package check removes GitHub Actions' temporary npm authentication
+settings and replaces them with an empty, temporary public-registry config
+before it runs `npx`. That makes the final check use the public registry exactly
+like a customer install, without reusing publishing access.
+
 The Actions summary reports **Build and test** separately from **Publish and
 registry**. A green package build does not mean the version is published. A
-missing or rejected npm credential, a conflicting duplicate version, or a
-registry verification timeout fails the workflow.
+missing OIDC identity, a rejected trusted-publisher match, a conflicting
+duplicate version, or a registry verification timeout fails the workflow.
+
+### Trusted npm publishing
+
+The npm package trusts only the `publish-mcp.yml` GitHub Actions workflow in
+`Hinkam-Lanello/scrapeloop`. The workflow uses GitHub OIDC to request a
+short-lived npm publishing identity. It must run on a GitHub-hosted runner with
+`id-token: write`, Node.js 24, and npm 11.5.1 or newer. Do not add `NPM_TOKEN` or
+another long-lived publish token.
 
-### Human-owned npm credential
+The source repository is private, so the workflow must not force npm
+provenance. npm supports Trusted Publishing from a private GitHub repository,
+but provenance is available only when the source repository is public.
 
-An npm account owner must create a publish-capable access token for
-`scrapeloop-mcp` and store it as the GitHub Actions repository secret
-`NPM_TOKEN`. Agents must not create, reveal, or enter this credential. To recover
-an already tagged but unpublished version, run the workflow manually with its
-exact existing tag. The workflow archives and publishes that tag's source rather
-than the current default branch.
+To recover an already tagged but unpublished version, run the workflow manually
+with its exact existing tag. The workflow archives and publishes that tag's
+source rather than the current default branch.
 
 Local preflight, which never publishes:
 
 ```bash
 npm ci --no-audit --no-fund
 npm test
-npm run release:preflight -- --tag mcp-v0.7.0
+npm run release:preflight -- --tag mcp-v0.7.1
 ```

package/package.json

@@ -1,10 +1,10 @@
 {
   "name": "scrapeloop-mcp",
-  "version": "0.7.0",
+  "version": "0.7.1",
   "description": "Scrapeloop MCP server — set up and run Scrapeloop end-to-end (integrations, scraping, lead database, verification, cleaners, enrichment, strategies, Instantly campaigns) from any MCP client (Claude Desktop, Cursor, ChatGPT, …).",
   "type": "module",
   "scripts": {
-    "test": "node --check src/index.js && node test/mcp_table_tools.mjs && node test/mcp_community_intent.mjs && node test/mcp_api_key_preflight.mjs && node test/release_readiness.mjs",
+    "test": "node --check src/index.js && node test/mcp_table_tools.mjs && node test/mcp_community_intent.mjs && node test/mcp_api_key_preflight.mjs && node test/mutation_retry_contract.mjs && node test/release_readiness.mjs",
     "release:preflight": "node scripts/release-preflight.mjs",
     "release:verify": "node scripts/release-installed-verify.mjs"
   },

package/src/index.js

@@ -18,10 +18,12 @@
 import { Server } from '@modelcontextprotocol/sdk/server/index.js';
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
 import { randomUUID } from 'node:crypto';
+import { AsyncLocalStorage } from 'node:async_hooks';
 import {
   CallToolRequestSchema,
   ListToolsRequestSchema,
 } from '@modelcontextprotocol/sdk/types.js';
+import { MUTATION_POLICIES, RETRY_CONTRACT_COPY } from './mutation-policies.js';
 
 const API_KEY = process.env.SCRAPELOOP_API_KEY;
 const BASE = (process.env.SCRAPELOOP_API_URL || 'https://api.scrapeloop.com').replace(/\/$/, '');
@@ -32,25 +34,39 @@ const MAX_TABLE_CELL_REQUEST_BYTES = 256 * 1024;
 const TRACE_HEADER = 'X-Scrapeloop-Trace-Id';
 const SAFE_TRACE_ID = /^[A-Za-z0-9_-]{8,80}$/;
 const STARTUP_WARNINGS = new Set();
+const RETRY_BASE_MS = Number(process.env.SCRAPELOOP_RETRY_BASE_MS) || 500;
+const toolCallContext = new AsyncLocalStorage();
 
 const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
 
-// One API call with a per-request timeout + retry/backoff on 429/5xx + transient
-// network errors. Never throws — always resolves to {ok, status, data|error} so a
-// single failed upstream call can't kill the server. The API key is sent in the
-// Authorization header only and is never logged.
-const uncertainMutationFailure = (status, error, reconciliation) => {
-  const base = error && typeof error === 'object' ? error : { detail: String(error) };
+const uncertainResult = ({ context, method, path, upstreamStatus, reconciliation }) => {
+  const policy = context?.policy || {};
+  const args = context?.args || {};
+  const match = Object.fromEntries(
+    (policy.match_fields || [])
+      .filter((field) => args[field] !== undefined)
+      .map((field) => [field, args[field]]),
+  );
   return {
     ok: false,
-    status,
+    status: upstreamStatus || 0,
     error: {
-      ...base,
+      type: 'uncertain_result',
       uncertain_result: true,
-      retry_guidance:
-        reconciliation.retry_guidance ||
-        'Do not repeat this mutation yet. The server may have committed it before the response was lost.',
-      reconciliation,
+      detail: `The ${method} ${path} result is unknown. The request may have committed before the response was lost.`,
+      tool: context?.toolName,
+      operation: `${method} ${path}`,
+      ...(args.idempotency_key ? { idempotency_key: args.idempotency_key } : {}),
+      inspect_with: policy.inspect_with || [],
+      match_fields: match,
+      ...(reconciliation ? { reconciliation } : {}),
+      ...(reconciliation?.retry_guidance
+        ? { retry_guidance: reconciliation.retry_guidance }
+        : {}),
+      guidance:
+        reconciliation?.guidance ||
+        reconciliation?.retry_guidance ||
+        'Inspect the listed read tools and stable fields before making any new mutation attempt.',
     },
   };
 };
@@ -69,34 +85,65 @@ async function api(method, path, body, options = {}) {
   }
   const fetcher = options.fetcher || fetch;
   const sleepFn = options.sleepFn || sleep;
-  const maxRetries = options.maxRetries ?? MAX_RETRIES;
   const shouldRetryResponse =
     options.shouldRetryResponse || ((status) => status === 429 || status >= 500);
-  const retryDelay = options.retryDelay || ((attempt) => 500 * 2 ** attempt);
+  const retryDelay = options.retryDelay || ((attempt) => RETRY_BASE_MS * 2 ** attempt);
   const traceId = safeTraceId(options.traceId);
+  const verb = method.toUpperCase();
+  const context = toolCallContext.getStore();
+  const policy = context?.policy;
+  if (verb !== 'GET' && (!policy || policy.method !== verb)) {
+    return {
+      ok: false,
+      status: 500,
+      error: {
+        detail: `MCP mutation policy missing or mismatched for ${context?.toolName || 'unknown tool'} (${verb} ${path}).`,
+      },
+    };
+  }
+  if (policy?.retry === 'idempotency_key' && !context?.args?.idempotency_key) {
+    return {
+      ok: false,
+      status: 400,
+      error: {
+        detail: `${context.toolName} requires idempotency_key. Generate one stable UUID and reuse it for every retry of this exact operation.`,
+      },
+    };
+  }
+  const canRetry = verb === 'GET'
+    || policy?.effect === 'read'
+    || policy?.retry === 'idempotent'
+    || policy?.retry === 'idempotency_key';
+  const maxRetries = canRetry ? (options.maxRetries ?? MAX_RETRIES) : 0;
+  const headers = {
+    Authorization: `Bearer ${API_KEY}`,
+    'Content-Type': 'application/json',
+    ...(traceId ? { [TRACE_HEADER]: traceId } : {}),
+    ...(policy?.retry === 'idempotency_key'
+      ? { 'Idempotency-Key': context.args.idempotency_key }
+      : {}),
+  };
   let lastErr;
   for (let attempt = 0; attempt <= maxRetries; attempt++) {
     let res;
     try {
       res = await fetcher(`${BASE}/api/v1${path}`, {
-        method,
-        headers: {
-          Authorization: `Bearer ${API_KEY}`,
-          'Content-Type': 'application/json',
-          ...(traceId ? { [TRACE_HEADER]: traceId } : {}),
-        },
+        method: verb,
+        headers,
         body: body === undefined ? undefined : JSON.stringify(body),
         signal: AbortSignal.timeout(TIMEOUT_MS),
       });
     } catch (e) {
-      // Network error / timeout — retry a few times, then surface a clean error.
       lastErr = e;
       if (attempt < maxRetries) {
         await sleepFn(retryDelay(attempt));
         continue;
       }
+      if (policy?.effect === 'mutation') {
+        return uncertainResult({ context, method: verb, path, reconciliation: options.reconciliation });
+      }
       const timedOut = e && (e.name === 'TimeoutError' || e.name === 'AbortError');
-      const failure = {
+      return {
         ok: false,
         status: 0,
         error: { detail: `Could not reach Scrapeloop (${timedOut ? `timeout after ${TIMEOUT_MS}ms` : String(e)}).` },
@@ -104,12 +151,10 @@ async function api(method, path, body, options = {}) {
           ? { trace_id: traceId, network_error: timedOut ? 'timeout' : 'transport' }
           : {}),
       };
-      return options.reconciliation
-        ? uncertainMutationFailure(0, failure.error, options.reconciliation)
-        : failure;
     }
     // Retry transient upstream failures (rate limit / server errors).
-    if (shouldRetryResponse(res.status) && attempt < maxRetries) {
+    const transient = shouldRetryResponse(res.status);
+    if (transient && attempt < maxRetries) {
       const retryAfter = Number(res.headers.get('retry-after')) * 1000;
       const delay =
         options.respectRetryAfter !== false && retryAfter > 0
@@ -126,9 +171,18 @@ async function api(method, path, body, options = {}) {
       data = { raw: text };
     }
     if (!res.ok) {
-      // Surface the API's structured error verbatim (401 auth, 402 credits, 403 scope, …).
-      if (res.status >= 500 && options.reconciliation) {
-        return uncertainMutationFailure(res.status, data, options.reconciliation);
+      if (
+        transient
+        && policy?.effect === 'mutation'
+        && !(res.status === 429 && canRetry)
+      ) {
+        return uncertainResult({
+          context,
+          method: verb,
+          path,
+          upstreamStatus: res.status,
+          reconciliation: options.reconciliation,
+        });
       }
       return {
         ok: false,
@@ -144,6 +198,9 @@ async function api(method, path, body, options = {}) {
       ...(options.captureTrace ? { trace_id: responseTraceId(res, traceId) } : {}),
     };
   }
+  if (policy?.effect === 'mutation') {
+    return uncertainResult({ context, method: verb, path, reconciliation: options.reconciliation });
+  }
   return {
     ok: false,
     status: 0,
@@ -385,7 +442,7 @@ const TOOLS = {
   list_scrapers: {
     def: {
       description:
-        'List available scrapers and the JSON Schema for each config. Ask the user the schema\'s fields (query, locations, limit, …), then fill `config` for estimate_scrape / submit_scrape.',
+        'List available scrapers, whether each requires a credential, and the JSON Schema for each config. Ask the user the schema\'s fields (query, state, locations, limit, …), then fill `config` for estimate_scrape / submit_scrape.',
       inputSchema: obj({}),
     },
     run: () => api('GET', '/scrapers'),
@@ -413,14 +470,16 @@ const TOOLS = {
   submit_scrape: {
     def: {
       description:
-        'Submit a scrape job. SPENDS vendor credits (BYOK) or lead credits (managed: 1 credit per NEW lead, deduped free) — confirm with the user first. billing: "auto" (default) uses the workspace key when one exists, else Scrapeloop\'s managed key; "byok"/"managed" force the mode. integration_id is required for BYOK, optional for managed. Surfaces 402 (budget/free-tier/credits) and 409 (rescrape confirmation needed) verbatim; pass confirm_rescrape:true to proceed past a coverage conflict.',
+        'Submit a scrape job. Optionally pass table_id from get_tables to add results to an existing writable static Table; omit it to keep results in All leads only. Paid scrapers spend vendor credits (BYOK) or lead credits (managed: 1 credit per NEW lead, deduped free), so confirm paid work with the user first. For every paid scraper, pass a positive hard_max_cost_usd equal to or above the estimate after the user confirms that ceiling; paid work will not start without it. A scraper with requires_credential=false is free and needs no integration_id, credential_id, or hard maximum. billing: "auto" (default) uses the workspace key when one exists, else Scrapeloop\'s managed key; "byok"/"managed" force the mode. integration_id is required for normal BYOK, optional for managed, and omitted for credential-free sources. Surfaces 402 (budget/free-tier/credits) and 409 (rescrape confirmation needed) verbatim; pass confirm_rescrape:true to proceed past a coverage conflict.',
       inputSchema: obj(
         {
           kind: S,
           integration_id: S,
           config: O,
+          table_id: S,
           credential_id: S,
           confirm_rescrape: B,
+          hard_max_cost_usd: { ...N, exclusiveMinimum: 0 },
           billing: { ...S, enum: ['auto', 'byok', 'managed'] },
         },
         ['kind', 'config'],
@@ -431,8 +490,10 @@ const TOOLS = {
         kind: a.kind,
         integration_id: a.integration_id ?? null,
         config: a.config || {},
+        ...(a.table_id ? { target_list_id: a.table_id } : {}),
         ...(a.credential_id ? { credential_id: a.credential_id } : {}),
         ...(a.confirm_rescrape ? { confirm_rescrape: true } : {}),
+        ...(a.hard_max_cost_usd !== undefined ? { hard_max_cost_usd: a.hard_max_cost_usd } : {}),
         ...(a.billing ? { billing: a.billing } : {}),
       }),
   },
@@ -445,7 +506,7 @@ const TOOLS = {
     run: (a) => api('GET', `/jobs/${enc(a.job_id)}`),
   },
   cancel_job: {
-    def: { description: 'Cancel a queued/running job (also best-effort cancels the vendor task).', inputSchema: obj({ job_id: S }, ['job_id']) },
+    def: { description: 'Request cancellation of a queued or running job. An active external vendor task remains nonterminal while the worker aborts it and settles final partial usage, then becomes cancelled.', inputSchema: obj({ job_id: S }, ['job_id']) },
     run: (a) => api('POST', `/jobs/${enc(a.job_id)}/cancel`),
   },
 
@@ -617,7 +678,7 @@ const TOOLS = {
   verify_catchall: {
     def: {
       description:
-        'Resolve a mailbox on a catch-all domain with the deep verifier (5 verify credits). High ROI: deliverable catch-all/unknown contacts get fewer cold emails because most senders skip them, so they reply more.',
+        'Resolve a mailbox on a catch-all domain with Scrapeloop managed verification (5 verify credits). High ROI: deliverable catch-all/unknown contacts get fewer cold emails because most senders skip them, so they reply more.',
       inputSchema: obj({ email: S }, ['email']),
     },
     run: (a) => api('POST', '/verify/catchall', { email: a.email }),
@@ -1207,6 +1268,76 @@ const TOOLS = {
       });
     },
   },
+  create_table_preset_column: {
+    def: {
+      description:
+        'Attach one shipped system preset or active workspace preset as a real enrichment column. operation_id is required and must be reused for every retry. auto_run defaults false and queues nothing. If auto_run would backfill existing rows, the API returns an exact 409 estimate first; confirm that estimate with confirm_auto_run and confirmed_estimated_cost_usd before retrying. The Table master auto-run switch and budget caps remain fail-closed. Only preset-documented overrides are accepted.',
+      inputSchema: {
+        ...obj(
+          {
+            table_id: S,
+            preset_slug: S,
+            preset_id: { ...S, format: 'uuid' },
+            label: S,
+            auto_run: B,
+            confirm_auto_run: B,
+            confirmed_estimated_cost_usd: { ...N, minimum: 0 },
+            overrides: O,
+            operation_id: {
+              ...S,
+              format: 'uuid',
+              description: 'Required stable retry key for this logical preset-column create.',
+            },
+          },
+          ['table_id', 'operation_id'],
+        ),
+        oneOf: [
+          { required: ['preset_slug'], not: { required: ['preset_id'] } },
+          { required: ['preset_id'], not: { required: ['preset_slug'] } },
+        ],
+      },
+    },
+    run: async (a) => {
+      if (!a.table_id || !a.operation_id) {
+        return {
+          ok: false,
+          status: 400,
+          error: { detail: 'table_id and a stable operation_id are required.' },
+        };
+      }
+      if (!!a.preset_slug === !!a.preset_id) {
+        return {
+          ok: false,
+          status: 400,
+          error: { detail: 'Pass exactly one of preset_slug or preset_id.' },
+        };
+      }
+      const requestBody = {
+        operation_id: a.operation_id,
+        ...(a.preset_slug !== undefined ? { preset_slug: a.preset_slug } : {}),
+        ...(a.preset_id !== undefined ? { preset_id: a.preset_id } : {}),
+        ...(a.label !== undefined ? { label: a.label } : {}),
+        ...(a.auto_run !== undefined ? { auto_run: a.auto_run } : {}),
+        ...(a.confirm_auto_run !== undefined ? { confirm_auto_run: a.confirm_auto_run } : {}),
+        ...(a.confirmed_estimated_cost_usd !== undefined
+          ? { confirmed_estimated_cost_usd: a.confirmed_estimated_cost_usd }
+          : {}),
+        ...(a.overrides !== undefined ? { overrides: a.overrides } : {}),
+      };
+      const path = `/tables/${enc(a.table_id)}/preset-columns`;
+      return api('POST', path, requestBody, {
+        reconciliation: {
+          operation_id: a.operation_id,
+          retry_with: {
+            tool: 'create_table_preset_column',
+            arguments: { ...a, operation_id: a.operation_id },
+          },
+          retry_guidance:
+            `Retry create_table_preset_column with the same operation_id ${a.operation_id}. Never substitute a new key for this logical create.`,
+        },
+      });
+    },
+  },
   set_table_cells: {
     def: {
       description:
@@ -1311,6 +1442,55 @@ const TOOLS = {
       });
     },
   },
+  list_apify_actors: {
+    def: {
+      description:
+        'List the APPROVED Apify actors you may run/import from. Arbitrary Apify actors are NOT allowed: only vetted actors (website content, contact info with add-ons off, google search with add-ons off) can be used, and LinkedIn / Facebook-group / social-graph actors are always rejected. Returns [{actor_id, add_ons_allowed}]. Use this before preview_apify_import to pick a permitted actor_id.',
+      inputSchema: obj({}),
+    },
+    run: () => api('GET', '/apify/actors'),
+  },
+  preview_apify_import: {
+    def: {
+      description:
+        "Read-only preview of an approved Apify actor's already-produced dataset before importing it. mapping is {lead_field: dotted.source.path} where lead_field is one of name, email, phone, domain, organization_name, city, state, country, linkedin_url, title. Normalizes the whole dataset (rows with no email/phone/domain/linkedin/name are skipped), returns the first 25 rows plus record_count (the true total) and a preview_hash. Pass that preview_hash to import_apify_dataset — the import re-verifies it and refuses (409) if the dataset changed. Does NOT run the actor or spend: it reads an existing dataset_id. Returns {dataset_id, actor_id, record_count, preview, preview_truncated, preview_hash}.",
+      inputSchema: obj(
+        {
+          dataset_id: { ...S, description: 'Apify dataset id from a completed actor run.' },
+          actor_id: { ...S, description: 'Approved actor id (owner/name), e.g. apify/google-search-scraper.' },
+          mapping: { ...O, description: '{lead_field: "dotted.source.path"} onto the lead spine.' },
+        },
+        ['dataset_id', 'actor_id', 'mapping'],
+      ),
+    },
+    run: (a) => api('POST', '/apify/preview', { dataset_id: a.dataset_id, actor_id: a.actor_id, mapping: a.mapping }),
+  },
+  import_apify_dataset: {
+    def: {
+      description:
+        'Import a previewed Apify dataset (≤1000 rows) into a private Scrapeloop Table through the bring-your-own-leads funnel (dedupe + identity matching + Table attach reused; no lead credits). Call preview_apify_import first and pass its preview_hash — the import re-reads the dataset and returns 409 (preview_drift) if it changed since preview. Each row gets a stable external_id (apify:{dataset}:{row}) so re-importing updates rather than duplicates; company lands in business_name and the contact name/title ride through as custom fields. Target list_id, or omit for a new "Apify import" Table. Returns the import funnel result {inserted, updated, deduped, invalid, ...}.',
+      inputSchema: obj(
+        {
+          dataset_id: S,
+          actor_id: S,
+          mapping: O,
+          preview_hash: { ...S, description: 'The preview_hash returned by preview_apify_import.' },
+          list_id: S,
+          list_name: S,
+        },
+        ['dataset_id', 'actor_id', 'mapping', 'preview_hash'],
+      ),
+    },
+    run: (a) =>
+      api('POST', '/apify/import', {
+        dataset_id: a.dataset_id,
+        actor_id: a.actor_id,
+        mapping: a.mapping,
+        preview_hash: a.preview_hash,
+        ...(a.list_id ? { list_id: a.list_id } : {}),
+        ...(a.list_name ? { list_name: a.list_name } : {}),
+      }),
+  },
   capture_community_intent: {
     def: {
       description:
@@ -1720,6 +1900,60 @@ const TOOLS = {
             error: { detail: 'campaign_id and rule_id are required.' },
           },
   },
+  test_flow_rule: {
+    def: {
+      description:
+        'Test one saved flow rule against one lead. Dry-run is the safe default and reports whether the row matches plus the action that would run. Set execute=true only after confirmation because the action may spend credits or change data.',
+      inputSchema: obj(
+        {
+          list_id: { ...S, description: 'Source Table id. Provide this or campaign_id, never both.' },
+          campaign_id: { ...S, description: 'Source campaign id. Provide this or list_id, never both.' },
+          rule_id: S,
+          lead_id: { ...S, description: 'Optional lead id. The newest source row is used when omitted.' },
+          execute: { ...B, description: 'False for dry-run. True executes the action once.' },
+        },
+        ['rule_id'],
+      ),
+    },
+    run: (a) => {
+      if (!!a.list_id === !!a.campaign_id) {
+        return {
+          ok: false,
+          status: 400,
+          error: { detail: 'Provide exactly one of list_id or campaign_id.' },
+        };
+      }
+      const source = a.list_id
+        ? `/lists/${enc(a.list_id)}`
+        : `/campaigns/${enc(a.campaign_id)}`;
+      return api('POST', `${source}/flow-rules/${enc(a.rule_id)}/test`, {
+        ...(a.lead_id ? { lead_id: a.lead_id } : {}),
+        execute: !!a.execute,
+      });
+    },
+  },
+  get_flow_rule_stats: {
+    def: {
+      description:
+        'Get the frozen 24-hour and 7-day fire, failure, last-run, and paused-state counters for every saved rule on one Table or campaign.',
+      inputSchema: obj({
+        list_id: { ...S, description: 'Source Table id. Provide this or campaign_id, never both.' },
+        campaign_id: { ...S, description: 'Source campaign id. Provide this or list_id, never both.' },
+      }),
+    },
+    run: (a) => {
+      if (!!a.list_id === !!a.campaign_id) {
+        return {
+          ok: false,
+          status: 400,
+          error: { detail: 'Provide exactly one of list_id or campaign_id.' },
+        };
+      }
+      return a.list_id
+        ? api('GET', `/lists/${enc(a.list_id)}/flow-rules/stats`)
+        : api('GET', `/campaigns/${enc(a.campaign_id)}/flow-rules/stats`);
+    },
+  },
   preview_send_to_table: {
     def: {
       description:
@@ -2366,6 +2600,49 @@ const TOOLS = {
   },
 };
 
+const extractHttpMethods = (run) => [
+  ...run.toString().matchAll(/api\(\s*['"](GET|POST|PUT|PATCH|DELETE)['"]/g),
+].map((match) => match[1]);
+
+export const TOOL_HTTP_OPERATIONS = Object.freeze(
+  Object.fromEntries(
+    Object.entries(TOOLS).map(([name, tool]) => [
+      name,
+      Object.freeze([...new Set(extractHttpMethods(tool.run))]),
+    ]),
+  ),
+);
+
+for (const [name, tool] of Object.entries(TOOLS)) {
+  const originalRun = tool.run;
+  const policy = MUTATION_POLICIES[name];
+  const methods = TOOL_HTTP_OPERATIONS[name];
+  const retryCopy = policy
+    ? RETRY_CONTRACT_COPY[policy.retry]
+    : methods.every((method) => method === 'GET')
+      ? RETRY_CONTRACT_COPY.bounded
+      : 'Policy missing. This operation is blocked until its retry contract is reviewed.';
+  tool.def.description = `${tool.def.description} Retry contract: ${retryCopy}`;
+  if (policy?.retry === 'idempotency_key') {
+    const schema = tool.def.inputSchema;
+    tool.def.inputSchema = {
+      ...schema,
+      properties: {
+        ...schema.properties,
+        idempotency_key: {
+          type: 'string',
+          description: 'Stable UUID for this exact mutation. Reuse it after a timeout or lost response.',
+        },
+      },
+      required: [...new Set([...(schema.required || []), 'idempotency_key'])],
+    };
+  }
+  tool.run = (args = {}) => toolCallContext.run(
+    { toolName: name, policy, args },
+    () => originalRun(args),
+  );
+}
+
 async function serve() {
   // Start cleanly even without a key — never crash or hang. The first tools/call
   // returns a clear, structured auth error (api() handles the missing key), and we
@@ -2379,7 +2656,7 @@ async function serve() {
   }
 
   const server = new Server(
-    { name: 'scrapeloop-mcp', version: '0.7.0' },
+    { name: 'scrapeloop-mcp', version: '0.7.1' },
     { capabilities: { tools: {} } }
   );
 
@@ -2423,6 +2700,7 @@ async function serve() {
 // the install path contains spaces — import.meta.url percent-encodes them but
 // process.argv[1] does not — so an explicit opt-out flag is used instead.)
 export {
+  MUTATION_POLICIES,
   TOOLS,
   classifyApiKeyPreflight,
   formatApiKeyPreflightWarning,

package/src/mutation-policies.js

@@ -0,0 +1,206 @@
+/**
+ * Retry contracts for every MCP operation that does not use HTTP GET.
+ *
+ * A POST may still be read-only, such as an estimate with a JSON filter body.
+ * Every true mutation declares whether it is provably idempotent, protected by
+ * a durable caller key, reconciliation-only, or forbidden from automatic retry.
+ */
+
+const read = (method = 'POST') => ({ method, effect: 'read', retry: 'bounded' });
+const idempotent = (method, inspectWith, matchFields) => ({
+  method,
+  effect: 'mutation',
+  retry: 'idempotent',
+  inspect_with: inspectWith,
+  match_fields: matchFields,
+});
+const keyed = (method, inspectWith, matchFields) => ({
+  method,
+  effect: 'mutation',
+  retry: 'idempotency_key',
+  inspect_with: inspectWith,
+  match_fields: matchFields,
+});
+const reconcile = (method, inspectWith, matchFields) => ({
+  method,
+  effect: 'mutation',
+  retry: 'reconcile',
+  inspect_with: inspectWith,
+  match_fields: matchFields,
+});
+const never = (method, inspectWith, matchFields) => ({
+  method,
+  effect: 'mutation',
+  retry: 'never',
+  inspect_with: inspectWith,
+  match_fields: matchFields,
+});
+
+export const MUTATION_POLICIES = Object.freeze({
+  create_integration: keyed('POST', ['list_integrations'], ['vendor', 'plugin_kind']),
+  add_credential: reconcile('POST', ['list_credentials'], ['integration_id', 'label']),
+  test_credential: idempotent('POST', ['list_credentials'], ['credential_id']),
+  estimate_scrape: read(),
+  submit_scrape: keyed('POST', ['list_jobs'], ['kind', 'integration_id', 'credential_id', 'table_id']),
+  cancel_job: never('POST', ['get_job'], ['job_id', 'status']),
+  search_leads: read(),
+  estimate_leads: read(),
+  expand_job_titles: read(),
+  reveal_lead: idempotent('POST', ['search_leads', 'get_credits'], ['global_person_id']),
+  save_leads: reconcile('POST', ['search_leads', 'get_credits'], ['global_person_ids']),
+  estimate_lead_import: read(),
+  import_leads_to_table: reconcile('POST', ['get_lists', 'get_list_rows'], ['list_id', 'new_list_name']),
+  save_search: idempotent('POST', ['list_saved_searches'], ['name']),
+  bulk_verify_leads: reconcile('POST', ['list_jobs'], ['lead_ids', 'global_person_ids']),
+  search_local_leads: read(),
+  estimate_local_leads: read(),
+  reveal_local_lead: idempotent('POST', ['search_local_leads', 'get_credits'], ['place_id']),
+  fill_coverage_gap: reconcile('POST', ['list_jobs', 'search_local_leads'], ['filters']),
+  verify_email: never('POST', ['get_credits'], ['email']),
+  verify_catchall: keyed('POST', ['get_credits'], ['email']),
+  preview_cleaners: read(),
+  apply_cleaners: reconcile('POST', ['get_lists'], ['list_id', 'cleaners']),
+  create_preset: reconcile('POST', ['list_presets'], ['name']),
+  estimate_enrich: read(),
+  run_enrich: never('POST', ['list_jobs'], ['preset_slug', 'preset_id', 'lead_ids', 'list_id']),
+  test_recipe: never('POST', ['get_credits'], ['lead_id']),
+  update_ai_settings: idempotent('PUT', ['get_ai_settings'], ['default_ai_model', 'enabled_models']),
+  update_ai_context: idempotent('PUT', ['get_ai_context'], ['company_description', 'icp']),
+  generate_ai_context: never('POST', ['get_ai_context', 'get_credits'], ['domain']),
+  create_strategy: reconcile('POST', ['list_strategies'], ['name']),
+  assign_strategy: reconcile('POST', ['list_strategies'], ['strategy_id', 'lead_ids', 'list_id']),
+  import_instantly_campaigns: reconcile('POST', ['list_campaigns'], ['credential_id', 'campaign_ids']),
+  import_instantly_lead_list: reconcile('POST', ['get_lists'], ['credential_id', 'lead_list_id']),
+  create_segment: reconcile('POST', ['list_segments'], ['name']),
+  preview_segment: read(),
+  preview_add_leads_to_campaign: read(),
+  add_leads_to_campaign: never('POST', ['list_campaigns', 'campaign_stats'], ['campaign_id', 'list_id']),
+  create_campaign: keyed('POST', ['list_campaigns'], ['name', 'sender_credential_id', 'source_list_id']),
+  update_campaign: idempotent('PATCH', ['list_campaigns'], ['campaign_id']),
+  duplicate_campaign: keyed('POST', ['list_campaigns'], ['campaign_id']),
+  activate_campaign: keyed('POST', ['list_campaigns', 'campaign_stats'], ['campaign_id', 'status']),
+  pause_campaign: reconcile('POST', ['list_campaigns'], ['campaign_id', 'status']),
+  sync_campaign: idempotent('POST', ['campaign_stats'], ['campaign_id']),
+  update_sender_config: idempotent('PUT', ['get_sender_config'], ['credential_id']),
+  create_list: keyed('POST', ['get_lists'], ['name']),
+  add_list_members: idempotent('POST', ['get_list_rows'], ['list_id', 'global_person_ids']),
+  create_workbook: reconcile('POST', ['list_workbooks'], ['name', 'list_ids']),
+  add_table_to_workbook: reconcile(
+    'POST',
+    ['list_workbooks'],
+    ['workbook_id', 'list_id', 'new_table_name'],
+  ),
+  remove_table_from_workbook: reconcile(
+    'DELETE',
+    ['list_workbooks'],
+    ['workbook_id', 'list_id'],
+  ),
+  reorder_workbook_table: idempotent(
+    'PATCH',
+    ['list_workbooks'],
+    ['workbook_id', 'list_id', 'position'],
+  ),
+  duplicate_workbook: reconcile(
+    'POST',
+    ['list_workbooks'],
+    ['workbook_id', 'name', 'folder_id'],
+  ),
+  create_folder: reconcile('POST', ['list_workbooks'], ['name']),
+  move_to_folder: idempotent(
+    'PATCH',
+    ['list_workbooks'],
+    ['folder_id', 'workbook_id', 'list_id'],
+  ),
+  delete_folder: never('DELETE', ['list_workbooks'], ['folder_id']),
+  create_table: idempotent('POST', ['get_tables'], ['name', 'operation_id']),
+  create_table_column: idempotent(
+    'POST',
+    ['get_table_columns'],
+    ['table_id', 'label', 'operation_id'],
+  ),
+  create_table_preset_column: idempotent(
+    'POST',
+    ['get_table_columns'],
+    ['table_id', 'preset_slug', 'preset_id', 'label', 'operation_id'],
+  ),
+  set_table_cells: idempotent('POST', ['list_table_rows'], ['table_id']),
+  import_leads: idempotent(
+    'POST',
+    ['get_tables', 'get_list_rows'],
+    ['list_id', 'list_name', 'dedupe_by', 'operation_id'],
+  ),
+  import_leads_csv: idempotent(
+    'POST',
+    ['get_tables', 'get_list_rows'],
+    ['list_id', 'list_name', 'dedupe_by', 'operation_id'],
+  ),
+  preview_import: read(),
+  preview_apify_import: read(),
+  import_apify_dataset: idempotent(
+    'POST',
+    ['get_tables', 'get_list_rows'],
+    ['list_id', 'list_name', 'dataset_id', 'preview_hash'],
+  ),
+  capture_community_intent: idempotent(
+    'POST',
+    ['get_tables', 'get_list_rows'],
+    ['source_url', 'public_profile_url', 'observed_at', 'operation_id'],
+  ),
+  save_flow_layout: idempotent('PUT', ['get_flow_graph'], ['scope_key']),
+  create_table_flow_rule: reconcile('POST', ['list_table_flow_rules'], ['list_id', 'name']),
+  toggle_table_flow_rule: idempotent('PATCH', ['list_table_flow_rules'], ['list_id', 'rule_id', 'enabled']),
+  create_campaign_flow_rule: reconcile(
+    'POST',
+    ['list_campaign_flow_rules'],
+    ['campaign_id', 'name'],
+  ),
+  toggle_campaign_flow_rule: idempotent(
+    'PATCH',
+    ['list_campaign_flow_rules'],
+    ['campaign_id', 'rule_id', 'enabled'],
+  ),
+  test_flow_rule: never(
+    'POST',
+    ['get_flow_rule_stats', 'list_table_flow_rules', 'list_campaign_flow_rules'],
+    ['list_id', 'campaign_id', 'rule_id', 'lead_id', 'execute'],
+  ),
+  preview_send_to_table: read(),
+  send_to_table: idempotent('POST', ['get_list_rows'], ['list_id', 'destination_list_id', 'new_table_name']),
+  preview_table_write_back: read(),
+  apply_table_write_back: idempotent('POST', ['get_list_rows'], ['list_id', 'column_id', 'field']),
+  export_table_csv: reconcile('POST', ['get_table_export'], ['list_id', 'filename']),
+  create_table_view: idempotent(
+    'POST',
+    ['list_table_views'],
+    ['list_id', 'name', 'operation_id'],
+  ),
+  update_table_view: idempotent('PATCH', ['list_table_views'], ['list_id', 'view_id']),
+  delete_table_view: reconcile('DELETE', ['list_table_views'], ['list_id', 'view_id']),
+  estimate_table_column: read(),
+  run_table_column: never('POST', ['get_list_history'], ['list_id', 'column_id']),
+  run_scope_summary: read(),
+  estimate_table_run_all: read(),
+  run_table_all: never('POST', ['get_list_history'], ['list_id', 'column_ids']),
+  remove_table_rows: reconcile('DELETE', ['list_table_rows'], ['list_id', 'lead_ids']),
+  create_list_webhook: keyed('POST', ['get_list_webhook'], ['list_id']),
+  update_list_webhook: idempotent('PATCH', ['get_list_webhook'], ['list_id']),
+  revoke_list_webhook: never('DELETE', ['get_list_webhook'], ['list_id']),
+  export_list_to_webhook: never('POST', ['get_list_history'], ['list_id']),
+  delete_list: never('DELETE', ['get_lists'], ['list_id']),
+  delete_campaign: never('DELETE', ['list_campaigns'], ['campaign_id']),
+  update_reply: idempotent('PATCH', ['list_replies'], ['reply_id']),
+  add_suppression_entry: reconcile('POST', ['list_suppression_entries'], ['kind', 'value']),
+  remove_suppression_entry: reconcile('DELETE', ['list_suppression_entries'], ['entry_id']),
+  update_suppression_settings: idempotent('PUT', ['get_suppression_settings'], ['auto_suppress_mode']),
+  roadmap_update_status: idempotent('PATCH', ['roadmap_list'], ['slug', 'status']),
+  roadmap_create_item: reconcile('POST', ['roadmap_list'], ['slug']),
+  roadmap_update_plan: idempotent('PATCH', ['roadmap_list'], ['slug']),
+});
+
+export const RETRY_CONTRACT_COPY = Object.freeze({
+  bounded: 'Read-only operation. Retries transport errors, 429, and 5xx with bounded backoff.',
+  idempotent: 'Proven idempotent write. Retries transient failures with bounded backoff.',
+  idempotency_key: 'Durable Idempotency-Key required. Transient retries replay one stored result.',
+  reconcile: 'One request only. An ambiguous result returns reconciliation tools and stable match fields.',
+  never: 'Never retried automatically. An ambiguous result must be reconciled before any new attempt.',
+});