@coldiq/mcp 0.1.0

package/tests/tools/search-reddit.test.ts

@@ -0,0 +1,125 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest'
+import { initClient } from '../../src/client.js'
+import { searchRedditHandler } from '../../src/tools/search-reddit.js'
+
+describe('search_reddit handler', () => {
+  const originalFetch = globalThis.fetch
+
+  beforeEach(() => {
+    initClient('http://test-api.local', 'test-key')
+  })
+
+  afterEach(() => {
+    globalThis.fetch = originalFetch
+  })
+
+  it('query search — reddit provider creates async job and polls to completion', async () => {
+    globalThis.fetch = vi.fn(async (url: string | URL | Request) => {
+      const u = url.toString()
+      if (u.includes('/reddit/scrape') && !u.includes('/scrape/')) {
+        return new Response(JSON.stringify({ jobId: 'r-1' }), { status: 200 })
+      }
+      if (u.includes('/reddit/scrape/r-1')) {
+        return new Response(JSON.stringify({
+          jobId: 'r-1',
+          status: 'done',
+          items: [{ title: 'Best CRM for startups', subreddit: 'r/sales', score: 342 }],
+        }), { status: 200 })
+      }
+      return new Response(JSON.stringify({ error: 'unexpected' }), { status: 500 })
+    }) as typeof fetch
+
+    const { getProviders } = await import('../../src/registry.js')
+    const providers = getProviders('search_reddit')
+    const reddit = providers.find((p) => p.id === 'reddit')!
+    const orig = { t: reddit.async!.timeoutMs, i: reddit.async!.pollIntervalMs }
+    reddit.async!.timeoutMs = 500
+    reddit.async!.pollIntervalMs = 20
+
+    try {
+      const result = await searchRedditHandler({ start_urls: ['https://www.reddit.com/r/sales/'], query: 'best CRM for startups', limit: 5 })
+
+      expect(result.isError).toBeFalsy()
+      const parsed = JSON.parse(result.content[0].text)
+      expect(parsed._meta.provider).toBe('reddit')
+      expect(parsed.data.items).toHaveLength(1)
+    } finally {
+      reddit.async!.timeoutMs = orig.t
+      reddit.async!.pollIntervalMs = orig.i
+    }
+  })
+
+  it('start_urls scrape — query is omitted from request body', async () => {
+    let capturedBody: Record<string, unknown> | null = null
+
+    globalThis.fetch = vi.fn(async (url: string | URL | Request, opts?: RequestInit) => {
+      const u = url.toString()
+      if (u.includes('/reddit/scrape') && !u.includes('/scrape/')) {
+        capturedBody = JSON.parse((opts?.body as string) ?? '{}')
+        return new Response(JSON.stringify({ jobId: 'r-2' }), { status: 200 })
+      }
+      if (u.includes('/reddit/scrape/r-2')) {
+        return new Response(JSON.stringify({
+          jobId: 'r-2',
+          status: 'done',
+          items: [{ title: 'Reddit post', subreddit: 'r/entrepreneur' }],
+        }), { status: 200 })
+      }
+      return new Response(JSON.stringify({ error: 'unexpected' }), { status: 500 })
+    }) as typeof fetch
+
+    const { getProviders } = await import('../../src/registry.js')
+    const providers = getProviders('search_reddit')
+    const reddit = providers.find((p) => p.id === 'reddit')!
+    const orig = { t: reddit.async!.timeoutMs, i: reddit.async!.pollIntervalMs }
+    reddit.async!.timeoutMs = 500
+    reddit.async!.pollIntervalMs = 20
+
+    try {
+      await searchRedditHandler({
+        start_urls: ['https://www.reddit.com/r/entrepreneur/'],
+        limit: 5,
+      })
+
+      expect(capturedBody).not.toBeNull()
+      // searchQueries is undefined when no query field provided
+      expect(capturedBody!.searchQueries).toBeUndefined()
+      expect(capturedBody!.startUrls).toEqual([{ url: 'https://www.reddit.com/r/entrepreneur/' }])
+    } finally {
+      reddit.async!.timeoutMs = orig.t
+      reddit.async!.pollIntervalMs = orig.i
+    }
+  })
+
+  it('async timeout — returns isError', async () => {
+    globalThis.fetch = vi.fn(async (url: string | URL | Request) => {
+      const u = url.toString()
+      if (u.includes('/reddit/scrape') && !u.includes('/scrape/')) {
+        return new Response(JSON.stringify({ jobId: 'r-3' }), { status: 200 })
+      }
+      // Always running — never completes
+      if (u.includes('/reddit/scrape/r-3')) {
+        return new Response(JSON.stringify({ jobId: 'r-3', status: 'running' }), { status: 200 })
+      }
+      return new Response(JSON.stringify({ error: 'unexpected' }), { status: 500 })
+    }) as typeof fetch
+
+    const { getProviders } = await import('../../src/registry.js')
+    const providers = getProviders('search_reddit')
+    const reddit = providers.find((p) => p.id === 'reddit')!
+    const orig = { t: reddit.async!.timeoutMs, i: reddit.async!.pollIntervalMs }
+    reddit.async!.timeoutMs = 100
+    reddit.async!.pollIntervalMs = 20
+
+    try {
+      const result = await searchRedditHandler({ start_urls: ['https://www.reddit.com/r/sales/'], query: 'cold email', limit: 5 })
+
+      expect(result.isError).toBe(true)
+      const parsed = JSON.parse(result.content[0].text)
+      expect(parsed.error).toBeTruthy()
+    } finally {
+      reddit.async!.timeoutMs = orig.t
+      reddit.async!.pollIntervalMs = orig.i
+    }
+  })
+})

package/tests/tools/search-seo.test.ts

@@ -0,0 +1,183 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest'
+import { initClient } from '../../src/client.js'
+import { searchSeoHandler } from '../../src/tools/search-seo.js'
+
+describe('search_seo handler', () => {
+  const originalFetch = globalThis.fetch
+
+  beforeEach(() => {
+    initClient('http://test-api.local', 'test-key')
+  })
+
+  afterEach(() => {
+    globalThis.fetch = originalFetch
+  })
+
+  it('category=keywords — kw_search_volume fires first', async () => {
+    globalThis.fetch = vi.fn(async (url: string | URL | Request) => {
+      const u = url.toString()
+      if (u.includes('/dataforseo/keywords/google-ads/search-volume')) {
+        return new Response(JSON.stringify({ tasks: [{ result: [{ keyword: 'cold email', search_volume: 5400 }] }] }), { status: 200 })
+      }
+      return new Response(JSON.stringify({ error: 'unexpected' }), { status: 500 })
+    }) as typeof fetch
+
+    const result = await searchSeoHandler({ category: 'keywords', keywords: ['cold email'] })
+
+    expect(result.isError).toBeFalsy()
+    const parsed = JSON.parse(result.content[0].text)
+    expect(parsed._meta.provider).toBe('kw_search_volume')
+  })
+
+  it('category=serp (google engine default) — serp_google fires', async () => {
+    globalThis.fetch = vi.fn(async (url: string | URL | Request) => {
+      const u = url.toString()
+      if (u.includes('/dataforseo/serp/google/organic')) {
+        return new Response(JSON.stringify({ tasks: [{ result: [{ items: [{ title: 'ColdIQ', url: 'https://coldiq.com' }] }] }] }), { status: 200 })
+      }
+      return new Response(JSON.stringify({ error: 'unexpected' }), { status: 500 })
+    }) as typeof fetch
+
+    const result = await searchSeoHandler({ category: 'serp', keyword: 'cold email tool' })
+
+    expect(result.isError).toBeFalsy()
+    const parsed = JSON.parse(result.content[0].text)
+    expect(parsed._meta.provider).toBe('serp_google')
+  })
+
+  it('category=serp engine=bing — serp_bing fires, serp_google skipped', async () => {
+    let googleCalled = false
+    globalThis.fetch = vi.fn(async (url: string | URL | Request) => {
+      const u = url.toString()
+      if (u.includes('/dataforseo/serp/google/organic')) { googleCalled = true }
+      if (u.includes('/dataforseo/serp/bing/organic')) {
+        return new Response(JSON.stringify({ tasks: [{ result: [{ items: [{ title: 'Bing result' }] }] }] }), { status: 200 })
+      }
+      return new Response(JSON.stringify({ error: 'unexpected' }), { status: 500 })
+    }) as typeof fetch
+
+    const result = await searchSeoHandler({ category: 'serp', keyword: 'cold email', engine: 'bing' })
+
+    expect(result.isError).toBeFalsy()
+    const parsed = JSON.parse(result.content[0].text)
+    expect(parsed._meta.provider).toBe('serp_bing')
+    expect(googleCalled).toBe(false)
+  })
+
+  it('category=serp engine=youtube — serp_youtube fires', async () => {
+    globalThis.fetch = vi.fn(async (url: string | URL | Request) => {
+      const u = url.toString()
+      if (u.includes('/dataforseo/serp/youtube/organic')) {
+        return new Response(JSON.stringify({ tasks: [{ result: [{ items: [{ title: 'YouTube result' }] }] }] }), { status: 200 })
+      }
+      return new Response(JSON.stringify({ error: 'unexpected' }), { status: 500 })
+    }) as typeof fetch
+
+    const result = await searchSeoHandler({ category: 'serp', keyword: 'cold email', engine: 'youtube' })
+
+    expect(result.isError).toBeFalsy()
+    const parsed = JSON.parse(result.content[0].text)
+    expect(parsed._meta.provider).toBe('serp_youtube')
+  })
+
+  it('category=backlinks — bl_summary fires first', async () => {
+    globalThis.fetch = vi.fn(async (url: string | URL | Request) => {
+      const u = url.toString()
+      if (u.includes('/dataforseo/backlinks/summary')) {
+        return new Response(JSON.stringify({ tasks: [{ result: [{ total_count: 1234, rank: 85 }] }] }), { status: 200 })
+      }
+      return new Response(JSON.stringify({ error: 'unexpected' }), { status: 500 })
+    }) as typeof fetch
+
+    const result = await searchSeoHandler({ category: 'backlinks', target: 'coldiq.com' })
+
+    expect(result.isError).toBeFalsy()
+    const parsed = JSON.parse(result.content[0].text)
+    expect(parsed._meta.provider).toBe('bl_summary')
+  })
+
+  it('category=domain action=technologies — domain_tech fires', async () => {
+    let whoisCalled = false
+    globalThis.fetch = vi.fn(async (url: string | URL | Request) => {
+      const u = url.toString()
+      if (u.includes('/dataforseo/domain-analytics/whois')) { whoisCalled = true }
+      if (u.includes('/dataforseo/domain-analytics/technologies')) {
+        return new Response(JSON.stringify({ tasks: [{ result: [{ technologies: { cms: ['WordPress'] } }] }] }), { status: 200 })
+      }
+      return new Response(JSON.stringify({ error: 'unexpected' }), { status: 500 })
+    }) as typeof fetch
+
+    const result = await searchSeoHandler({ category: 'domain', target: 'coldiq.com', action: 'technologies' })
+
+    expect(result.isError).toBeFalsy()
+    const parsed = JSON.parse(result.content[0].text)
+    expect(parsed._meta.provider).toBe('domain_tech')
+    expect(whoisCalled).toBe(false)
+  })
+
+  it('category=domain action=whois — domain_whois fires, domain_tech skipped', async () => {
+    let techCalled = false
+    globalThis.fetch = vi.fn(async (url: string | URL | Request) => {
+      const u = url.toString()
+      if (u.includes('/dataforseo/domain-analytics/technologies')) { techCalled = true }
+      if (u.includes('/dataforseo/domain-analytics/whois')) {
+        return new Response(JSON.stringify({ tasks: [{ result: [{ items: [{ domain: 'coldiq.com', expiration_datetime: '2026-01-01' }] }] }] }), { status: 200 })
+      }
+      return new Response(JSON.stringify({ error: 'unexpected' }), { status: 500 })
+    }) as typeof fetch
+
+    const result = await searchSeoHandler({ category: 'domain', target: 'coldiq.com', action: 'whois' })
+
+    expect(result.isError).toBeFalsy()
+    const parsed = JSON.parse(result.content[0].text)
+    expect(parsed._meta.provider).toBe('domain_whois')
+    expect(techCalled).toBe(false)
+  })
+
+  it('category=labs with target and no lab_action — labs_rank_overview fires (default)', async () => {
+    globalThis.fetch = vi.fn(async (url: string | URL | Request) => {
+      const u = url.toString()
+      if (u.includes('/dataforseo/labs/domain-rank-overview')) {
+        return new Response(JSON.stringify({ tasks: [{ result: [{ metrics: { organic: { pos_1: 3 } }, rank: 90 }] }] }), { status: 200 })
+      }
+      return new Response(JSON.stringify({ error: 'unexpected' }), { status: 500 })
+    }) as typeof fetch
+
+    const result = await searchSeoHandler({ category: 'labs', target: 'coldiq.com' })
+
+    expect(result.isError).toBeFalsy()
+    const parsed = JSON.parse(result.content[0].text)
+    expect(parsed._meta.provider).toBe('labs_rank_overview')
+  })
+
+  it('category=page page_action=content — page_content fires, page_lighthouse skipped', async () => {
+    let lighthouseCalled = false
+    globalThis.fetch = vi.fn(async (url: string | URL | Request) => {
+      const u = url.toString()
+      if (u.includes('/dataforseo/on-page/lighthouse')) { lighthouseCalled = true }
+      if (u.includes('/dataforseo/on-page/content-parsing')) {
+        return new Response(JSON.stringify({ tasks: [{ result: [{ content: 'ColdIQ homepage text', plain_text: 'ColdIQ' }] }] }), { status: 200 })
+      }
+      return new Response(JSON.stringify({ error: 'unexpected' }), { status: 500 })
+    }) as typeof fetch
+
+    const result = await searchSeoHandler({ category: 'page', url: 'https://coldiq.com', page_action: 'content' })
+
+    expect(result.isError).toBeFalsy()
+    const parsed = JSON.parse(result.content[0].text)
+    expect(parsed._meta.provider).toBe('page_content')
+    expect(lighthouseCalled).toBe(false)
+  })
+
+  it('all providers fail — returns isError', async () => {
+    globalThis.fetch = vi.fn(async () => {
+      return new Response(JSON.stringify({ error: 'down' }), { status: 503 })
+    }) as typeof fetch
+
+    const result = await searchSeoHandler({ category: 'serp', keyword: 'cold email' })
+
+    expect(result.isError).toBe(true)
+    const parsed = JSON.parse(result.content[0].text)
+    expect(parsed.error).toBeTruthy()
+  })
+})

package/tests/tools/search-web.test.ts

@@ -0,0 +1,79 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest'
+import { initClient } from '../../src/client.js'
+import { searchWebHandler } from '../../src/tools/search-web.js'
+
+describe('search_web handler', () => {
+  const originalFetch = globalThis.fetch
+
+  beforeEach(() => {
+    initClient('http://test-api.local', 'test-key')
+  })
+
+  afterEach(() => {
+    globalThis.fetch = originalFetch
+  })
+
+  it('returns Serper results for general search', async () => {
+    globalThis.fetch = vi.fn(async () =>
+      new Response(JSON.stringify({ organic: [{ title: 'ColdIQ', link: 'https://coldiq.com' }] }), { status: 200 })
+    ) as typeof fetch
+
+    const result = await searchWebHandler({ query: 'ColdIQ', search_type: 'general' })
+
+    const parsed = JSON.parse(result.content[0].text)
+    expect(parsed._meta.provider).toBe('serper')
+    expect(parsed.data.organic).toHaveLength(1)
+  })
+
+  it('prefers Exa for neural search type', async () => {
+    let capturedUrl = ''
+    globalThis.fetch = vi.fn(async (url: string | URL | Request) => {
+      capturedUrl = url.toString()
+      return new Response(JSON.stringify({ results: [{ title: 'ColdIQ', url: 'https://coldiq.com' }] }), { status: 200 })
+    }) as typeof fetch
+
+    const result = await searchWebHandler({ query: 'B2B sales intelligence', search_type: 'neural' })
+
+    expect(capturedUrl).toContain('/exa/search')
+    const parsed = JSON.parse(result.content[0].text)
+    expect(parsed._meta.provider).toBe('exa')
+  })
+
+  it('falls back to LimaData when Serper fails', async () => {
+    let callCount = 0
+    globalThis.fetch = vi.fn(async () => {
+      callCount++
+      if (callCount === 1) {
+        return new Response(JSON.stringify({ error: 'Rate limited' }), { status: 429 })
+      }
+      return new Response(JSON.stringify({ organic: [{ title: 'ColdIQ', link: 'https://coldiq.com' }] }), { status: 200 })
+    }) as typeof fetch
+
+    const result = await searchWebHandler({ query: 'ColdIQ', search_type: 'general' })
+
+    const parsed = JSON.parse(result.content[0].text)
+    expect(parsed._meta.provider).toBe('limadata')
+  })
+
+  it('falls back to Exa when Serper and LimaData both fail', async () => {
+    let callCount = 0
+    let capturedUrls: string[] = []
+    globalThis.fetch = vi.fn(async (url: string | URL | Request) => {
+      capturedUrls.push(url.toString())
+      callCount++
+      if (callCount === 1) {
+        return new Response(JSON.stringify({ error: 'Rate limited' }), { status: 429 })
+      }
+      if (callCount === 2) {
+        return new Response(JSON.stringify({ error: 'Service unavailable' }), { status: 500 })
+      }
+      return new Response(JSON.stringify({ results: [{ title: 'ColdIQ', url: 'https://coldiq.com' }] }), { status: 200 })
+    }) as typeof fetch
+
+    const result = await searchWebHandler({ query: 'ColdIQ', search_type: 'general' })
+
+    expect(capturedUrls[2]).toContain('/exa/search')
+    const parsed = JSON.parse(result.content[0].text)
+    expect(parsed._meta.provider).toBe('exa')
+  })
+})

package/tests/tools/verify-email.test.ts

@@ -0,0 +1,68 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest'
+import { initClient } from '../../src/client.js'
+import { verifyEmailHandler } from '../../src/tools/verify-email.js'
+
+describe('verify_email handler', () => {
+  const originalFetch = globalThis.fetch
+
+  beforeEach(() => {
+    initClient('http://test-api.local', 'test-key')
+  })
+
+  afterEach(() => {
+    globalThis.fetch = originalFetch
+  })
+
+  it('returns verification result from FindyMail', async () => {
+    globalThis.fetch = vi.fn(async () =>
+      new Response(JSON.stringify({ status: 'valid', email: 'michel@coldiq.com' }), { status: 200 })
+    ) as typeof fetch
+
+    const result = await verifyEmailHandler({ email: 'michel@coldiq.com' })
+
+    const parsed = JSON.parse(result.content[0].text)
+    expect(parsed._meta.provider).toBe('findymail')
+    expect(parsed.data.status).toBe('valid')
+  })
+
+  it('falls back to IcyPeas on FindyMail failure', async () => {
+    let callCount = 0
+    globalThis.fetch = vi.fn(async () => {
+      callCount++
+      if (callCount === 1) {
+        return new Response(JSON.stringify({ error: 'Provider error' }), { status: 502 })
+      }
+      return new Response(JSON.stringify({ result: 'valid' }), { status: 200 })
+    }) as typeof fetch
+
+    const result = await verifyEmailHandler({ email: 'michel@coldiq.com' })
+
+    const parsed = JSON.parse(result.content[0].text)
+    expect(parsed._meta.provider).toBe('icypeas')
+  })
+
+  it('falls through to Instantly when FindyMail and IcyPeas both fail, polls until terminal status', async () => {
+    let callCount = 0
+    globalThis.fetch = vi.fn(async (url: string | URL | Request) => {
+      const urlStr = typeof url === 'string' ? url : url instanceof URL ? url.href : url.url
+      callCount++
+      // Findymail and IcyPeas fail
+      if (urlStr.includes('findymail') || urlStr.includes('icypeas')) {
+        return new Response(JSON.stringify({ error: 'Provider error' }), { status: 502 })
+      }
+      // Instantly POST returns pending first
+      if (urlStr.includes('email-verification') && !urlStr.includes('%40')) {
+        return new Response(JSON.stringify({ email: 'michel@coldiq.com', status: 'pending' }), { status: 200 })
+      }
+      // Instantly GET poll returns terminal status
+      return new Response(JSON.stringify({ email: 'michel@coldiq.com', status: 'valid' }), { status: 200 })
+    }) as typeof fetch
+
+    const result = await verifyEmailHandler({ email: 'michel@coldiq.com' })
+
+    const parsed = JSON.parse(result.content[0].text)
+    expect(result.isError).toBeFalsy()
+    expect(parsed._meta.provider).toBe('instantly')
+    expect(parsed.data.status).toBe('valid')
+  })
+})

package/tsconfig.json

@@ -0,0 +1,17 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "outDir": "dist",
+    "rootDir": "src",
+    "declaration": true,
+    "declarationMap": true,
+    "sourceMap": true
+  },
+  "include": ["src"],
+  "exclude": ["node_modules", "dist", "tests"]
+}

package/vitest.config.ts

@@ -0,0 +1,7 @@
+import { defineConfig } from 'vitest/config'
+
+export default defineConfig({
+  test: {
+    include: ['tests/**/*.test.ts'],
+  },
+})