scrapercity 1.0.18 → 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).',
@@ -166,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'

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-18T15:59:27.714Z
+// 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.18",
+  "version": "1.0.19",
   "description": "ScraperCity CLI & MCP Server - B2B lead generation for AI agents",
   "type": "module",
   "bin": {