@companyenrich/mcp 0.0.0-stage → 3.0.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.
- package/LICENSE +21 -0
- package/README.md +651 -2
- package/dist/stdio.js +1047 -0
- package/package.json +54 -4
package/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2025-2026 STDIO Ltd.
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
package/README.md
CHANGED
|
@@ -1,3 +1,652 @@
|
|
|
1
|
-
#
|
|
1
|
+
# CompanyEnrich MCP Server
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
A [Model Context Protocol](https://modelcontextprotocol.io) server for the
|
|
4
|
+
[CompanyEnrich](https://companyenrich.com) API. It lets MCP clients such as
|
|
5
|
+
Claude, Codex, Cursor, and VS Code enrich companies, search companies and
|
|
6
|
+
people, and look up people.
|
|
7
|
+
|
|
8
|
+
The server exposes a curated set of high-value actions from version 2 of the
|
|
9
|
+
CompanyEnrich API. Batch and bulk jobs, exports, previews, autocomplete, and
|
|
10
|
+
catalog-style geo, industry, and keyword tools are left out on purpose.
|
|
11
|
+
|
|
12
|
+
Most tools spend credits from your CompanyEnrich account. See [Tools](#tools)
|
|
13
|
+
for what each one costs.
|
|
14
|
+
|
|
15
|
+
## Connecting
|
|
16
|
+
|
|
17
|
+
There are two ways to run the server. Both expose the same tools.
|
|
18
|
+
|
|
19
|
+
| | Hosted (Streamable HTTP) | Local (stdio) |
|
|
20
|
+
| ------------------ | ---------------------------------------------- | ---------------------------------------- |
|
|
21
|
+
| **Runs on** | `https://mcp.companyenrich.com/mcp` | Your machine, started by your MCP client |
|
|
22
|
+
| **Authentication** | OAuth sign-in, or an API key as a bearer token | API key in an environment variable |
|
|
23
|
+
| **Requires** | Nothing to install | Node.js 20 or newer |
|
|
24
|
+
|
|
25
|
+
### Hosted
|
|
26
|
+
|
|
27
|
+
Claude Code:
|
|
28
|
+
|
|
29
|
+
```bash
|
|
30
|
+
claude mcp add --transport http companyenrich https://mcp.companyenrich.com/mcp
|
|
31
|
+
```
|
|
32
|
+
|
|
33
|
+
Then open `/mcp` in Claude Code and complete the login flow.
|
|
34
|
+
|
|
35
|
+
Codex CLI:
|
|
36
|
+
|
|
37
|
+
```bash
|
|
38
|
+
codex mcp add companyenrich --url https://mcp.companyenrich.com/mcp
|
|
39
|
+
codex mcp login companyenrich
|
|
40
|
+
```
|
|
41
|
+
|
|
42
|
+
In other clients, add a remote or Streamable HTTP server with the URL
|
|
43
|
+
`https://mcp.companyenrich.com/mcp` and follow the sign-in prompt. To skip OAuth,
|
|
44
|
+
send a CompanyEnrich API key in the `Authorization: Bearer <key>` header instead.
|
|
45
|
+
|
|
46
|
+
### Local (stdio)
|
|
47
|
+
|
|
48
|
+
Create an API key at <https://app.companyenrich.com/access-keys>, then register
|
|
49
|
+
the server with your client.
|
|
50
|
+
|
|
51
|
+
Claude Code:
|
|
52
|
+
|
|
53
|
+
```bash
|
|
54
|
+
claude mcp add companyenrich --transport stdio \
|
|
55
|
+
--env COMPANYENRICH_API_KEY=your-api-key -- npx -y @companyenrich/mcp
|
|
56
|
+
```
|
|
57
|
+
|
|
58
|
+
Codex CLI:
|
|
59
|
+
|
|
60
|
+
```bash
|
|
61
|
+
codex mcp add companyenrich --env COMPANYENRICH_API_KEY=your-api-key \
|
|
62
|
+
-- npx -y @companyenrich/mcp
|
|
63
|
+
```
|
|
64
|
+
|
|
65
|
+
Claude Desktop, Cursor, and other clients with a JSON config:
|
|
66
|
+
|
|
67
|
+
```json
|
|
68
|
+
{
|
|
69
|
+
"mcpServers": {
|
|
70
|
+
"companyenrich": {
|
|
71
|
+
"command": "npx",
|
|
72
|
+
"args": ["-y", "@companyenrich/mcp"],
|
|
73
|
+
"env": {
|
|
74
|
+
"COMPANYENRICH_API_KEY": "your-api-key"
|
|
75
|
+
}
|
|
76
|
+
}
|
|
77
|
+
}
|
|
78
|
+
}
|
|
79
|
+
```
|
|
80
|
+
|
|
81
|
+
The server reads these environment variables:
|
|
82
|
+
|
|
83
|
+
| Variable | Required | Description |
|
|
84
|
+
| ----------------------- | -------- | ---------------------------------------------------------- |
|
|
85
|
+
| `COMPANYENRICH_API_KEY` | Yes | Your CompanyEnrich API key. |
|
|
86
|
+
| `COMPANYENRICH_API_URL` | No | API base URL. Defaults to `https://api.companyenrich.com`. |
|
|
87
|
+
|
|
88
|
+
To run from a checkout instead of npm, build it and use
|
|
89
|
+
`node /absolute/path/to/mcp-server/dist/stdio.js` as the command:
|
|
90
|
+
|
|
91
|
+
```bash
|
|
92
|
+
git clone https://github.com/CompanyEnrich/mcp-server.git
|
|
93
|
+
cd mcp-server
|
|
94
|
+
pnpm install
|
|
95
|
+
pnpm build
|
|
96
|
+
```
|
|
97
|
+
|
|
98
|
+
## Protocol Support
|
|
99
|
+
|
|
100
|
+
Both transports speak MCP `2026-07-28` and still serve 2025-era clients that open
|
|
101
|
+
with an `initialize` handshake. The deprecated HTTP+SSE transport is not served.
|
|
102
|
+
|
|
103
|
+
On the hosted server, OAuth clients can register through Client ID Metadata
|
|
104
|
+
Documents or, as a fallback, Dynamic Client Registration at `/register`.
|
|
105
|
+
|
|
106
|
+
## Tools
|
|
107
|
+
|
|
108
|
+
All tools call [version 2 of the CompanyEnrich API](https://api.companyenrich.com/openapi/v2.json).
|
|
109
|
+
Tool inputs are strict: an argument the tool does not define is rejected instead
|
|
110
|
+
of being ignored, so a mistyped filter never runs as a broader, paid search.
|
|
111
|
+
|
|
112
|
+
### Company Tools
|
|
113
|
+
|
|
114
|
+
#### `enrich_company`
|
|
115
|
+
|
|
116
|
+
Enriches a company by domain.
|
|
117
|
+
|
|
118
|
+
Inputs:
|
|
119
|
+
|
|
120
|
+
- `domain` (string, required): Company domain, for example `example.com`.
|
|
121
|
+
- `expand` (string array, optional): Extra data to include. See
|
|
122
|
+
[Company expansions](#company-expansions).
|
|
123
|
+
- `waitForEnrichment` (boolean, optional, default `true`): Set `false` to return
|
|
124
|
+
only stored data right away. A miss then schedules enrichment in the
|
|
125
|
+
background.
|
|
126
|
+
|
|
127
|
+
Cost: 1 credit per successful enrichment, plus expansions. A company that
|
|
128
|
+
cannot be found costs nothing.
|
|
129
|
+
|
|
130
|
+
#### `get_company_by_id`
|
|
131
|
+
|
|
132
|
+
Retrieves a stored company by CompanyEnrich company ID.
|
|
133
|
+
|
|
134
|
+
Inputs:
|
|
135
|
+
|
|
136
|
+
- `id` (UUID string, required): CompanyEnrich company ID.
|
|
137
|
+
- `expand` (string array, optional): See
|
|
138
|
+
[Company expansions](#company-expansions).
|
|
139
|
+
|
|
140
|
+
Cost: 1 credit per company returned, plus expansions.
|
|
141
|
+
|
|
142
|
+
#### `enrich_company_by_properties`
|
|
143
|
+
|
|
144
|
+
Resolves and enriches a company from identifying properties such as its name or
|
|
145
|
+
a social profile URL. Provide at least one property. When several are given,
|
|
146
|
+
all of them must match.
|
|
147
|
+
|
|
148
|
+
Inputs:
|
|
149
|
+
|
|
150
|
+
- `name` (string, optional): Company name.
|
|
151
|
+
- `linkedinUrl` (URL string, optional): Company LinkedIn URL.
|
|
152
|
+
- `linkedinId` (string, optional): Company LinkedIn ID.
|
|
153
|
+
- `twitterUrl` (URL string, optional): Company Twitter/X URL.
|
|
154
|
+
- `facebookUrl` (URL string, optional): Company Facebook URL.
|
|
155
|
+
- `instagramUrl` (URL string, optional): Company Instagram URL.
|
|
156
|
+
- `youtubeUrl` (URL string, optional): Company YouTube URL.
|
|
157
|
+
- `expand` (string array, optional): See
|
|
158
|
+
[Company expansions](#company-expansions).
|
|
159
|
+
|
|
160
|
+
Cost: 1 credit when a company is returned or when the properties cannot be
|
|
161
|
+
resolved to a company domain, plus expansions.
|
|
162
|
+
|
|
163
|
+
#### `get_company_workforce`
|
|
164
|
+
|
|
165
|
+
Returns the current employee count, department headcounts, and the latest 12
|
|
166
|
+
months of workforce history for one company. Provide exactly one of `id` and
|
|
167
|
+
`domain`.
|
|
168
|
+
|
|
169
|
+
Inputs:
|
|
170
|
+
|
|
171
|
+
- `id` (UUID string, optional): CompanyEnrich company ID.
|
|
172
|
+
- `domain` (string, optional): Company domain.
|
|
173
|
+
- `cursor` (string, optional): `nextCursor` from a previous response, to get
|
|
174
|
+
the preceding 12 months. Cursors expire after 30 minutes.
|
|
175
|
+
|
|
176
|
+
Cost: 1 credit per successful page.
|
|
177
|
+
|
|
178
|
+
#### `search_companies`
|
|
179
|
+
|
|
180
|
+
Searches companies in one of three ways:
|
|
181
|
+
|
|
182
|
+
- by filters alone,
|
|
183
|
+
- by a natural-language `semantic` query, or
|
|
184
|
+
- by `lookalike` seed domains, which finds companies similar to the ones given.
|
|
185
|
+
|
|
186
|
+
Filters can be combined with either of the other two. `semantic` and
|
|
187
|
+
`lookalike` cannot be combined with each other.
|
|
188
|
+
|
|
189
|
+
Inputs:
|
|
190
|
+
|
|
191
|
+
- `filter` (object, optional): See
|
|
192
|
+
[Company filters](#company-filters).
|
|
193
|
+
- `semantic` (object, optional):
|
|
194
|
+
- `query` (string, required, max 500 characters): For example
|
|
195
|
+
`saas companies in Turkey`.
|
|
196
|
+
- `weight` (number, optional, 0 to 1): Larger values favor semantic
|
|
197
|
+
similarity.
|
|
198
|
+
- `autoFilter` (boolean, optional, default `true`): Infers filters such as
|
|
199
|
+
location, size, and funding from the query. The response `interpretation`
|
|
200
|
+
reports what was inferred.
|
|
201
|
+
- `lookalike` (object, optional):
|
|
202
|
+
- `domains` (string array, required, 1 to 10 items): Seed company domains.
|
|
203
|
+
- `weight` (number, optional, -1 to 1): Larger values favor more similar
|
|
204
|
+
companies.
|
|
205
|
+
- `minScore` (number, optional, 0 to 1): Minimum similarity score.
|
|
206
|
+
- `expand` (string array, optional): See
|
|
207
|
+
[Company expansions](#company-expansions).
|
|
208
|
+
- `pageSize` (integer, optional, default `20`, max `100`): Results per page.
|
|
209
|
+
- `cursor` (string, optional): `nextCursor` from the previous response. Keep
|
|
210
|
+
the rest of the query the same. Cursors expire after 24 hours.
|
|
211
|
+
|
|
212
|
+
Cost per returned company: 1 credit for a filter search, 2 for a semantic
|
|
213
|
+
search, 5 for a lookalike search, plus expansions. An empty result costs one
|
|
214
|
+
result's price.
|
|
215
|
+
|
|
216
|
+
#### `count_companies`
|
|
217
|
+
|
|
218
|
+
Counts the companies a `search_companies` query would match, without returning
|
|
219
|
+
them. Use it to size or check a query before running the paid search.
|
|
220
|
+
|
|
221
|
+
Inputs:
|
|
222
|
+
|
|
223
|
+
- `filter`, `semantic`, `lookalike` (objects, optional): The same as in
|
|
224
|
+
`search_companies`.
|
|
225
|
+
|
|
226
|
+
The response has `count`, the matches your plan can access, and `total`, all
|
|
227
|
+
matches. A semantic query also returns `interpretation`, the filters inferred
|
|
228
|
+
from it.
|
|
229
|
+
|
|
230
|
+
Cost: free.
|
|
231
|
+
|
|
232
|
+
### People Tools
|
|
233
|
+
|
|
234
|
+
#### `get_person_by_id`
|
|
235
|
+
|
|
236
|
+
Retrieves a stored person by CompanyEnrich person ID.
|
|
237
|
+
|
|
238
|
+
Inputs:
|
|
239
|
+
|
|
240
|
+
- `id` (positive integer or numeric string, required): CompanyEnrich person ID.
|
|
241
|
+
- `expand` (string array, optional): See
|
|
242
|
+
[Person expansions](#person-expansions).
|
|
243
|
+
|
|
244
|
+
Cost: 2 credits per person returned, plus expansions.
|
|
245
|
+
|
|
246
|
+
#### `lookup_person_by_email`
|
|
247
|
+
|
|
248
|
+
Identifies a person from an email address. The API resolves the company from
|
|
249
|
+
the email domain and matches the person by common address patterns.
|
|
250
|
+
|
|
251
|
+
Inputs:
|
|
252
|
+
|
|
253
|
+
- `email` (email string, required): Email address to look up.
|
|
254
|
+
- `expand` (string array, optional): See
|
|
255
|
+
[Person expansions](#person-expansions).
|
|
256
|
+
|
|
257
|
+
Cost: 5 credits when a person is returned, plus expansions. No match costs
|
|
258
|
+
nothing.
|
|
259
|
+
|
|
260
|
+
#### `enrich_person_email`
|
|
261
|
+
|
|
262
|
+
Finds the work email address of a person on a company domain. The response
|
|
263
|
+
`status` is `found`, `not-found`, `unavailable`, or `pending`. A pending lookup
|
|
264
|
+
is still running, so call the tool again later.
|
|
265
|
+
|
|
266
|
+
Inputs:
|
|
267
|
+
|
|
268
|
+
- `id` (positive integer or numeric string, required): CompanyEnrich person ID.
|
|
269
|
+
- `domain` (string, optional): Company domain to find the email on. It must
|
|
270
|
+
belong to one of the person's companies. If omitted, the person's current
|
|
271
|
+
companies are tried.
|
|
272
|
+
|
|
273
|
+
Cost: 10 credits when it finds an email your account has not accessed before.
|
|
274
|
+
Every other outcome is free.
|
|
275
|
+
|
|
276
|
+
#### `search_people`
|
|
277
|
+
|
|
278
|
+
Searches people by person filters, a natural-language `semantic` query, and an
|
|
279
|
+
optional `company` query.
|
|
280
|
+
|
|
281
|
+
Inputs:
|
|
282
|
+
|
|
283
|
+
- `filter` (object, optional): See [People filters](#people-filters).
|
|
284
|
+
- `semantic` (object, optional):
|
|
285
|
+
- `query` (string, required, max 500 characters): For example
|
|
286
|
+
`VP of sales at Series A SaaS startups in Germany`. The API infers person
|
|
287
|
+
filters and the kind of company to look in, and reports them in
|
|
288
|
+
`interpretation`. A query from which nothing can be inferred is rejected.
|
|
289
|
+
- `company` (object, optional): Limits results to people whose current company
|
|
290
|
+
matches. Takes the same `filter`, `semantic`, and `lookalike` inputs as
|
|
291
|
+
`search_companies`.
|
|
292
|
+
- `expand` (string array, optional): See
|
|
293
|
+
[Person expansions](#person-expansions).
|
|
294
|
+
- `pageSize` (integer, optional, default `20`, max `100`): Results per page.
|
|
295
|
+
- `cursor` (string, optional): `nextCursor` from the previous response. Keep
|
|
296
|
+
the rest of the query the same. Cursors expire after 24 hours.
|
|
297
|
+
|
|
298
|
+
Cost: 2 credits per returned person, plus expansions. An empty result costs one
|
|
299
|
+
result's price.
|
|
300
|
+
|
|
301
|
+
#### `count_people`
|
|
302
|
+
|
|
303
|
+
Counts the people a `search_people` query would match, without returning them.
|
|
304
|
+
Use it to size or check a query before running the paid search.
|
|
305
|
+
|
|
306
|
+
Inputs:
|
|
307
|
+
|
|
308
|
+
- `filter`, `semantic`, `company` (objects, optional): The same as in
|
|
309
|
+
`search_people`.
|
|
310
|
+
|
|
311
|
+
The response has `count`, `total`, and for a semantic query `interpretation`,
|
|
312
|
+
as in `count_companies`.
|
|
313
|
+
|
|
314
|
+
Cost: free.
|
|
315
|
+
|
|
316
|
+
### Account Tool
|
|
317
|
+
|
|
318
|
+
#### `get_current_user`
|
|
319
|
+
|
|
320
|
+
Fetches the authenticated user's credit usage and allowance, and the account's
|
|
321
|
+
capabilities and limits.
|
|
322
|
+
|
|
323
|
+
Inputs: none.
|
|
324
|
+
|
|
325
|
+
Cost: free.
|
|
326
|
+
|
|
327
|
+
## Shared Input Reference
|
|
328
|
+
|
|
329
|
+
### Value filters
|
|
330
|
+
|
|
331
|
+
A filter on a list of values is an object with one or more of these keys:
|
|
332
|
+
|
|
333
|
+
| Key | Meaning |
|
|
334
|
+
| ------- | ---------------------------------------------------------------------------------------------------- |
|
|
335
|
+
| `in` | Matches any of the listed values. |
|
|
336
|
+
| `all` | Requires every listed value. Only on `keywords`, `technologies`, `naicsCodes`, and `categories`. |
|
|
337
|
+
| `notIn` | Excludes anything matching a listed value. |
|
|
338
|
+
|
|
339
|
+
For example, `{ "country": { "in": ["TR", "US"] } }` or
|
|
340
|
+
`{ "keywords": { "all": ["fintech"], "notIn": ["gambling"] } }`.
|
|
341
|
+
|
|
342
|
+
The API also accepts a bare value or a bare array for these fields. The tools
|
|
343
|
+
only accept the object form, so that every filter has one unambiguous shape.
|
|
344
|
+
|
|
345
|
+
### Company filters
|
|
346
|
+
|
|
347
|
+
These are the keys of `filter` in `search_companies` and of `company.filter` in
|
|
348
|
+
`search_people`. Unless noted, each one is a [value filter](#value-filters).
|
|
349
|
+
|
|
350
|
+
- `query`: Text matched against company names, keywords, and domain prefixes.
|
|
351
|
+
- `id`: CompanyEnrich company IDs.
|
|
352
|
+
- `domain`: Company domains.
|
|
353
|
+
- `keywords`: Company keywords. Supports `all`.
|
|
354
|
+
- `technologies`: Technologies the company uses. Supports `all`.
|
|
355
|
+
- `region`: Region IDs.
|
|
356
|
+
- `country`: 2-letter country codes.
|
|
357
|
+
- `state`: State IDs (integers).
|
|
358
|
+
- `city`: City IDs (integers).
|
|
359
|
+
- `type`: Company types.
|
|
360
|
+
- `employees`: Employee count ranges.
|
|
361
|
+
- `reportedEmployees`: Employee count ranges as reported by external sources.
|
|
362
|
+
- `revenue`: Revenue ranges in USD.
|
|
363
|
+
- `naicsCodes`: NAICS codes as strings of 2 to 6 digits. Supports `all`.
|
|
364
|
+
- `categories`: Company categories. Supports `all`.
|
|
365
|
+
- `fundingRounds`: Funding rounds.
|
|
366
|
+
- `foundedYear` (range object): `{ min?: number, max?: number }`.
|
|
367
|
+
- `fundingAmount` (range object): `{ min?: number, max?: number }`.
|
|
368
|
+
- `fundingYear` (range object): `{ min?: number, max?: number }`, the latest
|
|
369
|
+
funding year.
|
|
370
|
+
- `workforceGrowth` (object): `period`, `department`, `min`, and `max`. `min`
|
|
371
|
+
and `max` are ratios, so `0.15` is 15% growth.
|
|
372
|
+
- `workforceSize` (object array): Each item has `department`, `min`, and `max`
|
|
373
|
+
headcount.
|
|
374
|
+
- `require` (object): `{ all: [...] }`, the data a company must have, such as
|
|
375
|
+
`linkedin`, `twitter`, `facebook`, `instagram`, `angellist`, `crunchbase`,
|
|
376
|
+
`youtube`, `country`, `city`, `state`, `revenue`, `foundedYear`, or
|
|
377
|
+
`anyFunding`.
|
|
378
|
+
|
|
379
|
+
Company enum values:
|
|
380
|
+
|
|
381
|
+
- `type`: `private`, `public`, `self-employed`, `self-owned`, `partnership`,
|
|
382
|
+
`nonprofit`, `educational`, `government`.
|
|
383
|
+
- `categories`: `b2b`, `b2c`, `b2g`, `e-commerce`, `media`,
|
|
384
|
+
`service-provider`, `mobile`, `saas`, `local-business`.
|
|
385
|
+
- `employees` and `reportedEmployees`: `1-10`, `11-50`, `51-200`, `201-500`,
|
|
386
|
+
`501-1K`, `1K-5K`, `5K-10K`, `over-10K`.
|
|
387
|
+
- `revenue`: `under-1m`, `1m-10m`, `10m-50m`, `50m-100m`, `100m-200m`,
|
|
388
|
+
`200m-1b`, `over-1b`.
|
|
389
|
+
- `fundingRounds`: `seed`, `debt_financing`, `angel`, `venture`, `series_a`,
|
|
390
|
+
`series_b`, `series_c`, `series_d`, `series_e`, `series_f`, `series_g`,
|
|
391
|
+
`series_h`, `other`.
|
|
392
|
+
- Workforce departments: `overall`, `c_suite`, `product_management`,
|
|
393
|
+
`engineering_technical`, `design`, `education`, `finance`,
|
|
394
|
+
`human_resources`, `information_technology`, `legal`, `marketing`,
|
|
395
|
+
`medical_health`, `operations`, `sales`, `consulting`.
|
|
396
|
+
- Workforce growth periods: `m6`, `y1`, `y2`.
|
|
397
|
+
|
|
398
|
+
### People filters
|
|
399
|
+
|
|
400
|
+
These are the keys of `filter` in `search_people`. The top-level filters match
|
|
401
|
+
a person's current roles. Unless noted, each one is a
|
|
402
|
+
[value filter](#value-filters).
|
|
403
|
+
|
|
404
|
+
- `query`: Text matched against person names.
|
|
405
|
+
- `companyId`: Current company IDs.
|
|
406
|
+
- `domain`: Current company domains.
|
|
407
|
+
- `companyLinkedinHandle`: LinkedIn handles or URLs of current companies.
|
|
408
|
+
- `seniority`: Current seniority levels.
|
|
409
|
+
- `department`: Current departments. A root department includes its
|
|
410
|
+
sub-departments.
|
|
411
|
+
- `country`: 2-letter country codes of the person.
|
|
412
|
+
- `position`: Phrases matched against current job titles.
|
|
413
|
+
- `currentCompanyStartDate` (date range): `{ after?, before? }`, when the
|
|
414
|
+
person joined their current company.
|
|
415
|
+
- `currentPositionStartDate` (date range): `{ after?, before? }`, when the
|
|
416
|
+
person started their current position.
|
|
417
|
+
- `education` (object): `institutionName` and `institutionLinkedinHandle`
|
|
418
|
+
value filters.
|
|
419
|
+
- `pastExperience` (object): Finds people by a previous job. All of its rules
|
|
420
|
+
must match the same past role, and people who still work at an included
|
|
421
|
+
company are left out.
|
|
422
|
+
- `companyId`, `domain`, `companyLinkedinHandle`: Value filters.
|
|
423
|
+
- `seniority`, `department`, `position`: `{ in: [...] }` only. Exclusions are
|
|
424
|
+
not supported here.
|
|
425
|
+
- `startDate`, `endDate` (date ranges): `{ after?, before? }`.
|
|
426
|
+
|
|
427
|
+
Dates are ISO 8601 datetimes such as `2024-01-01T00:00:00Z`.
|
|
428
|
+
|
|
429
|
+
People enum values:
|
|
430
|
+
|
|
431
|
+
- Seniority: `owner`, `founder`, `c-suite`, `partner`, `vp`, `head`,
|
|
432
|
+
`director`, `manager`, `senior`, `entry`, `intern`.
|
|
433
|
+
- Department: root departments such as `c-suite`, `engineering-technical`,
|
|
434
|
+
`finance`, `human-resources`, `information-technology`, `legal`,
|
|
435
|
+
`marketing`, `operations`, `sales`, and `consulting`, or a sub-department
|
|
436
|
+
such as `engineering-technical/software-development`. The full list is
|
|
437
|
+
`PersonDepartmentEnum` in `src/schema.ts`.
|
|
438
|
+
|
|
439
|
+
### Company expansions
|
|
440
|
+
|
|
441
|
+
`expand` on the company tools adds data to each returned company. Each one
|
|
442
|
+
costs 1 extra credit per returned company:
|
|
443
|
+
|
|
444
|
+
- `financial`
|
|
445
|
+
- `keywords`
|
|
446
|
+
- `naicsCodes`
|
|
447
|
+
- `technologies`
|
|
448
|
+
- `workforce`: The latest 12 months of workforce history. Use
|
|
449
|
+
`get_company_workforce` with its `nextCursor` for earlier years.
|
|
450
|
+
|
|
451
|
+
### Person expansions
|
|
452
|
+
|
|
453
|
+
`expand` on the people tools adds data to each returned person:
|
|
454
|
+
|
|
455
|
+
- `education`: 1 extra credit per returned person.
|
|
456
|
+
- `company`: The company profile for each current and past role. 1 extra
|
|
457
|
+
credit per unique company whose profile is included.
|
|
458
|
+
|
|
459
|
+
## Credit Notes
|
|
460
|
+
|
|
461
|
+
Tool descriptions state the credit cost that the API documents for each call.
|
|
462
|
+
In short:
|
|
463
|
+
|
|
464
|
+
- A filter search costs 1 credit per company, a semantic search 2, and a
|
|
465
|
+
lookalike search 5.
|
|
466
|
+
- People search costs 2 credits per person.
|
|
467
|
+
- Expansions are charged on top of the base cost.
|
|
468
|
+
- A lookup that finds nothing is free, except `enrich_company_by_properties`.
|
|
469
|
+
A search with no results costs one result's price.
|
|
470
|
+
- `count_companies`, `count_people`, and `get_current_user` are free.
|
|
471
|
+
|
|
472
|
+
The MCP response includes any `x-credit-balance`, `x-credit-cost`, and
|
|
473
|
+
`x-credit-remaining` headers returned by the API under `creditInfo`.
|
|
474
|
+
|
|
475
|
+
## Upgrading from 2.x
|
|
476
|
+
|
|
477
|
+
Version 3 moves every tool from version 1 to version 2 of the CompanyEnrich
|
|
478
|
+
API. Tool inputs changed, so calls written for 2.x need updating:
|
|
479
|
+
|
|
480
|
+
- `find_similar_companies` is gone. Use `search_companies` with `lookalike`.
|
|
481
|
+
- `search_companies` takes `filter`, `semantic`, and `lookalike` objects
|
|
482
|
+
instead of flat arguments. `semanticQuery` is now `semantic.query`, and
|
|
483
|
+
`query` is now `filter.query`.
|
|
484
|
+
- Filters are [value filters](#value-filters). The separate `exclude` object
|
|
485
|
+
and the `categoryOperator`, `keywordsOperator`, and `technologiesOperator`
|
|
486
|
+
arguments are replaced by `notIn`, `in`, and `all`.
|
|
487
|
+
- Several filter names changed: `countries` to `country`, `states` to `state`,
|
|
488
|
+
`cities` to `city`, `regions` to `region`, and `naicsCode` (integers) to
|
|
489
|
+
`naicsCodes` (strings).
|
|
490
|
+
- `workforceGrowth` takes `min` and `max` ratios instead of `minPercent` and
|
|
491
|
+
`maxPercent`.
|
|
492
|
+
- `search_people` takes `filter`, `semantic`, and `company`. The person
|
|
493
|
+
filters moved under `filter`: `positionQuery` is now `filter.position`,
|
|
494
|
+
`domains` is `filter.domain`, `countries` is `filter.country`, and the
|
|
495
|
+
`atCurrent...` dates are `filter.currentCompanyStartDate` and
|
|
496
|
+
`filter.currentPositionStartDate`. `companyFilter` is now `company`.
|
|
497
|
+
- Paging uses `cursor` instead of `page`.
|
|
498
|
+
- `includeWorkforce` is replaced by `expand: ["workforce"]`, which now costs 1
|
|
499
|
+
credit instead of 5.
|
|
500
|
+
- Unknown arguments are rejected.
|
|
501
|
+
|
|
502
|
+
Version 3 also adds two free tools, `count_companies` and `count_people`.
|
|
503
|
+
|
|
504
|
+
## Privacy and Security
|
|
505
|
+
|
|
506
|
+
- Tool calls go to the CompanyEnrich API with your API key and an
|
|
507
|
+
`x-companyenrich-app: mcp` header, which attributes the usage to MCP. The local
|
|
508
|
+
server talks to nothing else, stores nothing, and has no telemetry.
|
|
509
|
+
- The hosted server does not store an API key sent directly as a bearer token.
|
|
510
|
+
For OAuth sign-ins it keeps your grant in Cloudflare KV with the API key
|
|
511
|
+
encrypted.
|
|
512
|
+
- OAuth sign-in and its approval step happen at CompanyEnrich's identity
|
|
513
|
+
provider. The hosted server completes a sign-in only in the browser that
|
|
514
|
+
started it.
|
|
515
|
+
|
|
516
|
+
Please report security vulnerabilities privately to
|
|
517
|
+
[support@companyenrich.com](mailto:support@companyenrich.com) rather than in a
|
|
518
|
+
public issue.
|
|
519
|
+
|
|
520
|
+
## Development
|
|
521
|
+
|
|
522
|
+
You need Node.js 20 or newer and [pnpm](https://pnpm.io).
|
|
523
|
+
|
|
524
|
+
```bash
|
|
525
|
+
pnpm install
|
|
526
|
+
pnpm type-check
|
|
527
|
+
pnpm build # bundles the stdio server into dist/stdio.js
|
|
528
|
+
```
|
|
529
|
+
|
|
530
|
+
Try the stdio server in the MCP Inspector:
|
|
531
|
+
|
|
532
|
+
```bash
|
|
533
|
+
npx @modelcontextprotocol/inspector -e COMPANYENRICH_API_KEY=your-api-key node dist/stdio.js
|
|
534
|
+
```
|
|
535
|
+
|
|
536
|
+
Run the Worker locally at `http://localhost:8787/mcp`. You can leave the OAuth
|
|
537
|
+
values in `.dev.vars` empty if you send an API key as a bearer token:
|
|
538
|
+
|
|
539
|
+
```bash
|
|
540
|
+
cp .dev.vars.example .dev.vars
|
|
541
|
+
pnpm dev
|
|
542
|
+
```
|
|
543
|
+
|
|
544
|
+
| Path | Purpose |
|
|
545
|
+
| ---------------------- | -------------------------------------------------------- |
|
|
546
|
+
| `src/mcp.ts` | Tool definitions, shared by both transports |
|
|
547
|
+
| `src/schema.ts` | Tool input schemas |
|
|
548
|
+
| `src/utils.ts` | CompanyEnrich API client and response handling |
|
|
549
|
+
| `src/stdio.ts` | stdio entry point (Node.js) |
|
|
550
|
+
| `src/http.ts` | Streamable HTTP handler (Cloudflare Workers) |
|
|
551
|
+
| `src/index.ts` | Worker entry point, puts the OAuth provider before `/mcp` |
|
|
552
|
+
| `src/clerk-handler.ts` | OAuth sign-in through Clerk |
|
|
553
|
+
|
|
554
|
+
Run `pnpm cf-typegen` after changing `wrangler.jsonc`.
|
|
555
|
+
|
|
556
|
+
## Publishing to npm
|
|
557
|
+
|
|
558
|
+
The local stdio server is published as `@companyenrich/mcp`.
|
|
559
|
+
|
|
560
|
+
### Automatic publishing from GitHub
|
|
561
|
+
|
|
562
|
+
The workflow in [`.github/workflows/publish.yml`](.github/workflows/publish.yml)
|
|
563
|
+
runs on every push to `main`. It installs dependencies from the lockfile,
|
|
564
|
+
type-checks, builds, and checks npm for the version in `package.json`. A new
|
|
565
|
+
stable version is published with the `latest` tag. If that version already
|
|
566
|
+
exists, the build succeeds and publishing is skipped. Older versions and
|
|
567
|
+
prereleases cannot replace `latest` through this workflow.
|
|
568
|
+
|
|
569
|
+
Configure the publishing token once before the first automated release:
|
|
570
|
+
|
|
571
|
+
1. Create a granular npm access token with **read and write** access to
|
|
572
|
+
`@companyenrich/mcp` and **Bypass 2FA** enabled.
|
|
573
|
+
2. In the GitHub repository, open **Settings → Secrets and variables → Actions**
|
|
574
|
+
and add a repository secret named **`NPM_TOKEN`** containing the token.
|
|
575
|
+
3. Commit and push the workflow and package changes to `main`. With the
|
|
576
|
+
already-published version `2.0.0`, this first run builds, checks npm
|
|
577
|
+
authentication, and skips publishing.
|
|
578
|
+
|
|
579
|
+
GitHub stores the token as an encrypted secret. The workflow exposes it as
|
|
580
|
+
`NODE_AUTH_TOKEN` only for the authentication check and publishing step. Never
|
|
581
|
+
commit the token to the repository. Replace the `NPM_TOKEN` secret when rotating
|
|
582
|
+
the token or before it expires. No npm trusted-publisher connection is needed.
|
|
583
|
+
The repository is private, so this workflow does not force a public provenance
|
|
584
|
+
statement.
|
|
585
|
+
|
|
586
|
+
For each release, bump the version before committing your changes:
|
|
587
|
+
|
|
588
|
+
```bash
|
|
589
|
+
npm version patch --no-git-tag-version
|
|
590
|
+
# Commit your code changes and package.json, then:
|
|
591
|
+
git push origin main
|
|
592
|
+
```
|
|
593
|
+
|
|
594
|
+
Use `minor` or `major` instead of `patch` when appropriate. For example, the next
|
|
595
|
+
patch after `2.0.0` is `2.0.1`. Pushing code without a new version still checks
|
|
596
|
+
the build but does not create an npm release. You can retry a failed release
|
|
597
|
+
from **GitHub → Actions → Publish to npm → Run workflow**, selecting `main`.
|
|
598
|
+
|
|
599
|
+
See npm's [CI/CD token guide](https://docs.npmjs.com/using-private-packages-in-a-ci-cd-workflow/)
|
|
600
|
+
for token configuration details.
|
|
601
|
+
|
|
602
|
+
### Manual publishing
|
|
603
|
+
|
|
604
|
+
Your npm account must have permission to publish under the `companyenrich`
|
|
605
|
+
scope. Enable two-factor authentication for interactive publishing.
|
|
606
|
+
|
|
607
|
+
From the repository root:
|
|
608
|
+
|
|
609
|
+
```bash
|
|
610
|
+
pnpm install --frozen-lockfile
|
|
611
|
+
npm run type-check
|
|
612
|
+
npm pack --dry-run
|
|
613
|
+
npm login --registry=https://registry.npmjs.org/
|
|
614
|
+
npm whoami --registry=https://registry.npmjs.org/
|
|
615
|
+
npm publish --access public
|
|
616
|
+
```
|
|
617
|
+
|
|
618
|
+
`npm pack --dry-run` builds the server and lists the package contents without
|
|
619
|
+
publishing. Check that the package contains `dist/stdio.js`, `package.json`,
|
|
620
|
+
`README.md`, and `LICENSE`. Publishing runs the type check and builds the server
|
|
621
|
+
automatically. The package defaults to public access on the npm registry.
|
|
622
|
+
|
|
623
|
+
For subsequent releases, update the version first. Each release needs a
|
|
624
|
+
version that has not already been published. Choose either the GitHub workflow
|
|
625
|
+
or manual publishing for a release.
|
|
626
|
+
|
|
627
|
+
See npm's [scoped package publishing guide](https://docs.npmjs.com/creating-and-publishing-scoped-public-packages/)
|
|
628
|
+
for account and authentication requirements.
|
|
629
|
+
|
|
630
|
+
## Deploying
|
|
631
|
+
|
|
632
|
+
The hosted server runs on Cloudflare Workers. Its OAuth flow is tied to
|
|
633
|
+
CompanyEnrich's Clerk instance and internal API endpoints, so a fork needs to
|
|
634
|
+
adapt `src/clerk-handler.ts` to offer sign-in. Direct API key access works
|
|
635
|
+
without it.
|
|
636
|
+
|
|
637
|
+
Keep secrets out of `wrangler.jsonc`, since its `vars` are stored in plain text.
|
|
638
|
+
Set them as Worker secrets instead. A deploy fails if a secret listed in
|
|
639
|
+
`secrets.required` is missing.
|
|
640
|
+
|
|
641
|
+
```bash
|
|
642
|
+
pnpm exec wrangler secret put OAUTH_CLIENT_ID -e production
|
|
643
|
+
pnpm exec wrangler secret put OAUTH_CLIENT_SECRET -e production
|
|
644
|
+
pnpm run deploy
|
|
645
|
+
```
|
|
646
|
+
|
|
647
|
+
If your Cloudflare login can access several accounts, set
|
|
648
|
+
`CLOUDFLARE_ACCOUNT_ID`, for example in a local `.env` file, which git ignores.
|
|
649
|
+
|
|
650
|
+
## License
|
|
651
|
+
|
|
652
|
+
[MIT](LICENSE)
|