@yawlabs/npmjs-mcp 0.6.0 → 0.8.0

package/README.md

@@ -65,7 +65,7 @@ Add to `claude_desktop_config.json`:
 }
 ```
 
-## Tools (46)
+## Tools (63)
 
 ### Search
 - `npm_search` — Search the npm registry with qualifiers (keywords, author, scope)
@@ -139,10 +139,25 @@ These bypass the CLI/2FA friction that causes `npm deprecate` and similar comman
 - `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_unpublish_package` — Unpublish an entire package (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_add` — Add a maintainer (resolves user via `/-/user/`)
 - `npm_owner_remove` — Remove a maintainer (prevents lockout)
+- `npm_access_set` — Set public/private/restricted access
+- `npm_access_set_mfa` — Configure 2FA requirement for publish (none/publish/automation)
+- `npm_team_grant` / `npm_team_revoke` — Grant/revoke team permissions on a package
+- `npm_team_create` / `npm_team_delete` — Create/delete a team in an org
+- `npm_team_member_add` / `npm_team_member_remove` — Manage team members
+- `npm_org_member_set` / `npm_org_member_remove` — Add/remove org members, set roles
+- `npm_token_revoke` — Revoke an access token by key (creation requires a password and isn't exposed)
+
+### Webhooks (requires NPM_TOKEN)
+- `npm_hook_add` — Register a webhook on a package, scope, or user
+- `npm_hook_list` — List webhooks (optional package filter)
+- `npm_hook_get` — Fetch a single webhook
+- `npm_hook_update` — Update endpoint/secret of a webhook
+- `npm_hook_remove` — Delete a webhook
 
 ### Operation Decision Matrix
 
@@ -158,7 +173,7 @@ Call `npm_ops_playbook` at the start of any session for the up-to-date matrix.
 
 ## Features
 
-- **37 tools** covering search, packages, deps, downloads, security, analysis, auth, orgs, provenance, trust, and publish workflows
+- **63 tools** covering search, packages, deps, downloads, security, analysis, auth, orgs, access, provenance, trust, publish workflows, write operations, and registry webhooks
 - **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

@@ -21015,8 +21015,21 @@ var REGISTRY_URL = "https://registry.npmjs.org";
 var DOWNLOADS_URL = "https://api.npmjs.org";
 var REPLICATE_URL = "https://replicate.npmjs.com";
 var REQUEST_TIMEOUT_MS = 3e4;
+var PACKAGE_NAME_MAX_LENGTH = 214;
+var PACKAGE_NAME_PATTERN = /^(?:@[a-zA-Z0-9][a-zA-Z0-9\-_.]*\/)?[a-zA-Z0-9][a-zA-Z0-9\-_.]*$/;
+function validatePackageName(name) {
+  if (typeof name !== "string" || name.length === 0) return "Package name is empty";
+  if (name.length > PACKAGE_NAME_MAX_LENGTH) {
+    return `Package name exceeds ${PACKAGE_NAME_MAX_LENGTH} characters (got ${name.length}).`;
+  }
+  if (!PACKAGE_NAME_PATTERN.test(name)) {
+    return `Invalid package name '${name}'. Names must start with an alphanumeric character and contain only [a-zA-Z0-9-_.], optionally prefixed with '@scope/' for scoped packages.`;
+  }
+  return null;
+}
 function encPkg(name) {
-  if (!name || name === "@") throw new Error("Invalid package name");
+  const err = validatePackageName(name);
+  if (err) throw new Error(err);
   return name.startsWith("@") ? `@${encodeURIComponent(name.slice(1))}` : encodeURIComponent(name);
 }
 function isAuthenticated() {
@@ -21081,11 +21094,14 @@ function registryPost(path, body) {
 function registryGetAuth(path) {
   return request(REGISTRY_URL, path, { headers: authHeaders() });
 }
+function registryPostAuth(path, body) {
+  return request(REGISTRY_URL, path, { method: "POST", body, 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 registryDeleteAuth(path, body) {
+  return request(REGISTRY_URL, path, { method: "DELETE", body, headers: authHeaders() });
 }
 function downloadsGet(path) {
   return request(DOWNLOADS_URL, path);
@@ -21229,6 +21245,61 @@ function maxSatisfying(versions, range) {
   return best;
 }
 
+// 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/access.ts
 var accessTools = [
   {
@@ -21248,7 +21319,7 @@ var accessTools = [
       const authErr = requireAuth();
       if (authErr) return authErr;
       const res = await registryGetAuth(`/-/package/${encPkg(input.name)}/collaborators`);
-      if (!res.ok) return res;
+      if (!res.ok) return translateError(res, { pkg: input.name, op: "collaborators" });
       const collaborators = Object.entries(res.data).map(([username, permissions]) => ({
         username,
         permissions
@@ -21284,7 +21355,7 @@ var accessTools = [
         registryGetAuth(`/-/package/${encPkg(input.name)}/access`),
         registryGetAuth(`/-/package/${encPkg(input.name)}/collaborators`)
       ]);
-      if (!accessRes.ok && !collabRes.ok) return collabRes;
+      if (!accessRes.ok && !collabRes.ok) return translateError(collabRes, { pkg: input.name, op: "package_access" });
       const result = {
         package: input.name,
         isScoped: input.name.startsWith("@")
@@ -21385,7 +21456,7 @@ var analysisTools = [
         downloadsGet(`/downloads/point/last-week/${encPkg(input.name)}`),
         downloadsGet(`/downloads/point/last-month/${encPkg(input.name)}`)
       ]);
-      if (!pkgRes.ok) return pkgRes;
+      if (!pkgRes.ok) return translateError(pkgRes, { pkg: input.name, op: "health" });
       const pkg = pkgRes.data;
       const latest = pkg["dist-tags"]?.latest;
       const latestVersion = latest ? pkg.versions[latest] : void 0;
@@ -21459,7 +21530,7 @@ var analysisTools = [
     }),
     handler: async (input) => {
       const res = await registryGet(`/${encPkg(input.name)}`);
-      if (!res.ok) return res;
+      if (!res.ok) return translateError(res, { pkg: input.name, op: "maintainers" });
       const pkg = res.data;
       const publishCounts = {};
       for (const ver of Object.values(pkg.versions)) {
@@ -21495,7 +21566,7 @@ var analysisTools = [
     }),
     handler: async (input) => {
       const res = await registryGet(`/${encPkg(input.name)}`);
-      if (!res.ok) return res;
+      if (!res.ok) return translateError(res, { pkg: input.name, op: "release_frequency" });
       const pkg = res.data;
       const limit = input.limit ?? 20;
       const releases = Object.keys(pkg.versions).map((v) => ({ version: v, date: pkg.time[v] })).filter((r) => r.date).sort((a, b) => new Date(b.date).getTime() - new Date(a.date).getTime()).slice(0, limit);
@@ -21542,7 +21613,8 @@ var authTools = [
     handler: async () => {
       const authErr = requireAuth();
       if (authErr) return authErr;
-      return registryGetAuth("/-/whoami");
+      const res = await registryGetAuth("/-/whoami");
+      return res.ok ? res : translateError(res, { op: "whoami" });
     }
   },
   {
@@ -21560,7 +21632,7 @@ var authTools = [
       const authErr = requireAuth();
       if (authErr) return authErr;
       const res = await registryGetAuth("/-/npm/v1/user");
-      if (!res.ok) return res;
+      if (!res.ok) return translateError(res, { op: "profile" });
       const p = res.data;
       return {
         ok: true,
@@ -21604,7 +21676,7 @@ var authTools = [
       const qs = params.toString();
       const path = `/-/npm/v1/tokens${qs ? `?${qs}` : ""}`;
       const res = await registryGetAuth(path);
-      if (!res.ok) return res;
+      if (!res.ok) return translateError(res, { op: "tokens" });
       const data = res.data;
       return {
         ok: true,
@@ -21678,7 +21750,7 @@ var authTools = [
       const res = await registryGetAuth(
         `/-/user/org.couchdb.user:${encodeURIComponent(input.username)}/package`
       );
-      if (!res.ok) return res;
+      if (!res.ok) return translateError(res, { op: `user_packages ${input.username}` });
       const packages = Object.entries(res.data).map(([name, access]) => ({ name, access }));
       return {
         ok: true,
@@ -21712,7 +21784,7 @@ var dependencyTools = [
     handler: async (input) => {
       const ver = input.version ?? "latest";
       const res = await registryGet(`/${encPkg(input.name)}/${ver}`);
-      if (!res.ok) return res;
+      if (!res.ok) return translateError(res, { pkg: input.name, op: `dependencies ${ver}` });
       const v = res.data;
       return {
         ok: true,
@@ -21827,7 +21899,7 @@ var dependencyTools = [
     handler: async (input) => {
       const ver = input.version ?? "latest";
       const res = await registryGet(`/${encPkg(input.name)}/${ver}`);
-      if (!res.ok) return res;
+      if (!res.ok) return translateError(res, { pkg: input.name, op: `license_check ${ver}` });
       const pkg = res.data;
       const depEntries = Object.entries(pkg.dependencies ?? {});
       const runLimited = createLimiter(10);
@@ -21885,7 +21957,8 @@ var downloadTools = [
     }),
     handler: async (input) => {
       const period = input.period ?? "last-week";
-      return downloadsGet(`/downloads/point/${period}/${encPkg(input.name)}`);
+      const res = await downloadsGet(`/downloads/point/${period}/${encPkg(input.name)}`);
+      return res.ok ? res : translateError(res, { pkg: input.name, op: `downloads ${period}` });
     }
   },
   {
@@ -21904,7 +21977,8 @@ var downloadTools = [
     }),
     handler: async (input) => {
       const period = input.period ?? "last-month";
-      return downloadsGet(`/downloads/range/${period}/${encPkg(input.name)}`);
+      const res = await downloadsGet(`/downloads/range/${period}/${encPkg(input.name)}`);
+      return res.ok ? res : translateError(res, { pkg: input.name, op: `downloads_range ${period}` });
     }
   },
   {
@@ -21924,7 +21998,8 @@ var downloadTools = [
     handler: async (input) => {
       const period = input.period ?? "last-week";
       const names = input.packages.map((p) => encPkg(p)).join(",");
-      return downloadsGet(`/downloads/point/${period}/${names}`);
+      const res = await downloadsGet(`/downloads/point/${period}/${names}`);
+      return res.ok ? res : translateError(res, { op: `downloads_bulk ${period}` });
     }
   },
   {
@@ -21943,7 +22018,142 @@ var downloadTools = [
     }),
     handler: async (input) => {
       const period = input.period ?? "last-week";
-      return downloadsGet(`/versions/${encPkg(input.name)}/${period}`);
+      const res = await downloadsGet(`/versions/${encPkg(input.name)}/${period}`);
+      return res.ok ? res : translateError(res, { pkg: input.name, op: `version_downloads ${period}` });
+    }
+  }
+];
+
+// src/tools/hooks.ts
+function classifyHookTarget(target) {
+  if (target.startsWith("~")) return { type: "owner", name: target.slice(1) };
+  if (/^@[^/]+$/.test(target)) return { type: "scope", name: target };
+  return { type: "package", name: target };
+}
+var hookTools = [
+  {
+    name: "npm_hook_add",
+    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.",
+    annotations: {
+      title: "Add webhook",
+      readOnlyHint: false,
+      destructiveHint: true,
+      idempotentHint: false,
+      openWorldHint: true
+    },
+    inputSchema: external_exports.object({
+      target: external_exports.string().describe("Hook target: 'pkg', '@scope/pkg', '@scope', or '~user'"),
+      endpoint: external_exports.string().url().describe("HTTPS URL that will receive POST events"),
+      secret: external_exports.string().describe("Secret used to HMAC-sign webhook payloads")
+    }),
+    handler: async (input) => {
+      const authErr = requireAuth();
+      if (authErr) return authErr;
+      const { type, name } = classifyHookTarget(input.target);
+      const res = await registryPostAuth("/-/npm/v1/hooks/hook", {
+        type,
+        name,
+        endpoint: input.endpoint,
+        secret: input.secret
+      });
+      if (!res.ok) return translateError(res, { op: `hook_add ${input.target}` });
+      return { ok: true, status: 200, data: res.data };
+    }
+  },
+  {
+    name: "npm_hook_list",
+    description: "List webhooks. Optionally filter by package name.",
+    annotations: {
+      title: "List webhooks",
+      readOnlyHint: true,
+      destructiveHint: false,
+      idempotentHint: true,
+      openWorldHint: true
+    },
+    inputSchema: external_exports.object({
+      package: external_exports.string().optional().describe("Filter by package name"),
+      limit: external_exports.number().int().optional().describe("Max results"),
+      offset: external_exports.number().int().optional().describe("Pagination offset")
+    }),
+    handler: async (input) => {
+      const authErr = requireAuth();
+      if (authErr) return authErr;
+      const qs = new URLSearchParams();
+      if (input.package) qs.set("package", input.package);
+      if (input.limit !== void 0) qs.set("limit", String(input.limit));
+      if (input.offset !== void 0) qs.set("offset", String(input.offset));
+      const q = qs.toString();
+      const res = await registryGetAuth(`/-/npm/v1/hooks${q ? `?${q}` : ""}`);
+      if (!res.ok) return translateError(res, { op: "hook_list" });
+      return { ok: true, status: 200, data: res.data };
+    }
+  },
+  {
+    name: "npm_hook_get",
+    description: "Get a single webhook by its ID.",
+    annotations: {
+      title: "Get webhook",
+      readOnlyHint: true,
+      destructiveHint: false,
+      idempotentHint: true,
+      openWorldHint: true
+    },
+    inputSchema: external_exports.object({
+      id: external_exports.string().describe("Hook ID (UUID from npm_hook_list)")
+    }),
+    handler: async (input) => {
+      const authErr = requireAuth();
+      if (authErr) return authErr;
+      const res = await registryGetAuth(`/-/npm/v1/hooks/hook/${encodeURIComponent(input.id)}`);
+      if (!res.ok) return translateError(res, { op: `hook_get ${input.id}` });
+      return { ok: true, status: 200, data: res.data };
+    }
+  },
+  {
+    name: "npm_hook_update",
+    description: "Update a webhook's endpoint and/or secret.",
+    annotations: {
+      title: "Update webhook",
+      readOnlyHint: false,
+      destructiveHint: true,
+      idempotentHint: true,
+      openWorldHint: true
+    },
+    inputSchema: external_exports.object({
+      id: external_exports.string().describe("Hook ID"),
+      endpoint: external_exports.string().url().describe("New HTTPS URL"),
+      secret: external_exports.string().describe("New signing secret")
+    }),
+    handler: async (input) => {
+      const authErr = requireAuth();
+      if (authErr) return authErr;
+      const res = await registryPutAuth(`/-/npm/v1/hooks/hook/${encodeURIComponent(input.id)}`, {
+        endpoint: input.endpoint,
+        secret: input.secret
+      });
+      if (!res.ok) return translateError(res, { op: `hook_update ${input.id}` });
+      return { ok: true, status: 200, data: res.data };
+    }
+  },
+  {
+    name: "npm_hook_remove",
+    description: "Delete a webhook by ID.",
+    annotations: {
+      title: "Remove webhook",
+      readOnlyHint: false,
+      destructiveHint: true,
+      idempotentHint: true,
+      openWorldHint: true
+    },
+    inputSchema: external_exports.object({
+      id: external_exports.string().describe("Hook ID")
+    }),
+    handler: async (input) => {
+      const authErr = requireAuth();
+      if (authErr) return authErr;
+      const res = await registryDeleteAuth(`/-/npm/v1/hooks/hook/${encodeURIComponent(input.id)}`);
+      if (!res.ok) return translateError(res, { op: `hook_remove ${input.id}` });
+      return { ok: true, status: 200, data: { id: input.id, removed: true } };
     }
   }
 ];
@@ -21967,7 +22177,7 @@ var orgTools = [
       const authErr = requireAuth();
       if (authErr) return authErr;
       const res = await registryGetAuth(`/-/org/${encodeURIComponent(input.org)}/user`);
-      if (!res.ok) return res;
+      if (!res.ok) return translateError(res, { op: `org_members ${input.org}` });
       const members = Object.entries(res.data).map(([username, role]) => ({ username, role }));
       return {
         ok: true,
@@ -21997,7 +22207,7 @@ var orgTools = [
       const authErr = requireAuth();
       if (authErr) return authErr;
       const res = await registryGetAuth(`/-/org/${encodeURIComponent(input.org)}/package`);
-      if (!res.ok) return res;
+      if (!res.ok) return translateError(res, { op: `org_packages ${input.org}` });
       const packages = Object.entries(res.data).map(([name, access]) => ({ name, access }));
       return {
         ok: true,
@@ -22027,7 +22237,7 @@ var orgTools = [
       const authErr = requireAuth();
       if (authErr) return authErr;
       const res = await registryGetAuth(`/-/org/${encodeURIComponent(input.org)}/team`);
-      if (!res.ok) return res;
+      if (!res.ok) return translateError(res, { op: `org_teams ${input.org}` });
       return {
         ok: true,
         status: 200,
@@ -22059,7 +22269,7 @@ var orgTools = [
       const res = await registryGetAuth(
         `/-/team/${encodeURIComponent(input.org)}/${encodeURIComponent(input.team)}/package`
       );
-      if (!res.ok) return res;
+      if (!res.ok) return translateError(res, { op: `team_packages ${input.org}:${input.team}` });
       const packages = Object.entries(res.data).map(([name, permissions]) => ({ name, permissions }));
       return {
         ok: true,
@@ -22092,7 +22302,7 @@ var packageTools = [
     }),
     handler: async (input) => {
       const res = await registryGet(`/${encPkg(input.name)}`);
-      if (!res.ok) return res;
+      if (!res.ok) return translateError(res, { pkg: input.name, op: "package" });
       const pkg = res.data;
       const latest = pkg["dist-tags"]?.latest;
       const latestVersion = latest ? pkg.versions[latest] : void 0;
@@ -22136,7 +22346,7 @@ var packageTools = [
     handler: async (input) => {
       const ver = input.version ?? "latest";
       const res = await registryGet(`/${encPkg(input.name)}/${ver}`);
-      if (!res.ok) return res;
+      if (!res.ok) return translateError(res, { pkg: input.name, op: `version ${ver}` });
       const v = res.data;
       return {
         ok: true,
@@ -22186,7 +22396,7 @@ var packageTools = [
     }),
     handler: async (input) => {
       const res = await registryGet(`/${encPkg(input.name)}`);
-      if (!res.ok) return res;
+      if (!res.ok) return translateError(res, { pkg: input.name, op: "versions" });
       const pkg = res.data;
       const limit = input.limit ?? 50;
       const allVersions = Object.keys(pkg.versions).map((v) => ({
@@ -22224,7 +22434,7 @@ var packageTools = [
     }),
     handler: async (input) => {
       const res = await registryGet(`/${encPkg(input.name)}`);
-      if (!res.ok) return res;
+      if (!res.ok) return translateError(res, { pkg: input.name, op: "readme" });
       const readme = res.data.readme;
       if (!readme) {
         return { ok: true, status: 200, data: { name: input.name, readme: "(no readme available)" } };
@@ -22246,7 +22456,8 @@ var packageTools = [
       name: external_exports.string().describe("Package name")
     }),
     handler: async (input) => {
-      return registryGet(`/-/package/${encPkg(input.name)}/dist-tags`);
+      const res = await registryGet(`/-/package/${encPkg(input.name)}/dist-tags`);
+      return res.ok ? res : translateError(res, { pkg: input.name, op: "dist_tags" });
     }
   },
   {
@@ -22276,7 +22487,7 @@ var packageTools = [
         registryGet(`/${encPkg(input.name)}/${ver}`),
         registryGet(`/${encPkg(typesPackage)}`)
       ]);
-      if (!versionRes.ok) return versionRes;
+      if (!versionRes.ok) return translateError(versionRes, { pkg: input.name, op: `types ${ver}` });
       const v = versionRes.data;
       const hasBuiltinTypes = !!(v.types || v.typings);
       const typesEntry = hasBuiltinTypes ? v.types ?? v.typings : void 0;
@@ -22324,9 +22535,9 @@ var provenanceTools = [
     }),
     handler: async (input) => {
       const res = await registryGet(
-        `/-/npm/v1/attestations/${encPkg(input.name)}@${input.version}`
+        `/-/npm/v1/attestations/${encPkg(input.name)}@${encodeURIComponent(input.version)}`
       );
-      if (!res.ok) return res;
+      if (!res.ok) return translateError(res, { pkg: input.name, op: `provenance ${input.version}` });
       const attestations = (res.data.attestations ?? []).map((a) => ({
         predicateType: a.predicateType,
         bundle: a.bundle
@@ -22364,7 +22575,8 @@ var registryTools = [
     }),
     handler: async (input) => {
       const period = input.period ?? "last-week";
-      return downloadsGet(`/downloads/point/${period}`);
+      const res = await downloadsGet(`/downloads/point/${period}`);
+      return res.ok ? res : translateError(res, { op: `registry_stats ${period}` });
     }
   },
   {
@@ -22386,7 +22598,7 @@ var registryTools = [
         replicateGet("/"),
         replicateGet(`/_changes?limit=${limit}&descending=true`)
       ]);
-      if (!changesRes.ok) return changesRes;
+      if (!changesRes.ok) return translateError(changesRes, { op: "recent_changes" });
       const changes = changesRes.data.results.map((r) => ({
         package: r.id,
         rev: r.changes[0]?.rev
@@ -22497,7 +22709,7 @@ var searchTools = [
       if (input.popularity !== void 0) params.set("popularity", String(input.popularity));
       if (input.maintenance !== void 0) params.set("maintenance", String(input.maintenance));
       const res = await registryGet(`/-/v1/search?${params}`);
-      if (!res.ok) return res;
+      if (!res.ok) return translateError(res, { op: `search "${input.query}"` });
       const results = res.data.objects.map((obj) => ({
         name: obj.package.name,
         version: obj.package.version,
@@ -22530,7 +22742,34 @@ var securityTools = [
       packages: external_exports.record(external_exports.array(external_exports.string())).describe('Object mapping package names to arrays of version strings, e.g. {"lodash": ["4.17.20"]}')
     }),
     handler: async (input) => {
-      return registryPost("/-/npm/v1/security/advisories/bulk", input.packages);
+      const res = await registryPost("/-/npm/v1/security/advisories/bulk", input.packages);
+      if (!res.ok) return translateError(res, { op: "audit" });
+      const advisoriesByPackage = res.data ?? {};
+      const summary = Object.entries(advisoriesByPackage).map(([name, advisories]) => {
+        const list = Array.isArray(advisories) ? advisories : [];
+        const severityCounts = {};
+        for (const adv of list) {
+          const severity = adv?.severity ?? "unknown";
+          severityCounts[severity] = (severityCounts[severity] ?? 0) + 1;
+        }
+        return { name, advisoryCount: list.length, severityCounts };
+      });
+      const queried = Object.keys(input.packages);
+      const vulnerable = summary.filter((s) => s.advisoryCount > 0).map((s) => s.name);
+      const clean = queried.filter((n) => !vulnerable.includes(n));
+      return {
+        ok: true,
+        status: 200,
+        data: {
+          queriedCount: queried.length,
+          vulnerableCount: vulnerable.length,
+          cleanCount: clean.length,
+          vulnerable,
+          clean,
+          summary,
+          advisories: advisoriesByPackage
+        }
+      };
     }
   },
   {
@@ -22557,7 +22796,8 @@ var securityTools = [
           Object.entries(input.dependencies).map(([pkg, ver]) => [pkg, { version: ver }])
         )
       };
-      return registryPost("/-/npm/v1/security/audits", body);
+      const res = await registryPost("/-/npm/v1/security/audits", body);
+      return res.ok ? res : translateError(res, { pkg: input.name, op: "audit_deep" });
     }
   },
   {
@@ -22572,7 +22812,8 @@ var securityTools = [
     },
     inputSchema: external_exports.object({}),
     handler: async () => {
-      return registryGet("/-/npm/v1/keys");
+      const res = await registryGet("/-/npm/v1/keys");
+      return res.ok ? res : translateError(res, { op: "signing_keys" });
     }
   }
 ];
@@ -22596,7 +22837,7 @@ var trustTools = [
       const authErr = requireAuth();
       if (authErr) return authErr;
       const res = await registryGetAuth(`/-/package/${encPkg(input.name)}/trust`);
-      if (!res.ok) return res;
+      if (!res.ok) return translateError(res, { pkg: input.name, op: "trusted_publishers" });
       const configs = (res.data ?? []).map((c) => {
         const result = {
           id: c.id,
@@ -22904,72 +23145,31 @@ 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`);
 }
+function parseTeamTarget(target) {
+  const m = target.match(/^@?([^:]+):(.+)$/);
+  return m ? { scope: m[1], team: m[2] } : null;
+}
+function highestVersion(versions) {
+  const parsed = [];
+  for (const v of versions) {
+    const m = v.match(/^(\d+)\.(\d+)\.(\d+)/);
+    if (m) parsed.push([Number(m[1]), Number(m[2]), Number(m[3]), v]);
+  }
+  if (parsed.length === 0) return null;
+  parsed.sort((a, b) => a[0] - b[0] || a[1] - b[1] || a[2] - b[2]);
+  return parsed[parsed.length - 1][3];
+}
 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.",
+    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.",
     annotations: {
       title: "Deprecate package",
       readOnlyHint: false,
@@ -23072,9 +23272,17 @@ var writeTools = [
   // ───────────────────────────────────────────────────────
   // npm_unpublish_version
   // ───────────────────────────────────────────────────────
+  // Mirrors libnpmpublish/unpublish.js single-version flow:
+  //   1. GET /{pkg}?write=true
+  //   2. mutate: remove version, fix dist-tags, delete _revisions/_attachments
+  //   3. PUT /{pkg}/-rev/{rev}
+  //   4. GET /{pkg}?write=true (fresh rev)
+  //   5. DELETE {tarball-pathname}/-rev/{newRev}
+  // The tarball DELETE is best-effort — if it fails, the version is already unreachable
+  // via the packument (step 3 succeeded), so we report success with a warning.
   {
     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.",
+    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. Follows the npm CLI flow (mutate packument + delete tarball). For full-package unpublish use npm_unpublish_package.",
     annotations: {
       title: "Unpublish version",
       readOnlyHint: false,
@@ -23100,33 +23308,118 @@ var writeTools = [
       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]) {
+      const versionData = packument.versions?.[input.version];
+      if (!versionData) {
         return {
           ok: false,
           status: 404,
-          error: `Version ${input.version} not found for ${input.name}. Published versions: ${Object.keys(packument.versions).join(", ")}.`
+          error: `Version ${input.version} not found for ${input.name}. Published versions: ${Object.keys(packument.versions || {}).join(", ")}.`
         };
       }
+      if (!packument._rev) {
+        return {
+          ok: false,
+          status: 500,
+          error: `Packument for ${input.name} missing _rev \u2014 cannot unpublish. Try again; this is usually transient.`
+        };
+      }
+      const tarballUrl = versionData.dist?.tarball;
+      const latestBefore = packument["dist-tags"]?.latest;
       delete packument.versions[input.version];
-      for (const tag of Object.keys(packument["dist-tags"])) {
+      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)" });
+      if (latestBefore === input.version) {
+        const newLatest = highestVersion(Object.keys(packument.versions));
+        if (newLatest) packument["dist-tags"].latest = newLatest;
+      }
+      delete packument._revisions;
+      delete packument._attachments;
+      const putRes = await registryPutAuth(
+        `/${encPkg(input.name)}/-rev/${encodeURIComponent(packument._rev)}`,
+        packument
+      );
+      if (!putRes.ok) return translateError(putRes, { pkg: input.name, op: "unpublish (packument PUT)" });
+      let tarballDeleted = false;
+      let tarballError;
+      if (tarballUrl) {
+        const freshRes = await fetchPackument(input.name);
+        const freshRev = freshRes.ok ? freshRes.data._rev : void 0;
+        if (freshRev) {
+          try {
+            const pathname = new URL(tarballUrl).pathname;
+            const delRes = await registryDeleteAuth(`${pathname}/-rev/${encodeURIComponent(freshRev)}`);
+            tarballDeleted = delRes.ok;
+            if (!delRes.ok) tarballError = delRes.error;
+          } catch (err) {
+            tarballError = err instanceof Error ? err.message : String(err);
+          }
+        } else {
+          tarballError = "could not re-fetch packument for tarball DELETE rev";
+        }
+      }
       return {
         ok: true,
         status: 200,
         data: {
           package: input.name,
           unpublishedVersion: input.version,
-          remainingVersions: Object.keys(packument.versions)
+          remainingVersions: Object.keys(packument.versions),
+          tarballDeleted,
+          ...tarballError ? { tarballWarning: tarballError } : {}
         }
       };
     }
   },
   // ───────────────────────────────────────────────────────
+  // npm_unpublish_package
+  // ───────────────────────────────────────────────────────
+  {
+    name: "npm_unpublish_package",
+    description: "Unpublish an ENTIRE package (all versions). DELETE /{pkg}/-rev/{rev}. IRREVERSIBLE: the name is blocked for 72 hours and cannot be re-published. For single-version unpublish prefer npm_unpublish_version. Requires confirm: true.",
+    annotations: {
+      title: "Unpublish entire package",
+      readOnlyHint: false,
+      destructiveHint: true,
+      idempotentHint: false,
+      openWorldHint: true
+    },
+    inputSchema: external_exports.object({
+      name: external_exports.string().describe("Package name"),
+      confirm: external_exports.literal(true).describe("Must be literally true. Guards against accidental full unpublish.")
+    }),
+    handler: async (input) => {
+      const authErr = requireAuth();
+      if (authErr) return authErr;
+      if (input.confirm !== true) {
+        return {
+          ok: false,
+          status: 400,
+          error: "Full-package unpublish requires confirm: true. This blocks the name for 72 hours."
+        };
+      }
+      const pRes = await fetchPackument(input.name);
+      if (!pRes.ok) return translateError(pRes, { pkg: input.name, op: "unpublish_package (fetch)" });
+      const rev = pRes.data._rev;
+      if (!rev) {
+        return {
+          ok: false,
+          status: 500,
+          error: `Packument for ${input.name} missing _rev \u2014 cannot unpublish.`
+        };
+      }
+      const delRes = await registryDeleteAuth(`/${encPkg(input.name)}/-rev/${encodeURIComponent(rev)}`);
+      if (!delRes.ok) return translateError(delRes, { pkg: input.name, op: "unpublish_package (DELETE)" });
+      return {
+        ok: true,
+        status: 200,
+        data: { package: input.name, unpublished: true }
+      };
+    }
+  },
+  // ───────────────────────────────────────────────────────
   // npm_dist_tag_set
   // ───────────────────────────────────────────────────────
   {
@@ -23204,9 +23497,13 @@ var writeTools = [
   // ───────────────────────────────────────────────────────
   // npm_owner_add
   // ───────────────────────────────────────────────────────
+  // Mirrors npm CLI owner.js:
+  //   1. GET /-/user/org.couchdb.user:{user} → resolve {name, email}
+  //   2. GET /{pkg}?write=true → packument with _rev
+  //   3. PUT /{pkg}/-rev/{_rev} body {_id, _rev, maintainers}
   {
     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.",
+    description: "Add a user as a maintainer of a package. They will have publish and write permissions. Resolves the user's email via /-/user/ (no need to supply it). Use npm_collaborators to verify before adding.",
     annotations: {
       title: "Add package owner",
       readOnlyHint: false,
@@ -23216,38 +23513,53 @@ var writeTools = [
     },
     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)")
+      username: external_exports.string().describe("npm username to add as maintainer")
     }),
     handler: async (input) => {
       const authErr = requireAuth();
       if (authErr) return authErr;
+      const uRes = await registryGetAuth(
+        `/-/user/org.couchdb.user:${encodeURIComponent(input.username)}`
+      );
+      if (!uRes.ok) return translateError(uRes, { pkg: input.name, op: `owner_add (resolve user ${input.username})` });
+      const userRecord = { name: uRes.data.name, email: uRes.data.email ?? "" };
       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)) {
+      const owners = packument.maintainers || [];
+      if (owners.some((m) => m.name === userRecord.name)) {
         return {
           ok: true,
           status: 200,
           data: {
             package: input.name,
-            username: input.username,
+            username: userRecord.name,
             alreadyOwner: true,
-            maintainers: packument.maintainers.map((m) => m.name)
+            maintainers: owners.map((m) => m.name)
           }
         };
       }
-      packument.maintainers.push({ name: input.username, email: input.email ?? "" });
-      const putRes = await registryPutAuth(`/${encPkg(input.name)}`, packument);
+      if (!packument._rev) {
+        return {
+          ok: false,
+          status: 500,
+          error: `Packument for ${input.name} missing _rev \u2014 cannot update owners.`
+        };
+      }
+      const maintainers = [...owners, userRecord];
+      const putRes = await registryPutAuth(`/${encPkg(input.name)}/-rev/${encodeURIComponent(packument._rev)}`, {
+        _id: packument._id,
+        _rev: packument._rev,
+        maintainers
+      });
       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)
+          addedOwner: userRecord.name,
+          maintainers: maintainers.map((m) => m.name)
         }
       };
     }
@@ -23291,8 +23603,18 @@ var writeTools = [
           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 (!packument._rev) {
+        return {
+          ok: false,
+          status: 500,
+          error: `Packument for ${input.name} missing _rev \u2014 cannot update owners.`
+        };
+      }
+      const putRes = await registryPutAuth(`/${encPkg(input.name)}/-rev/${encodeURIComponent(packument._rev)}`, {
+        _id: packument._id,
+        _rev: packument._rev,
+        maintainers: after
+      });
       if (!putRes.ok) return translateError(putRes, { pkg: input.name, op: "owner_remove (write)" });
       return {
         ok: true,
@@ -23304,11 +23626,368 @@ var writeTools = [
         }
       };
     }
+  },
+  // ───────────────────────────────────────────────────────
+  // npm_access_set
+  // ───────────────────────────────────────────────────────
+  {
+    name: "npm_access_set",
+    description: "Set package access level: 'public', 'private', or 'restricted'. Unscoped packages are always public. Private access requires a paid npm account.",
+    annotations: {
+      title: "Set package access level",
+      readOnlyHint: false,
+      destructiveHint: true,
+      idempotentHint: true,
+      openWorldHint: true
+    },
+    inputSchema: external_exports.object({
+      name: external_exports.string().describe("Package name"),
+      access: external_exports.enum(["public", "private", "restricted"]).describe("Access level")
+    }),
+    handler: async (input) => {
+      const authErr = requireAuth();
+      if (authErr) return authErr;
+      const res = await registryPostAuth(`/-/package/${encPkg(input.name)}/access`, { access: input.access });
+      if (!res.ok) return translateError(res, { pkg: input.name, op: `access_set ${input.access}` });
+      return {
+        ok: true,
+        status: 200,
+        data: { package: input.name, access: input.access }
+      };
+    }
+  },
+  // ───────────────────────────────────────────────────────
+  // npm_access_set_mfa
+  // ───────────────────────────────────────────────────────
+  {
+    name: "npm_access_set_mfa",
+    description: "Configure 2FA requirement for publishing: 'none' (off), 'publish' (2FA required), 'automation' (2FA required but automation tokens can bypass).",
+    annotations: {
+      title: "Set package 2FA publish policy",
+      readOnlyHint: false,
+      destructiveHint: true,
+      idempotentHint: true,
+      openWorldHint: true
+    },
+    inputSchema: external_exports.object({
+      name: external_exports.string().describe("Package name"),
+      level: external_exports.enum(["none", "publish", "automation"]).describe("MFA level for publish")
+    }),
+    handler: async (input) => {
+      const authErr = requireAuth();
+      if (authErr) return authErr;
+      let body;
+      if (input.level === "none") {
+        body = { publish_requires_tfa: false };
+      } else if (input.level === "publish") {
+        body = { publish_requires_tfa: true, automation_token_overrides_tfa: false };
+      } else {
+        body = { publish_requires_tfa: true, automation_token_overrides_tfa: true };
+      }
+      const res = await registryPostAuth(`/-/package/${encPkg(input.name)}/access`, body);
+      if (!res.ok) return translateError(res, { pkg: input.name, op: `access_set_mfa ${input.level}` });
+      return {
+        ok: true,
+        status: 200,
+        data: { package: input.name, mfaLevel: input.level }
+      };
+    }
+  },
+  // ───────────────────────────────────────────────────────
+  // npm_team_grant
+  // ───────────────────────────────────────────────────────
+  {
+    name: "npm_team_grant",
+    description: "Grant a team read-only or read-write permission on a package. Scope and team are passed as @scope:team (e.g. '@yawlabs:devs'). Requires org admin or team admin.",
+    annotations: {
+      title: "Grant team package permission",
+      readOnlyHint: false,
+      destructiveHint: true,
+      idempotentHint: true,
+      openWorldHint: true
+    },
+    inputSchema: external_exports.object({
+      team: external_exports.string().describe("Team in the form '@scope:team' (e.g. '@yawlabs:devs')"),
+      package: external_exports.string().describe("Package name"),
+      permissions: external_exports.enum(["read-only", "read-write"]).describe("Permission level")
+    }),
+    handler: async (input) => {
+      const authErr = requireAuth();
+      if (authErr) return authErr;
+      const parsed = parseTeamTarget(input.team);
+      if (!parsed) {
+        return {
+          ok: false,
+          status: 400,
+          error: `Team must be in the form '@scope:team' (got '${input.team}').`
+        };
+      }
+      const { scope, team } = parsed;
+      const res = await registryPutAuth(`/-/team/${encodeURIComponent(scope)}/${encodeURIComponent(team)}/package`, {
+        package: input.package,
+        permissions: input.permissions
+      });
+      if (!res.ok) return translateError(res, { pkg: input.package, op: `team_grant ${input.team}` });
+      return {
+        ok: true,
+        status: 200,
+        data: { team: `@${scope}:${team}`, package: input.package, permissions: input.permissions }
+      };
+    }
+  },
+  // ───────────────────────────────────────────────────────
+  // npm_team_revoke
+  // ───────────────────────────────────────────────────────
+  {
+    name: "npm_team_revoke",
+    description: "Revoke a team's access to a package. Team is passed as '@scope:team'. Does not delete the team itself \u2014 use npm_team_delete for that.",
+    annotations: {
+      title: "Revoke team package permission",
+      readOnlyHint: false,
+      destructiveHint: true,
+      idempotentHint: true,
+      openWorldHint: true
+    },
+    inputSchema: external_exports.object({
+      team: external_exports.string().describe("Team in the form '@scope:team'"),
+      package: external_exports.string().describe("Package name")
+    }),
+    handler: async (input) => {
+      const authErr = requireAuth();
+      if (authErr) return authErr;
+      const parsed = parseTeamTarget(input.team);
+      if (!parsed) {
+        return {
+          ok: false,
+          status: 400,
+          error: `Team must be in the form '@scope:team' (got '${input.team}').`
+        };
+      }
+      const { scope, team } = parsed;
+      const res = await registryDeleteAuth(`/-/team/${encodeURIComponent(scope)}/${encodeURIComponent(team)}/package`, {
+        package: input.package
+      });
+      if (!res.ok) return translateError(res, { pkg: input.package, op: `team_revoke ${input.team}` });
+      return {
+        ok: true,
+        status: 200,
+        data: { team: `@${scope}:${team}`, package: input.package, revoked: true }
+      };
+    }
+  },
+  // ───────────────────────────────────────────────────────
+  // npm_team_create
+  // ───────────────────────────────────────────────────────
+  {
+    name: "npm_team_create",
+    description: "Create a team inside an organization. Team is passed as '@scope:team'.",
+    annotations: {
+      title: "Create team",
+      readOnlyHint: false,
+      destructiveHint: true,
+      idempotentHint: false,
+      openWorldHint: true
+    },
+    inputSchema: external_exports.object({
+      team: external_exports.string().describe("Team in the form '@scope:team'"),
+      description: external_exports.string().optional().describe("Optional team description")
+    }),
+    handler: async (input) => {
+      const authErr = requireAuth();
+      if (authErr) return authErr;
+      const parsed = parseTeamTarget(input.team);
+      if (!parsed) {
+        return { ok: false, status: 400, error: `Team must be in the form '@scope:team' (got '${input.team}').` };
+      }
+      const { scope, team } = parsed;
+      const res = await registryPutAuth(`/-/org/${encodeURIComponent(scope)}/team`, {
+        name: team,
+        description: input.description
+      });
+      if (!res.ok) return translateError(res, { op: `team_create ${input.team}` });
+      return { ok: true, status: 200, data: { team: `@${scope}:${team}`, created: true } };
+    }
+  },
+  // ───────────────────────────────────────────────────────
+  // npm_team_delete
+  // ───────────────────────────────────────────────────────
+  {
+    name: "npm_team_delete",
+    description: "Delete a team. Team is passed as '@scope:team'. Revokes all package permissions that team held.",
+    annotations: {
+      title: "Delete team",
+      readOnlyHint: false,
+      destructiveHint: true,
+      idempotentHint: true,
+      openWorldHint: true
+    },
+    inputSchema: external_exports.object({
+      team: external_exports.string().describe("Team in the form '@scope:team'")
+    }),
+    handler: async (input) => {
+      const authErr = requireAuth();
+      if (authErr) return authErr;
+      const parsed = parseTeamTarget(input.team);
+      if (!parsed) {
+        return { ok: false, status: 400, error: `Team must be in the form '@scope:team' (got '${input.team}').` };
+      }
+      const { scope, team } = parsed;
+      const res = await registryDeleteAuth(`/-/team/${encodeURIComponent(scope)}/${encodeURIComponent(team)}`);
+      if (!res.ok) return translateError(res, { op: `team_delete ${input.team}` });
+      return { ok: true, status: 200, data: { team: `@${scope}:${team}`, deleted: true } };
+    }
+  },
+  // ───────────────────────────────────────────────────────
+  // npm_team_member_add
+  // ───────────────────────────────────────────────────────
+  {
+    name: "npm_team_member_add",
+    description: "Add a user to a team. Team is '@scope:team'. User must already be in the org.",
+    annotations: {
+      title: "Add team member",
+      readOnlyHint: false,
+      destructiveHint: true,
+      idempotentHint: true,
+      openWorldHint: true
+    },
+    inputSchema: external_exports.object({
+      team: external_exports.string().describe("Team in the form '@scope:team'"),
+      user: external_exports.string().describe("npm username")
+    }),
+    handler: async (input) => {
+      const authErr = requireAuth();
+      if (authErr) return authErr;
+      const parsed = parseTeamTarget(input.team);
+      if (!parsed) {
+        return { ok: false, status: 400, error: `Team must be in the form '@scope:team' (got '${input.team}').` };
+      }
+      const { scope, team } = parsed;
+      const res = await registryPutAuth(`/-/team/${encodeURIComponent(scope)}/${encodeURIComponent(team)}/user`, {
+        user: input.user
+      });
+      if (!res.ok) return translateError(res, { op: `team_member_add ${input.team}` });
+      return { ok: true, status: 200, data: { team: `@${scope}:${team}`, addedUser: input.user } };
+    }
+  },
+  // ───────────────────────────────────────────────────────
+  // npm_team_member_remove
+  // ───────────────────────────────────────────────────────
+  {
+    name: "npm_team_member_remove",
+    description: "Remove a user from a team. Team is '@scope:team'. User remains in the org.",
+    annotations: {
+      title: "Remove team member",
+      readOnlyHint: false,
+      destructiveHint: true,
+      idempotentHint: true,
+      openWorldHint: true
+    },
+    inputSchema: external_exports.object({
+      team: external_exports.string().describe("Team in the form '@scope:team'"),
+      user: external_exports.string().describe("npm username")
+    }),
+    handler: async (input) => {
+      const authErr = requireAuth();
+      if (authErr) return authErr;
+      const parsed = parseTeamTarget(input.team);
+      if (!parsed) {
+        return { ok: false, status: 400, error: `Team must be in the form '@scope:team' (got '${input.team}').` };
+      }
+      const { scope, team } = parsed;
+      const res = await registryDeleteAuth(`/-/team/${encodeURIComponent(scope)}/${encodeURIComponent(team)}/user`, {
+        user: input.user
+      });
+      if (!res.ok) return translateError(res, { op: `team_member_remove ${input.team}` });
+      return { ok: true, status: 200, data: { team: `@${scope}:${team}`, removedUser: input.user } };
+    }
+  },
+  // ───────────────────────────────────────────────────────
+  // npm_org_member_set
+  // ───────────────────────────────────────────────────────
+  {
+    name: "npm_org_member_set",
+    description: "Add a user to an org or change their role. Roles: 'developer', 'admin', 'owner'. If user is already in the org, updates the role. Omit role to keep existing role.",
+    annotations: {
+      title: "Set org member",
+      readOnlyHint: false,
+      destructiveHint: true,
+      idempotentHint: true,
+      openWorldHint: true
+    },
+    inputSchema: external_exports.object({
+      org: external_exports.string().describe("Organization name (with or without leading @)"),
+      user: external_exports.string().describe("npm username"),
+      role: external_exports.enum(["developer", "admin", "owner"]).optional().describe("Role to assign")
+    }),
+    handler: async (input) => {
+      const authErr = requireAuth();
+      if (authErr) return authErr;
+      const org = input.org.replace(/^@/, "");
+      const user = input.user.replace(/^@/, "");
+      const body = { user };
+      if (input.role) body.role = input.role;
+      const res = await registryPutAuth(`/-/org/${encodeURIComponent(org)}/user`, body);
+      if (!res.ok) return translateError(res, { op: `org_member_set ${org}/${user}` });
+      return { ok: true, status: 200, data: { org, user, role: input.role } };
+    }
+  },
+  // ───────────────────────────────────────────────────────
+  // npm_org_member_remove
+  // ───────────────────────────────────────────────────────
+  {
+    name: "npm_org_member_remove",
+    description: "Remove a user from an org. Their team memberships in that org are also removed.",
+    annotations: {
+      title: "Remove org member",
+      readOnlyHint: false,
+      destructiveHint: true,
+      idempotentHint: true,
+      openWorldHint: true
+    },
+    inputSchema: external_exports.object({
+      org: external_exports.string().describe("Organization name"),
+      user: external_exports.string().describe("npm username")
+    }),
+    handler: async (input) => {
+      const authErr = requireAuth();
+      if (authErr) return authErr;
+      const org = input.org.replace(/^@/, "");
+      const user = input.user.replace(/^@/, "");
+      const res = await registryDeleteAuth(`/-/org/${encodeURIComponent(org)}/user`, { user });
+      if (!res.ok) return translateError(res, { op: `org_member_remove ${org}/${user}` });
+      return { ok: true, status: 200, data: { org, removedUser: user } };
+    }
+  },
+  // ───────────────────────────────────────────────────────
+  // npm_token_revoke
+  // ───────────────────────────────────────────────────────
+  // Note: token CREATION requires a user password (not a token), so it cannot be
+  // performed via NPM_TOKEN alone — we intentionally don't expose npm_token_create.
+  {
+    name: "npm_token_revoke",
+    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.",
+    annotations: {
+      title: "Revoke access token",
+      readOnlyHint: false,
+      destructiveHint: true,
+      idempotentHint: true,
+      openWorldHint: true
+    },
+    inputSchema: external_exports.object({
+      tokenKey: external_exports.string().describe("Token key (UUID shown by npm_tokens)")
+    }),
+    handler: async (input) => {
+      const authErr = requireAuth();
+      if (authErr) return authErr;
+      const res = await registryDeleteAuth(`/-/npm/v1/tokens/token/${encodeURIComponent(input.tokenKey)}`);
+      if (!res.ok) return translateError(res, { op: "token_revoke" });
+      return { ok: true, status: 200, data: { tokenKey: input.tokenKey, revoked: true } };
+    }
   }
 ];
 
 // src/index.ts
-var version2 = true ? "0.6.0" : (await null).createRequire(import.meta.url)("../package.json").version;
+var version2 = true ? "0.8.0" : (await null).createRequire(import.meta.url)("../package.json").version;
 var subcommand = process.argv[2];
 if (subcommand === "version" || subcommand === "--version") {
   console.log(version2);
@@ -23328,7 +24007,8 @@ var allTools = [
   ...provenanceTools,
   ...trustTools,
   ...workflowTools,
-  ...writeTools
+  ...writeTools,
+  ...hookTools
 ];
 var server = new McpServer({
   name: "@yawlabs/npmjs-mcp",

package/package.json

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