@companyenrich/mcp 0.0.0-stage → 2.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.
Files changed (4) hide show
  1. package/LICENSE +21 -0
  2. package/README.md +464 -2
  3. package/dist/stdio.js +1136 -0
  4. 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,465 @@
1
- # Temporary Holding Version
1
+ # CompanyEnrich MCP Server
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
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 API actions. Bulk jobs, exports,
9
+ scroll endpoints, preview and count helpers, autocomplete, list management, 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
+ ### Company Tools
109
+
110
+ #### `enrich_company`
111
+
112
+ Enriches a company by domain.
113
+
114
+ Inputs:
115
+
116
+ - `domain` (string, required): Company domain, for example `example.com`.
117
+ - `includeWorkforce` (boolean, optional, default `false`): Include expanded
118
+ workforce insights.
119
+
120
+ Cost: 1 credit per call, plus 5 additional credits when `includeWorkforce` is
121
+ true.
122
+
123
+ #### `get_company_by_id`
124
+
125
+ Retrieves a company by CompanyEnrich company ID.
126
+
127
+ Inputs:
128
+
129
+ - `id` (UUID string, required): CompanyEnrich company ID.
130
+ - `includeWorkforce` (boolean, optional, default `false`): Include expanded
131
+ workforce insights.
132
+
133
+ Cost: 1 credit per call, plus 5 additional credits when `includeWorkforce` is
134
+ true.
135
+
136
+ #### `enrich_company_by_properties`
137
+
138
+ Enriches a company from known properties such as name or social profile URL.
139
+ Provide at least one company property.
140
+
141
+ Inputs:
142
+
143
+ - `name` (string, optional): Company name.
144
+ - `linkedinUrl` (URL string, optional): Company LinkedIn URL.
145
+ - `linkedinId` (string, optional): Company LinkedIn ID.
146
+ - `twitterUrl` (URL string, optional): Company Twitter/X URL.
147
+ - `facebookUrl` (URL string, optional): Company Facebook URL.
148
+ - `instagramUrl` (URL string, optional): Company Instagram URL.
149
+ - `youtubeUrl` (URL string, optional): Company YouTube URL.
150
+ - `includeWorkforce` (boolean, optional, default `false`): Include expanded
151
+ workforce insights.
152
+
153
+ Cost: 1 credit per call, plus 5 additional credits when `includeWorkforce` is
154
+ true.
155
+
156
+ #### `get_company_workforce`
157
+
158
+ Fetches workforce insights for one company. Provide exactly one lookup
159
+ parameter.
160
+
161
+ Inputs:
162
+
163
+ - `id` (UUID string, optional): CompanyEnrich company ID.
164
+ - `domain` (string, optional): Company domain.
165
+
166
+ Cost: 5 credits per successful call.
167
+
168
+ #### `search_companies`
169
+
170
+ Runs page-based company search. Use `semanticQuery` for natural-language
171
+ profile search and `query` for company name/domain search.
172
+
173
+ Inputs:
174
+
175
+ - `semanticQuery` (string, optional): Natural-language company profile query.
176
+ - `semanticWeight` (number, optional, 0 to 1): Weight for semantic matching.
177
+ - `query` (string, optional): Search against company name and domain.
178
+ - Common company filters: see [Company Filter Inputs](#company-filter-inputs).
179
+ - `includeWorkforce` (boolean, optional, default `false`): Include expanded
180
+ workforce insights for returned companies.
181
+ - `page` (integer, optional, default `1`): 1-indexed page number.
182
+ - `pageSize` (integer, optional, default `20`, max `100`): Results per page.
183
+
184
+ Cost: 1 credit per company returned, with a 1-credit minimum.
185
+
186
+ #### `find_similar_companies`
187
+
188
+ Finds companies similar to one or more seed domains, with optional filters.
189
+
190
+ Inputs:
191
+
192
+ - `domains` (string array, required, 1 to 10 items): Seed company domains.
193
+ - `similarityWeight` (number, optional, -1 to 1): Higher favors similarity;
194
+ lower favors more established companies.
195
+ - `minScore` (number, optional, 0 to 1): Minimum similarity score for results.
196
+ - `query` (string, optional): Search against company name and domain.
197
+ - Common company filters: see [Company Filter Inputs](#company-filter-inputs).
198
+ - `includeWorkforce` (boolean, optional, default `false`): Include expanded
199
+ workforce insights for returned companies.
200
+ - `page` (integer, optional, default `1`): 1-indexed page number.
201
+ - `pageSize` (integer, optional, default `20`, max `100`): Results per page.
202
+
203
+ Cost: 5 credits per company returned, with a 5-credit minimum.
204
+
205
+ ### People Tools
206
+
207
+ #### `get_person_by_id`
208
+
209
+ Retrieves a person by CompanyEnrich person ID.
210
+
211
+ Inputs:
212
+
213
+ - `id` (positive integer or numeric string, required): CompanyEnrich person ID.
214
+
215
+ Cost: 2 credits per call.
216
+
217
+ #### `lookup_person_by_email`
218
+
219
+ Looks up a person by email address. The API resolves the company from the email
220
+ domain and matches the local part.
221
+
222
+ Inputs:
223
+
224
+ - `email` (email string, required): Email address to look up.
225
+
226
+ Cost: 5 credits per successful call.
227
+
228
+ #### `enrich_person_email`
229
+
230
+ Beta endpoint that resolves a work email address for a single person.
231
+
232
+ Inputs:
233
+
234
+ - `id` (positive integer or numeric string, required): CompanyEnrich person ID.
235
+ - `domain` (string, optional): Company domain to resolve the email on. If
236
+ omitted, current experience domains are tried by the API.
237
+
238
+ Cost: 10 credits per newly accessed found email.
239
+
240
+ #### `search_people`
241
+
242
+ Runs page-based people search.
243
+
244
+ Inputs:
245
+
246
+ - `query` (string, optional): Name search query. This is not semantic search.
247
+ - `positionQuery` (string or string array, optional): Current job title query or
248
+ queries.
249
+ - `atCurrentCompanyAfter` (UTC datetime string, optional): Joined current
250
+ company after this datetime.
251
+ - `atCurrentCompanyBefore` (UTC datetime string, optional): Joined current
252
+ company before this datetime.
253
+ - `atCurrentPositionAfter` (UTC datetime string, optional): Started current
254
+ position after this datetime.
255
+ - `atCurrentPositionBefore` (UTC datetime string, optional): Started current
256
+ position before this datetime.
257
+ - `countries` (string array, optional): 2-letter country codes.
258
+ - `domains` (string array, optional, max 100): Current company domains.
259
+ - `seniority` (string array, optional): Person seniority values.
260
+ - `department` (string array, optional): Person department values.
261
+ - `exclude` (object, optional): Exclusion filters with `positionQuery`,
262
+ `countries`, `domains`, `seniority`, and `department`.
263
+ - `companyFilter` (object, optional): Scope people by company filters:
264
+ `{ search?: CompanySearchFilter, similar?: CompanySimilarFilter }`.
265
+ - `page` (integer, optional, default `1`): 1-indexed page number.
266
+ - `pageSize` (integer, optional, default `20`, max `100`): Results per page.
267
+
268
+ Cost: 2 credits per person returned, with a 2-credit minimum.
269
+
270
+ ### Account Tool
271
+
272
+ #### `get_current_user`
273
+
274
+ Fetches the authenticated user's credit balance and account capabilities.
275
+
276
+ Inputs: none.
277
+
278
+ Cost: free.
279
+
280
+ ## Shared Input Reference
281
+
282
+ ### Company Filter Inputs
283
+
284
+ These inputs are available on `search_companies`, `find_similar_companies`, and
285
+ nested `companyFilter` values in `search_people`.
286
+
287
+ - `exclude` (object, optional): Excludes companies matching any supplied
288
+ filters. Supports `domains`, `regions`, `countries`, `states`, `cities`,
289
+ `type`, `categories`, `employees`, `revenue`, `naicsCode`, `keywords`,
290
+ `technologies`, and `fundingRounds`.
291
+ - `foundedYear` (object, optional): `{ min?: number, max?: number }`.
292
+ - `fundingAmount` (object, optional): `{ min?: number, max?: number }`.
293
+ - `fundingYear` (object, optional): `{ min?: number, max?: number }`.
294
+ - `categoryOperator` (string, optional): `And` or `Or`.
295
+ - `keywordsOperator` (string, optional): `And` or `Or`.
296
+ - `technologiesOperator` (string, optional): `And` or `Or`.
297
+ - `workforceGrowth` (object, optional): `period`, `department`, `minPercent`,
298
+ and `maxPercent`.
299
+ - `workforceSize` (object array, optional): Each item has `department`, `min`,
300
+ and `max`.
301
+ - `require` (string array, optional): Required company features such as
302
+ `linkedin`, `twitter`, `facebook`, `instagram`, `angellist`, `crunchbase`,
303
+ `youtube`, `country`, `city`, `state`, `revenue`, `foundedYear`, or
304
+ `anyFunding`.
305
+ - `regions` (string array, optional): Region IDs.
306
+ - `country` (string, optional): Deprecated single-country alias.
307
+ - `countries` (string array, optional): 2-letter country codes.
308
+ - `states` (integer array, optional): State IDs.
309
+ - `cities` (integer array, optional): City IDs.
310
+ - `type` (string array, optional): Company types.
311
+ - `categories` (string array, optional): Company categories.
312
+ - `employees` (string array, optional): Employee count ranges.
313
+ - `revenue` (string array, optional): Revenue ranges.
314
+ - `naicsCode` (integer array, optional): NAICS codes.
315
+ - `keywords` (string array, optional): Company keywords.
316
+ - `technologies` (string array, optional): Company technologies.
317
+ - `fundingRounds` (string array, optional): Funding round values.
318
+
319
+ Common company enum values:
320
+
321
+ - `type`: `private`, `public`, `self-employed`, `self-owned`, `partnership`,
322
+ `nonprofit`, `educational`, `government`.
323
+ - `categories`: `b2b`, `b2c`, `b2g`, `e-commerce`, `media`,
324
+ `service-provider`, `mobile`, `saas`.
325
+ - `employees`: `1-10`, `11-50`, `51-200`, `201-500`, `501-1K`, `1K-5K`,
326
+ `5K-10K`, `over-10K`.
327
+ - `revenue`: `under-1m`, `1m-10m`, `10m-50m`, `50m-100m`, `100m-200m`,
328
+ `200m-1b`, `over-1b`.
329
+ - `fundingRounds`: `seed`, `debt_financing`, `angel`, `venture`, `series_a`,
330
+ `series_b`, `series_c`, `series_d`, `series_e`, `series_f`, `series_g`,
331
+ `series_h`, `other`.
332
+ - Workforce departments: `overall`, `c_suite`, `product_management`,
333
+ `engineering_technical`, `design`, `education`, `finance`,
334
+ `human_resources`, `information_technology`, `legal`, `marketing`,
335
+ `medical_health`, `operations`, `sales`, `consulting`.
336
+ - Workforce growth periods: `m6`, `y1`, `y2`.
337
+
338
+ ### People Filter Values
339
+
340
+ - Seniority values: `owner`, `founder`, `c-suite`, `partner`, `vp`, `head`,
341
+ `director`, `manager`, `senior`, `entry`, `intern`.
342
+ - Department values include root departments and sub-departments such as
343
+ `c-suite`, `engineering-technical`, `engineering-technical/software-development`,
344
+ `finance`, `human-resources`, `information-technology`, `legal`, `marketing`,
345
+ `operations`, `sales`, and `consulting`. The full enum is defined in
346
+ `src/schema.ts`.
347
+
348
+ ## Credit Notes
349
+
350
+ Tool descriptions include the API credit costs where the public API documents
351
+ them. In short:
352
+
353
+ - Company enrichment and company search consume company credits.
354
+ - Similar-company search is more expensive than regular company search.
355
+ - People search and person lookup consume people credits.
356
+ - `enrich_person_email` is beta and can cost 10 credits for a newly accessed
357
+ found email.
358
+ - `get_current_user` is free.
359
+
360
+ The MCP response includes any `x-credit-balance`, `x-credit-cost`, and
361
+ `x-credit-remaining` headers returned by the API under `creditInfo`.
362
+
363
+ ## Privacy and Security
364
+
365
+ - Tool calls go to the CompanyEnrich API with your API key and an
366
+ `x-companyenrich-app: mcp` header, which attributes the usage to MCP. The local
367
+ server talks to nothing else, stores nothing, and has no telemetry.
368
+ - The hosted server does not store an API key sent directly as a bearer token.
369
+ For OAuth sign-ins it keeps your grant in Cloudflare KV with the API key
370
+ encrypted.
371
+
372
+ Please report security vulnerabilities privately to
373
+ [support@companyenrich.com](mailto:support@companyenrich.com) rather than in a
374
+ public issue.
375
+
376
+ ## Development
377
+
378
+ You need Node.js 20 or newer and [pnpm](https://pnpm.io).
379
+
380
+ ```bash
381
+ pnpm install
382
+ pnpm type-check
383
+ pnpm build # bundles the stdio server into dist/stdio.js
384
+ ```
385
+
386
+ Try the stdio server in the MCP Inspector:
387
+
388
+ ```bash
389
+ npx @modelcontextprotocol/inspector -e COMPANYENRICH_API_KEY=your-api-key node dist/stdio.js
390
+ ```
391
+
392
+ Run the Worker locally at `http://localhost:8787/mcp`. You can leave the OAuth
393
+ values in `.dev.vars` empty if you send an API key as a bearer token:
394
+
395
+ ```bash
396
+ cp .dev.vars.example .dev.vars
397
+ pnpm dev
398
+ ```
399
+
400
+ | Path | Purpose |
401
+ | ---------------------- | -------------------------------------------------------- |
402
+ | `src/mcp.ts` | Tool definitions, shared by both transports |
403
+ | `src/schema.ts` | Tool input schemas |
404
+ | `src/utils.ts` | CompanyEnrich API client and response handling |
405
+ | `src/stdio.ts` | stdio entry point (Node.js) |
406
+ | `src/http.ts` | Streamable HTTP handler (Cloudflare Workers) |
407
+ | `src/index.ts` | Worker entry point, puts the OAuth provider before `/mcp` |
408
+ | `src/clerk-handler.ts` | OAuth sign-in through Clerk |
409
+
410
+ Run `pnpm cf-typegen` after changing `wrangler.jsonc`.
411
+
412
+ ## Publishing to npm
413
+
414
+ The local stdio server is published as `@companyenrich/mcp`. Your npm account
415
+ must have permission to publish under the `companyenrich` scope. For an npm
416
+ organization, create or join the organization and obtain publishing access
417
+ first; the GitHub organization does not automatically create an npm scope.
418
+ Enable two-factor authentication on your npm account for interactive publishing.
419
+
420
+ From the repository root:
421
+
422
+ ```bash
423
+ pnpm install --frozen-lockfile
424
+ npm run type-check
425
+ npm pack --dry-run
426
+ npm login --registry=https://registry.npmjs.org/
427
+ npm whoami --registry=https://registry.npmjs.org/
428
+ npm publish --access public
429
+ ```
430
+
431
+ `npm pack --dry-run` builds the server and lists the package contents without
432
+ publishing. Check that the package contains `dist/stdio.js`, `package.json`,
433
+ `README.md`, and `LICENSE`. Publishing runs the type check and builds the server
434
+ automatically. The package defaults to public access on the npm registry.
435
+
436
+ The current version is `2.0.0`. For subsequent releases, commit your changes,
437
+ run `npm version patch` (or `minor` / `major` as appropriate), and publish again.
438
+ Each release needs a version that has not already been published.
439
+
440
+ See npm's [scoped package publishing guide](https://docs.npmjs.com/creating-and-publishing-scoped-public-packages/)
441
+ for account and authentication requirements.
442
+
443
+ ## Deploying
444
+
445
+ The hosted server runs on Cloudflare Workers. Its OAuth flow is tied to
446
+ CompanyEnrich's Clerk instance and internal API endpoints, so a fork needs to
447
+ adapt `src/clerk-handler.ts` to offer sign-in. Direct API key access works
448
+ without it.
449
+
450
+ Keep secrets out of `wrangler.jsonc`, since its `vars` are stored in plain text.
451
+ Set them as Worker secrets instead. A deploy fails if a secret listed in
452
+ `secrets.required` is missing.
453
+
454
+ ```bash
455
+ pnpm exec wrangler secret put OAUTH_CLIENT_ID -e production
456
+ pnpm exec wrangler secret put OAUTH_CLIENT_SECRET -e production
457
+ pnpm run deploy
458
+ ```
459
+
460
+ If your Cloudflare login can access several accounts, set
461
+ `CLOUDFLARE_ACCOUNT_ID`, for example in a local `.env` file, which git ignores.
462
+
463
+ ## License
464
+
465
+ [MIT](LICENSE)