{"_id":"@agentic-web-labs/npm-advisor-mcp","name":"@agentic-web-labs/npm-advisor-mcp","dist-tags":{"latest":"0.4.0"},"versions":{"0.4.0":{"name":"@agentic-web-labs/npm-advisor-mcp","version":"0.4.0","description":"MCP server exposing npm package intelligence (security, license, scoring, recommendations) to MCP-aware AI clients like Claude Code, Claude Desktop, and Cursor.","keywords":["mcp","model-context-protocol","npm","dependencies","security","advisories","vulnerability","license","bundle-size","package-analysis","publint","e18e","claude","cursor","ai","llm"],"license":"Apache-2.0","author":{"name":"Agentic Web Labs"},"homepage":"https://github.com/amedina/agentic-web-labs/tree/develop/packages/mcp/npm-advisor-mcp#readme","repository":{"type":"git","url":"git+https://github.com/amedina/agentic-web-labs.git","directory":"packages/mcp/npm-advisor-mcp"},"bugs":{"url":"https://github.com/amedina/agentic-web-labs/issues"},"type":"module","engines":{"node":">=20"},"main":"./dist/server.js","bin":{"npm-advisor-mcp":"dist/server.js"},"publishConfig":{"access":"public"},"devDependencies":{"@modelcontextprotocol/sdk":"^1.25.2","@types/node":"^24.3.0","esbuild":"^0.25.0","rimraf":"^5.0.5","typescript":"~5.8.3","vitest":"^4.1.0","zod":"4.3.5","@agentic-web-labs/package-analyzer-core":"1.0.0","@agentic-web-labs/shared-config":"1.1.0","@agentic-web-labs/project-analyzer-core":"1.0.0"},"scripts":{"prebuild":"rimraf dist","build":"node esbuild.config.js --production","dev":"node esbuild.config.js --watch","start":"node dist/server.js","start:http":"node dist/server.js --http","check-types":"tsc --noEmit","format":"prettier . --write","test":"vitest run --root . --silent"},"_id":"@agentic-web-labs/npm-advisor-mcp@0.4.0","_integrity":"sha512-9d79gMQUY0z/LdNFJaDpsxERPJo6p+G4LtgGaRUG2REqLkrArQWw3S5IArFMLVdz0CUMlSFK965s0ZSHb3gj5A==","_resolved":"/private/var/folders/ly/d4kl537d55j8qj98115vsqw40000gn/T/4d1dc6ad405763d9e2ba6617968a2e2a/agentic-web-labs-npm-advisor-mcp-0.4.0.tgz","_from":"file:agentic-web-labs-npm-advisor-mcp-0.4.0.tgz","_nodeVersion":"24.14.1","_npmVersion":"11.12.1","dist":{"integrity":"sha512-9d79gMQUY0z/LdNFJaDpsxERPJo6p+G4LtgGaRUG2REqLkrArQWw3S5IArFMLVdz0CUMlSFK965s0ZSHb3gj5A==","shasum":"00b899f5444571c5966d239e2ec45a83a7eb2eaf","tarball":"https://registry.npmjs.org/@agentic-web-labs/npm-advisor-mcp/-/npm-advisor-mcp-0.4.0.tgz","fileCount":4,"unpackedSize":14948401,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIQC01B0hOEj7KJsKxHbksgVJmdG4qsC5MXtMoDlIfaPakAIgc1npu92a1Klk5HyluYtZ90K5Vsa33rEUouGifI+36vc="}]},"_npmUser":{"name":"albertomedina","email":"aa.medina@gmail.com"},"directories":{},"maintainers":[{"name":"albertomedina","email":"aa.medina@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/npm-advisor-mcp_0.4.0_1781715120638_0.15197304989475469"},"_hasShrinkwrap":false}},"time":{"created":"2026-06-17T16:52:00.410Z","0.4.0":"2026-06-17T16:52:00.942Z","modified":"2026-06-17T16:52:01.173Z"},"maintainers":[{"name":"albertomedina","email":"aa.medina@gmail.com"}],"description":"MCP server exposing npm package intelligence (security, license, scoring, recommendations) to MCP-aware AI clients like Claude Code, Claude Desktop, and Cursor.","homepage":"https://github.com/amedina/agentic-web-labs/tree/develop/packages/mcp/npm-advisor-mcp#readme","keywords":["mcp","model-context-protocol","npm","dependencies","security","advisories","vulnerability","license","bundle-size","package-analysis","publint","e18e","claude","cursor","ai","llm"],"repository":{"type":"git","url":"git+https://github.com/amedina/agentic-web-labs.git","directory":"packages/mcp/npm-advisor-mcp"},"author":{"name":"Agentic Web Labs"},"bugs":{"url":"https://github.com/amedina/agentic-web-labs/issues"},"license":"Apache-2.0","readme":"# NPM Advisor MCP server\n\nAn MCP (Model Context Protocol) server that exposes npm package intelligence to MCP-aware AI clients like **Claude Code**, **Claude Desktop**, **Cursor**, **Continue**, and any future MCP-aware editor or agent.\n\nIt's the same analysis pipeline that powers the [NPM Advisor VSCode extension](https://marketplace.visualstudio.com/items?itemName=AgenticWebLabs.vscode-npm-advisor) and the [NPM Advisor Chrome extension](https://chromewebstore.google.com/detail/npm-advisor/iheaipmbkihiebidhfigbpliililcifh): Fitness scoring, GitHub Security Advisories, license compatibility against your project's target license, bundle size, last-commit / stars, and replacement recommendations from [e18e](https://github.com/e18e/module-replacements).\n\n## What it gives your AI\n\nFive tools:\n\n| Tool                          | What it returns                                                                                                                                                                                                                                                                                                                                                                                       | When the model calls it                                                              |\n| ----------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------ |\n| `get_package_stats`           | Full `PackageStats` for one package: Fitness score, security advisories, license + compatibility verdict, bundle size, GitHub stars + last commit, replacement recommendations.                                                                                                                                                                                                                       | \"Tell me about lodash.\" \"Is express maintained?\" \"Compare lodash and underscore.\"    |\n| `list_known_vscode_projects`  | **Needs the [NPM Advisor VSCode extension](https://marketplace.visualstudio.com/items?itemName=AgenticWebLabs.vscode-npm-advisor).** Lists every workspace that extension has tracked (absolute path, parsed `name`, open/closed status, last-opened time), so a client with no project context (such as Claude Desktop) can resolve \"my project\". Returns empty when the extension is not installed. | \"Which project should I look at?\" \"What do I have open in VSCode?\"                   |\n| `list_workspace_dependencies` | Every `package.json` under a directory with its `name` and dep counts (no network). Auto-ascends from the server's working directory to the surrounding monorepo root. Maps a project before drilling in; works standalone, no VSCode extension needed.                                                                                                                                               | \"What does this project look like?\" \"Where do my dependencies live?\"                 |\n| `analyze_package_json`        | Per-dep stats for one `package.json` plus a roll-up summary (vulnerable / license-incompatible / replaceable counts).                                                                                                                                                                                                                                                                                 | \"Audit this project.\" \"Which dependencies should I worry about?\"                     |\n| `analyze_project`             | Analyzes one package (the single `package.json` at `rootPath`): [publint](https://publint.dev) publish-readiness, circular-dependency cycles, and e18e replacement opportunities for its declared deps, returned as one findings list tagged `publint` / `circular-deps` / `replacements`. The MCP equivalent of the VSCode extension's single-package \"project analysis\"; run it once per package to cover a monorepo. Read-only.                                                                       | \"Is my package.json ready to publish?\" \"Do I have any import cycles?\" \"Which of my deps have lighter alternatives?\" |\n\nEvery tool returns plain JSON in the MCP `text` content slot so any AI client can parse it deterministically. The `get_package_stats`, `analyze_package_json`, and `analyze_project` tools include rendering hints in their descriptions that instruct Claude to present results as a rich visual artifact (metric cards, score bar chart, tabbed sections) when the client supports it.\n\n## Quick install\n\nThe server runs as a Node binary. The recommended invocation is via `npx` so you don't have to manage a global install or a path:\n\n```sh\nnpx -y @agentic-web-labs/npm-advisor-mcp\n```\n\nIt speaks MCP over stdio by default. Configure your AI client to spawn it as shown below, or jump to [HTTP transport](#http-transport-host-it-on-localhost-or-a-remote-server) to run it as a long-lived local or remote server instead.\n\n> The examples throughout this README include an optional `GITHUB_TOKEN`. It is **not required** (the server runs fine without it), but a public-read token raises the GitHub API rate limit from 60 to 5,000 requests per hour, which the analysis relies on for advisories, stars, and last-commit data. Omit it to stay unauthenticated, or see [GitHub authentication](#github-authentication-optional-but-recommended) for the details and required scopes.\n\n### Claude Code\n\nAdd the server via the Claude Code CLI from your project root:\n\n```sh\nclaude mcp add npm-advisor --env GITHUB_TOKEN=ghp_… -- npx -y @agentic-web-labs/npm-advisor-mcp\n```\n\nThis writes an entry to `~/.claude.json` (or `.mcp.json` if you want it scoped to the project). Restart any open Claude Code session and ask: _\"List my dependencies and tell me which ones have security issues.\"_\n\n### Claude Desktop\n\nEdit `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or `%APPDATA%\\Claude\\claude_desktop_config.json` (Windows):\n\n```json\n{\n  \"mcpServers\": {\n    \"npm-advisor\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@agentic-web-labs/npm-advisor-mcp\"],\n      \"env\": {\n        \"GITHUB_TOKEN\": \"ghp_…\"\n      }\n    }\n  }\n}\n```\n\nRestart Claude Desktop. The tools appear under the connector icon in the chat composer.\n\n### Cursor\n\nIn Cursor's settings, open _MCP_ → _Add new global MCP server_ and paste:\n\n```json\n{\n  \"mcpServers\": {\n    \"npm-advisor\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@agentic-web-labs/npm-advisor-mcp\"],\n      \"env\": {\n        \"GITHUB_TOKEN\": \"ghp_…\"\n      }\n    }\n  }\n}\n```\n\nCursor's Composer can now call the tools. Toggle them on under MCP Tools when you start a chat.\n\n### VSCode (built-in MCP support, 1.96+)\n\nAdd to your workspace's `.vscode/mcp.json` (or user-scope `mcp.json`):\n\n```json\n{\n  \"servers\": {\n    \"npm-advisor\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@agentic-web-labs/npm-advisor-mcp\"],\n      \"env\": {\n        \"GITHUB_TOKEN\": \"ghp_…\"\n      }\n    }\n  }\n}\n```\n\nCopilot Chat in agent mode will discover the tools.\n\n### Continue\n\nIn `~/.continue/config.json` (or the project-scoped `.continue/config.json`):\n\n```json\n{\n  \"experimental\": {\n    \"modelContextProtocolServers\": [\n      {\n        \"transport\": {\n          \"type\": \"stdio\",\n          \"command\": \"npx\",\n          \"args\": [\"-y\", \"@agentic-web-labs/npm-advisor-mcp\"],\n          \"env\": {\n            \"GITHUB_TOKEN\": \"ghp_…\"\n          }\n        }\n      }\n    ]\n  }\n}\n```\n\n## HTTP transport (host it on localhost or a remote server)\n\nBy default the binary speaks MCP over stdio so AI clients can spawn it as a subprocess. Pass `--http` to instead start a Streamable HTTP server. This is useful when you want one running instance shared between several clients on your machine, or when you want to host npm-advisor on a remote server and connect to it over the network.\n\n### Run locally\n\n```sh\nGITHUB_TOKEN=ghp_… npx -y @agentic-web-labs/npm-advisor-mcp --http\n```\n\nThis binds to `127.0.0.1:3845` (loopback only, not reachable from other machines) and serves MCP at `http://127.0.0.1:3845/mcp`.\n\nOverride the port and host with flags:\n\n```sh\nnpx -y @agentic-web-labs/npm-advisor-mcp --http --port 4000 --host 127.0.0.1\n```\n\nPoint any MCP-aware client at the URL. For example, Claude Desktop:\n\n```json\n{\n  \"mcpServers\": {\n    \"npm-advisor\": {\n      \"transport\": \"http\",\n      \"url\": \"http://127.0.0.1:3845/mcp\"\n    }\n  }\n}\n```\n\nIn HTTP mode the optional `GITHUB_TOKEN` is set where the server is launched (shown above), not in the client config, since the client only connects to the URL.\n\n### Host it remotely\n\nTo accept connections from other machines, bind to a non-loopback address (`0.0.0.0` for all interfaces, or a specific interface IP):\n\n```sh\nGITHUB_TOKEN=ghp_… MCP_HTTP_TOKEN=your-long-random-token \\\n  npx -y @agentic-web-labs/npm-advisor-mcp --http --host 0.0.0.0 --port 3845\n```\n\nWhen `MCP_HTTP_TOKEN` is set, every request must include:\n\n```\nAuthorization: Bearer your-long-random-token\n```\n\nThe server prints a warning to stderr if you bind to a non-loopback address without a token. Public deployments should also sit behind a reverse proxy that terminates TLS (`https://`); the server itself only speaks plain HTTP.\n\nA typical Claude Desktop entry pointing at a hosted instance:\n\n```json\n{\n  \"mcpServers\": {\n    \"npm-advisor\": {\n      \"transport\": \"http\",\n      \"url\": \"https://npm-advisor.example.com/mcp\",\n      \"headers\": {\n        \"Authorization\": \"Bearer your-long-random-token\"\n      }\n    }\n  }\n}\n```\n\n### CLI flags\n\n| Flag                      | Default           | Description                                              |\n| ------------------------- | ----------------- | -------------------------------------------------------- |\n| `--http`                  | (off, stdio mode) | Switch to the Streamable HTTP transport.                 |\n| `--port <n>`              | `3845`            | TCP port to listen on.                                   |\n| `--host <addr>`           | `127.0.0.1`       | Bind address. Use `0.0.0.0` to expose on all interfaces. |\n| `--transport stdio\\|http` | `stdio`           | Long form of `--http` / `--stdio`.                       |\n\n`--port`, `--host`, and `--transport` also accept the `--name=value` form.\n\n## GitHub authentication (optional but recommended)\n\nWithout a token GitHub rate-limits the server's API calls to **60 requests / hour / IP**, which is easy to exhaust during a workspace audit. Set a personal-access token in the environment your AI client launches the server in:\n\n```sh\nexport GITHUB_TOKEN=ghp_…\n```\n\nOr `GH_TOKEN`, which is also recognized. With a token the rate limit jumps to **5,000 requests / hour**.\n\n### Create a token\n\n1. Open [github.com/settings/tokens](https://github.com/settings/tokens) and choose **Generate new token → Generate new token (classic)**.\n2. Give it a name (for example `npm-advisor-mcp`) and an expiration.\n3. Leave every scope unchecked. The server reads only public data and never touches private repositories, so no scopes are required (the token still raises the rate limit).\n4. Click **Generate token** and copy the `ghp_…` value. GitHub shows it only once.\n5. Set it as `GITHUB_TOKEN` (or `GH_TOKEN`) in your MCP client's `env` block using one of the configs above, or `export` it in the shell that launches the server.\n\nPrefer a [fine-grained token](https://github.com/settings/personal-access-tokens/new)? Create one with read-only **Public Repositories** access and no account permissions.\n\nA typical Claude Desktop entry with auth:\n\n```json\n{\n  \"mcpServers\": {\n    \"npm-advisor\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@agentic-web-labs/npm-advisor-mcp\"],\n      \"env\": {\n        \"GITHUB_TOKEN\": \"ghp_…\"\n      }\n    }\n  }\n}\n```\n\nA ready-to-copy template lives at [`.env.example`](https://github.com/amedina/agentic-web-labs/blob/develop/packages/mcp/npm-advisor-mcp/.env.example) in the source repo. Copy the keys you need into your MCP client's `env` block, or `source` the file before running the binary directly.\n\nOn startup the server prints one line to stderr indicating whether a token was detected, so you can confirm your client actually forwarded the env var:\n\n```\nnpm-advisor-mcp: GitHub auth = token (from $GITHUB_TOKEN); rate limit 5,000 req/hr\n```\n\nor, when no token was passed:\n\n```\nnpm-advisor-mcp: GitHub auth = unauthenticated; rate limit 60 req/hr (set $GITHUB_TOKEN to lift)\n```\n\n## How it works\n\n```\n                ┌──────────────────────────────────────┐\n                │  Claude Desktop / Code / Cursor /    │\n                │  Continue / VSCode (MCP-aware AI)    │\n                └─────────────────┬────────────────────┘\n                                  │ JSON-RPC over stdio\n                                  │   or Streamable HTTP (--http)\n                                  ▼\n            ┌───────────────────────────────────────────┐\n            │  npm-advisor-mcp (this package)           │\n            │   ┌─────────────────────────────────────┐ │\n            │   │ McpServer (modelcontextprotocol)    │ │\n            │   │   tools:                            │ │\n            │   │   • get_package_stats               │ │\n            │   │   • list_known_vscode_projects      │ │\n            │   │   • list_workspace_dependencies     │ │\n            │   │   • analyze_package_json            │ │\n            │   │   • analyze_project                 │ │\n            │   └─────────────────────────────────────┘ │\n            │   ┌─────────────────────────────────────┐ │\n            │   │ Analysis engine (bundled)           │ │\n            │   │   data sources:                     │ │\n            │   │   - npm registry                    │ │\n            │   │   - GitHub GraphQL (advisories,     │ │\n            │   │     stars, last commit)             │ │\n            │   │   - Bundlephobia (size)             │ │\n            │   │   - OSADL license matrix            │ │\n            │   │   - e18e replacement rules          │ │\n            │   │   - calculateScore (Fitness)        │ │\n            │   └─────────────────────────────────────┘ │\n            └───────────────────────────────────────────┘\n```\n\nThe AI client either spawns this process as a subprocess (stdio mode, default) or connects to a long-running HTTP instance (Streamable HTTP mode, `--http`). Either way, tools register on startup, the client lists them, and the model invokes any tool at any time. Every tool result flows back as JSON the model can quote, summarize, or act on.\n\n## Privacy\n\nAll API calls go to public endpoints: `registry.npmjs.org`, `bundlephobia.com`, `api.github.com`, and the OSADL license matrix bundled into the server. This server doesn't phone home anywhere else, and reads only files under the workspace path you ask `list_workspace_dependencies`, `analyze_package_json`, or `analyze_project` to scan.\n\n## Build from source\n\nThe package lives in the [agentic-web-labs](https://github.com/amedina/agentic-web-labs) monorepo. To build it yourself:\n\n```sh\ngit clone https://github.com/amedina/agentic-web-labs.git\ncd agentic-web-labs\npnpm install\npnpm build:npm-advisor-mcp\n```\n\nThis produces `packages/mcp/npm-advisor-mcp/dist/server.js` with a shebang and the executable bit set, so you can also point your AI client straight at it during development:\n\n```json\n{\n  \"mcpServers\": {\n    \"npm-advisor-dev\": {\n      \"command\": \"node\",\n      \"args\": [\"/absolute/path/to/dist/server.js\"],\n      \"env\": {\n        \"GITHUB_TOKEN\": \"ghp_…\"\n      }\n    }\n  }\n}\n```\n\nTo run the built server directly from the repo root for local testing (for example, against the [MCP Inspector](https://github.com/modelcontextprotocol/inspector)):\n\n```sh\n# stdio mode\npnpm start:npm-advisor-mcp\n\n# Streamable HTTP mode on http://127.0.0.1:3845/mcp\npnpm start:npm-advisor-mcp:http\n```\n\n## License\n\n[Apache-2.0](./LICENSE)\n\n## Related packages\n\n- [NPM Advisor Chrome extension](https://chromewebstore.google.com/detail/npm-advisor/iheaipmbkihiebidhfigbpliililcifh)\n- [NPM Advisor VSCode extension](https://marketplace.visualstudio.com/items?itemName=AgenticWebLabs.vscode-npm-advisor), which also exposes these tools through `@npm-advisor` in Copilot Chat\n","readmeFilename":"README.md","_rev":"1-cf17ecaf288d2fa005c91e609ba1328b"}