Skip to main content
Glama

NPM Sentinel MCP

Github Workflow npm version npm-month npm-total Docker Hub Ask DeepWiki Donate

A powerful Model Context Protocol (MCP v2) server built on @modelcontextprotocol/server and @modelcontextprotocol/core (v2) that revolutionizes NPM package analysis through AI. Built to integrate seamlessly with Claude, Anthropic AI, and any MCP v2 compatible client, it provides real-time intelligence on package security, dependencies, and performance.

This server features Modular ESM Architecture (src/), Dual Output Protocol Returns (content + structuredContent), Zod Output Schemas (outputSchema), Embedded SVG Data URI Icons, and Real-Time Context Logging.

Key Features

  • MCP v2 Native Protocol: Fully upgraded to MCP v2 with outputSchema Zod validation, dual structuredContent returning, and diagnostic context logging (ctx.mcpReq.log).

  • Self-Contained Vector Icons: Pre-configured SVG Data URIs (data:image/svg+xml) embedded across all 19 tools, resources, and prompts for enhanced client UI presentation.

  • Advanced Security Scanning: Recursive dependency checks powered by Google's deps.dev and OSV.dev, ecosystem awareness, and accurate version resolution.

  • Smart Alternatives Filtering (npmAlternatives): Intelligent search based on functional domain keywords with strict ecosystem plugin/extension filtering (e.g., excludes express-rate-limit when searching for alternatives to express).

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

  • Dependency & Transitive Mapping: Complete dependency tree analysis mapping through deps.dev.

  • Package Quality & Maintenance Metrics: Real-time scoring using OpenSSF Scorecard, GitHub repository metrics, and npms.io.

  • Download Trends & Performance: Real-time download statistics and bundle size analysis.

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

  • Efficient Caching System: Automated cache invalidation on workspace lockfile changes (pnpm-lock.yaml, package-lock.json, yarn.lock) with manual bypass (ignoreCache: true).

Related MCP server: NPM Helper MCP

Security & OWASP LLM01 Compliance

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

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

  2. Metadata Signaling (_meta): Responses include _meta.untrustedExternalContent = true and _meta.sources arrays for programmatic client-side detection and policy enforcement.

  3. Tool & Prompt Safety Warnings: Tool descriptions and prompt definitions explicitly instruct LLM agents to treat documentation as passive data and ignore embedded execution commands.

  4. 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).

  5. Prototype Pollution Protection: Enforces Object.hasOwn() checks on dictionary lookups (blocking reserved properties like constructor and __proto__).

To ensure data accuracy while maintaining high performance:

  • Automatic Invalidation: The cache is automatically invalidated whenever pnpm-lock.yaml, package-lock.json, or yarn.lock changes in your workspace.

  • Force Refresh: All tools accept an optional ignoreCache: true parameter to bypass the cache and force a fresh lookup from the NPM registry.

Example Usage (JSON-RPC)

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

Installation & Transports

Dual-Era MCP Architecture (v1 2025-11-25 + v2 2026-07-28)

This MCP server features native Dual-Era Protocol Compatibility, seamlessly serving both modern MCP v2 clients (2026-07-28) and legacy MCP v1 clients (2025-11-25) out of the box across both STDIO and Streamable HTTP transports:

  • STDIO Mode (npx @nekzus/mcp-server): Powered by serveStdio({ legacy: "serve" }). Handles modern server/discover probes sessionlessly and conjoins seamlessly with legacy initialize handshakes for local execution (Claude Desktop, Cursor, Docker).

  • Streamable HTTP / SSE Mode (@nekzus/mcp-server/http): Powered by createMcpHandler({ legacy: "stateless" }). Designed for serverless and web-standard runtimes (Cloudflare Workers, Hono, Express, Vercel API Routes).

Example: Mounting HTTP Handler (Cloudflare Workers / Hono / Express)

import { createMcpHttpHandler } from '@nekzus/mcp-server/http';

const handleRequest = createMcpHttpHandler();

export default {
  async fetch(request, env, ctx) {
    return handleRequest(request);
  }
};

Development Commands:

# Install dependencies
pnpm install

# Compile TypeScript to dist/
pnpm run build

# Start STDIO server (Dual-Era)
pnpm run start

# Development server
pnpm run dev

# Run full unit and integration test suite (238 tests)
pnpm test -- --run

# Run full E2E tarball verification
node __tests__/full-e2e-pack-validation.js

Install in VS Code / Cursor

Add this to your VS Code / Cursor MCP configuration:

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

Install in Claude Desktop

Add this to your claude_desktop_config.json:

{
  "mcpServers": {
    "npm-sentinel": {
      "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: ~/.config/Claude/claude_desktop_config.json

Docker Usage

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

# Run with local volume mount
docker run -i --rm -w /projects -v ${PWD}:/projects nekzus/npm-sentinel-mcp node dist/index.js

Web Standard Streamable HTTP & Cloudflare Workers Integration

The package exports createMcpHttpHandler and WebStandardStreamableHTTPServerTransport for serverless platforms (Cloudflare Workers, Hono, Vercel, Express, Fastify, Next.js API routes) requiring official Web Standard Streamable HTTP transport under MCP v2:

import { createMcpHttpHandler } from '@nekzus/mcp-server/http';

const handleMcpRequest = createMcpHttpHandler();

export default {
  async fetch(request: Request): Promise<Response> {
    return handleMcpRequest(request);
  },
};

100% MCP v2 Compliance: Powered by WebStandardStreamableHTTPServerTransport, this handler natively activates all 3 MCP primitives (Tools, Resources, and Prompts) with peak performance, SSE streaming support, and full Web Standard Request $\rightarrow$ Response compatibility.

Configuration

The server supports the following configuration parameters:

Environment Variable

Config Object Property

Default

Description

NPM_REGISTRY_URL

config.NPM_REGISTRY_URL

https://registry.npmjs.org

URL of the NPM registry to use for all requests


MCP Server Capabilities (v2 API)

All tool responses conform to the MCP v2 dual output format, providing both human-readable text in content and parsed JSON objects in structuredContent:

{
  "content": [
    {
      "type": "text",
      "text": "{\n  \"queryPackages\": [\"express\"],\n  \"results\": [...]\n}"
    }
  ],
  "structuredContent": {
    "queryPackages": ["express"],
    "results": [...]
  }
}

Server Resources

Accessible via MCP readResource requests:

  • doc://server/readme

    • Description: Main documentation file for NPM Sentinel MCP server.

    • MIME Type: text/markdown

    • Icon: Embedded Document SVG Data URI.

  • doc://mcp/specification

    • Description: Complete Model Context Protocol specification file (llms-full.txt).

    • MIME Type: text/plain

    • Icon: Embedded Document SVG Data URI.

Server Prompts

Accessible via MCP getPrompt requests:

  • analyze-package

    • Description: Generates a comprehensive prompt template for AI analysis of an NPM package including security, performance, dependencies, and health metrics.

    • Arguments: package (string, required)

    • Icon: Embedded Security SVG Data URI.


Tools Catalog (19 Tools)

All 19 tools define inputSchema, outputSchema, annotations (title, readOnlyHint), and icons:

1. npmLatest

  • Get latest version information, release dates, SRI integrity hashes, and dist-tags.

  • Input: packages (string[]), ignoreCache (boolean, optional)

2. npmVersions

  • Get full version history with release dates and deprecation statuses.

  • Input: packages (string[]), ignoreCache (boolean, optional)

3. npmDeps

  • Complete dependency tree analysis including direct dependencies and full transitive graph mapping via deps.dev.

  • Input: packages (string[]), ignoreCache (boolean, optional)

4. npmTypes

  • Verify TypeScript support (native index.d.ts declaration files vs @types/* DefinitelyTyped packages).

  • Input: packages (string[]), ignoreCache (boolean, optional)

5. npmSize

  • Package bundle size, minified size, and gzip impact analysis.

  • Input: packages (string[]), ignoreCache (boolean, optional)

6. npmVulnerabilities

  • Instant transitive vulnerability scanning powered by Google's deps.dev and OSV.dev advisories.

  • Input: packages (string[]), ignoreCache (boolean, optional)

7. npmTrends

  • Historical download statistics over customizable time ranges (last-week, last-month, last-year).

  • Input: packages (string[]), period ("last-week" | "last-month" | "last-year"), ignoreCache (boolean, optional)

8. npmCompare

  • Side-by-side metric comparison across multiple packages.

  • Input: packages (string[]), ignoreCache (boolean, optional)

9. npmMaintainers

  • List of package maintainers, public emails, and publishing activity.

  • Input: packages (string[]), ignoreCache (boolean, optional)

10. npmScore

  • Consolidated score combining quality, popularity, maintenance, and OpenSSF Scorecard.

  • Input: packages (string[]), ignoreCache (boolean, optional)

11. npmPackageReadme

  • Retrieve full formatted raw README markdown content from NPM registry / CDN.

  • Input: packages (string[]), ignoreCache (boolean, optional)

12. npmSearch

  • Search NPM registry packages by query with rich metadata (scores, publisher, keywords).

  • Input: query (string), limit (number, optional)

13. npmLicenseCompatibility

  • Analyze license compatibility across multiple packages (MIT, Apache-2.0, GPL, etc.).

  • Input: packages (string[]), ignoreCache (boolean, optional)

14. npmRepoStats

  • Repository statistics (GitHub stars, forks, open issues) combined with OpenSSF Scorecard checks.

  • Input: packages (string[]), ignoreCache (boolean, optional)

15. npmDeprecated

  • Detect deprecation status on package and recursive sub-dependencies.

  • Input: packages (string[]), ignoreCache (boolean, optional)

16. npmChangelogAnalysis

  • Extract release notes and GitHub release history.

  • Input: packages (string[]), ignoreCache (boolean, optional)

17. npmAlternatives

  • Smart functional alternative suggestions filtering out ecosystem plugins (e.g. excludes express-rate-limit for express).

  • Input: packages (string[]), ignoreCache (boolean, optional)

18. npmQuality

  • Package code quality score (0–1).

  • Input: packages (string[]), ignoreCache (boolean, optional)

19. npmMaintenance

  • Package maintenance activity score (0–1).

  • Input: packages (string[]), ignoreCache (boolean, optional)


License

This MCP server is licensed under the MIT License. See LICENSE for details.

MIT © nekzus

Available Tools

19 tools
npmAlternativesB
Read-only
Inspect

Find alternative packages with similar functionality

Inputs: packages (required), ignoreCache. Returns: message, results, summary

npmChangelogAnalysisC
Read-onlyIdempotent
Inspect

Analyze changelog and release history of packages

Inputs: packages (required), ignoreCache. Returns: message, results, summary

npmCompareB
Read-onlyIdempotent
Inspect

Compare multiple NPM packages based on various metrics

Inputs: packages (required), ignoreCache. Returns: message, results, queryPackages

npmDeprecatedC
Read-onlyIdempotent
Inspect

Check if packages are deprecated

Inputs: packages (required), ignoreCache. Returns: message, results, summary

npmDepsA
Read-onlyIdempotent
Inspect

Analyze dependencies and devDependencies of an NPM package

Inputs: packages (required), ignoreCache. Returns: message, results, summary

npmLatestB
Read-onlyIdempotent
Inspect

Get the latest version and changelog of an NPM package

Inputs: packages (required), ignoreCache. Returns: message, results, summary

npmLicenseCompatibilityB
Read-onlyIdempotent
Inspect

Check license compatibility between multiple packages

Inputs: packages (required), ignoreCache. Returns: compatibility, licenseDetails, packagesAnalyzed

npmMaintainersB
Read-onlyIdempotent
Inspect

Get maintainers information for NPM packages

Inputs: packages (required), ignoreCache. Returns: message, results, summary

npmMaintenanceB
Read-onlyIdempotent
Inspect

Analyze package maintenance metrics

Inputs: packages (required), ignoreCache. Returns: message, results, summary

npmPackageReadmeB
Read-onlyIdempotent
Inspect

Get the README content for NPM packages

Inputs: packages (required), ignoreCache. Returns: message, results, summary

npmQualityC
Read-onlyIdempotent
Inspect

Analyze package quality metrics

Inputs: packages (required), ignoreCache. Returns: message, results, summary

npmRepoStatsB
Read-onlyIdempotent
Inspect

Get repository statistics for NPM packages

Inputs: packages (required), ignoreCache. Returns: message, results, summary

npmScoreA
Read-onlyIdempotent
Inspect

Get consolidated package score based on quality, maintenance, and popularity metrics

Inputs: packages (required), ignoreCache. Returns: message, results, summary

npmSearchA
Read-only
Inspect

Search for NPM packages with optional limit

Inputs: query (required), limit, ignoreCache. Returns: query, message, results, limitUsed, +2 more

npmSizeA
Read-onlyIdempotent
Inspect

Get package size information including dependencies and bundle size

Inputs: packages (required), ignoreCache. Returns: message, results, summary

npmTrendsA
Read-onlyIdempotent
Inspect

Get download trends and popularity metrics for packages

Inputs: packages (required), period, ignoreCache. Returns: message, results, summary

npmTypesA
Read-onlyIdempotent
Inspect

Check TypeScript types availability and version for a package

Inputs: packages (required), ignoreCache. Returns: message, results, summary

npmVersionsA
Read-onlyIdempotent
Inspect

Get all available versions of an NPM package

Inputs: packages (required), ignoreCache. Returns: message, results, summary

npmVulnerabilitiesC
Read-only
Inspect

Check for known vulnerabilities in packages

Inputs: packages (required), ignoreCache. Returns: message, results, summary

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.5/5.0

    Scored across 19 tools

    Disambiguation5/5

    Each tool targets a distinct aspect of NPM packages (e.g., versions, dependencies, vulnerabilities, trends). There is no overlap; even similar-sounding tools like npmQuality, npmMaintenance, and npmScore have clearly separated purposes.

    Naming Consistency5/5

    All tools follow a consistent camelCase pattern starting with 'npm' followed by a descriptive noun or noun phrase (e.g., npmVersions, npmChangelogAnalysis). The naming is predictable and uniform.

    Tool Count4/5

    With 19 tools, the set is slightly above the typical well-scoped range of 3-15, but each tool serves a specific and valuable function within the domain of NPM package analysis, making the count reasonable.

    Completeness4/5

    The tools cover a wide range of NPM package metrics and information (versions, dependencies, vulnerabilities, trends, license, etc.), leaving few gaps (e.g., dependents or reverse dependencies missing). The coverage is comprehensive for the server's purpose.

    Maintenance

    ActivityMaintained
    ResponsivenessLimited data

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      D
      quality
      D
      maintenance
      A Model Context Protocol server that allows AI models to fetch detailed information about npm packages and discover popular packages in the npm ecosystem.
      1
      1
      ISC
    • A
      license
      Not graded
      quality
      D
      maintenance
      A Model Context Protocol server that provides tools for NPM package management, including dependency searching, updates, conflict resolution, and version management to help AI assistants safely upgrade project dependencies.
      51 npm
      8
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      A Model Context Protocol server that enables language models to interact with npm services securely, providing tools for package management, project initialization, script execution, and security auditing.
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      An MCP server for searching, inspecting, and evaluating NPM packages through health scoring and license risk assessments. It provides comprehensive package analysis including maintenance status, popularity trends, and security vulnerability reports to help users make informed dependency decisions.
      4
      MIT