scrapeloop-mcp 0.3.0 → 0.5.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "scrapeloop-mcp",
-  "version": "0.3.0",
+  "version": "0.5.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": {

package/src/index.js

@@ -183,7 +183,10 @@ const TOOLS = {
       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`),
+    run: (a) =>
+      a.integration_id
+        ? api('GET', `/integrations/${enc(a.integration_id)}/credentials`)
+        : { ok: false, status: 400, error: { detail: 'integration_id is required. Use list_integrations to find it.' } },
   },
   add_credential: {
     def: {
@@ -228,28 +231,44 @@ const TOOLS = {
   },
   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']),
+      description: 'Preview a scrape job: estimated result count, cost, budget headroom, coverage, and (for managed billing) the lead-credit cost. Always show this before submit_scrape.',
+      inputSchema: obj(
+        { kind: S, integration_id: S, config: O, billing: { ...S, enum: ['auto', 'byok', 'managed'] } },
+        ['kind', 'config'],
+      ),
     },
     run: (a) =>
-      api('POST', '/jobs/estimate', { kind: a.kind, integration_id: a.integration_id, config: a.config || {} }),
+      api('POST', '/jobs/estimate', {
+        kind: a.kind,
+        integration_id: a.integration_id,
+        config: a.config || {},
+        ...(a.billing ? { billing: a.billing } : {}),
+      }),
   },
   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.',
+        '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.',
       inputSchema: obj(
-        { kind: S, integration_id: S, config: O, credential_id: S, confirm_rescrape: B },
-        ['kind', 'integration_id', 'config'],
+        {
+          kind: S,
+          integration_id: S,
+          config: O,
+          credential_id: S,
+          confirm_rescrape: B,
+          billing: { ...S, enum: ['auto', 'byok', 'managed'] },
+        },
+        ['kind', 'config'],
       ),
     },
     run: (a) =>
       api('POST', '/jobs', {
         kind: a.kind,
-        integration_id: a.integration_id,
+        integration_id: a.integration_id ?? null,
         config: a.config || {},
         ...(a.credential_id ? { credential_id: a.credential_id } : {}),
         ...(a.confirm_rescrape ? { confirm_rescrape: true } : {}),
+        ...(a.billing ? { billing: a.billing } : {}),
       }),
   },
   list_jobs: {
@@ -426,7 +445,23 @@ const TOOLS = {
       }),
   },
 
-  // ── Step 7: Instantly + segments + campaigns ──────────────────────────
+  // ── Step 7: senders + segments + campaigns ────────────────────────────
+  list_senders: {
+    def: {
+      description:
+        'List the sender vendors Scrapeloop supports (instantly, …) with each one\'s capabilities (webhooks, lead lists, async moves, bulk upload). Catalog read — use it to know what a connected sender can do before configuring feed/offload.',
+      inputSchema: obj({}),
+    },
+    run: () => api('GET', '/senders'),
+  },
+  list_sender_campaigns: {
+    def: {
+      description:
+        "List a sender credential's campaigns at the vendor (vendor-generic: works for any connected sender key, same shape as list_instantly_campaigns — use it to pick external_list_id).",
+      inputSchema: obj({ credential_id: S }, ['credential_id']),
+    },
+    run: (a) => api('GET', `/senders/${enc(a.credential_id)}/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 })}`),
@@ -496,6 +531,14 @@ const TOOLS = {
     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 || {}),
   },
+  duplicate_campaign: {
+    def: {
+      description:
+        'Duplicate a campaign: clones ALL configuration (list/segment binding, sender credential, Instantly binding, feed/drip/offload settings, field mapping) into a new draft named "Copy of …". Created SAFE regardless of the source — feed_mode is forced to off and require_approval to true, so the copy never feeds leads to Instantly until explicitly enabled. Leads/stats/ledger are NOT copied.',
+      inputSchema: obj({ campaign_id: S }, ['campaign_id']),
+    },
+    run: (a) => api('POST', `/campaigns/${enc(a.campaign_id)}/duplicate`),
+  },
   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`),
@@ -546,6 +589,189 @@ const TOOLS = {
     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 }),
   },
+  import_leads: {
+    def: {
+      description:
+        'Bring your own leads: import externally-sourced lead records into a campaign-bindable Scrapeloop list. For leads you already have (a CSV/export with emails — optionally pre-verified, with a generated first line) — no scraping, no lead credits, and NO re-verification (your verification_status is preserved). Idempotent: dedupe within the workspace by email (default) or external_id — re-running the same batch UPDATES existing leads (merges custom_fields, unions strategy tags), never duplicates. custom_fields flow through to Instantly as custom variables (usable as {{first_line}} etc.). Target an existing list_id OR a list_name (create-or-get). Batch up to 1000 records. Each record: {email (required), first_name, last_name, business_name, phone, website, address, city, state_region, country, niche, rating, reviews_count, verification_status ("verified"|"catchall_verified"|"unverified"|"risky"|"invalid"), strategy_tags:[], custom_fields:{}, external_id}. Returns {list_id, inserted, updated, deduped, invalid, invalid_reasons}. Then bind list_id with create_campaign(source_list_id=...).',
+      inputSchema: obj(
+        {
+          list_id: S,
+          list_name: S,
+          records: ARR(O),
+          dedupe_by: { ...S, description: '"email" (default) or "external_id"' },
+          default_verification_status: S,
+        },
+        ['records'],
+      ),
+    },
+    run: (a) =>
+      api('POST', '/leads/import', {
+        ...(a.list_id ? { list_id: a.list_id } : {}),
+        ...(a.list_name ? { list_name: a.list_name } : {}),
+        records: a.records || [],
+        ...(a.dedupe_by ? { dedupe_by: a.dedupe_by } : {}),
+        ...(a.default_verification_status ? { default_verification_status: a.default_verification_status } : {}),
+      }),
+  },
+  preview_import: {
+    def: {
+      description:
+        'Dry-run for import_leads: report exactly what an import WOULD do — {would_insert, would_update, deduped, invalid, invalid_reasons, list_exists} — WITHOUT writing anything (no leads, no list, no tags created). Same inputs as import_leads. Call this first for a bring-your-own batch, show the user the plan (e.g. "adds 340 new, updates 12, skips 3 bad rows"), then confirm before import_leads.',
+      inputSchema: obj(
+        {
+          list_id: S,
+          list_name: S,
+          records: ARR(O),
+          dedupe_by: { ...S, description: '"email" (default) or "external_id"' },
+          default_verification_status: S,
+        },
+        ['records'],
+      ),
+    },
+    run: (a) =>
+      api('POST', '/leads/import/preview', {
+        ...(a.list_id ? { list_id: a.list_id } : {}),
+        ...(a.list_name ? { list_name: a.list_name } : {}),
+        records: a.records || [],
+        ...(a.dedupe_by ? { dedupe_by: a.dedupe_by } : {}),
+        ...(a.default_verification_status ? { default_verification_status: a.default_verification_status } : {}),
+      }),
+  },
+  get_list_rows: {
+    def: {
+      description:
+        "Read a list's leads with their fields (email, name, status, verification_status, custom_fields, strategy tags, position). The read-back for a list built by import_leads (custom_fields + verification_status live on the lead's attributes). Paginated (limit ≤ 500, offset).",
+      inputSchema: obj({ list_id: S, limit: N, offset: N }, ['list_id']),
+    },
+    run: (a) =>
+      a.list_id
+        ? api('GET', `/lists/${enc(a.list_id)}/leads${qs({ limit: a.limit, offset: a.offset })}`)
+        : { ok: false, status: 400, error: { detail: 'list_id is required.' } },
+  },
+  delete_list: {
+    def: {
+      description:
+        'Delete a list (the list + its membership; the underlying leads stay in the workspace). Works for any Scrapeloop list. Irreversible — confirm with the user first.',
+      inputSchema: obj({ list_id: S }, ['list_id']),
+    },
+    run: (a) =>
+      a.list_id
+        ? api('DELETE', `/lists/${enc(a.list_id)}`)
+        : { ok: false, status: 400, error: { detail: 'list_id is required.' } },
+  },
+  delete_campaign: {
+    def: {
+      description:
+        'Delete a campaign (the Scrapeloop campaign + its ledger; the Instantly campaign itself is not deleted). Irreversible — if you only want to stop sending, pause_campaign instead. Confirm with the user first.',
+      inputSchema: obj({ campaign_id: S }, ['campaign_id']),
+    },
+    run: (a) =>
+      a.campaign_id
+        ? api('DELETE', `/campaigns/${enc(a.campaign_id)}`)
+        : { ok: false, status: 400, error: { detail: 'campaign_id is required.' } },
+  },
+
+  // ── Replies + suppression ─────────────────────────────────────────────
+  list_replies: {
+    def: {
+      description:
+        'List inbound campaign replies, newest first. Filters: sentiment (interested|not_interested|unsubscribed), handled (true = already actioned, false = needs attention), lead_id, campaign_id, status (pending|auto_classified|human_required|human_reviewed — human_required is the review queue).',
+      inputSchema: obj({ sentiment: S, handled: B, lead_id: S, campaign_id: S, status: S, limit: N, offset: N }),
+    },
+    run: (a) =>
+      api(
+        'GET',
+        `/replies${qs({
+          sentiment: a.sentiment,
+          handled: a.handled,
+          lead_id: a.lead_id,
+          campaign_id: a.campaign_id,
+          status: a.status,
+          limit: a.limit,
+          offset: a.offset,
+        })}`,
+      ),
+  },
+  update_reply: {
+    def: {
+      description:
+        "Update a reply: mark it handled/unhandled and/or set its sentiment. Setting sentiment is a human classification — it propagates to the lead (reply_sentiment, replied_at, status transition, the unsubscribe guard for 'unsubscribed', and the workspace's auto-suppress feed).",
+      inputSchema: obj(
+        {
+          reply_id: S,
+          handled: B,
+          sentiment: { ...S, enum: ['interested', 'not_interested', 'unsubscribed', 'neutral'] },
+        },
+        ['reply_id'],
+      ),
+    },
+    run: (a) =>
+      api('PATCH', `/replies/${enc(a.reply_id)}`, {
+        ...(a.handled !== undefined ? { handled: a.handled } : {}),
+        ...(a.sentiment ? { sentiment: a.sentiment } : {}),
+      }),
+  },
+  list_suppression_entries: {
+    def: {
+      description:
+        'List the workspace do-not-contact suppression entries (emails + whole domains, optionally expiring). q searches values; kind filters email|domain. Suppressed addresses are never uploaded to campaigns.',
+      inputSchema: obj({ q: S, kind: { ...S, enum: ['email', 'domain'] }, limit: N, offset: N }),
+    },
+    run: (a) => api('GET', `/suppression/entries${qs({ q: a.q, kind: a.kind, limit: a.limit, offset: a.offset })}`),
+  },
+  add_suppression_entry: {
+    def: {
+      description:
+        'Add a do-not-contact suppression entry: kind "email" (one address) or "domain" (the whole company). Optional expires_at (ISO timestamp; omit for permanent). For a bulk/CSV import pass entries: [{kind, value, reason}] (max 500 per call) instead of kind+value.',
+      inputSchema: obj({ kind: { ...S, enum: ['email', 'domain'] }, value: S, reason: S, expires_at: S, entries: ARR(O) }),
+    },
+    run: (a) =>
+      api('POST', '/suppression/entries', {
+        ...(a.kind ? { kind: a.kind } : {}),
+        ...(a.value ? { value: a.value } : {}),
+        ...(a.reason ? { reason: a.reason } : {}),
+        ...(a.expires_at ? { expires_at: a.expires_at } : {}),
+        ...(a.entries ? { entries: a.entries } : {}),
+      }),
+  },
+  remove_suppression_entry: {
+    def: {
+      description: 'Remove a suppression entry by id (the address/domain becomes contactable again).',
+      inputSchema: obj({ entry_id: S }, ['entry_id']),
+    },
+    run: (a) =>
+      a.entry_id
+        ? api('DELETE', `/suppression/entries/${enc(a.entry_id)}`)
+        : { ok: false, status: 400, error: { detail: 'entry_id is required. Use list_suppression_entries to find it.' } },
+  },
+  get_suppression_settings: {
+    def: {
+      description:
+        'Get the workspace auto-suppress settings: mode (manual = never auto-suppress; all_negative = suppress on any negative reply; hostile_only = suppress on hostile/unsubscribe replies) + duration in days (0 = permanent).',
+      inputSchema: obj({}),
+    },
+    run: () => api('GET', '/suppression/settings'),
+  },
+  update_suppression_settings: {
+    def: {
+      description:
+        'Set the auto-suppress policy: auto_suppress_mode (manual | all_negative | hostile_only) and auto_suppress_duration_days (0 = permanent, max 3650). Explain the choice to the user before changing it.',
+      inputSchema: obj(
+        {
+          auto_suppress_mode: { ...S, enum: ['manual', 'all_negative', 'hostile_only'] },
+          auto_suppress_duration_days: N,
+        },
+        ['auto_suppress_mode'],
+      ),
+    },
+    run: (a) =>
+      api('PUT', '/suppression/settings', {
+        auto_suppress_mode: a.auto_suppress_mode,
+        ...(a.auto_suppress_duration_days != null
+          ? { auto_suppress_duration_days: a.auto_suppress_duration_days }
+          : {}),
+      }),
+  },
 };
 
 async function serve() {
@@ -560,7 +786,7 @@ async function serve() {
   }
 
   const server = new Server(
-    { name: 'scrapeloop-mcp', version: '0.3.0' },
+    { name: 'scrapeloop-mcp', version: '0.5.0' },
     { capabilities: { tools: {} } }
   );