README.md
NPM package analysis with health scoring and license risk assessment
npm-registry-mcp
A Model Context Protocol (MCP) server for NPM package analysis with health scoring, license risk assessment, and comprehensive package evaluation.
Features
- 4 MCP Tools for searching, inspecting, and evaluating NPM packages
- CLI Interface for direct usage from the terminal
- Health Scoring with weighted factors (maintenance, popularity, security, dependencies)
- License Risk Assessment using SPDX identifiers (Low/Medium/High/Critical)
- GitHub Integration for commit activity and repository health
- In-Memory Caching with 5-minute TTL for API responses
Installation
From Source
go install github.com/howmanysmall/npm-registry-mcp/src@latest
From Releases
Download the latest binary from GitHub Releases.
Build Locally
git clone https://github.com/howmanysmall/npm-registry-mcp.git
cd npm-registry-mcp
go build -o npm-registry-mcp ./src
Configuration
Environment Variables
| Variable | Required | Description |
|---|---|---|
GITHUB_TOKEN |
No | GitHub Personal Access Token for higher API rate limits (60/hr without, 5000/hr with) |
.env File Support
Create a .env file in the working directory:
GITHUB_TOKEN=ghp_xxxxxxxxxxxxxxxxxxxx
Usage with Claude Desktop
Add to your claude_desktop_config.json:
{
"mcpServers": {
"npm-registry": {
"command": "/path/to/npm-registry-mcp",
"env": {
"GITHUB_TOKEN": "ghp_xxxxxxxxxxxxxxxxxxxx"
}
}
}
}
CLI Usage
The binary can be used directly as a CLI tool. If no subcommands are provided, it defaults to starting the MCP server.
Search for packages
./npm-registry-mcp search react --limit 5
Get package details
./npm-registry-mcp info lodash
List package versions
./npm-registry-mcp versions express --limit 20
Evaluate package health
./npm-registry-mcp health react
JSON Output
All commands support the --json flag for machine-readable output.
./npm-registry-mcp health react --json
Tools
search-npm-packages
Search the NPM registry for packages.
Input:
| Parameter | Type | Required | Description |
|---|---|---|---|
query |
string | Yes | Search query |
limit |
integer | No | Max results (1-100, default: 10) |
Example:
{
"query": "react",
"limit": 5
}
get-npm-package
Get detailed information about an NPM package.
Input:
| Parameter | Type | Required | Description |
|---|---|---|---|
name |
string | Yes | Package name |
Example:
{
"name": "lodash"
}
Returns: Name, version, description, license, homepage, repository, maintainers, keywords, dependencies, and recent versions.
should-i-install
Comprehensive health check for evaluating whether to install a package.
Input:
| Parameter | Type | Required | Description |
|---|---|---|---|
package |
string | Yes | Package name to evaluate |
Example:
{
"package": "lodash"
}
Returns:
verdict:"yes"|"caution"|"no"score: 0-100 health scoremaintenance: Last publish date and statusdependencies: Direct, transitive, and outdated countssecurity: Vulnerability countpopularity: Weekly downloads and trendlicense: SPDX identifier and risk levelwarnings: Array of concern messages
Verdict Criteria:
| Verdict | Criteria |
|---|---|
yes |
Score >= 70, no warnings, no vulnerabilities |
caution |
Score 40-69, or warnings present |
no |
Score < 40, or vulnerabilities present |
Health Scoring Algorithm
| Factor | Weight | Description |
|---|---|---|
| Last Publish | 25% | Time since last release (100 pts if <=30 days) |
| Download Trend | 20% | Growth/decline in weekly downloads |
| Dependencies | 20% | Percentage of outdated dependencies |
| Commit Activity | 15% | Commits in last 90 days (requires GitHub token) |
| Maintainers | 10% | Number of active maintainers |
| Vulnerabilities | 10% | Known security vulnerabilities |
License Risk Levels
| Risk | Examples | Description |
|---|---|---|
| Low | MIT, Apache-2.0, BSD-3-Clause, ISC | Permissive, safe for any use |
| Medium | LGPL-3.0, MPL-2.0, EPL-2.0 | Weak copyleft, some restrictions |
| High | GPL-3.0, AGPL-3.0 | Strong copyleft, derivative works must share |
| Critical | SSPL-1.0, BUSL-1.1, UNLICENSED | Problematic, review with legal |
Development
# Build
go build -o npm-registry-mcp ./src
# Test
go test -v -race ./...
# Lint
golangci-lint run ./...
# Integration tests (requires network)
go test -tags=integration -v ./src
Building & Releasing
Local Build
go build -o npm-registry-mcp ./src
``
Tools (3)
search-npm-packagesSearch the NPM registry for packages.get-npm-packageGet detailed information about an NPM package.should-i-installComprehensive health check for evaluating whether to install a package.Environment Variables
GITHUB_TOKENGitHub Personal Access Token for higher API rate limitsConfiguration
claude_desktop_config.json
{"mcpServers": {"npm-registry": {"command": "/path/to/npm-registry-mcp", "env": {"GITHUB_TOKEN": "ghp_xxxxxxxxxxxxxxxxxxxx"}}}}Try it
→Search for popular react state management libraries.
→Get detailed information about the lodash package.
→Should I install the express package? Please perform a health check.
→Evaluate the health and security risks of the axios package.