@yawlabs/npmjs-mcp 0.4.0 → 0.6.0

package/README.md

@@ -65,7 +65,7 @@ Add to `claude_desktop_config.json`:
 }
 ```
 
-## Tools (35)
+## Tools (46)
 
 ### Search
 - `npm_search` — Search the npm registry with qualifiers (keywords, author, scope)
@@ -76,6 +76,7 @@ Add to `claude_desktop_config.json`:
 - `npm_versions` — List all published versions with dates
 - `npm_readme` — Get README content
 - `npm_dist_tags` — Get dist-tags (latest, next, beta, etc)
+- `npm_types` — Check TypeScript type support (built-in types or @types/*)
 
 ### Dependencies
 - `npm_dependencies` — Get dependency lists (prod, dev, peer, optional)
@@ -102,14 +103,20 @@ Add to `claude_desktop_config.json`:
 ### Registry
 - `npm_registry_stats` — Total npm-wide download counts
 - `npm_recent_changes` — Recent package publishes from the CouchDB changes feed
+- `npm_ops_playbook` — Canonical recipes for npm operations (call this FIRST when unsure which tool to use)
 
 ### Provenance
 - `npm_provenance` — Get Sigstore provenance attestations (SLSA, publish)
 
+### Trusted Publishers (requires NPM_TOKEN)
+- `npm_trusted_publishers` — List OIDC trust relationships with CI/CD providers
+
 ### Auth (requires NPM_TOKEN)
 - `npm_whoami` — Check authenticated user
 - `npm_profile` — Get profile, email, 2FA status
 - `npm_tokens` — List access tokens
+- `npm_verify_token` — One-call capability check (call this FIRST when debugging write failures)
+- `npm_user_packages` — List packages published by a user
 
 ### Access (requires NPM_TOKEN)
 - `npm_collaborators` — List package collaborators and permissions
@@ -121,16 +128,37 @@ Add to `claude_desktop_config.json`:
 - `npm_org_teams` — List org teams
 - `npm_team_packages` — List team package permissions
 
-### Hooks (requires NPM_TOKEN)
-- `npm_hooks` — List npm webhooks
-
 ### Workflows
 - `npm_check_auth` — Auth health check with headless publish feasibility
 - `npm_publish_preflight` — Pre-publish validation checklist
 
+### Write Operations (requires NPM_TOKEN with write scope)
+
+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`.
+
+- `npm_deprecate` — Deprecate a package or specific versions (validates message format)
+- `npm_undeprecate` — Clear deprecation
+- `npm_unpublish_version` — Unpublish a specific version (requires `confirm: true`)
+- `npm_dist_tag_set` — Point a dist-tag at a version
+- `npm_dist_tag_remove` — Remove a dist-tag (except `latest`)
+- `npm_owner_add` — Add a maintainer
+- `npm_owner_remove` — Remove a maintainer (prevents lockout)
+
+### Operation Decision Matrix
+
+| Operation | Preferred path | Why |
+|---|---|---|
+| Read (search/view/stats) | These MCP tools, no auth required | Fast, zero friction |
+| Deprecate / dist-tag / owner | `npm_deprecate`, `npm_dist_tag_*`, `npm_owner_*` | HTTP API, no CLI auth issues |
+| Publish | CI tag-push workflow | Version discipline, provenance, org token |
+| Unpublish | `npm_unpublish_version` (with `confirm: true`) | Safer than CLI; irreversible within 72h |
+| CLI fallback (only if MCP returns 422) | `npm login --auth-type=web` then `npm <op>` | End-user interactive path |
+
+Call `npm_ops_playbook` at the start of any session for the up-to-date matrix.
+
 ## Features
 
-- **35 tools** covering search, packages, deps, downloads, security, analysis, auth, orgs, provenance, and publish workflows
+- **37 tools** covering search, packages, deps, downloads, security, analysis, auth, orgs, provenance, trust, and publish workflows
 - **No API key required** for read-only tools — authenticated tools opt-in via NPM_TOKEN
 - **Zero runtime dependencies** — Single bundled file for instant `npx` startup
 - **Agent-aware publish tools** — Detects non-interactive context, provides human hand-off actions instead of unworkable retries

package/dist/index.js

@@ -21081,12 +21081,35 @@ function registryPost(path, body) {
 function registryGetAuth(path) {
   return request(REGISTRY_URL, path, { headers: authHeaders() });
 }
+function registryPutAuth(path, body) {
+  return request(REGISTRY_URL, path, { method: "PUT", body, headers: authHeaders() });
+}
+function registryDeleteAuth(path) {
+  return request(REGISTRY_URL, path, { method: "DELETE", headers: authHeaders() });
+}
 function downloadsGet(path) {
   return request(DOWNLOADS_URL, path);
 }
 function replicateGet(path) {
   return request(REPLICATE_URL, path);
 }
+function createLimiter(max) {
+  let active = 0;
+  const queue = [];
+  return function runLimited(fn) {
+    return new Promise((resolve, reject) => {
+      const run = () => {
+        active++;
+        fn().then(resolve, reject).finally(() => {
+          active--;
+          if (queue.length > 0) queue.shift()();
+        });
+      };
+      if (active < max) run();
+      else queue.push(run);
+    });
+  };
+}
 function parseSemver(v) {
   const m = v.match(/^(\d+)\.(\d+)\.(\d+)/);
   return m ? [Number(m[1]), Number(m[2]), Number(m[3])] : null;
@@ -21098,63 +21121,109 @@ function cmpSemver(a, b) {
   }
   return 0;
 }
-function maxSatisfying(versions, range) {
-  const r = range.trim().replace(/^v/, "");
-  if (versions.includes(r)) return r;
-  let minInclusive = null;
-  let maxExclusive = null;
+function parseSingleConstraint(r) {
+  if (r === "*" || r === "") {
+    return { min: null, max: null };
+  }
   if (r.startsWith("^")) {
     const base = parseSemver(r.slice(1));
     if (!base) return null;
-    minInclusive = base;
-    if (base[0] > 0) maxExclusive = [base[0] + 1, 0, 0];
-    else if (base[1] > 0) maxExclusive = [0, base[1] + 1, 0];
-    else maxExclusive = [0, 0, base[2] + 1];
-  } else if (r.startsWith("~")) {
+    let max;
+    if (base[0] > 0) max = [base[0] + 1, 0, 0];
+    else if (base[1] > 0) max = [0, base[1] + 1, 0];
+    else max = [0, 0, base[2] + 1];
+    return { min: base, max };
+  }
+  if (r.startsWith("~")) {
     const base = parseSemver(r.slice(1));
     if (!base) return null;
-    minInclusive = base;
-    maxExclusive = [base[0], base[1] + 1, 0];
-  } else if (r.startsWith(">=")) {
+    return { min: base, max: [base[0], base[1] + 1, 0] };
+  }
+  if (r.startsWith(">=")) {
     const base = parseSemver(r.slice(2));
     if (!base) return null;
-    minInclusive = base;
-  } else if (r.startsWith("<=")) {
+    return { min: base, max: null };
+  }
+  if (r.startsWith(">")) {
+    const base = parseSemver(r.slice(1));
+    if (!base) return null;
+    return { min: [base[0], base[1], base[2] + 1], max: null };
+  }
+  if (r.startsWith("<=")) {
     const base = parseSemver(r.slice(2));
     if (!base) return null;
-    maxExclusive = [base[0], base[1], base[2] + 1];
-  } else {
-    const xm = r.match(/^(\d+)(?:\.(\d+|x)(?:\.(\d+|x))?)?$/);
-    if (xm) {
-      const major = Number(xm[1]);
-      const minor = xm[2] !== void 0 && xm[2] !== "x" ? Number(xm[2]) : null;
-      if (minor === null) {
-        minInclusive = [major, 0, 0];
-        maxExclusive = [major + 1, 0, 0];
-      } else {
-        const patch = xm[3] !== void 0 && xm[3] !== "x" ? Number(xm[3]) : null;
-        if (patch === null) {
-          minInclusive = [major, minor, 0];
-          maxExclusive = [major, minor + 1, 0];
-        } else {
-          return null;
-        }
+    return { min: null, max: [base[0], base[1], base[2] + 1] };
+  }
+  if (r.startsWith("<")) {
+    const base = parseSemver(r.slice(1));
+    if (!base) return null;
+    return { min: null, max: base };
+  }
+  if (r.startsWith("=")) {
+    const base = parseSemver(r.slice(1));
+    if (!base) return null;
+    return { min: base, max: [base[0], base[1], base[2] + 1] };
+  }
+  const xm = r.match(/^(\d+)(?:\.(\d+|x|\*)(?:\.(\d+|x|\*))?)?$/);
+  if (xm) {
+    const major = Number(xm[1]);
+    const minor = xm[2] !== void 0 && xm[2] !== "x" && xm[2] !== "*" ? Number(xm[2]) : null;
+    if (minor === null) {
+      return { min: [major, 0, 0], max: [major + 1, 0, 0] };
+    }
+    const patch = xm[3] !== void 0 && xm[3] !== "x" && xm[3] !== "*" ? Number(xm[3]) : null;
+    if (patch === null) {
+      return { min: [major, minor, 0], max: [major, minor + 1, 0] };
+    }
+    return null;
+  }
+  return null;
+}
+function parseRange(r) {
+  const hyphenMatch = r.match(/^(\d+\.\d+\.\d+)\s+-\s+(\d+\.\d+\.\d+)$/);
+  if (hyphenMatch) {
+    const low = parseSemver(hyphenMatch[1]);
+    const high = parseSemver(hyphenMatch[2]);
+    if (low && high) return { min: low, max: [high[0], high[1], high[2] + 1] };
+    return null;
+  }
+  const parts = r.trim().split(/\s+/);
+  if (parts.length > 1) {
+    let min = null;
+    let max = null;
+    for (const part of parts) {
+      const constraint = parseSingleConstraint(part);
+      if (!constraint) return null;
+      if (constraint.min) {
+        if (!min || cmpSemver(constraint.min, min) > 0) min = constraint.min;
+      }
+      if (constraint.max) {
+        if (!max || cmpSemver(constraint.max, max) < 0) max = constraint.max;
       }
-    } else {
-      return null;
     }
+    return { min, max };
   }
+  return parseSingleConstraint(r.trim());
+}
+function maxSatisfying(versions, range) {
+  const r = range.trim().replace(/^v/, "");
+  if (versions.includes(r)) return r;
+  const subRanges = r.split("||").map((s) => s.trim());
   let best = null;
   let bestParsed = null;
-  for (const v of versions) {
-    if (v.includes("-") && !r.includes("-")) continue;
-    const parsed = parseSemver(v);
+  for (const sub of subRanges) {
+    const parsed = parseRange(sub);
     if (!parsed) continue;
-    if (minInclusive && cmpSemver(parsed, minInclusive) < 0) continue;
-    if (maxExclusive && cmpSemver(parsed, maxExclusive) >= 0) continue;
-    if (!bestParsed || cmpSemver(parsed, bestParsed) > 0) {
-      best = v;
-      bestParsed = parsed;
+    for (const v of versions) {
+      if (v.includes("-") && !sub.includes("-")) continue;
+      const vp = parseSemver(v);
+      if (!vp) continue;
+      if (parsed.min && cmpSemver(vp, parsed.min) < 0) continue;
+      if (parsed.max && cmpSemver(vp, parsed.max) >= 0) continue;
+      if (!bestParsed || cmpSemver(vp, bestParsed) > 0) {
+        best = v;
+        bestParsed = vp;
+      }
     }
   }
   return best;
@@ -21553,6 +21622,43 @@ var authTools = [
       };
     }
   },
+  {
+    name: "npm_verify_token",
+    description: "Verify the NPM_TOKEN and surface its capabilities \u2014 username, 2FA status, and whether writes are likely to succeed. Call this FIRST when debugging any write failure to rule out auth issues before trying other fixes. Faster than running writes and interpreting 401/403 errors.",
+    annotations: {
+      title: "Verify token capabilities",
+      readOnlyHint: true,
+      destructiveHint: false,
+      idempotentHint: true,
+      openWorldHint: true
+    },
+    inputSchema: external_exports.object({}),
+    handler: async () => {
+      const authErr = requireAuth();
+      if (authErr) return authErr;
+      const [whoami, profile] = await Promise.all([
+        registryGetAuth("/-/whoami"),
+        registryGetAuth("/-/npm/v1/user")
+      ]);
+      if (!whoami.ok) {
+        return {
+          ...whoami,
+          error: `Token failed /-/whoami check. Token is invalid, expired, or revoked. Create a new one at https://www.npmjs.com/settings/~/tokens. Raw: ${whoami.error}`
+        };
+      }
+      const tfa = profile.ok && profile.data?.tfa ? { enabled: true, mode: profile.data.tfa.mode } : { enabled: false };
+      return {
+        ok: true,
+        status: 200,
+        data: {
+          username: whoami.data?.username,
+          tokenValid: true,
+          tfa,
+          hint: "For write ops, token must have 'Read and write' scope on the target package. Granular Access Tokens require 2FA for writes; Classic Automation tokens bypass 2FA. Check your token's scope at https://www.npmjs.com/settings/~/tokens if writes return 401 or 403."
+        }
+      };
+    }
+  },
   {
     name: "npm_user_packages",
     description: "List all packages published by a specific npm user. Shows package names and the user's access level for each. Requires authentication.",
@@ -21641,26 +21747,11 @@ var dependencyTools = [
     }),
     handler: async (input) => {
       const maxDepth = input.depth ?? 3;
-      const MAX_CONCURRENT = 10;
+      const runLimited = createLimiter(10);
       const packumentCache = /* @__PURE__ */ new Map();
       const resolved = /* @__PURE__ */ new Set();
       const tree = {};
       const warnings = [];
-      let active = 0;
-      const queue = [];
-      function runLimited(fn) {
-        return new Promise((resolve2, reject) => {
-          const run = () => {
-            active++;
-            fn().then(resolve2, reject).finally(() => {
-              active--;
-              if (queue.length > 0) queue.shift()();
-            });
-          };
-          if (active < MAX_CONCURRENT) run();
-          else queue.push(run);
-        });
-      }
       async function resolve(name, versionHint2, currentDepth) {
         const hintKey = `${name}@${versionHint2}`;
         if (resolved.has(hintKey) || currentDepth > maxDepth) return;
@@ -21739,22 +21830,7 @@ var dependencyTools = [
       if (!res.ok) return res;
       const pkg = res.data;
       const depEntries = Object.entries(pkg.dependencies ?? {});
-      const MAX_CONCURRENT = 10;
-      let active = 0;
-      const queue = [];
-      function runLimited(fn) {
-        return new Promise((resolve, reject) => {
-          const run = () => {
-            active++;
-            fn().then(resolve, reject).finally(() => {
-              active--;
-              if (queue.length > 0) queue.shift()();
-            });
-          };
-          if (active < MAX_CONCURRENT) run();
-          else queue.push(run);
-        });
-      }
+      const runLimited = createLimiter(10);
       const depLicenses = await Promise.all(
         depEntries.map(async ([depName, depRange]) => {
           const abbrevRes = await runLimited(() => registryGetAbbreviated(`/${encPkg(depName)}`));
@@ -22324,6 +22400,72 @@ var registryTools = [
         }
       };
     }
+  },
+  {
+    name: "npm_ops_playbook",
+    description: "Return canonical recipes for common npm operations \u2014 which MCP tool to call for which op, CLI fallbacks when the MCP server can't handle something, and message format guidance. Call this FIRST when you're not sure how to do an npm operation. Prevents reinventing approaches that don't work.",
+    annotations: {
+      title: "npm operations playbook",
+      readOnlyHint: true,
+      destructiveHint: false,
+      idempotentHint: true,
+      openWorldHint: false
+    },
+    inputSchema: external_exports.object({}),
+    handler: async () => ({
+      ok: true,
+      status: 200,
+      data: {
+        read: {
+          search: "mcp_tool: npm_search",
+          view: "mcp_tool: npm_package",
+          downloads: "mcp_tool: npm_downloads",
+          securityAudit: "mcp_tool: npm_audit",
+          auth: "none required"
+        },
+        write: {
+          deprecate: {
+            tool: "mcp_tool: npm_deprecate",
+            requiresNpmToken: true,
+            messageFormat: {
+              preferred: "Renamed to @scope/pkg \u2014 install that instead",
+              avoid: "Renamed to @scope/pkg. Install that instead.",
+              note: "Period-capital form has triggered 422 on at least one scoped package; use em-dash."
+            }
+          },
+          undeprecate: "mcp_tool: npm_undeprecate",
+          unpublishVersion: "mcp_tool: npm_unpublish_version (requires confirm: true)",
+          distTag: "mcp_tool: npm_dist_tag_set / npm_dist_tag_remove",
+          owner: "mcp_tool: npm_owner_add / npm_owner_remove"
+        },
+        publish: {
+          method: "CI tag-push",
+          neverRunLocally: true,
+          steps: [
+            "Bump version in package.json",
+            "git add package.json && git commit -m 'vX.Y.Z'",
+            "git tag vX.Y.Z",
+            "git push origin main --follow-tags",
+            "gh run list --limit 1 to confirm CI published"
+          ],
+          why: "Local npm publish bypasses version discipline and often fails on 2FA. CI uses repo-level NPM_TOKEN."
+        },
+        auth: {
+          verifyToken: "mcp_tool: npm_verify_token (first step when debugging write failures)",
+          envVar: "NPM_TOKEN",
+          tokenTypes: {
+            granularAccess: "Requires 2FA for writes. Most common.",
+            classicAutomation: "Bypasses 2FA. Ideal for CI.",
+            classicPublish: "Requires 2FA for writes."
+          }
+        },
+        cliFallback: {
+          when: "When an MCP write op returns 422 despite valid token (rare, account-level 2FA policy)",
+          sequence: ["npm login --auth-type=web", "npm <deprecate|unpublish|dist-tag> <args>"],
+          who: "End user runs in their terminal \u2014 MCP server cannot initiate browser auth."
+        }
+      }
+    })
   }
 ];
 
@@ -22762,8 +22904,411 @@ var workflowTools = [
   }
 ];
 
+// src/errors.ts
+function translateError(res, context) {
+  if (res.ok) return res;
+  const pkgPart = context.pkg ? ` for ${context.pkg}` : "";
+  const opPart = context.op ? ` during ${context.op}` : "";
+  switch (res.status) {
+    case 401:
+      return {
+        ...res,
+        error: `Authentication failed${pkgPart}${opPart}. Your NPM_TOKEN may be invalid, expired, or lack write scope. Create a Granular Access Token with 'Read and write' permission at https://www.npmjs.com/settings/~/tokens, or use a classic Automation token (which bypasses 2FA). Raw: ${res.error}`
+      };
+    case 403:
+      return {
+        ...res,
+        error: `Not authorized${pkgPart}${opPart}. You may not be a maintainer of this package, or the token's scope doesn't include it. Check current maintainers with npm_collaborators or npm_package_access. Raw: ${res.error}`
+      };
+    case 404:
+      return {
+        ...res,
+        error: `Not found${pkgPart}${opPart}. Check the exact package name (scoped packages require the @scope/ prefix). If the version is specified, verify it exists with npm_package. Raw: ${res.error}`
+      };
+    case 422:
+      return {
+        ...res,
+        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}`
+      };
+    case 429:
+      return {
+        ...res,
+        error: `Rate limited${opPart}. Wait 60 seconds and retry. Raw: ${res.error}`
+      };
+    case 0:
+      return {
+        ...res,
+        error: `Network error${opPart}. Could not reach the registry. Raw: ${res.error}`
+      };
+    default:
+      return res;
+  }
+}
+function validateDeprecationMessage(msg) {
+  if (msg.length > 1024) {
+    return "Deprecation message exceeds 1024 characters (registry limit).";
+  }
+  if (msg.length === 0) return null;
+  if (/\.\s+[A-Z]/.test(msg)) {
+    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.`;
+  }
+  return null;
+}
+function versionsMatchingRange(versions, range, maxSatisfying2) {
+  if (range === "*" || range === "") return [...versions];
+  return versions.filter((v) => maxSatisfying2([v], range) === v);
+}
+
+// src/tools/writes.ts
+async function fetchPackument(pkg) {
+  return registryGetAuth(`/${encPkg(pkg)}?write=true`);
+}
+var writeTools = [
+  // ───────────────────────────────────────────────────────
+  // npm_deprecate
+  // ───────────────────────────────────────────────────────
+  {
+    name: "npm_deprecate",
+    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: prefer em-dash form ('Renamed to @scope/pkg \u2014 install that instead'); period-capital form sometimes triggers 422.",
+    annotations: {
+      title: "Deprecate package",
+      readOnlyHint: false,
+      destructiveHint: true,
+      idempotentHint: true,
+      openWorldHint: true
+    },
+    inputSchema: external_exports.object({
+      name: external_exports.string().describe("Package name (e.g. '@yawlabs/tokenmeter-mcp')"),
+      message: external_exports.string().describe("Deprecation message. Empty string to clear deprecation (use npm_undeprecate instead)."),
+      versionRange: external_exports.string().optional().describe("Semver range. Omit to deprecate ALL versions. Example: '<1.0.0' or '0.3.x'."),
+      force: external_exports.boolean().optional().describe("Bypass message format validation (default: false).")
+    }),
+    handler: async (input) => {
+      const authErr = requireAuth();
+      if (authErr) return authErr;
+      if (!input.force) {
+        const problem = validateDeprecationMessage(input.message);
+        if (problem) return { ok: false, status: 400, error: problem };
+      }
+      const pRes = await fetchPackument(input.name);
+      if (!pRes.ok) return translateError(pRes, { pkg: input.name, op: "deprecate (fetch)" });
+      const packument = pRes.data;
+      const allVersions = Object.keys(packument.versions || {});
+      const range = input.versionRange ?? "*";
+      const affected = versionsMatchingRange(allVersions, range, maxSatisfying);
+      if (affected.length === 0) {
+        return {
+          ok: false,
+          status: 400,
+          error: `No versions match range '${range}' for ${input.name}. Published versions: ${allVersions.join(", ") || "(none)"}.`
+        };
+      }
+      for (const v of affected) {
+        packument.versions[v].deprecated = input.message;
+      }
+      const putRes = await registryPutAuth(`/${encPkg(input.name)}`, packument);
+      if (!putRes.ok) return translateError(putRes, { pkg: input.name, op: "deprecate (write)" });
+      return {
+        ok: true,
+        status: 200,
+        data: {
+          package: input.name,
+          affectedVersions: affected,
+          totalAffected: affected.length,
+          message: input.message
+        }
+      };
+    }
+  },
+  // ───────────────────────────────────────────────────────
+  // npm_undeprecate
+  // ───────────────────────────────────────────────────────
+  {
+    name: "npm_undeprecate",
+    description: "Clear the deprecation message from a package or specific versions. Equivalent to npm_deprecate with an empty message but more explicit about intent.",
+    annotations: {
+      title: "Undeprecate package",
+      readOnlyHint: false,
+      destructiveHint: true,
+      idempotentHint: true,
+      openWorldHint: true
+    },
+    inputSchema: external_exports.object({
+      name: external_exports.string().describe("Package name"),
+      versionRange: external_exports.string().optional().describe("Semver range. Omit to undeprecate ALL versions.")
+    }),
+    handler: async (input) => {
+      const authErr = requireAuth();
+      if (authErr) return authErr;
+      const pRes = await fetchPackument(input.name);
+      if (!pRes.ok) return translateError(pRes, { pkg: input.name, op: "undeprecate (fetch)" });
+      const packument = pRes.data;
+      const allVersions = Object.keys(packument.versions || {});
+      const range = input.versionRange ?? "*";
+      const affected = versionsMatchingRange(allVersions, range, maxSatisfying);
+      if (affected.length === 0) {
+        return {
+          ok: false,
+          status: 400,
+          error: `No versions match range '${range}' for ${input.name}.`
+        };
+      }
+      for (const v of affected) {
+        packument.versions[v].deprecated = "";
+      }
+      const putRes = await registryPutAuth(`/${encPkg(input.name)}`, packument);
+      if (!putRes.ok) return translateError(putRes, { pkg: input.name, op: "undeprecate (write)" });
+      return {
+        ok: true,
+        status: 200,
+        data: {
+          package: input.name,
+          affectedVersions: affected,
+          totalAffected: affected.length
+        }
+      };
+    }
+  },
+  // ───────────────────────────────────────────────────────
+  // npm_unpublish_version
+  // ───────────────────────────────────────────────────────
+  {
+    name: "npm_unpublish_version",
+    description: "Unpublish a specific version of a package. IRREVERSIBLE: once unpublished, the version cannot be re-published and will be blocked for 72 hours. Only works within 72 hours of the original publish for most packages. Requires explicit confirm: true to prevent accidents.",
+    annotations: {
+      title: "Unpublish version",
+      readOnlyHint: false,
+      destructiveHint: true,
+      idempotentHint: false,
+      openWorldHint: true
+    },
+    inputSchema: external_exports.object({
+      name: external_exports.string().describe("Package name"),
+      version: external_exports.string().describe("Specific version to unpublish (e.g. '1.2.3')"),
+      confirm: external_exports.literal(true).describe("Must be literally true. Guards against accidental unpublish.")
+    }),
+    handler: async (input) => {
+      const authErr = requireAuth();
+      if (authErr) return authErr;
+      if (input.confirm !== true) {
+        return {
+          ok: false,
+          status: 400,
+          error: "Unpublish requires confirm: true. This op is irreversible within 72 hours."
+        };
+      }
+      const pRes = await fetchPackument(input.name);
+      if (!pRes.ok) return translateError(pRes, { pkg: input.name, op: "unpublish (fetch)" });
+      const packument = pRes.data;
+      if (!packument.versions[input.version]) {
+        return {
+          ok: false,
+          status: 404,
+          error: `Version ${input.version} not found for ${input.name}. Published versions: ${Object.keys(packument.versions).join(", ")}.`
+        };
+      }
+      delete packument.versions[input.version];
+      for (const tag of Object.keys(packument["dist-tags"])) {
+        if (packument["dist-tags"][tag] === input.version) {
+          delete packument["dist-tags"][tag];
+        }
+      }
+      const putRes = await registryPutAuth(`/${encPkg(input.name)}`, packument);
+      if (!putRes.ok) return translateError(putRes, { pkg: input.name, op: "unpublish (write)" });
+      return {
+        ok: true,
+        status: 200,
+        data: {
+          package: input.name,
+          unpublishedVersion: input.version,
+          remainingVersions: Object.keys(packument.versions)
+        }
+      };
+    }
+  },
+  // ───────────────────────────────────────────────────────
+  // npm_dist_tag_set
+  // ───────────────────────────────────────────────────────
+  {
+    name: "npm_dist_tag_set",
+    description: "Point a dist-tag (e.g. 'latest', 'beta', 'next') at a specific version. Common uses: promote a beta to latest, roll back latest to a prior version, maintain separate channels.",
+    annotations: {
+      title: "Set dist-tag",
+      readOnlyHint: false,
+      destructiveHint: true,
+      idempotentHint: true,
+      openWorldHint: true
+    },
+    inputSchema: external_exports.object({
+      name: external_exports.string().describe("Package name"),
+      tag: external_exports.string().describe("Dist-tag name (e.g. 'latest', 'beta', 'next')"),
+      version: external_exports.string().describe("Version the tag should point to")
+    }),
+    handler: async (input) => {
+      const authErr = requireAuth();
+      if (authErr) return authErr;
+      const putRes = await registryPutAuth(
+        `/-/package/${encPkg(input.name)}/dist-tags/${encodeURIComponent(input.tag)}`,
+        input.version
+      );
+      if (!putRes.ok) return translateError(putRes, { pkg: input.name, op: `dist-tag set ${input.tag}` });
+      return {
+        ok: true,
+        status: 200,
+        data: {
+          package: input.name,
+          tag: input.tag,
+          version: input.version
+        }
+      };
+    }
+  },
+  // ───────────────────────────────────────────────────────
+  // npm_dist_tag_remove
+  // ───────────────────────────────────────────────────────
+  {
+    name: "npm_dist_tag_remove",
+    description: "Remove a dist-tag from a package. The 'latest' tag cannot be removed, only reassigned.",
+    annotations: {
+      title: "Remove dist-tag",
+      readOnlyHint: false,
+      destructiveHint: true,
+      idempotentHint: true,
+      openWorldHint: true
+    },
+    inputSchema: external_exports.object({
+      name: external_exports.string().describe("Package name"),
+      tag: external_exports.string().describe("Dist-tag name to remove")
+    }),
+    handler: async (input) => {
+      const authErr = requireAuth();
+      if (authErr) return authErr;
+      if (input.tag === "latest") {
+        return {
+          ok: false,
+          status: 400,
+          error: "The 'latest' tag cannot be removed. Use npm_dist_tag_set to reassign it to a different version."
+        };
+      }
+      const delRes = await registryDeleteAuth(
+        `/-/package/${encPkg(input.name)}/dist-tags/${encodeURIComponent(input.tag)}`
+      );
+      if (!delRes.ok) return translateError(delRes, { pkg: input.name, op: `dist-tag remove ${input.tag}` });
+      return {
+        ok: true,
+        status: 200,
+        data: { package: input.name, removedTag: input.tag }
+      };
+    }
+  },
+  // ───────────────────────────────────────────────────────
+  // npm_owner_add
+  // ───────────────────────────────────────────────────────
+  {
+    name: "npm_owner_add",
+    description: "Add a user as a maintainer of a package. They will have publish and write permissions. Use npm_collaborators to verify before adding.",
+    annotations: {
+      title: "Add package owner",
+      readOnlyHint: false,
+      destructiveHint: true,
+      idempotentHint: true,
+      openWorldHint: true
+    },
+    inputSchema: external_exports.object({
+      name: external_exports.string().describe("Package name"),
+      username: external_exports.string().describe("npm username to add as maintainer"),
+      email: external_exports.string().optional().describe("Optional email for the maintainer record (defaults to empty)")
+    }),
+    handler: async (input) => {
+      const authErr = requireAuth();
+      if (authErr) return authErr;
+      const pRes = await fetchPackument(input.name);
+      if (!pRes.ok) return translateError(pRes, { pkg: input.name, op: "owner_add (fetch)" });
+      const packument = pRes.data;
+      packument.maintainers = packument.maintainers || [];
+      if (packument.maintainers.some((m) => m.name === input.username)) {
+        return {
+          ok: true,
+          status: 200,
+          data: {
+            package: input.name,
+            username: input.username,
+            alreadyOwner: true,
+            maintainers: packument.maintainers.map((m) => m.name)
+          }
+        };
+      }
+      packument.maintainers.push({ name: input.username, email: input.email ?? "" });
+      const putRes = await registryPutAuth(`/${encPkg(input.name)}`, packument);
+      if (!putRes.ok) return translateError(putRes, { pkg: input.name, op: "owner_add (write)" });
+      return {
+        ok: true,
+        status: 200,
+        data: {
+          package: input.name,
+          addedOwner: input.username,
+          maintainers: packument.maintainers.map((m) => m.name)
+        }
+      };
+    }
+  },
+  // ───────────────────────────────────────────────────────
+  // npm_owner_remove
+  // ───────────────────────────────────────────────────────
+  {
+    name: "npm_owner_remove",
+    description: "Remove a user from a package's maintainer list. Refuses if it would leave the package with zero maintainers (lockout prevention).",
+    annotations: {
+      title: "Remove package owner",
+      readOnlyHint: false,
+      destructiveHint: true,
+      idempotentHint: true,
+      openWorldHint: true
+    },
+    inputSchema: external_exports.object({
+      name: external_exports.string().describe("Package name"),
+      username: external_exports.string().describe("npm username to remove")
+    }),
+    handler: async (input) => {
+      const authErr = requireAuth();
+      if (authErr) return authErr;
+      const pRes = await fetchPackument(input.name);
+      if (!pRes.ok) return translateError(pRes, { pkg: input.name, op: "owner_remove (fetch)" });
+      const packument = pRes.data;
+      const before = packument.maintainers || [];
+      if (!before.some((m) => m.name === input.username)) {
+        return {
+          ok: false,
+          status: 404,
+          error: `${input.username} is not a maintainer of ${input.name}. Current maintainers: ${before.map((m) => m.name).join(", ") || "(none)"}.`
+        };
+      }
+      const after = before.filter((m) => m.name !== input.username);
+      if (after.length === 0) {
+        return {
+          ok: false,
+          status: 400,
+          error: `Removing ${input.username} would leave ${input.name} with zero maintainers (lockout). Add another maintainer first with npm_owner_add.`
+        };
+      }
+      packument.maintainers = after;
+      const putRes = await registryPutAuth(`/${encPkg(input.name)}`, packument);
+      if (!putRes.ok) return translateError(putRes, { pkg: input.name, op: "owner_remove (write)" });
+      return {
+        ok: true,
+        status: 200,
+        data: {
+          package: input.name,
+          removedOwner: input.username,
+          remainingMaintainers: after.map((m) => m.name)
+        }
+      };
+    }
+  }
+];
+
 // src/index.ts
-var version2 = true ? "0.4.0" : (await null).createRequire(import.meta.url)("../package.json").version;
+var version2 = true ? "0.6.0" : (await null).createRequire(import.meta.url)("../package.json").version;
 var subcommand = process.argv[2];
 if (subcommand === "version" || subcommand === "--version") {
   console.log(version2);
@@ -22782,7 +23327,8 @@ var allTools = [
   ...accessTools,
   ...provenanceTools,
   ...trustTools,
-  ...workflowTools
+  ...workflowTools,
+  ...writeTools
 ];
 var server = new McpServer({
   name: "@yawlabs/npmjs-mcp",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yawlabs/npmjs-mcp",
-  "version": "0.4.0",
+  "version": "0.6.0",
   "description": "npm registry MCP server — package intelligence, security audits, and dependency analysis for AI assistants",
   "license": "MIT",
   "author": "YawLabs <contact@yaw.sh>",