@coldiq/mcp 0.1.0

package/dist/tools/search-seo.d.ts

@@ -0,0 +1,37 @@
+import { z } from 'zod';
+export declare const searchSeoName = "search_seo";
+export declare const searchSeoDescription: string;
+export declare const searchSeoSchema: {
+    category: z.ZodEnum<["keywords", "serp", "backlinks", "domain", "labs", "page"]>;
+    target: z.ZodOptional<z.ZodString>;
+    keyword: z.ZodOptional<z.ZodString>;
+    keywords: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    location: z.ZodOptional<z.ZodString>;
+    language: z.ZodOptional<z.ZodString>;
+    limit: z.ZodDefault<z.ZodNumber>;
+    date_from: z.ZodOptional<z.ZodString>;
+    date_to: z.ZodOptional<z.ZodString>;
+    time_range: z.ZodOptional<z.ZodString>;
+    engine: z.ZodDefault<z.ZodEnum<["google", "bing", "youtube"]>>;
+    device: z.ZodOptional<z.ZodEnum<["desktop", "mobile"]>>;
+    action: z.ZodOptional<z.ZodEnum<["technologies", "whois"]>>;
+    lab_action: z.ZodOptional<z.ZodEnum<["ranked-keywords", "competitors", "keyword-ideas", "rank-overview"]>>;
+    url: z.ZodOptional<z.ZodString>;
+    page_action: z.ZodDefault<z.ZodEnum<["lighthouse", "content"]>>;
+    enable_javascript: z.ZodOptional<z.ZodBoolean>;
+    full_data: z.ZodOptional<z.ZodBoolean>;
+};
+export declare function searchSeoHandler(input: Record<string, unknown>): Promise<{
+    content: {
+        type: "text";
+        text: string;
+    }[];
+    isError: boolean;
+} | {
+    content: {
+        type: "text";
+        text: string;
+    }[];
+    isError?: undefined;
+}>;
+//# sourceMappingURL=search-seo.d.ts.map

package/dist/tools/search-seo.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"search-seo.d.ts","sourceRoot":"","sources":["../../src/tools/search-seo.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAA;AAGvB,eAAO,MAAM,aAAa,eAAe,CAAA;AAEzC,eAAO,MAAM,oBAAoB,QAQiD,CAAA;AAElF,eAAO,MAAM,eAAe;;;;;;;;;;;;;;;;;;;CAmC3B,CAAA;AAED,wBAAsB,gBAAgB,CAAC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;;;;;;;;;;;;GAMpE"}

package/dist/tools/search-seo.js

@@ -0,0 +1,49 @@
+import { z } from 'zod';
+import { executeWithFallback, isExecutionError } from '../executor.js';
+export const searchSeoName = 'search_seo';
+export const searchSeoDescription = 'Search SEO data — 6 categories. Pick category + required fields:\n' +
+    '• keywords: pass keywords[] — search volume or trends\n' +
+    '• serp: pass keyword (single string) — Google/Bing/YouTube organic results\n' +
+    '• backlinks: pass target (domain or URL) — summary, links, referring domains\n' +
+    '• domain: pass target + action ("technologies" | "whois")\n' +
+    '• labs: pass target for rank-overview/competitors/ranked-keywords; OR pass keywords[] for keyword-ideas\n' +
+    '• page: pass url + page_action ("lighthouse" | "content")\n' +
+    'Optional shared: location, language, limit. All sync. Cost varies by endpoint.';
+export const searchSeoSchema = {
+    category: z.enum(['keywords', 'serp', 'backlinks', 'domain', 'labs', 'page'])
+        .describe('Which SEO category to use. Required.'),
+    target: z.string().optional()
+        .describe('Domain or URL. Required for: backlinks, domain, labs.'),
+    keyword: z.string().optional()
+        .describe('Single keyword. Required for: serp.'),
+    keywords: z.array(z.string()).optional()
+        .describe('Keyword list. Required for: keywords/search-volume, labs/keyword-ideas.'),
+    location: z.string().optional()
+        .describe('Location name e.g. "United States", "London,England,United Kingdom".'),
+    language: z.string().optional()
+        .describe('Language code e.g. "en".'),
+    limit: z.number().int().min(1).max(700).default(10),
+    date_from: z.string().optional().describe('YYYY-MM-DD. keywords/trends.'),
+    date_to: z.string().optional().describe('YYYY-MM-DD. keywords/trends.'),
+    time_range: z.string().optional().describe('keywords/trends: "past_7_days", "past_30_days", etc.'),
+    engine: z.enum(['google', 'bing', 'youtube']).default('google'),
+    device: z.enum(['desktop', 'mobile']).optional(),
+    action: z.enum(['technologies', 'whois']).optional()
+        .describe('domain: "technologies" (tech stack) or "whois". Default: technologies.'),
+    lab_action: z.enum(['ranked-keywords', 'competitors', 'keyword-ideas', 'rank-overview']).optional()
+        .describe('labs action. Default: rank-overview when target set; keyword-ideas when keywords[] set.'),
+    url: z.string().url().optional()
+        .describe('Full URL to analyze. Required for page category.'),
+    page_action: z.enum(['lighthouse', 'content']).default('lighthouse')
+        .describe('page: "lighthouse" (Core Web Vitals audit) or "content" (parse page text).'),
+    enable_javascript: z.boolean().optional(),
+    full_data: z.boolean().optional().describe('Lighthouse only: include full audit data.'),
+};
+export async function searchSeoHandler(input) {
+    const result = await executeWithFallback('search_seo', input);
+    if (isExecutionError(result)) {
+        return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }], isError: true };
+    }
+    return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
+}
+//# sourceMappingURL=search-seo.js.map

package/dist/tools/search-seo.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"search-seo.js","sourceRoot":"","sources":["../../src/tools/search-seo.ts"],"names":[],"mappings":"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"}

package/dist/tools/search-web.d.ts

@@ -0,0 +1,23 @@
+import { z } from 'zod';
+export declare const searchWebName = "search_web";
+export declare const searchWebDescription: string;
+export declare const searchWebSchema: {
+    query: z.ZodString;
+    num_results: z.ZodDefault<z.ZodNumber>;
+    country: z.ZodOptional<z.ZodString>;
+    search_type: z.ZodDefault<z.ZodEnum<["general", "neural"]>>;
+};
+export declare function searchWebHandler(input: Record<string, unknown>): Promise<{
+    content: {
+        type: "text";
+        text: string;
+    }[];
+    isError: boolean;
+} | {
+    content: {
+        type: "text";
+        text: string;
+    }[];
+    isError?: undefined;
+}>;
+//# sourceMappingURL=search-web.d.ts.map

package/dist/tools/search-web.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"search-web.d.ts","sourceRoot":"","sources":["../../src/tools/search-web.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAA;AAGvB,eAAO,MAAM,aAAa,eAAe,CAAA;AAEzC,eAAO,MAAM,oBAAoB,QAGoE,CAAA;AAErG,eAAO,MAAM,eAAe;;;;;CAK3B,CAAA;AAED,wBAAsB,gBAAgB,CAAC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;;;;;;;;;;;;GAMpE"}

package/dist/tools/search-web.js

@@ -0,0 +1,20 @@
+import { z } from 'zod';
+import { executeWithFallback, isExecutionError } from '../executor.js';
+export const searchWebName = 'search_web';
+export const searchWebDescription = 'Search the web for market research, company news, or general lookups. Supports Google search (default) and neural/semantic search via Exa. ' +
+    'NEVER use this to find, verify, or look up people, contacts, LinkedIn profiles, or executives — even as a fallback when find_people returns uncertain results. ' +
+    'find_people is the only tool for people lookups; do not supplement or replace it with web search.';
+export const searchWebSchema = {
+    query: z.string().describe('Search query'),
+    num_results: z.number().min(1).max(100).default(10).describe('Number of results (default: 10, max: 100)'),
+    country: z.string().optional().describe('Country code for geo-targeting (e.g. "us", "fr")'),
+    search_type: z.enum(['general', 'neural']).default('general').describe('"general" for Google search (default), "neural" for semantic search via Exa'),
+};
+export async function searchWebHandler(input) {
+    const result = await executeWithFallback('search_web', input);
+    if (isExecutionError(result)) {
+        return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }], isError: true };
+    }
+    return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
+}
+//# sourceMappingURL=search-web.js.map

package/dist/tools/search-web.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"search-web.js","sourceRoot":"","sources":["../../src/tools/search-web.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAA;AACvB,OAAO,EAAE,mBAAmB,EAAE,gBAAgB,EAAE,MAAM,gBAAgB,CAAA;AAEtE,MAAM,CAAC,MAAM,aAAa,GAAG,YAAY,CAAA;AAEzC,MAAM,CAAC,MAAM,oBAAoB,GAC/B,6IAA6I;IAC7I,iKAAiK;IACjK,mGAAmG,CAAA;AAErG,MAAM,CAAC,MAAM,eAAe,GAAG;IAC7B,KAAK,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,cAAc,CAAC;IAC1C,WAAW,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC,OAAO,CAAC,EAAE,CAAC,CAAC,QAAQ,CAAC,2CAA2C,CAAC;IACzG,OAAO,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,kDAAkD,CAAC;IAC3F,WAAW,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC,SAAS,EAAE,QAAQ,CAAC,CAAC,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC,QAAQ,CAAC,6EAA6E,CAAC;CACtJ,CAAA;AAED,MAAM,CAAC,KAAK,UAAU,gBAAgB,CAAC,KAA8B;IACnE,MAAM,MAAM,GAAG,MAAM,mBAAmB,CAAC,YAAY,EAAE,KAAK,CAAC,CAAA;IAC7D,IAAI,gBAAgB,CAAC,MAAM,CAAC,EAAE,CAAC;QAC7B,OAAO,EAAE,OAAO,EAAE,CAAC,EAAE,IAAI,EAAE,MAAe,EAAE,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,MAAM,EAAE,IAAI,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,OAAO,EAAE,IAAI,EAAE,CAAA;IACvG,CAAC;IACD,OAAO,EAAE,OAAO,EAAE,CAAC,EAAE,IAAI,EAAE,MAAe,EAAE,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,MAAM,EAAE,IAAI,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,CAAA;AACxF,CAAC"}

package/dist/tools/verify-email.d.ts

@@ -0,0 +1,20 @@
+import { z } from 'zod';
+export declare const verifyEmailName = "verify_email";
+export declare const verifyEmailDescription = "Check whether an email address is valid and deliverable. Returns verification status (valid, invalid, catch-all, unknown). Use before cold outreach to protect sender reputation.";
+export declare const verifyEmailSchema: {
+    email: z.ZodString;
+};
+export declare function verifyEmailHandler(input: Record<string, unknown>): Promise<{
+    content: {
+        type: "text";
+        text: string;
+    }[];
+    isError: boolean;
+} | {
+    content: {
+        type: "text";
+        text: string;
+    }[];
+    isError?: undefined;
+}>;
+//# sourceMappingURL=verify-email.d.ts.map

package/dist/tools/verify-email.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"verify-email.d.ts","sourceRoot":"","sources":["../../src/tools/verify-email.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAA;AAGvB,eAAO,MAAM,eAAe,iBAAiB,CAAA;AAE7C,eAAO,MAAM,sBAAsB,sLACkJ,CAAA;AAErL,eAAO,MAAM,iBAAiB;;CAE7B,CAAA;AAED,wBAAsB,kBAAkB,CAAC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;;;;;;;;;;;;GAMtE"}

package/dist/tools/verify-email.js

@@ -0,0 +1,15 @@
+import { z } from 'zod';
+import { executeWithFallback, isExecutionError } from '../executor.js';
+export const verifyEmailName = 'verify_email';
+export const verifyEmailDescription = 'Check whether an email address is valid and deliverable. Returns verification status (valid, invalid, catch-all, unknown). Use before cold outreach to protect sender reputation.';
+export const verifyEmailSchema = {
+    email: z.string().email().describe('Email address to verify'),
+};
+export async function verifyEmailHandler(input) {
+    const result = await executeWithFallback('verify_email', input);
+    if (isExecutionError(result)) {
+        return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }], isError: true };
+    }
+    return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
+}
+//# sourceMappingURL=verify-email.js.map

package/dist/tools/verify-email.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"verify-email.js","sourceRoot":"","sources":["../../src/tools/verify-email.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAA;AACvB,OAAO,EAAE,mBAAmB,EAAE,gBAAgB,EAAE,MAAM,gBAAgB,CAAA;AAEtE,MAAM,CAAC,MAAM,eAAe,GAAG,cAAc,CAAA;AAE7C,MAAM,CAAC,MAAM,sBAAsB,GACjC,mLAAmL,CAAA;AAErL,MAAM,CAAC,MAAM,iBAAiB,GAAG;IAC/B,KAAK,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,KAAK,EAAE,CAAC,QAAQ,CAAC,yBAAyB,CAAC;CAC9D,CAAA;AAED,MAAM,CAAC,KAAK,UAAU,kBAAkB,CAAC,KAA8B;IACrE,MAAM,MAAM,GAAG,MAAM,mBAAmB,CAAC,cAAc,EAAE,KAAK,CAAC,CAAA;IAC/D,IAAI,gBAAgB,CAAC,MAAM,CAAC,EAAE,CAAC;QAC7B,OAAO,EAAE,OAAO,EAAE,CAAC,EAAE,IAAI,EAAE,MAAe,EAAE,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,MAAM,EAAE,IAAI,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,OAAO,EAAE,IAAI,EAAE,CAAA;IACvG,CAAC;IACD,OAAO,EAAE,OAAO,EAAE,CAAC,EAAE,IAAI,EAAE,MAAe,EAAE,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,MAAM,EAAE,IAAI,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,CAAA;AACxF,CAAC"}

package/package.json

@@ -0,0 +1,28 @@
+{
+  "name": "@coldiq/mcp",
+  "version": "0.1.0",
+  "type": "module",
+  "main": "dist/index.js",
+  "bin": {
+    "coldiq-mcp": "dist/index.js"
+  },
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsx src/index.ts",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:gtm": "LIVE_TESTS=1 vitest run tests/gtm",
+    "test:gtm:one": "LIVE_TESTS=1 vitest run"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.12.1",
+    "zod": "^3.24.2"
+  },
+  "devDependencies": {
+    "@anthropic-ai/sdk": "^0.52.0",
+    "tsx": "^4.19.3",
+    "typescript": "^5.8.2",
+    "vitest": "^3.1.3",
+    "zod-to-json-schema": "^3.25.0"
+  }
+}

package/src/client.ts

@@ -0,0 +1,60 @@
+export type ApiResponse = {
+  ok: boolean
+  status: number
+  data: unknown
+}
+
+let _apiUrl: string
+let _apiKey: string
+
+export function initClient(apiUrl?: string, apiKey?: string): void {
+  _apiUrl = apiUrl ?? process.env.COLDIQ_API_URL ?? 'https://api.coldiq.com'
+  _apiKey = apiKey ?? process.env.COLDIQ_API_KEY ?? ''
+  if (!_apiKey) {
+    throw new Error('COLDIQ_API_KEY is required — set it in .mcp.json env or as an environment variable')
+  }
+  // Strip trailing slash
+  _apiUrl = _apiUrl.replace(/\/+$/, '')
+}
+
+export async function callApi(
+  method: 'GET' | 'POST',
+  path: string,
+  body?: unknown,
+  queryParams?: Record<string, string>,
+): Promise<ApiResponse> {
+  const url = new URL(`${_apiUrl}/v1${path}`)
+  if (queryParams) {
+    for (const [k, v] of Object.entries(queryParams)) {
+      if (v !== undefined && v !== '') url.searchParams.set(k, v)
+    }
+  }
+
+  const headers: Record<string, string> = {
+    Authorization: `Bearer ${_apiKey}`,
+  }
+
+  const init: RequestInit = { method, headers }
+
+  if (method === 'POST' && body !== undefined) {
+    headers['Content-Type'] = 'application/json'
+    init.body = JSON.stringify(body)
+  }
+
+  try {
+    const res = await fetch(url.toString(), init)
+    let data: unknown
+    try {
+      data = await res.json()
+    } catch {
+      data = { error: 'Non-JSON response from API' }
+    }
+    return { ok: res.ok, status: res.status, data }
+  } catch (err) {
+    return {
+      ok: false,
+      status: 0,
+      data: { error: err instanceof Error ? err.message : String(err) },
+    }
+  }
+}

package/src/executor.ts

@@ -0,0 +1,182 @@
+import { callApi } from './client.js'
+import { getProviders, getSearchWebProviders } from './registry.js'
+import type { Capability, ProviderEntry } from './registry.js'
+
+export interface ExecutionResult {
+  data: unknown
+  _meta: {
+    provider: string
+    latencyMs: number
+  }
+}
+
+export interface ExecutionError {
+  error: string
+  providers_tried: Array<{ id: string; status: number; error: string }>
+}
+
+function isExecutionError(result: ExecutionResult | ExecutionError): result is ExecutionError {
+  return 'error' in result && 'providers_tried' in result
+}
+
+export { isExecutionError }
+
+// ---------------------------------------------------------------------------
+// Logging — user-facing vs developer debug
+// ---------------------------------------------------------------------------
+
+/** User-facing logs: which provider was picked, success/failure */
+function log(msg: string): void {
+  console.error(`[coldiq] ${msg}`)
+}
+
+/** Developer debug logs: polling details, internals. Set COLDIQ_DEBUG=1 to enable. */
+function debug(msg: string): void {
+  if (process.env.COLDIQ_DEBUG) {
+    console.error(`[coldiq:debug] ${msg}`)
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Async polling
+// ---------------------------------------------------------------------------
+
+async function executeAsync(
+  provider: ProviderEntry,
+  payload: { body?: unknown; queryParams?: Record<string, string> },
+): Promise<{ ok: boolean; data: unknown }> {
+  const asyncCfg = provider.async!
+
+  // Step 1: create the job
+  debug(`${provider.id} async: creating job...`)
+  const createRes = await callApi(provider.method, provider.endpoint, payload.body, payload.queryParams)
+  if (!createRes.ok) {
+    debug(`${provider.id} async: create failed (${createRes.status})`)
+    return createRes
+  }
+
+  // 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' } }
+  }
+  if (!jobId) return { ok: false, data: { error: 'Empty job ID from async response' } }
+  debug(`${provider.id} async: job created (${jobId}), polling...`)
+
+  // Step 3: poll until complete or timeout
+  const deadline = Date.now() + asyncCfg.timeoutMs
+  let pollCount = 0
+  while (Date.now() < deadline) {
+    await sleep(asyncCfg.pollIntervalMs)
+    pollCount++
+
+    const pollRes = await callApi('GET', asyncCfg.pollEndpoint(jobId))
+    if (!pollRes.ok) continue // transient poll errors — retry
+
+    const status = (pollRes.data as Record<string, unknown>).status ?? 'unknown'
+    const progress = (pollRes.data as Record<string, unknown>).progress_percentage ?? '?'
+    debug(`${provider.id} async: poll #${pollCount} — status=${status}, progress=${progress}%`)
+
+    if (asyncCfg.isComplete(pollRes.data)) {
+      debug(`${provider.id} async: complete`)
+      return pollRes
+    }
+  }
+
+  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` } }
+}
+
+function sleep(ms: number): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, ms))
+}
+
+// ---------------------------------------------------------------------------
+// Execute a single provider
+// ---------------------------------------------------------------------------
+
+async function executeSingle(
+  provider: ProviderEntry,
+  input: Record<string, unknown>,
+): Promise<{ ok: boolean; status: number; data: unknown; latencyMs: number }> {
+  const start = Date.now()
+  const payload = provider.mapParams(input)
+
+  debug(`${provider.id}: payload = ${JSON.stringify(payload)}`)
+
+  let result: { ok: boolean; status: number; data: unknown }
+
+  if (provider.async) {
+    const asyncResult = await executeAsync(provider, payload)
+    result = { ...asyncResult, status: asyncResult.ok ? 200 : 500 }
+  } else {
+    result = await callApi(provider.method, provider.endpoint, payload.body, payload.queryParams)
+  }
+
+  return { ...result, latencyMs: Date.now() - start }
+}
+
+// ---------------------------------------------------------------------------
+// Fallback execution — try providers in order, return first success
+// ---------------------------------------------------------------------------
+
+export async function executeWithFallback(
+  capability: Capability,
+  input: Record<string, unknown>,
+): Promise<ExecutionResult | ExecutionError> {
+  const providers =
+    capability === 'search_web'
+      ? getSearchWebProviders(input.search_type === 'neural')
+      : getProviders(capability)
+
+  const errors: ExecutionError['providers_tried'] = []
+
+  for (const provider of providers) {
+    if (provider.isApplicable && !provider.isApplicable(input)) {
+      debug(`${capability} → skipping ${provider.id} (input not applicable)`)
+      continue
+    }
+    log(`${capability} → trying ${provider.id}`)
+    const result = await executeSingle(provider, input)
+
+    let payload = result.data
+    if (result.ok && provider.postFilter) {
+      payload = provider.postFilter(payload, input)
+    }
+    if (result.ok && provider.hasResult(payload)) {
+      log(`${capability} → ${provider.id} ✓ (${result.latencyMs}ms)`)
+      return { data: payload, _meta: { provider: provider.id, latencyMs: result.latencyMs } }
+    }
+
+    // Record the failure
+    const rawErr = result.data && typeof result.data === 'object' && 'error' in result.data
+      ? (result.data as Record<string, unknown>).error
+      : undefined
+    const errMsg = rawErr !== undefined
+      ? (typeof rawErr === 'string' ? rawErr : JSON.stringify(rawErr))
+      : `Status ${result.status}, no results`
+    log(`${capability} → ${provider.id} ✗ ${errMsg}`)
+    errors.push({ id: provider.id, status: result.status, error: errMsg })
+  }
+
+  return {
+    error: `All ${errors.length} providers failed for ${capability}`,
+    providers_tried: errors,
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Waterfall execution — try providers until one returns a result
+// Used for enrich_email: stop on first provider that finds an email
+// ---------------------------------------------------------------------------
+
+export async function executeWaterfall(
+  capability: Capability,
+  input: Record<string, unknown>,
+): Promise<ExecutionResult | ExecutionError> {
+  // Waterfall is functionally the same as fallback — try each until one succeeds
+  // The distinction is semantic: waterfall means "I expect most to fail, stop on first hit"
+  return executeWithFallback(capability, input)
+}

package/src/index.ts

@@ -0,0 +1,155 @@
+#!/usr/bin/env node
+
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js'
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js'
+import { initClient } from './client.js'
+
+import {
+  searchCompaniesName,
+  searchCompaniesDescription,
+  searchCompaniesSchema,
+  searchCompaniesHandler,
+} from './tools/search-companies.js'
+
+import {
+  findPeopleName,
+  findPeopleDescription,
+  findPeopleSchema,
+  findPeopleHandler,
+} from './tools/find-people.js'
+
+import {
+  findEmailName,
+  findEmailDescription,
+  findEmailSchema,
+  findEmailHandler,
+} from './tools/find-email.js'
+
+import {
+  enrichPersonName,
+  enrichPersonDescription,
+  enrichPersonSchema,
+  enrichPersonHandler,
+} from './tools/enrich-person.js'
+
+import {
+  findEmailsName,
+  findEmailsDescription,
+  findEmailsSchema,
+  findEmailsHandler,
+} from './tools/find-emails.js'
+
+import {
+  verifyEmailName,
+  verifyEmailDescription,
+  verifyEmailSchema,
+  verifyEmailHandler,
+} from './tools/verify-email.js'
+
+import {
+  findPhoneName,
+  findPhoneDescription,
+  findPhoneSchema,
+  findPhoneHandler,
+} from './tools/find-phone.js'
+
+import {
+  enrichCompanyName,
+  enrichCompanyDescription,
+  enrichCompanySchema,
+  enrichCompanyHandler,
+} from './tools/enrich-company.js'
+
+import {
+  searchWebName,
+  searchWebDescription,
+  searchWebSchema,
+  searchWebHandler,
+} from './tools/search-web.js'
+
+import {
+  searchJobsName,
+  searchJobsDescription,
+  searchJobsSchema,
+  searchJobsHandler,
+} from './tools/search-jobs.js'
+
+import {
+  searchAdsName,
+  searchAdsDescription,
+  searchAdsSchema,
+  searchAdsHandler,
+} from './tools/search-ads.js'
+
+import {
+  searchPlacesName,
+  searchPlacesDescription,
+  searchPlacesSchema,
+  searchPlacesHandler,
+} from './tools/search-places.js'
+
+import {
+  findInfluencersName,
+  findInfluencersDescription,
+  findInfluencersSchema,
+  findInfluencersHandler,
+} from './tools/find-influencers.js'
+
+import {
+  searchRedditName,
+  searchRedditDescription,
+  searchRedditSchema,
+  searchRedditHandler,
+} from './tools/search-reddit.js'
+
+import {
+  searchSeoName,
+  searchSeoDescription,
+  searchSeoSchema,
+  searchSeoHandler,
+} from './tools/search-seo.js'
+
+import {
+  findSignalsName,
+  findSignalsDescription,
+  findSignalsSchema,
+  findSignalsHandler,
+} from './tools/find-signals.js'
+
+import {
+  fetchPageContentName,
+  fetchPageContentDescription,
+  fetchPageContentSchema,
+  fetchPageContentHandler,
+} from './tools/fetch-page-content.js'
+
+// Initialize HTTP client (reads env vars)
+initClient()
+
+const server = new McpServer({
+  name: 'coldiq',
+  version: '0.1.0',
+})
+
+// Register all tools
+server.tool(searchCompaniesName, searchCompaniesDescription, searchCompaniesSchema, searchCompaniesHandler)
+server.tool(findPeopleName, findPeopleDescription, findPeopleSchema, findPeopleHandler)
+server.tool(findEmailName, findEmailDescription, findEmailSchema, findEmailHandler)
+server.tool(enrichPersonName, enrichPersonDescription, enrichPersonSchema, enrichPersonHandler)
+server.tool(findEmailsName, findEmailsDescription, findEmailsSchema, findEmailsHandler)
+server.tool(verifyEmailName, verifyEmailDescription, verifyEmailSchema, verifyEmailHandler)
+server.tool(findPhoneName, findPhoneDescription, findPhoneSchema, findPhoneHandler)
+server.tool(enrichCompanyName, enrichCompanyDescription, enrichCompanySchema, enrichCompanyHandler)
+server.tool(searchWebName, searchWebDescription, searchWebSchema, searchWebHandler)
+server.tool(searchJobsName, searchJobsDescription, searchJobsSchema, searchJobsHandler)
+server.tool(searchAdsName, searchAdsDescription, searchAdsSchema, searchAdsHandler)
+server.tool(searchPlacesName, searchPlacesDescription, searchPlacesSchema, searchPlacesHandler)
+server.tool(findInfluencersName, findInfluencersDescription, findInfluencersSchema, findInfluencersHandler)
+server.tool(searchRedditName, searchRedditDescription, searchRedditSchema, searchRedditHandler)
+server.tool(searchSeoName, searchSeoDescription, searchSeoSchema, searchSeoHandler)
+server.tool(findSignalsName, findSignalsDescription, findSignalsSchema, findSignalsHandler)
+server.tool(fetchPageContentName, fetchPageContentDescription, fetchPageContentSchema, fetchPageContentHandler)
+
+// Connect via stdio transport
+const transport = new StdioServerTransport()
+await server.connect(transport)