scrapeloop-mcp 0.3.0

package/README.md

@@ -0,0 +1,87 @@
+# scrapeloop-mcp
+
+A [Model Context Protocol](https://modelcontextprotocol.io) server for Scrapeloop.
+**Set up and run Scrapeloop end-to-end from Claude Desktop, Cursor, ChatGPT, or any
+MCP client** — connect integrations, scrape or pull from the lead database, verify
+(incl. catch-all), clean, enrich, tag, and feed Instantly campaigns.
+
+Pair it with the [`scrapeloop-setup` skill](../skill) for a guided, step-by-step
+flow ("set up Scrapeloop").
+
+## Setup
+
+1. Generate an API key in Scrapeloop: **Settings → API access → "MCP / full
+   automation"** (mints an `sl_live_…` key with the full driving scope set).
+2. Add it to your MCP client config.
+
+### Claude Desktop
+
+`~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or
+`%APPDATA%\Claude\claude_desktop_config.json` (Windows):
+
+```json
+{
+  "mcpServers": {
+    "scrapeloop": {
+      "command": "npx",
+      "args": ["-y", "scrapeloop-mcp"],
+      "env": {
+        "SCRAPELOOP_API_KEY": "sl_live_your_key_here"
+      }
+    }
+  }
+}
+```
+
+(For local/self-hosted, also set `SCRAPELOOP_API_URL`, e.g. `http://localhost:8000`.)
+
+### ChatGPT / other MCP clients
+
+Add the same command + `SCRAPELOOP_API_KEY` as a custom connector. For ChatGPT,
+pair it with the generated instructions pack (skill `dist/chatgpt-instructions.md`).
+
+## Scopes
+
+The key's scopes gate the **write/spend** surface (reads are free + ungated; credit
+gating lives in the API as 402s). The "MCP / full automation" preset requests the
+full set so the setup flow works end-to-end:
+
+```
+leads:read  leads:reveal  verify  lists  lists:write  integrations:read
+integrations:write  scrape  enrich  cleaners  strategies  campaigns:write  instantly
+```
+
+A 403 with `"API key missing scope(s): …"` means the key was minted with a narrower
+set — regenerate it with the full preset.
+
+## Tools
+
+Call **`get_capabilities`** first (the live manifest: scrapers + schemas, presets,
+cleaners, strategy tags, vendors, scopes, and the ordered 7 setup steps) and
+**`get_setup_status`** to see what's done. Then walk the steps. Tools cover:
+
+| Area | Tools |
+|------|-------|
+| Discovery | `get_capabilities`, `get_setup_status`, `get_credits`, `get_meta` |
+| Integrations (BYOK) | `list_integrations`, `create_integration`, `list_credentials`, `add_credential`, `test_credential`, `list_instantly_connections` |
+| Scrape | `list_scrapers`, `estimate_scrape`, `submit_scrape`, `list_jobs`, `get_job`, `cancel_job` |
+| Lead database | `search_leads`, `estimate_leads`, `reveal_lead`, `save_leads`, `bulk_verify_leads` |
+| Verify | `verify_email`, `verify_catchall` |
+| Clean | `list_cleaners`, `preview_cleaners`, `apply_cleaners` |
+| 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` |
+| Lists | `get_lists`, `create_list`, `add_list_members` |
+
+Credit-spending (`reveal_lead`, `save_leads`, `submit_scrape`, `verify_*`,
+`run_enrich`) and send-starting (`activate_campaign`) tools should be preceded by the
+matching `estimate_*` call and an explicit user confirmation. Out-of-credit (402),
+missing-scope (403), and confirmation-needed (409) responses are returned verbatim so
+the assistant can explain or self-correct.
+
+## Develop / smoke-test locally
+
+```bash
+SCRAPELOOP_API_URL=http://localhost:8000 \
+SCRAPELOOP_API_KEY=sl_live_… \
+  node test/mcp_smoke.mjs       # drives tools against a running API + drift-checks the manifest
+```

package/package.json

@@ -0,0 +1,25 @@
+{
+  "name": "scrapeloop-mcp",
+  "version": "0.3.0",
+  "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",
+  "bin": {
+    "scrapeloop-mcp": "src/index.js"
+  },
+  "files": [
+    "src",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.0.0"
+  },
+  "keywords": ["mcp", "scrapeloop", "leads", "b2b", "email-verification", "cold-email", "model-context-protocol"],
+  "homepage": "https://scrapeloop.com",
+  "repository": { "type": "git", "url": "git+https://github.com/Hinkam-Lanello/scrapeloop.git", "directory": "packages/mcp" },
+  "bugs": { "url": "https://github.com/Hinkam-Lanello/scrapeloop/issues" },
+  "publishConfig": { "access": "public" },
+  "license": "UNLICENSED"
+}

package/src/index.js

@@ -0,0 +1,608 @@
+#!/usr/bin/env node
+/**
+ * scrapeloop-mcp — Model Context Protocol server for Scrapeloop.
+ *
+ * A thin wrapper over the Scrapeloop REST API (/api/v1). Authenticates with a
+ * per-workspace API key (Settings → API access). Credit-gated actions surface
+ * 402/403 bodies verbatim so the model can self-correct or prompt a top-up.
+ *
+ * The full setup flow (connect → choose source → configure → verify → clean →
+ * enrich → campaigns) is driven by these tools. Call `get_capabilities` first to
+ * learn what this workspace actually has and `get_setup_status` to know where the
+ * user already is, then walk the manifest's `steps` in order.
+ *
+ * Env:
+ *   SCRAPELOOP_API_KEY   required — sl_live_… key
+ *   SCRAPELOOP_API_URL   optional — defaults to https://api.scrapeloop.com
+ */
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import {
+  CallToolRequestSchema,
+  ListToolsRequestSchema,
+} from '@modelcontextprotocol/sdk/types.js';
+
+const API_KEY = process.env.SCRAPELOOP_API_KEY;
+const BASE = (process.env.SCRAPELOOP_API_URL || 'https://api.scrapeloop.com').replace(/\/$/, '');
+const TIMEOUT_MS = Number(process.env.SCRAPELOOP_TIMEOUT_MS) || 30000;
+const MAX_RETRIES = 3;
+
+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.
+async function api(method, path, body) {
+  if (!API_KEY) {
+    return {
+      ok: false,
+      status: 401,
+      error: {
+        detail:
+          'SCRAPELOOP_API_KEY is not set. Generate one in Scrapeloop → Settings → ' +
+          'API access ("MCP / full automation") and add it to this server\'s env.',
+      },
+    };
+  }
+  let lastErr;
+  for (let attempt = 0; attempt <= MAX_RETRIES; attempt++) {
+    let res;
+    try {
+      res = await fetch(`${BASE}/api/v1${path}`, {
+        method,
+        headers: { Authorization: `Bearer ${API_KEY}`, 'Content-Type': 'application/json' },
+        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 < MAX_RETRIES) {
+        await sleep(500 * 2 ** attempt);
+        continue;
+      }
+      const timedOut = e && (e.name === 'TimeoutError' || e.name === 'AbortError');
+      return {
+        ok: false,
+        status: 0,
+        error: { detail: `Could not reach Scrapeloop (${timedOut ? `timeout after ${TIMEOUT_MS}ms` : String(e)}).` },
+      };
+    }
+    // Retry transient upstream failures (rate limit / server errors).
+    if ((res.status === 429 || res.status >= 500) && attempt < MAX_RETRIES) {
+      const retryAfter = Number(res.headers.get('retry-after')) * 1000;
+      await sleep(retryAfter > 0 ? retryAfter : 500 * 2 ** attempt);
+      continue;
+    }
+    const text = await res.text();
+    let data;
+    try {
+      data = text ? JSON.parse(text) : {};
+    } catch {
+      data = { raw: text };
+    }
+    if (!res.ok) {
+      // Surface the API's structured error verbatim (401 auth, 402 credits, 403 scope, …).
+      return { ok: false, status: res.status, error: data };
+    }
+    return { ok: true, status: res.status, data };
+  }
+  return { ok: false, status: 0, error: { detail: `Request failed: ${String(lastErr)}` } };
+}
+
+const result = (payload) => ({
+  content: [{ type: 'text', text: JSON.stringify(payload, null, 2) }],
+  isError: payload && payload.ok === false,
+});
+
+const enc = encodeURIComponent;
+// Build "?k=v&…" from defined args, omitting undefined/null.
+const qs = (params) => {
+  const parts = Object.entries(params)
+    .filter(([, v]) => v !== undefined && v !== null)
+    .map(([k, v]) => `${enc(k)}=${enc(v)}`);
+  return parts.length ? `?${parts.join('&')}` : '';
+};
+
+const obj = (properties, required) => ({
+  type: 'object',
+  properties,
+  ...(required ? { required } : {}),
+});
+const S = { type: 'string' };
+const N = { type: 'number' };
+const B = { type: 'boolean' };
+const O = { type: 'object' };
+const ARR = (items) => ({ type: 'array', items });
+
+// --- Tool registry: name → { def, run } -------------------------------------
+const TOOLS = {
+  // ── Discovery / status ────────────────────────────────────────────────
+  get_capabilities: {
+    def: {
+      description:
+        'Fetch the live Scrapeloop capability manifest: scrapers (+ their config schemas), enrichment primitives & presets, cleaners, strategy tags, vendors, scopes, filter enums, and the ordered 7 setup steps with guidance. CALL THIS FIRST and whenever unsure what is available — it reflects the workspace as it is right now.',
+      inputSchema: obj({}),
+    },
+    run: () => api('GET', '/manifest'),
+  },
+  get_setup_status: {
+    def: {
+      description:
+        'Onboarding checklist booleans (integration connected, a lead revealed, a verify run, a list created) so you know what is already done and where to resume.',
+      inputSchema: obj({}),
+    },
+    run: () => api('GET', '/setup/status'),
+  },
+  get_credits: {
+    def: {
+      description: 'Get the workspace lead-credit and verify-credit balances.',
+      inputSchema: obj({}),
+    },
+    run: () => api('GET', '/credits'),
+  },
+  get_meta: {
+    def: {
+      description:
+        'List the canonical values for a lead-database filter (seniorities, functions, email_quality_labels, employee_ranges) so search inputs are valid. Use "_all" for everything.',
+      inputSchema: obj({ filter: { ...S, description: 'filter name or "_all"' } }, ['filter']),
+    },
+    run: (a) => api('GET', `/meta/${enc(a.filter)}`),
+  },
+
+  // ── Step 1: integrations + credentials (BYOK) ─────────────────────────
+  list_integrations: {
+    def: { description: 'List the workspace integrations (connected vendors).', inputSchema: obj({}) },
+    run: () => api('GET', '/integrations'),
+  },
+  create_integration: {
+    def: {
+      description:
+        'Register a vendor integration before adding its key. plugin_kind is scraper|enricher|sender|crm|notification (e.g. outscraper→scraper, instantly→sender, reoon→enricher).',
+      inputSchema: obj(
+        {
+          vendor: S,
+          plugin_kind: { ...S, enum: ['scraper', 'enricher', 'sender', 'crm', 'notification'] },
+          selection_strategy: { ...S, enum: ['cheapest_first', 'round_robin', 'sticky', 'manual'] },
+          monthly_cap_usd: N,
+        },
+        ['vendor', 'plugin_kind'],
+      ),
+    },
+    run: (a) =>
+      api('POST', '/integrations', {
+        vendor: a.vendor,
+        plugin_kind: a.plugin_kind,
+        ...(a.selection_strategy ? { selection_strategy: a.selection_strategy } : {}),
+        ...(a.monthly_cap_usd != null ? { monthly_cap_usd: a.monthly_cap_usd } : {}),
+      }),
+  },
+  list_credentials: {
+    def: {
+      description: "List an integration's stored credentials (masked — keys are never returned).",
+      inputSchema: obj({ integration_id: S }, ['integration_id']),
+    },
+    run: (a) => api('GET', `/integrations/${enc(a.integration_id)}/credentials`),
+  },
+  add_credential: {
+    def: {
+      description:
+        'Store a BYOK vendor API key (Outscraper/Apify/Prospeo/Instantly/Reoon/BounceBan). The key is validated against the vendor on save and encrypted at rest.',
+      inputSchema: obj(
+        { integration_id: S, label: S, raw_key: S, notes: S },
+        ['integration_id', 'label', 'raw_key'],
+      ),
+    },
+    run: (a) =>
+      api('POST', `/integrations/${enc(a.integration_id)}/credentials`, {
+        label: a.label,
+        raw_key: a.raw_key,
+        ...(a.notes ? { notes: a.notes } : {}),
+      }),
+  },
+  test_credential: {
+    def: {
+      description: 'Live-check a stored credential against the vendor (free). Returns ok + balance where available.',
+      inputSchema: obj({ credential_id: S }, ['credential_id']),
+    },
+    run: (a) => api('POST', `/credentials/${enc(a.credential_id)}/test`),
+  },
+  list_instantly_connections: {
+    def: { description: 'List the connected Instantly sender keys in the workspace.', inputSchema: obj({}) },
+    run: () => api('GET', '/instantly/connections'),
+  },
+
+  // ── Step 2/3: scrapers + scrape jobs ──────────────────────────────────
+  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.',
+      inputSchema: obj({}),
+    },
+    run: () => api('GET', '/scrapers'),
+  },
+  list_primitives: {
+    def: { description: 'List enrichment primitives (the building blocks recipes compose from).', inputSchema: obj({}) },
+    run: () => api('GET', '/primitives'),
+  },
+  estimate_scrape: {
+    def: {
+      description: 'Preview a scrape job: estimated result count, cost, budget headroom, and coverage. Always show this before submit_scrape.',
+      inputSchema: obj({ kind: S, integration_id: S, config: O }, ['kind', 'config']),
+    },
+    run: (a) =>
+      api('POST', '/jobs/estimate', { kind: a.kind, integration_id: a.integration_id, config: a.config || {} }),
+  },
+  submit_scrape: {
+    def: {
+      description:
+        'Submit a scrape job. SPENDS vendor credits — confirm with the user first. Surfaces 402 (budget/free-tier) 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, credential_id: S, confirm_rescrape: B },
+        ['kind', 'integration_id', 'config'],
+      ),
+    },
+    run: (a) =>
+      api('POST', '/jobs', {
+        kind: a.kind,
+        integration_id: a.integration_id,
+        config: a.config || {},
+        ...(a.credential_id ? { credential_id: a.credential_id } : {}),
+        ...(a.confirm_rescrape ? { confirm_rescrape: true } : {}),
+      }),
+  },
+  list_jobs: {
+    def: { description: 'List recent scrape/enrich jobs in the workspace.', inputSchema: obj({}) },
+    run: () => api('GET', '/jobs'),
+  },
+  get_job: {
+    def: { description: 'Get one job with its execution steps (poll this for scrape progress).', inputSchema: obj({ job_id: S }, ['job_id']) },
+    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']) },
+    run: (a) => api('POST', `/jobs/${enc(a.job_id)}/cancel`),
+  },
+
+  // ── Lead database ─────────────────────────────────────────────────────
+  search_leads: {
+    def: {
+      description:
+        'Search the Scrapeloop B2B lead database. Emails are masked until revealed. Pass a filters object (titles, seniorities, functions, industries, countries, states, cities, company_keywords_include, employee_ranges, decision_maker, …). Free — costs no credits.',
+      inputSchema: obj({ filters: O, limit: { ...N, description: '1-100 (default 25)' }, offset: N }),
+    },
+    run: (a) => api('POST', '/leads/search', { filters: a.filters || {}, limit: a.limit || 25, offset: a.offset || 0 }),
+  },
+  estimate_leads: {
+    def: { description: 'Count how many leads match a filters object (free).', inputSchema: obj({ filters: O }) },
+    run: (a) => api('POST', '/leads/estimate', { filters: a.filters || {} }),
+  },
+  reveal_lead: {
+    def: {
+      description: "Reveal a lead's email by global_person_id. SPENDS 1 lead credit (idempotent — already-revealed leads are free).",
+      inputSchema: obj({ global_person_id: S }, ['global_person_id']),
+    },
+    run: (a) => api('POST', '/leads/reveal', { global_person_id: a.global_person_id }),
+  },
+  save_leads: {
+    def: {
+      description: 'Save leads into the workspace by global_person_id. SPENDS 1 lead credit per newly-acquired lead.',
+      inputSchema: obj({ global_person_ids: ARR(S) }, ['global_person_ids']),
+    },
+    run: (a) => api('POST', '/leads/save', { global_person_ids: a.global_person_ids }),
+  },
+  bulk_verify_leads: {
+    def: {
+      description: 'Enqueue a background verification pass over saved/DB leads (by lead_ids or global_person_ids).',
+      inputSchema: obj({ lead_ids: ARR(S), global_person_ids: ARR(S), max_per_hour: N }),
+    },
+    run: (a) =>
+      api('POST', '/leads/verify', {
+        lead_ids: a.lead_ids || [],
+        global_person_ids: a.global_person_ids || [],
+        ...(a.max_per_hour ? { max_per_hour: a.max_per_hour } : {}),
+      }),
+  },
+
+  // ── Step 4: verification ──────────────────────────────────────────────
+  verify_email: {
+    def: { description: 'Verify an email address (1 verify credit).', inputSchema: obj({ email: S }, ['email']) },
+    run: (a) => api('POST', '/verify', { email: a.email }),
+  },
+  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.',
+      inputSchema: obj({ email: S }, ['email']),
+    },
+    run: (a) => api('POST', '/verify/catchall', { email: a.email }),
+  },
+
+  // ── Step 5: cleaners ──────────────────────────────────────────────────
+  list_cleaners: {
+    def: { description: 'List the available cleaners (normalize names, drop .edu/.gov/.mil, drop free/disposable, dedup).', inputSchema: obj({}) },
+    run: () => api('GET', '/cleaners'),
+  },
+  preview_cleaners: {
+    def: {
+      description: 'Dry-run cleaners over the workspace (or one list): counts how many leads each cleaner would change. No writes.',
+      inputSchema: obj({ list_id: S, cleaners: ARR(S) }, ['cleaners']),
+    },
+    run: (a) => api('POST', '/cleaners/preview', { ...(a.list_id ? { list_id: a.list_id } : {}), cleaners: a.cleaners }),
+  },
+  apply_cleaners: {
+    def: {
+      description:
+        'Apply cleaners (confirm=true required). Non-destructive: email drops null the email + tag the row; dedup soft-removes the newer duplicate. Preview first.',
+      inputSchema: obj({ list_id: S, cleaners: ARR(S), confirm: B }, ['cleaners']),
+    },
+    run: (a) =>
+      api('POST', '/cleaners/apply', {
+        ...(a.list_id ? { list_id: a.list_id } : {}),
+        cleaners: a.cleaners,
+        confirm: a.confirm === true,
+      }),
+  },
+
+  // ── Step 6: enrichment + strategies ───────────────────────────────────
+  list_presets: {
+    def: { description: 'List enrichment recipes (system + workspace presets).', inputSchema: obj({}) },
+    run: () => api('GET', '/presets'),
+  },
+  create_preset: {
+    def: {
+      description: 'Create a custom enrichment recipe. recipe = {steps:[{kind, config}]} where kind is a primitive name.',
+      inputSchema: obj({ name: S, description: S, recipe: O }, ['name', 'recipe']),
+    },
+    run: (a) => api('POST', '/presets', { name: a.name, description: a.description, recipe: a.recipe }),
+  },
+  estimate_enrich: {
+    def: {
+      description: 'Estimate the cost of running an enrichment over leads (by preset_slug/preset_id + lead_ids or filter).',
+      inputSchema: obj({ preset_slug: S, preset_id: S, lead_ids: ARR(S), filter_query: O }),
+    },
+    run: (a) =>
+      api('POST', '/enrich/estimate', {
+        ...(a.preset_slug ? { preset_slug: a.preset_slug } : {}),
+        ...(a.preset_id ? { preset_id: a.preset_id } : {}),
+        lead_ids: a.lead_ids || [],
+        ...(a.filter_query ? { filter_query: a.filter_query } : {}),
+      }),
+  },
+  run_enrich: {
+    def: {
+      description: 'Enqueue a bulk enrichment run. SPENDS vendor credits — estimate + confirm first.',
+      inputSchema: obj({ preset_slug: S, preset_id: S, lead_ids: ARR(S), filter_query: O }),
+    },
+    run: (a) =>
+      api('POST', '/enrich/run', {
+        ...(a.preset_slug ? { preset_slug: a.preset_slug } : {}),
+        ...(a.preset_id ? { preset_id: a.preset_id } : {}),
+        lead_ids: a.lead_ids || [],
+        ...(a.filter_query ? { filter_query: a.filter_query } : {}),
+      }),
+  },
+  test_recipe: {
+    def: { description: 'Test an enrichment recipe on a single lead (synchronous).', inputSchema: obj({ recipe: O, lead_id: S }, ['recipe', 'lead_id']) },
+    run: (a) => api('POST', '/enrich/test', { recipe: a.recipe, lead_id: a.lead_id }),
+  },
+  get_ai_settings: {
+    def: { description: 'Get the workspace AI defaults + available models/pricing.', inputSchema: obj({}) },
+    run: () => api('GET', '/ai-settings'),
+  },
+  update_ai_settings: {
+    def: {
+      description: 'Update the workspace AI settings (default_ai_model, enabled_models, cache_settings).',
+      inputSchema: obj({ default_ai_model: S, enabled_models: ARR(S), cache_settings: O }),
+    },
+    run: (a) =>
+      api('PUT', '/ai-settings', {
+        ...(a.default_ai_model ? { default_ai_model: a.default_ai_model } : {}),
+        ...(a.enabled_models ? { enabled_models: a.enabled_models } : {}),
+        ...(a.cache_settings ? { cache_settings: a.cache_settings } : {}),
+      }),
+  },
+  list_strategies: {
+    def: { description: 'List the workspace strategy tags (routing tags campaigns filter on).', inputSchema: obj({}) },
+    run: () => api('GET', '/strategies'),
+  },
+  create_strategy: {
+    def: {
+      description: 'Create a workspace strategy tag (e.g. needs_website, review_first_line).',
+      inputSchema: obj({ name: S, color: S, description: S }, ['name']),
+    },
+    run: (a) => api('POST', '/strategies', { name: a.name, color: a.color, description: a.description }),
+  },
+  assign_strategy: {
+    def: {
+      description: "Tag leads with a strategy (appended to each lead's tags). Target explicit lead_ids OR every lead in a list.",
+      inputSchema: obj({ strategy_id: S, lead_ids: ARR(S), list_id: S }, ['strategy_id']),
+    },
+    run: (a) =>
+      api('POST', `/strategies/${enc(a.strategy_id)}/assign`, {
+        lead_ids: a.lead_ids || [],
+        ...(a.list_id ? { list_id: a.list_id } : {}),
+      }),
+  },
+
+  // ── Step 7: Instantly + segments + campaigns ──────────────────────────
+  list_instantly_campaigns: {
+    def: { description: "List an Instantly key's campaigns (to pick external_list_id for a Scrapeloop campaign).", inputSchema: obj({ credential_id: S }, ['credential_id']) },
+    run: (a) => api('GET', `/instantly/campaigns${qs({ credential_id: a.credential_id })}`),
+  },
+  list_instantly_lead_lists: {
+    def: { description: "List an Instantly key's CRM lead-lists.", inputSchema: obj({ credential_id: S }, ['credential_id']) },
+    run: (a) => api('GET', `/instantly/lead-lists${qs({ credential_id: a.credential_id })}`),
+  },
+  import_instantly_campaigns: {
+    def: { description: 'Import existing Instantly campaigns into Scrapeloop as paused, configurable campaigns.', inputSchema: obj({ credential_id: S, campaign_ids: ARR(S) }, ['credential_id', 'campaign_ids']) },
+    run: (a) => api('POST', '/instantly/import-campaigns', { credential_id: a.credential_id, campaign_ids: a.campaign_ids }),
+  },
+  import_instantly_lead_list: {
+    def: { description: 'Import an Instantly CRM lead-list into a new Scrapeloop list (dedup-aware).', inputSchema: obj({ credential_id: S, lead_list_id: S, name: S }, ['credential_id', 'lead_list_id']) },
+    run: (a) => api('POST', '/instantly/import-lead-list', { credential_id: a.credential_id, lead_list_id: a.lead_list_id, ...(a.name ? { name: a.name } : {}) }),
+  },
+  list_segments: {
+    def: { description: 'List lead segments (saved filter definitions campaigns can target).', inputSchema: obj({}) },
+    run: () => api('GET', '/segments'),
+  },
+  create_segment: {
+    def: { description: 'Create a segment from a filter_expression.', inputSchema: obj({ name: S, description: S, filter_expression: O }, ['name']) },
+    run: (a) => api('POST', '/segments', { name: a.name, description: a.description, filter_expression: a.filter_expression || {} }),
+  },
+  preview_segment: {
+    def: { description: 'Preview how many leads a filter_expression matches (count + sample rows).', inputSchema: obj({ filter_expression: O, limit: N }) },
+    run: (a) => api('POST', '/segments/preview', { filter_expression: a.filter_expression || {}, limit: a.limit || 10 }),
+  },
+  list_campaigns: {
+    def: { description: 'List campaigns with per-campaign stats and the bound list name.', inputSchema: obj({}) },
+    run: () => api('GET', '/campaigns'),
+  },
+  create_campaign: {
+    def: {
+      description:
+        'Create a campaign binding a Scrapeloop list (source_list_id) OR segment to an Instantly campaign (external_list_id from list_instantly_campaigns). feed_mode: off|auto_add|drip. Set target_active_count, cooldown_days (default 180), resting_period_days (default 90). Created paused — confirm before activate_campaign.',
+      inputSchema: obj(
+        {
+          name: S,
+          source_list_id: S,
+          segment_id: S,
+          sender_credential_id: S,
+          external_list_id: S,
+          instantly_campaign_name: S,
+          feed_mode: { ...S, enum: ['off', 'auto_add', 'drip'] },
+          drip_strategy: { ...S, enum: ['target_active', 'fixed_daily'] },
+          drip_daily_count: N,
+          target_active_count: N,
+          cooldown_days: N,
+          resting_period_days: N,
+        },
+        ['name', 'sender_credential_id', 'external_list_id'],
+      ),
+    },
+    run: (a) => {
+      const body = { name: a.name, sender_credential_id: a.sender_credential_id, external_list_id: a.external_list_id };
+      for (const k of [
+        'source_list_id', 'segment_id', 'instantly_campaign_name', 'feed_mode', 'drip_strategy',
+        'drip_daily_count', 'target_active_count', 'cooldown_days', 'resting_period_days',
+      ]) {
+        if (a[k] !== undefined && a[k] !== null) body[k] = a[k];
+      }
+      return api('POST', '/campaigns', body);
+    },
+  },
+  update_campaign: {
+    def: { description: 'Patch a campaign (feed_mode, target_active_count, cooldown_days, external_list_id, …).', inputSchema: obj({ campaign_id: S, patch: O }, ['campaign_id', 'patch']) },
+    run: (a) => api('PATCH', `/campaigns/${enc(a.campaign_id)}`, a.patch || {}),
+  },
+  activate_campaign: {
+    def: { description: 'Activate a campaign — STARTS the feed/send loop. Confirm with the user first.', inputSchema: obj({ campaign_id: S }, ['campaign_id']) },
+    run: (a) => api('POST', `/campaigns/${enc(a.campaign_id)}/activate`),
+  },
+  pause_campaign: {
+    def: { description: 'Pause a campaign (stops feeding/sending).', inputSchema: obj({ campaign_id: S }, ['campaign_id']) },
+    run: (a) => api('POST', `/campaigns/${enc(a.campaign_id)}/pause`),
+  },
+  sync_campaign: {
+    def: { description: 'Run one feed/offload tick for an active campaign immediately (idempotent).', inputSchema: obj({ campaign_id: S }, ['campaign_id']) },
+    run: (a) => api('POST', `/campaigns/${enc(a.campaign_id)}/sync-now`),
+  },
+  campaign_stats: {
+    def: { description: "A campaign's ledger stats + best-effort live Instantly analytics.", inputSchema: obj({ campaign_id: S }, ['campaign_id']) },
+    run: (a) => api('GET', `/campaigns/${enc(a.campaign_id)}/stats`),
+  },
+  get_sender_config: {
+    def: { description: "Get an Instantly credential's sender config (daily cap, send accounts, …).", inputSchema: obj({ credential_id: S }, ['credential_id']) },
+    run: (a) => api('GET', `/sender_configs/${enc(a.credential_id)}`),
+  },
+  update_sender_config: {
+    def: {
+      description: 'Set the sender config for an Instantly credential: daily_send_cap, send_account_emails, bounce_list_id, auto_confirm_after_days.',
+      inputSchema: obj(
+        { credential_id: S, daily_send_cap: N, send_account_emails: ARR(S), bounce_list_id: S, auto_confirm_after_days: N },
+        ['credential_id'],
+      ),
+    },
+    run: (a) =>
+      api('PUT', `/sender_configs/${enc(a.credential_id)}`, {
+        ...(a.daily_send_cap != null ? { daily_send_cap: a.daily_send_cap } : {}),
+        ...(a.send_account_emails ? { send_account_emails: a.send_account_emails } : {}),
+        ...(a.bounce_list_id ? { bounce_list_id: a.bounce_list_id } : {}),
+        ...(a.auto_confirm_after_days != null ? { auto_confirm_after_days: a.auto_confirm_after_days } : {}),
+      }),
+  },
+
+  // ── Lists ─────────────────────────────────────────────────────────────
+  get_lists: {
+    def: { description: 'List the saved lead lists in the workspace.', inputSchema: obj({}) },
+    run: () => api('GET', '/lists'),
+  },
+  create_list: {
+    def: { description: 'Create a saved lead list.', inputSchema: obj({ name: S, description: S, color: S }, ['name']) },
+    run: (a) => api('POST', '/lists', { name: a.name, description: a.description, color: a.color }),
+  },
+  add_list_members: {
+    def: { description: 'Add lead-database people to a list by global_person_id (acquires them, dedup-aware).', inputSchema: obj({ list_id: S, global_person_ids: ARR(S) }, ['list_id', 'global_person_ids']) },
+    run: (a) => api('POST', `/lists/${enc(a.list_id)}/members`, { global_person_ids: a.global_person_ids }),
+  },
+};
+
+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
+  // log exactly one warning to stderr here. The key itself is never logged.
+  if (!API_KEY) {
+    console.error(
+      'scrapeloop-mcp: SCRAPELOOP_API_KEY is not set — tools will return an auth error until it is. ' +
+        'Generate a key in Scrapeloop → Settings → API access.'
+    );
+  }
+
+  const server = new Server(
+    { name: 'scrapeloop-mcp', version: '0.3.0' },
+    { capabilities: { tools: {} } }
+  );
+
+  server.setRequestHandler(ListToolsRequestSchema, async () => ({
+    tools: Object.entries(TOOLS).map(([name, t]) => ({ name, ...t.def })),
+  }));
+
+  server.setRequestHandler(CallToolRequestSchema, async (req) => {
+    const tool = TOOLS[req.params.name];
+    if (!tool) return result({ ok: false, error: `unknown tool: ${req.params.name}` });
+    try {
+      return result(await tool.run(req.params.arguments || {}));
+    } catch (e) {
+      // Belt-and-braces: a tool's run() should already return structured errors.
+      return result({ ok: false, status: 0, error: { detail: String(e) } });
+    }
+  });
+
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+  console.error('scrapeloop-mcp running on stdio →', BASE);
+
+  // Non-blocking key validation: warn once if the key is missing/invalid, so the
+  // user sees the problem at startup instead of only on first use. Never blocks
+  // serving and never logs the key.
+  if (API_KEY) {
+    api('GET', '/me').then((r) => {
+      if (!r.ok) {
+        const why = r.status === 401 ? 'invalid or revoked' : `unreachable (status ${r.status})`;
+        console.error(`scrapeloop-mcp: API key check failed — ${why}. Tools may return auth errors.`);
+      }
+    });
+  }
+}
+
+// Exported for the manifest/tools drift test. Tests set SCRAPELOOP_MCP_NO_SERVE
+// before importing so the stdio server (and the API-key requirement) stay dormant;
+// the CLI leaves it unset and serves. (An entrypoint-URL check is unreliable when
+// 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 { TOOLS, serve };
+
+if (!process.env.SCRAPELOOP_MCP_NO_SERVE) {
+  await serve();
+}