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

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

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.

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

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

Add this to your VS Code / Cursor MCP configuration:

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

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

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

# 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

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.

The server supports the following configuration parameters:

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": [...]
  }
}

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.

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.

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

• Get latest version information, release dates, SRI integrity hashes, and dist-tags.
• Input: packages (string[]), ignoreCache (boolean, optional)

• Get full version history with release dates and deprecation statuses.
• Input: packages (string[]), ignoreCache (boolean, optional)

• Complete dependency tree analysis including direct dependencies and full transitive graph mapping via deps.dev.
• Input: packages (string[]), ignoreCache (boolean, optional)

• Verify TypeScript support (native index.d.ts declaration files vs @types/* DefinitelyTyped packages).
• Input: packages (string[]), ignoreCache (boolean, optional)

• Package bundle size, minified size, and gzip impact analysis.
• Input: packages (string[]), ignoreCache (boolean, optional)

• Instant transitive vulnerability scanning powered by Google's deps.dev and OSV.dev advisories.
• Input: packages (string[]), ignoreCache (boolean, optional)

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

• Side-by-side metric comparison across multiple packages.
• Input: packages (string[]), ignoreCache (boolean, optional)

• List of package maintainers, public emails, and publishing activity.
• Input: packages (string[]), ignoreCache (boolean, optional)

• Consolidated score combining quality, popularity, maintenance, and OpenSSF Scorecard.
• Input: packages (string[]), ignoreCache (boolean, optional)

• Retrieve full formatted raw README markdown content from NPM registry / CDN.
• Input: packages (string[]), ignoreCache (boolean, optional)

• Search NPM registry packages by query with rich metadata (scores, publisher, keywords).
• Input: query (string), limit (number, optional)

• Analyze license compatibility across multiple packages (MIT, Apache-2.0, GPL, etc.).
• Input: packages (string[]), ignoreCache (boolean, optional)

• Repository statistics (GitHub stars, forks, open issues) combined with OpenSSF Scorecard checks.
• Input: packages (string[]), ignoreCache (boolean, optional)

• Detect deprecation status on package and recursive sub-dependencies.
• Input: packages (string[]), ignoreCache (boolean, optional)

• Extract release notes and GitHub release history.
• Input: packages (string[]), ignoreCache (boolean, optional)

• Smart functional alternative suggestions filtering out ecosystem plugins (e.g. excludes express-rate-limit for express).
• Input: packages (string[]), ignoreCache (boolean, optional)

• Package code quality score (0–1).
• Input: packages (string[]), ignoreCache (boolean, optional)

• Package maintenance activity score (0–1).
• Input: packages (string[]), ignoreCache (boolean, optional)

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

MIT © nekzus