@coldiq/mcp 0.1.8 → 0.1.10

package/tests/tools/find-emails.test.ts

@@ -313,3 +313,90 @@ interface EmailResult {
   email: string | null
   provider: string | null
 }
+
+describe('find_emails handler — use_providers', () => {
+  const originalFetch = globalThis.fetch
+
+  beforeEach(() => {
+    initClient('http://test-api.local', 'test-key')
+  })
+
+  afterEach(() => {
+    globalThis.fetch = originalFetch
+  })
+
+  it('Scenario A — pinned to prospeo only, skips fallback providers', async () => {
+    let findymailCalled = false
+    globalThis.fetch = vi.fn(async (url: string | URL | Request) => {
+      const u = url.toString()
+      if (u.includes('/findymail')) findymailCalled = true
+      if (u.includes('/prospeo/bulk-enrich-person')) {
+        return new Response(JSON.stringify({
+          error: false,
+          results: [{ identifier: 'p1', person: { email: { email: 'alice@example.com' } } }],
+        }), { status: 200 })
+      }
+      return new Response(JSON.stringify({ error: 'unexpected' }), { status: 500 })
+    }) as typeof fetch
+
+    const result = await findEmailsHandler({
+      people: [{ id: 'p1', first_name: 'Alice', domain: 'example.com' }],
+      use_providers: ['prospeo'],
+    })
+
+    expect(result.isError).toBeUndefined()
+    expect(findymailCalled).toBe(false)
+    const parsed = JSON.parse(result.content[0].text)
+    expect(parsed.data.results[0]).toMatchObject({ provider: 'prospeo' })
+  })
+
+  it('Scenario H — all pinned providers find nothing → returns isError with pushback message', async () => {
+    globalThis.fetch = vi.fn(async () =>
+      new Response(JSON.stringify({ error: false, results: [] }), { status: 200 })
+    ) as typeof fetch
+
+    const result = await findEmailsHandler({
+      people: [{ id: 'p1', first_name: 'Unknown', domain: 'nowhere.xyz' }],
+      use_providers: ['findymail'],
+    })
+
+    expect(result.isError).toBe(true)
+    const parsed = JSON.parse(result.content[0].text)
+    expect(parsed.error).toContain('Couldn\'t fulfill')
+    expect(parsed.error).toContain('ColdIQ will automatically pick the best tool')
+  })
+
+  it('Scenario E — unrecognized provider name returns isError', async () => {
+    const result = await findEmailsHandler({
+      people: [{ id: 'p1', first_name: 'Alice', domain: 'example.com' }],
+      use_providers: ['wiza'],
+    })
+
+    expect(result.isError).toBe(true)
+    const parsed = JSON.parse(result.content[0].text)
+    expect(parsed.error).toContain("'wiza' is not a recognized provider")
+    expect(parsed.error).toContain('ColdIQ will automatically pick the best tool')
+  })
+
+  it('Scenario G — ordered providers: first succeeds, second skipped', async () => {
+    let icypeasCalled = false
+    globalThis.fetch = vi.fn(async (url: string | URL | Request) => {
+      const u = url.toString()
+      if (u.includes('/icypeas')) icypeasCalled = true
+      if (u.includes('/findymail/search/name')) {
+        return new Response(JSON.stringify({ email: 'alice@example.com' }), { status: 200 })
+      }
+      return new Response(JSON.stringify({ error: 'unexpected' }), { status: 500 })
+    }) as typeof fetch
+
+    const result = await findEmailsHandler({
+      people: [{ id: 'p1', first_name: 'Alice', domain: 'example.com' }],
+      use_providers: ['findymail', 'icypeas'],
+    })
+
+    expect(result.isError).toBeUndefined()
+    const parsed = JSON.parse(result.content[0].text)
+    expect(parsed.data.results[0]).toMatchObject({ provider: 'findymail', email: 'alice@example.com' })
+    expect(icypeasCalled).toBe(false)
+  })
+})

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

@@ -55,4 +55,44 @@ describe('search_companies handler', () => {
     expect(parsed.error).toContain('All')
     expect(parsed.providers_tried.length).toBeGreaterThan(0)
   })
+
+  describe('use_providers', () => {
+    it('Scenario A — pinned provider succeeds, skips others', async () => {
+      let callCount = 0
+      globalThis.fetch = vi.fn(async () => {
+        callCount++
+        return new Response(JSON.stringify({ data: [{ name: 'ColdIQ' }] }), { status: 200 })
+      }) as typeof fetch
+
+      const result = await searchCompaniesHandler({ countries: ['FR'], limit: 5, use_providers: ['companyenrich'] })
+
+      expect(result.isError).toBeUndefined()
+      expect(callCount).toBe(1)
+      const parsed = JSON.parse(result.content[0].text)
+      expect(parsed._meta.provider).toBe('companyenrich')
+    })
+
+    it('Scenario E — unrecognized provider returns isError with helpful message', async () => {
+      const result = await searchCompaniesHandler({ countries: ['FR'], limit: 5, use_providers: ['salesforce'] })
+
+      expect(result.isError).toBe(true)
+      const parsed = JSON.parse(result.content[0].text)
+      expect(parsed.error).toContain("'salesforce' is not a recognized provider")
+      expect(parsed.error).toContain('ColdIQ will automatically pick the best tool')
+      expect(parsed.available_providers).toBeInstanceOf(Array)
+    })
+
+    it('Scenario D — fuzzy match resolves typo and surfaces matchedFrom', async () => {
+      globalThis.fetch = vi.fn(async () =>
+        new Response(JSON.stringify({ data: [{ name: 'ColdIQ' }] }), { status: 200 })
+      ) as typeof fetch
+
+      const result = await searchCompaniesHandler({ countries: ['FR'], limit: 5, use_providers: ['fullenrch'] })
+
+      expect(result.isError).toBeUndefined()
+      const parsed = JSON.parse(result.content[0].text)
+      expect(parsed._meta.provider).toBe('fullenrich')
+      expect(parsed._meta.matchedFrom).toEqual({ fullenrch: 'fullenrich' })
+    })
+  })
 })

package/tests/utils/fuzzy.test.ts

@@ -0,0 +1,63 @@
+import { describe, it, expect } from 'vitest'
+import { normalize, fuzzyMatch } from '../../src/utils/fuzzy.js'
+
+describe('normalize', () => {
+  it('lowercases', () => {
+    expect(normalize('FullEnrich')).toBe('fullenrich')
+  })
+
+  it('strips hyphens', () => {
+    expect(normalize('ai-ark')).toBe('aiark')
+    expect(normalize('find-email')).toBe('findemail')
+  })
+
+  it('strips spaces', () => {
+    expect(normalize('blitz api')).toBe('blitzapi')
+  })
+
+  it('strips underscores', () => {
+    expect(normalize('ai_ark')).toBe('aiark')
+  })
+})
+
+describe('fuzzyMatch', () => {
+  const candidates = ['prospeo', 'fullenrich', 'findymail', 'icypeas', 'wiza', 'ai-ark', 'limadata']
+
+  it('exact match', () => {
+    const r = fuzzyMatch('prospeo', candidates)
+    expect(r).toEqual({ matched: 'prospeo', via: 'exact' })
+  })
+
+  it('normalized match (case)', () => {
+    const r = fuzzyMatch('Prospeo', candidates)
+    expect(r).toEqual({ matched: 'prospeo', via: 'normalized' })
+  })
+
+  it('normalized match (punctuation stripped)', () => {
+    const r = fuzzyMatch('ai_ark', candidates)
+    expect(r).toEqual({ matched: 'ai-ark', via: 'normalized' })
+  })
+
+  it('fuzzy match (1 typo)', () => {
+    const r = fuzzyMatch('prospec', candidates)
+    expect(r).toEqual({ matched: 'prospeo', via: 'fuzzy' })
+  })
+
+  it('fuzzy match (1 char addition in longer name)', () => {
+    const r = fuzzyMatch('fullenrichx', candidates)
+    expect(r?.matched).toBe('fullenrich')
+    expect(r?.via).toBe('fuzzy')
+  })
+
+  it('no match for clearly wrong name', () => {
+    expect(fuzzyMatch('salesforce', candidates)).toBeNull()
+  })
+
+  it('no match for very short string with no candidate', () => {
+    expect(fuzzyMatch('xyz', candidates)).toBeNull()
+  })
+
+  it('returns null when candidates is empty', () => {
+    expect(fuzzyMatch('prospeo', [])).toBeNull()
+  })
+})

package/tests/utils/provider-resolver.test.ts

@@ -0,0 +1,145 @@
+import { describe, it, expect } from 'vitest'
+import { resolvePreferredProviders } from '../../src/utils/provider-resolver.js'
+
+describe('resolvePreferredProviders', () => {
+  describe('auto-route path (empty / absent)', () => {
+    it('returns ok with empty providers when field is absent', () => {
+      const r = resolvePreferredProviders('find_email', {}, undefined)
+      expect(r.ok).toBe(true)
+      if (r.ok) expect(r.providers).toEqual([])
+    })
+
+    it('returns ok with empty providers when field is empty array', () => {
+      const r = resolvePreferredProviders('find_email', {}, [])
+      expect(r.ok).toBe(true)
+      if (r.ok) expect(r.providers).toEqual([])
+    })
+  })
+
+  describe('Scenario A — valid provider, exact match', () => {
+    it('resolves known provider and returns it', () => {
+      const r = resolvePreferredProviders('find_email', { first_name: 'Michel', domain: 'coldiq.com' }, ['findymail'])
+      expect(r.ok).toBe(true)
+      if (r.ok) {
+        expect(r.providers).toEqual(['findymail'])
+        expect(r.matchedFrom).toBeUndefined()
+      }
+    })
+
+    it('preserves user order when multiple providers given', () => {
+      const r = resolvePreferredProviders(
+        'find_email',
+        { first_name: 'Michel', domain: 'coldiq.com' },
+        ['prospeo', 'findymail'],
+      )
+      expect(r.ok).toBe(true)
+      if (r.ok) expect(r.providers).toEqual(['prospeo', 'findymail'])
+    })
+  })
+
+  describe('Scenario D — fuzzy match', () => {
+    it('resolves a 1-typo name and populates matchedFrom', () => {
+      const r = resolvePreferredProviders('find_email', { first_name: 'Michel', domain: 'coldiq.com' }, ['prospec'])
+      expect(r.ok).toBe(true)
+      if (r.ok) {
+        expect(r.providers).toEqual(['prospeo'])
+        expect(r.matchedFrom).toEqual({ prospec: 'prospeo' })
+      }
+    })
+
+    it('resolves case-insensitive name (normalized match)', () => {
+      const r = resolvePreferredProviders('find_email', { first_name: 'Michel', domain: 'coldiq.com' }, ['Prospeo'])
+      expect(r.ok).toBe(true)
+      if (r.ok) {
+        expect(r.providers).toEqual(['prospeo'])
+        expect(r.matchedFrom).toEqual({ Prospeo: 'prospeo' })
+      }
+    })
+  })
+
+  describe('Scenario E — unrecognized provider', () => {
+    it('returns error for completely unknown name', () => {
+      const r = resolvePreferredProviders('find_email', {}, ['salesforce'])
+      expect(r.ok).toBe(false)
+      if (!r.ok) {
+        expect(r.error.error).toContain("'salesforce' is not a recognized provider")
+        expect(r.error.error).toContain('ColdIQ will automatically pick the best tool')
+        expect(r.error.available_providers.length).toBeGreaterThan(0)
+      }
+    })
+
+    it('returns error for provider from a different capability', () => {
+      const r = resolvePreferredProviders('find_email', {}, ['google_maps'])
+      expect(r.ok).toBe(false)
+      if (!r.ok) {
+        expect(r.error.error).toContain("'google_maps' is not a recognized provider")
+      }
+    })
+  })
+
+  describe('Scenario C — gated provider', () => {
+    it('requires gate: message says "requires X, which wasn\'t provided"', () => {
+      // blitzapi for find_email requires linkedin_url
+      const r = resolvePreferredProviders('find_email', { first_name: 'Michel', domain: 'coldiq.com' }, ['blitzapi'])
+      expect(r.ok).toBe(false)
+      if (!r.ok) {
+        expect(r.error.error).toContain("'blitzapi' requires linkedin_url, which wasn't provided")
+        expect(r.error.error).toContain('ColdIQ will automatically pick the best tool')
+      }
+    })
+
+    it('incompatible_with gate: message says "is not compatible with X"', () => {
+      // apollo for search_companies is incompatible with year/tech/funding/revenue filters
+      const r = resolvePreferredProviders(
+        'search_companies',
+        { keywords: ['SaaS'], min_founded_year: 2020 },
+        ['apollo'],
+      )
+      expect(r.ok).toBe(false)
+      if (!r.ok) {
+        expect(r.error.error).toContain("'apollo' is not compatible with")
+        expect(r.error.error).not.toContain("which wasn't provided")
+        expect(r.error.error).toContain('ColdIQ will automatically pick the best tool')
+      }
+    })
+
+    it('succeeds when gated provider inputs are satisfied', () => {
+      // blitzapi requires linkedin_url
+      const r = resolvePreferredProviders(
+        'find_email',
+        { linkedin_url: 'https://www.linkedin.com/in/michel-lieben' },
+        ['blitzapi'],
+      )
+      expect(r.ok).toBe(true)
+      if (r.ok) expect(r.providers).toEqual(['blitzapi'])
+    })
+  })
+
+  describe('duplicate de-duplication', () => {
+    it('de-duplicates provider names that resolve to the same ID', () => {
+      const r = resolvePreferredProviders(
+        'find_email',
+        { first_name: 'Michel', domain: 'coldiq.com' },
+        ['prospeo', 'Prospeo'],
+      )
+      expect(r.ok).toBe(true)
+      if (r.ok) {
+        expect(r.providers).toEqual(['prospeo'])
+        expect(r.providers).toHaveLength(1)
+      }
+    })
+  })
+
+  describe('find_emails capability (custom waterfall)', () => {
+    it('resolves providers for find_emails', () => {
+      const r = resolvePreferredProviders('find_emails', {}, ['prospeo'])
+      expect(r.ok).toBe(true)
+      if (r.ok) expect(r.providers).toEqual(['prospeo'])
+    })
+
+    it('errors for provider not in find_emails', () => {
+      const r = resolvePreferredProviders('find_emails', {}, ['wiza'])
+      expect(r.ok).toBe(false)
+    })
+  })
+})