@sellable/mcp 0.1.224 → 0.1.226

package/dist/tools/leads.js

@@ -59,6 +59,51 @@ 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 PROSPEO_LARGE_TITLE_INCLUDE_BOOLEAN_THRESHOLD = 8;
+const prospeoCompanyKeywordIncludeAliases = new Map([
+    ["ai", "artificial intelligence"],
+    ["api", "application programming interface"],
+    ["gtm", "go to market"],
+    ["saas", "software as a service"],
+]);
+const prospeoCompanyIcpRegionAliases = new Map([
+    ["north america", ["United States", "Canada"]],
+    ["na", ["United States", "Canada"]],
+    ["us", ["United States"]],
+    ["usa", ["United States"]],
+    ["u.s.", ["United States"]],
+    ["u.s.a.", ["United States"]],
+]);
+const prospeoCompanyIcpDepartments = new Set([
+    "Consumers",
+    "Customer Success",
+    "Data",
+    "Design",
+    "Engineering",
+    "Finance",
+    "HR",
+    "IT",
+    "Legal",
+    "Marketing",
+    "Operations",
+    "Procurement",
+    "SMB Owners",
+    "Sales",
+    "Security",
+]);
+const prospeoKeyCustomerCompanionFilters = [
+    "company_attributes",
+    "company_headcount_range",
+    "company_headcount_custom",
+    "company_industry",
+    "company_keywords",
+    "company_website_search",
+    "company_icp",
+];
 const prospeoFilterValueSchema = {
     type: "object",
     description: "Include/exclude list filter (values must match Prospeo enums)",
@@ -477,12 +522,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 +2357,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 +2394,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 +2403,221 @@ 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;
+            removeEmptyObjectFilter(filters, "company_lookalike");
+        }
+    }
+    normalizeMcpCompanyKeywords(filters);
+    normalizeMcpCompanyIcp(filters);
+    stripMcpDuplicateCompanyIndustry(filters);
+    stripMcpKeyCustomerCompanionFilters(filters);
+    return {
+        ...input,
+        filters,
+    };
+}
+function normalizeProspeoSearchInputForMcp(input) {
+    const filters = input?.filters && typeof input.filters === "object"
+        ? clonePlainObject(input.filters)
+        : {};
+    normalizeMcpPersonJobTitle(filters);
+    return {
+        ...input,
+        filters,
+    };
+}
+function normalizeMcpCompanyKeywords(filters) {
+    const keywords = filters.company_keywords;
+    if (!isPlainObject(keywords)) {
+        return;
+    }
+    const include = normalizeStringArray(keywords.include).map((keyword) => {
+        const alias = prospeoCompanyKeywordIncludeAliases.get(keyword.toLowerCase());
+        return alias ?? keyword;
+    });
+    const validInclude = include.filter((keyword) => keyword.length >= 3);
+    if (validInclude.length > 0) {
+        keywords.include = uniqueStrings(validInclude);
+    }
+    else {
+        delete keywords.include;
+        delete keywords.exclude;
+    }
+    if (keywords.exclude !== undefined && validInclude.length === 0) {
+        delete keywords.exclude;
+    }
+    removeEmptyObjectFilter(filters, "company_keywords");
+}
+function normalizeMcpCompanyIcp(filters) {
+    const icp = filters.company_icp;
+    if (!isPlainObject(icp)) {
+        return;
+    }
+    const scope = typeof icp.geographic_scope === "string"
+        ? icp.geographic_scope.trim()
+        : "";
+    const scopeMarkets = expandMcpCompanyIcpMarket(scope);
+    if (scopeMarkets.length > 0) {
+        icp.geographic_scope = "multi_country";
+        icp.geographic_markets = uniqueStrings([
+            ...scopeMarkets,
+            ...normalizeMcpCompanyIcpMarkets(icp.geographic_markets),
+        ]);
+    }
+    else if (scope &&
+        scope !== "single_country" &&
+        scope !== "multi_country") {
+        delete icp.geographic_scope;
+    }
+    if (icp.geographic_markets !== undefined) {
+        icp.geographic_markets = normalizeMcpCompanyIcpMarkets(icp.geographic_markets);
+        if (Array.isArray(icp.geographic_markets) &&
+            icp.geographic_markets.length === 0) {
+            delete icp.geographic_markets;
+        }
+    }
+    normalizeMcpCompanyIcpDepartments(icp);
+    removeEmptyObjectFilter(filters, "company_icp");
+}
+function normalizeMcpCompanyIcpDepartments(icp) {
+    const departments = icp.departments;
+    if (Array.isArray(departments)) {
+        const valid = departments
+            .filter((department) => typeof department === "string")
+            .filter((department) => prospeoCompanyIcpDepartments.has(department));
+        if (valid.length > 0) {
+            icp.departments = uniqueStrings(valid);
+        }
+        else {
+            delete icp.departments;
+        }
+        return;
+    }
+    if (!isPlainObject(departments)) {
+        return;
+    }
+    const include = normalizeStringArray(departments.include).filter((department) => prospeoCompanyIcpDepartments.has(department));
+    const exclude = normalizeStringArray(departments.exclude).filter((department) => prospeoCompanyIcpDepartments.has(department));
+    if (include.length > 0) {
+        departments.include = uniqueStrings(include);
+    }
+    else {
+        delete departments.include;
+    }
+    if (exclude.length > 0) {
+        departments.exclude = uniqueStrings(exclude);
+    }
+    else {
+        delete departments.exclude;
+    }
+    if (departments.include === undefined && departments.exclude === undefined) {
+        delete icp.departments;
+    }
+}
+function normalizeMcpCompanyIcpMarkets(input) {
+    const markets = normalizeStringArray(input);
+    return uniqueStrings(markets.flatMap(expandMcpCompanyIcpMarket));
+}
+function expandMcpCompanyIcpMarket(market) {
+    const trimmed = market.trim();
+    if (!trimmed) {
+        return [];
+    }
+    return prospeoCompanyIcpRegionAliases.get(trimmed.toLowerCase()) ?? [trimmed];
+}
+function stripMcpDuplicateCompanyIndustry(filters) {
+    const icp = filters.company_icp;
+    if (isPlainObject(icp) &&
+        Array.isArray(icp.industries) &&
+        icp.industries.length > 0) {
+        delete filters.company_industry;
+    }
+}
+function stripMcpKeyCustomerCompanionFilters(filters) {
+    const keyCustomers = filters.company_key_customers;
+    if (!isPlainObject(keyCustomers)) {
+        return;
+    }
+    const include = normalizeStringArray(keyCustomers.include);
+    if (include.length === 0) {
+        return;
+    }
+    for (const filterName of prospeoKeyCustomerCompanionFilters) {
+        delete filters[filterName];
+    }
+}
+function normalizeMcpPersonJobTitle(filters) {
+    const jobTitle = filters.person_job_title;
+    if (!isPlainObject(jobTitle)) {
+        return;
+    }
+    const include = normalizeStringArray(jobTitle.include);
+    const exclude = normalizeStringArray(jobTitle.exclude);
+    if (include.length > PROSPEO_LARGE_TITLE_INCLUDE_BOOLEAN_THRESHOLD &&
+        exclude.length === 0 &&
+        typeof jobTitle.boolean_search !== "string") {
+        delete jobTitle.include;
+        jobTitle.boolean_search = include
+            .map((title) => `"${title.replace(/"/g, '\\"')}"`)
+            .join(" OR ");
+    }
+}
+function isPlainObject(input) {
+    return Boolean(input) && typeof input === "object" && !Array.isArray(input);
+}
+function normalizeStringArray(input) {
+    if (!Array.isArray(input)) {
+        return [];
+    }
+    return input
+        .filter((value) => typeof value === "string")
+        .map((value) => value.trim())
+        .filter((value) => value.length > 0);
+}
+function uniqueStrings(input) {
+    return Array.from(new Set(input));
+}
+function removeEmptyObjectFilter(filters, filterName) {
+    const filter = filters[filterName];
+    if (isPlainObject(filter) && Object.keys(filter).length === 0) {
+        delete filters[filterName];
+    }
+}
+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 +2647,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.",
     };
 }
@@ -2464,7 +2727,8 @@ export async function searchProspeo(input) {
         nestedCompany?.names !== undefined) {
         throw new Error("search_prospeo does not accept filters.company.websites or filters.company.names. For known accounts, resolve names/domains into a domainFilterId with load_csv_domains or save_domain_filters. For company/account lookalikes, use search_prospeo_companies first, then confirm_prospeo_company_accounts.");
     }
-    const response = await api.post(`/api/v3/prospeo/search`, input);
+    const safeInput = normalizeProspeoSearchInputForMcp(input);
+    const response = await api.post(`/api/v3/prospeo/search`, safeInput);
     return compactProspeoSearchResponse(response);
 }
 function compactProspeoSearchResponse(response) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sellable/mcp",
-  "version": "0.1.224",
+  "version": "0.1.226",
   "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,11 @@ 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.
 
 Prospeo company/account search is useful when the source plan depends on
 website traffic (`company_website_traffic`), confirmed AI Attributes including
@@ -238,6 +240,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