consulti-mcp 2.4.0 → 2.4.2
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 +42 -16
- package/dist/index.js +40 -15
- package/package.json +5 -5
package/README.md
CHANGED
|
@@ -5,7 +5,7 @@
|
|
|
5
5
|
|
|
6
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.
|
|
7
7
|
|
|
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
|
|
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
|
|
|
10
10
|
## Installation
|
|
11
11
|
|
|
@@ -130,7 +130,7 @@ Enrich a person by their LinkedIn profile URL → a verified work email plus the
|
|
|
130
130
|
|
|
131
131
|
### search_b2b_leads
|
|
132
132
|
|
|
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.
|
|
133
|
+
Search a database of 500M+ B2B leads with filters like job title, industry, location, and company size. All inputs are optional. 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.
|
|
134
134
|
|
|
135
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.
|
|
136
136
|
|
|
@@ -141,8 +141,8 @@ Search a database of 500M+ B2B leads with filters like job title, industry, loca
|
|
|
141
141
|
| `industries` | string[] | Industries to filter by (e.g. ["Technology", "Finance"]) |
|
|
142
142
|
| `technologies` | string[] | Website tech, exact Wappalyzer-style names (e.g. ["Shopify"]); OR-matched. Canonical list: `GET /api/v1/meta/technologies` |
|
|
143
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 |
|
|
144
|
-
| `countries` | string[] |
|
|
145
|
-
| `states` | string[] |
|
|
144
|
+
| `countries` | string[] | Equivalent aliases match the same population (e.g. ["United States"] or ["US"]) |
|
|
145
|
+
| `states` | string[] | Equivalent aliases match the same population (e.g. ["Ontario"] or ["ON"]) |
|
|
146
146
|
| `cities` | string[] | Cities to filter by (e.g. ["San Francisco"]) |
|
|
147
147
|
| `company` | string | Company name to search for |
|
|
148
148
|
| `empMin` | number | Minimum employee count |
|
|
@@ -168,9 +168,25 @@ Search a database of 500M+ B2B leads with filters like job title, industry, loca
|
|
|
168
168
|
}
|
|
169
169
|
```
|
|
170
170
|
|
|
171
|
+
### List kinds
|
|
172
|
+
|
|
173
|
+
A saved list holds exactly one entity kind, recorded as `kind` on the list.
|
|
174
|
+
`kind` decides which identifier the list stores and which one every reader looks
|
|
175
|
+
for, so it must match what you add:
|
|
176
|
+
|
|
177
|
+
| `kind` | What you add to it | Where the members come from |
|
|
178
|
+
| ---------- | ------------------ | ------------------------------ |
|
|
179
|
+
| `lead` | `emails` | `search_b2b_leads` |
|
|
180
|
+
| `business` | `businessIds` | local business search (REST) |
|
|
181
|
+
|
|
182
|
+
Create the list with the kind you need. `kind` cannot be changed afterwards, and
|
|
183
|
+
adding `businessIds` to a `lead` list produces a list that cannot be opened or
|
|
184
|
+
exported.
|
|
185
|
+
|
|
171
186
|
### get_lists
|
|
172
187
|
|
|
173
|
-
Get all saved
|
|
188
|
+
Get all saved lists for the authenticated user, with member counts and each
|
|
189
|
+
list's kind. No inputs required.
|
|
174
190
|
|
|
175
191
|
**Example:**
|
|
176
192
|
```json
|
|
@@ -179,27 +195,37 @@ Get all saved lead lists for the authenticated user, with member counts. No inpu
|
|
|
179
195
|
|
|
180
196
|
### create_list
|
|
181
197
|
|
|
182
|
-
Create a new saved
|
|
198
|
+
Create a new saved list.
|
|
183
199
|
|
|
184
|
-
| Input | Type | Description
|
|
185
|
-
| ------------- | ------ |
|
|
186
|
-
| `name` | string | **Required.** Name of the list
|
|
187
|
-
| `description` | string | Optional description of the list
|
|
200
|
+
| Input | Type | Description |
|
|
201
|
+
| ------------- | ------ | --------------------------------------------------------------- |
|
|
202
|
+
| `name` | string | **Required.** Name of the list |
|
|
203
|
+
| `description` | string | Optional description of the list |
|
|
204
|
+
| `kind` | string | `lead` (default) or `business`. Podcast, YouTube and Instagram lists are created in the dashboard, because this package cannot add members to them. |
|
|
188
205
|
|
|
189
206
|
**Example:**
|
|
190
207
|
```json
|
|
191
208
|
{ "name": "Tech CEOs", "description": "CEOs at tech companies with 50-500 employees" }
|
|
192
209
|
```
|
|
193
210
|
|
|
211
|
+
**Example, for local businesses:**
|
|
212
|
+
```json
|
|
213
|
+
{ "name": "TX roofers", "kind": "business" }
|
|
214
|
+
```
|
|
215
|
+
|
|
194
216
|
### add_leads_to_list
|
|
195
217
|
|
|
196
|
-
Add
|
|
218
|
+
Add members to a saved list. Send `emails` to a `lead` list, or `businessIds` to
|
|
219
|
+
a `business` list. Send only one of the two per call.
|
|
220
|
+
|
|
221
|
+
| Input | Type | Description |
|
|
222
|
+
| ------------- | -------- | -------------------------------------------------------- |
|
|
223
|
+
| `listId` | string | **Required.** UUID of the target list |
|
|
224
|
+
| `emails` | string[] | Email addresses of B2B leads. Needs `kind: "lead"` |
|
|
225
|
+
| `businessIds` | number[] | Business IDs from local search. Needs `kind: "business"` |
|
|
197
226
|
|
|
198
|
-
|
|
199
|
-
|
|
200
|
-
| `listId` | string | **Required.** UUID of the target list |
|
|
201
|
-
| `emails` | string[] | Email addresses of B2B leads to add |
|
|
202
|
-
| `businessIds` | number[] | Business IDs of local leads to add |
|
|
227
|
+
A payload that does not match the list's kind produces a list that cannot be
|
|
228
|
+
opened or exported. Match the kind.
|
|
203
229
|
|
|
204
230
|
**Example:**
|
|
205
231
|
```json
|
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.4.
|
|
5
|
+
const VERSION = "2.4.2";
|
|
6
6
|
if (process.argv.includes("--version") || process.argv.includes("-v")) {
|
|
7
7
|
console.log(VERSION);
|
|
8
8
|
process.exit(0);
|
|
@@ -32,7 +32,10 @@ async function apiPost(path, body) {
|
|
|
32
32
|
const data = await response.json();
|
|
33
33
|
if (!response.ok) {
|
|
34
34
|
const message = data?.error || data?.message || `API returned ${response.status}`;
|
|
35
|
-
|
|
35
|
+
// Preserve the machine-readable code when the API sends one. An agent
|
|
36
|
+
// can only branch on a code that survives this wrapper, and collapsing
|
|
37
|
+
// every failure to prose forces it to pattern-match on wording.
|
|
38
|
+
return JSON.stringify(data?.code ? { error: message, code: data.code } : { error: message }, null, 2);
|
|
36
39
|
}
|
|
37
40
|
return JSON.stringify(data, null, 2);
|
|
38
41
|
}
|
|
@@ -62,7 +65,10 @@ async function apiGet(path) {
|
|
|
62
65
|
const data = await response.json();
|
|
63
66
|
if (!response.ok) {
|
|
64
67
|
const message = data?.error || data?.message || `API returned ${response.status}`;
|
|
65
|
-
|
|
68
|
+
// Preserve the machine-readable code when the API sends one. An agent
|
|
69
|
+
// can only branch on a code that survives this wrapper, and collapsing
|
|
70
|
+
// every failure to prose forces it to pattern-match on wording.
|
|
71
|
+
return JSON.stringify(data?.code ? { error: message, code: data.code } : { error: message }, null, 2);
|
|
66
72
|
}
|
|
67
73
|
return JSON.stringify(data, null, 2);
|
|
68
74
|
}
|
|
@@ -93,14 +99,14 @@ server.tool("enrich_lead", "Enrich a lead's full profile using their email addre
|
|
|
93
99
|
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 }) => ({
|
|
94
100
|
content: [{ type: "text", text: await apiPost("/enrich/linkedin", { linkedin_url }) }],
|
|
95
101
|
}));
|
|
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.", {
|
|
102
|
+
server.tool("search_b2b_leads", "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.", {
|
|
97
103
|
q: z.string().optional().describe("Free text search across name, title, company, and industry"),
|
|
98
104
|
titles: z.array(z.string()).optional().describe("Job titles to filter by (e.g. [\"CEO\", \"VP Marketing\"])"),
|
|
99
105
|
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
106
|
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
107
|
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."),
|
|
102
|
-
countries: z.array(z.string()).optional().describe("Countries to filter by (
|
|
103
|
-
states: z.array(z.string()).optional().describe("States/regions to filter by (
|
|
108
|
+
countries: z.array(z.string()).optional().describe("Countries to filter by. Alias-group members are equivalent (e.g. \"United States\" and \"US\"). Accepted values: GET https://www.consulti.ai/api/v1/meta/countries"),
|
|
109
|
+
states: z.array(z.string()).optional().describe("States/regions to filter by. Alias-group members are equivalent (e.g. \"Ontario\" and \"ON\"). Accepted values: GET https://www.consulti.ai/api/v1/meta/states"),
|
|
104
110
|
cities: z.array(z.string()).optional().describe("Cities to filter by (e.g. [\"San Francisco\", \"London\"])"),
|
|
105
111
|
company: z.string().optional().describe("Company name to search for"),
|
|
106
112
|
empMin: z.number().optional().describe("Minimum employee count"),
|
|
@@ -153,10 +159,11 @@ server.tool("search_instagram_profiles", "Search a database of Instagram profile
|
|
|
153
159
|
followingMax: z.number().optional().describe("Maximum following count"),
|
|
154
160
|
postsMin: z.number().optional().describe("Minimum post count"),
|
|
155
161
|
postsMax: z.number().optional().describe("Maximum post count"),
|
|
156
|
-
categories: z.array(z.string()).optional().describe("Categories to filter by (e.g. [\"
|
|
157
|
-
accountTypes: z.array(z.string()).optional().describe("Account types to filter by (e.g. [\"business\", \"personal\"])"),
|
|
162
|
+
categories: z.array(z.string()).optional().describe("Categories to filter by (e.g. [\"Digital creator\", \"Photographer\"]). Canonical list: GET https://www.consulti.ai/api/v1/meta/instagram-categories"),
|
|
163
|
+
accountTypes: z.array(z.string()).optional().describe("Account types to filter by (e.g. [\"business\", \"personal\"]). Canonical list: GET https://www.consulti.ai/api/v1/meta/instagram-account-types"),
|
|
164
|
+
emailStatus: z.array(z.string()).optional().describe("Email verification status to filter by (e.g. [\"good\", \"risky\", \"bad\", \"catch_all\"]). Canonical list: GET https://www.consulti.ai/api/v1/meta/instagram-email-statuses"),
|
|
158
165
|
verified: z.boolean().optional().describe("Filter to only verified accounts"),
|
|
159
|
-
hasEmail: z.boolean().optional().describe("Filter to only accounts with
|
|
166
|
+
hasEmail: z.boolean().optional().describe("Filter to only accounts with an email on file"),
|
|
160
167
|
hasPhone: z.boolean().optional().describe("Filter to only accounts with phone number"),
|
|
161
168
|
hasWebsite: z.boolean().optional().describe("Filter to only accounts with website"),
|
|
162
169
|
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"),
|
|
@@ -190,6 +197,8 @@ server.tool("search_instagram_profiles", "Search a database of Instagram profile
|
|
|
190
197
|
body.categories = params.categories;
|
|
191
198
|
if (params.accountTypes)
|
|
192
199
|
body.accountTypes = params.accountTypes;
|
|
200
|
+
if (params.emailStatus)
|
|
201
|
+
body.emailStatus = params.emailStatus;
|
|
193
202
|
if (params.verified !== undefined)
|
|
194
203
|
body.verified = params.verified;
|
|
195
204
|
if (params.hasEmail !== undefined)
|
|
@@ -212,24 +221,40 @@ server.tool("search_instagram_profiles", "Search a database of Instagram profile
|
|
|
212
221
|
content: [{ type: "text", text: await apiPost("/instagram/search", body) }],
|
|
213
222
|
};
|
|
214
223
|
});
|
|
215
|
-
server.tool("get_lists", "Get all saved
|
|
224
|
+
server.tool("get_lists", "Get all saved lists for the authenticated user, with member counts and each list's kind", {}, async () => ({
|
|
216
225
|
content: [{ type: "text", text: await apiGet("/lists") }],
|
|
217
226
|
}));
|
|
218
|
-
server.tool("create_list", "Create a new saved lead list", {
|
|
227
|
+
server.tool("create_list", "Create a new saved list. A list holds exactly one entity kind. Use kind='lead' to store B2B lead emails and kind='business' to store local business IDs. Choose the kind that matches what you plan to add, because members cannot be added to a list of a different kind.", {
|
|
219
228
|
name: z.string().describe("Name of the list"),
|
|
220
229
|
description: z.string().optional().describe("Optional description of the list"),
|
|
221
|
-
|
|
230
|
+
// Only the two kinds add_leads_to_list can actually populate. Offering
|
|
231
|
+
// podcast, youtube, or instagram here would let an agent create a list it
|
|
232
|
+
// can never add a member to, because this package sends only emails or
|
|
233
|
+
// businessIds. Those kinds are created in the dashboard.
|
|
234
|
+
kind: z
|
|
235
|
+
.enum(["lead", "business"])
|
|
236
|
+
.optional()
|
|
237
|
+
.describe("Entity kind this list holds. Defaults to 'lead' for B2B emails. Use 'business' before adding businessIds from local business search."),
|
|
238
|
+
}, async ({ name, description, kind }) => {
|
|
222
239
|
const body = { name };
|
|
223
240
|
if (description)
|
|
224
241
|
body.description = description;
|
|
242
|
+
if (kind)
|
|
243
|
+
body.kind = kind;
|
|
225
244
|
return {
|
|
226
245
|
content: [{ type: "text", text: await apiPost("/lists", body) }],
|
|
227
246
|
};
|
|
228
247
|
});
|
|
229
|
-
server.tool("add_leads_to_list", "Add
|
|
248
|
+
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.", {
|
|
230
249
|
listId: z.string().describe("UUID of the target list"),
|
|
231
|
-
emails: z
|
|
232
|
-
|
|
250
|
+
emails: z
|
|
251
|
+
.array(z.string())
|
|
252
|
+
.optional()
|
|
253
|
+
.describe("Email addresses of B2B leads to add. Requires a list with kind='lead'."),
|
|
254
|
+
businessIds: z
|
|
255
|
+
.array(z.number())
|
|
256
|
+
.optional()
|
|
257
|
+
.describe("Business IDs from local business search. Requires a list with kind='business'."),
|
|
233
258
|
}, async ({ listId, emails, businessIds }) => {
|
|
234
259
|
const body = {};
|
|
235
260
|
if (emails)
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "consulti-mcp",
|
|
3
|
-
"version": "2.4.
|
|
3
|
+
"version": "2.4.2",
|
|
4
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.",
|
|
5
5
|
"type": "module",
|
|
6
6
|
"bin": {
|
|
@@ -27,20 +27,20 @@
|
|
|
27
27
|
"homepage": "https://www.consulti.ai/api-docs",
|
|
28
28
|
"repository": {
|
|
29
29
|
"type": "git",
|
|
30
|
-
"url": "git+https://github.com/
|
|
30
|
+
"url": "git+https://github.com/Lead-Gen-Jay/consulti.git",
|
|
31
31
|
"directory": "mcp"
|
|
32
32
|
},
|
|
33
33
|
"bugs": {
|
|
34
|
-
"url": "https://github.com/
|
|
34
|
+
"url": "https://github.com/Lead-Gen-Jay/consulti/issues"
|
|
35
35
|
},
|
|
36
36
|
"license": "MIT",
|
|
37
37
|
"dependencies": {
|
|
38
|
-
"@modelcontextprotocol/sdk": "^1.
|
|
38
|
+
"@modelcontextprotocol/sdk": "^1.30.0",
|
|
39
39
|
"zod": "^3.24.1"
|
|
40
40
|
},
|
|
41
41
|
"devDependencies": {
|
|
42
42
|
"@types/node": "^22.15.2",
|
|
43
|
-
"tsx": "^4.
|
|
43
|
+
"tsx": "^4.23.4",
|
|
44
44
|
"typescript": "^5.8.3"
|
|
45
45
|
}
|
|
46
46
|
}
|