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-mcp
npm install
npm 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.

Parameter	Type	Required	Description
query	string	Yes	Feature or keyword (e.g., "form validation", "state management")
limit	number	No	Max results to return (default: 8, max: 15)

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.

Parameter	Type	Required	Description
packages	string[]	Yes	Array of package names (2–5 items)

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.

Parameter	Type	Required	Description
package_name	string	Yes	The npm package name

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.

Parameter	Type	Required	Description
packages	string[]	Yes	Array of package names to evaluate (2–10)
max_size_kb	number	No	Max acceptable gzip size in KB — packages exceeding this get penalized
require_typescript	boolean	No	If true, packages without TS types are penalized more
use_case	string	No	browser, node, react, cli, or general — adjusts scoring weights

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)

Criterion	Weight	What it measures
Bundle size (gzip)	25%	Smaller is better; relative within comparison group
Weekly downloads	20%	Community adoption (log-scaled)
Maintenance	20%	npms.io maintenance score
TypeScript support	15%	Built-in types (100) > @types (60) > none (20)
Dependency count	10%	Fewer runtime deps = less risk
Freshness	10%	More recently published = better

Use Case Weight Adjustments

Criterion	browser	node	react	cli
Bundle size	40%	10%	30%	5%
Downloads	15%	20%	20%	20%
Maintenance	15%	25%	15%	30%
TypeScript	15%	15%	20%	10%
Dependencies	10%	20%	10%	20%
Freshness	5%	10%	5%	15%

5. resolve_technical_doubt

Answer a specific technical question about a package.

Parameter	Type	Required	Description
package_name	string	Yes	The npm package name
question	string	Yes	Your technical question

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.

Parameter	Type	Required	Description
package_name	string	Yes	The npm package name to audit

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.

Parameter	Type	Required	Description
package_name	string	Yes	The package to find alternatives for
limit	number	No	Max alternatives to return (default: 6, max: 10)

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.

Parameter	Type	Required	Description
package_name	string	Yes	The npm package name to check

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.

Parameter	Type	Required	Description
package_name	string	Yes	The npm package name
include_peer_deps	boolean	No	Include peer dependencies (default: true)
dev	boolean	No	Install as a dev dependency (default: false)

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.

Parameter	Type	Required	Description
package_name	string	Yes	The npm package name
limit	number	No	Number of recent releases to show (default: 5, max: 10)

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:

Pattern in repository URL	Detected as	API used
github.com/...	GitHub	GitHub Releases API
gitlab.com/...	GitLab cloud	GitLab Releases API
gitlab.yourcompany.com/...	Self-hosted GitLab	GitLab Releases API (same path, different base URL)
git.yourcompany.com/...	Self-hosted GitLab	GitLab Releases API
bitbucket.org/...	Bitbucket	Bitbucket Tags API
None of the above	—	Falls back to npm versions page link

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:

"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.

Parameter	Type	Required	Description
package_name	string	Yes	The package name to check resolution for

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

API	Base URL	What it provides	Auth
npm Registry	resolved from .npmrc (default: registry.npmjs.org)	Package metadata, versions, README, deps, deprecation	Via .npmrc
npm Downloads	api.npmjs.org/downloads	Weekly download counts	None
npm Audit	resolved from .npmrc + /-/npm/v1/security/audits	Known CVEs and advisories	Via .npmrc
npms.io	api.npms.io/v2	Search + quality/maintenance/popularity scores	None
Bundlephobia	bundlephobia.com/api	Minified size, gzip size, tree-shaking, side effects	None
GitHub API	api.github.com	Release notes and changelog	None
GitLab API	gitlab.com/api/v4 or self-hosted /api/v4	Release notes and changelog	None (public) / token if private
Bitbucket API	api.bitbucket.org/2.0	Tags used as release history	None

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:

• Reads ~/.npmrc and looks for a scoped registry override matching the package scope (e.g. @ATLAS:registry=...)
• If found, uses that registry URL with the corresponding auth token
• If not found, uses the default registry value from .npmrc (or registry.npmjs.org if not set)
• 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

Source	Public packages	Private registry packages
Registry metadata	✅ Full	✅ Full (via .npmrc auth)
Weekly downloads	✅	✅ (npm downloads API is public)
Bundle size	✅	❌ Bundlephobia only indexes public npm
npms.io scores	✅	❌ npms.io only indexes public npm
Security audit	✅	⚠️ Also checks public npm advisory DB as fallback
Changelog	✅ GitHub / GitLab / Bitbucket	✅ If repository field has a full HTTPS URL

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:

Tier	TTL	Used for
Short	2 min	Download counts, npms.io scores, search results
Medium	5 min	npm registry metadata, GitHub releases
Long	10 min	Bundle sizes, security audit results

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

Development

# Watch mode (recompiles on save)
npm run dev

# Single build
npm run build

# Run directly
npm start

Project Scripts

Script	Command	Description
build	tsc	Compile TypeScript to dist/
start	node dist/index.js	Run the MCP server
dev	tsc --watch	Watch mode for development

Tech Stack

Technology	Version	Purpose
Node.js	18+	Runtime (native fetch)
TypeScript	~5.5	Type safety
@modelcontextprotocol/sdk	^1.12	MCP server framework
zod	^3.23	Schema validation for tool inputs

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

How It Works

• User asks a question in Kiro (e.g., "find me a library for CSV parsing")
• Kiro routes to the appropriate tool based on the prompt
• The tool checks the in-memory cache — returns instantly if data is fresh
• On cache miss, fetches live data from npm registry, npms.io, bundlephobia, and GitHub in parallel
• Results are scored, formatted, and returned as structured markdown
• 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:

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

To add a new data source:

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

Troubleshooting

Issue	Solution
Server doesn't appear in Kiro	Check mcp.json path is correct; ensure dist/index.js exists
"Cannot find module" errors	Run npm run build after any source changes
Timeout errors from APIs	Normal behind corporate proxies — results will be partial
Bundle size shows "N/A"	Bundlephobia can't analyze all packages (native addons, etc.)
Audit returns no results	npm advisory API may not have data for that package version
Changelog shows no releases	Package may not use GitHub/GitLab releases, or repository field is missing/SSH-only in package.json
Private package returns "not found"	Run check_registry to verify the registry URL and auth token are resolving correctly from ~/.npmrc
check_registry shows wrong registry	Check ~/.npmrc has @SCOPE:registry=https://... and //host/:_authToken=... entries

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