consulti-mcp 2.1.0 → 2.3.0

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.
Files changed (3) hide show
  1. package/README.md +36 -6
  2. package/dist/index.js +11 -5
  3. package/package.json +2 -2
package/README.md CHANGED
@@ -3,9 +3,9 @@
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 — **8 stable tools** to search 500M+ B2B leads, verify emails, enrich leads by email or LinkedIn URL, manage saved lists, and check credit balance.
6
+ MCP server for the Consulti lead intelligence API — **9 stable tools** to search 500M+ B2B leads, verify emails (including catch-all mailbox resolution), enrich leads by email or LinkedIn URL, manage saved lists, and check credit balance.
7
7
 
8
- > **Stable surface only.** Beta endpoints (LinkedIn cache-only lookup `find-by-linkedin`, name-domain lookup, local-business search, creator search) are intentionally NOT exposed via MCP — their schemas may change. To use them, call the REST API directly: https://www.consulti.ai/api-docs
8
+ > **Stable surface only.** Beta endpoints (name-domain lookup, local-business search, creator search) are intentionally NOT exposed via MCP — their schemas may change. To use them, call the REST API directly: https://www.consulti.ai/api-docs
9
9
 
10
10
  ## Installation
11
11
 
@@ -68,6 +68,36 @@ Verify if an email address is valid and deliverable.
68
68
  { "email": "john@example.com" }
69
69
  ```
70
70
 
71
+ ### verify_catchall
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`.
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).
76
+
77
+ | Input | Type | Description |
78
+ | ------- | ------ | ------------------------------------------------- |
79
+ | `email` | string | The email address on a catch-all domain to resolve |
80
+
81
+ **Example:**
82
+ ```json
83
+ { "email": "john@catchall-domain.com" }
84
+ ```
85
+
86
+ **Response shape:**
87
+ ```json
88
+ {
89
+ "success": true,
90
+ "data": {
91
+ "email": "john@catchall-domain.com",
92
+ "status": "good",
93
+ "is_catch_all": true,
94
+ "catch_all_verification": { "score": 95, "status": "Deliverable", "provider": "consulti" },
95
+ "credits_used": 5,
96
+ "cached": false
97
+ }
98
+ }
99
+ ```
100
+
71
101
  ### enrich_lead
72
102
 
73
103
  Enrich a lead's full profile using their email address.
@@ -100,7 +130,7 @@ Enrich a person by their LinkedIn profile URL → a verified work email plus the
100
130
 
101
131
  ### search_b2b_leads
102
132
 
103
- Search a database of 500M+ B2B leads with filters like job title, industry, location, and company size. All inputs are optional.
133
+ Search a database of 500M+ B2B leads with filters like job title, industry, location, and company size. All inputs are optional. Results are always restricted to leads carrying our verified email label — there is no option to include unverified leads.
104
134
 
105
135
  **Cost:** 1 lead credit per result returned. Credits are reserved up to `size` then refunded down to the actual row count; 0 results = 0 credits. Call `get_credits` first before using large `size` values.
106
136
 
@@ -109,13 +139,14 @@ Search a database of 500M+ B2B leads with filters like job title, industry, loca
109
139
  | `q` | string | Free text search across name, title, company, and industry |
110
140
  | `titles` | string[] | Job titles to filter by (e.g. ["CEO", "VP Marketing"]) |
111
141
  | `industries` | string[] | Industries to filter by (e.g. ["Technology", "Finance"]) |
142
+ | `technologies` | string[] | Website tech, exact Wappalyzer-style names (e.g. ["Shopify"]); OR-matched. Canonical list: `GET /api/v1/meta/technologies` |
143
+ | `excludeTechnologies` | string[] | Website tech to EXCLUDE (same names). A lead is dropped if its company uses ANY listed tech; leads with no technology data are kept |
112
144
  | `countries` | string[] | Countries to filter by (e.g. ["United States"]) |
113
145
  | `states` | string[] | States/regions to filter by (e.g. ["California"]) |
114
146
  | `cities` | string[] | Cities to filter by (e.g. ["San Francisco"]) |
115
147
  | `company` | string | Company name to search for |
116
148
  | `empMin` | number | Minimum employee count |
117
149
  | `empMax` | number | Maximum employee count |
118
- | `emailStatus` | string | One of `good`, `valid`, `risky`, `bad`, `invalid`, `unknown`, `verified`, `all` (default: `all`). `verified` is a legacy alias retained for backward compatibility. Canonical list: `GET https://www.consulti.ai/api/v1/meta/email-statuses` |
119
150
  | `excludeListId` | string | UUID of a saved list owned by the API key holder — leads in this list will be excluded from results. Canonical singular field name; `exclude_list_id` and other variants return HTTP 400. |
120
151
  | `page` | number | Page number (default: 1) |
121
152
  | `size` | number | Results per page (default: 25, max: 100) |
@@ -132,7 +163,6 @@ Search a database of 500M+ B2B leads with filters like job title, industry, loca
132
163
  "countries": ["United States"],
133
164
  "empMin": 50,
134
165
  "empMax": 500,
135
- "emailStatus": "verified",
136
166
  "excludeListId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
137
167
  "size": 25
138
168
  }
@@ -220,7 +250,7 @@ Print the installed version:
220
250
 
221
251
  ```bash
222
252
  npx -y consulti-mcp --version
223
- # → 2.1.0
253
+ # → 2.3.0
224
254
  ```
225
255
 
226
256
  Releases are published to npm via [GitHub Actions trusted publishing](https://docs.npmjs.com/trusted-publishers) on tags matching `mcp-v*` — each release carries an [npm provenance attestation](https://docs.npmjs.com/generating-provenance-statements).
package/dist/index.js CHANGED
@@ -2,7 +2,7 @@
2
2
  import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
3
3
  import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
4
4
  import { z } from "zod";
5
- const VERSION = "2.1.0";
5
+ const VERSION = "2.3.0";
6
6
  if (process.argv.includes("--version") || process.argv.includes("-v")) {
7
7
  console.log(VERSION);
8
8
  process.exit(0);
@@ -84,23 +84,27 @@ const server = new McpServer({
84
84
  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 }) => ({
85
85
  content: [{ type: "text", text: await apiPost("/verify", { email }) }],
86
86
  }));
87
+ 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 }) => ({
88
+ content: [{ type: "text", text: await apiPost("/verify/catchall", { email }) }],
89
+ }));
87
90
  server.tool("enrich_lead", "Enrich a lead's full profile using their email address. 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 }) => ({
88
91
  content: [{ type: "text", text: await apiPost("/leads/enrich", { email }) }],
89
92
  }));
90
93
  server.tool("enrich_linkedin", "Enrich a person by their LinkedIn profile URL → a verified work email plus their US mobile phone (free add-on). Cache-first: served instantly when we already hold a verified email for that profile, otherwise enriched live and cached. Cost: 1 lead credit — charged ONLY when an email is returned; phone-only or no-match responses are free.", { linkedin_url: z.string().describe("The LinkedIn profile URL, e.g. https://linkedin.com/in/johndoe") }, async ({ linkedin_url }) => ({
91
94
  content: [{ type: "text", text: await apiPost("/enrich/linkedin", { linkedin_url }) }],
92
95
  }));
93
- server.tool("search_b2b_leads", "Search a database of 500M+ B2B leads with filters like job title, industry, location, and company size. 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.", {
96
+ server.tool("search_b2b_leads", "Search a database of 500M+ B2B leads with filters like job title, industry, location, and company size. 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.", {
94
97
  q: z.string().optional().describe("Free text search across name, title, company, and industry"),
95
98
  titles: z.array(z.string()).optional().describe("Job titles to filter by (e.g. [\"CEO\", \"VP Marketing\"])"),
96
99
  industries: z.array(z.string()).optional().describe("Industries to filter by (case-sensitive exact match). Get the canonical list: GET https://www.consulti.ai/api/v1/meta/industries"),
100
+ technologies: z.array(z.string()).optional().describe("Technologies the company's website uses, exact Wappalyzer-style names (e.g. [\"Shopify\", \"HubSpot\", \"WordPress\"]). OR-matched: a lead matches if it uses ANY listed technology. Canonical list: GET https://www.consulti.ai/api/v1/meta/technologies"),
101
+ excludeTechnologies: z.array(z.string()).optional().describe("Technologies to EXCLUDE, same Wappalyzer-style names. A lead is dropped if its company uses ANY listed technology; leads with no technology data are kept."),
97
102
  countries: z.array(z.string()).optional().describe("Countries to filter by (exact match). Canonical list: GET https://www.consulti.ai/api/v1/meta/countries"),
98
103
  states: z.array(z.string()).optional().describe("States/regions to filter by (exact match). Canonical list: GET https://www.consulti.ai/api/v1/meta/states"),
99
104
  cities: z.array(z.string()).optional().describe("Cities to filter by (e.g. [\"San Francisco\", \"London\"])"),
100
105
  company: z.string().optional().describe("Company name to search for"),
101
106
  empMin: z.number().optional().describe("Minimum employee count"),
102
107
  empMax: z.number().optional().describe("Maximum employee count"),
103
- emailStatus: z.enum(["good", "valid", "risky", "bad", "invalid", "unknown", "verified", "all"]).optional().describe("Filter by email verification status. 'all' (default) returns every status. 'verified' is a legacy alias retained for backward compatibility. Canonical list: GET https://www.consulti.ai/api/v1/meta/email-statuses"),
104
108
  excludeListId: z.string().optional().describe("UUID of a saved list owned by the API key holder — leads in this list will be excluded from results. Response includes both `total` (pre-exclusion) and `total_after_exclusion` (post) so the caller can verify exclusion fired."),
105
109
  page: z.number().optional().describe("Page number (default: 1)"),
106
110
  size: z.number().optional().describe("Results per page (default: 25, max: 100)"),
@@ -112,6 +116,10 @@ server.tool("search_b2b_leads", "Search a database of 500M+ B2B leads with filte
112
116
  body.titles = params.titles;
113
117
  if (params.industries)
114
118
  body.industries = params.industries;
119
+ if (params.technologies)
120
+ body.technologies = params.technologies;
121
+ if (params.excludeTechnologies)
122
+ body.excludeTechnologies = params.excludeTechnologies;
115
123
  if (params.countries)
116
124
  body.countries = params.countries;
117
125
  if (params.states)
@@ -124,8 +132,6 @@ server.tool("search_b2b_leads", "Search a database of 500M+ B2B leads with filte
124
132
  body.empMin = params.empMin;
125
133
  if (params.empMax !== undefined)
126
134
  body.empMax = params.empMax;
127
- if (params.emailStatus)
128
- body.emailStatus = params.emailStatus;
129
135
  if (params.excludeListId)
130
136
  body.excludeListId = params.excludeListId;
131
137
  if (params.page !== undefined)
package/package.json CHANGED
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "name": "consulti-mcp",
3
- "version": "2.1.0",
4
- "description": "Consulti.ai MCP server — 8 stable tools for email verification, B2B lead search/enrichment, LinkedIn-URL enrichment, 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.3.0",
4
+ "description": "Consulti.ai MCP server — 9 stable tools for email verification (incl. catch-all mailbox resolution), B2B lead search/enrichment, LinkedIn-URL enrichment, 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.",
5
5
  "type": "module",
6
6
  "bin": {
7
7
  "consulti-mcp": "dist/index.js"