Npm Advisor Mcp

npm-advisor-mcp

A Model Context Protocol (MCP) server that acts as an intelligent npm package advisor. Describe the feature you need, and it will search the registry, compare candidates, audit for vulnerabilities, and recommend the best library based on bundle size, popularity, maintenance, TypeScript support, and more.

Features

• Search by feature — describe what you need (e.g., "date manipulation", "PDF generation") and get ranked results
• Side-by-side comparison — compare 2–5 packages on key metrics in a clean table format
• Deep package details — full breakdown of a single package: README, dependencies, scores, links
• Weighted recommendations — algorithm-driven pick with dynamic weights per use case (browser, Node.js, React, CLI)
• Security audit — check for known CVEs with severity breakdown and patch availability
• Deprecation check — detect deprecated, abandoned, or unmaintained packages with a clear verdict
• Find alternatives — discover competing packages when migrating away from a deprecated library
• Install command generator — copy-paste commands for npm, yarn, pnpm, and bun with peer deps included
• Changelog viewer — fetch recent release notes from GitHub, GitLab (cloud + self-hosted), or Bitbucket
• Technical Q&A — ask specific questions about a package and get contextual answers from its metadata
• In-memory caching — all API responses are cached with TTL to eliminate redundant network calls

Architecture

npm-advisor-mcp/├── package.json                  # Project manifest (ESM, Node 18+)├── tsconfig.json                 # TypeScript strict config (ES2022/Node16)├── mcp-config.json               # Ready-to-use Kiro MCP configuration snippet├── src/│   ├── index.ts                  # MCP server entry point (stdio transport)│   ├── models/│   │   └── types.ts              # Shared interfaces and scoring weights│   ├── services/│   │   ├── cache.ts              # In-memory TTL cache (2/5/10 min tiers)│   │   ├── npm-registry.ts       # registry.npmjs.org client│   │   ├── npm-audit.ts          # npm security advisory API client│   │   ├── bundlephobia.ts       # Bundle size data (bundlephobia.com)│   │   ├── npms-io.ts            # Quality/maintenance/popularity scores│   │   └── scoring.ts            # Weighted recommendation engine + license checker│   └── tools/│       ├── search-packages.ts│       ├── compare-packages.ts│       ├── package-details.ts│       ├── recommend.ts│       ├── resolve-doubt.ts│       ├── audit-package.ts│       ├── find-alternatives.ts│       ├── check-deprecation.ts│       ├── generate-install-command.ts│       └── get-changelog.ts└── dist/                         # Compiled output (generated by `npm run build`)

Prerequisites

• Node.js 18+ (uses native fetch)
• npm 9+

No API keys required — all data sources are public and free.

Installation

cd C:\Users\617500221\Projects\AI-Tools\npm-advisor-mcpnpm installnpm run build

Configuration (Kiro MCP)

Add this to your ~/.kiro/settings/mcp.json inside the "mcpServers" object:

"npm-advisor": {  "command": "node",  "args": [    "C:\\Users\\617500221\\Projects\\AI-Tools\\npm-advisor-mcp\\dist\\index.js"  ],  "disabled": false,  "autoApprove": [    "search_packages",    "compare_packages",    "get_package_details",    "recommend_package",    "resolve_technical_doubt",    "audit_package",    "find_alternatives",    "check_deprecation",    "generate_install_command",    "get_changelog"  ]}

After saving, the server will appear in the Kiro MCP panel and reconnect automatically.

Tools Reference

1. search_packages

Search npm for packages matching a feature or keyword.

Example prompt:

"Search for packages that handle PDF generation in Node.js"

Returns: Ranked list with description, weekly downloads, gzip size, quality/maintenance/popularity scores, and tree-shaking support.

2. compare_packages

Compare 2–5 packages side-by-side on all key metrics.

Example prompt:

"Compare dayjs, date-fns, and moment for date manipulation"

Returns: Markdown table with version, gzip size, minified size, downloads/week, TypeScript support, tree-shaking, dependency count, maintenance score, quality score, last publish date, and license.

3. get_package_details

Deep dive into a single package with full metadata.

Example prompt:

"Get details about the zod package"

Returns: Version, description, quick stats table (downloads, sizes, deps, TS support, license, publish date), quality scores, dependency list, peer dependencies, links, keywords, and a README excerpt.

4. recommend_package

Get a weighted recommendation from a list of candidates. Scoring weights automatically adjust based on your target environment.

Example prompt:

"Recommend a date library from dayjs, date-fns, moment, and luxon for a browser app — must be under 10KB gzipped"

Returns: Winner with rationale, runner-up alternatives, a detailed score breakdown table, and a license compatibility column.

Default Scoring Weights (general)

Use Case Weight Adjustments

5. resolve_technical_doubt

Answer a specific technical question about a package.

Example prompts:

"Does dayjs support timezone conversion out of the box?" "Is lodash tree-shakeable?" "What are the peer dependencies of @angular/material?" "Is chalk still actively maintained?"

Returns: Contextual answer pulling from metadata, bundle analysis, dependency tree, scores, and README content. Automatically detects question category (size, TypeScript, dependencies, maintenance, tree-shaking) and surfaces relevant data.

6. audit_package

Check a package for known security vulnerabilities.

Example prompt:

"Are there any known vulnerabilities in lodash?"

Returns: Total vulnerability count, severity breakdown (critical/high/moderate/low), per-CVE details with affected version ranges, patch availability, advisory links, and a deprecation warning if applicable.

7. find_alternatives

Find similar or competing packages as alternatives to a given one.

Example prompts:

"Find alternatives to moment.js" "What can I use instead of request?"

Returns: Ranked list of alternatives with descriptions, weekly downloads, bundle sizes, quality scores, and tree-shaking support. Flags if the original package is deprecated.

8. check_deprecation

Detect if a package is deprecated, unmaintained, or potentially abandoned.

Example prompts:

"Is request still maintained?" "Is moment.js deprecated?"

Returns: npm deprecation flag, days since last publish, maintenance score, weekly downloads, and a clear verdict — actively maintained / moderately stale / potentially abandoned / officially deprecated.

9. generate_install_command

Generate ready-to-paste install commands across all major package managers.

Example prompts:

"Give me the install command for @tanstack/react-query" "How do I install eslint as a dev dependency with pnpm?"

Returns: Install commands for npm, yarn, pnpm, and bun. Automatically appends peer dependencies and adds a separate @types/ install block if the package lacks built-in TypeScript types.

10. get_changelog

Fetch recent release notes for a package from its git repository. Supports GitHub, GitLab (cloud and self-hosted), and Bitbucket.

Example prompts:

"What changed in the last few versions of zod?" "Show me the recent releases for vite" "What's new in @ATLAS/info-panel?"

Returns: Release history with version tags, publish dates, and formatted release notes (truncated at 800 chars per release).

Git host detection

The tool reads the repository field from the package's package.json and auto-detects the host:

Note for private/internal packages: The tool reads the repository field from the package metadata fetched from your registry. If your internal package.json doesn't include a repository field, or uses an SSH URL like git@internal-git:atlas/info-panel without a recognisable hostname, the tool won't be able to detect the host. Add a full HTTPS URL to fix this:

json

"repository": "https://gitlab.yourcompany.com/atlas/info-panel"

11. check_registry (diagnostic)

Shows which registry URL and auth credentials the server resolves for a given package name, based on ~/.npmrc. Run this first when debugging private registry access.

Example prompt:

"Check registry for @ATLAS/info-panel"

Returns: Resolved registry URL, whether an auth token was found, and guidance if it's resolving to the public registry unexpectedly.

Data Sources

All requests include timeouts (10–15s) and graceful fallbacks — if one API is slow or unavailable, the tool still returns partial results rather than failing. Responses are cached in-memory to avoid redundant calls within a session.

Private Registry Support (.npmrc)

The server reads ~/.npmrc directly to resolve the registry URL and auth token for each package. No shell subprocess is involved — it parses the file the same way npm does, so it works regardless of how the MCP server process was spawned.

This means scoped private packages like @your-company/some-lib work out of the box as long as your .npmrc is configured correctly — for example:

@ATLAS:registry=https://your-company-registry.example.com///your-company-registry.example.com/:_authToken=your-token

Scope names in .npmrc are matched case-insensitively — @ATLAS, @atlas, and @Atlas all match the same entry.

Registry resolution logic

For every package fetch, the server:

1. Reads ~/.npmrc and looks for a scoped registry override matching the package scope (e.g. @ATLAS:registry=...)
2. If found, uses that registry URL with the corresponding auth token
3. If not found, uses the default registry value from .npmrc (or registry.npmjs.org if not set)
4. If the resolved registry fails and it wasn't already the public registry, automatically retries against registry.npmjs.org — so public packages always work even if a custom default registry is configured

Use the check_registry tool to verify what registry and auth the server resolves for any package before running other tools.

Public vs private package support

For private packages, tools that depend on bundlephobia or npms.io (search_packages, find_alternatives, bundle size in comparisons) will show N/A for those fields but will still return all registry metadata correctly.

Caching

All API responses are cached in-memory with tiered TTLs:

The cache is process-scoped — it resets when the MCP server restarts.

Development

# Watch mode (recompiles on save)npm run dev
# Single buildnpm run build
# Run directlynpm start

Project Scripts

Tech Stack

Zero runtime dependencies beyond the MCP SDK and zod. No database, no external auth.

How It Works

1. User asks a question in Kiro (e.g., "find me a library for CSV parsing")
2. Kiro routes to the appropriate tool based on the prompt
3. The tool checks the in-memory cache — returns instantly if data is fresh
4. On cache miss, fetches live data from npm registry, npms.io, bundlephobia, and GitHub in parallel
5. Results are scored, formatted, and returned as structured markdown
6. Kiro presents the answer in the chat with tables, scores, and actionable recommendations

The server runs as a stdio process — Kiro spawns it on demand and communicates via JSON-RPC over stdin/stdout.

Extending

To add a new tool:

1. Create src/tools/your-tool.ts with a handler function
2. Register it in src/index.ts using server.tool(name, description, zodSchema, handler)
3. Add the tool name to autoApprove in mcp-config.json
4. Rebuild: npm run build

To add a new data source:

1. Create src/services/your-source.ts with fetch functions
2. Wrap responses with cache.set / cache.get from services/cache.ts
3. Import and use it in the relevant tool handlers
4. Add timeout + graceful fallback for resilience

Troubleshooting

If running behind a corporate proxy that intercepts HTTPS (e.g., Zscaler), add your corporate CA certificate to the MCP config:

"env": {  "NODE_EXTRA_CA_CERTS": "C:\\path\\to\\your\\corporate-ca.pem"}

This is the recommended fix. Node's native fetch does not respect NODE_TLS_REJECT_UNAUTHORIZED=0 in all cases, and disabling TLS verification entirely is a security risk. Using NODE_EXTRA_CA_CERTS adds your corporate CA to Node's trust store without disabling verification for everything else.

To find your corporate CA cert path, check with your IT team or look in your system certificate store. On Windows it is typically exported from certmgr.msc → Trusted Root Certification Authorities.

If you also need an explicit proxy:

"env": {  "NODE_EXTRA_CA_CERTS": "C:\\path\\to\\your\\corporate-ca.pem",  "HTTPS_PROXY": "http://your-proxy:8080"}

License

ISC