scrapercity 1.0.17 → 1.0.19

package/AGENT_DOCS.txt

@@ -252,6 +252,16 @@ GET /api/v1/database/local-businesses?category=Dentist&country=US&hasContact=tru
 GET /api/v1/database/ecommerce?...
   Same pattern (including excludeDelivered and after), different dataset.
 
+POST /api/v1/database/plan  { "query": "dentists in Austin", "database": "local" }
+  (or GET /api/v1/database/plan?query=...&database=...)
+  $149/mo plan and up; planning does not count toward the daily limit. Plain English -> ready-to-run
+  database searches. query is who you want ("websites that
+  use shopify", "CEOs of SaaS companies in Texas") or what you sell ("I sell life insurance").
+  database (optional): leads | local | ecommerce; leave it out to let the planner pick.
+  Returns: { targeting, searches: [{ database, name, description, filters, count, apiEndpoint,
+             apiParams, link }] }. Filters use values the database really has; count leaves out
+             records this account already has. Send apiParams as they are to /api/v1/<apiEndpoint>.
+
 ────────────────────────────────────────
 ERROR CODES
 ────────────────────────────────────────

package/SKILL.md

@@ -81,6 +81,7 @@ Apollo scrapes take **up to 4 days** to deliver. Do NOT poll in a loop.
 | GET | `/api/v1/database/leads?title=CTO&country=United%20States&hasEmail=true&limit=100` | Lead DB ($149/mo plan and up, 100k new leads/day). Optional: `excludeDelivered=true` (only leads you don't have yet), `after=0` then `pagination.next_after` (cursor paging). Company filters: `keywords`, `revenueMin`/`revenueMax`, `companyCountry`/`companyState`/`companyCity`. Exclusions: `notTitle`, `notKeywords`, `notIndustry`. `url=<people-search URL>` searches with that URL's filters. POST with a JSON body takes the same parameters (use it for a long `url`) |
 | GET | `/api/v1/database/local-businesses?category=Dentist&country=US&hasContact=true&limit=100` | Local biz DB ($149/mo plan and up, 100k new businesses/day). Search like Google Maps: `keyword` (repeat; names and categories, any keyword) and `location` (repeat; cities, states, countries, postal codes), with `searched_as` in the response and `lead_database` when nothing is found but the Lead Database has 100+ people. Filters: `category`, `country`, `state`, `city`, `postalCode`, `query`, `minRating`/`maxRating`, `minReviews`/`maxReviews`, `hasEmail`, `hasPhone`, `hasWebsite`, `hasContact` (only businesses with a named contact person), `title` (business name), `box=minLat,minLng,maxLat,maxLng` (a map area). Exclusions: `notCategory`. `url=<Google Maps search URL>` searches with that URL's keyword and place. POST with a JSON body takes the same parameters (use it for a long `url`). Same optional `excludeDelivered` / `after` |
 | GET | `/api/v1/database/ecommerce?...` | Ecommerce DB ($149/mo plan and up). Same optional `excludeDelivered` / `after` |
+| POST | `/api/v1/database/plan` | $149/mo plan and up (GET with `?query=` also works). `{ "query": "dentists in Austin", "database"?: "leads" or "local" or "ecommerce" }` -> ready-to-run searches: `{ targeting, searches: [{ database, name, filters, count, apiEndpoint, apiParams, link }] }`. Send `apiParams` as they are to `/api/v1/<apiEndpoint>` |
 
 ## Status Values
 `RUNNING` → `SUCCEEDED` or `FAILED` or `CANCELLED`

package/bin/cli.mjs

@@ -441,6 +441,22 @@ async function main() {
         break
       }
 
+      // ── Plan: plain English -> database searches ($149/mo plan and up) ──
+      case 'plan': {
+        const database = flag('--database')
+        const query = args.join(' ').trim()
+        if (!query) die('Usage: scrapercity plan "dentists in Austin" [--database leads|local|ecommerce]')
+        const r = await sc.planSearch(query, typeof database === 'string' ? database : undefined)
+        if (r.targeting) console.log(r.targeting)
+        for (const s of r.searches || []) {
+          console.log(`\n${s.name} (${s.database}): ${Number(s.count || 0).toLocaleString()} matches`)
+          console.log(`  ${s.apiEndpoint}: ${JSON.stringify(s.apiParams)}`)
+          console.log(`  ${s.link}`)
+        }
+        if (!(r.searches || []).length) console.log('No search found for that. Try naming who or what you want.')
+        break
+      }
+
       // ── Poll (convenience) ────────────────────────────────
       case 'poll': {
         if (!args[0]) die('Usage: scrapercity poll <runId> [--interval 15]')
@@ -491,6 +507,10 @@ ScraperCity CLI - B2B lead generation from your terminal
     scrapercity logs <runId>                 View run logs
     scrapercity runs [--hours 24]            List recent runs
 
+  Plan ($149/mo plan and up):
+    scrapercity plan "dentists in Austin"    Plain English -> ready-to-run database searches
+      --database leads|local|ecommerce       Only this database (default: the ones that fit)
+
   Database ($149/mo plan and up):
     scrapercity db-leads [filters]           Query lead database
       --title --industry --country --state --city --company --domain --seniority --department

package/bin/mcp.mjs

@@ -48,6 +48,14 @@ const UTILITY_TOOLS = [
     description: 'Cancel a running scraper job.',
     inputSchema: { type: 'object', properties: { runId: { type: 'string', description: 'The run ID to cancel' } }, required: ['runId'] }
   },
+  {
+    name: 'plan_search',
+    description: 'Turn a plain-English request into ready-to-run database searches. Describe who you want ("dentists in Austin", "websites that use Shopify", "CEOs of SaaS companies in Texas") or what you sell ("I sell life insurance"). Returns a few searches, each with its database, filters set to values that database really has, how many records match (leaving out what this account already has), a dashboard link, and apiParams to pass as they are to the matching query tool: query_lead_database for database/leads, query_local_business_database for database/local-businesses, query_ecommerce_database for database/ecommerce. Included with the $149/mo plan, like the database tools. Use it before a database query whenever you are not sure of the exact filter values.',
+    inputSchema: { type: 'object', properties: {
+      query: { type: 'string', description: 'What you are looking for or what you sell, in plain English' },
+      database: { type: 'string', enum: ['leads', 'local', 'ecommerce'], description: 'Optional: plan in this database only (leads = people at companies, local = local businesses, ecommerce = online stores). Leave it out to let the planner pick the databases that fit.' }
+    }, required: ['query'] }
+  },
   {
     name: 'query_lead_database',
     description: 'Query the B2B lead database directly. Returns contacts with names, emails, phones, titles, companies (plus company website, revenue, HQ location and keywords). Up to 100 per request. Included with the $149/mo plan (100,000 new leads a day; leads you already have do not count again). For a daily pull of only new leads set excludeDelivered=true. For big pulls page with after: send after="0" first, then the pagination.next_after from each response until it is null. Have a saved people-search URL? Pass it as url to search with its filters right away (search_translation in the response says what was applied).',
@@ -111,6 +119,36 @@ const UTILITY_TOOLS = [
       excludeDelivered: { type: 'boolean', description: 'Skip businesses this account already has (from the API or unlocked in the dashboard). With this on, keep page at 1 or use after.' },
       after: { type: 'string', description: 'Cursor paging: return businesses after this id. Use "0" to start, then the pagination.next_after from each response.' }
     } }
+  },
+  {
+    name: 'query_ecommerce_database',
+    description: 'Query the ecommerce store database directly. Returns online stores with platform, estimated monthly sales and visits, employee count, emails, phones and social links. Up to 100 per request. Included with the $149/mo plan (100,000 new stores a day; stores you already have do not count again). For a daily pull of only new stores set excludeDelivered=true. For big pulls page with after: send after="0" first, then the pagination.next_after from each response until it is null.',
+    inputSchema: { type: 'object', properties: {
+      platform: { type: 'array', items: { type: 'string' }, description: 'Ecommerce platforms, e.g. ["shopify", "woocommerce"] (any match)' },
+      country: { type: 'array', items: { type: 'string' }, description: 'Two-letter country codes, e.g. ["US"]' },
+      state: { type: 'string', description: 'State (partial match)' },
+      city: { type: 'string', description: 'City (partial match)' },
+      category: { type: 'array', items: { type: 'string' }, description: 'Store categories (any match)' },
+      merchant: { type: 'string', description: 'Merchant name (partial match)' },
+      domain: { type: 'string', description: 'Store domain(s), comma or space separated' },
+      technologies: { type: 'array', items: { type: 'string' }, description: 'Technologies the store uses (any match)' },
+      planExclude: { type: 'array', items: { type: 'string' }, description: 'Exclude stores on these plan tiers, e.g. ["Shopify Plus"]' },
+      salesMin: { type: 'number', description: 'Minimum estimated monthly sales, USD' },
+      salesMax: { type: 'number', description: 'Maximum estimated monthly sales, USD' },
+      visitsMin: { type: 'number', description: 'Minimum estimated monthly visits' },
+      visitsMax: { type: 'number', description: 'Maximum estimated monthly visits' },
+      employeesMin: { type: 'number', description: 'Minimum employee count' },
+      employeesMax: { type: 'number', description: 'Maximum employee count' },
+      hasEmail: { type: 'boolean', description: 'Only stores with an email address' },
+      hasPhone: { type: 'boolean', description: 'Only stores with a phone number' },
+      hasInstagram: { type: 'boolean', description: 'Only stores with Instagram' },
+      hasFacebook: { type: 'boolean', description: 'Only stores with Facebook' },
+      hasTiktok: { type: 'boolean', description: 'Only stores with TikTok' },
+      page: { type: 'number', description: 'Page number (default 1)', default: 1 },
+      limit: { type: 'number', description: 'Results per page (max 100)', default: 50 },
+      excludeDelivered: { type: 'boolean', description: 'Skip stores this account already has (from the API or unlocked in the dashboard). With this on, keep page at 1 or use after.' },
+      after: { type: 'string', description: 'Cursor paging: return stores after this id. Use "0" to start, then the pagination.next_after from each response.' }
+    } }
   }
 ]
 
@@ -136,6 +174,7 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
           break
         }
         case 'cancel_run': result = await sc.cancel(args.runId); break
+        case 'plan_search': result = await sc.planSearch(args.query, args.database); break
         case 'query_lead_database': {
           const params = { ...args }
           if (params.hasEmail) params.hasEmail = 'true'
@@ -156,6 +195,16 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
           result = await sc.dbLocalBusinesses(params)
           break
         }
+        case 'query_ecommerce_database': {
+          const params = { ...args }
+          for (const k of ['hasEmail', 'hasPhone', 'hasInstagram', 'hasFacebook', 'hasTiktok', 'excludeDelivered']) {
+            if (params[k]) params[k] = 'true'
+            else delete params[k]
+          }
+          if (params.after !== undefined && params.after !== null) params.after = String(params.after)
+          result = await sc.dbEcommerce(params)
+          break
+        }
         default:
           return { content: [{ type: 'text', text: `Unknown tool: ${name}` }], isError: true }
       }

package/lib/catalog.generated.mjs

@@ -1,6 +1,6 @@
 // AUTO-GENERATED by scripts/generate.mjs — DO NOT EDIT BY HAND.
 // Source of truth: scraperConfigs.ts (+ src/config/scrapers.ts). Regenerate: npm run generate
-// Generated: 2026-10-09T16:22:32.237Z
+// Generated: 2026-10-19T21:46:11.092Z
 export const TOOLS = [
   {
     "name": "scrape_apollo",
@@ -661,5 +661,6 @@ export const ENDPOINTS = {
   "database-enrichment": "/api/v1/enrich",
   "database-local-business-enrichment": "/api/v1/enrich/local-businesses",
   "database-local-businesses": "/api/v1/database/local-businesses",
-  "database-ecommerce": "/api/v1/database/ecommerce"
+  "database-ecommerce": "/api/v1/database/ecommerce",
+  "database-plan": "/api/v1/database/plan"
 }

package/lib/client.mjs

@@ -208,6 +208,10 @@ export const dbEcommerce = (params) => {
   return get(`${ENDPOINTS['database-ecommerce']}?${qs}`)
 }
 
+// Plain English -> ready-to-run database searches ($149/mo plan and up). database: 'leads' | 'local' | 'ecommerce', or leave it out.
+export const planSearch = (query, database) =>
+  post('/api/v1/database/plan', database ? { query, database } : { query })
+
 // ── Poll until done ───────────────────────────────────────────
 export async function pollUntilDone(runId, { interval = 15000, timeout = 3600000, onStatus } = {}) {
   const start = Date.now()

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "scrapercity",
-  "version": "1.0.17",
+  "version": "1.0.19",
   "description": "ScraperCity CLI & MCP Server - B2B lead generation for AI agents",
   "type": "module",
   "bin": {