@coldiq/mcp 0.3.31 → 0.3.33
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +44 -0
- package/dist/tools/find-emails-bulk.d.ts.map +1 -1
- package/dist/tools/find-emails-bulk.js +4 -2
- package/dist/tools/find-emails-bulk.js.map +1 -1
- package/dist/tools/get-bulk-job.d.ts.map +1 -1
- package/dist/tools/get-bulk-job.js +1 -0
- package/dist/tools/get-bulk-job.js.map +1 -1
- package/dist/tools/search-companies.d.ts.map +1 -1
- package/dist/tools/search-companies.js +5 -0
- package/dist/tools/search-companies.js.map +1 -1
- package/package.json +1 -1
- package/src/tools/find-emails-bulk.ts +4 -2
- package/src/tools/get-bulk-job.ts +1 -0
- package/src/tools/search-companies.ts +5 -0
- package/tests/tools/search-companies.test.ts +19 -0
package/README.md
CHANGED
|
@@ -14,6 +14,17 @@ An [MCP (Model Context Protocol)](https://modelcontextprotocol.io) server that e
|
|
|
14
14
|
| `COLDIQ_API_KEY` | Yes | — | Your ColdIQ API key |
|
|
15
15
|
| `COLDIQ_API_URL` | No | `https://api.coldiq.com` | Override the API base URL |
|
|
16
16
|
| `COLDIQ_DEBUG` | No | — | Set to `1` to enable debug logging |
|
|
17
|
+
| `COLDIQ_HTTP_TIMEOUT_MS` | No | `120000` | Per-request timeout. Async verbs (e.g. `find_people`, bulk jobs) run a full server-side waterfall and can take 20–90s, so the default is deliberately generous. |
|
|
18
|
+
|
|
19
|
+
## Fastest install (all agents)
|
|
20
|
+
|
|
21
|
+
One command installs the MCP server **and** the GTM skills into whichever agents you have (Claude Code, Cursor, Codex, Windsurf, Cline):
|
|
22
|
+
|
|
23
|
+
```bash
|
|
24
|
+
curl -fsSL https://raw.githubusercontent.com/Cold-IQ/coldiq-marketplace-skills/main/install.sh | COLDIQ_API_KEY=your_key bash
|
|
25
|
+
```
|
|
26
|
+
|
|
27
|
+
Re-run it any time to update. To wire a single agent by hand instead, use the per-agent snippets below.
|
|
17
28
|
|
|
18
29
|
## Connecting to Claude
|
|
19
30
|
|
|
@@ -49,6 +60,39 @@ The `--scope user` flag makes the server available in all your projects. The `--
|
|
|
49
60
|
COLDIQ_API_KEY=your_key npx @coldiq/mcp@latest
|
|
50
61
|
```
|
|
51
62
|
|
|
63
|
+
## Connecting to other agents
|
|
64
|
+
|
|
65
|
+
The server is a standard stdio MCP server, so any MCP-compatible client works. Agents without a native skills loader (Codex, Windsurf, Cline) still reach the 18 GTM skills through the `list_skills` / `load_skill` tools — installing the MCP is enough.
|
|
66
|
+
|
|
67
|
+
### Cursor
|
|
68
|
+
|
|
69
|
+
Add to `~/.cursor/mcp.json`, then approve the server in Settings → MCP:
|
|
70
|
+
|
|
71
|
+
```json
|
|
72
|
+
{
|
|
73
|
+
"mcpServers": {
|
|
74
|
+
"coldiq": {
|
|
75
|
+
"command": "npx",
|
|
76
|
+
"args": ["-y", "@coldiq/mcp@latest"],
|
|
77
|
+
"env": { "COLDIQ_API_KEY": "your_api_key_here" }
|
|
78
|
+
}
|
|
79
|
+
}
|
|
80
|
+
}
|
|
81
|
+
```
|
|
82
|
+
|
|
83
|
+
### Codex
|
|
84
|
+
|
|
85
|
+
```bash
|
|
86
|
+
codex mcp add coldiq --env COLDIQ_API_KEY=your_key -- npx -y @coldiq/mcp@latest
|
|
87
|
+
```
|
|
88
|
+
|
|
89
|
+
### Windsurf / Cline
|
|
90
|
+
|
|
91
|
+
Add the same `{ "mcpServers": { "coldiq": … } }` block (see Cursor) to:
|
|
92
|
+
|
|
93
|
+
- **Windsurf:** `~/.codeium/windsurf/mcp_config.json`
|
|
94
|
+
- **Cline:** its `cline_mcp_settings.json` (VS Code globalStorage), then refresh MCP servers.
|
|
95
|
+
|
|
52
96
|
## Available Tools
|
|
53
97
|
|
|
54
98
|
### Prospecting
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"find-emails-bulk.d.ts","sourceRoot":"","sources":["../../src/tools/find-emails-bulk.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAA;AAGvB,eAAO,MAAM,kBAAkB,qBAAqB,CAAA;AAEpD,eAAO,MAAM,yBAAyB,
|
|
1
|
+
{"version":3,"file":"find-emails-bulk.d.ts","sourceRoot":"","sources":["../../src/tools/find-emails-bulk.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAA;AAGvB,eAAO,MAAM,kBAAkB,qBAAqB,CAAA;AAEpD,eAAO,MAAM,yBAAyB,QAUY,CAAA;AAElD,eAAO,MAAM,oBAAoB;;;;;;;;;;;;;;;;;;;;;CAehC,CAAA;AAED,wBAAsB,qBAAqB,CAAC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;;;;;;GAGzE"}
|
|
@@ -5,8 +5,10 @@ export const findEmailsBulkDescription = 'Find professional emails for up to 5,0
|
|
|
5
5
|
'Poll get_bulk_job(job_id) until status is "done" (usually minutes), then read the found/not_found summary and page through rows. ' +
|
|
6
6
|
'Each person should have first_name + last_name + domain (people missing those come back as not_found and are not charged). ' +
|
|
7
7
|
'Charged only per found email. A "found" row means an email was LOCATED, not verified deliverable: each row\'s ' +
|
|
8
|
-
'result carries a `confidence` (high/medium/
|
|
9
|
-
'verify_emails_bulk before sending, or you risk bounces.
|
|
8
|
+
'result carries a `confidence` (high/medium/unknown) — treat medium/unknown as unverified and run ' +
|
|
9
|
+
'verify_emails_bulk before sending, or you risk bounces. A located email the provider itself flags as a low-confidence ' +
|
|
10
|
+
'pattern guess comes back as verdict `guessed` instead of `found` and is FREE — never send a `guessed` email unverified. ' +
|
|
11
|
+
'The 202 response includes `credits_reserved` (worst-case hold, ' +
|
|
10
12
|
'settled to actual on completion) and a `low_balance_warning` when your balance is running low. For 50 or fewer people that ' +
|
|
11
13
|
'you want back inline, use find_emails instead.';
|
|
12
14
|
export const findEmailsBulkSchema = {
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"find-emails-bulk.js","sourceRoot":"","sources":["../../src/tools/find-emails-bulk.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAA;AACvB,OAAO,EAAE,OAAO,EAAE,MAAM,cAAc,CAAA;AAEtC,MAAM,CAAC,MAAM,kBAAkB,GAAG,kBAAkB,CAAA;AAEpD,MAAM,CAAC,MAAM,yBAAyB,GACpC,uIAAuI;IACvI,mIAAmI;IACnI,6HAA6H;IAC7H,gHAAgH;IAChH,
|
|
1
|
+
{"version":3,"file":"find-emails-bulk.js","sourceRoot":"","sources":["../../src/tools/find-emails-bulk.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAA;AACvB,OAAO,EAAE,OAAO,EAAE,MAAM,cAAc,CAAA;AAEtC,MAAM,CAAC,MAAM,kBAAkB,GAAG,kBAAkB,CAAA;AAEpD,MAAM,CAAC,MAAM,yBAAyB,GACpC,uIAAuI;IACvI,mIAAmI;IACnI,6HAA6H;IAC7H,gHAAgH;IAChH,mGAAmG;IACnG,wHAAwH;IACxH,0HAA0H;IAC1H,iEAAiE;IACjE,6HAA6H;IAC7H,gDAAgD,CAAA;AAElD,MAAM,CAAC,MAAM,oBAAoB,GAAG;IAClC,MAAM,EAAE,CAAC;SACN,KAAK,CACJ,CAAC,CAAC,MAAM,CAAC;QACP,EAAE,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,yFAAyF,CAAC;QAC7H,UAAU,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,YAAY,CAAC;QACxD,SAAS,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,WAAW,CAAC;QACtD,MAAM,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,oCAAoC,CAAC;QAC5E,YAAY,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,iCAAiC,CAAC;KAChF,CAAC,CACH;SACA,GAAG,CAAC,CAAC,CAAC;SACN,GAAG,CAAC,IAAI,CAAC;SACT,QAAQ,CAAC,gGAAgG,CAAC;IAC7G,WAAW,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,mDAAmD,CAAC;CACjG,CAAA;AAED,MAAM,CAAC,KAAK,UAAU,qBAAqB,CAAC,KAA8B;IACxE,MAAM,GAAG,GAAG,MAAM,OAAO,CAAC,MAAM,EAAE,yBAAyB,EAAE,KAAK,CAAC,CAAA;IACnE,OAAO,EAAE,OAAO,EAAE,CAAC,EAAE,IAAI,EAAE,MAAe,EAAE,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC,EAAE,OAAO,EAAE,CAAC,GAAG,CAAC,EAAE,EAAE,CAAA;AACnG,CAAC"}
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"get-bulk-job.d.ts","sourceRoot":"","sources":["../../src/tools/get-bulk-job.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAA;AAGvB,eAAO,MAAM,cAAc,iBAAiB,CAAA;AAE5C,eAAO,MAAM,qBAAqB,
|
|
1
|
+
{"version":3,"file":"get-bulk-job.d.ts","sourceRoot":"","sources":["../../src/tools/get-bulk-job.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAA;AAGvB,eAAO,MAAM,cAAc,iBAAiB,CAAA;AAE5C,eAAO,MAAM,qBAAqB,QASsB,CAAA;AAExD,eAAO,MAAM,gBAAgB;;;;CAI5B,CAAA;AAED,wBAAsB,iBAAiB,CAAC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;;;;;;GAIrE"}
|
|
@@ -4,6 +4,7 @@ export const getBulkJobName = 'get_bulk_job';
|
|
|
4
4
|
export const getBulkJobDescription = 'Poll any async bulk job (verify_emails_bulk, find_emails_bulk, enrich_person_bulk, enrich_company_bulk, find_phone_bulk). ' +
|
|
5
5
|
'Returns { status, items_total, items_processed, summary, coverage, credits_reserved, credits_charged, page }. Poll until status is "done" (or "timed_out"). ' +
|
|
6
6
|
'Use the `summary` per-verdict counts for totals — do NOT expect all rows inline: rows come one page at a time (default 100). ' +
|
|
7
|
+
'For find jobs, verdict `guessed` means an email was located but the provider marked it a low-confidence pattern guess — it is NOT billed; verify it before sending. ' +
|
|
7
8
|
'The `coverage` block {conclusive, skipped, unverifiable, failed, pending} tells you how much was truly resolved: `skipped` rows (per-row ' +
|
|
8
9
|
'`result.reason` chunk_failed/not_returned/timed_out) were never conclusively checked and are safe to re-submit; `failed` is a hard error (retry unlikely to help). ' +
|
|
9
10
|
'`credits_charged` (null until settled) is the actual spend; `credits_reserved` is the worst-case hold. Each row echoes its submitted `input`, ' +
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"get-bulk-job.js","sourceRoot":"","sources":["../../src/tools/get-bulk-job.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAA;AACvB,OAAO,EAAE,OAAO,EAAE,MAAM,cAAc,CAAA;AAEtC,MAAM,CAAC,MAAM,cAAc,GAAG,cAAc,CAAA;AAE5C,MAAM,CAAC,MAAM,qBAAqB,GAChC,4HAA4H;IAC5H,8JAA8J;IAC9J,+HAA+H;IAC/H,2IAA2I;IAC3I,qKAAqK;IACrK,gJAAgJ;IAChJ,yIAAyI;IACzI,sDAAsD,CAAA;AAExD,MAAM,CAAC,MAAM,gBAAgB,GAAG;IAC9B,MAAM,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,CAAC,QAAQ,CAAC,8CAA8C,CAAC;IACjF,MAAM,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,4LAA4L,CAAC;IAC1O,KAAK,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,wCAAwC,CAAC;CACvG,CAAA;AAED,MAAM,CAAC,KAAK,UAAU,iBAAiB,CAAC,KAA8B;IACpE,MAAM,EAAE,MAAM,EAAE,GAAG,IAAI,EAAE,GAAG,KAAK,CAAA;IACjC,MAAM,GAAG,GAAG,MAAM,OAAO,CAAC,MAAM,EAAE,SAAS,MAAM,UAAU,EAAE,IAAI,CAAC,CAAA;IAClE,OAAO,EAAE,OAAO,EAAE,CAAC,EAAE,IAAI,EAAE,MAAe,EAAE,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC,EAAE,OAAO,EAAE,CAAC,GAAG,CAAC,EAAE,EAAE,CAAA;AACnG,CAAC"}
|
|
1
|
+
{"version":3,"file":"get-bulk-job.js","sourceRoot":"","sources":["../../src/tools/get-bulk-job.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAA;AACvB,OAAO,EAAE,OAAO,EAAE,MAAM,cAAc,CAAA;AAEtC,MAAM,CAAC,MAAM,cAAc,GAAG,cAAc,CAAA;AAE5C,MAAM,CAAC,MAAM,qBAAqB,GAChC,4HAA4H;IAC5H,8JAA8J;IAC9J,+HAA+H;IAC/H,sKAAsK;IACtK,2IAA2I;IAC3I,qKAAqK;IACrK,gJAAgJ;IAChJ,yIAAyI;IACzI,sDAAsD,CAAA;AAExD,MAAM,CAAC,MAAM,gBAAgB,GAAG;IAC9B,MAAM,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,CAAC,QAAQ,CAAC,8CAA8C,CAAC;IACjF,MAAM,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,4LAA4L,CAAC;IAC1O,KAAK,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,wCAAwC,CAAC;CACvG,CAAA;AAED,MAAM,CAAC,KAAK,UAAU,iBAAiB,CAAC,KAA8B;IACpE,MAAM,EAAE,MAAM,EAAE,GAAG,IAAI,EAAE,GAAG,KAAK,CAAA;IACjC,MAAM,GAAG,GAAG,MAAM,OAAO,CAAC,MAAM,EAAE,SAAS,MAAM,UAAU,EAAE,IAAI,CAAC,CAAA;IAClE,OAAO,EAAE,OAAO,EAAE,CAAC,EAAE,IAAI,EAAE,MAAe,EAAE,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC,EAAE,OAAO,EAAE,CAAC,GAAG,CAAC,EAAE,EAAE,CAAA;AACnG,CAAC"}
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"search-companies.d.ts","sourceRoot":"","sources":["../../src/tools/search-companies.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAA;AAIvB,eAAO,MAAM,mBAAmB,qBAAqB,CAAA;AAErD,eAAO,MAAM,0BAA0B,QAEkV,CAAA;AAEzX,eAAO,MAAM,qBAAqB;;;;;;;;;;;;;;;;;;;;;;;;;;;CA2BjC,CAAA;
|
|
1
|
+
{"version":3,"file":"search-companies.d.ts","sourceRoot":"","sources":["../../src/tools/search-companies.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAA;AAIvB,eAAO,MAAM,mBAAmB,qBAAqB,CAAA;AAErD,eAAO,MAAM,0BAA0B,QAEkV,CAAA;AAEzX,eAAO,MAAM,qBAAqB;;;;;;;;;;;;;;;;;;;;;;;;;;;CA2BjC,CAAA;AAuCD,wBAAsB,sBAAsB,CAAC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;;;;;;;;;;;;GAgB1E"}
|
|
@@ -40,12 +40,17 @@ export const searchCompaniesSchema = {
|
|
|
40
40
|
// filter and reopen the billing hole. Exclusion fields (`exclude_*`) are
|
|
41
41
|
// deliberately absent — excluding a domain narrows nothing on its own. Kept in
|
|
42
42
|
// sync with the server-side guard in src/router/verb-handler.ts.
|
|
43
|
+
// MUST stay in sync with NARROWING_KEYS in src/router/verb-handler.ts (the
|
|
44
|
+
// server-side guard). Drift here is a usability false-reject: the MCP client
|
|
45
|
+
// refuses a search the API would happily serve. `similar_to_domains` (lookalike
|
|
46
|
+
// seeds) narrows — a seeds-only search is a legitimate, bounded query.
|
|
43
47
|
const NARROWING_FILTER_KEYS = [
|
|
44
48
|
'keywords', 'countries', 'locations', 'industries', 'technologies',
|
|
45
49
|
'min_employees', 'max_employees', 'min_founded_year', 'max_founded_year',
|
|
46
50
|
'funding_stages', 'min_funding_amount', 'max_funding_amount',
|
|
47
51
|
'min_funding_year', 'max_funding_year', 'min_revenue', 'max_revenue',
|
|
48
52
|
'is_hiring', 'min_workforce_growth_pct', 'linkedin_search_url',
|
|
53
|
+
'similar_to_domains',
|
|
49
54
|
];
|
|
50
55
|
// A value narrows only when it actually constrains: a non-blank string, an array
|
|
51
56
|
// with at least one non-blank element, a non-zero finite number (a `min_*` of 0
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"search-companies.js","sourceRoot":"","sources":["../../src/tools/search-companies.ts"],"names":[],"mappings":"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
|
|
1
|
+
{"version":3,"file":"search-companies.js","sourceRoot":"","sources":["../../src/tools/search-companies.ts"],"names":[],"mappings":"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"}
|
package/package.json
CHANGED
|
@@ -8,8 +8,10 @@ export const findEmailsBulkDescription =
|
|
|
8
8
|
'Poll get_bulk_job(job_id) until status is "done" (usually minutes), then read the found/not_found summary and page through rows. ' +
|
|
9
9
|
'Each person should have first_name + last_name + domain (people missing those come back as not_found and are not charged). ' +
|
|
10
10
|
'Charged only per found email. A "found" row means an email was LOCATED, not verified deliverable: each row\'s ' +
|
|
11
|
-
'result carries a `confidence` (high/medium/
|
|
12
|
-
'verify_emails_bulk before sending, or you risk bounces.
|
|
11
|
+
'result carries a `confidence` (high/medium/unknown) — treat medium/unknown as unverified and run ' +
|
|
12
|
+
'verify_emails_bulk before sending, or you risk bounces. A located email the provider itself flags as a low-confidence ' +
|
|
13
|
+
'pattern guess comes back as verdict `guessed` instead of `found` and is FREE — never send a `guessed` email unverified. ' +
|
|
14
|
+
'The 202 response includes `credits_reserved` (worst-case hold, ' +
|
|
13
15
|
'settled to actual on completion) and a `low_balance_warning` when your balance is running low. For 50 or fewer people that ' +
|
|
14
16
|
'you want back inline, use find_emails instead.'
|
|
15
17
|
|
|
@@ -7,6 +7,7 @@ export const getBulkJobDescription =
|
|
|
7
7
|
'Poll any async bulk job (verify_emails_bulk, find_emails_bulk, enrich_person_bulk, enrich_company_bulk, find_phone_bulk). ' +
|
|
8
8
|
'Returns { status, items_total, items_processed, summary, coverage, credits_reserved, credits_charged, page }. Poll until status is "done" (or "timed_out"). ' +
|
|
9
9
|
'Use the `summary` per-verdict counts for totals — do NOT expect all rows inline: rows come one page at a time (default 100). ' +
|
|
10
|
+
'For find jobs, verdict `guessed` means an email was located but the provider marked it a low-confidence pattern guess — it is NOT billed; verify it before sending. ' +
|
|
10
11
|
'The `coverage` block {conclusive, skipped, unverifiable, failed, pending} tells you how much was truly resolved: `skipped` rows (per-row ' +
|
|
11
12
|
'`result.reason` chunk_failed/not_returned/timed_out) were never conclusively checked and are safe to re-submit; `failed` is a hard error (retry unlikely to help). ' +
|
|
12
13
|
'`credits_charged` (null until settled) is the actual spend; `credits_reserved` is the worst-case hold. Each row echoes its submitted `input`, ' +
|
|
@@ -45,12 +45,17 @@ export const searchCompaniesSchema = {
|
|
|
45
45
|
// filter and reopen the billing hole. Exclusion fields (`exclude_*`) are
|
|
46
46
|
// deliberately absent — excluding a domain narrows nothing on its own. Kept in
|
|
47
47
|
// sync with the server-side guard in src/router/verb-handler.ts.
|
|
48
|
+
// MUST stay in sync with NARROWING_KEYS in src/router/verb-handler.ts (the
|
|
49
|
+
// server-side guard). Drift here is a usability false-reject: the MCP client
|
|
50
|
+
// refuses a search the API would happily serve. `similar_to_domains` (lookalike
|
|
51
|
+
// seeds) narrows — a seeds-only search is a legitimate, bounded query.
|
|
48
52
|
const NARROWING_FILTER_KEYS = [
|
|
49
53
|
'keywords', 'countries', 'locations', 'industries', 'technologies',
|
|
50
54
|
'min_employees', 'max_employees', 'min_founded_year', 'max_founded_year',
|
|
51
55
|
'funding_stages', 'min_funding_amount', 'max_funding_amount',
|
|
52
56
|
'min_funding_year', 'max_funding_year', 'min_revenue', 'max_revenue',
|
|
53
57
|
'is_hiring', 'min_workforce_growth_pct', 'linkedin_search_url',
|
|
58
|
+
'similar_to_domains',
|
|
54
59
|
] as const
|
|
55
60
|
|
|
56
61
|
// A value narrows only when it actually constrains: a non-blank string, an array
|
|
@@ -82,6 +82,25 @@ describe('search_companies handler', () => {
|
|
|
82
82
|
expect(globalThis.fetch).toHaveBeenCalledOnce()
|
|
83
83
|
})
|
|
84
84
|
|
|
85
|
+
// Regression: the server's NARROWING_KEYS accepts similar_to_domains, so the MCP
|
|
86
|
+
// guard must too — otherwise a lookalike-only TAM search is falsely rejected
|
|
87
|
+
// client-side and never reaches the API.
|
|
88
|
+
it('treats a seeds-only lookalike search (similar_to_domains) as discriminating', async () => {
|
|
89
|
+
globalThis.fetch = okFetch()
|
|
90
|
+
|
|
91
|
+
const result = await searchCompaniesHandler({ similar_to_domains: ['coldiq.com'], limit: 10 })
|
|
92
|
+
|
|
93
|
+
expect(result.isError).toBeFalsy()
|
|
94
|
+
expect(globalThis.fetch).toHaveBeenCalledOnce()
|
|
95
|
+
})
|
|
96
|
+
|
|
97
|
+
it('still rejects an empty similar_to_domains array', async () => {
|
|
98
|
+
const result = await searchCompaniesHandler({ similar_to_domains: [] })
|
|
99
|
+
|
|
100
|
+
expect(result.isError).toBe(true)
|
|
101
|
+
expect(fetchSpy).not.toHaveBeenCalled()
|
|
102
|
+
})
|
|
103
|
+
|
|
85
104
|
it('treats boolean true and non-zero numeric filters as discriminating', async () => {
|
|
86
105
|
globalThis.fetch = okFetch()
|
|
87
106
|
|