@yawlabs/npmjs-mcp 0.8.0 → 0.10.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (3) hide show
  1. package/README.md +241 -127
  2. package/dist/index.js +230 -86
  3. package/package.json +5 -1
package/README.md CHANGED
@@ -1,29 +1,42 @@
1
1
  # @yawlabs/npmjs-mcp
2
2
 
3
- MCP server for the [npm](https://www.npmjs.com) registry. Package intelligence, security audits, dependency analysis, and org management from any MCP-compatible AI assistant.
3
+ [![npm version](https://img.shields.io/npm/v/@yawlabs/npmjs-mcp)](https://www.npmjs.com/package/@yawlabs/npmjs-mcp)
4
+ [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
5
+ [![GitHub stars](https://img.shields.io/github/stars/YawLabs/npmjs-mcp)](https://github.com/YawLabs/npmjs-mcp/stargazers)
6
+ [![CI](https://github.com/YawLabs/npmjs-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/YawLabs/npmjs-mcp/actions/workflows/ci.yml) [![Release](https://github.com/YawLabs/npmjs-mcp/actions/workflows/release.yml/badge.svg)](https://github.com/YawLabs/npmjs-mcp/actions/workflows/release.yml)
4
7
 
5
- ## Quick start
8
+ **Run npm registry operations from Claude Code, Cursor, and any MCP client.** 63 tools covering the full registry surface: package intelligence, security audits, dependency analysis, org/team management, and the write ops that normally fight you locally (`npm deprecate`, `npm dist-tag`, `npm owner`, `npm unpublish`).
6
9
 
7
- ```bash
8
- npx @yawlabs/npmjs-mcp
9
- ```
10
+ Built and maintained by [Yaw Labs](https://yaw.sh).
10
11
 
11
- ## Setup
12
+ [![Add to mcp.hosting](https://mcp.hosting/install-button.svg)](https://mcp.hosting/install?name=npm&command=npx&args=-y%2C%40yawlabs%2Fnpmjs-mcp&env=NPM_TOKEN&description=npm%20registry%20-%20package%20intel%2C%20security%2C%20dependency%20analysis%2C%20write%20ops&source=https%3A%2F%2Fgithub.com%2FYawLabs%2Fnpmjs-mcp)
12
13
 
13
- No API key is required for read-only tools (search, packages, downloads, security, analysis). For authenticated tools (auth, access, orgs, hooks), set your npm token:
14
+ One click adds this to your [mcp.hosting](https://mcp.hosting) account so it syncs to every MCP client you use. Or install manually below.
14
15
 
15
- ```bash
16
- export NPM_TOKEN="your-token"
17
- ```
16
+ ## Why this one?
17
+
18
+ Other npm MCP servers wrap `npm search` and call it done. This one doesn't.
18
19
 
19
- ### Claude Code
20
+ - **Full registry HTTP surface** — 63 tools across reads, writes, orgs, teams, hooks, provenance, trusted publishers, and ops health. Not just `npm view`.
21
+ - **Write ops that actually work in agents** — `npm_deprecate`, `npm_dist_tag_set`, `npm_owner_add`, `npm_unpublish_version` go directly to the HTTP API with your token. No 2FA prompts, no `--otp` hunts, no `ENEEDAUTH` from a session-bound `.npmrc`.
22
+ - **Agent-aware failure surfacing** — write tools detect non-interactive context and return specific human-runnable commands (`npm login --auth-type=web`) instead of looping on unrecoverable errors.
23
+ - **Safety by default** — `npm_unpublish_*` requires `confirm: true`. `npm_owner_remove` blocks you from locking yourself out. `npm_deprecate` validates the message format (em-dash, no trailing period) that npmjs.com's API actually accepts.
24
+ - **Ops playbook built in** — `npm_ops_playbook` returns the canonical tool-vs-CLI-vs-CI decision matrix so your agent picks the right path on the first try.
25
+ - **Tool annotations** — every tool declares `readOnlyHint`, `destructiveHint`, `idempotentHint`, and `openWorldHint`, so MCP clients can skip confirmation on safe ops.
26
+ - **No API key required for reads** — search, packages, downloads, security, dep tree, licenses all work anonymously. Auth is opt-in via `NPM_TOKEN`.
27
+ - **Instant startup** — ships as a single bundled file with zero runtime dependencies. No 5-minute `node_modules` install.
28
+ - **Input hardening** — package names, scopes, versions, dist-tags, and team names are all regex-validated against npm's actual constraints. Defends against CRLF and path-traversal in URL construction.
29
+
30
+ ## Quick start
20
31
 
21
- Add to your MCP config:
32
+ **1. Create `.mcp.json` in your project root**
33
+
34
+ macOS / Linux / WSL:
22
35
 
23
36
  ```json
24
37
  {
25
38
  "mcpServers": {
26
- "npmjs": {
39
+ "npm": {
27
40
  "command": "npx",
28
41
  "args": ["-y", "@yawlabs/npmjs-mcp"]
29
42
  }
@@ -31,153 +44,254 @@ Add to your MCP config:
31
44
  }
32
45
  ```
33
46
 
34
- With authentication:
47
+ Windows:
35
48
 
36
49
  ```json
37
50
  {
38
51
  "mcpServers": {
39
- "npmjs": {
40
- "command": "npx",
41
- "args": ["-y", "@yawlabs/npmjs-mcp"],
42
- "env": {
43
- "NPM_TOKEN": "your-token"
44
- }
52
+ "npm": {
53
+ "command": "cmd",
54
+ "args": ["/c", "npx", "-y", "@yawlabs/npmjs-mcp"]
45
55
  }
46
56
  }
47
57
  }
48
58
  ```
49
59
 
50
- ### Claude Desktop
60
+ > **Why the extra step on Windows?** Since Node 20, `child_process.spawn` cannot directly execute `.cmd` files (that's what `npx` is on Windows). Wrapping with `cmd /c` is the standard workaround.
61
+
62
+ **2. Restart and approve**
63
+
64
+ Restart Claude Code (or your MCP client) and approve the npm MCP server when prompted.
51
65
 
52
- Add to `claude_desktop_config.json`:
66
+ **3. (Optional) Add your npm token for write operations**
67
+
68
+ Read-only tools work without any setup. For write tools (`deprecate`, `dist-tag`, `owner`, `team_*`, `org_member_*`, `unpublish`, `hook_*`, `access_set*`, `token_revoke`), add `NPM_TOKEN` to the `env` block:
53
69
 
54
70
  ```json
55
71
  {
56
72
  "mcpServers": {
57
- "npmjs": {
73
+ "npm": {
58
74
  "command": "npx",
59
75
  "args": ["-y", "@yawlabs/npmjs-mcp"],
60
76
  "env": {
61
- "NPM_TOKEN": "your-token"
77
+ "NPM_TOKEN": "npm_xxxxxxxxxxxx"
62
78
  }
63
79
  }
64
80
  }
65
81
  }
66
82
  ```
67
83
 
84
+ Use a [Granular Access Token](https://docs.npmjs.com/creating-and-viewing-access-tokens#creating-granular-access-tokens) scoped to just the packages and orgs you want your agent to manage.
85
+
86
+ That's it. Now ask your AI assistant:
87
+
88
+ > "Deprecate my-old-pkg 1.x with a pointer to v2"
89
+ >
90
+ > "What's the dep tree for fastify look like three levels deep?"
91
+ >
92
+ > "Audit express for known CVEs and tell me the fix"
93
+ >
94
+ > "Who are the maintainers of next.js and when did each one last publish?"
95
+
96
+ ## Configuration
97
+
98
+ | Environment variable | Default | Description |
99
+ |---|---|---|
100
+ | `NPM_TOKEN` | (none) | npm access token. Required only for write/auth/org/access/hooks tools. A Granular Access Token is strongly preferred over a Classic Automation token. |
101
+ | `NPM_REGISTRY` | `https://registry.npmjs.org` | Alternate registry (enterprise/private). Must support the npm HTTP API shape. |
102
+
103
+ **Alternate MCP clients:**
104
+
105
+ | Client | Config file |
106
+ |---|---|
107
+ | Claude Code | `.mcp.json` (project root) or `~/.claude.json` (global) |
108
+ | Claude Desktop | `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) |
109
+ | Cursor | `~/.cursor/mcp.json` |
110
+ | Windsurf | `~/.codeium/windsurf/mcp_config.json` |
111
+ | VS Code | `.vscode/mcp.json` |
112
+
113
+ Use the same JSON block shown above in any of these.
114
+
68
115
  ## Tools (63)
69
116
 
70
- ### Search
71
- - `npm_search` — Search the npm registry with qualifiers (keywords, author, scope)
72
-
73
- ### Packages
74
- - `npm_package` — Get package metadata (description, dist-tags, maintainers, license)
75
- - `npm_version` — Get detailed metadata for a specific version
76
- - `npm_versions` — List all published versions with dates
77
- - `npm_readme` — Get README content
78
- - `npm_dist_tags` — Get dist-tags (latest, next, beta, etc)
79
- - `npm_types` — Check TypeScript type support (built-in types or @types/*)
80
-
81
- ### Dependencies
82
- - `npm_dependencies` — Get dependency lists (prod, dev, peer, optional)
83
- - `npm_dep_tree` — Resolve transitive dependency tree (configurable depth)
84
- - `npm_license_check` — Check licenses of a package and its direct deps
85
-
86
- ### Downloads
87
- - `npm_downloads` — Get total download count for a period
88
- - `npm_downloads_range` — Get daily download breakdown
89
- - `npm_downloads_bulk` — Compare downloads for up to 128 packages
90
- - `npm_version_downloads` — Per-version download counts
91
-
92
- ### Security
93
- - `npm_audit` — Check packages for known vulnerabilities
94
- - `npm_audit_deep` — Full audit with CVSS scores, CWEs, fix recommendations
95
- - `npm_signing_keys` — Get registry ECDSA signing keys
96
-
97
- ### Analysis
98
- - `npm_compare` — Compare 2-5 packages side-by-side
99
- - `npm_health` — Assess maintenance, downloads, security, deprecation status
100
- - `npm_maintainers` — Get maintainers and their publish history
101
- - `npm_release_frequency` — Analyze release cadence and gaps
102
-
103
- ### Registry
104
- - `npm_registry_stats` — Total npm-wide download counts
105
- - `npm_recent_changes` — Recent package publishes from the CouchDB changes feed
106
- - `npm_ops_playbook` — Canonical recipes for npm operations (call this FIRST when unsure which tool to use)
107
-
108
- ### Provenance
109
- - `npm_provenance` — Get Sigstore provenance attestations (SLSA, publish)
110
-
111
- ### Trusted Publishers (requires NPM_TOKEN)
112
- - `npm_trusted_publishers` — List OIDC trust relationships with CI/CD providers
113
-
114
- ### Auth (requires NPM_TOKEN)
115
- - `npm_whoami` — Check authenticated user
116
- - `npm_profile` — Get profile, email, 2FA status
117
- - `npm_tokens` — List access tokens
118
- - `npm_verify_token` — One-call capability check (call this FIRST when debugging write failures)
119
- - `npm_user_packages` — List packages published by a user
120
-
121
- ### Access (requires NPM_TOKEN)
122
- - `npm_collaborators` — List package collaborators and permissions
123
- - `npm_package_access` — Get package access settings
124
-
125
- ### Organizations (requires NPM_TOKEN)
126
- - `npm_org_members` — List org members and roles
127
- - `npm_org_packages` — List org packages
128
- - `npm_org_teams` — List org teams
129
- - `npm_team_packages` — List team package permissions
130
-
131
- ### Workflows
132
- - `npm_check_auth` — Auth health check with headless publish feasibility
133
- - `npm_publish_preflight` — Pre-publish validation checklist
134
-
135
- ### Write Operations (requires NPM_TOKEN with write scope)
136
-
137
- These bypass the CLI/2FA friction that causes `npm deprecate` and similar commands to 422 locally. All use the HTTP API with your `NPM_TOKEN`.
138
-
139
- - `npm_deprecate` — Deprecate a package or specific versions (validates message format)
140
- - `npm_undeprecate` — Clear deprecation
141
- - `npm_unpublish_version` — Unpublish a specific version (requires `confirm: true`)
142
- - `npm_unpublish_package` — Unpublish an entire package (requires `confirm: true`)
143
- - `npm_dist_tag_set` — Point a dist-tag at a version
144
- - `npm_dist_tag_remove` — Remove a dist-tag (except `latest`)
145
- - `npm_owner_add` — Add a maintainer (resolves user via `/-/user/`)
146
- - `npm_owner_remove` — Remove a maintainer (prevents lockout)
147
- - `npm_access_set` — Set public/private/restricted access
148
- - `npm_access_set_mfa` — Configure 2FA requirement for publish (none/publish/automation)
149
- - `npm_team_grant` / `npm_team_revoke` — Grant/revoke team permissions on a package
150
- - `npm_team_create` / `npm_team_delete` — Create/delete a team in an org
151
- - `npm_team_member_add` / `npm_team_member_remove` — Manage team members
152
- - `npm_org_member_set` / `npm_org_member_remove` — Add/remove org members, set roles
153
- - `npm_token_revoke` — Revoke an access token by key (creation requires a password and isn't exposed)
154
-
155
- ### Webhooks (requires NPM_TOKEN)
156
- - `npm_hook_add` — Register a webhook on a package, scope, or user
157
- - `npm_hook_list` — List webhooks (optional package filter)
158
- - `npm_hook_get` — Fetch a single webhook
159
- - `npm_hook_update` — Update endpoint/secret of a webhook
160
- - `npm_hook_remove` — Delete a webhook
161
-
162
- ### Operation Decision Matrix
117
+ ### Search (1)
118
+ - **npm_search** — Search the npm registry with qualifiers (keywords, author, scope).
119
+
120
+ ### Packages (6)
121
+ - **npm_package** — Metadata: description, dist-tags, maintainers, license, repository.
122
+ - **npm_version** — Detailed metadata for a specific version.
123
+ - **npm_versions** — All published versions with dates.
124
+ - **npm_readme** — README content.
125
+ - **npm_dist_tags** — Dist-tags (latest, next, beta, etc).
126
+ - **npm_types** — TypeScript type support (built-in types or `@types/*`).
127
+
128
+ ### Dependencies (3)
129
+ - **npm_dependencies** — Dependency lists (prod, dev, peer, optional).
130
+ - **npm_dep_tree** — Transitive dependency tree (configurable depth).
131
+ - **npm_license_check** — License audit of a package and its direct deps.
132
+
133
+ ### Downloads (4)
134
+ - **npm_downloads** — Total download count for a period.
135
+ - **npm_downloads_range** — Daily download breakdown.
136
+ - **npm_downloads_bulk** — Compare downloads for up to 128 packages.
137
+ - **npm_version_downloads** — Per-version download counts.
138
+
139
+ ### Security (3)
140
+ - **npm_audit** — Check packages for known vulnerabilities.
141
+ - **npm_audit_deep** — Full audit with CVSS scores, CWEs, fix recommendations.
142
+ - **npm_signing_keys** — Registry ECDSA signing keys.
143
+
144
+ ### Analysis (4)
145
+ - **npm_compare** — Compare 2–5 packages side-by-side.
146
+ - **npm_health** — Maintenance, downloads, security, deprecation summary.
147
+ - **npm_maintainers** — Maintainers and publish history.
148
+ - **npm_release_frequency** — Release cadence and gaps.
149
+
150
+ ### Registry (3)
151
+ - **npm_registry_stats** — Total npm-wide download counts.
152
+ - **npm_recent_changes** — Recent publishes from the CouchDB changes feed.
153
+ - **npm_ops_playbook** — Canonical recipes for npm operations. **Call this first** when unsure which tool to use.
154
+
155
+ ### Provenance & trust (2)
156
+ - **npm_provenance** — Sigstore attestations (SLSA, publish).
157
+ - **npm_trusted_publishers** — OIDC trust relationships with CI/CD providers.
158
+
159
+ ### Auth (5, requires NPM_TOKEN)
160
+ - **npm_whoami** — Authenticated user.
161
+ - **npm_profile** — Profile, email, 2FA status.
162
+ - **npm_tokens** — List access tokens.
163
+ - **npm_verify_token** — One-call capability check. **Call this first** when debugging write failures.
164
+ - **npm_user_packages** — Packages published by a user.
165
+
166
+ ### Access & orgs (6, requires NPM_TOKEN)
167
+ - **npm_collaborators** — Package collaborators and permissions.
168
+ - **npm_package_access** — Package access settings.
169
+ - **npm_org_members** — Org members and roles.
170
+ - **npm_org_packages** — Org packages.
171
+ - **npm_org_teams** — Org teams.
172
+ - **npm_team_packages** — Team package permissions.
173
+
174
+ ### Workflows (2)
175
+ - **npm_check_auth** — Auth health check with headless publish feasibility.
176
+ - **npm_publish_preflight** — Pre-publish validation checklist.
177
+
178
+ ### Write operations (19, requires NPM_TOKEN with write scope)
179
+
180
+ These bypass the CLI/2FA friction that makes `npm deprecate` and friends fail locally. All use the HTTP API with your `NPM_TOKEN`.
181
+
182
+ - **npm_deprecate** — Deprecate a package or specific versions (validates message format).
183
+ - **npm_undeprecate** — Clear deprecation.
184
+ - **npm_unpublish_version** — Unpublish a version. Requires `confirm: true`.
185
+ - **npm_unpublish_package** — Unpublish an entire package. Requires `confirm: true`.
186
+ - **npm_dist_tag_set** — Point a dist-tag at a version.
187
+ - **npm_dist_tag_remove** — Remove a dist-tag (refuses `latest`).
188
+ - **npm_owner_add** — Add a maintainer (resolves user via `/-/user/`).
189
+ - **npm_owner_remove** — Remove a maintainer (prevents self-lockout).
190
+ - **npm_access_set** — Set public/private/restricted access.
191
+ - **npm_access_set_mfa** — Configure 2FA requirement (none/publish/automation).
192
+ - **npm_team_grant** / **npm_team_revoke** — Grant/revoke team permissions on a package.
193
+ - **npm_team_create** / **npm_team_delete** — Create/delete a team in an org.
194
+ - **npm_team_member_add** / **npm_team_member_remove** — Manage team members.
195
+ - **npm_org_member_set** / **npm_org_member_remove** — Manage org membership and roles.
196
+ - **npm_token_revoke** — Revoke an access token by key.
197
+
198
+ ### Webhooks (5, requires NPM_TOKEN)
199
+ - **npm_hook_add** — Register a webhook on a package, scope, or user.
200
+ - **npm_hook_list** — List webhooks (optional package filter).
201
+ - **npm_hook_get** — Fetch a single webhook.
202
+ - **npm_hook_update** — Update endpoint/secret.
203
+ - **npm_hook_remove** — Delete a webhook.
204
+
205
+ ## Operation decision matrix
163
206
 
164
207
  | Operation | Preferred path | Why |
165
208
  |---|---|---|
166
- | Read (search/view/stats) | These MCP tools, no auth required | Fast, zero friction |
167
- | Deprecate / dist-tag / owner | `npm_deprecate`, `npm_dist_tag_*`, `npm_owner_*` | HTTP API, no CLI auth issues |
209
+ | Read (search/view/stats) | These MCP tools, no auth | Fast, zero friction |
210
+ | Deprecate / dist-tag / owner / team / hook | `npm_deprecate`, `npm_dist_tag_*`, etc. | HTTP API, no CLI 2FA friction |
168
211
  | Publish | CI tag-push workflow | Version discipline, provenance, org token |
169
212
  | Unpublish | `npm_unpublish_version` (with `confirm: true`) | Safer than CLI; irreversible within 72h |
170
- | CLI fallback (only if MCP returns 422) | `npm login --auth-type=web` then `npm <op>` | End-user interactive path |
213
+ | CLI fallback (rare) | `npm login --auth-type=web` then `npm <op>` | Only if MCP returns 422 |
214
+
215
+ Call `npm_ops_playbook` at the start of any session to get the up-to-date matrix.
216
+
217
+ ## Examples
218
+
219
+ ### Audit a dependency
220
+
221
+ ```
222
+ > "What vulnerabilities does lodash 4.17.20 have and what's the fix?"
223
+ → npm_audit_deep({ name: "lodash", version: "4.17.20" })
224
+ ```
225
+
226
+ ### Deprecate a package
227
+
228
+ ```
229
+ > "Deprecate @myorg/legacy-sdk with a pointer to @myorg/sdk"
230
+ → npm_deprecate({ name: "@myorg/legacy-sdk", message: "Renamed to @myorg/sdk — install that instead" })
231
+ ```
232
+
233
+ ### Compare package health
234
+
235
+ ```
236
+ > "Compare fastify vs express vs koa for maintenance health"
237
+ → npm_compare({ names: ["fastify", "express", "koa"] })
238
+ → npm_health({ name: "fastify" }) // ...etc
239
+ ```
240
+
241
+ ### Rotate a dist-tag
242
+
243
+ ```
244
+ > "Point @myorg/pkg@latest at 3.2.1"
245
+ → npm_dist_tag_set({ name: "@myorg/pkg", tag: "latest", version: "3.2.1" })
246
+ ```
247
+
248
+ ### Debug a write failure
249
+
250
+ ```
251
+ > "My deprecate keeps returning 422 — what's wrong?"
252
+ → npm_verify_token() // Confirms token scope, packages, 2FA state
253
+ → npm_ops_playbook() // Returns the canonical retry sequence
254
+ ```
255
+
256
+ ## Troubleshooting
257
+
258
+ **"Error: NPM_TOKEN is required"**
259
+
260
+ - The tool you called needs auth. Add `NPM_TOKEN` to the `env` block of your MCP config and restart the client.
261
+ - Prefer a [Granular Access Token](https://docs.npmjs.com/creating-and-viewing-access-tokens#creating-granular-access-tokens) scoped to just the packages and orgs you want touched.
262
+
263
+ **"HTTP 401 Unauthorized" or "HTTP 403 Forbidden"**
264
+
265
+ - Your token lacks scope on the target package. Call `npm_verify_token` — it reports which packages and orgs the token can actually write.
266
+ - If the package requires 2FA for writes, your token must be an automation token or come from an OIDC trusted publisher. A user token will 403.
267
+
268
+ **"HTTP 422 Unprocessable" on deprecate**
171
269
 
172
- Call `npm_ops_playbook` at the start of any session for the up-to-date matrix.
270
+ - Common cause: message format. Use an em-dash and no trailing period: `"Renamed to @x/y — install that instead"`, not `"Renamed to @x/y. Install that instead."`
271
+ - Another: specifying a `versions` range that doesn't match any published version. Call `npm_versions` to confirm.
173
272
 
174
- ## Features
273
+ **Windows: MCP server doesn't start**
274
+
275
+ - Use the `cmd /c npx ...` pattern from the Quick start section. Node 20+ can't spawn `.cmd` files directly.
276
+
277
+ ## Requirements
278
+
279
+ - Node.js 18+
280
+ - (Optional) npm access token for write operations
281
+
282
+ ## Contributing
283
+
284
+ ```bash
285
+ git clone https://github.com/YawLabs/npmjs-mcp.git
286
+ cd npmjs-mcp
287
+ npm install
288
+ npm run lint # Biome check
289
+ npm run lint:fix # Auto-fix
290
+ npm run build # tsc + esbuild bundle
291
+ npm test # node --test
292
+ ```
175
293
 
176
- - **63 tools** covering search, packages, deps, downloads, security, analysis, auth, orgs, access, provenance, trust, publish workflows, write operations, and registry webhooks
177
- - **No API key required** for read-only tools — authenticated tools opt-in via NPM_TOKEN
178
- - **Zero runtime dependencies** — Single bundled file for instant `npx` startup
179
- - **Agent-aware publish tools** — Detects non-interactive context, provides human hand-off actions instead of unworkable retries
180
- - **MCP annotations** — Every tool declares read-only, destructive, and idempotent hints
294
+ See [CONTRIBUTING.md](CONTRIBUTING.md) for the full workflow, including release process.
181
295
 
182
296
  ## License
183
297
 
package/dist/index.js CHANGED
@@ -21011,12 +21011,39 @@ var StdioServerTransport = class {
21011
21011
  };
21012
21012
 
21013
21013
  // src/api.ts
21014
- var REGISTRY_URL = "https://registry.npmjs.org";
21014
+ var DEFAULT_REGISTRY_URL = "https://registry.npmjs.org";
21015
21015
  var DOWNLOADS_URL = "https://api.npmjs.org";
21016
21016
  var REPLICATE_URL = "https://replicate.npmjs.com";
21017
- var REQUEST_TIMEOUT_MS = 3e4;
21017
+ var DEFAULT_TIMEOUT_MS = 3e4;
21018
+ var DEFAULT_BACKOFF_MS = 500;
21019
+ var MAX_RETRIES = 2;
21020
+ var RETRYABLE_STATUSES = /* @__PURE__ */ new Set([429, 502, 503, 504]);
21021
+ function getRegistryUrl() {
21022
+ return (process.env.NPM_REGISTRY || DEFAULT_REGISTRY_URL).replace(/\/+$/, "");
21023
+ }
21024
+ function getTimeoutMs() {
21025
+ const raw = process.env.NPM_REQUEST_TIMEOUT_MS;
21026
+ if (!raw) return DEFAULT_TIMEOUT_MS;
21027
+ const parsed = Number(raw);
21028
+ return Number.isFinite(parsed) && parsed > 0 ? parsed : DEFAULT_TIMEOUT_MS;
21029
+ }
21030
+ function getBackoffMs(attempt) {
21031
+ const raw = process.env.NPM_RETRY_BACKOFF_MS;
21032
+ const parsed = raw !== void 0 ? Number(raw) : Number.NaN;
21033
+ const base = Number.isFinite(parsed) && parsed >= 0 ? parsed : DEFAULT_BACKOFF_MS;
21034
+ return base * 2 ** attempt;
21035
+ }
21036
+ function debugEnabled() {
21037
+ const v = process.env.DEBUG;
21038
+ return v === "npmjs-mcp" || v === "*";
21039
+ }
21040
+ function debug(msg) {
21041
+ if (debugEnabled()) console.error(`[npmjs-mcp] ${msg}`);
21042
+ }
21018
21043
  var PACKAGE_NAME_MAX_LENGTH = 214;
21019
21044
  var PACKAGE_NAME_PATTERN = /^(?:@[a-zA-Z0-9][a-zA-Z0-9\-_.]*\/)?[a-zA-Z0-9][a-zA-Z0-9\-_.]*$/;
21045
+ var IDENT_MAX_LENGTH = 214;
21046
+ var IDENT_PATTERN = /^[a-zA-Z0-9][a-zA-Z0-9\-_.]*$/;
21020
21047
  function validatePackageName(name) {
21021
21048
  if (typeof name !== "string" || name.length === 0) return "Package name is empty";
21022
21049
  if (name.length > PACKAGE_NAME_MAX_LENGTH) {
@@ -21027,11 +21054,43 @@ function validatePackageName(name) {
21027
21054
  }
21028
21055
  return null;
21029
21056
  }
21057
+ function validateIdent(value, label) {
21058
+ if (typeof value !== "string" || value.length === 0) return `${label} is empty`;
21059
+ if (value.length > IDENT_MAX_LENGTH) return `${label} exceeds ${IDENT_MAX_LENGTH} characters`;
21060
+ if (!IDENT_PATTERN.test(value)) {
21061
+ return `Invalid ${label.toLowerCase()} '${value}'. Must start alphanumeric and contain only [a-zA-Z0-9-_.].`;
21062
+ }
21063
+ return null;
21064
+ }
21065
+ function validateScope(scope) {
21066
+ return validateIdent(scope.replace(/^@/, ""), "Scope");
21067
+ }
21068
+ function validateUsername(username) {
21069
+ return validateIdent(username.replace(/^@/, ""), "Username");
21070
+ }
21071
+ function validateTeam(team) {
21072
+ return validateIdent(team, "Team name");
21073
+ }
21030
21074
  function encPkg(name) {
21031
21075
  const err = validatePackageName(name);
21032
21076
  if (err) throw new Error(err);
21033
21077
  return name.startsWith("@") ? `@${encodeURIComponent(name.slice(1))}` : encodeURIComponent(name);
21034
21078
  }
21079
+ function encScope(scope) {
21080
+ const err = validateScope(scope);
21081
+ if (err) throw new Error(err);
21082
+ return encodeURIComponent(scope.replace(/^@/, ""));
21083
+ }
21084
+ function encUser(username) {
21085
+ const err = validateUsername(username);
21086
+ if (err) throw new Error(err);
21087
+ return encodeURIComponent(username.replace(/^@/, ""));
21088
+ }
21089
+ function encTeam(team) {
21090
+ const err = validateTeam(team);
21091
+ if (err) throw new Error(err);
21092
+ return encodeURIComponent(team);
21093
+ }
21035
21094
  function isAuthenticated() {
21036
21095
  return !!process.env.NPM_TOKEN;
21037
21096
  }
@@ -21047,6 +21106,17 @@ function authHeaders() {
21047
21106
  const token = process.env.NPM_TOKEN;
21048
21107
  return token ? { Authorization: `Bearer ${token}` } : {};
21049
21108
  }
21109
+ function parseRetryAfter(header) {
21110
+ if (!header) return null;
21111
+ const seconds = Number(header);
21112
+ if (Number.isFinite(seconds) && seconds >= 0) return seconds * 1e3;
21113
+ const date3 = Date.parse(header);
21114
+ if (!Number.isNaN(date3)) return Math.max(0, date3 - Date.now());
21115
+ return null;
21116
+ }
21117
+ function sleep(ms) {
21118
+ return new Promise((resolve) => setTimeout(resolve, ms));
21119
+ }
21050
21120
  async function request(baseUrl, path, options) {
21051
21121
  const method = options?.method ?? "GET";
21052
21122
  const headers = {
@@ -21059,49 +21129,75 @@ async function request(baseUrl, path, options) {
21059
21129
  fetchBody = JSON.stringify(options.body);
21060
21130
  }
21061
21131
  const url = `${baseUrl}${path}`;
21062
- try {
21063
- const res = await fetch(url, {
21064
- method,
21065
- headers,
21066
- body: fetchBody,
21067
- signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS)
21068
- });
21069
- if (!res.ok) {
21070
- const errorBody = await res.text();
21071
- return { ok: false, status: res.status, error: errorBody };
21072
- }
21073
- if (res.status === 204 || res.headers.get("content-length") === "0") {
21074
- return { ok: true, status: res.status };
21132
+ for (let attempt = 0; attempt <= MAX_RETRIES; attempt++) {
21133
+ const started = Date.now();
21134
+ try {
21135
+ const res = await fetch(url, {
21136
+ method,
21137
+ headers,
21138
+ body: fetchBody,
21139
+ signal: AbortSignal.timeout(getTimeoutMs())
21140
+ });
21141
+ if (RETRYABLE_STATUSES.has(res.status) && attempt < MAX_RETRIES) {
21142
+ const retryAfter = parseRetryAfter(res.headers.get("Retry-After"));
21143
+ const waitMs = retryAfter ?? getBackoffMs(attempt);
21144
+ debug(`${method} ${url} -> ${res.status} retry in ${waitMs}ms (attempt ${attempt + 1}/${MAX_RETRIES + 1})`);
21145
+ try {
21146
+ await res.text();
21147
+ } catch {
21148
+ }
21149
+ await sleep(waitMs);
21150
+ continue;
21151
+ }
21152
+ const elapsed = Date.now() - started;
21153
+ if (!res.ok) {
21154
+ const errorBody = await res.text();
21155
+ debug(`${method} ${url} -> ${res.status} ${elapsed}ms`);
21156
+ return { ok: false, status: res.status, error: errorBody };
21157
+ }
21158
+ if (res.status === 204 || res.headers.get("content-length") === "0") {
21159
+ debug(`${method} ${url} -> ${res.status} ${elapsed}ms`);
21160
+ return { ok: true, status: res.status };
21161
+ }
21162
+ const data = await res.json();
21163
+ debug(`${method} ${url} -> ${res.status} ${elapsed}ms`);
21164
+ return { ok: true, status: res.status, data };
21165
+ } catch (err) {
21166
+ const message = err instanceof Error ? err.message : String(err);
21167
+ if (attempt < MAX_RETRIES) {
21168
+ const waitMs = getBackoffMs(attempt);
21169
+ debug(`${method} ${url} -> network error retry in ${waitMs}ms (${message})`);
21170
+ await sleep(waitMs);
21171
+ continue;
21172
+ }
21173
+ debug(`${method} ${url} -> network error: ${message}`);
21174
+ return { ok: false, status: 0, error: message };
21075
21175
  }
21076
- const data = await res.json();
21077
- return { ok: true, status: res.status, data };
21078
- } catch (err) {
21079
- const message = err instanceof Error ? err.message : String(err);
21080
- return { ok: false, status: 0, error: message };
21081
21176
  }
21177
+ return { ok: false, status: 0, error: "unreachable" };
21082
21178
  }
21083
21179
  function registryGet(path) {
21084
- return request(REGISTRY_URL, path);
21180
+ return request(getRegistryUrl(), path);
21085
21181
  }
21086
21182
  function registryGetAbbreviated(path) {
21087
- return request(REGISTRY_URL, path, {
21183
+ return request(getRegistryUrl(), path, {
21088
21184
  headers: { Accept: "application/vnd.npm.install-v1+json" }
21089
21185
  });
21090
21186
  }
21091
21187
  function registryPost(path, body) {
21092
- return request(REGISTRY_URL, path, { method: "POST", body });
21188
+ return request(getRegistryUrl(), path, { method: "POST", body });
21093
21189
  }
21094
21190
  function registryGetAuth(path) {
21095
- return request(REGISTRY_URL, path, { headers: authHeaders() });
21191
+ return request(getRegistryUrl(), path, { headers: authHeaders() });
21096
21192
  }
21097
21193
  function registryPostAuth(path, body) {
21098
- return request(REGISTRY_URL, path, { method: "POST", body, headers: authHeaders() });
21194
+ return request(getRegistryUrl(), path, { method: "POST", body, headers: authHeaders() });
21099
21195
  }
21100
21196
  function registryPutAuth(path, body) {
21101
- return request(REGISTRY_URL, path, { method: "PUT", body, headers: authHeaders() });
21197
+ return request(getRegistryUrl(), path, { method: "PUT", body, headers: authHeaders() });
21102
21198
  }
21103
21199
  function registryDeleteAuth(path, body) {
21104
- return request(REGISTRY_URL, path, { method: "DELETE", body, headers: authHeaders() });
21200
+ return request(getRegistryUrl(), path, { method: "DELETE", body, headers: authHeaders() });
21105
21201
  }
21106
21202
  function downloadsGet(path) {
21107
21203
  return request(DOWNLOADS_URL, path);
@@ -21269,12 +21365,12 @@ function translateError(res, context) {
21269
21365
  case 422:
21270
21366
  return {
21271
21367
  ...res,
21272
- error: `Registry rejected the request payload${pkgPart}${opPart} (422 Unprocessable Entity). Most common causes: (1) invalid semver range \u2014 validate with npm_package versions first; (2) deprecation message format \u2014 em-dash form works, period-capital form sometimes 422s; (3) account-level 2FA policy requires interactive CLI session. If #3, CLI fallback: \`npm login --auth-type=web\` followed by the npm CLI command. Raw: ${res.error}`
21368
+ error: `Registry rejected the request payload${pkgPart}${opPart} (422 Unprocessable Entity). Most common causes: (1) semver range matches no published versions \u2014 validate with npm_versions first; (2) deprecation message exceeds 1024 characters; (3) account-level 2FA policy requires an interactive CLI session. If #3, CLI fallback: \`npm login --auth-type=web\` followed by the equivalent npm CLI command. Raw: ${res.error}`
21273
21369
  };
21274
21370
  case 429:
21275
21371
  return {
21276
21372
  ...res,
21277
- error: `Rate limited${opPart}. Wait 60 seconds and retry. Raw: ${res.error}`
21373
+ error: `Rate limited${opPart}. Retried automatically and still failed \u2014 wait longer and retry, or contact npm support if this persists. Raw: ${res.error}`
21278
21374
  };
21279
21375
  case 0:
21280
21376
  return {
@@ -21289,10 +21385,6 @@ function validateDeprecationMessage(msg) {
21289
21385
  if (msg.length > 1024) {
21290
21386
  return "Deprecation message exceeds 1024 characters (registry limit).";
21291
21387
  }
21292
- if (msg.length === 0) return null;
21293
- if (/\.\s+[A-Z]/.test(msg)) {
21294
- return `Deprecation message contains the "period + space + capital letter" pattern that has triggered 422 Unprocessable Entity on at least one scoped package. The working form uses em-dash and lowercase continuation: e.g. "Renamed to @yawlabs/spend \u2014 install that instead". Pass force: true to bypass this validation.`;
21295
- }
21296
21388
  return null;
21297
21389
  }
21298
21390
  function versionsMatchingRange(versions, range, maxSatisfying2) {
@@ -22030,10 +22122,24 @@ function classifyHookTarget(target) {
22030
22122
  if (/^@[^/]+$/.test(target)) return { type: "scope", name: target };
22031
22123
  return { type: "package", name: target };
22032
22124
  }
22125
+ function stripSecrets(data) {
22126
+ if (Array.isArray(data)) {
22127
+ return data.map((item) => stripSecrets(item));
22128
+ }
22129
+ if (data !== null && typeof data === "object") {
22130
+ const out = {};
22131
+ for (const [k, v] of Object.entries(data)) {
22132
+ if (k === "secret") continue;
22133
+ out[k] = stripSecrets(v);
22134
+ }
22135
+ return out;
22136
+ }
22137
+ return data;
22138
+ }
22033
22139
  var hookTools = [
22034
22140
  {
22035
22141
  name: "npm_hook_add",
22036
- description: "Create a registry webhook. Target is 'pkg' or '@scope/pkg' for a package, '@scope' for a scope, or '~user' for a user's packages. Endpoint is the HTTPS URL to POST events to; secret is used to HMAC-sign payloads.",
22142
+ description: "Create a registry webhook. Target is 'pkg' or '@scope/pkg' for a package, '@scope' for a scope, or '~user' for a user's packages. Endpoint is the HTTPS URL to POST events to; secret is used to HMAC-sign payloads. The secret is never echoed back in tool responses.",
22037
22143
  annotations: {
22038
22144
  title: "Add webhook",
22039
22145
  readOnlyHint: false,
@@ -22057,12 +22163,12 @@ var hookTools = [
22057
22163
  secret: input.secret
22058
22164
  });
22059
22165
  if (!res.ok) return translateError(res, { op: `hook_add ${input.target}` });
22060
- return { ok: true, status: 200, data: res.data };
22166
+ return { ok: true, status: 200, data: stripSecrets(res.data) };
22061
22167
  }
22062
22168
  },
22063
22169
  {
22064
22170
  name: "npm_hook_list",
22065
- description: "List webhooks. Optionally filter by package name.",
22171
+ description: "List webhooks. Optionally filter by package name. Secrets are redacted from responses.",
22066
22172
  annotations: {
22067
22173
  title: "List webhooks",
22068
22174
  readOnlyHint: true,
@@ -22085,12 +22191,12 @@ var hookTools = [
22085
22191
  const q = qs.toString();
22086
22192
  const res = await registryGetAuth(`/-/npm/v1/hooks${q ? `?${q}` : ""}`);
22087
22193
  if (!res.ok) return translateError(res, { op: "hook_list" });
22088
- return { ok: true, status: 200, data: res.data };
22194
+ return { ok: true, status: 200, data: stripSecrets(res.data) };
22089
22195
  }
22090
22196
  },
22091
22197
  {
22092
22198
  name: "npm_hook_get",
22093
- description: "Get a single webhook by its ID.",
22199
+ description: "Get a single webhook by its ID. The stored secret is redacted from the response.",
22094
22200
  annotations: {
22095
22201
  title: "Get webhook",
22096
22202
  readOnlyHint: true,
@@ -22106,12 +22212,12 @@ var hookTools = [
22106
22212
  if (authErr) return authErr;
22107
22213
  const res = await registryGetAuth(`/-/npm/v1/hooks/hook/${encodeURIComponent(input.id)}`);
22108
22214
  if (!res.ok) return translateError(res, { op: `hook_get ${input.id}` });
22109
- return { ok: true, status: 200, data: res.data };
22215
+ return { ok: true, status: 200, data: stripSecrets(res.data) };
22110
22216
  }
22111
22217
  },
22112
22218
  {
22113
22219
  name: "npm_hook_update",
22114
- description: "Update a webhook's endpoint and/or secret.",
22220
+ description: "Update a webhook's endpoint and/or secret. The returned hook object has the secret redacted.",
22115
22221
  annotations: {
22116
22222
  title: "Update webhook",
22117
22223
  readOnlyHint: false,
@@ -22132,7 +22238,7 @@ var hookTools = [
22132
22238
  secret: input.secret
22133
22239
  });
22134
22240
  if (!res.ok) return translateError(res, { op: `hook_update ${input.id}` });
22135
- return { ok: true, status: 200, data: res.data };
22241
+ return { ok: true, status: 200, data: stripSecrets(res.data) };
22136
22242
  }
22137
22243
  },
22138
22244
  {
@@ -23151,7 +23257,16 @@ async function fetchPackument(pkg) {
23151
23257
  }
23152
23258
  function parseTeamTarget(target) {
23153
23259
  const m = target.match(/^@?([^:]+):(.+)$/);
23154
- return m ? { scope: m[1], team: m[2] } : null;
23260
+ if (!m) {
23261
+ return { error: `Team must be in the form '@scope:team' (got '${target}').` };
23262
+ }
23263
+ const scope = m[1];
23264
+ const team = m[2];
23265
+ const scopeErr = validateScope(scope);
23266
+ if (scopeErr) return { error: scopeErr };
23267
+ const teamErr = validateTeam(team);
23268
+ if (teamErr) return { error: teamErr };
23269
+ return { scope, team };
23155
23270
  }
23156
23271
  function highestVersion(versions) {
23157
23272
  const parsed = [];
@@ -23169,7 +23284,7 @@ var writeTools = [
23169
23284
  // ───────────────────────────────────────────────────────
23170
23285
  {
23171
23286
  name: "npm_deprecate",
23172
- description: "Deprecate a package or specific versions. Shows a warning message on install. Uses the HTTP API with NPM_TOKEN, bypassing the CLI auth friction that causes 422 errors on accounts with 2FA. Message format tip: the period-then-capital pattern ('... install that instead. Thanks.') has 422'd on at least one scoped package; em-dash form is the known-good workaround. Pass force: true to skip the preflight check if you want the exact message as-is.",
23287
+ description: "Deprecate a package or specific versions. Shows a warning message on install. Uses the HTTP API with NPM_TOKEN, bypassing the CLI auth friction that causes 422 errors on accounts with 2FA. Registry hard limit: deprecation messages must be <= 1024 characters. If the registry 422s, first verify the semver range matches at least one published version (npm_versions) \u2014 range/version mismatches are the most common cause, not message format.",
23173
23288
  annotations: {
23174
23289
  title: "Deprecate package",
23175
23290
  readOnlyHint: false,
@@ -23178,18 +23293,15 @@ var writeTools = [
23178
23293
  openWorldHint: true
23179
23294
  },
23180
23295
  inputSchema: external_exports.object({
23181
- name: external_exports.string().describe("Package name (e.g. '@yawlabs/tokenmeter-mcp')"),
23296
+ name: external_exports.string().describe("Package name (e.g. '@yawlabs/spend')"),
23182
23297
  message: external_exports.string().describe("Deprecation message. Empty string to clear deprecation (use npm_undeprecate instead)."),
23183
- versionRange: external_exports.string().optional().describe("Semver range. Omit to deprecate ALL versions. Example: '<1.0.0' or '0.3.x'."),
23184
- force: external_exports.boolean().optional().describe("Bypass message format validation (default: false).")
23298
+ versionRange: external_exports.string().optional().describe("Semver range. Omit to deprecate ALL versions. Example: '<1.0.0' or '0.3.x'.")
23185
23299
  }),
23186
23300
  handler: async (input) => {
23187
23301
  const authErr = requireAuth();
23188
23302
  if (authErr) return authErr;
23189
- if (!input.force) {
23190
- const problem = validateDeprecationMessage(input.message);
23191
- if (problem) return { ok: false, status: 400, error: problem };
23192
- }
23303
+ const problem = validateDeprecationMessage(input.message);
23304
+ if (problem) return { ok: false, status: 400, error: problem };
23193
23305
  const pRes = await fetchPackument(input.name);
23194
23306
  if (!pRes.ok) return translateError(pRes, { pkg: input.name, op: "deprecate (fetch)" });
23195
23307
  const packument = pRes.data;
@@ -23518,8 +23630,10 @@ var writeTools = [
23518
23630
  handler: async (input) => {
23519
23631
  const authErr = requireAuth();
23520
23632
  if (authErr) return authErr;
23633
+ const userErr = validateUsername(input.username);
23634
+ if (userErr) return { ok: false, status: 400, error: userErr };
23521
23635
  const uRes = await registryGetAuth(
23522
- `/-/user/org.couchdb.user:${encodeURIComponent(input.username)}`
23636
+ `/-/user/org.couchdb.user:${encUser(input.username)}`
23523
23637
  );
23524
23638
  if (!uRes.ok) return translateError(uRes, { pkg: input.name, op: `owner_add (resolve user ${input.username})` });
23525
23639
  const userRecord = { name: uRes.data.name, email: uRes.data.email ?? "" };
@@ -23584,6 +23698,8 @@ var writeTools = [
23584
23698
  handler: async (input) => {
23585
23699
  const authErr = requireAuth();
23586
23700
  if (authErr) return authErr;
23701
+ const userErr = validateUsername(input.username);
23702
+ if (userErr) return { ok: false, status: 400, error: userErr };
23587
23703
  const pRes = await fetchPackument(input.name);
23588
23704
  if (!pRes.ok) return translateError(pRes, { pkg: input.name, op: "owner_remove (fetch)" });
23589
23705
  const packument = pRes.data;
@@ -23715,15 +23831,11 @@ var writeTools = [
23715
23831
  const authErr = requireAuth();
23716
23832
  if (authErr) return authErr;
23717
23833
  const parsed = parseTeamTarget(input.team);
23718
- if (!parsed) {
23719
- return {
23720
- ok: false,
23721
- status: 400,
23722
- error: `Team must be in the form '@scope:team' (got '${input.team}').`
23723
- };
23834
+ if ("error" in parsed) {
23835
+ return { ok: false, status: 400, error: parsed.error };
23724
23836
  }
23725
23837
  const { scope, team } = parsed;
23726
- const res = await registryPutAuth(`/-/team/${encodeURIComponent(scope)}/${encodeURIComponent(team)}/package`, {
23838
+ const res = await registryPutAuth(`/-/team/${encScope(scope)}/${encTeam(team)}/package`, {
23727
23839
  package: input.package,
23728
23840
  permissions: input.permissions
23729
23841
  });
@@ -23756,15 +23868,11 @@ var writeTools = [
23756
23868
  const authErr = requireAuth();
23757
23869
  if (authErr) return authErr;
23758
23870
  const parsed = parseTeamTarget(input.team);
23759
- if (!parsed) {
23760
- return {
23761
- ok: false,
23762
- status: 400,
23763
- error: `Team must be in the form '@scope:team' (got '${input.team}').`
23764
- };
23871
+ if ("error" in parsed) {
23872
+ return { ok: false, status: 400, error: parsed.error };
23765
23873
  }
23766
23874
  const { scope, team } = parsed;
23767
- const res = await registryDeleteAuth(`/-/team/${encodeURIComponent(scope)}/${encodeURIComponent(team)}/package`, {
23875
+ const res = await registryDeleteAuth(`/-/team/${encScope(scope)}/${encTeam(team)}/package`, {
23768
23876
  package: input.package
23769
23877
  });
23770
23878
  if (!res.ok) return translateError(res, { pkg: input.package, op: `team_revoke ${input.team}` });
@@ -23796,11 +23904,11 @@ var writeTools = [
23796
23904
  const authErr = requireAuth();
23797
23905
  if (authErr) return authErr;
23798
23906
  const parsed = parseTeamTarget(input.team);
23799
- if (!parsed) {
23800
- return { ok: false, status: 400, error: `Team must be in the form '@scope:team' (got '${input.team}').` };
23907
+ if ("error" in parsed) {
23908
+ return { ok: false, status: 400, error: parsed.error };
23801
23909
  }
23802
23910
  const { scope, team } = parsed;
23803
- const res = await registryPutAuth(`/-/org/${encodeURIComponent(scope)}/team`, {
23911
+ const res = await registryPutAuth(`/-/org/${encScope(scope)}/team`, {
23804
23912
  name: team,
23805
23913
  description: input.description
23806
23914
  });
@@ -23813,7 +23921,7 @@ var writeTools = [
23813
23921
  // ───────────────────────────────────────────────────────
23814
23922
  {
23815
23923
  name: "npm_team_delete",
23816
- description: "Delete a team. Team is passed as '@scope:team'. Revokes all package permissions that team held.",
23924
+ description: "Delete a team. Team is passed as '@scope:team'. Revokes all package permissions that team held. Requires confirm: true \u2014 this removes the team and all its package grants in one call.",
23817
23925
  annotations: {
23818
23926
  title: "Delete team",
23819
23927
  readOnlyHint: false,
@@ -23822,17 +23930,25 @@ var writeTools = [
23822
23930
  openWorldHint: true
23823
23931
  },
23824
23932
  inputSchema: external_exports.object({
23825
- team: external_exports.string().describe("Team in the form '@scope:team'")
23933
+ team: external_exports.string().describe("Team in the form '@scope:team'"),
23934
+ confirm: external_exports.literal(true).describe("Must be literally true. Guards against accidental team deletion.")
23826
23935
  }),
23827
23936
  handler: async (input) => {
23828
23937
  const authErr = requireAuth();
23829
23938
  if (authErr) return authErr;
23939
+ if (input.confirm !== true) {
23940
+ return {
23941
+ ok: false,
23942
+ status: 400,
23943
+ error: "team_delete requires confirm: true. This removes the team and all its package grants."
23944
+ };
23945
+ }
23830
23946
  const parsed = parseTeamTarget(input.team);
23831
- if (!parsed) {
23832
- return { ok: false, status: 400, error: `Team must be in the form '@scope:team' (got '${input.team}').` };
23947
+ if ("error" in parsed) {
23948
+ return { ok: false, status: 400, error: parsed.error };
23833
23949
  }
23834
23950
  const { scope, team } = parsed;
23835
- const res = await registryDeleteAuth(`/-/team/${encodeURIComponent(scope)}/${encodeURIComponent(team)}`);
23951
+ const res = await registryDeleteAuth(`/-/team/${encScope(scope)}/${encTeam(team)}`);
23836
23952
  if (!res.ok) return translateError(res, { op: `team_delete ${input.team}` });
23837
23953
  return { ok: true, status: 200, data: { team: `@${scope}:${team}`, deleted: true } };
23838
23954
  }
@@ -23857,12 +23973,14 @@ var writeTools = [
23857
23973
  handler: async (input) => {
23858
23974
  const authErr = requireAuth();
23859
23975
  if (authErr) return authErr;
23976
+ const userErr = validateUsername(input.user);
23977
+ if (userErr) return { ok: false, status: 400, error: userErr };
23860
23978
  const parsed = parseTeamTarget(input.team);
23861
- if (!parsed) {
23862
- return { ok: false, status: 400, error: `Team must be in the form '@scope:team' (got '${input.team}').` };
23979
+ if ("error" in parsed) {
23980
+ return { ok: false, status: 400, error: parsed.error };
23863
23981
  }
23864
23982
  const { scope, team } = parsed;
23865
- const res = await registryPutAuth(`/-/team/${encodeURIComponent(scope)}/${encodeURIComponent(team)}/user`, {
23983
+ const res = await registryPutAuth(`/-/team/${encScope(scope)}/${encTeam(team)}/user`, {
23866
23984
  user: input.user
23867
23985
  });
23868
23986
  if (!res.ok) return translateError(res, { op: `team_member_add ${input.team}` });
@@ -23889,12 +24007,14 @@ var writeTools = [
23889
24007
  handler: async (input) => {
23890
24008
  const authErr = requireAuth();
23891
24009
  if (authErr) return authErr;
24010
+ const userErr = validateUsername(input.user);
24011
+ if (userErr) return { ok: false, status: 400, error: userErr };
23892
24012
  const parsed = parseTeamTarget(input.team);
23893
- if (!parsed) {
23894
- return { ok: false, status: 400, error: `Team must be in the form '@scope:team' (got '${input.team}').` };
24013
+ if ("error" in parsed) {
24014
+ return { ok: false, status: 400, error: parsed.error };
23895
24015
  }
23896
24016
  const { scope, team } = parsed;
23897
- const res = await registryDeleteAuth(`/-/team/${encodeURIComponent(scope)}/${encodeURIComponent(team)}/user`, {
24017
+ const res = await registryDeleteAuth(`/-/team/${encScope(scope)}/${encTeam(team)}/user`, {
23898
24018
  user: input.user
23899
24019
  });
23900
24020
  if (!res.ok) return translateError(res, { op: `team_member_remove ${input.team}` });
@@ -23922,11 +24042,15 @@ var writeTools = [
23922
24042
  handler: async (input) => {
23923
24043
  const authErr = requireAuth();
23924
24044
  if (authErr) return authErr;
24045
+ const orgErr = validateScope(input.org);
24046
+ if (orgErr) return { ok: false, status: 400, error: orgErr };
24047
+ const userErr = validateUsername(input.user);
24048
+ if (userErr) return { ok: false, status: 400, error: userErr };
23925
24049
  const org = input.org.replace(/^@/, "");
23926
24050
  const user = input.user.replace(/^@/, "");
23927
24051
  const body = { user };
23928
24052
  if (input.role) body.role = input.role;
23929
- const res = await registryPutAuth(`/-/org/${encodeURIComponent(org)}/user`, body);
24053
+ const res = await registryPutAuth(`/-/org/${encScope(org)}/user`, body);
23930
24054
  if (!res.ok) return translateError(res, { op: `org_member_set ${org}/${user}` });
23931
24055
  return { ok: true, status: 200, data: { org, user, role: input.role } };
23932
24056
  }
@@ -23936,7 +24060,7 @@ var writeTools = [
23936
24060
  // ───────────────────────────────────────────────────────
23937
24061
  {
23938
24062
  name: "npm_org_member_remove",
23939
- description: "Remove a user from an org. Their team memberships in that org are also removed.",
24063
+ description: "Remove a user from an org. Their team memberships in that org are also removed. Requires confirm: true \u2014 team memberships cascade and cannot be selectively preserved.",
23940
24064
  annotations: {
23941
24065
  title: "Remove org member",
23942
24066
  readOnlyHint: false,
@@ -23946,14 +24070,26 @@ var writeTools = [
23946
24070
  },
23947
24071
  inputSchema: external_exports.object({
23948
24072
  org: external_exports.string().describe("Organization name"),
23949
- user: external_exports.string().describe("npm username")
24073
+ user: external_exports.string().describe("npm username"),
24074
+ confirm: external_exports.literal(true).describe("Must be literally true. Guards against accidental member removal.")
23950
24075
  }),
23951
24076
  handler: async (input) => {
23952
24077
  const authErr = requireAuth();
23953
24078
  if (authErr) return authErr;
24079
+ if (input.confirm !== true) {
24080
+ return {
24081
+ ok: false,
24082
+ status: 400,
24083
+ error: "org_member_remove requires confirm: true. Team memberships in the org are also removed."
24084
+ };
24085
+ }
24086
+ const orgErr = validateScope(input.org);
24087
+ if (orgErr) return { ok: false, status: 400, error: orgErr };
24088
+ const userErr = validateUsername(input.user);
24089
+ if (userErr) return { ok: false, status: 400, error: userErr };
23954
24090
  const org = input.org.replace(/^@/, "");
23955
24091
  const user = input.user.replace(/^@/, "");
23956
- const res = await registryDeleteAuth(`/-/org/${encodeURIComponent(org)}/user`, { user });
24092
+ const res = await registryDeleteAuth(`/-/org/${encScope(org)}/user`, { user });
23957
24093
  if (!res.ok) return translateError(res, { op: `org_member_remove ${org}/${user}` });
23958
24094
  return { ok: true, status: 200, data: { org, removedUser: user } };
23959
24095
  }
@@ -23965,7 +24101,7 @@ var writeTools = [
23965
24101
  // performed via NPM_TOKEN alone — we intentionally don't expose npm_token_create.
23966
24102
  {
23967
24103
  name: "npm_token_revoke",
23968
- description: "Revoke an access token by its key (UUID from npm_tokens). Creating tokens is NOT exposed because the endpoint requires the user password \u2014 create via https://www.npmjs.com/settings/~/tokens instead.",
24104
+ description: "Revoke an access token by its key (UUID from npm_tokens). Requires confirm: true. Revoking the token currently in use by NPM_TOKEN will break the next call. Creating tokens is NOT exposed because the endpoint requires the user password \u2014 create via https://www.npmjs.com/settings/~/tokens instead.",
23969
24105
  annotations: {
23970
24106
  title: "Revoke access token",
23971
24107
  readOnlyHint: false,
@@ -23974,11 +24110,19 @@ var writeTools = [
23974
24110
  openWorldHint: true
23975
24111
  },
23976
24112
  inputSchema: external_exports.object({
23977
- tokenKey: external_exports.string().describe("Token key (UUID shown by npm_tokens)")
24113
+ tokenKey: external_exports.string().describe("Token key (UUID shown by npm_tokens)"),
24114
+ confirm: external_exports.literal(true).describe("Must be literally true. Guards against revoking the token you're authenticating with.")
23978
24115
  }),
23979
24116
  handler: async (input) => {
23980
24117
  const authErr = requireAuth();
23981
24118
  if (authErr) return authErr;
24119
+ if (input.confirm !== true) {
24120
+ return {
24121
+ ok: false,
24122
+ status: 400,
24123
+ error: "token_revoke requires confirm: true. Revoking the token in NPM_TOKEN will break the next call."
24124
+ };
24125
+ }
23982
24126
  const res = await registryDeleteAuth(`/-/npm/v1/tokens/token/${encodeURIComponent(input.tokenKey)}`);
23983
24127
  if (!res.ok) return translateError(res, { op: "token_revoke" });
23984
24128
  return { ok: true, status: 200, data: { tokenKey: input.tokenKey, revoked: true } };
@@ -23987,7 +24131,7 @@ var writeTools = [
23987
24131
  ];
23988
24132
 
23989
24133
  // src/index.ts
23990
- var version2 = true ? "0.8.0" : (await null).createRequire(import.meta.url)("../package.json").version;
24134
+ var version2 = true ? "0.10.0" : (await null).createRequire(import.meta.url)("../package.json").version;
23991
24135
  var subcommand = process.argv[2];
23992
24136
  if (subcommand === "version" || subcommand === "--version") {
23993
24137
  console.log(version2);
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@yawlabs/npmjs-mcp",
3
- "version": "0.8.0",
3
+ "version": "0.10.0",
4
4
  "description": "npm registry MCP server — package intelligence, security audits, and dependency analysis for AI assistants",
5
5
  "license": "MIT",
6
6
  "author": "YawLabs <contact@yaw.sh>",
@@ -39,6 +39,10 @@
39
39
  "prepublishOnly": "npm run build"
40
40
  },
41
41
  "dependencies": {},
42
+ "overrides": {
43
+ "hono": "^4.12.14",
44
+ "@hono/node-server": "^1.19.13"
45
+ },
42
46
  "devDependencies": {
43
47
  "@biomejs/biome": "^1.9.4",
44
48
  "@modelcontextprotocol/sdk": "^1.29.0",