@sellable/mcp 0.1.224 → 0.1.225

package/dist/tools/leads.js

@@ -59,6 +59,10 @@ export const MAX_SIGNAL_DISCOVERY_POSTS = 10;
 // capacity math instead of raw visible engagement counts.
 const signalDiscoveryReactionFetchLimit = 1000;
 const signalDiscoveryCommentFetchLimit = 1000;
+const prospeoCompanySearchTokenRefs = new Map();
+let prospeoCompanySearchTokenRefCounter = 0;
+const PROSPEO_COMPANY_SEARCH_TOKEN_REF_PREFIX = "mcp-prospeo-company-search-token:";
+const MAX_PROSPEO_COMPANY_SEARCH_TOKEN_REFS = 200;
 const prospeoFilterValueSchema = {
     type: "object",
     description: "Include/exclude list filter (values must match Prospeo enums)",
@@ -477,12 +481,14 @@ search_prospeo_companies({
   }
 })
 Do not invent company_oids. When seedCompanies or seedDomains are present, omit company_oids and let the backend resolve real Prospeo company IDs.
+After account approval, copy the companySearchToken exactly into confirm_prospeo_company_accounts; package-backed MCP may return a short mcp-prospeo-company-search-token:* reference to avoid long-token copy errors.
 For accounts in the news: { "company_news": { "categories": ["Funding & Investment"], "timeframe_days": 90 } }.
 For awards: { "company_awards": { "include": ["G2"], "match_mode": "CONTAINS" } }.
 For website traffic: { "company_website_traffic": { "min_monthly_visits": 50000 } }.
 For products/services, integrations, key customers, and Google discovery use "company_products_services", "company_integrations", "company_key_customers", and "company_google_discovery".
 For headcount by location: { "company_headcount_by_location": { "entries": [{ "country": "United States", "city": "Austin", "min_headcount": 10 }] } }.
 For structured ICP: { "company_icp": { "titles_include": ["Head of RevOps"], "company_sizes": ["midmarket"], "departments": { "include": ["Sales"], "match_mode": "ANY" }, "geographic_scope": "multi_country", "geographic_markets": ["United States", "Canada"] }, "company_headcount_range": ["101-200", "201-500", "501-1000"] }. Pair company_icp.company_sizes with company_headcount_range or rely on MCP normalization that derives the range; inspect the account sample for size drift. Product is not a company_icp.departments value; use titles_include for product roles. geographic_scope only accepts single_country or multi_country.
+Use company_key_customers as a standalone first-pass account filter. Do not combine company_key_customers with company_website_search, company_icp, company_keywords, or broad AI Attributes in the first call. Do not use AI, API, GTM, or SaaS as company keyword terms; use confirmed attributes or spell out artificial intelligence, application programming interface, go to market, and software as a service. Do not send company_keywords.exclude without an include keyword. For post-confirm people search, prefer person_job_title.boolean_search for long role synonym lists.
 company_intent is unsupported; support-channel AI Attribute guesses like phone/email/chat/ticket/social are not exposed. public API rows do not include lookalike tier/score/reason.`;
 function loadSignalDiscoveryConfig() {
     if (!existsSync(signalProviderConfigPath)) {
@@ -2310,14 +2316,15 @@ export async function searchProspeoCompanies(input) {
         campaignOfferId: input?.campaignOfferId,
     });
     const api = getApi();
+    const safeInput = normalizeProspeoCompanySearchInputForMcp(input);
     const response = await api.post("/api/v3/prospeo/company-search", removeUndefinedValues({
-        campaignOfferId: input?.campaignOfferId,
-        seedCompanies: input?.seedCompanies,
-        seedDomains: input?.seedDomains,
-        filters: input?.filters ?? {},
-        limit: input?.limit,
-        page: input?.page,
-        sort: input?.sort,
+        campaignOfferId: safeInput?.campaignOfferId,
+        seedCompanies: safeInput?.seedCompanies,
+        seedDomains: safeInput?.seedDomains,
+        filters: safeInput?.filters ?? {},
+        limit: safeInput?.limit,
+        page: safeInput?.page,
+        sort: safeInput?.sort,
     }));
     return compactProspeoCompanySearchResponse(response);
 }
@@ -2346,7 +2353,7 @@ export async function confirmProspeoCompanyAccounts(input) {
     const api = getApi();
     const response = await api.post("/api/v3/prospeo/company-search/confirm-domain-filter", removeUndefinedValues({
         campaignOfferId: input?.campaignOfferId,
-        companySearchToken: input.companySearchToken,
+        companySearchToken: resolveProspeoCompanySearchTokenRef(input.companySearchToken),
         selectedCompanyIds: input.selectedCompanyIds,
         name: input.name,
     }));
@@ -2355,6 +2362,49 @@ export async function confirmProspeoCompanyAccounts(input) {
 function removeUndefinedValues(input) {
     return Object.fromEntries(Object.entries(input).filter(([, value]) => value !== undefined));
 }
+function normalizeProspeoCompanySearchInputForMcp(input) {
+    const filters = input?.filters && typeof input.filters === "object"
+        ? clonePlainObject(input.filters)
+        : {};
+    const hasSeeds = (input.seedCompanies?.length ?? 0) > 0 ||
+        (input.seedDomains?.length ?? 0) > 0;
+    if (hasSeeds) {
+        const lookalike = filters.company_lookalike;
+        if (lookalike &&
+            typeof lookalike === "object" &&
+            !Array.isArray(lookalike) &&
+            "company_oids" in lookalike) {
+            delete lookalike.company_oids;
+        }
+    }
+    return {
+        ...input,
+        filters,
+    };
+}
+function clonePlainObject(input) {
+    return JSON.parse(JSON.stringify(input));
+}
+function storeProspeoCompanySearchTokenRef(token) {
+    if (typeof token !== "string" || token.length === 0) {
+        return token;
+    }
+    if (token.startsWith(PROSPEO_COMPANY_SEARCH_TOKEN_REF_PREFIX)) {
+        return token;
+    }
+    const ref = `${PROSPEO_COMPANY_SEARCH_TOKEN_REF_PREFIX}${Date.now().toString(36)}-${(++prospeoCompanySearchTokenRefCounter).toString(36)}`;
+    prospeoCompanySearchTokenRefs.set(ref, token);
+    while (prospeoCompanySearchTokenRefs.size > MAX_PROSPEO_COMPANY_SEARCH_TOKEN_REFS) {
+        const oldest = prospeoCompanySearchTokenRefs.keys().next().value;
+        if (!oldest)
+            break;
+        prospeoCompanySearchTokenRefs.delete(oldest);
+    }
+    return ref;
+}
+function resolveProspeoCompanySearchTokenRef(token) {
+    return prospeoCompanySearchTokenRefs.get(token) ?? token;
+}
 function compactProspeoCompanySearchResponse(response) {
     if (!response || typeof response !== "object") {
         return response;
@@ -2384,7 +2434,7 @@ function compactProspeoCompanySearchResponse(response) {
         },
         requestedFilters: response.normalizedFilters ?? response.filters ?? {},
         warnings: Array.isArray(response.warnings) ? response.warnings : [],
-        companySearchToken: response.companySearchToken ?? null,
+        companySearchToken: storeProspeoCompanySearchTokenRef(response.companySearchToken),
         nextStep: "Review accounts, then call confirm_prospeo_company_accounts with companySearchToken and selectedCompanyIds. These accounts are not people leads yet.",
     };
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sellable/mcp",
-  "version": "0.1.224",
+  "version": "0.1.225",
   "type": "module",
   "description": "Sellable MCP server for Claude Code and Codex campaign workflows",
   "main": "dist/index.js",

package/skills/create-campaign/SKILL.md

@@ -214,9 +214,12 @@ before person search, use the Prospeo account approval flow:
 First return an account sample and ask the user to approve the account set.
 Only call `confirm_prospeo_company_accounts` with the `companySearchToken`
 returned by `search_prospeo_companies` and selected Prospeo company IDs; never
-reconstruct raw account rows or domains manually. Account rows are not people
-leads yet. The confirmation creates the `domainFilterId` that constrains the
-follow-on `search_prospeo` people search.
+reconstruct raw account rows or domains manually; always copy the `companySearchToken` exactly.
+Package-backed MCP may return a short `mcp-prospeo-company-search-token:*`
+reference to avoid long-token copy errors. Account rows are not people leads
+yet. The confirmation creates the `domainFilterId` that constrains the follow-on
+`search_prospeo` people search.
+Always copy the `companySearchToken` exactly.
 
 Prospeo company/account search is useful when the source plan depends on
 website traffic (`company_website_traffic`), confirmed AI Attributes including
@@ -238,6 +241,22 @@ company_icp.departments value; use `titles_include` for product roles.
 `uses_ai` when that is the actual signal. Do not use `company_intent`, and do
 not invent unsupported support-channel filters or AI Attribute guesses like
 phone/email/chat/ticket/social.
+Use `company_key_customers` as a standalone first-pass account filter; in short,
+run company_key_customers as a standalone first-pass. Do not combine
+`company_key_customers` with `company_website_search`, `company_icp`,
+`company_keywords`, or broad AI Attributes in the first call. Do not use `AI`,
+`API`, `GTM`, or `SaaS` as company keyword terms; use confirmed attributes or
+spell out artificial intelligence, application programming interface, go to
+market, and software as a service. Do not send `company_keywords.exclude`
+without an include keyword, and do not duplicate `company_industry` when
+`company_icp.industries` already carries the industry. For post-confirm people
+search, prefer `person_job_title.boolean_search` for long role synonym lists
+instead of many `person_job_title.include` values plus broad department/seniority
+filters.
+Do not use `AI`, `API`, `GTM`, or `SaaS` as company keyword terms.
+Do not combine `company_key_customers` with ICP, website-search, keyword,
+attribute, industry, or headcount filters until the standalone pass proves
+useful.
 
     After scouting, ask for a second approval on Start Import. For
     LinkedIn engagement (`signal-discovery` internally), name how many

package/skills/find-leads/SKILL.md

@@ -414,15 +414,33 @@ Use first for broad persona expansion, ABM/domain targeting, hiring-led targetin
 - `company_keywords.include/exclude` values must be at least 3 characters; use
   `artificial intelligence` instead of `AI`, or use confirmed attributes such
   as `uses_ai` when that is the actual signal.
+- Use `company_key_customers` as a standalone first-pass account filter; in
+  short, run company_key_customers as a standalone first-pass. Do not
+  combine `company_key_customers` with `company_website_search`, `company_icp`,
+  `company_keywords`, or broad AI Attributes in the first call.
+- Do not combine `company_key_customers` with ICP, website-search, keyword,
+  attribute, industry, or headcount filters until the standalone pass proves
+  useful.
+- Do not use `AI`, `API`, `GTM`, or `SaaS` as company keyword terms; use
+  confirmed attributes or spell out artificial intelligence, application
+  programming interface, go to market, and software as a service.
+- Do not send `company_keywords.exclude` unless at least one include keyword is
+  present. Do not duplicate `company_industry` when `company_icp.industries`
+  already carries the industry.
 - Do not use `company_intent`. Do not invent unsupported support-channel filters
   or AI Attribute guesses like phone/email/chat/ticket/social.
 - Company/account search returns an account sample only; account rows are not people leads yet. Ask the user to approve the account sample.
 - After approval, call `confirm_prospeo_company_accounts` with the
   `companySearchToken` and selected Prospeo company IDs from
   `search_prospeo_companies`; do not reconstruct account rows or domains
-  manually.
+  manually. Always copy the `companySearchToken` exactly; package-backed MCP may
+  return a short `mcp-prospeo-company-search-token:*` reference to avoid
+  long-token copy errors.
 - Use the returned `domainFilterId` in the follow-on `search_prospeo` people
   search.
+- For post-confirm people search, prefer `person_job_title.boolean_search` for
+  long role synonym lists instead of many `person_job_title.include` values plus
+  broad department/seniority filters.
 - Prospeo is the terminal fallback for this chain. If projected fit is still
   below the 10% planning floor after reasonable Prospeo refinement, stop and ask
   for a tighter ICP/source direction instead of inventing another provider.

package/skills/providers/prospeo.md

@@ -80,7 +80,7 @@ confirm_prospeo_company_accounts({
 })
 ```
 
-Use the returned `domainFilterId` in `search_prospeo` with people filters. Do not reconstruct raw account rows or domains manually as Prospeo-sourced provenance.
+Use the returned `domainFilterId` in `search_prospeo` with people filters. Do not reconstruct raw account rows or domains manually as Prospeo-sourced provenance. Always copy the `companySearchToken` exactly from `search_prospeo_companies`; package-backed MCP may return a short `mcp-prospeo-company-search-token:*` reference so the model does not have to copy a long signed backend token.
 
 When `seedDomains` or `seedCompanies` are present, omit `company_oids`; the MCP
 backend resolves real Prospeo company IDs. Do not invent company_oids such as
@@ -100,6 +100,14 @@ company ICP departments include Consumers, Customer Success, Data, Design,
 Engineering, Finance, HR, IT, Legal, Marketing, Operations, Procurement, SMB
 Owners, Sales, and Security.
 
+Avoidable-400 guardrails:
+
+- Use `company_key_customers` as a standalone first-pass account filter; in short, run company_key_customers as a standalone first-pass. Do not combine `company_key_customers` with `company_website_search`, `company_icp`, `company_keywords`, or broad AI Attributes in the first call; inspect the account sample, then refine if needed.
+- Do not use `AI`, `API`, `GTM`, or `SaaS` as company keyword terms. Use confirmed attributes such as `uses_ai` / `has_api`, or spell out `artificial intelligence`, `application programming interface`, `go to market`, and `software as a service`.
+- Do not send `company_keywords.exclude` unless at least one include keyword is present.
+- Do not duplicate `company_industry` when `company_icp.industries` already carries the industry.
+- For post-confirm people search, prefer `person_job_title.boolean_search` for long role synonym lists instead of many `person_job_title.include` values plus broad department/seniority filters.
+
 Unsupported/caveats:
 
 - `company_intent` is unsupported by Prospeo public API.
@@ -234,10 +242,13 @@ Preference rules:
 - 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.
+- For long title synonym lists, prefer `person_job_title.boolean_search` with explicit OR terms instead of oversized include arrays.
 - 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.
 - `company_keywords.include/exclude` values must be at least 3 characters; use `artificial intelligence` instead of `AI`, or use confirmed attributes such as `uses_ai` when that is the real signal.
+- Do not use `AI`, `API`, `GTM`, or `SaaS` as company keyword terms; use longer phrases such as `artificial intelligence`, `application programming interface`, `go to market`, or `software as a service`.
+- Run `company_key_customers` as a standalone first-pass filter. Do not combine `company_key_customers` with ICP, website-search, keyword, attribute, industry, or headcount filters until the standalone pass proves useful.
 
 ### Person Filters