NPM Sentinel MCP

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

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, Smithery.ai).

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 with Smithery CLI playground
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

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

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