NPM Sentinel MCP

smithery badge 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, [email protected], 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).

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

STDIO & Streamable HTTP Transports

This MCP server supports both STDIO (standard input/output) and Streamable HTTP / SSE transports out of the box.

  • STDIO Mode: Default transport for local execution via npx or Docker.
  • Streamable HTTP / SSE Mode: Decoupled createServer({ config }) factory exported from dist/index.js and dist/src/server.js for mounting on Express, Hono, Cloudflare Workers, or Smithery.ai.

Development Commands:

# Install dependencies
pnpm install

# Compile TypeScript to dist/
pnpm run build

# Start STDIO server
pnpm run start

# Development server with Smithery CLI playground
pnpm run dev

# Run unit and integration test suite (212+ 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

Smithery.ai Deployment

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

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

Streamable HTTP (POST) & Cloudflare Workers Integration

The package exports a stateless HTTP handler handleStreamableHttpRequest designed for serverless platforms (Cloudflare Workers, Vercel, Express, Fastify, Next.js API routes) requiring Streamable HTTP POST transport under MCP v2:

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

export default {
  async fetch(request: Request): Promise<Response> {
    if (request.method !== 'POST') {
      return new Response('NPM Sentinel MCP v2 Streamable HTTP Server', { status: 200 });
    }

    try {
      const payload = await request.json();
      const mcpResponse = await handleStreamableHttpRequest(payload);

      return new Response(mcpResponse.body, {
        status: mcpResponse.status,
        headers: mcpResponse.headers,
      });
    } catch {
      return new Response(JSON.stringify({ error: 'Invalid JSON-RPC payload' }), { status: 400 });
    }
  },
};

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