@coldiq/mcp 0.1.0

package/tests/gtm-scenarios.md

@@ -0,0 +1,32 @@
+# GTM Scenario Matrix
+
+Manual regression sheet — 15 realistic buyer/GTM prompts mapped to the expected MCP tool and key parameters.
+
+**How to use**: For each scenario, verify that the tool description + schema alone would lead an agent to pick the right tool with the right params. Update affected rows whenever a tool's description or routing changes.
+
+| # | Prompt | Tool | Key params | Notes |
+|---|---|---|---|---|
+| 1 | "Find Series-B SaaS companies in France with 50–200 employees" | `search_companies` | `keywords: ['SaaS']`, `countries: ['FR']`, `funding_stages: ['series_b']`, `min_employees: 50`, `max_employees: 200` | Firmographic + funding combo |
+| 2 | "Get the CEO and CRO of ColdIQ and Folk" | `find_people` | `company_domains: ['coldiq.com','folk.app']`, `job_titles: ['CEO','CRO']` | Multi-company, multi-title |
+| 3 | "What's Michel Lieben's email at ColdIQ?" | `find_email` | `first_name: 'Michel'`, `last_name: 'Lieben'`, `domain: 'coldiq.com'` | Name+domain → email (find, not enrich) |
+| 4 | "Is michel@coldiq.com a real, deliverable address?" | `verify_email` | `email: 'michel@coldiq.com'` | Deliverability check |
+| 5 | "Enrich this LinkedIn profile: linkedin.com/in/michel-lieben" | `enrich_person` | `linkedin_url: 'https://www.linkedin.com/in/michel-lieben'` | URL-based enrichment |
+| 6 | "What companies recently raised Series A in Europe?" | `find_signals` | `signal_type: 'funding'`, `countries: ['GB','FR','DE','NL']` | Funding signal, country-targeted |
+| 7 | "Companies hiring SDRs in NYC right now" | `search_jobs` | `title_keywords: ['SDR']`, `locations: ['New York, United States']` | Live job postings (not `find_signals`) |
+| 8 | "Show companies showing buying intent for Salesforce alternatives" | `find_signals` | `signal_type: 'intent'`, `companies: ['Salesforce']` or `domains: ['salesforce.com']` | Intent requires companies or domains |
+| 9 | "What's the Google SEO ranking for 'cold email tool'?" | `search_seo` | `category: 'serp'`, `keyword: 'cold email tool'`, `engine: 'google'` | SERP category |
+| 10 | "What tech stack does stripe.com use?" | `search_seo` | `category: 'domain'`, `target: 'stripe.com'`, `action: 'technologies'` | Domain-analytics category |
+| 11 | "Find B2B SaaS influencers on LinkedIn" | `find_influencers` | `platform: 'linkedin'`, `ai_search: 'B2B SaaS founders'` | Discovery mode (no handle) |
+| 12 | "What does the ColdIQ homepage say?" | `fetch_page_content` | `urls: ['https://coldiq.com']` | Page text extraction (find URL via `search_web` first if unknown) |
+| 13 | "Coffee shops near Times Square" | `search_places` | `query: 'coffee shop'`, `city: 'New York'`, `country: 'US'` | Local place search |
+| 14 | "Reddit threads about cold email tools" | `search_reddit` | `query: 'cold email tool'`, `sort: 'top'` | One async provider |
+| 15 | "LinkedIn ads run by ColdIQ" | `search_ads` | `platform: 'linkedin'`, `search_urls: ['...']` | Requires pre-built LinkedIn Ad Library URL |
+
+## Boundary pairs (easily confused tools)
+
+| A | B | Distinction |
+|---|---|---|
+| `search_jobs` | `find_signals(hiring)` | `search_jobs` = individual live postings; `find_signals(hiring)` = aggregated hiring-surge signal at company level |
+| `find_email` | `enrich_person` | `find_email` = name+domain → email; `enrich_person` = any identifier → full profile |
+| `fetch_page_content` | `search_web` | `search_web` = URL discovery; `fetch_page_content` = fetch full text of known URLs |
+| `find_signals(news)` | `find_signals(intent)` | `news`/`startup_post` are feed-style (country only, no company filter); `intent` is company-targeted |

package/tests/live/smoke-report.ts

@@ -0,0 +1,255 @@
+/**
+ * Live smoke + waterfall report.
+ *
+ * Runs every MCP tool with minimal-credit payloads, captures the executor's
+ * waterfall logs, and prints a structured report at the end.
+ *
+ * Usage:
+ *   COLDIQ_API_KEY=<key> npx tsx mcp/tests/live/smoke-report.ts
+ *
+ * Env:
+ *   COLDIQ_API_KEY  required
+ *   COLDIQ_API_URL  optional (default: https://api.coldiq.com)
+ */
+
+process.env.COLDIQ_DEBUG = '1' // captures `skipping <id>` debug lines
+
+import { initClient } from '../../src/client.js'
+import { enrichCompanyHandler } from '../../src/tools/enrich-company.js'
+import { enrichPersonHandler } from '../../src/tools/enrich-person.js'
+import { fetchPageContentHandler } from '../../src/tools/fetch-page-content.js'
+import { findEmailHandler } from '../../src/tools/find-email.js'
+import { findEmailsHandler } from '../../src/tools/find-emails.js'
+import { findInfluencersHandler } from '../../src/tools/find-influencers.js'
+import { findPeopleHandler } from '../../src/tools/find-people.js'
+import { findPhoneHandler } from '../../src/tools/find-phone.js'
+import { findSignalsHandler } from '../../src/tools/find-signals.js'
+import { searchAdsHandler } from '../../src/tools/search-ads.js'
+import { searchCompaniesHandler } from '../../src/tools/search-companies.js'
+import { searchJobsHandler } from '../../src/tools/search-jobs.js'
+import { searchPlacesHandler } from '../../src/tools/search-places.js'
+import { searchRedditHandler } from '../../src/tools/search-reddit.js'
+import { searchSeoHandler } from '../../src/tools/search-seo.js'
+import { searchWebHandler } from '../../src/tools/search-web.js'
+import { verifyEmailHandler } from '../../src/tools/verify-email.js'
+
+type Handler = (input: Record<string, unknown>) => Promise<{ content: { text: string }[]; isError?: boolean }>
+
+interface Case {
+  tool: string
+  variant: string
+  handler: Handler
+  input: Record<string, unknown>
+}
+
+interface CaseResult {
+  tool: string
+  variant: string
+  ok: boolean
+  winner: string | null
+  latencyMs: number | null
+  tried: string[]      // providers that fired (excluding the winner)
+  failed: { id: string; reason: string }[]
+  skipped: string[]    // providers gated out
+  errorMsg?: string
+  totalDurationMs: number
+}
+
+const API_URL = process.env.COLDIQ_API_URL ?? 'https://api.coldiq.com'
+const API_KEY = process.env.COLDIQ_API_KEY
+
+if (!API_KEY) {
+  console.error('COLDIQ_API_KEY is required')
+  process.exit(1)
+}
+
+initClient(API_URL, API_KEY)
+
+// ─── Cases ─────────────────────────────────────────────────────────────────
+
+const cases: Case[] = [
+  // 1 case each (sync, cheap)
+  { tool: 'verify_email',       variant: 'michel@coldiq.com',         handler: verifyEmailHandler,    input: { email: 'michel@coldiq.com' } },
+  { tool: 'find_email',         variant: 'Michel Lieben at coldiq',   handler: findEmailHandler,      input: { first_name: 'Michel', last_name: 'Lieben', domain: 'coldiq.com' } },
+  { tool: 'find_emails',        variant: 'bulk single contact',       handler: findEmailsHandler,     input: { people: [{ id: 'michel-lieben', first_name: 'Michel', last_name: 'Lieben', domain: 'coldiq.com' }] } },
+  { tool: 'find_phone',         variant: 'Brahim LinkedIn',           handler: findPhoneHandler,      input: { linkedin_url: 'https://www.linkedin.com/in/brahim-sliti/' } },
+  { tool: 'enrich_company',     variant: 'coldiq.com',                handler: enrichCompanyHandler,  input: { domain: 'coldiq.com' } },
+  { tool: 'find_people',        variant: 'CEO at ColdIQ',             handler: findPeopleHandler,     input: { company_domains: ['coldiq.com'], job_titles: ['CEO'], limit: 1 } },
+  { tool: 'search_web',         variant: 'ColdIQ outbound',           handler: searchWebHandler,      input: { query: 'ColdIQ outbound sales', limit: 1 } },
+  { tool: 'fetch_page_content', variant: 'coldiq.com',                handler: fetchPageContentHandler, input: { urls: ['https://coldiq.com'] } },
+  { tool: 'find_signals',       variant: 'funding in FR',             handler: findSignalsHandler,    input: { signal_type: 'funding', countries: ['FR'], limit: 1 } },
+  { tool: 'search_seo',         variant: 'serp google: coldiq',       handler: searchSeoHandler,      input: { category: 'serp', keyword: 'coldiq', limit: 1 } },
+  { tool: 'find_influencers',   variant: 'Instagram discovery',       handler: findInfluencersHandler, input: { platform: 'instagram', ai_search: 'B2B SaaS founders', limit: 1 } },
+
+  // tools with branching gates — 2 variants
+  { tool: 'enrich_person',      variant: 'by email',                  handler: enrichPersonHandler,   input: { email: 'michel@coldiq.com' } },
+  { tool: 'enrich_person',      variant: 'by linkedin_url',           handler: enrichPersonHandler,   input: { linkedin_url: 'https://www.linkedin.com/in/michel-lieben' } },
+
+  { tool: 'search_companies',   variant: 'keyword + country',         handler: searchCompaniesHandler, input: { keywords: ['SaaS'], countries: ['FR'], limit: 1 } },
+  { tool: 'search_companies',   variant: 'tech-stack filter',         handler: searchCompaniesHandler, input: { technologies: ['Salesforce'], limit: 1 } },
+
+  { tool: 'search_places',      variant: 'US (Openmart route)',       handler: searchPlacesHandler,   input: { query: 'coffee shop', country: 'US', limit: 1 } },
+  { tool: 'search_places',      variant: 'FR (Google Maps route)',    handler: searchPlacesHandler,   input: { query: 'café', country: 'FR', limit: 1 } },
+
+  // async tools — 1 each (slow)
+  { tool: 'search_jobs',        variant: 'SDR in Paris',              handler: searchJobsHandler,     input: { title_keywords: ['SDR'], locations: ['Paris'], limit: 10 } },
+  { tool: 'search_ads',         variant: 'meta: ColdIQ',              handler: searchAdsHandler,      input: { platform: 'meta', query: 'ColdIQ' } },
+  { tool: 'search_reddit',      variant: 'r/sales top posts',         handler: searchRedditHandler,   input: { start_urls: ['https://www.reddit.com/r/sales/'], sort: 'hot', limit: 3 } },
+]
+
+// ─── Log capture ───────────────────────────────────────────────────────────
+
+const reLog   = /^\[coldiq\] (\S+) → (.+)$/
+const reDebug = /^\[coldiq:debug\] (\S+) → (.+)$/
+
+function captureCase(): { stop: () => string[]; lines: string[] } {
+  const lines: string[] = []
+  const orig = console.error
+  console.error = (...args: unknown[]) => {
+    const line = args.map((a) => (typeof a === 'string' ? a : JSON.stringify(a))).join(' ')
+    lines.push(line)
+  }
+  return {
+    lines,
+    stop: () => { console.error = orig; return lines },
+  }
+}
+
+function parseLogs(lines: string[]): Pick<CaseResult, 'winner' | 'latencyMs' | 'tried' | 'failed' | 'skipped'> {
+  let winner: string | null = null
+  let latencyMs: number | null = null
+  const tried: string[] = []
+  const failed: { id: string; reason: string }[] = []
+  const skipped: string[] = []
+
+  for (const raw of lines) {
+    const dm = raw.match(reDebug)
+    if (dm) {
+      const m = dm[2].match(/^skipping (\S+) /)
+      if (m) skipped.push(m[1])
+      continue
+    }
+    const lm = raw.match(reLog)
+    if (!lm) continue
+    const rest = lm[2]
+    const tMatch = rest.match(/^trying (\S+)$/)
+    const wMatch = rest.match(/^(\S+) ✓ \((\d+)ms\)$/)
+    const fMatch = rest.match(/^(\S+) ✗ (.+)$/)
+    if (tMatch) { tried.push(tMatch[1]); continue }
+    if (wMatch) { winner = wMatch[1]; latencyMs = parseInt(wMatch[2], 10); continue }
+    if (fMatch) { failed.push({ id: fMatch[1], reason: fMatch[2] }); continue }
+  }
+  // Remove the winner from tried list (it'll be in there from the "trying" log)
+  const triedExcludingWinner = tried.filter((t) => t !== winner)
+  return { winner, latencyMs, tried: triedExcludingWinner, failed, skipped }
+}
+
+// ─── Run ───────────────────────────────────────────────────────────────────
+
+async function runCase(c: Case): Promise<CaseResult> {
+  const cap = captureCase()
+  const start = Date.now()
+  let ok = false
+  let errorMsg: string | undefined
+  try {
+    const r = await c.handler(c.input)
+    ok = !r.isError
+    if (!ok) {
+      try {
+        const parsed = JSON.parse(r.content[0].text)
+        errorMsg = typeof parsed.error === 'string' ? parsed.error : JSON.stringify(parsed).slice(0, 200)
+      } catch {
+        errorMsg = r.content[0].text.slice(0, 200)
+      }
+    }
+  } catch (e) {
+    ok = false
+    errorMsg = e instanceof Error ? e.message : String(e)
+  }
+  const totalDurationMs = Date.now() - start
+  cap.stop()
+  const parsed = parseLogs(cap.lines)
+  return { tool: c.tool, variant: c.variant, ok, totalDurationMs, errorMsg, ...parsed }
+}
+
+function fmtList(xs: string[]): string {
+  return xs.length === 0 ? '—' : xs.join(', ')
+}
+
+function printCase(r: CaseResult, idx: number, total: number): void {
+  const status = r.ok ? '✅' : '❌'
+  const winner = r.winner ?? '—'
+  const lat = r.latencyMs !== null ? `${r.latencyMs}ms` : `${r.totalDurationMs}ms total`
+  process.stdout.write(`[${idx + 1}/${total}] ${status} ${r.tool} (${r.variant}) — ${winner} (${lat})\n`)
+  if (!r.ok && r.errorMsg) {
+    process.stdout.write(`     error: ${r.errorMsg.slice(0, 200)}\n`)
+  }
+}
+
+function printReport(results: CaseResult[]): void {
+  const groups = new Map<string, CaseResult[]>()
+  for (const r of results) {
+    const arr = groups.get(r.tool) ?? []
+    arr.push(r)
+    groups.set(r.tool, arr)
+  }
+
+  // Final markdown report
+  console.log('\n')
+  console.log('# MCP Live Smoke Report')
+  console.log('')
+  console.log(`Run at: ${new Date().toISOString()}`)
+  console.log(`API: ${API_URL}`)
+  console.log('')
+
+  console.log('## Summary')
+  console.log('')
+  console.log('| Tool | Cases | Status | Winners | Total Latency |')
+  console.log('|---|---|---|---|---|')
+  for (const [tool, rs] of groups) {
+    const allOk = rs.every((r) => r.ok)
+    const status = allOk ? '✅' : rs.every((r) => !r.ok) ? '❌' : '⚠️'
+    const winners = [...new Set(rs.map((r) => r.winner ?? '—'))].join(' / ')
+    const totalMs = rs.reduce((s, r) => s + r.totalDurationMs, 0)
+    console.log(`| ${tool} | ${rs.length} | ${status} | ${winners} | ${totalMs}ms |`)
+  }
+  const okCount = results.filter((r) => r.ok).length
+  console.log('')
+  console.log(`**${okCount}/${results.length} cases passed**`)
+  console.log('')
+
+  console.log('## Per-tool detail')
+  console.log('')
+  for (const [tool, rs] of groups) {
+    console.log(`### ${tool}`)
+    console.log('')
+    console.log('| Variant | Status | Winner | Latency | Skipped (gated) | Tried before winner | Failed |')
+    console.log('|---|---|---|---|---|---|---|')
+    for (const r of rs) {
+      const status = r.ok ? '✅' : '❌'
+      const winner = r.winner ?? '—'
+      const lat = r.latencyMs !== null ? `${r.latencyMs}ms` : `(${r.totalDurationMs}ms total)`
+      const skipped = fmtList(r.skipped)
+      const triedBefore = fmtList(r.tried)
+      const failed = r.failed.length === 0 ? '—' : r.failed.map((f) => `${f.id}: ${f.reason.slice(0, 40)}`).join('; ')
+      console.log(`| ${r.variant} | ${status} | ${winner} | ${lat} | ${skipped} | ${triedBefore} | ${failed} |`)
+    }
+    console.log('')
+  }
+}
+
+async function main(): Promise<void> {
+  process.stdout.write(`Running ${cases.length} live cases against ${API_URL}\n\n`)
+  const results: CaseResult[] = []
+  for (let i = 0; i < cases.length; i++) {
+    const r = await runCase(cases[i])
+    results.push(r)
+    printCase(r, i, cases.length)
+  }
+  printReport(results)
+}
+
+main().catch((e) => {
+  console.error('FATAL:', e)
+  process.exit(1)
+})

package/tests/live/smoke.test.ts

@@ -0,0 +1,134 @@
+/**
+ * Live smoke tests — require real API access.
+ *
+ * Run with:
+ *   LIVE_TESTS=1 COLDIQ_API_KEY=<key> npm test
+ * or with a custom base URL:
+ *   LIVE_TESTS=1 COLDIQ_API_URL=https://api.coldiq.com COLDIQ_API_KEY=<key> npm test
+ *
+ * Expected credit cost per full run: ~17–20 credits (limit:1 everywhere).
+ * Assertions are lenient — provider availability varies day-to-day.
+ */
+
+import { describe, it, expect, beforeAll } from 'vitest'
+import { initClient } from '../../src/client.js'
+import { searchCompaniesHandler } from '../../src/tools/search-companies.js'
+import { findPeopleHandler } from '../../src/tools/find-people.js'
+import { findEmailHandler } from '../../src/tools/find-email.js'
+import { findEmailsHandler } from '../../src/tools/find-emails.js'
+import { verifyEmailHandler } from '../../src/tools/verify-email.js'
+import { findPhoneHandler } from '../../src/tools/find-phone.js'
+import { enrichCompanyHandler } from '../../src/tools/enrich-company.js'
+import { enrichPersonHandler } from '../../src/tools/enrich-person.js'
+import { searchWebHandler } from '../../src/tools/search-web.js'
+import { searchJobsHandler } from '../../src/tools/search-jobs.js'
+import { searchAdsHandler } from '../../src/tools/search-ads.js'
+import { searchPlacesHandler } from '../../src/tools/search-places.js'
+import { findInfluencersHandler } from '../../src/tools/find-influencers.js'
+import { searchRedditHandler } from '../../src/tools/search-reddit.js'
+import { searchSeoHandler } from '../../src/tools/search-seo.js'
+import { findSignalsHandler } from '../../src/tools/find-signals.js'
+import { fetchPageContentHandler } from '../../src/tools/fetch-page-content.js'
+
+const RUN_LIVE = process.env.LIVE_TESTS === '1'
+
+function assertSuccess(result: { content: { text: string }[]; isError?: boolean }, label: string) {
+  expect(result.isError, `${label}: isError`).toBeFalsy()
+  const parsed = JSON.parse(result.content[0].text)
+  expect(parsed._meta?.provider, `${label}: _meta.provider`).toBeTruthy()
+  return parsed
+}
+
+describe.runIf(RUN_LIVE)('live smoke', () => {
+  beforeAll(() => {
+    initClient(process.env.COLDIQ_API_URL, process.env.COLDIQ_API_KEY)
+  })
+
+  it('search_companies — SaaS in FR', async () => {
+    const result = await searchCompaniesHandler({ keywords: ['SaaS'], countries: ['FR'], limit: 1 })
+    assertSuccess(result, 'search_companies')
+  }, 60_000)
+
+  it('find_people — CEO at ColdIQ', async () => {
+    const result = await findPeopleHandler({ company_domains: ['coldiq.com'], job_titles: ['CEO'], limit: 1 })
+    const parsed = assertSuccess(result, 'find_people')
+    expect(parsed.data).toBeTruthy()
+  }, 60_000)
+
+  it('find_email — Michel Lieben at coldiq.com', async () => {
+    const result = await findEmailHandler({ first_name: 'Michel', last_name: 'Lieben', domain: 'coldiq.com' })
+    assertSuccess(result, 'find_email')
+  }, 60_000)
+
+  it('find_emails — bulk: Michel Lieben at coldiq.com', async () => {
+    const result = await findEmailsHandler({ people: [{ id: 'michel-lieben', first_name: 'Michel', last_name: 'Lieben', domain: 'coldiq.com' }] })
+    assertSuccess(result, 'find_emails')
+  }, 60_000)
+
+  it('verify_email — michel@coldiq.com', async () => {
+    const result = await verifyEmailHandler({ email: 'michel@coldiq.com' })
+    assertSuccess(result, 'verify_email')
+  }, 60_000)
+
+  it('find_phone — Michel Lieben LinkedIn', async () => {
+    const result = await findPhoneHandler({ linkedin_url: 'https://www.linkedin.com/in/michel-lieben' })
+    // find_phone may return no result if number is private — just check no crash
+    expect(result.content[0].text).toBeTruthy()
+  }, 60_000)
+
+  it('enrich_company — coldiq.com', async () => {
+    const result = await enrichCompanyHandler({ domain: 'coldiq.com' })
+    assertSuccess(result, 'enrich_company')
+  }, 60_000)
+
+  it('enrich_person — michel@coldiq.com', async () => {
+    const result = await enrichPersonHandler({ email: 'michel@coldiq.com' })
+    assertSuccess(result, 'enrich_person')
+  }, 60_000)
+
+  it('search_web — ColdIQ outbound', async () => {
+    const result = await searchWebHandler({ query: 'ColdIQ outbound', limit: 1 })
+    assertSuccess(result, 'search_web')
+  }, 60_000)
+
+  it('search_jobs — SDR in Paris', async () => {
+    const result = await searchJobsHandler({ title_keywords: ['SDR'], locations: ['Paris, France'], limit: 10 })
+    assertSuccess(result, 'search_jobs')
+  }, 120_000)
+
+  it('search_ads — Meta ads for ColdIQ', async () => {
+    const result = await searchAdsHandler({ platform: 'meta', query: 'ColdIQ' })
+    // ads may return empty for small advertisers — just check no crash
+    expect(result.content[0].text).toBeTruthy()
+  }, 120_000)
+
+  it('search_places — coffee shop in Paris', async () => {
+    const result = await searchPlacesHandler({ query: 'coffee shop', country: 'FR', limit: 1 })
+    assertSuccess(result, 'search_places')
+  }, 120_000)
+
+  it('find_influencers — Instagram B2B SaaS', async () => {
+    const result = await findInfluencersHandler({ platform: 'instagram', ai_search: 'B2B SaaS founders', limit: 1 })
+    assertSuccess(result, 'find_influencers')
+  }, 60_000)
+
+  it('search_reddit — outbound sales posts', async () => {
+    const result = await searchRedditHandler({ query: 'outbound sales', limit: 1 })
+    assertSuccess(result, 'search_reddit')
+  }, 120_000)
+
+  it('search_seo — SERP for coldiq', async () => {
+    const result = await searchSeoHandler({ category: 'serp', keyword: 'coldiq', limit: 1 })
+    assertSuccess(result, 'search_seo')
+  }, 60_000)
+
+  it('find_signals — funding in FR', async () => {
+    const result = await findSignalsHandler({ signal_type: 'funding', countries: ['FR'], limit: 1 })
+    assertSuccess(result, 'find_signals')
+  }, 60_000)
+
+  it('fetch_page_content — coldiq.com homepage', async () => {
+    const result = await fetchPageContentHandler({ urls: ['https://coldiq.com'] })
+    assertSuccess(result, 'fetch_page_content')
+  }, 60_000)
+})