NPM Sentinel MCP

A powerful Model Context Protocol (MCP) server that revolutionizes NPM package analysis through AI. Built to integrate with Claude and Anthropic AI, it provides real-time intelligence on package security, dependencies, and performance. This MCP server delivers instant insights and smart analysis to safeguard and optimize your npm ecosystem, making package management decisions faster and safer for modern development workflows.

Features

Version analysis and tracking
Dependency analysis and mapping
Advanced Security Scanning: Recursive dependency checks, ecosystem awareness (e.g., React), and accurate version resolution.
Strict Input Validation & Batch Rate Control: Input sanitization via Zod against Path Traversal, SSRF, and Command Injection. Search queries (npmSearch) are capped at 100 characters and filtered for control characters. Batch analysis tools enforce a strict cap of 25 packages per request to prevent registry enumeration DoS.
Smart SemVer Shorthand & Range Resolution: Transparently resolves major version shorthands, prefixes, and ranges (e.g., express@2, express@v4, zod@3.x, react@^18, lodash@~4.17) to the highest matching release without failing on missing exact version keys.
Indirect Prompt Injection Defense (OWASP LLM01): All tools returning raw 3rd-party Markdown/text (npmPackageReadme, npmChangelogAnalysis) wrap untrusted content in <untrusted_external_content> tags, attach _meta.untrustedExternalContent = true flags, and enforce strict tool schema warnings.
Package quality metrics
Download trends and statistics
TypeScript support verification
Package size analysis
Maintenance metrics
Real-time package comparisons
Standardized error handling and MCP response formats
Efficient caching for improved performance and API rate limit management
Rigorous schema validation and type safety using Zod

Note: The server provides AI-assisted analysis through MCP integration.

Security & OWASP LLM01 Compliance

This server implements Defense-in-Depth controls aligned with OWASP LLM01:2025 (Indirect Prompt Injection):

XML Data Demarcation: Content from external packages (README.md, GitHub changelogs, release notes) is wrapped inside <untrusted_external_content source="..." package="..." type="..."> tags so consuming LLM models distinguish untrusted data from instructions.
Metadata Signaling (_meta): Responses include _meta.untrustedExternalContent = true and _meta.sources arrays for programmatic client-side detection and policy enforcement.
Tool & Prompt Safety Warnings: Tool descriptions and prompt definitions explicitly instruct LLM agents to treat documentation as passive data and ignore embedded execution commands.
Batch Size Capping & Query Sanitization: All 18 multi-package analysis tools enforce a 25-package limit per request (PackageListSchema). Search queries are sanitized and capped at 100 characters (SearchQuerySchema).
Prototype Pollution Protection: Enforces Object.hasOwn() checks on dictionary lookups (blocking reserved properties like constructor and __proto__).

Caching and Invalidation

To ensure data accuracy while maintaining performance, the server implements robust caching strategies:

Automatic Invalidation: The cache is automatically invalidated whenever pnpm-lock.yaml, package-lock.json, or yarn.lock changes in your workspace. This ensures you always get fresh data after installing or updating dependencies.
Force Refresh: All tools accept an optional ignoreCache: true parameter to bypass the cache and force a fresh lookup from the registry.

Example Usage (JSON-RPC)

When calling a tool, simply include ignoreCache: true in the arguments:

{
  "name": "npmVersions",
  "arguments": {
    "packages": ["react"],
    "ignoreCache": true
  }
}

Installation

Migration to HTTP Streamable

This MCP server now supports both STDIO and HTTP streamable transport. Your existing STDIO configuration will continue to work without changes.

New capabilities:

HTTP streamable transport via Smithery.ai
Enhanced scalability and performance
Interactive testing playground

Development commands:

# Compile TypeScript
pnpm run build

# Start STDIO server
pnpm run start

# Development server with playground
pnpm run dev

Install in VS Code

Add this to your VS Code MCP config file. See VS Code MCP docs for more info.

{
  "servers": {
    "npm-sentinel": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@nekzus/mcp-server@latest"]
    }
  }
}

Smithery.ai Deployment (HTTP Streamable)

This MCP server now supports HTTP streamable transport through Smithery.ai for enhanced scalability and performance. You can deploy it directly on Smithery.ai: Benefits of HTTP deployment:

Scalable: Handles multiple concurrent connections
Streamable: Real-time streaming responses
Managed: Automatic deployment and monitoring
Backward Compatible: Still supports STDIO for local development
Interactive Testing: Built-in playground for testing tools

Configuration for Smithery.ai:

{
  "mcpServers": {
    "npm-sentinel": {
      "type": "http",
      "url": "https://smithery.ai/server/@Nekzus/npm-sentinel-mcp"
    }
  }
}

Configuration

The server supports the following configuration options:

Environment Variable	CLI Argument	Default	Description
`NPM_REGISTRY_URL`	`config.NPM_REGISTRY_URL`	`https://registry.npmjs.org`	URL of the NPM registry to use for all requests

HTTP Deployment (Smithery/Docker)

When deploying via Smithery or Docker, you can configure these options in your configuration file:

{
  "mcpServers": {
    "npm-sentinel": {
      "type": "http",
      "url": "https://smithery.ai/server/@Nekzus/npm-sentinel-mcp",
      "config": {
        "NPM_REGISTRY_URL": "https://registry.npmjs.org"
      }
    }
  }
}

Docker

Build

# Build the Docker image
docker build -t nekzus/npm-sentinel-mcp .

Usage

You can run the MCP server using Docker with directory mounting to /projects:

{
  "mcpServers": {
    "npm-sentinel-mcp": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-w", "/projects",
        "--mount", "type=bind,src=${PWD},dst=/projects",
        "nekzus/npm-sentinel-mcp",
        "node",
        "dist/index.js"
      ]
    }
  }
}

For multiple directories:

{
  "mcpServers": {
    "npm-sentinel-mcp": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-w", "/projects",
        "--mount", "type=bind,src=/path/to/workspace,dst=/projects/workspace",
        "--mount", "type=bind,src=/path/to/other/dir,dst=/projects/other/dir,ro",
        "nekzus/npm-sentinel-mcp",
        "node",
        "dist/index.js"
      ]
    }
  }
}

Note: All mounted directories must be under /projects for proper access.

Usage with Claude Desktop

Add this to your claude_desktop_config.json:

{
  "mcpServers": {
    "npmsentinel": {
      "command": "npx",
      "args": ["-y", "@nekzus/mcp-server@latest"]
    }
  }
}

Configuration file locations:

Windows: %APPDATA%\Claude\claude_desktop_config.json
macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Linux: (Claude for Desktop does not officially support Linux at this time)

NPX

{
  "mcpServers": {
    "npm-sentinel-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "@nekzus/mcp-server@latest"
      ]
    }
  }
}

API

The server exposes its tools via the Model Context Protocol. All tools adhere to a standardized response format:

{
  "content": [
    {
      "type": "text",
      "text": "string",
      "isError": boolean // Optional
    }
    // ... more content items if necessary
  ]
}

Resources

npm://registry: NPM Registry interface
npm://security: Security analysis interface
npm://metrics: Package metrics interface

Server Resources

The server also provides the following informational resources accessible via MCP GetResource requests:

doc://server/readme:
- Description: Retrieves the main README.md file content for this NPM Sentinel MCP server.
- MIME Type: text/markdown
doc://mcp/specification:
- Description: Retrieves the llms-full.txt content, providing the comprehensive Model Context Protocol specification.
- MIME Type: text/plain

Tools

npmVersions

Get all versions of a package
Input: packages (string[])
Returns: Version history with release dates

npmLatest

Get latest version information
Input: packages (string[])
Returns: Latest version details and changelog

npmDeps

Analyze package dependencies
Input: packages (string[])
Returns: Complete dependency tree analysis including direct dependencies and full transitive graph (count and explicit flatten list) mapping through deps.dev.

npmTypes

Check TypeScript support
Input: packages (string[])
Returns: TypeScript compatibility status

npmSize

Analyze package size
Input: packages (string[])
Returns: Bundle size and import cost analysis

npmVulnerabilities

Scan for security vulnerabilities
Features:
- Instant Transitive Scanning: Powered by Google's deps.dev API to resolve massive dependency trees (e.g. Next.js, Astro) in a single request, bypassing deep recursion limitations.
- Ecosystem Awareness: Automatically scans related packages efficiently.
- Rich Reports: Includes CVE IDs and full summaries from OSV.dev.
Input: packages (string[])
Returns: Detailed security advisories, CVEs, and severity ratings

npmTrends

Get download trends
Input:
- packages (string[])
- period ("last-week" | "last-month" | "last-year")
Returns: Download statistics over time

npmCompare

Compare multiple packages
Input: packages (string[])
Returns: Detailed comparison metrics

npmMaintainers

Get package maintainers
Input: packages (string[])
Returns: Maintainer information and activity

npmScore

Get package quality score
Input: packages (string[])
Returns: Comprehensive quality metrics, scoring details, and OpenSSF Scorecard.

npmPackageReadme

Get package README
Input: packages (string[])
Returns: Formatted README content

npmSearch

Search for packages
Input:
- query (string)
- limit (number, optional)
Returns: Matching packages with metadata

npmLicenseCompatibility

Check license compatibility
Input: packages (string[])
Returns: License analysis and compatibility info

npmRepoStats

Get repository statistics
Input: packages (string[])
Returns: GitHub/repository metrics (stars, forks, open issues) along with OpenSSF Scorecard checks and scores via deps.dev.

npmDeprecated

Check for deprecation
Input: packages (string[])
Returns: Deprecation status and alternatives

npmChangelogAnalysis

Analyze package changelogs
Input: packages (string[])
Returns: Changelog summaries and impact analysis

npmAlternatives

Find package alternatives
Input: packages (string[])
Returns: Similar packages with comparisons

npmQuality

Assess package quality
Input: packages (string[])
Returns: Quality metrics and scores

npmMaintenance

Check maintenance status
Input: packages (string[])
Returns: Maintenance activity metrics

Build

# Install dependencies
pnpm install

# Build TypeScript
pnpm run build

# Start the STDIO server
pnpm run start

# Development server
pnpm run dev

License

This MCP server is licensed under the MIT License. This means you are free to use, modify, and distribute the software, subject to the terms and conditions of the MIT License. For more details, please see the LICENSE file in the project repository.

MIT © nekzus

Name		Name	Last commit message	Last commit date
Latest commit History 421 Commits
.github		.github
__tests__		__tests__
.gitattributes		.gitattributes
.gitignore		.gitignore
.npmignore		.npmignore
.npmrc		.npmrc
.releaserc.json		.releaserc.json
CHANGELOG.md		CHANGELOG.md
Dockerfile		Dockerfile
LICENSE		LICENSE
README.md		README.md
SECURITY.md		SECURITY.md
biome.json		biome.json
index.ts		index.ts
llms-full.txt		llms-full.txt
llms.txt		llms.txt
package.json		package.json
pnpm-lock.yaml		pnpm-lock.yaml
pnpm-workspace.yaml		pnpm-workspace.yaml
server.json		server.json
smithery.yaml		smithery.yaml
tsconfig.json		tsconfig.json
vitest.config.ts		vitest.config.ts

Uh oh!

Folders and files

Latest commit

History

Repository files navigation

NPM Sentinel MCP

Features

Security & OWASP LLM01 Compliance

Caching and Invalidation

Example Usage (JSON-RPC)

Installation

Migration to HTTP Streamable

Install in VS Code

Smithery.ai Deployment (HTTP Streamable)

Configuration

HTTP Deployment (Smithery/Docker)

Docker

Build

Usage

Usage with Claude Desktop

NPX

API

Resources

Server Resources

Tools

npmVersions

npmLatest

npmDeps

npmTypes

npmSize

npmVulnerabilities

npmTrends

npmCompare

npmMaintainers

npmScore

npmPackageReadme

npmSearch

npmLicenseCompatibility

npmRepoStats

npmDeprecated

npmChangelogAnalysis

npmAlternatives

npmQuality

npmMaintenance

Build

License

About

Topics

Resources

Security policy

Stars

Watchers

Forks

Releases

Sponsor this project

Packages

Used by

Contributors

Languages