@sellable/mcp 0.1.0

package/skills/providers/prospeo.md

@@ -0,0 +1,398 @@
+# Prospeo Enrichment Provider
+
+Prospeo is a data enrichment API for finding verified emails and company data. Use it as an alternative to Apollo for lead enrichment.
+
+## Search + Import (MCP)
+
+Prospeo supports search + import in the campaign builder flow.
+
+## Domain Filters (ABM / Account-Based Targeting)
+
+When a user gives company domains:
+
+1. If the domains already live in a CSV file on disk, call `load_csv_domains`.
+2. If the user pasted raw domains into chat, call `save_domain_filters`.
+3. Report validation feedback.
+4. Pass the returned `domainFilterId` into `search_prospeo`.
+
+**IMPORTANT:** NEVER pass raw domains to `search_prospeo`. ALWAYS create a `domainFilterId` first with `load_csv_domains` or `save_domain_filters`.
+
+If a user gives company names instead of domains:
+
+1. Resolve each company to its official website domain (use web search).
+2. Build the include/exclude domain lists from those resolved domains.
+3. If the domains are now in a CSV file, call `load_csv_domains`; otherwise call `save_domain_filters`.
+4. Use returned `domainFilterId` in `search_prospeo`.
+
+Example:
+
+```json
+load_csv_domains({
+  "filePath": "/absolute/path/to/accounts.csv"
+})
+```
+
+```json
+load_csv_domains({
+  "filePath": "/absolute/path/to/accounts.csv",
+  "confirmed": true,
+  "confirmationToken": "preview-token"
+})
+```
+
+```json
+save_domain_filters({
+  "include": ["stripe.com", "notion.so", "linear.app"],
+  "exclude": ["competitor.com"]
+})
+```
+
+```json
+search_prospeo({
+  "campaignOfferId": "cmp_123",
+  "domainFilterId": "clx_abc123",
+  "filters": {
+    "person_seniority": { "include": ["Vice President"] }
+  }
+})
+```
+
+- Use `search_prospeo` with filters (and optional `domainFilterId`) to find leads.
+- `search_prospeo` in MCP rejects raw domain inputs (`domains`) and nested company targeting (`filters.company.websites`, `filters.company.names`). Always use `load_csv_domains` for CSV-on-disk input or `save_domain_filters` for pasted/raw domain lists first.
+- Pass `searchId` on subsequent pages to paginate.
+- Use `import_leads` with `provider: \"prospeo\"` and the `searchId` to create a lead list and start import.
+- **IMPORTANT:** If `import_leads` returns `needsModeSelection: true`, use `AskUserQuestion` to ask "add to existing leads or replace?" Do NOT assume.
+- After the list finishes and the user confirms it looks good, call `confirm_lead_list` with the `jobId` and `targetLeadCount` from `import_leads` to import into the campaign table.
+- Post-confirm routing order is required:
+  1. `update_campaign({ currentStep: "filter-choice" })`
+  2. `wait_for_campaign_table_ready({ campaignId })`
+  3. `get_campaign_context({ campaignId, refresh: true })` then `get_rows_minimal(...)` for recommendation
+
+**Required:** Always include `campaignOfferId` on new `search_prospeo` calls so searches persist in watch mode.
+
+## Prospeo Filters (search_prospeo)
+
+Prospeo filters are split into person vs company. Most filters use `include` / `exclude` arrays, with a few special cases called out below.
+
+### Filter Selection Strategy (recommended order)
+
+1. Start with 2-3 anchors: role (`person_job_title` OR `person_department` + `person_seniority`) + company fit (`company_industry` or `domainFilterId`) + company size (`company_headcount_range`).
+2. Add geography: prefer `person_location_search`; use `company_location_search` only when HQ is part of ICP.
+3. Add precision filters last: `company_technology`, `company_funding`, `company_revenue`, `person_job_change`, `max_person_per_company`.
+4. Iterate one filter at a time:
+   - Too broad: add one narrowing filter.
+   - Too narrow: remove one hard constraint (exact title, tech, location, or funding) first.
+5. For function-specific lanes, prefer explicit function-title anchors before seniority widening:
+   - good: `Head of Security`, `Director of Security Operations`, `VP of Demand Gen`
+   - risky: bare `Head`, `Director`, `VP` plus a department guess
+   - if you widen with seniority, keep a matching department/function check and inspect the sample for `Head of X` leakage
+
+Preference rules:
+
+- For ABM lists, use `load_csv_domains` + `domainFilterId` when the accounts are already in a CSV file on disk.
+- For pasted/raw domain lists, use `save_domain_filters` + `domainFilterId` instead of inline domains or `company.websites.include`.
+- If user input starts as company names, resolve names to domains first, then use `save_domain_filters`.
+- Prefer comprehensive `person_job_title.include` lists (synonyms + role variants) for role precision.
+- Use `person_department + person_seniority` as supporting constraints when title variance is expected.
+- In security, AppSec, SOC, RevOps, Demand Gen, and similar function-specific lanes, do not rely on bare `Head` / `Director` / `VP` widening by itself. Pair seniority with explicit function keywords in `person_job_title` and verify the sample for off-function titles like `Head of Social Media`.
+- Prefer `company_headcount_range` for most sizing; use `company_headcount_custom` for precise numeric bounds.
+- Prefer `company_industry` before `company_keywords`; use keywords for refinement, not first-pass targeting.
+
+### Person Filters
+
+- `person_name`: include/exclude names
+- `person_name_or_job_title`: string quick search
+- `person_job_title`: use include/exclude OR `boolean_search` (not both)
+- `person_seniority`: include-only (do not mix include + exclude)
+- `person_department`: include-only (do not mix include + exclude)
+- `person_location_search`: include/exclude location strings from Search Suggestions (accept raw `name` or `name #ISO`)
+- `person_year_of_experience`, `person_time_in_current_role`, `person_time_in_current_company`: `{ min, max }`
+- `person_contact_details`: `{ email: [], mobile: [], operator: "OR" | "AND" }`
+- `person_job_change`: `{ timeframe_days, only_promotion, only_new_company }`
+- `max_person_per_company`
+
+Job title boolean syntax for `person_job_title.boolean_search`:
+`term`, `"term"`, `'term'`, `!term`, `AND`, `OR`, `()`. Do not mix AND/OR at the same level without parentheses.
+
+### Company Filters (allowed inside /search-person)
+
+- `company_industry`, `company_technology`, `company_email_provider`, `company_naics`, `company_sics`
+- `company_headcount_range`: array of size strings (e.g., `["51-100", "101-200"]`)
+- `company_headcount_custom`: `{ min, max }`
+- `company_location_search`: include/exclude location strings from Search Suggestions
+- `company_type`: single string (`"Private" | "Public" | "Non profit" | "Other"`)
+- `company_funding`:
+  - `stage`: array of funding stages
+  - `funding_date`: days since last funding (`90`, `180`, `270`, `365`)
+  - `last_funding` / `total_funding`: `{ min, max }` string buckets (`"<100K"`, `"100K"`, `"500K"`, `"1M"`, `"5M"`, `"10M"`)
+- `company_keywords`, `company_attributes`, `company_revenue`, `company_founded`, `company_headcount_growth`
+- `company_job_posting_hiring_for`, `company_job_posting_quantity`, `company_headcount_by_department`
+
+Domain note for MCP:
+
+- Do NOT use `company.websites.include` or `company.names.include` in `search_prospeo`.
+- Domain targeting in MCP must use `load_csv_domains` or `save_domain_filters` to create a `domainFilterId` first.
+
+### Example
+
+```json
+search_prospeo({
+  "campaignOfferId": "cmp_123",
+  "searchName": "VP Sales at SaaS 50-200",
+  "domainFilterId": "clx_abc123",
+  "filters": {
+    "person_seniority": { "include": ["Vice President"] },
+    "person_department": { "include": ["Sales"] },
+    "person_location_search": { "include": ["United States"] },
+    "company_headcount_range": ["51-100", "101-200"],
+    "company_industry": { "include": ["Software Development"] },
+    "company_funding": { "stage": ["Series A"], "funding_date": 180 }
+  }
+})
+```
+
+## Archetype Starters (quick recipes)
+
+1. Vertical SaaS (mid-market): Sales/Operations leaders, 51-500 employees, target vertical industry.
+2. Devtools: Engineering leadership titles, 51-1000 employees, technology include/exclude for stack fit.
+3. Recruiting/Staffing: TA/HR leadership titles, 201-5000 employees, people-location targeting for hiring market.
+4. Fintech compliance/security: Risk/Compliance/Security leadership with stage/revenue constraints.
+5. Agencies selling to growth teams: Marketing leadership in SMB/mid-market + industry fit.
+
+## When to Use Prospeo
+
+- **Email Finding**: Get verified work emails from LinkedIn URLs
+- **Lead Enrichment**: Add company data, job history, and contact info to leads
+- **Bulk Operations**: Enrich up to 100 leads at once
+
+## Available Tools
+
+### save_domain_filters
+
+Save include/exclude domain lists for Prospeo search and return a `domainFilterId`.
+
+Inputs:
+
+- `include?: string[]` (max 1000)
+- `exclude?: string[]` (max 1000)
+
+### load_csv_domains
+
+Preview and confirm a CSV file on disk, then return a `domainFilterId` for `search_prospeo`.
+
+Use this when:
+
+- the CSV already lives on the MCP host
+- the user wants carryover columns preserved with the domain filter
+- you need a bounded preview before upload
+
+Important behavior:
+
+- First call previews the file and returns a `confirmationToken`
+- Confirm with the same file and token to create the `domainFilterId`
+- Caps: `5 MB`, `7,500` rows, `1,000` unique candidate domains, `20` carryover columns
+- Duplicate carryover rows are `last_wins`
+
+Returns:
+
+- `id` (domain filter id)
+- `includeDomains`, `excludeDomains` (validated)
+- `validation` feedback (`includeValid`, `includeInvalid`, `excludeValid`, `excludeInvalid`, `dropped`)
+
+### enrich_with_prospeo
+
+Enrich a single person. Preferred input is LinkedIn URL.
+
+**Inputs:**
+
+- `linkedinUrl` (preferred) - LinkedIn profile URL
+- OR: `firstName` + `lastName` + (`companyName` OR `companyWebsite`)
+- `onlyVerifiedEmail` - Only return verified emails (default: true)
+- `enrichMobile` - Include mobile number, costs 10 credits (default: false)
+
+**Returns:**
+
+- Person: name, title, headline, email, emailStatus, phone, location
+- Company: name, domain, industry, employeeRange
+
+**Cost:** 1 credit (10 if enrichMobile=true)
+
+**Example:**
+
+```json
+enrich_with_prospeo({
+  "linkedinUrl": "https://linkedin.com/in/johndoe"
+})
+```
+
+**Response:**
+
+```json
+{
+  "success": true,
+  "creditsUsed": 1,
+  "person": {
+    "name": "John Doe",
+    "title": "VP of Sales",
+    "headline": "VP of Sales | B2B SaaS",
+    "email": "john.doe@company.com",
+    "emailStatus": "VERIFIED",
+    "linkedinUrl": "https://linkedin.com/in/johndoe",
+    "location": "San Francisco, CA, USA"
+  },
+  "company": {
+    "name": "Company Inc",
+    "domain": "company.com",
+    "industry": "Software",
+    "employeeRange": "51-200"
+  }
+}
+```
+
+### bulk_enrich_with_prospeo
+
+Enrich multiple people at once. Each input needs a unique identifier.
+
+**Inputs:**
+
+- `inputs` - Array of objects with:
+  - `identifier` (required) - Unique ID for correlation
+  - `linkedin_url` OR name+company fields
+- `onlyVerifiedEmail` (default: true)
+
+**Returns:**
+
+- `matched` - Array of successful enrichments
+- `notMatched` - Array of identifiers that couldn't be found
+- `summary` - Counts of requested/matched/notMatched
+
+**Cost:** 1 credit per match (not per request)
+
+**Example:**
+
+```json
+bulk_enrich_with_prospeo({
+  "inputs": [
+    { "identifier": "lead-1", "linkedin_url": "https://linkedin.com/in/johndoe" },
+    { "identifier": "lead-2", "first_name": "Jane", "last_name": "Smith", "company_name": "Acme Corp" }
+  ]
+})
+```
+
+**Response:**
+
+```json
+{
+  "success": true,
+  "totalCost": 2,
+  "summary": { "requested": 2, "matched": 2, "notMatched": 0, "invalid": 0 },
+  "matched": [
+    {
+      "identifier": "lead-1",
+      "name": "John Doe",
+      "email": "john@company.com",
+      "emailStatus": "VERIFIED",
+      "company": "Company Inc"
+    },
+    {
+      "identifier": "lead-2",
+      "name": "Jane Smith",
+      "email": "jane@acme.com",
+      "emailStatus": "VERIFIED",
+      "company": "Acme Corp"
+    }
+  ],
+  "notMatched": [],
+  "invalidDatapoints": []
+}
+```
+
+### get_prospeo_credits
+
+Check remaining credits before bulk operations.
+
+**Returns:**
+
+- `remainingCredits` - Credits available
+- `plan` - Current subscription plan
+- `renewsInDays` - Days until quota resets
+
+**Example:**
+
+```json
+get_prospeo_credits({})
+```
+
+**Response:**
+
+```json
+{
+  "plan": "Business",
+  "remainingCredits": 4500,
+  "usedCredits": 500,
+  "renewsInDays": 15
+}
+```
+
+## Workflow Patterns
+
+### Single Lead Enrichment
+
+```
+1. User provides LinkedIn URL
+2. Call enrich_with_prospeo with linkedinUrl
+3. If emailStatus is "VERIFIED", proceed with outreach
+4. If emailStatus is "UNAVAILABLE" or null, note that no verified email exists
+```
+
+### Bulk Lead Enrichment
+
+```
+1. Check credits: get_prospeo_credits
+2. Prepare inputs with unique identifiers (e.g., row IDs)
+3. Call bulk_enrich_with_prospeo (max 100 per call)
+4. Map matched results back using identifier
+5. Handle notMatched entries (may need Apollo fallback)
+```
+
+### Email Status Values
+
+| Status        | Meaning                          | Action                   |
+| ------------- | -------------------------------- | ------------------------ |
+| `VERIFIED`    | Email confirmed deliverable      | Safe to use for outreach |
+| `CATCH_ALL`   | Domain accepts all emails        | May work, higher risk    |
+| `UNAVAILABLE` | No email found                   | Try alternative methods  |
+| `INVALID`     | Email exists but not deliverable | Do not use               |
+
+## Apollo vs Prospeo Comparison
+
+| Feature            | Apollo          | Prospeo                    |
+| ------------------ | --------------- | -------------------------- |
+| Best for           | Search + enrich | Direct LinkedIn enrichment |
+| LinkedIn URL input | Via bulk_match  | Native support             |
+| Email verification | Separate step   | Included                   |
+| Mobile numbers     | Via enrichment  | 10 credits extra           |
+| Max bulk size      | 10              | 100                        |
+| Duplicate handling | Charged         | FREE (same record twice)   |
+
+**Recommendation:** Use Prospeo when you have LinkedIn URLs. Use Apollo when you need to search by filters (titles, company size, industry, etc.).
+
+## Credit Management
+
+| Operation            | Cost                               |
+| -------------------- | ---------------------------------- |
+| Single enrich        | 1 credit                           |
+| Bulk enrich          | 1 credit per match (not per input) |
+| Mobile number        | +10 credits                        |
+| Account info         | FREE                               |
+| Duplicate enrichment | FREE (same record twice)           |
+
+Always check `get_prospeo_credits` before large bulk operations.
+
+## Best Practices
+
+1. **Prefer LinkedIn URLs** - Higher match rate than name+company
+2. **Check credits first** - Avoid failed bulk operations
+3. **Use identifiers** - Map results back to your data source
+4. **Handle failures gracefully** - Some leads won't match
+5. **Batch efficiently** - Use bulk for 10+ leads to reduce API calls