@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.
Files changed (4) hide show
  1. package/LICENSE +21 -0
  2. package/README.md +651 -2
  3. package/dist/stdio.js +1047 -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,652 @@
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 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)