@yawlabs/npmjs-mcp 0.1.0 → 0.3.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Yaw Labs
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,141 @@
+# @yawlabs/npmjs-mcp
+
+MCP server for the [npm](https://www.npmjs.com) registry. Package intelligence, security audits, dependency analysis, and org management from any MCP-compatible AI assistant.
+
+## Quick start
+
+```bash
+npx @yawlabs/npmjs-mcp
+```
+
+## Setup
+
+No API key is required for read-only tools (search, packages, downloads, security, analysis). For authenticated tools (auth, access, orgs, hooks), set your npm token:
+
+```bash
+export NPM_TOKEN="your-token"
+```
+
+### Claude Code
+
+Add to your MCP config:
+
+```json
+{
+  "mcpServers": {
+    "npmjs": {
+      "command": "npx",
+      "args": ["-y", "@yawlabs/npmjs-mcp"]
+    }
+  }
+}
+```
+
+With authentication:
+
+```json
+{
+  "mcpServers": {
+    "npmjs": {
+      "command": "npx",
+      "args": ["-y", "@yawlabs/npmjs-mcp"],
+      "env": {
+        "NPM_TOKEN": "your-token"
+      }
+    }
+  }
+}
+```
+
+### Claude Desktop
+
+Add to `claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "npmjs": {
+      "command": "npx",
+      "args": ["-y", "@yawlabs/npmjs-mcp"],
+      "env": {
+        "NPM_TOKEN": "your-token"
+      }
+    }
+  }
+}
+```
+
+## Tools (35)
+
+### Search
+- `npm_search` — Search the npm registry with qualifiers (keywords, author, scope)
+
+### Packages
+- `npm_package` — Get package metadata (description, dist-tags, maintainers, license)
+- `npm_version` — Get detailed metadata for a specific version
+- `npm_versions` — List all published versions with dates
+- `npm_readme` — Get README content
+- `npm_dist_tags` — Get dist-tags (latest, next, beta, etc)
+
+### Dependencies
+- `npm_dependencies` — Get dependency lists (prod, dev, peer, optional)
+- `npm_dep_tree` — Resolve transitive dependency tree (configurable depth)
+- `npm_license_check` — Check licenses of a package and its direct deps
+
+### Downloads
+- `npm_downloads` — Get total download count for a period
+- `npm_downloads_range` — Get daily download breakdown
+- `npm_downloads_bulk` — Compare downloads for up to 128 packages
+- `npm_version_downloads` — Per-version download counts
+
+### Security
+- `npm_audit` — Check packages for known vulnerabilities
+- `npm_audit_deep` — Full audit with CVSS scores, CWEs, fix recommendations
+- `npm_signing_keys` — Get registry ECDSA signing keys
+
+### Analysis
+- `npm_compare` — Compare 2-5 packages side-by-side
+- `npm_health` — Assess maintenance, downloads, security, deprecation status
+- `npm_maintainers` — Get maintainers and their publish history
+- `npm_release_frequency` — Analyze release cadence and gaps
+
+### Registry
+- `npm_registry_stats` — Total npm-wide download counts
+- `npm_recent_changes` — Recent package publishes from the CouchDB changes feed
+
+### Provenance
+- `npm_provenance` — Get Sigstore provenance attestations (SLSA, publish)
+
+### Auth (requires NPM_TOKEN)
+- `npm_whoami` — Check authenticated user
+- `npm_profile` — Get profile, email, 2FA status
+- `npm_tokens` — List access tokens
+
+### Access (requires NPM_TOKEN)
+- `npm_collaborators` — List package collaborators and permissions
+- `npm_package_access` — Get package access settings
+
+### Organizations (requires NPM_TOKEN)
+- `npm_org_members` — List org members and roles
+- `npm_org_packages` — List org packages
+- `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
+
+## Features
+
+- **35 tools** covering search, packages, deps, downloads, security, analysis, auth, orgs, provenance, 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
+- **MCP annotations** — Every tool declares read-only, destructive, and idempotent hints
+
+## License
+
+MIT

package/dist/index.js

@@ -21016,8 +21016,24 @@ var DOWNLOADS_URL = "https://api.npmjs.org";
 var REPLICATE_URL = "https://replicate.npmjs.com";
 var REQUEST_TIMEOUT_MS = 3e4;
 function encPkg(name) {
+  if (!name || name === "@") throw new Error("Invalid package name");
   return name.startsWith("@") ? `@${encodeURIComponent(name.slice(1))}` : encodeURIComponent(name);
 }
+function isAuthenticated() {
+  return !!process.env.NPM_TOKEN;
+}
+function requireAuth() {
+  if (isAuthenticated()) return null;
+  return {
+    ok: false,
+    status: 401,
+    error: "No NPM_TOKEN configured. Set the NPM_TOKEN environment variable to use authenticated endpoints. Create a token at https://www.npmjs.com/settings/~/tokens \u2014 use a Granular Access Token for CI/CD (automation tokens bypass 2FA)."
+  };
+}
+function authHeaders() {
+  const token = process.env.NPM_TOKEN;
+  return token ? { Authorization: `Bearer ${token}` } : {};
+}
 async function request(baseUrl, path, options) {
   const method = options?.method ?? "GET";
   const headers = {
@@ -21030,21 +21046,26 @@ async function request(baseUrl, path, options) {
     fetchBody = JSON.stringify(options.body);
   }
   const url = `${baseUrl}${path}`;
-  const res = await fetch(url, {
-    method,
-    headers,
-    body: fetchBody,
-    signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS)
-  });
-  if (!res.ok) {
-    const errorBody = await res.text();
-    return { ok: false, status: res.status, error: errorBody };
-  }
-  if (res.status === 204 || res.headers.get("content-length") === "0") {
-    return { ok: true, status: res.status };
+  try {
+    const res = await fetch(url, {
+      method,
+      headers,
+      body: fetchBody,
+      signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS)
+    });
+    if (!res.ok) {
+      const errorBody = await res.text();
+      return { ok: false, status: res.status, error: errorBody };
+    }
+    if (res.status === 204 || res.headers.get("content-length") === "0") {
+      return { ok: true, status: res.status };
+    }
+    const data = await res.json();
+    return { ok: true, status: res.status, data };
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    return { ok: false, status: 0, error: message };
   }
-  const data = await res.json();
-  return { ok: true, status: res.status, data };
 }
 function registryGet(path) {
   return request(REGISTRY_URL, path);
@@ -21057,6 +21078,9 @@ function registryGetAbbreviated(path) {
 function registryPost(path, body) {
   return request(REGISTRY_URL, path, { method: "POST", body });
 }
+function registryGetAuth(path) {
+  return request(REGISTRY_URL, path, { headers: authHeaders() });
+}
 function downloadsGet(path) {
   return request(DOWNLOADS_URL, path);
 }
@@ -21064,6 +21088,84 @@ function replicateGet(path) {
   return request(REPLICATE_URL, path);
 }
 
+// src/tools/access.ts
+var accessTools = [
+  {
+    name: "npm_collaborators",
+    description: "Get all users who have access to a package and their permission levels (read-only, read-write). Useful for verifying who can publish to a package before setting up CI/CD.",
+    annotations: {
+      title: "Package collaborators",
+      readOnlyHint: true,
+      destructiveHint: false,
+      idempotentHint: true,
+      openWorldHint: true
+    },
+    inputSchema: external_exports.object({
+      name: external_exports.string().describe("Package name (e.g. 'express' or '@yawlabs/npmjs-mcp')")
+    }),
+    handler: async (input) => {
+      const authErr = requireAuth();
+      if (authErr) return authErr;
+      const res = await registryGetAuth(`/-/package/${encPkg(input.name)}/collaborators`);
+      if (!res.ok) return res;
+      const collaborators = Object.entries(res.data).map(([username, permissions]) => ({
+        username,
+        permissions
+      }));
+      return {
+        ok: true,
+        status: 200,
+        data: {
+          package: input.name,
+          collaboratorCount: collaborators.length,
+          collaborators
+        }
+      };
+    }
+  },
+  {
+    name: "npm_package_access",
+    description: "Get package access settings \u2014 visibility (public/private), whether publish requires 2FA, and whether automation tokens can bypass 2FA. Critical for understanding why CI publishing fails: if publish_requires_tfa is true but automation_token_overrides_tfa is false, automation tokens cannot publish.",
+    annotations: {
+      title: "Package access settings",
+      readOnlyHint: true,
+      destructiveHint: false,
+      idempotentHint: true,
+      openWorldHint: true
+    },
+    inputSchema: external_exports.object({
+      name: external_exports.string().describe("Package name (e.g. 'express' or '@yawlabs/npmjs-mcp')")
+    }),
+    handler: async (input) => {
+      const authErr = requireAuth();
+      if (authErr) return authErr;
+      const [accessRes, collabRes] = await Promise.all([
+        registryGetAuth(`/-/package/${encPkg(input.name)}/access`),
+        registryGetAuth(`/-/package/${encPkg(input.name)}/collaborators`)
+      ]);
+      if (!accessRes.ok && !collabRes.ok) return collabRes;
+      const result = {
+        package: input.name,
+        isScoped: input.name.startsWith("@")
+      };
+      if (input.name.startsWith("@")) {
+        result.scope = input.name.split("/")[0];
+        result.hint = "Scoped packages belong to an org. Use npm_org_packages to see all packages in the org, and npm_tokens to check if you have a token scoped to this org.";
+      }
+      if (accessRes.ok) {
+        result.access = accessRes.data;
+      }
+      if (collabRes.ok) {
+        result.collaborators = Object.entries(collabRes.data).map(([username, permissions]) => ({
+          username,
+          permissions
+        }));
+      }
+      return { ok: true, status: 200, data: result };
+    }
+  }
+];
+
 // src/tools/analysis.ts
 var analysisTools = [
   {
@@ -21093,8 +21195,8 @@ var analysisTools = [
             return { name, error: pkgRes.error };
           }
           const pkg = pkgRes.data;
-          const latest = pkg["dist-tags"].latest;
-          const latestVersion = pkg.versions[latest];
+          const latest = pkg["dist-tags"]?.latest;
+          const latestVersion = latest ? pkg.versions[latest] : void 0;
           const versionKeys = Object.keys(pkg.versions);
           return {
             name,
@@ -21105,7 +21207,7 @@ var analysisTools = [
             weeklyDownloads: dlRes.ok ? dlRes.data.downloads : null,
             versionCount: versionKeys.length,
             created: pkg.time.created,
-            lastPublish: pkg.time[latest],
+            lastPublish: latest ? pkg.time[latest] : void 0,
             deprecated: latestVersion?.deprecated ?? false,
             hasReadme: !!(pkg.readme && pkg.readme.length > 0),
             repository: pkg.repository,
@@ -21138,8 +21240,8 @@ var analysisTools = [
       ]);
       if (!pkgRes.ok) return pkgRes;
       const pkg = pkgRes.data;
-      const latest = pkg["dist-tags"].latest;
-      const latestVersion = pkg.versions[latest];
+      const latest = pkg["dist-tags"]?.latest;
+      const latestVersion = latest ? pkg.versions[latest] : void 0;
       const versionKeys = Object.keys(pkg.versions);
       const publishDates = versionKeys.map((v) => pkg.time[v]).filter(Boolean).map((d) => new Date(d).getTime()).sort((a, b) => b - a);
       const now = Date.now();
@@ -21154,7 +21256,7 @@ var analysisTools = [
         avgDaysBetweenReleases = Math.round(gaps.reduce((a, b) => a + b, 0) / gaps.length);
       }
       const hasLicense = !!(pkg.license ?? latestVersion?.license);
-      const hasReadme = !!(pkg.readme && pkg.readme.length > 100);
+      const hasReadme = !!(pkg.readme && pkg.readme.length > 0);
       const hasRepo = !!pkg.repository;
       const hasHomepage = !!pkg.homepage;
       const isDeprecated = !!latestVersion?.deprecated;
@@ -21266,6 +21368,105 @@ var analysisTools = [
   }
 ];
 
+// src/tools/auth.ts
+var authTools = [
+  {
+    name: "npm_whoami",
+    description: "Check the currently authenticated npm user. Verifies the NPM_TOKEN is valid and returns the associated username. Essential for debugging auth issues before publishing.",
+    annotations: {
+      title: "Check npm auth",
+      readOnlyHint: true,
+      destructiveHint: false,
+      idempotentHint: true,
+      openWorldHint: true
+    },
+    inputSchema: external_exports.object({}),
+    handler: async () => {
+      const authErr = requireAuth();
+      if (authErr) return authErr;
+      return registryGetAuth("/-/whoami");
+    }
+  },
+  {
+    name: "npm_profile",
+    description: "Get the authenticated user's npm profile \u2014 name, email, 2FA status, creation date. Useful for checking whether 2FA is enabled (which affects token requirements for publishing).",
+    annotations: {
+      title: "Get npm profile",
+      readOnlyHint: true,
+      destructiveHint: false,
+      idempotentHint: true,
+      openWorldHint: true
+    },
+    inputSchema: external_exports.object({}),
+    handler: async () => {
+      const authErr = requireAuth();
+      if (authErr) return authErr;
+      const res = await registryGetAuth("/-/npm/v1/user");
+      if (!res.ok) return res;
+      const p = res.data;
+      return {
+        ok: true,
+        status: 200,
+        data: {
+          name: p.name,
+          email: p.email,
+          emailVerified: p.email_verified,
+          fullname: p.fullname,
+          tfa: p.tfa ? { enabled: true, mode: p.tfa.mode, pending: p.tfa.pending } : { enabled: false },
+          homepage: p.homepage,
+          github: p.github,
+          twitter: p.twitter,
+          created: p.created,
+          updated: p.updated,
+          cidrWhitelist: p.cidr_whitelist
+        }
+      };
+    }
+  },
+  {
+    name: "npm_tokens",
+    description: "List all access tokens for the authenticated npm user. Shows token type, creation date, CIDR restrictions, and read-only status. Critical for finding reusable automation/granular tokens that cover your org scope \u2014 avoids the common mistake of creating duplicate tokens or using publish tokens in CI (which still require OTP).",
+    annotations: {
+      title: "List npm tokens",
+      readOnlyHint: true,
+      destructiveHint: false,
+      idempotentHint: true,
+      openWorldHint: true
+    },
+    inputSchema: external_exports.object({
+      page: external_exports.number().min(0).optional().describe("Page number for pagination (default: 0)"),
+      perPage: external_exports.number().min(1).max(100).optional().describe("Results per page (default: 25)")
+    }),
+    handler: async (input) => {
+      const authErr = requireAuth();
+      if (authErr) return authErr;
+      const params = new URLSearchParams();
+      if (input.page !== void 0) params.set("page", String(input.page));
+      if (input.perPage !== void 0) params.set("perPage", String(input.perPage));
+      const qs = params.toString();
+      const path = `/-/npm/v1/tokens${qs ? `?${qs}` : ""}`;
+      const res = await registryGetAuth(path);
+      if (!res.ok) return res;
+      const data = res.data;
+      return {
+        ok: true,
+        status: 200,
+        data: {
+          total: data.total,
+          tokens: data.objects.map((t) => ({
+            token: t.token,
+            key: t.key,
+            readonly: t.readonly,
+            cidrWhitelist: t.cidr_whitelist,
+            created: t.created,
+            updated: t.updated
+          }))
+        }
+      };
+    }
+  }
+];
+
 // src/tools/dependencies.ts
 var dependencyTools = [
   {
@@ -21320,33 +21521,58 @@ var dependencyTools = [
     }),
     handler: async (input) => {
       const maxDepth = input.depth ?? 3;
-      const resolved = /* @__PURE__ */ new Map();
+      const MAX_CONCURRENT = 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, versionHint, currentDepth) {
-        const key = `${name}@${versionHint}`;
-        if (resolved.has(key) || currentDepth > maxDepth) return;
-        resolved.set(key, versionHint);
-        const res = await registryGetAbbreviated(`/${encPkg(name)}`);
-        if (!res.ok) {
-          tree[key] = { version: versionHint, dependencies: {} };
-          return;
+        const hintKey = `${name}@${versionHint}`;
+        if (resolved.has(hintKey) || currentDepth > maxDepth) return;
+        resolved.add(hintKey);
+        let pkg = packumentCache.get(name);
+        if (!pkg) {
+          const res = await runLimited(() => registryGetAbbreviated(`/${encPkg(name)}`));
+          if (!res.ok) {
+            warnings.push(`Failed to fetch ${name}: ${res.error}`);
+            tree[hintKey] = { version: versionHint, dependencies: {} };
+            return;
+          }
+          pkg = res.data;
+          packumentCache.set(name, pkg);
         }
-        const pkg = res.data;
         let resolvedVersion;
         if (pkg.versions[versionHint]) {
           resolvedVersion = versionHint;
         } else if (pkg["dist-tags"][versionHint]) {
           resolvedVersion = pkg["dist-tags"][versionHint];
         } else {
-          resolvedVersion = pkg["dist-tags"].latest ?? Object.keys(pkg.versions).pop() ?? versionHint;
+          resolvedVersion = pkg["dist-tags"]?.latest ?? versionHint;
         }
+        const resolvedKey = `${name}@${resolvedVersion}`;
+        if (tree[resolvedKey]) return;
         const versionData = pkg.versions[resolvedVersion];
         if (!versionData) {
-          tree[key] = { version: resolvedVersion, dependencies: {} };
+          tree[resolvedKey] = { version: resolvedVersion, dependencies: {} };
           return;
         }
         const deps = versionData.dependencies ?? {};
-        tree[`${name}@${resolvedVersion}`] = { version: resolvedVersion, dependencies: deps };
+        tree[resolvedKey] = { version: resolvedVersion, dependencies: deps };
         if (currentDepth < maxDepth) {
           const tasks = Object.entries(deps).map(([depName, depRange]) => resolve(depName, depRange, currentDepth + 1));
           await Promise.all(tasks);
@@ -21360,7 +21586,8 @@ var dependencyTools = [
           root: `${input.name}@${input.version ?? "latest"}`,
           depth: maxDepth,
           totalPackages: Object.keys(tree).length,
-          tree
+          tree,
+          ...warnings.length > 0 ? { warnings } : {}
         }
       };
     }
@@ -21377,7 +21604,10 @@ var dependencyTools = [
     },
     inputSchema: external_exports.object({
       name: external_exports.string().describe("Package name"),
-      version: external_exports.string().optional().describe("Semver version or dist-tag (default: 'latest')")
+      version: external_exports.string().optional().describe("Semver version or dist-tag (default: 'latest')"),
+      allowed: external_exports.array(external_exports.string()).optional().describe(
+        "SPDX license identifiers to treat as allowed (default: MIT, ISC, BSD-2-Clause, BSD-3-Clause, Apache-2.0, 0BSD, Unlicense)"
+      )
     }),
     handler: async (input) => {
       const ver = input.version ?? "latest";
@@ -21385,26 +21615,45 @@ var dependencyTools = [
       if (!res.ok) return res;
       const pkg = res.data;
       const deps = Object.keys(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 depLicenses = await Promise.all(
         deps.map(async (depName) => {
-          const depRes = await registryGet(`/${encPkg(depName)}/latest`);
+          const depRes = await runLimited(() => registryGet(`/${encPkg(depName)}/latest`));
           return {
             name: depName,
             license: depRes.ok ? depRes.data?.license ?? "UNKNOWN" : "FETCH_ERROR"
           };
         })
       );
-      const PERMISSIVE = /* @__PURE__ */ new Set(["MIT", "ISC", "BSD-2-Clause", "BSD-3-Clause", "Apache-2.0", "0BSD", "Unlicense"]);
+      const allowedSet = new Set(
+        input.allowed ?? ["MIT", "ISC", "BSD-2-Clause", "BSD-3-Clause", "Apache-2.0", "0BSD", "Unlicense"]
+      );
       const results = [
         { name: pkg.name, version: pkg.version, license: pkg.license ?? "UNKNOWN" },
         ...depLicenses.map((d) => ({ name: d.name, version: "latest", license: d.license }))
       ];
-      const flagged = results.filter((r) => !PERMISSIVE.has(r.license));
+      const flagged = results.filter((r) => !allowedSet.has(r.license));
       return {
         ok: true,
         status: 200,
         data: {
           total: results.length,
+          allowed: [...allowedSet],
           flagged: flagged.length,
           packages: results,
           issues: flagged.length > 0 ? flagged : void 0
@@ -21485,10 +21734,190 @@ var downloadTools = [
       openWorldHint: true
     },
     inputSchema: external_exports.object({
-      name: external_exports.string().describe("Package name")
+      name: external_exports.string().describe("Package name"),
+      period: external_exports.string().optional().describe("Period: 'last-day', 'last-week', 'last-month' (default: 'last-week')")
+    }),
+    handler: async (input) => {
+      const period = input.period ?? "last-week";
+      return downloadsGet(`/versions/${encPkg(input.name)}/${period}`);
+    }
+  }
+];
+
+// src/tools/hooks.ts
+var hookTools = [
+  {
+    name: "npm_hooks",
+    description: "List all npm webhooks configured for the authenticated user. Shows hook type (package, scope, or owner), endpoint URL, delivery status, and last response code.",
+    annotations: {
+      title: "List npm hooks",
+      readOnlyHint: true,
+      destructiveHint: false,
+      idempotentHint: true,
+      openWorldHint: true
+    },
+    inputSchema: external_exports.object({
+      package: external_exports.string().optional().describe("Filter hooks by package name"),
+      limit: external_exports.number().min(1).max(100).optional().describe("Max results (default: 25)"),
+      offset: external_exports.number().min(0).optional().describe("Pagination offset")
+    }),
+    handler: async (input) => {
+      const authErr = requireAuth();
+      if (authErr) return authErr;
+      const params = new URLSearchParams();
+      if (input.package) params.set("package", input.package);
+      if (input.limit !== void 0) params.set("limit", String(input.limit));
+      if (input.offset !== void 0) params.set("offset", String(input.offset));
+      const qs = params.toString();
+      const path = `/-/npm/v1/hooks${qs ? `?${qs}` : ""}`;
+      const res = await registryGetAuth(path);
+      if (!res.ok) return res;
+      const data = res.data;
+      return {
+        ok: true,
+        status: 200,
+        data: {
+          total: data.total,
+          hooks: data.objects.map((h) => ({
+            id: h.id,
+            type: h.type,
+            name: h.name,
+            endpoint: h.endpoint,
+            status: h.status,
+            lastDelivery: h.last_delivery,
+            lastResponseCode: h.response_code,
+            created: h.created,
+            updated: h.updated
+          }))
+        }
+      };
+    }
+  }
+];
+
+// src/tools/orgs.ts
+var orgTools = [
+  {
+    name: "npm_org_members",
+    description: "List all members of an npm organization with their roles (owner, admin, developer). Requires authentication as an org member.",
+    annotations: {
+      title: "List org members",
+      readOnlyHint: true,
+      destructiveHint: false,
+      idempotentHint: true,
+      openWorldHint: true
+    },
+    inputSchema: external_exports.object({
+      org: external_exports.string().describe("Organization name (without @ prefix)")
+    }),
+    handler: async (input) => {
+      const authErr = requireAuth();
+      if (authErr) return authErr;
+      const res = await registryGetAuth(`/-/org/${encodeURIComponent(input.org)}/user`);
+      if (!res.ok) return res;
+      const members = Object.entries(res.data).map(([username, role]) => ({ username, role }));
+      return {
+        ok: true,
+        status: 200,
+        data: {
+          org: input.org,
+          memberCount: members.length,
+          members
+        }
+      };
+    }
+  },
+  {
+    name: "npm_org_packages",
+    description: "List all packages accessible to an npm organization with their access levels. Shows what the org owns or has been granted access to.",
+    annotations: {
+      title: "List org packages",
+      readOnlyHint: true,
+      destructiveHint: false,
+      idempotentHint: true,
+      openWorldHint: true
+    },
+    inputSchema: external_exports.object({
+      org: external_exports.string().describe("Organization name (without @ prefix)")
+    }),
+    handler: async (input) => {
+      const authErr = requireAuth();
+      if (authErr) return authErr;
+      const res = await registryGetAuth(`/-/org/${encodeURIComponent(input.org)}/package`);
+      if (!res.ok) return res;
+      const packages = Object.entries(res.data).map(([name, access]) => ({ name, access }));
+      return {
+        ok: true,
+        status: 200,
+        data: {
+          org: input.org,
+          packageCount: packages.length,
+          packages
+        }
+      };
+    }
+  },
+  {
+    name: "npm_org_teams",
+    description: "List all teams within an npm organization. Requires authentication as an org member.",
+    annotations: {
+      title: "List org teams",
+      readOnlyHint: true,
+      destructiveHint: false,
+      idempotentHint: true,
+      openWorldHint: true
+    },
+    inputSchema: external_exports.object({
+      org: external_exports.string().describe("Organization name (without @ prefix)")
+    }),
+    handler: async (input) => {
+      const authErr = requireAuth();
+      if (authErr) return authErr;
+      const res = await registryGetAuth(`/-/org/${encodeURIComponent(input.org)}/team`);
+      if (!res.ok) return res;
+      return {
+        ok: true,
+        status: 200,
+        data: {
+          org: input.org,
+          teamCount: res.data.length,
+          teams: res.data
+        }
+      };
+    }
+  },
+  {
+    name: "npm_team_packages",
+    description: "List all packages a specific team has access to and their permission levels (read-only or read-write). Useful for auditing team permissions.",
+    annotations: {
+      title: "List team packages",
+      readOnlyHint: true,
+      destructiveHint: false,
+      idempotentHint: true,
+      openWorldHint: true
+    },
+    inputSchema: external_exports.object({
+      org: external_exports.string().describe("Organization name (without @ prefix)"),
+      team: external_exports.string().describe("Team name")
     }),
     handler: async (input) => {
-      return downloadsGet(`/versions/${encPkg(input.name)}/last-week`);
+      const authErr = requireAuth();
+      if (authErr) return authErr;
+      const res = await registryGetAuth(
+        `/-/team/${encodeURIComponent(input.org)}/${encodeURIComponent(input.team)}/package`
+      );
+      if (!res.ok) return res;
+      const packages = Object.entries(res.data).map(([name, permissions]) => ({ name, permissions }));
+      return {
+        ok: true,
+        status: 200,
+        data: {
+          org: input.org,
+          team: input.team,
+          packageCount: packages.length,
+          packages
+        }
+      };
     }
   }
 ];
@@ -21512,8 +21941,8 @@ var packageTools = [
       const res = await registryGet(`/${encPkg(input.name)}`);
       if (!res.ok) return res;
       const pkg = res.data;
-      const latest = pkg["dist-tags"].latest;
-      const latestVersion = pkg.versions[latest];
+      const latest = pkg["dist-tags"]?.latest;
+      const latestVersion = latest ? pkg.versions[latest] : void 0;
       return {
         ok: true,
         status: 200,
@@ -21553,7 +21982,39 @@ var packageTools = [
     }),
     handler: async (input) => {
       const ver = input.version ?? "latest";
-      return registryGet(`/${encPkg(input.name)}/${ver}`);
+      const res = await registryGet(`/${encPkg(input.name)}/${ver}`);
+      if (!res.ok) return res;
+      const v = res.data;
+      return {
+        ok: true,
+        status: 200,
+        data: {
+          name: v.name,
+          version: v.version,
+          description: v.description,
+          license: v.license,
+          author: v.author,
+          maintainers: v.maintainers,
+          homepage: v.homepage,
+          repository: v.repository,
+          bugs: v.bugs,
+          keywords: v.keywords,
+          engines: v.engines,
+          dependencies: v.dependencies ?? {},
+          devDependencies: v.devDependencies ?? {},
+          peerDependencies: v.peerDependencies ?? {},
+          optionalDependencies: v.optionalDependencies ?? {},
+          deprecated: v.deprecated ?? false,
+          dist: {
+            shasum: v.dist.shasum,
+            integrity: v.dist.integrity,
+            tarball: v.dist.tarball,
+            fileCount: v.dist.fileCount,
+            unpackedSize: v.dist.unpackedSize
+          },
+          publisher: v._npmUser?.name
+        }
+      };
     }
   },
   {
@@ -21633,6 +22094,47 @@ var packageTools = [
   }
 ];
 
+// src/tools/provenance.ts
+var provenanceTools = [
+  {
+    name: "npm_provenance",
+    description: "Get Sigstore provenance attestations for a specific package version. Shows SLSA provenance (which CI built it, from which repo/commit) and publish attestations. Essential for supply chain security verification.",
+    annotations: {
+      title: "Package provenance",
+      readOnlyHint: true,
+      destructiveHint: false,
+      idempotentHint: true,
+      openWorldHint: true
+    },
+    inputSchema: external_exports.object({
+      name: external_exports.string().describe("Package name (e.g. '@anthropic-ai/sdk')"),
+      version: external_exports.string().describe("Exact semver version (e.g. '1.0.0')")
+    }),
+    handler: async (input) => {
+      const res = await registryGet(
+        `/-/npm/v1/attestations/${encPkg(input.name)}@${input.version}`
+      );
+      if (!res.ok) return res;
+      const attestations = (res.data.attestations ?? []).map((a) => ({
+        predicateType: a.predicateType,
+        bundle: a.bundle
+      }));
+      return {
+        ok: true,
+        status: 200,
+        data: {
+          package: input.name,
+          version: input.version,
+          attestationCount: attestations.length,
+          hasProvenance: attestations.some((a) => a.predicateType.includes("slsa.dev/provenance")),
+          hasPublishAttestation: attestations.some((a) => a.predicateType.includes("npmjs.com/attestation")),
+          attestations
+        }
+      };
+    }
+  }
+];
+
 // src/tools/registry.ts
 var registryTools = [
   {
@@ -21668,7 +22170,6 @@ var registryTools = [
     }),
     handler: async (input) => {
       const limit = input.limit ?? 25;
-      const infoRes = await replicateGet("/_db_updates");
       const dbRes = await replicateGet("/");
       if (!dbRes.ok) return dbRes;
       const since = dbRes.data.update_seq - limit;
@@ -21726,7 +22227,7 @@ var searchTools = [
         description: obj.package.description,
         date: obj.package.date,
         license: obj.package.license,
-        publisher: obj.package.publisher?.username,
+        publisher: obj.package.publisher,
         keywords: obj.package.keywords,
         links: obj.package.links,
         score: obj.score.detail,
@@ -21801,8 +22302,281 @@ var securityTools = [
   }
 ];
 
+// src/tools/workflows.ts
+var workflowTools = [
+  {
+    name: "npm_check_auth",
+    description: "Quick auth health check \u2014 returns structured data about npm auth status, token capability, and whether headless (CI/agent) publishing is possible. Run this BEFORE attempting any publish operation. Returns canPublishHeadless boolean and a clear recommendation.\n\nMCP servers are called by AI agents which CANNOT open browsers or enter OTP codes. This tool detects that and provides the exact terminal command for the human to run instead of suggesting unworkable retries.",
+    annotations: {
+      title: "Check npm auth health",
+      readOnlyHint: true,
+      destructiveHint: false,
+      idempotentHint: true,
+      openWorldHint: true
+    },
+    inputSchema: external_exports.object({}),
+    handler: async () => {
+      const result = {
+        authenticated: false,
+        username: null,
+        twoFactorAuth: "unknown",
+        tokenType: "unknown",
+        canPublishHeadless: false,
+        recommendation: null
+      };
+      if (!isAuthenticated()) {
+        result.recommendation = 'No NPM_TOKEN configured. Run "npm login" in your terminal, or create a token at https://www.npmjs.com/settings/~/tokens';
+        return { ok: true, status: 200, data: result };
+      }
+      const whoamiRes = await registryGetAuth("/-/whoami");
+      if (!whoamiRes.ok) {
+        result.recommendation = `Token is set but invalid (HTTP ${whoamiRes.status}). It may be expired or revoked. Create a new token at https://www.npmjs.com/settings/~/tokens`;
+        return { ok: true, status: 200, data: result };
+      }
+      result.authenticated = true;
+      result.username = whoamiRes.data.username;
+      const profileRes = await registryGetAuth("/-/npm/v1/user");
+      if (profileRes.ok && profileRes.data) {
+        const tfa = profileRes.data.tfa;
+        if (tfa && !tfa.pending) {
+          result.twoFactorAuth = tfa.mode;
+        } else {
+          result.twoFactorAuth = "disabled";
+        }
+      }
+      const tokensRes = await registryGetAuth("/-/npm/v1/tokens");
+      if (tokensRes.ok && tokensRes.data) {
+        const tokens = tokensRes.data.objects;
+        const hasReadWrite = tokens.some((t) => !t.readonly);
+        result.tokenCount = tokensRes.data.total;
+        result.hasReadWriteTokens = hasReadWrite;
+      }
+      if (result.twoFactorAuth === "disabled") {
+        result.canPublishHeadless = true;
+        result.tokenType = "any (2FA disabled)";
+        result.recommendation = "2FA is disabled \u2014 any valid token can publish. Consider enabling 2FA for security.";
+      } else {
+        result.tokenType = "unknown (tokens are redacted in API)";
+        result.canPublishHeadless = null;
+        result.recommendation = `2FA is enabled (${result.twoFactorAuth}). Headless publishing ONLY works with automation/granular tokens. Publish tokens from ~/.npmrc ALWAYS require OTP and WILL fail in CI/agent contexts. If publish fails with EOTP, your token is a publish token \u2014 you need an automation token.`;
+        result.ifPublishFails = {
+          errorType: "2FA_REQUIRED",
+          humanAction: {
+            label: "Publish from your terminal (one-time)",
+            command: "npm publish --access public --auth-type=web",
+            context: "Run in an INTERACTIVE terminal \u2014 a browser will open for 2FA. Do NOT run through piped/agent runners."
+          },
+          permanentFix: {
+            label: "Set up automation token (permanent fix for CI/agents)",
+            url: "https://www.npmjs.com/settings/~/tokens",
+            instructions: "Create a 'Granular Access Token' with publish permissions scoped to your org/packages. Then set it as your CI secret or run: npm config set //registry.npmjs.org/:_authToken=<token>"
+          }
+        };
+      }
+      return { ok: true, status: 200, data: result };
+    }
+  },
+  {
+    name: "npm_publish_preflight",
+    description: "Comprehensive pre-publish validation \u2014 run before publishing ANY npm package. Returns an actionable checklist with pass/fail/warn for each item.\n\nASSUMES NON-INTERACTIVE CONTEXT BY DEFAULT because MCP servers are called by AI agents that:\n- CANNOT open browsers (so --auth-type=web is useless)\n- CANNOT enter OTP codes\n- CANNOT retry with 2FA \u2014 this is a hand-off to the human\n\nChecks: auth token validity, 2FA requirements, token type inference, org-level token reuse, package name availability, maintainer access, scoped package settings.\n\nWhen issues are found, returns structured actions with exact commands for the HUMAN to run in their terminal \u2014 never suggests actions an agent cannot perform.",
+    annotations: {
+      title: "Publish preflight check",
+      readOnlyHint: true,
+      destructiveHint: false,
+      idempotentHint: true,
+      openWorldHint: true
+    },
+    inputSchema: external_exports.object({
+      name: external_exports.string().describe("Package name to publish (e.g. '@yawlabs/npmjs-mcp')")
+    }),
+    handler: async (input) => {
+      const checks = [];
+      const actions = [];
+      const isScoped = input.name.startsWith("@");
+      const scope = isScoped ? input.name.split("/")[0] : null;
+      let username = null;
+      let twoFactorAuth = null;
+      let canPublishHeadless = null;
+      if (!isAuthenticated()) {
+        checks.push({
+          check: "NPM_TOKEN configured",
+          status: "fail",
+          detail: "No NPM_TOKEN environment variable set. Publishing requires authentication."
+        });
+        actions.push({
+          label: "Login interactively",
+          command: "npm login",
+          context: "Run in your terminal to create a publish token"
+        });
+        actions.push({
+          label: "Create automation token (for CI/agents)",
+          url: "https://www.npmjs.com/settings/~/tokens",
+          context: `Create a Granular Access Token with publish permissions${scope ? ` scoped to ${scope}` : ""}, then set NPM_TOKEN in your environment`
+        });
+      } else {
+        const whoamiRes = await registryGetAuth("/-/whoami");
+        if (!whoamiRes.ok) {
+          checks.push({
+            check: "NPM_TOKEN valid",
+            status: "fail",
+            detail: `Token rejected (HTTP ${whoamiRes.status}). Expired or revoked.`
+          });
+          actions.push({
+            label: "Create new token",
+            url: "https://www.npmjs.com/settings/~/tokens",
+            context: "Your current token is invalid. Create a new Granular Access Token."
+          });
+        } else {
+          username = whoamiRes.data.username;
+          checks.push({
+            check: "NPM_TOKEN valid",
+            status: "pass",
+            detail: `Authenticated as: ${username}`
+          });
+        }
+        if (username) {
+          const profileRes = await registryGetAuth("/-/npm/v1/user");
+          if (profileRes.ok && profileRes.data) {
+            const tfa = profileRes.data.tfa;
+            if (tfa && !tfa.pending) {
+              twoFactorAuth = tfa.mode;
+              checks.push({
+                check: "2FA status",
+                status: "info",
+                detail: `2FA is enabled (mode: ${tfa.mode}). In this non-interactive context:
+  - Automation/granular tokens: can publish (bypass 2FA)
+  - Publish tokens (from ~/.npmrc): WILL FAIL with EOTP error
+  - --auth-type=web: IMPOSSIBLE (needs browser)
+  - OTP codes: IMPOSSIBLE (agent can't enter them)`
+              });
+            } else {
+              twoFactorAuth = "disabled";
+              canPublishHeadless = true;
+              checks.push({
+                check: "2FA status",
+                status: "warn",
+                detail: "2FA is disabled. Any valid token can publish, but 2FA is strongly recommended for security."
+              });
+            }
+          }
+          const tokensRes = await registryGetAuth("/-/npm/v1/tokens");
+          if (tokensRes.ok && tokensRes.data) {
+            const tokens = tokensRes.data.objects;
+            const totalTokens = tokensRes.data.total;
+            const readWriteTokens = tokens.filter((t) => !t.readonly);
+            if (twoFactorAuth && twoFactorAuth !== "disabled") {
+              if (readWriteTokens.length > 0) {
+                checks.push({
+                  check: "Token capability",
+                  status: "warn",
+                  detail: `Found ${readWriteTokens.length} read-write token(s) out of ${totalTokens} total. Cannot determine token type from API (tokens are redacted). If publish fails with EOTP, your active token is a publish-type token \u2014 you need an automation/granular token.`
+                });
+                canPublishHeadless = null;
+              } else {
+                checks.push({
+                  check: "Token capability",
+                  status: "fail",
+                  detail: "No read-write tokens found. You need a token with publish permissions."
+                });
+                canPublishHeadless = false;
+              }
+            }
+            if (isScoped && scope) {
+              checks.push({
+                check: "Org-scope token reuse",
+                status: "info",
+                detail: `${input.name} is under ${scope}. You have ${totalTokens} token(s). If any are granular tokens scoped to ${scope}, they cover ALL packages under that scope \u2014 check your tokens at https://www.npmjs.com/settings/~/tokens before creating duplicates.`
+              });
+            }
+          }
+        }
+      }
+      const pkgRes = await registryGet(`/${encPkg(input.name)}`);
+      if (!pkgRes.ok && pkgRes.status === 404) {
+        checks.push({
+          check: "Package name available",
+          status: "pass",
+          detail: `"${input.name}" is not taken \u2014 you can publish it as a new package.`
+        });
+        if (isScoped) {
+          checks.push({
+            check: "First publish access flag",
+            status: "info",
+            detail: "First publish of a scoped package requires --access public (otherwise it defaults to restricted/paid)."
+          });
+        }
+      } else if (pkgRes.ok && pkgRes.data) {
+        const pkg = pkgRes.data;
+        const maintainers = pkg.maintainers?.map((m) => m.name) ?? [];
+        const isMaintainer = username ? maintainers.includes(username) : null;
+        if (isMaintainer === true) {
+          checks.push({
+            check: "Maintainer access",
+            status: "pass",
+            detail: `You (${username}) are a maintainer of ${input.name}.`
+          });
+        } else if (isMaintainer === false) {
+          checks.push({
+            check: "Maintainer access",
+            status: "fail",
+            detail: `You (${username}) are NOT a maintainer. Maintainers: ${maintainers.join(", ")}. You need to be added as a maintainer or collaborator.`
+          });
+        } else {
+          checks.push({
+            check: "Package exists",
+            status: "info",
+            detail: `"${input.name}" exists. Maintainers: ${maintainers.join(", ") || "unknown"}. Authenticate to check your access.`
+          });
+        }
+      }
+      if (twoFactorAuth && twoFactorAuth !== "disabled" && canPublishHeadless !== true) {
+        actions.push({
+          label: "Publish from your terminal (one-time)",
+          command: "npm publish --access public --auth-type=web",
+          context: "Run this in an INTERACTIVE terminal (not piped through an agent or ! runner). A browser will open for 2FA."
+        });
+        actions.push({
+          label: "Set up automation token (permanent fix for CI/agents)",
+          url: "https://www.npmjs.com/settings/~/tokens",
+          context: `Create a 'Granular Access Token' with publish permissions${scope ? ` scoped to ${scope} packages` : ""}. This bypasses 2FA for headless publishing.`
+        });
+      }
+      const failures = checks.filter((c) => c.status === "fail");
+      const warnings = checks.filter((c) => c.status === "warn");
+      const passes = checks.filter((c) => c.status === "pass");
+      let summary;
+      if (failures.length > 0) {
+        summary = `BLOCKED: ${failures.length} issue(s) must be resolved before publishing.`;
+      } else if (canPublishHeadless === false) {
+        summary = "BLOCKED: No suitable token for headless publishing. See actions below.";
+      } else if (canPublishHeadless === null && twoFactorAuth !== "disabled") {
+        summary = "UNCERTAIN: 2FA is enabled and token type cannot be verified. Publishing may fail with EOTP. If it does, this is a hand-off to the human \u2014 do NOT retry. See actions below.";
+      } else if (warnings.length > 0) {
+        summary = `READY with ${warnings.length} warning(s). Review before proceeding.`;
+      } else {
+        summary = "READY to publish. All checks passed.";
+      }
+      const response = {
+        package: input.name,
+        context: "non-interactive (MCP/agent)",
+        summary,
+        canPublishHeadless,
+        passCount: passes.length,
+        warnCount: warnings.length,
+        failCount: failures.length,
+        checks
+      };
+      if (actions.length > 0) {
+        response.humanActions = actions;
+        response.agentNote = "The actions below are for the HUMAN to run in their terminal. Do NOT attempt these through piped runners, ! commands, or automation. Do NOT retry the publish. Do NOT suggest --otp. Present these actions to the user and wait for them to complete the step manually.";
+      }
+      return { ok: true, status: 200, data: response };
+    }
+  }
+];
+
 // src/index.ts
-var version2 = true ? "0.1.0" : (await null).createRequire(import.meta.url)("../package.json").version;
+var version2 = true ? "0.3.0" : (await null).createRequire(import.meta.url)("../package.json").version;
 var subcommand = process.argv[2];
 if (subcommand === "version" || subcommand === "--version") {
   console.log(version2);
@@ -21815,7 +22589,13 @@ var allTools = [
   ...downloadTools,
   ...securityTools,
   ...analysisTools,
-  ...registryTools
+  ...registryTools,
+  ...authTools,
+  ...orgTools,
+  ...accessTools,
+  ...provenanceTools,
+  ...hookTools,
+  ...workflowTools
 ];
 var server = new McpServer({
   name: "@yawlabs/npmjs-mcp",

package/package.json

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