@coldiq/mcp 0.1.18 → 0.2.4

package/src/executor.ts

@@ -8,12 +8,27 @@ export interface ExecutionResult {
     provider: string
     latencyMs: number
     matchedFrom?: Record<string, string>
+    /** Net ColdIQ credits charged for this call (parsed from `X-ColdIQ-Credits-Charged`). */
+    credits_charged?: number
+    /** ColdIQ credit balance remaining after this call (parsed from `X-ColdIQ-Credits-Remaining`). */
+    credits_remaining?: number
   }
 }
 
 export interface ExecutionError {
   error: string
-  providers_tried: Array<{ provider: string; status: number; error: string }>
+  providers_tried: Array<{
+    provider: string
+    status: number
+    error: string
+    /**
+     * Structured upstream provider response body, when available. Lets callers
+     * see validation detail (e.g. Prospeo `filter_error`) that would otherwise
+     * be lost when the short `error` string is built. Capped at ~2KB to protect
+     * against unbounded provider payloads.
+     */
+    upstream_error?: unknown
+  }>
   /** Set when at least one provider returned 402 — points the user at the top-up page. */
   billingUrl?: string
   /** True when every attempted provider failed with 402 (the user is fully blocked on credits). */
@@ -42,6 +57,32 @@ function debug(msg: string): void {
   }
 }
 
+// ---------------------------------------------------------------------------
+// Upstream error cap
+// ---------------------------------------------------------------------------
+
+const MAX_UPSTREAM_ERROR_BYTES = 2048
+
+/**
+ * Defensive cap on upstream_error payloads. The API already caps `details` at
+ * 2KB, but pre-migration providers may surface their full `data` object here —
+ * keep this guard so a misbehaving upstream can't blow up the MCP response.
+ * Falls back to a truncated string repr when the JSON serialization is over
+ * the cap (rather than emitting malformed JSON).
+ */
+function capUpstreamError(u: unknown): unknown {
+  if (u === undefined) return undefined
+  let serialized: string
+  try {
+    serialized = JSON.stringify(u)
+  } catch {
+    return undefined
+  }
+  if (serialized === undefined) return undefined
+  if (serialized.length <= MAX_UPSTREAM_ERROR_BYTES) return u
+  return serialized.slice(0, MAX_UPSTREAM_ERROR_BYTES)
+}
+
 // ---------------------------------------------------------------------------
 // Async polling
 // ---------------------------------------------------------------------------
@@ -49,7 +90,7 @@ function debug(msg: string): void {
 async function executeAsync(
   provider: ProviderEntry,
   payload: { body?: unknown; queryParams?: Record<string, string> },
-): Promise<{ ok: boolean; data: unknown }> {
+): Promise<{ ok: boolean; data: unknown; headers: Record<string, string> }> {
   const asyncCfg = provider.async!
   const firstPollMs = parseInt(process.env.COLDIQ_FIRST_POLL_MS ?? '750', 10)
   const maxPollErrors = parseInt(process.env.COLDIQ_MAX_POLL_ERRORS ?? '3', 10)
@@ -61,15 +102,18 @@ async function executeAsync(
     debug(`${provider.id} async: create failed (${createRes.status})`)
     return createRes
   }
+  // Credit headers are emitted on the create response (where the reservation
+  // happens). Poll responses don't bill, so they won't carry them.
+  const createHeaders = createRes.headers
 
   // Step 2: extract job ID
   let jobId: string
   try {
     jobId = asyncCfg.extractId(createRes.data)
   } catch {
-    return { ok: false, data: { error: 'Could not extract job ID from async response' } }
+    return { ok: false, data: { error: 'Could not extract job ID from async response' }, headers: createHeaders }
   }
-  if (!jobId) return { ok: false, data: { error: 'Empty job ID from async response' } }
+  if (!jobId) return { ok: false, data: { error: 'Empty job ID from async response' }, headers: createHeaders }
   debug(`${provider.id} async: job created (${jobId}), polling...`)
 
   // Step 3: poll until complete or timeout.
@@ -93,7 +137,7 @@ async function executeAsync(
       consecutivePollErrors++
       if (consecutivePollErrors >= maxPollErrors) {
         log(`${provider.id} async: poll failing (${consecutivePollErrors} consecutive errors), skipping`)
-        return { ok: false, data: { error: `Poll endpoint failed ${consecutivePollErrors} consecutive times` } }
+        return { ok: false, data: { error: `Poll endpoint failed ${consecutivePollErrors} consecutive times` }, headers: createHeaders }
       }
     } else {
       consecutivePollErrors = 0
@@ -103,7 +147,7 @@ async function executeAsync(
 
       if (asyncCfg.isComplete(pollRes.data)) {
         debug(`${provider.id} async: complete`)
-        return pollRes
+        return { ...pollRes, headers: { ...createHeaders, ...pollRes.headers } }
       }
     }
 
@@ -117,13 +161,19 @@ async function executeAsync(
   }
 
   debug(`${provider.id} async: timed out after ${asyncCfg.timeoutMs / 1000}s`)
-  return { ok: false, data: { error: `Async operation timed out after ${asyncCfg.timeoutMs / 1000}s` } }
+  return { ok: false, data: { error: `Async operation timed out after ${asyncCfg.timeoutMs / 1000}s` }, headers: createHeaders }
 }
 
 function sleep(ms: number): Promise<void> {
   return new Promise((resolve) => setTimeout(resolve, ms))
 }
 
+function parseCreditHeader(raw: string | undefined): number | undefined {
+  if (raw === undefined) return undefined
+  const n = Number(raw)
+  return Number.isFinite(n) ? n : undefined
+}
+
 // ---------------------------------------------------------------------------
 // Execute a single provider
 // ---------------------------------------------------------------------------
@@ -142,7 +192,7 @@ function syncProviderTimeoutMs(): number {
 async function executeSingle(
   provider: ProviderEntry,
   input: Record<string, unknown>,
-): Promise<{ ok: boolean; status: number; data: unknown; latencyMs: number }> {
+): Promise<{ ok: boolean; status: number; data: unknown; latencyMs: number; headers: Record<string, string> }> {
   const start = Date.now()
 
   let payload: ReturnType<ProviderEntry['mapParams']>
@@ -151,12 +201,12 @@ async function executeSingle(
   } catch (err) {
     const msg = err instanceof Error ? err.message : String(err)
     debug(`${provider.id}: mapParams threw — ${msg}`)
-    return { ok: false, status: 0, data: { error: `mapParams_threw: ${msg}` }, latencyMs: Date.now() - start }
+    return { ok: false, status: 0, data: { error: `mapParams_threw: ${msg}` }, latencyMs: Date.now() - start, headers: {} }
   }
 
   debug(`${provider.id}: payload_keys = ${Object.keys(payload?.body ?? {}).join(',')}`)
 
-  let result: { ok: boolean; status: number; data: unknown }
+  let result: { ok: boolean; status: number; data: unknown; headers: Record<string, string> }
 
   if (provider.async) {
     const asyncResult = await executeAsync(provider, payload)
@@ -164,13 +214,14 @@ async function executeSingle(
   } else {
     const cap = syncProviderTimeoutMs()
     const call = callApi(provider.method, provider.endpoint, payload.body, payload.queryParams)
-    const timeout = new Promise<{ ok: boolean; status: number; data: unknown }>((resolve) =>
+    const timeout = new Promise<{ ok: boolean; status: number; data: unknown; headers: Record<string, string> }>((resolve) =>
       setTimeout(
         () =>
           resolve({
             ok: false,
             status: 0,
             data: { error: `Provider exceeded ${cap}ms sync cap` },
+            headers: {},
           }),
         cap,
       ),
@@ -215,7 +266,7 @@ export async function executeWithFallback(
     allProviders = ordered
   }
 
-  const errors: Array<{ id: string; status: number; error: string }> = []
+  const errors: Array<{ id: string; status: number; error: string; upstream_error?: unknown }> = []
   let billingUrl: string | undefined
   let zeroBalance = false
 
@@ -259,18 +310,29 @@ export async function executeWithFallback(
       if (options?.matchedFrom && Object.keys(options.matchedFrom).length > 0) {
         meta.matchedFrom = options.matchedFrom
       }
+      const charged = parseCreditHeader(result.headers['x-coldiq-credits-charged'])
+      const remaining = parseCreditHeader(result.headers['x-coldiq-credits-remaining'])
+      if (charged !== undefined) meta.credits_charged = charged
+      if (remaining !== undefined) meta.credits_remaining = remaining
       return { data: payload, _meta: meta }
     }
 
     // Record the failure
-    const rawErr = result.data && typeof result.data === 'object' && 'error' in result.data
-      ? (result.data as Record<string, unknown>).error
+    const dataObj = result.data && typeof result.data === 'object'
+      ? (result.data as Record<string, unknown>)
       : undefined
+    const rawErr = dataObj && 'error' in dataObj ? dataObj.error : undefined
     const errMsg = rawErr !== undefined
       ? (typeof rawErr === 'string' ? rawErr : JSON.stringify(rawErr))
       : `Status ${result.status}, no results`
+    // Prefer the API's sanitized `details` passthrough; fall back to the full
+    // body so providers that haven't migrated yet still surface SOMETHING
+    // structured to the caller. `'details' in dataObj` (rather than `?? dataObj`)
+    // so an explicitly-emitted `details: null/false/0` is preserved verbatim
+    // instead of silently falling through to the full body.
+    const upstreamErr = dataObj && 'details' in dataObj ? dataObj.details : dataObj
     log(`${capability} → ${provider.id} ✗ ${errMsg}`)
-    errors.push({ id: provider.id, status: result.status, error: errMsg })
+    errors.push({ id: provider.id, status: result.status, error: errMsg, upstream_error: upstreamErr })
 
     // Capture the billing URL the API surfaces in 402 responses so the
     // top-level error can include a clickable link for the user.
@@ -297,9 +359,19 @@ export async function executeWithFallback(
   // When the user pinned specific providers, expose their real IDs in the error
   // (they already know what they asked for). Otherwise anonymize to avoid leaking
   // internal provider names on auto-route failures.
+  const buildEntry = (provider: string, e: { status: number; error: string; upstream_error?: unknown }) => {
+    const entry: ExecutionError['providers_tried'][number] = {
+      provider,
+      status: e.status,
+      error: e.error.slice(0, 200),
+    }
+    const capped = capUpstreamError(e.upstream_error)
+    if (capped !== undefined) entry.upstream_error = capped
+    return entry
+  }
   const sanitized = isConstrained
-    ? errors.map((e) => ({ provider: e.id, status: e.status, error: e.error.slice(0, 200) }))
-    : errors.map((e, i) => ({ provider: `provider_${i + 1}`, status: e.status, error: e.error.slice(0, 200) }))
+    ? errors.map((e) => buildEntry(e.id, e))
+    : errors.map((e, i) => buildEntry(`provider_${i + 1}`, e))
 
   const allOutOfCredits = zeroBalance
     || (errors.length > 0 && errors.every((e) => e.status === 402))

package/src/index.ts

@@ -123,6 +123,13 @@ import {
   fetchPageContentHandler,
 } from './tools/fetch-page-content.js'
 
+import {
+  getCreditBalanceName,
+  getCreditBalanceDescription,
+  getCreditBalanceSchema,
+  getCreditBalanceHandler,
+} from './tools/get-credit-balance.js'
+
 // Initialize HTTP client (reads env vars)
 initClient()
 
@@ -149,6 +156,7 @@ server.tool(searchRedditName, searchRedditDescription, searchRedditSchema, searc
 server.tool(searchSeoName, searchSeoDescription, searchSeoSchema, searchSeoHandler)
 server.tool(findSignalsName, findSignalsDescription, findSignalsSchema, findSignalsHandler)
 server.tool(fetchPageContentName, fetchPageContentDescription, fetchPageContentSchema, fetchPageContentHandler)
+server.tool(getCreditBalanceName, getCreditBalanceDescription, getCreditBalanceSchema, getCreditBalanceHandler)
 
 // Connect via stdio transport
 const transport = new StdioServerTransport()

package/src/registry.ts

@@ -76,6 +76,28 @@ function hasAnyKey(obj: unknown, keys: string[]): boolean {
   })
 }
 
+// Prospeo only accepts headcount as a list of fixed buckets, not arbitrary
+// min/max ranges. Map the user's numeric range to the overlapping buckets.
+const PROSPEO_HEADCOUNT_BUCKETS: ReadonlyArray<{ label: string; low: number; high: number }> = [
+  { label: '1-10', low: 1, high: 10 },
+  { label: '11-20', low: 11, high: 20 },
+  { label: '21-50', low: 21, high: 50 },
+  { label: '51-100', low: 51, high: 100 },
+  { label: '101-200', low: 101, high: 200 },
+  { label: '201-500', low: 201, high: 500 },
+  { label: '501-1000', low: 501, high: 1000 },
+  { label: '1001-2000', low: 1001, high: 2000 },
+  { label: '2001-5000', low: 2001, high: 5000 },
+  { label: '5001-10000', low: 5001, high: 10000 },
+  { label: '10000+', low: 10001, high: Number.POSITIVE_INFINITY },
+]
+
+export function prospeoHeadcountBuckets(min: number | undefined, max: number | undefined): string[] {
+  const lo = typeof min === 'number' ? min : 0
+  const hi = typeof max === 'number' ? max : Number.POSITIVE_INFINITY
+  return PROSPEO_HEADCOUNT_BUCKETS.filter((b) => b.low <= hi && b.high >= lo).map((b) => b.label)
+}
+
 function toLinkupFundingStage(stage: string): string | undefined {
   const map: Record<string, string> = {
     seed: 'Seed',
@@ -883,13 +905,13 @@ const searchCompaniesProviders: ProviderEntry[] = [
             company_industry: { include: input.industries },
           }),
           ...(isNonEmptyArray(input.countries) && {
-            company_country: { include: (input.countries as string[]).map(isoCountryToName) },
+            company_location_search: { include: (input.countries as string[]).map(isoCountryToName) },
           }),
           ...((input.min_employees !== undefined || input.max_employees !== undefined) && {
-            company_headcount_custom: {
-              min: input.min_employees,
-              max: input.max_employees,
-            },
+            company_headcount_range: prospeoHeadcountBuckets(
+              input.min_employees as number | undefined,
+              input.max_employees as number | undefined,
+            ),
           }),
         },
       },
@@ -985,6 +1007,12 @@ const findPeopleProviders: ProviderEntry[] = [
     endpoint: '/leadsfactory/contact-finder/searches',
     method: 'POST',
     priority: 1,
+    // LF is a company-scoped contact finder — upstream 500s with
+    // "At least one of company_linkedin_urls or company_domains must be provided"
+    // when neither is supplied. Skip for pure prospecting (titles/seniorities/keywords
+    // only); apollo at priority 2 handles that path.
+    isApplicable: (input) =>
+      isNonEmptyArray(input.company_domains) || isNonEmptyArray(input.company_linkedin_urls),
     mapParams: (input) => {
       const rawTitles = (input.job_titles as string[] | undefined) ?? []
       // Step 1: deduplicate near-identical "of" variants (e.g. "VP Sales" ≡ "VP of Sales")
@@ -1075,6 +1103,10 @@ const findPeopleProviders: ProviderEntry[] = [
     endpoint: '/apollo/people/search',
     method: 'POST',
     priority: 2,
+    // Apollo caps per_page at 100 and rejects larger values with a 400. The
+    // find_people schema permits limit up to 500 (a waterfall-wide ceiling),
+    // so clamp here to keep Apollo from breaking the request when the caller
+    // pins use_providers=['apollo'] with a large limit.
     mapParams: (input) => ({
       body: {
         person_titles: input.job_titles,
@@ -1082,7 +1114,7 @@ const findPeopleProviders: ProviderEntry[] = [
         person_seniorities: input.seniorities,
         person_locations: input.locations,
         q_keywords: (input.keywords as string[] | undefined)?.join(' ') || undefined,
-        per_page: (input.limit as number) ?? 25,
+        per_page: Math.min((input.limit as number) ?? 25, 100),
       },
     }),
     hasResult: (data) => {
@@ -1127,12 +1159,27 @@ const findPeopleProviders: ProviderEntry[] = [
     endpoint: '/pdl/person/search',
     method: 'POST',
     priority: 3,
+    // Refuse fully-unbounded queries: PDL accepts an empty `must` and would return its
+    // entire index — turning the waterfall into a "random 25 humans" generator.
+    isApplicable: (input) =>
+      isNonEmptyArray(input.company_domains) ||
+      isNonEmptyArray(input.company_linkedin_urls) ||
+      isNonEmptyArray(input.job_titles) ||
+      isNonEmptyArray(input.seniorities),
     mapParams: (input) => {
       const must: unknown[] = []
       if (isNonEmptyArray(input.job_titles))
         must.push({ terms: { job_title: input.job_titles } })
       if (isNonEmptyArray(input.company_domains))
         must.push({ terms: { job_company_website: input.company_domains } })
+      if (isNonEmptyArray(input.company_linkedin_urls)) {
+        // PDL indexes LinkedIn URLs in canonical short form (`linkedin.com/company/x`)
+        // and `terms` is exact-match — full URLs from callers silently return 0 hits.
+        const normalized = (input.company_linkedin_urls as string[]).map((u) =>
+          u.toLowerCase().replace(/^https?:\/\//, '').replace(/^www\./, '').replace(/\/+$/, ''),
+        )
+        must.push({ terms: { job_company_linkedin_url: normalized } })
+      }
       if (isNonEmptyArray(input.seniorities))
         must.push({ terms: { job_title_levels: input.seniorities } })
       if (isNonEmptyArray(input.locations))
@@ -1154,10 +1201,16 @@ const findPeopleProviders: ProviderEntry[] = [
     endpoint: '/companyenrich/people/search',
     method: 'POST',
     priority: 4,
+    // Upstream `filters.companies` accepts domains only — no LinkedIn-URL field exists.
+    // Skip when the caller supplied only LinkedIn URLs so we don't fall back to a
+    // titles-only global search that masquerades as company-scoped.
+    isApplicable: (input) =>
+      isNonEmptyArray(input.company_domains) || !isNonEmptyArray(input.company_linkedin_urls),
     mapParams: (input) => ({
       body: {
         filters: {
           jobTitles: input.job_titles,
+          companies: isNonEmptyArray(input.company_domains) ? input.company_domains : undefined,
           countries: input.locations,
         },
         pageSize: (input.limit as number) ?? 25,
@@ -1236,7 +1289,7 @@ const findPeopleProviders: ProviderEntry[] = [
       body: {
         filters: {
           ...(isNonEmptyArray(input.job_titles) && {
-            job_title: { include: input.job_titles },
+            person_job_title: { include: input.job_titles },
           }),
           ...(isNonEmptyArray(input.seniorities) && {
             person_seniority: { include: input.seniorities },
@@ -1245,7 +1298,7 @@ const findPeopleProviders: ProviderEntry[] = [
             company: { websites: { include: input.company_domains } },
           }),
           ...(isNonEmptyArray(input.locations) && {
-            person_location: { include: input.locations },
+            person_location_search: { include: input.locations },
           }),
         },
       },
@@ -1293,6 +1346,12 @@ const findPeopleProviders: ProviderEntry[] = [
     endpoint: '/fullenrich/people/search',
     method: 'POST',
     priority: 9,
+    // Requires company_domains: the upstream rejects LinkedIn-URL variants as
+    // `error.filters.empty` (despite the schema declaring `current_company_linkedin_urls`,
+    // the live API doesn't honor it). Without any company filter, FullEnrich silently
+    // degrades to a 50k-result titles-only search whose first 25 short-circuit the
+    // waterfall via hasResult.
+    isApplicable: (input) => isNonEmptyArray(input.company_domains),
     mapParams: (input) => ({
       body: {
         current_company_domains: isNonEmptyArray(input.company_domains)