consulti-mcp 2.5.0 → 2.6.1

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 CHANGED
@@ -3,7 +3,7 @@
3
3
  [![npm version](https://img.shields.io/npm/v/consulti-mcp.svg)](https://www.npmjs.com/package/consulti-mcp)
4
4
  [![license](https://img.shields.io/npm/l/consulti-mcp.svg)](./LICENSE)
5
5
 
6
- MCP server for the Consulti lead intelligence API — **10 stable tools** to search 500M+ B2B leads, search Instagram profiles, verify emails (including catch-all mailbox resolution), enrich leads by email or LinkedIn URL, manage saved lists, and check credit balance.
6
+ MCP server for the Consulti lead intelligence API — **14 stable tools** to search 500M+ B2B leads, search Instagram profiles, verify emails (including catch-all mailbox resolution), enrich leads by email or LinkedIn URL, manage saved lists, run inbox placement tests, and check credit balance.
7
7
 
8
8
  > **Stable surface only.** Beta endpoints (name-domain lookup, local-business search, creator search) are intentionally NOT exposed via MCP — their schemas may change. The REST local-business search accepts US states, DC, and Canadian provinces/territories by full name or two-letter code. To use beta endpoints, call the REST API directly: https://www.consulti.ai/api-docs
9
9
 
@@ -70,9 +70,9 @@ Verify if an email address is valid and deliverable.
70
70
 
71
71
  ### verify_catchall
72
72
 
73
- Resolve whether a specific mailbox on a catch-all domain actually exists — the ESP-engine probe that plain SMTP (`verify_email`) cannot do. Use it on addresses `verify_email` returns with `is_catch_all: true`.
73
+ Resolve whether a specific mailbox on a catch-all domain actually exists — the ESP-engine probe that plain SMTP (`verify_email`) cannot do. Use it on addresses `verify_email` returns with `is_catch_all: true`. A call usually answers within about 50 seconds and can run for up to 300, and the client's timeout is longer than that. A 503 `verifier_unavailable` means no verdict in time, with the credits refunded; a 500 `refund_unconfirmed` means the refund could not be confirmed, so check credits before retrying.
74
74
 
75
- **Cost:** 5 verification credits per call (charged on success, including cache hits; refunded on a 500). Requires a plan with catch-all verification enabled (Pro or higher).
75
+ **Cost:** 5 verification credits per call (charged on success, including cache hits; refunded on a 503 `verifier_unavailable`). A 500 is not always refunded: `refund_unconfirmed` means the refund could not be confirmed, and a 500 raised after the verdict was reached can stay billed, so check credits before retrying any 500. Requires a plan with catch-all verification enabled (Pro or higher).
76
76
 
77
77
  | Input | Type | Description |
78
78
  | ------- | ------ | ------------------------------------------------- |
@@ -258,6 +258,43 @@ Check the authenticated user's current lead and verification credit balance. Fre
258
258
  }
259
259
  ```
260
260
 
261
+ ### create_placement_test
262
+
263
+ Create an inbox placement test. Checking starts at create. Send one email from the mailbox you want to test to every seed address within 15 minutes, with the returned `test_code` in the subject or body, then poll `get_placement_test`.
264
+
265
+ **Cost:** 1 lead credit, charged when the test is created. Requires the Pro plan or higher. A retried call creates, and charges for, a new test. `Idempotency-Key` has no effect. A 429 `too_many_open_tests` is free and safe to retry after `retry_after`.
266
+
267
+ | Input | Type | Description |
268
+ | --------- | ------ | -------------------------------------------------------- |
269
+ | `name` | string | Optional label (max 120 characters) |
270
+ | `subject` | string | Optional subject of the email you will send (max 998) |
271
+ | `body` | string | Optional body of the email you will send (max 100,000) |
272
+
273
+ ### mark_placement_test_sent
274
+
275
+ Start checking a test that was created as a draft, after the email has gone out. On a test that is already checking it changes nothing. Free.
276
+
277
+ | Input | Type | Description |
278
+ | ----- | ------ | ---------------------------- |
279
+ | `id` | string | **Required.** The test id |
280
+
281
+ ### get_placement_test
282
+
283
+ Status, per-seed placement, summary, 0 to 10 score and report for one test. Free.
284
+
285
+ | Input | Type | Description |
286
+ | ----- | ------ | ---------------------------- |
287
+ | `id` | string | **Required.** The test id |
288
+
289
+ ### list_placement_tests
290
+
291
+ List your placement tests, newest first. Free.
292
+
293
+ | Input | Type | Description |
294
+ | ------ | ------ | ---------------------------------- |
295
+ | `page` | number | Page number, from 1 (default 1) |
296
+ | `size` | number | Tests per page, 1 to 100 (default 25) |
297
+
261
298
  ## Get your API key
262
299
 
263
300
  Sign up at [www.consulti.ai](https://www.consulti.ai) and generate an API key under **Settings → Integrations → API Keys**.
@@ -269,7 +306,7 @@ Sign up at [www.consulti.ai](https://www.consulti.ai) and generate an API key un
269
306
  | `CONSULTI_API_KEY` | **Yes** | — | Your Consulti API key (starts with `capi_`). |
270
307
  | `MCP_BASE_URL` | No | `https://www.consulti.ai/api/v1` | Override the API base URL. Only set this for staging / local dev — never in prod. |
271
308
 
272
- The server enforces a 30-second timeout on every API request; timed-out calls return a structured `{"error": "Request timed out after 30s"}` so MCP clients can parse and retry.
309
+ The server waits up to 130 seconds for `search_b2b_leads` and 310 seconds for every other call, so it never gives up before the API does. Failed calls return a structured error with `status`, `code` and `retry_after` when known. A timeout or a 5xx on a paid call may still have been charged, so the error says to call `get_credits` before retrying.
273
310
 
274
311
  ## Versioning
275
312
 
package/dist/index.js CHANGED
@@ -1,6 +1,7 @@
1
1
  #!/usr/bin/env node
2
2
  import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
3
3
  import { VERSION, createConsultiMcpServer } from "./server.js";
4
+ import { createApi } from "./transport.js";
4
5
  if (process.argv.includes("--version") || process.argv.includes("-v")) {
5
6
  console.log(VERSION);
6
7
  process.exit(0);
@@ -12,75 +13,7 @@ if (!CONSULTI_API_KEY) {
12
13
  }
13
14
  const BASE_URL = process.env.MCP_BASE_URL || "https://www.consulti.ai/api/v1";
14
15
  const USER_AGENT = `consulti-mcp/${VERSION}`;
15
- const REQUEST_TIMEOUT_MS = 30_000;
16
- async function apiPost(path, body) {
17
- const controller = new AbortController();
18
- const timer = setTimeout(() => controller.abort(), REQUEST_TIMEOUT_MS);
19
- try {
20
- const response = await fetch(`${BASE_URL}${path}`, {
21
- method: "POST",
22
- headers: {
23
- "Authorization": `Bearer ${CONSULTI_API_KEY}`,
24
- "Content-Type": "application/json",
25
- "User-Agent": USER_AGENT,
26
- },
27
- body: JSON.stringify(body),
28
- signal: controller.signal,
29
- });
30
- const data = await response.json();
31
- if (!response.ok) {
32
- const message = data?.error || data?.message || `API returned ${response.status}`;
33
- // Preserve the machine-readable code when the API sends one. An agent
34
- // can only branch on a code that survives this wrapper, and collapsing
35
- // every failure to prose forces it to pattern-match on wording.
36
- return JSON.stringify(data?.code ? { error: message, code: data.code } : { error: message }, null, 2);
37
- }
38
- return JSON.stringify(data, null, 2);
39
- }
40
- catch (error) {
41
- if (error instanceof Error && error.name === "AbortError") {
42
- return JSON.stringify({ error: `Request timed out after ${REQUEST_TIMEOUT_MS / 1000}s` }, null, 2);
43
- }
44
- const message = error instanceof Error ? error.message : "Unknown error";
45
- return JSON.stringify({ error: `Request failed: ${message}` }, null, 2);
46
- }
47
- finally {
48
- clearTimeout(timer);
49
- }
50
- }
51
- async function apiGet(path) {
52
- const controller = new AbortController();
53
- const timer = setTimeout(() => controller.abort(), REQUEST_TIMEOUT_MS);
54
- try {
55
- const response = await fetch(`${BASE_URL}${path}`, {
56
- method: "GET",
57
- headers: {
58
- "Authorization": `Bearer ${CONSULTI_API_KEY}`,
59
- "User-Agent": USER_AGENT,
60
- },
61
- signal: controller.signal,
62
- });
63
- const data = await response.json();
64
- if (!response.ok) {
65
- const message = data?.error || data?.message || `API returned ${response.status}`;
66
- // Preserve the machine-readable code when the API sends one. An agent
67
- // can only branch on a code that survives this wrapper, and collapsing
68
- // every failure to prose forces it to pattern-match on wording.
69
- return JSON.stringify(data?.code ? { error: message, code: data.code } : { error: message }, null, 2);
70
- }
71
- return JSON.stringify(data, null, 2);
72
- }
73
- catch (error) {
74
- if (error instanceof Error && error.name === "AbortError") {
75
- return JSON.stringify({ error: `Request timed out after ${REQUEST_TIMEOUT_MS / 1000}s` }, null, 2);
76
- }
77
- const message = error instanceof Error ? error.message : "Unknown error";
78
- return JSON.stringify({ error: `Request failed: ${message}` }, null, 2);
79
- }
80
- finally {
81
- clearTimeout(timer);
82
- }
83
- }
16
+ const { apiPost, apiGet } = createApi({ baseUrl: BASE_URL, apiKey: CONSULTI_API_KEY, userAgent: USER_AGENT });
84
17
  const server = createConsultiMcpServer({ apiPost, apiGet });
85
18
  async function main() {
86
19
  const transport = new StdioServerTransport();
package/dist/server.d.ts CHANGED
@@ -1,5 +1,5 @@
1
1
  import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
2
- export declare const VERSION = "2.5.0";
2
+ export declare const VERSION = "2.6.1";
3
3
  export type ConsultiMcpApiPost = (path: string, body: Record<string, unknown>) => Promise<string>;
4
4
  export type ConsultiMcpApiGet = (path: string) => Promise<string>;
5
5
  /**
package/dist/server.js CHANGED
@@ -1,7 +1,7 @@
1
1
  import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
2
2
  import { z } from "zod";
3
3
  import { handleSearchB2bLeads, searchB2bLeadsInputObjectSchema } from "./leads-search.js";
4
- export const VERSION = "2.5.0";
4
+ export const VERSION = "2.6.1";
5
5
  /**
6
6
  * Build the Consulti MCP server with every stable tool registered.
7
7
  * Import-safe: does not connect a transport, read env, or start stdio.
@@ -15,7 +15,7 @@ export function createConsultiMcpServer(options) {
15
15
  server.tool("verify_email", "Verify if an email address is valid and deliverable. Cost: 1 verification credit per call.", { email: z.string().describe("The email address to verify") }, async ({ email }) => ({
16
16
  content: [{ type: "text", text: await apiPost("/verify", { email }) }],
17
17
  }));
18
- server.tool("verify_catchall", "Resolve whether a specific mailbox on a catch-all domain actually exists — the ESP-engine probe that plain SMTP (verify_email) cannot do. Use it on addresses verify_email returns with is_catch_all=true. Cost: 5 verification credits per call; requires a plan with catch-all verification enabled (Pro or higher).", { email: z.string().describe("The email address on a catch-all domain to resolve") }, async ({ email }) => ({
18
+ server.tool("verify_catchall", "Resolve whether a specific mailbox on a catch-all domain actually exists — the ESP-engine probe that plain SMTP (verify_email) cannot do. Use it on addresses verify_email returns with is_catch_all=true. Cost: 5 verification credits per call; requires a plan with catch-all verification enabled (Pro or higher). A call usually answers within about 50 seconds and can run for up to 300; this client waits longer than that. A 503 verifier_unavailable means no verdict in time and the credits were refunded; a 500 refund_unconfirmed means the refund could not be confirmed, so check get_credits before retrying.", { email: z.string().describe("The email address on a catch-all domain to resolve") }, async ({ email }) => ({
19
19
  content: [{ type: "text", text: await apiPost("/verify/catchall", { email }) }],
20
20
  }));
21
21
  server.tool("enrich_lead", "Enrich a lead's full profile using their email address, including company-level funding, traffic, HQ, followers, and specialties when the lead is linked to a company. Cost: 1 lead credit — only deducted on a successful match; 404 responses are free.", { email: z.string().describe("The email address of the lead to enrich") }, async ({ email }) => ({
@@ -25,11 +25,11 @@ export function createConsultiMcpServer(options) {
25
25
  content: [{ type: "text", text: await apiPost("/enrich/linkedin", { linkedin_url }) }],
26
26
  }));
27
27
  server.registerTool("search_b2b_leads", {
28
- description: "Search a database of 500M+ B2B leads with filters like job title, industry, location, and company size. Country and state/region alias-group members are equivalent, so names and codes return identical populations. Results are always restricted to leads carrying our verified email label (there is no option to include unverified leads). Cost: 1 lead credit per result returned — reserved up to `size` then refunded down to the actual row count; 0 results = 0 credits. Call get_credits first before large `size` values.",
28
+ description: "Search a database of B2B leads with filters like job title, industry, location, and company size. Country and state/region alias-group members are equivalent, so names and codes return identical populations. Results are always restricted to leads carrying our verified email label (there is no option to include unverified leads). Cost: 1 lead credit per result returned — reserved up to `size` then refunded down to the actual row count; 0 results = 0 credits. Call get_credits first before large `size` values.",
29
29
  inputSchema: searchB2bLeadsInputObjectSchema,
30
30
  }, async (params) => handleSearchB2bLeads(params, apiPost));
31
31
  server.tool("search_instagram_profiles", "Search a database of Instagram profiles with filters like follower count, category, location, and data quality. Cost: 1 lead credit per result returned — reserved up to `size` then refunded down to the actual row count; 0 results = 0 credits. Call get_credits first before large operations.", {
32
- q: z.string().optional().describe("Free text search across username and bio"),
32
+ q: z.string().optional().describe("Case-insensitive text match on username or full name"),
33
33
  bioKeywords: z.array(z.string()).optional().describe("Keywords to search for in profile bios"),
34
34
  excludeKeywords: z.array(z.string()).optional().describe("Exclude profiles whose bio matches any of these keywords"),
35
35
  excludeAdultContent: z.boolean().optional().describe("Exclude profiles with adult/sexual content terms in their bio"),
@@ -47,6 +47,7 @@ export function createConsultiMcpServer(options) {
47
47
  hasPhone: z.boolean().optional().describe("Filter to only accounts with phone number"),
48
48
  hasWebsite: z.boolean().optional().describe("Filter to only accounts with website"),
49
49
  countries: z.array(z.string()).optional().describe("Countries to filter by (exact match). Canonical list: GET https://www.consulti.ai/api/v1/meta/instagram-countries"),
50
+ excludeListId: z.string().optional().describe("UUID of an INSTAGRAM-kind saved list owned by the API key holder. Profiles on it are removed before billing, so they cost nothing. Another kind, an unknown list or someone else's list returns HTTP 400, a list over 100,000 members returns 422, and a temporary lookup failure returns 503, all before anything is charged (get_lists reports each list's kind). With it the response adds `total_after_exclusion`; both totals then count up to 10001 and can be null on a timeout, so paginate on has_more."),
50
51
  sortBy: z.string().optional().describe("Field to sort by (followers, posts, engagement, username)"),
51
52
  sortOrder: z.string().optional().describe("Sort order (asc or desc)"),
52
53
  page: z.number().optional().describe("Page number (default: 1)"),
@@ -89,6 +90,10 @@ export function createConsultiMcpServer(options) {
89
90
  body.hasWebsite = params.hasWebsite;
90
91
  if (params.countries)
91
92
  body.countries = params.countries;
93
+ // !== undefined, not truthiness: a blank id must reach the API and get its
94
+ // 400 rather than silently running (and billing) an unexcluded search.
95
+ if (params.excludeListId !== undefined)
96
+ body.excludeListId = params.excludeListId;
92
97
  if (params.sortBy)
93
98
  body.sortBy = params.sortBy;
94
99
  if (params.sortOrder)
@@ -125,7 +130,7 @@ export function createConsultiMcpServer(options) {
125
130
  content: [{ type: "text", text: await apiPost("/lists", body) }],
126
131
  };
127
132
  });
128
- server.tool("add_leads_to_list", "Add members to a saved list. Send 'emails' to a list with kind='lead', or 'businessIds' to a list with kind='business'. Send only one of the two per call. Adding members whose type does not match the list's kind produces a list that cannot be opened or exported, so create the list with the matching kind first.", {
133
+ server.tool("add_leads_to_list", "Add members to a saved list. Send 'emails' to a list with kind='lead', or 'businessIds' to a list with kind='business'. Send only one array per call. Email saves are free. Business saves cost 1 lead credit per newly unlocked business with usable email data. Already unlocked IDs, including successful paid local search results, cost no additional credits. Check credits_used and already_unlocked in the response.", {
129
134
  listId: z.string().describe("UUID of the target list"),
130
135
  emails: z
131
136
  .array(z.string())
@@ -148,5 +153,41 @@ export function createConsultiMcpServer(options) {
148
153
  server.tool("get_credits", "Check the authenticated user's current lead and verification credit balance. Free — no credits deducted. Use before bulk operations to avoid running out mid-task.", {}, async () => ({
149
154
  content: [{ type: "text", text: await apiGet("/credits") }],
150
155
  }));
156
+ server.tool("create_placement_test", "Create an inbox placement test. Checking starts when the test is created: send one email from the mailbox you want to test to every address in seed_addresses within 15 minutes, with the test_code anywhere in the subject or the body, then poll get_placement_test. Results usually arrive within a few minutes of sending. Cost: 1 lead credit per test, charged when the test is created and refunded if creation fails; requires the Pro plan or higher. A retried call creates, and charges for, a new test: an Idempotency-Key header has no effect at present, so check list_placement_tests before retrying instead of repeating the call. At most 3 tests can be checking at once; another create returns 429 with code too_many_open_tests and retry_after, is not charged, and is safe to retry after that many seconds. If the response says status \"draft\", the test could not be started: call mark_placement_test_sent after sending.", {
157
+ name: z.string().optional().describe("Optional label for the test (max 120 characters). Defaults to the subject."),
158
+ subject: z.string().optional().describe("Optional subject of the email you will send (max 998 characters). Used for the content check when no seed returns a body."),
159
+ body: z.string().optional().describe("Optional body of the email you will send (max 100,000 characters), for the same purpose."),
160
+ }, async ({ name, subject, body }) => {
161
+ const payload = {};
162
+ if (name !== undefined)
163
+ payload.name = name;
164
+ if (subject !== undefined)
165
+ payload.subject = subject;
166
+ if (body !== undefined)
167
+ payload.body = body;
168
+ return {
169
+ content: [{ type: "text", text: await apiPost("/placement-tests", payload) }],
170
+ };
171
+ });
172
+ server.tool("mark_placement_test_sent", "Start checking a placement test that create_placement_test returned with status \"draft\", once the email has gone out. Optional: a test created through the API is already checking, and calling this on a checking test changes nothing. A completed test returns 409 already_finished. Free; the test was charged when it was created.", { id: z.string().describe("The test id returned by create_placement_test") }, async ({ id }) => ({
173
+ content: [{ type: "text", text: await apiPost(`/placement-tests/${encodeURIComponent(id)}/sent`, {}) }],
174
+ }));
175
+ server.tool("get_placement_test", "Get a placement test: status, where the email landed for each seed (inbox, spam, promotions and other tabs, not_found), the SPF, DKIM and DMARC verdicts, a summary, and the 0 to 10 score and full report once built. A test can complete before expires_at and still correct a missing seed until then; results are final at expires_at. Another account's test, or an unknown id, returns 404. Free.", { id: z.string().describe("The test id returned by create_placement_test") }, async ({ id }) => ({
176
+ content: [{ type: "text", text: await apiGet(`/placement-tests/${encodeURIComponent(id)}`) }],
177
+ }));
178
+ server.tool("list_placement_tests", "List your placement tests, newest first. Only tests your account created are listed. Free.", {
179
+ page: z.number().optional().describe("Page number, from 1 (default 1)"),
180
+ size: z.number().optional().describe("Tests per page, 1 to 100 (default 25)"),
181
+ }, async ({ page, size }) => {
182
+ const query = new URLSearchParams();
183
+ if (page !== undefined)
184
+ query.set("page", String(page));
185
+ if (size !== undefined)
186
+ query.set("size", String(size));
187
+ const qs = query.toString();
188
+ return {
189
+ content: [{ type: "text", text: await apiGet(`/placement-tests${qs ? `?${qs}` : ""}`) }],
190
+ };
191
+ });
151
192
  return server;
152
193
  }
@@ -0,0 +1,21 @@
1
+ /**
2
+ * Per-route client timeouts, keyed by path template. The client must outlast the route's
3
+ * maxDuration, otherwise it aborts while the server is still working and bills, and a
4
+ * retry then charges again. /leads/search runs for up to 120 s; /verify/catchall answers
5
+ * within about 50 s and caps at 300 s; a route that exports no maxDuration runs under
6
+ * Vercel's 300 s default.
7
+ */
8
+ export declare const TOOL_TIMEOUT_MS: Record<string, number>;
9
+ export declare const DEFAULT_TIMEOUT_MS = 310000;
10
+ /** Timeout for a request path. Query strings are ignored. */
11
+ export declare function timeoutFor(path: string): number;
12
+ export interface ApiOptions {
13
+ baseUrl: string;
14
+ apiKey: string;
15
+ userAgent: string;
16
+ fetchImpl?: typeof fetch;
17
+ }
18
+ export declare function createApi(options: ApiOptions): {
19
+ apiPost: (path: string, body: Record<string, unknown>) => Promise<string>;
20
+ apiGet: (path: string) => Promise<string>;
21
+ };
@@ -0,0 +1,119 @@
1
+ // HTTP transport for the MCP server. Import-safe: no env reads, no process.exit, no stdio.
2
+ /**
3
+ * Per-route client timeouts, keyed by path template. The client must outlast the route's
4
+ * maxDuration, otherwise it aborts while the server is still working and bills, and a
5
+ * retry then charges again. /leads/search runs for up to 120 s; /verify/catchall answers
6
+ * within about 50 s and caps at 300 s; a route that exports no maxDuration runs under
7
+ * Vercel's 300 s default.
8
+ */
9
+ export const TOOL_TIMEOUT_MS = {
10
+ "/leads/search": 130_000,
11
+ };
12
+ export const DEFAULT_TIMEOUT_MS = 310_000;
13
+ /** Timeout for a request path. Query strings are ignored. */
14
+ export function timeoutFor(path) {
15
+ return TOOL_TIMEOUT_MS[path.split("?")[0]] ?? DEFAULT_TIMEOUT_MS;
16
+ }
17
+ /** False for the calls that never debit credits: balance, lists, and placement reads and /sent. */
18
+ function isBillable(method, path) {
19
+ const p = path.split("?")[0];
20
+ if (p === "/credits" || p === "/lists")
21
+ return false;
22
+ if (/^\/placement-tests\/[^/]+\/sent$/.test(p))
23
+ return false;
24
+ if (method === "GET" && p.startsWith("/placement-tests"))
25
+ return false;
26
+ return true;
27
+ }
28
+ const BILLED_HINT = "The request may still have been billed. Call get_credits before retrying.";
29
+ function retryAfterFrom(header, body) {
30
+ const fromHeader = header === null || header.trim() === "" ? NaN : Number(header);
31
+ if (Number.isFinite(fromHeader))
32
+ return fromHeader;
33
+ const fromBody = body?.retry_after;
34
+ return typeof fromBody === "number" && Number.isFinite(fromBody) ? fromBody : undefined;
35
+ }
36
+ function nonJsonCode(status) {
37
+ if (status === 403 || status === 429)
38
+ return "blocked";
39
+ if (status === 502 || status === 504)
40
+ return "gateway_timeout";
41
+ return "non_json";
42
+ }
43
+ export function createApi(options) {
44
+ const { baseUrl, apiKey, userAgent } = options;
45
+ const fetchImpl = options.fetchImpl ?? fetch;
46
+ async function request(method, path, body) {
47
+ const timeoutMs = timeoutFor(path);
48
+ const billable = isBillable(method, path);
49
+ const controller = new AbortController();
50
+ const timer = setTimeout(() => controller.abort(), timeoutMs);
51
+ const fail = (fields) => JSON.stringify(fields, null, 2);
52
+ try {
53
+ const response = await fetchImpl(`${baseUrl}${path}`, {
54
+ method,
55
+ headers: {
56
+ "Authorization": `Bearer ${apiKey}`,
57
+ ...(method === "POST" ? { "Content-Type": "application/json" } : {}),
58
+ "User-Agent": userAgent,
59
+ },
60
+ ...(method === "POST" ? { body: JSON.stringify(body ?? {}) } : {}),
61
+ signal: controller.signal,
62
+ });
63
+ const text = await response.text();
64
+ let data;
65
+ try {
66
+ const parsed = JSON.parse(text);
67
+ if (parsed !== null && typeof parsed === "object")
68
+ data = parsed;
69
+ }
70
+ catch {
71
+ // Not JSON: a firewall challenge, a platform error page or a plain-text body.
72
+ }
73
+ if (response.ok && data)
74
+ return JSON.stringify(data, null, 2);
75
+ const status = response.status;
76
+ const retryAfter = retryAfterFrom(response.headers.get("Retry-After"), data);
77
+ // A 503 that reports credits_used 0 was sent only after a confirmed refund. A 2xx that
78
+ // reached here has an unreadable body, so the route may have charged without our seeing it.
79
+ const refunded = status === 503 && data?.credits_used === 0;
80
+ const maybeBilled = billable && ((status >= 500 && !refunded) || response.ok);
81
+ if (!data) {
82
+ return fail({
83
+ error: `API returned ${status} with a non-JSON body`,
84
+ code: nonJsonCode(status),
85
+ status,
86
+ ...(retryAfter !== undefined ? { retry_after: retryAfter } : {}),
87
+ body_snippet: text.slice(0, 200),
88
+ ...(maybeBilled ? { hint: BILLED_HINT } : {}),
89
+ });
90
+ }
91
+ // Keep status, code and retry_after: an agent can only tell a retryable failure from a final one
92
+ // if they survive this wrapper, and collapsing every failure to prose forces it to match on wording.
93
+ const message = data.error || data.message || `API returned ${status}`;
94
+ return fail({
95
+ error: message,
96
+ ...(data.code ? { code: data.code } : {}),
97
+ status,
98
+ ...(retryAfter !== undefined ? { retry_after: retryAfter } : {}),
99
+ ...(data.credits_used !== undefined ? { credits_used: data.credits_used } : {}),
100
+ ...(maybeBilled ? { hint: BILLED_HINT } : {}),
101
+ });
102
+ }
103
+ catch (error) {
104
+ const hint = billable ? { hint: BILLED_HINT } : {};
105
+ if (error instanceof Error && error.name === "AbortError") {
106
+ return fail({ error: `Request timed out after ${timeoutMs / 1000}s`, code: "timeout", ...hint });
107
+ }
108
+ const message = error instanceof Error ? error.message : "Unknown error";
109
+ return fail({ error: `Request failed: ${message}`, code: "network_error", ...hint });
110
+ }
111
+ finally {
112
+ clearTimeout(timer);
113
+ }
114
+ }
115
+ return {
116
+ apiPost: (path, body) => request("POST", path, body),
117
+ apiGet: (path) => request("GET", path),
118
+ };
119
+ }
package/package.json CHANGED
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "name": "consulti-mcp",
3
- "version": "2.5.0",
4
- "description": "Consulti.ai MCP server — 10 stable tools for email verification (incl. catch-all mailbox resolution), B2B lead search/enrichment, LinkedIn-URL enrichment, Instagram profile search, list management, and credit-balance checks. Stable surface only; beta endpoints are not exposed via MCP. Compatible with Claude Desktop, Cursor, and any MCP client.",
3
+ "version": "2.6.1",
4
+ "description": "Consulti.ai MCP server — 14 stable tools for email verification (incl. catch-all mailbox resolution), B2B lead search/enrichment, LinkedIn-URL enrichment, Instagram profile search, list management, inbox placement tests, and credit-balance checks. Stable surface only; beta endpoints are not exposed via MCP. Compatible with Claude Desktop, Cursor, and any MCP client.",
5
5
  "type": "module",
6
6
  "bin": {
7
7
  "consulti-mcp": "dist/index.js"