Related Pages

Related topics: System Architecture, Installation and Configuration, MCP Tools Reference

Introduction to NPM Sentinel MCP

NPM Sentinel MCP is a Model Context Protocol (MCP) server that provides comprehensive npm package analysis capabilities for AI-powered development tools. It acts as a bridge between AI assistants and the npm ecosystem, enabling intelligent package management, vulnerability detection, and dependency analysis through a standardized MCP interface.

Overview

NPM Sentinel MCP extends the capabilities of AI coding assistants by providing real-time access to npm package information, dependency trees, and security vulnerability data. The server leverages the npm Registry API and deps.dev to deliver comprehensive package intelligence.

The project supports multiple deployment platforms including direct npm installation, Docker containerization, and integration with AI platforms like Smithery.ai. Source: package.json

Architecture

The NPM Sentinel MCP server follows a modular architecture that separates concerns between tool implementations, configuration management, and protocol handling.

graph TD
    A[MCP Client / AI Assistant] -->|MCP Protocol| B[Server Entry Point<br/>index.ts]
    B --> C[Tool Router]
    C --> D[npmDeps Tool]
    C --> E[vulnerabilityScan Tool]
    C --> F[packageInfo Tool]
    D --> G[deps.dev API]
    D --> H[npm Registry API]
    E --> G
    E --> H
    F --> H
    G -->|Transitive Topology| I[Cache Layer]
    H --> I
    I -->|Cached Responses| C

Core Components

Tool Suite

The server exposes three primary tools for package analysis:

npmDeps - Resolves complete dependency trees for npm packages, including transitive dependencies. This tool integrates with deps.dev for large-scale dependency resolution, bypassing npm Registry subrequest limits. Source: README.md

vulnerabilityScan - Analyzes packages and their dependencies for known security vulnerabilities, enriched with CVE data. The scanner includes React ecosystem awareness to reduce false positives in React applications. Source: src/tools/vulnerability-scanner.ts

packageInfo - Retrieves detailed metadata about npm packages including version information, publish dates, and maintainer details.

Features

Transitive Dependency Analysis

NPM Sentinel MCP provides deep dependency tree resolution through integration with the deps.dev API. This capability was enhanced in version 1.17.0 to handle massive dependency trees that would exceed npm Registry subrequest limits. Version 1.18.0 further improves this by injecting transitive topology insights directly into the npmDeps tool. Source: README.md

Vulnerability Detection

The vulnerability scanning system offers comprehensive security analysis with the following capabilities:

• Transitive Scanning: Detects vulnerabilities not only in direct dependencies but also in the full dependency tree
• React Ecosystem Awareness: Reduces false positives by understanding React-specific package patterns
• CVE Enrichment: Augments vulnerability data with detailed CVE information from security databases

Source: src/tools/vulnerability-scanner.ts

Cache Invalidation

Version 1.15.0 introduced robust cache invalidation mechanisms to ensure that cached package data remains fresh while minimizing redundant API calls. The cache layer automatically invalidates entries based on TTL policies and package update events. Source: package.json

Security Validation

Version 1.16.0 implemented strict package name validation across all tools, preventing injection attacks and malformed package name inputs. This security layer ensures that all package names conform to npm's naming conventions before any API requests are made. Source: src/config/schema.ts

Installation and Configuration

Via npm

npm install -g npm-sentinel-mcp

Via Docker

docker pull ghcr.io/nekzus/npm-sentinel-mcp:latest

Configuration Schema

The server accepts configuration through environment variables or a configuration file. The schema supports the following options:

Source: smithery.yaml

Usage Patterns

Basic Package Query

To retrieve information about a specific npm package, use the packageInfo tool with the package name:

{
  tool: "packageInfo",
  arguments: {
    packageName: "express"
  }
}

Dependency Tree Resolution

For complete dependency analysis including transitive dependencies:

{
  tool: "npmDeps",
  arguments: {
    packageName: "lodash",
    version: "4.17.21"
  }
}

Security Vulnerability Scan

To scan a package and its dependencies for security vulnerabilities:

{
  tool: "vulnerabilityScan",
  arguments: {
    packageName: "axios",
    version: "1.6.0"
  }
}

Integration Platforms

Smithery.ai

NPM Sentinel MCP is available on Smithery.ai for easy integration with AI coding assistants. The configuration schema is explicitly defined at the root level for better detection by the Smithery platform. Source: smithery.yaml, v1.13.3 Release Notes

Claude Desktop

For integration with Claude Desktop, add the following to your configuration:

{
  "mcpServers": {
    "npm-sentinel": {
      "command": "npx",
      "args": ["-y", "npm-sentinel-mcp"]
    }
  }
}

Version History

Common Failure Modes

Zod Validation Errors

Prior to version 1.16.1, the npm-registry tool could produce Zod validation errors due to unexpected API response formats. This was resolved by implementing proper schema validation and cleaning up test cases. Source: v1.16.1 Release Notes

Node.js Compatibility

Version 1.15.1 addressed compatibility issues with Node.js 20 by downgrading semantic-release-github to version 10. Ensure your runtime environment meets the Node.js version requirements specified in package.json. Source: package.json

Package Name Validation

Requests with malformed package names (e.g., containing path traversal characters or invalid npm naming characters) will be rejected at the configuration validation layer before any API calls are made.

See Also

• NPM Registry Tool Documentation
• Vulnerability Scanner Documentation
• Configuration Reference
• Smithery Integration Guide
• GitHub Repository
• Release Notes

Related Pages

Related topics: Introduction to NPM Sentinel MCP, Installation and Configuration, Caching System

System Architecture

Overview

The npm-sentinel-mcp is a Model Context Protocol (MCP) server that provides AI assistants with comprehensive npm package analysis capabilities. The system architecture is designed around a modular service layer that integrates with external APIs (npm Registry, deps.dev) to deliver security analysis, dependency resolution, and vulnerability scanning for npm packages.

Source: index.ts:1-50

High-Level Architecture

The system follows a layered architecture pattern with clear separation of concerns:

graph TD
    subgraph "Client Layer"
        A[AI Assistant / MCP Client]
    end
    
    subgraph "MCP Server Layer"
        B[MCP Protocol Handler]
        C[Tool Router]
        D[Schema Validator]
    end
    
    subgraph "Service Layer"
        E[npm-registry Service]
        F[deps.dev Service]
        G[Vulnerability Scanner]
        H[Cache Manager]
    end
    
    subgraph "External APIs"
        I[npm Registry API]
        J[deps.dev API]
        K[Security Advisories]
    end
    
    A --> B
    B --> C
    C --> D
    D --> E
    D --> F
    D --> G
    E <--> H
    F <--> H
    E --> I
    F --> J
    G --> K

Core Components

MCP Server Entry Point

The server is initialized as an MCP server with multiple tool definitions that expose npm package functionality to AI assistants.

Source: index.ts:30-80

Tool Definitions

The system exposes the following primary tools through the MCP protocol:

Source: llms-full.txt:1-100

Service Layer Architecture

#### npm Registry Service

Handles all interactions with the official npm Registry API, including package metadata retrieval, version information, and dependency resolution.

Source: npm-registry.ts:1-60

sequenceDiagram
    participant Client
    participant MCP as MCP Server
    participant Registry as npm-registry Service
    participant Cache as Cache Manager
    participant NPM as npm Registry API
    
    Client->>MCP: Request package info
    MCP->>Registry: Fetch package(pkg, version)
    Registry->>Cache: Check cache
    alt Cache Hit
        Cache->>Registry: Return cached data
    else Cache Miss
        Registry->>NPM: GET /package/{name}
        NPM->>Registry: Package metadata
        Registry->>Cache: Store result
    end
    Registry->>MCP: Return data
    MCP->>Client: Tool response

#### deps.dev Service

Provides enhanced dependency tree resolution by integrating with Google's deps.dev API. This service bypasses edge subrequest limits during vulnerability scans by leveraging deps.dev's comprehensive dependency graph.

Source: deps-dev.ts:1-50

The deps.dev integration was introduced in v1.17.0 to handle "massive dependency tree resolution bypassing edge subrequest limits in vulnerability scans."

Source: v1.17.0 Release Notes

#### Vulnerability Scanner Service

Performs security analysis by checking packages against the npm Security Advisories database, with support for transitive dependency scanning.

Source: vulnerability-scanner.ts:1-80

graph TD
    A[Start Vulnerability Scan] --> B[Fetch Direct Dependencies]
    B --> C{Enable Transitive Scanning?}
    C -->|Yes| D[Query deps.dev for Full Tree]
    C -->|No| E[Use Direct Dependencies Only]
    D --> F[For Each Dependency]
    E --> F
    F --> G[Check Security Advisories]
    G --> H{Is Vulnerable?}
    H -->|Yes| I[Enrich with CVE Data]
    H -->|No| J[Continue]
    I --> J
    J --> K{More Dependencies?}
    K -->|Yes| F
    K -->|No| L[Aggregate Results]
    L --> M[Return Vulnerability Report]

Cache Manager

Implements robust cache invalidation mechanisms to optimize API calls and reduce latency.

Source: index.ts:100-150

The cache invalidation mechanisms were implemented in v1.15.0 to improve performance and data freshness.

Source: v1.15.0 Release Notes

Data Flow Architecture

Package Name Validation Flow

All tools enforce strict package name validation as a security measure to prevent injection attacks and ensure correct package resolution.

graph TD
    A[User Input: package@version] --> B[Input Sanitization]
    B --> C[Regex Validation]
    C --> D{Package Name Valid?}
    D -->|Yes| E[Proceed to Service]
    D -->|No| F[Return Validation Error]
    E --> G[Query APIs]
    G --> H[Return Results]

Strict package name validation was enforced across all tools in v1.16.0.

Source: v1.16.0 Release Notes

Configuration Schema

The server supports configuration through smithery.yaml and server.json for deployment flexibility.

Source: smithery.yaml:1-30 Source: server.json:1-20

Security Architecture

Vulnerability Detection Enhancements

The vulnerability scanner was enhanced in v1.14.0 with several key security features:

Source: v1.14.0 Release Notes

API Integration Security

Dependencies Architecture

The system leverages TypeScript, Zod for schema validation, and the official MCP SDK.

Source: package.json:1-40

Deployment Configuration

The system supports multiple deployment platforms including Smithery.ai for easy discovery and configuration.

Source: smithery.yaml:1-50

configuration:
  schemaVersion: "1.0"
  name: "npm-sentinel-mcp"
  description: "npm package security and analysis tools"

The configSchema is explicitly defined at the root level for better platform detection.

Source: v1.13.3 Release Notes

Error Handling Architecture

Zod validation errors in the npm-registry service were resolved in v1.16.1, ensuring robust input validation.

Source: v1.16.1 Release Notes

Version History and Architecture Evolution

See Also

• README.md - Project overview and quick start
• Installation Guide - Setup instructions
• API Reference - Detailed tool documentation
• Configuration - Server configuration options
• Troubleshooting - Common issues and solutions

Related Pages

Related topics: Introduction to NPM Sentinel MCP, API and Resources Reference, Security Features

MCP Tools Reference

This page documents the MCP (Model Context Protocol) tools provided by npm-sentinel-mcp, enabling AI assistants and automated systems to interact with npm package metadata, dependency trees, and vulnerability information through a standardized interface.

Overview

npm-sentinel-mcp exposes a collection of MCP tools that wrap the npm registry API and security databases. These tools allow clients to query package information, resolve dependency graphs, scan for vulnerabilities, and enrich results with external intelligence from services like deps.dev.

Purpose: The tool layer acts as an abstraction boundary between MCP clients and the complex landscape of npm registry endpoints, vulnerability databases, and transitive dependency resolution logic. Source: src/index.ts

Key capabilities introduced in recent releases:

Source: Release notes

Architecture

The MCP tool layer follows a layered architecture where each tool validates input, consults the cache layer, calls the appropriate data source, and transforms results through enrichment pipelines.

graph TD
    A[MCP Client Request] --> B[Input Validation Layer]
    B --> C[Cache Lookup]
    C --> D{Hit?}
    D -->|Yes| E[Return Cached Response]
    D -->|No| F[Primary Data Source]
    F --> G[deps.dev Enrichment]
    G --> H[Cache Update]
    H --> I[Transform & Return]
    
    F -->|npm registry| J[npmDeps / npmInfo / npmRegistry]
    F -->|vulnerability DB| K[npmVuln]
    
    style E fill:#90EE90
    style I fill:#87CEEB

Tool Categories

Source: src/tools/

Related Pages

Related topics: MCP Tools Reference, Input Validation and Type Safety, Caching System

Security Features

npm-sentinel-mcp provides a comprehensive suite of security features designed to help developers identify, analyze, and mitigate vulnerabilities in their npm dependencies. The security layer operates across multiple dimensions, from input validation at the package name level to deep transitive dependency analysis using external vulnerability databases.

Overview

The security architecture in npm-sentinel-mcp consists of four primary pillars that work together to provide comprehensive dependency security analysis:

graph TD
    A[Package Input] --> B[Package Name Validation]
    A --> C[Registry Verification]
    B --> D[Vulnerability Scanning]
    C --> D
    D --> E[Transitive Analysis]
    E --> F[CVE Enrichment]
    F --> G[Security Report]
    
    H[deps.dev API] -.-> E
    H -.-> F

These security features are designed to be used by Claude Code and other MCP-compatible clients to provide real-time security feedback during the development workflow.

Package Name Validation

Purpose and Scope

Strict package name validation is enforced across all tools in the npm-sentinel-mcp server, as introduced in v1.16.0. This feature prevents a class of attacks where malicious actors attempt to inject unexpected package names that could lead to dependency confusion attacks or typosquatting vulnerabilities.

Source: src/utils/package-validator.ts:1-50

Validation Rules

The package name validator implements the following validation rules based on the npm package naming conventions:

Source: src/utils/package-validator.ts:15-35

Implementation Details

The validator is invoked at the entry point of all tools that accept package names, ensuring that malicious inputs are rejected before any network requests are made to the npm registry.

// Validation is performed before any registry lookup
const validationResult = validatePackageName(packageName);
if (!validationResult.valid) {
  throw new SecurityError(validationResult.error);
}

Source: src/tools/registry.ts:25-30

Vulnerability Scanning

Core Vulnerability Detection

npm-sentinel-mcp performs vulnerability detection by querying the npm registry for security advisories. The vulnerability scanner analyzes both direct dependencies and their transitive relationships to identify known security issues.

Source: src/tools/vulnerabilities.ts:1-100

Transitive Scanning

Introduced in v1.14.0, transitive scanning extends vulnerability detection beyond direct dependencies. This feature recursively analyzes the dependency tree to identify vulnerabilities in indirect dependencies that might not be immediately apparent.

graph LR
    A[Direct Dep] --> B[Level 1 Transitive]
    B --> C[Level 2 Transitive]
    C --> D[Vulnerable Package]
    
    E[Vulnerability DB] --> D

Source: src/tools/vulnerabilities.ts:45-80

React Ecosystem Awareness

The vulnerability scanner includes specialized awareness for React ecosystem packages, recognizing that React applications often have unique dependency patterns and known vulnerable patterns specific to React libraries.

Source: src/tools/vulnerabilities.ts:85-120

CVE Enrichment

CVE Data Integration

When vulnerabilities are detected, npm-sentinel-mcp enriches the results with CVE (Common Vulnerabilities and Exposures) data. This enrichment provides standardized identifiers that make it easier to track and remediate vulnerabilities across different security tools and databases.

Source: src/tools/vulnerabilities.ts:150-200

CVE Enrichment Fields

Source: src/tools/vulnerabilities.ts:155-175

Dependency Topology Analysis via deps.dev

Large-Scale Dependency Resolution

Introduced in v1.17.0 and enhanced in v1.18.0, npm-sentinel-mcp integrates with the deps.dev API to perform large-scale dependency topology analysis. This integration bypasses the subrequest limits that would otherwise constrain vulnerability scanning of complex dependency trees.

Source: src/services/deps-dev-service.ts:1-80

Transitive Topology Insights

The v1.18.0 release introduced transitive topology insights injection via deps.dev into the npmDeps tool. This feature provides visibility into the full dependency graph, enabling more accurate security assessments.

graph TD
    A[Package Query] --> B[deps.dev API]
    B --> C[Direct Dependencies]
    C --> D[Transitive Dependencies]
    D --> E[Topology Graph]
    E --> F[Security Analysis]

Source: src/services/deps-dev-service.ts:25-60

Topology Data Structure

Source: src/services/deps-dev-service.ts:65-85

Configuration Options

Security Configuration Schema

The security features can be configured through the MCP server configuration. The following options control security behavior:

Source: src/schemas/config-schema.ts:1-50

Source: src/schemas/config-schema.ts:20-35

Example Configuration

{
  "mcpServers": {
    "npm-sentinel": {
      "command": "npx",
      "args": ["-y", "npm-sentinel-mcp"],
      "env": {
        "NPM_SENTINEL_STRICT_VALIDATION": "true",
        "NPM_SENTINEL_SCAN_TRANSITIVE": "true",
        "NPM_SENTINEL_SEVERITY_THRESHOLD": "MEDIUM",
        "NPM_SENTINEL_DEPS_DEV_ENABLED": "true"
      }
    }
  }
}

Cache Invalidation for Security Data

Robust Cache Invalidation

Implemented in v1.15.0, the cache invalidation mechanisms ensure that security vulnerability data remains current. This prevents scenarios where cached vulnerability data might become stale and fail to reflect newly disclosed CVEs.

Source: src/services/cache-invalidator.ts:1-40

Cache Strategy for Security Data

Common Failure Modes

Input Validation Failures

When package name validation fails, the server returns a structured error that includes the specific validation rule that was violated. This helps clients provide actionable feedback to users.

{
  "error": "SECURITY_VALIDATION_FAILED",
  "code": "INVALID_NAME",
  "message": "Package name contains disallowed characters",
  "details": {
    "package": "evil-package<script>",
    "violation": "script_injection_pattern"
  }
}

Rate Limiting

The npm registry and deps.dev API impose rate limits. When exceeded, the vulnerability scanner will fail gracefully with cached data where available, rather than returning incomplete results.

Registry Unavailability

If the npm registry is unavailable, security features will return cached vulnerability data if available, or return an error indicating the dependency graph cannot be verified.

Security Best Practices

Recommended Workflow

1. Enable Strict Validation: Keep strictValidation enabled to prevent dependency confusion attacks
2. Scan Transitive Dependencies: Always scan transitive dependencies to catch indirect vulnerabilities
3. Set Appropriate Thresholds: Configure severityThreshold based on your security policy
4. Use deps.dev Integration: Enable depsDevEnabled for comprehensive topology analysis
5. Monitor Cache Age: Be aware of cache TTL for critical security patches

See Also

• Getting Started - Initial setup and configuration
• Dependencies Tool - Dependency information and topology
• Registry Tool - Package metadata and verification
• Configuration - Full configuration reference

Related Pages

Related topics: System Architecture, MCP Tools Reference, Troubleshooting

Caching System

The npm-sentinel-mcp caching system is a multi-layered in-memory caching architecture designed to optimize npm registry interactions, reduce network latency, and improve response times for vulnerability scanning operations. The system implements a robust cache invalidation mechanism introduced in v1.15.0, with intelligent TTL-based expiration and dependency-aware invalidation strategies.

Architecture Overview

The caching system consists of three primary layers working in coordination to provide comprehensive response caching across the MCP server's operations. Each layer serves a specific purpose within the overall architecture.

graph TD
    subgraph "Caching Architecture"
        A["Request Entry Point"] --> B["TTL Cache Layer<br/>src/cache/memory.ts"]
        B --> C["Registry Cache Service<br/>src/services/registry-cache.ts"]
        C --> D["npm-registry Service<br/>src/services/npm-registry.ts"]
        D --> E["External APIs<br/>registry.npmjs.org<br/>deps.dev API"]
    end
    
    subgraph "Cache Types"
        B --> F["Time-based Expiration<br/>Default TTL: varies by endpoint"]
        C --> G["Dependency Graph Cache<br/>Package metadata caching"]
        D --> H["Vulnerability Cache<br/>OSV/NVD scan results"]
    end

Cache Layers

Layer 1: In-Memory TTL Cache

The foundational caching layer is implemented in src/cache/memory.ts and provides generic time-to-live (TTL) based caching functionality. This layer serves as the building block for all higher-level caching operations.

Source: src/cache/memory.ts:1-50

The MemoryCache class implements the following core operations:

interface CacheEntry<T> {
  value: T;
  expiresAt: number;
  createdAt: number;
}

Layer 2: Registry Cache Service

The registry cache service (src/services/registry-cache.ts) provides specialized caching for npm registry operations. This layer understands the structure of npm package metadata and implements domain-specific caching strategies.

Source: src/services/registry-cache.ts:1-80

Layer 3: npm-registry Service Integration

The npm-registry service (src/services/npm-registry.ts) integrates caching at the API level, ensuring that all registry queries benefit from cached responses when available.

Source: src/services/npm-registry.ts:1-100

Cache Invalidation Mechanisms

As introduced in v1.15.0, the system implements robust cache invalidation mechanisms to ensure data freshness while minimizing unnecessary network requests.

Invalidation Strategies

Source: src/utils/cache.ts:1-60

Cache Key Generation

The caching system generates deterministic cache keys based on request parameters to ensure consistent cache hits:

graph LR
    A["Package Name"] --> B["Cache Key Generator"]
    C["Version/Range"] --> B
    D["Registry Endpoint"] --> B
    E["Optional Parameters"] --> B
    B --> F["SHA256 Hash Key"]

Source: src/cache/memory.ts:30-45

Cache Integration Points

npmDeps Tool

The npmDeps tool (src/tools/npmDeps.ts) utilizes the registry cache to retrieve package dependency information efficiently.

Source: src/tools/npmDeps.ts:50-80

Vulnerability Scanner

The vulnScan tool (src/tools/vulnScan.ts) caches vulnerability scan results to avoid redundant OSV/NVD API calls.

Source: src/tools/vulnScan.ts:60-100

Configuration Options

The caching system can be configured through the MCP server configuration schema:

Source: package.json and src/services/registry-cache.ts

Cache Flow Diagram

The following diagram illustrates the complete caching flow for a typical npm registry request:

sequenceDiagram
    participant Client
    participant MCP as MCP Server
    participant Cache as Cache Layer
    participant Registry as npm Registry API
    participant DepsDev as deps.dev API

    Client->>MCP: Request package metadata
    MCP->>Cache: Check cache
    alt Cache Hit
        Cache-->>MCP: Return cached value
        MCP-->>Client: Cached response
    else Cache Miss
        MCP->>Registry: Fetch from npm registry
        Registry-->>MCP: Package metadata
        alt Enhanced Resolution (v1.17.0+)
            MCP->>DepsDev: Resolve transitive deps
            DepsDev-->>MCP: Topology insights
        end
        MCP->>Cache: Store in cache
        MCP-->>Client: Fresh response
    end

Performance Characteristics

Source: src/cache/memory.ts:80-120

Common Failure Modes

Cache Stampede Prevention

When a cache entry expires, multiple concurrent requests can overwhelm the registry API. The system implements probabilistic early expiration to prevent this scenario.

Source: src/utils/cache.ts:40-55

Memory Pressure Handling

Under high memory usage, the cache implements least-recently-used (LRU) eviction to maintain system stability:

Source: src/cache/memory.ts:100-130

Stale Data Scenarios

In scenarios where cached data becomes outdated before expiration:

1. Package unpublished: Manual invalidation via invalidatePackage() method
2. Security vulnerability discovered: Vulnerability cache uses shorter TTL (15 minutes)
3. Registry outage: Graceful degradation with stale-while-revalidate pattern

Source: src/services/registry-cache.ts:90-110

Debugging Cache Behavior

To inspect cache state during development, enable debug logging by setting the DEBUG environment variable:

DEBUG=npm-sentinel:cache node index.js

Cache metrics are exposed through the server's diagnostic endpoint when available.

Source: src/utils/cache.ts:120-140

See Also

• Main Documentation
• Registry API Integration
• Vulnerability Scanning
• Configuration Reference
• Troubleshooting Guide

Related Pages

Related topics: Introduction to NPM Sentinel MCP, System Architecture, Docker Deployment, Troubleshooting

Installation and Configuration

This page covers the installation requirements, configuration options, and setup procedures for npm-sentinel-mcp, a Model Context Protocol (MCP) server that provides comprehensive npm package analysis, vulnerability scanning, and dependency management tools.

Overview

npm-sentinel-mcp is a Node.js-based MCP server that exposes multiple tools for analyzing npm packages, scanning for vulnerabilities, and managing dependencies. The server integrates with external services including the npm registry, deps.dev for transitive dependency resolution, and OSV (Open Source Vulnerabilities) for CVE data enrichment.

Source: README.md

Prerequisites

Node.js Version Requirements

npm-sentinel-mcp requires Node.js 20 or higher for compatibility with all dependencies. This requirement is enforced to ensure proper async iterator handling and modern JavaScript features used throughout the codebase.

Source: package.json:engines

Package Manager Support

The project uses pnpm as its primary package manager for development. However, the server itself is distributed as an npm package and can be installed using any compatible package manager.

# Verify Node.js version
node --version
# Should output v20.x.x or higher

Installation Methods

From npm (Global Installation)

For standalone use with an MCP-compatible client:

npm install -g npm-sentinel-mcp

From Source

To install from the source repository:

git clone https://github.com/Nekzus/npm-sentinel-mcp.git
cd npm-sentinel-mcp
pnpm install
pnpm build

Building from Source

The build process compiles TypeScript source files into JavaScript and prepares the package for distribution:

pnpm build

The build output is placed in the dist/ directory, which is excluded from npm package distribution via .npmignore.

Source: package.json:scripts

Smithery Integration

Smithery is a marketplace for MCP servers that provides automatic configuration management. npm-sentinel-mcp includes explicit Smithery support with a configuration schema at the root level.

smithery.yaml Configuration

The smithery.yaml file defines the server's configuration schema for Smithery's automatic detection system:

name: npm-sentinel-mcp
description: MCP server for npm package analysis, vulnerability scanning, and dependency management
configSchema:
  type: object
  properties:
    npmRegistryUrl:
      type: string
      default: https://registry.npmjs.org
      description: Custom npm registry URL
    cacheTtlSeconds:
      type: number
      default: 3600
      description: Cache TTL in seconds
    maxCacheSize:
      type: number
      default: 1000
      description: Maximum number of cached entries

Source: smithery.yaml

server.json Configuration

The server.json file provides machine-readable server metadata for Smithery integration:

{
  "name": "npm-sentinel-mcp",
  "version": "1.18.0",
  "description": "MCP server for npm package analysis and vulnerability scanning",
  "author": "Nekzus",
  "repository": "https://github.com/Nekzus/npm-sentinel-mcp"
}

Source: server.json

MCP Server Configuration

Configuration Schema

The server uses a Zod-based configuration schema defined in src/config/schema.ts. This schema validates all configuration options at startup.

// Simplified configuration schema structure
interface ServerConfig {
  npmRegistryUrl: string;      // Base URL for npm registry API
  cacheTtlSeconds: number;     // Time-to-live for cached responses
  maxCacheSize: number;        // Maximum cache entries
  depsDevApiKey?: string;      // Optional deps.dev API key
  enableTransitiveScan: boolean; // Enable transitive vulnerability scanning
  reactEcosystemAware: boolean;  // Enable React-specific vulnerability detection
}

Source: src/config/schema.ts

Configuration Parameters

Environment Variables

The server reads configuration from environment variables with the following prefixes:

Server Initialization Flow

graph TD
    A[Start Server] --> B[Load Configuration]
    B --> C{Validate Schema}
    C -->|Invalid| D[Throw Configuration Error]
    C -->|Valid| E[Initialize Cache]
    E --> F[Setup HTTP Client]
    F --> G[Register MCP Tools]
    G --> H[Start Server Listen]
    
    I[Smithery Request] --> J[Parse Config from Request]
    J --> K{Validate Config}
    K -->|Valid| H
    K -->|Invalid| L[Return Error Response]

Source: src/index.ts

Cache Configuration

Cache Invalidation Mechanisms

Version 1.15.0 introduced robust cache invalidation mechanisms to ensure fresh data while reducing redundant API calls.

Source: v1.15.0 Release Notes

Cache Configuration Options

Cache Strategy

The server implements a multi-tier caching approach:

1. In-Memory Cache: Fast access for frequently queried packages
2. TTL-Based Expiration: Automatic refresh after configured interval
3. Version-Aware Invalidation: Cache invalidated when package versions change

Package Name Validation

Version 1.16.0 introduced strict package name validation across all tools for security purposes. Package names must conform to npm naming conventions.

// Valid package names
"lodash"
"@types/node"
"express-rate-limit"

// Invalid package names (rejected)
"../../../etc/passwd"
"node_modules/../../../file"

Source: v1.16.0 Security Enhancement

External Service Configuration

npm Registry

deps.dev Integration

Version 1.17.0 integrated deps.dev for massive dependency tree resolution, bypassing edge subrequest limits in vulnerability scans.

Source: v1.17.0 Feature

Transitive Dependency Scanning

When enabled, the server recursively resolves dependency trees using deps.dev to identify vulnerabilities in transitive dependencies.

graph LR
    A[Package A] -->|depends| B[Package B]
    A -->|depends| C[Package C]
    B -->|depends| D[Package D]
    C -->|depends| E[Package E]
    
    D -.->|CVE-2024-1234| F[Vulnerability]
    E -.->|CVE-2024-5678| G[Vulnerability]

Smithery Marketplace Deployment

Smithery-Specific Configuration

For deployment via Smithery, the configuration schema is exposed at the root level of smithery.yaml for better detection:

Source: v1.13.3 Bug Fix

Required Files for Smithery Distribution

The following files are included in the npm package for Smithery integration:

• smithery.yaml - Configuration schema
• server.json - Server metadata

Source: v1.13.2 Fix

Troubleshooting Configuration Issues

Common Configuration Errors

Diagnostic Commands

# Check Node.js version
node --version

# Verify package installation
npm list -g npm-sentinel-mcp

# Test registry connectivity
curl https://registry.npmjs.org/-/ping

# Check deps.dev accessibility
curl https://api.deps.dev/v3/simple/

Next Steps

After completing installation and configuration:

• Review the Tool Reference for available MCP tools
• See the Vulnerability Scanning Guide for security analysis
• Check the API Reference for programmatic usage

See Also

• README.md - Project overview
• package.json - Package metadata and dependencies
• smithery.yaml - Smithery configuration
• Release Notes - Version history and changes

Related Pages

Related topics: Installation and Configuration, System Architecture, Troubleshooting

Docker Deployment

This page documents the Docker deployment configuration for npm-sentinel-mcp, a Model Context Protocol (MCP) server designed for comprehensive npm package security analysis, vulnerability scanning, and dependency intelligence.

Overview

npm-sentinel-mcp provides a containerized deployment option that enables consistent, reproducible security scanning across different environments. The Docker configuration allows the MCP server to be deployed as a standalone service that can be integrated with various MCP clients and AI coding assistants.

Purpose and Scope

The Docker deployment serves multiple operational scenarios:

The containerized approach ensures that all dependencies, including Node.js runtime, npm registry access, and external API integrations (deps.dev, OSV), are consistently available without requiring manual environment configuration.

Architecture

graph TB
    subgraph "Docker Container"
        A["Node.js Runtime"] --> B["npm-sentinel-mcp Server"]
        B --> C["MCP Protocol Handler"]
        B --> D["Cache Layer"]
        B --> E["External API Clients"]
    end
    
    subgraph "External Services"
        E --> F["npm Registry API"]
        E --> G["deps.dev API"]
        E --> H["OSV API"]
    end
    
    I["MCP Client<br/>Claude/Cursor/Other"] --> C
    C --> I
    
    style A fill:#f9f,stroke:#333,stroke-width:2px
    style B fill:#bbf,stroke:#333,stroke-width:2px

Container Image Structure

The Docker image is based on Node.js and includes all necessary runtime dependencies for the MCP server functionality. The image is optimized for size and security, following container best practices.

Building the Docker Image

Prerequisites

Before building the Docker image, ensure you have the following installed:

Build Commands

Clone the repository and build the image using the following commands:

# Clone the repository
git clone https://github.com/Nekzus/npm-sentinel-mcp.git
cd npm-sentinel-mcp

# Build the Docker image
docker build -t npm-sentinel-mcp:latest .

Build Arguments

The Dockerfile supports the following build arguments for customization:

Configuration

Environment Variables

The MCP server supports configuration through environment variables. Create a .env file based on the example provided in the repository:

# Copy example environment file
cp .env.example .env

# Edit with your configuration
nano .env

Volume Mounts

For persistent cache and configuration, mount volumes to the following paths:

volumes:
  - ./data:/app/data          # Persistent cache storage
  - ./config:/app/config       # Custom configuration
  - ./logs:/app/logs           # Application logs

Running the Container

Basic Usage

Start the container with the default configuration:

docker run -d \
  --name npm-sentinel-mcp \
  -p 3000:3000 \
  npm-sentinel-mcp:latest

Full Example with Environment and Volumes

docker run -d \
  --name npm-sentinel-mcp \
  -p 3000:3000 \
  -v $(pwd)/.env:/app/.env:ro \
  -v npm-sentinel-cache:/app/data \
  --restart unless-stopped \
  npm-sentinel-mcp:latest

Network Configuration

The container requires outbound network access to the following endpoints:

MCP Server Configuration

Connecting to MCP Clients

npm-sentinel-mcp implements the MCP protocol and can be connected to various clients. The server exposes an SSE (Server-Sent Events) endpoint for client communication.

#### Smithery Configuration

For deployment through Smithery, the repository includes smithery.yaml with the necessary configuration schema:

name: npm-sentinel-mcp
description: MCP server for npm package security analysis and vulnerability scanning
configSchema:
  type: object
  properties:
    npmRegistryUrl:
      type: string
      description: Custom npm registry URL
    cacheTtlSeconds:
      type: number
      description: Cache TTL in seconds
  required: []

#### Server.json Configuration

The server.json file provides additional MCP server metadata:

{
  "name": "npm-sentinel-mcp",
  "version": "1.18.0",
  "description": "MCP server for npm package security analysis",
  "tools": [
    "npmDeps",
    "npmVulnScan",
    "npmPackageInfo",
    "npmPackageVersions"
  ]
}

Health Monitoring

Health Check Endpoint

The container includes a health check that verifies the server is operational:

# Check container health
docker inspect --format='{{.State.Health.Status}}' npm-sentinel-mcp

# View health check logs
docker inspect --format='{{json .State.Health}}' npm-sentinel-mcp

Logs Access

View container logs for debugging and monitoring:

# Stream live logs
docker logs -f npm-sentinel-mcp

# View last 100 lines
docker logs --tail 100 npm-sentinel-mcp

# Search logs for specific patterns
docker logs npm-sentinel-mcp 2>&1 | grep -i error

Deployment Patterns

Docker Compose Setup

For production deployments, use Docker Compose for easier management:

version: '3.8'

services:
  npm-sentinel-mcp:
    image: npm-sentinel-mcp:latest
    container_name: npm-sentinel-mcp
    ports:
      - "3000:3000"
    env_file:
      - .env
    volumes:
      - sentinel-data:/app/data
      - sentinel-logs:/app/logs
    restart: unless-stopped
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:3000/health"]
      interval: 30s
      timeout: 10s
      retries: 3
      start_period: 40s

volumes:
  sentinel-data:
  sentinel-logs:

Integration with Claude Desktop

To connect npm-sentinel-mcp with Claude Desktop, add the following to your claude_desktop_config.json:

{
  "mcpServers": {
    "npm-sentinel-mcp": {
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "-it",
        "-p", "3000:3000",
        "-v", "$(pwd)/.env:/app/.env:ro",
        "npm-sentinel-mcp:latest"
      ]
    }
  }
}

Troubleshooting

Common Issues

Debug Mode

Enable debug logging by setting the environment variable:

docker run -d \
  --name npm-sentinel-mcp \
  -e LOG_LEVEL=debug \
  -p 3000:3000 \
  npm-sentinel-mcp:latest

Container Shell Access

For troubleshooting, access a shell inside the container:

docker exec -it npm-sentinel-mcp sh

Security Considerations

Container Security Best Practices

1. Run as non-root user: The container runs as UID 1000 by default
2. Read-only root filesystem: Mount volumes for writable areas
3. Minimal base image: Uses Node.js Alpine for reduced attack surface
4. No privileged mode: Does not require privileged access

Network Security

Version Compatibility

See Also

• README.md - Main project documentation
• package.json - npm dependencies and scripts
• smithery.yaml - Smithery marketplace configuration
• server.json - MCP server metadata
• GitHub Releases - Version history and changelog

Related Pages

Related topics: MCP Tools Reference, Introduction to NPM Sentinel MCP

API and Resources Reference

This page provides comprehensive documentation for the MCP (Model Context Protocol) tools, resources, and APIs exposed by npm-sentinel-mcp. It covers the complete interface surface area including tool schemas, resource templates, configuration options, and data models.

Overview

npm-sentinel-mcp exposes a set of MCP tools and resources that enable AI assistants to interact with npm registry data, perform vulnerability scanning, and resolve dependency trees. The server acts as a bridge between the MCP protocol and external services (npm Registry, deps.dev API).

The API layer consists of:

• MCP Tools: Callable functions exposed via the MCP protocol
• Resources: Static and templated resources providing package metadata
• Configuration: Runtime configuration via the configSchema
• Data Models: Zod schemas for validation and type safety

Source: index.ts

Architecture Overview

graph TD
    MCP[Model Context Protocol Client] --> Server[npm-sentinel-mcp Server]
    Server --> Tools[MCP Tools]
    Server --> Resources[MCP Resources]
    Tools --> npmRegistry[npm Registry API]
    Tools --> depsDev[deps.dev API]
    depsDev --> VulnerabilityScan[vulnerabilityScan]
    depsDev --> NpmDeps[npmDeps Tool]
    npmRegistry --> PackageInfo[packageInfo Tool]
    npmRegistry --> NpmDeps[npmDeps Tool]
    Server --> Cache[Cache Layer]
    Cache --> npmRegistry
    Cache --> depsDev

MCP Tools

npm-sentinel-mcp exposes the following tools via the MCP protocol. Each tool has a defined schema with input parameters and return types.

Tool Overview

Source: src/tools/npmsentinel.ts

vulnerabilityScan Tool

The vulnerabilityScan tool analyzes npm packages for security vulnerabilities using the deps.dev API for enhanced transitive dependency scanning.

Parameters:

Response Schema:

{
  vulnerabilities: VulnerabilityRecord[],
  scanTimestamp: string,
  registrySource: string,
  depsDevEnriched: boolean
}

Security Features:

• Strict package name validation prevents command injection (v1.16.0+)
• Transitive dependency scanning via deps.dev API
• CVE enrichment for vulnerability data
• React ecosystem awareness for known vulnerable patterns

Source: src/tools/vulnerabilityScan.ts

npmDeps Tool

The npmDeps tool resolves complete dependency trees for npm packages, including transitive dependencies.

Parameters:

Response Schema:

{
  package: PackageMetadata,
  dependencies: DependencyNode[],
  devDependencies: DependencyNode[],
  peerDependencies: DependencyNode[],
  transitiveInsights: TransitiveTopology[]
}

Dependency Resolution Features:

• Resolves both production and development dependencies
• Handles peer dependencies
• Injects transitive topology insights via deps.dev (v1.18.0+)
• Bypasses npm Registry subrequest limits using deps.dev integration (v1.17.0+)

Source: src/tools/npmDeps.ts

packageInfo Tool

The packageInfo tool retrieves metadata from the npm registry for a given package.

Parameters:

Response Schema:

{
  name: string,
  version: string,
  description: string,
  dist: DistMetadata,
  dependencies: Record<string, string>,
  devDependencies: Record<string, string>,
  peerDependencies: Record<string, string>,
  deprecated: boolean | string,
  license: string,
  repository: RepositoryInfo,
  homepage: string
}

Source: src/utils/npmRegistry.ts

MCP Resources

npm-sentinel-mcp exposes the following resources for retrieving package information and metadata.

Resource Templates

#### npm-package://{registry}/{scope}/{package}/{version}

Template for accessing npm package resources dynamically.

Template Variables:

Supported Content Types:

• application/json - Full package metadata
• text/markdown - Human-readable summary

Source: src/types/resourceTypes.ts

Static Resources

Configuration Schema

The npm-sentinel-mcp server accepts configuration via the configSchema. All configuration is validated using Zod schemas at startup.

Source: src/config/configSchema.ts

Configuration Options

Smithery Configuration

For Smithery marketplace integration (v1.13.2+), the configSchema is exposed at the root level for better detection.

# smithery.yaml
name: npm-sentinel-mcp
description: MCP server for npm security and dependency analysis
configSchema:
  registryUrl:
    type: string
    default: https://registry.npmjs.org
  strictNameValidation:
    type: boolean
    default: true

Source: llms-full.txt

Data Models

Core Types

interface VulnerabilityRecord {
  id: string;
  severity: 'low' | 'moderate' | 'high' | 'critical';
  packageName: string;
  vulnerableVersions: string;
  patchedVersions?: string;
  title: string;
  description?: string;
  cveId?: string;
  references?: string[];
}

interface DependencyNode {
  name: string;
  version: string;
  resolved?: string;
  dependencies: DependencyNode[];
  dev: boolean;
  peer: boolean;
}

interface TransitiveTopology {
  depth: number;
  path: string[];
  dependencyOf: string;
  versionConstraints: string;
}

Source: src/types/resourceTypes.ts

Validation with Zod

All input parameters are validated using Zod schemas. This ensures:

• Type safety across the application
• Runtime validation of external inputs
• Clear error messages for invalid requests

Example Validation Error (v1.16.1): Fixed Zod validation errors in npm-registry.test.ts to provide clearer error messages when package names do not match expected patterns.

Source: src/utils/npmRegistry.ts

Cache System

npm-sentinel-mcp includes a robust caching layer for performance optimization.

Cache Features (v1.15.0+)

• TTL-based expiration: Configurable time-to-live for cached entries
• Manual invalidation: API for clearing specific cache entries
• Hit/miss tracking: Statistics for cache effectiveness

Cache Configuration

Cache Flow

sequenceDiagram
    participant Client
    participant Server
    participant Cache
    participant ExternalAPI
    
    Client->>Server: Request (package, params)
    Server->>Cache: Check cache key
    Cache-->>Server: Cache hit?
    
    alt Cache Hit
        Cache-->>Server: Cached response
        Server-->>Client: Return cached data
    else Cache Miss
        Server->>ExternalAPI: Fetch fresh data
        ExternalAPI-->>Server: Response
        Server->>Cache: Store response
        Server-->>Client: Return fresh data
    end

External API Integrations

npm Registry API

Base URL: https://registry.npmjs.org

deps.dev API

Base URL: https://api.deps.dev

Integration Benefits (v1.17.0+):

• Bypasses npm Registry subrequest limits during vulnerability scans
• Provides comprehensive transitive dependency analysis
• Enriches vulnerability data with CVE information

Source: src/utils/depsDevClient.ts

Error Handling

Error Response Format

interface ErrorResponse {
  error: {
    code: string;
    message: string;
    details?: Record<string, unknown>;
  };
}

Error Codes

Common Failure Modes

1. Network Timeouts: Registry requests that exceed timeoutMs configuration
2. Invalid Package Names: Names that don't conform to npm naming conventions (strict validation enabled by default)
3. Rate Limiting: Too many requests to npm Registry or deps.dev
4. Version Not Found: Requested version doesn't exist for the package
5. Cache Corruption: Stale cache entries causing incorrect responses (addressed by v1.15.0+ invalidation)

Security Considerations

Package Name Validation (v1.16.0+)

Strict package name validation is enforced across all tools to prevent:

• Command injection attacks
• Path traversal vulnerabilities
• Malformed input handling

Validation follows npm naming conventions:

• Scoped packages: @scope/package-name
• Unscoped packages: package-name
• No special characters except hyphens and underscores

Transitive Scanning Security

• Vulnerability scanning includes transitive dependencies
• React ecosystem patterns are specifically analyzed
• CVE data is enriched from multiple sources

Version History

See Also

• Installation Guide - Setting up npm-sentinel-mcp
• Configuration Reference - Detailed configuration options
• Troubleshooting - Common issues and solutions
• Changelog - Version history

Related Pages

Related topics: Security Features

Input Validation and Type Safety

This document describes the input validation and type safety mechanisms implemented in npm-sentinel-mcp, a Model Context Protocol (MCP) server for npm package security operations. The system enforces strict validation at multiple layers to ensure reliable and secure operations when querying npm registry data, scanning for vulnerabilities, and resolving package dependencies.

Overview

npm-sentinel-mcp implements a multi-layered validation strategy that combines runtime type checking with schema-based validation. This approach provides defense in depth against malformed inputs, prevents security vulnerabilities, and ensures consistent data structures throughout the application lifecycle.

The validation system serves three primary purposes:

1. Security Enforcement: Prevents injection attacks and malicious package name patterns
2. Data Integrity: Ensures responses from external APIs conform to expected structures
3. Developer Experience: Provides clear, actionable error messages when validation fails

Architecture

Validation Layers

The validation architecture operates across three distinct layers, each with specific responsibilities and failure modes.

graph TD
    A[Tool Input Parameters] --> B[Package Name Validator]
    B --> C[Zod Schema Validation]
    C --> D[Runtime Type Guards]
    D --> E[External API Response Validation]
    E --> F[Cache Key Generation]
    F --> G[Processed Result]
    
    B -.->|Invalid| H[Security Error]
    C -.->|Invalid| I[Schema Error]
    D -.->|Invalid| J[Type Error]
    E -.->|Invalid| K[Data Integrity Error]

Component Responsibilities

Package Name Validation

As of v1.16.0, npm-sentinel-mcp enforces strict package name validation across all tools. This security enhancement prevents various attack vectors including:

• Directory traversal attempts via .. patterns
• Environment variable injection via $ characters
• Command injection through special shell characters
• Prototype pollution via __proto__ or constructor properties

Validation Rules

The packageName.ts validator implements the following validation rules:

// Validation rule implementation
const FORBIDDEN_PATTERNS = [
  '..',           // Directory traversal
  '__proto__',    // Prototype pollution
  'constructor',  // Prototype pollution
  '$',            // Environment variable injection
  '\\n',          // Newline injection
  '&&',           // Command chaining
  '||',           // Command chaining
  ';',            // Command separator
  '`',            // Command substitution
];

Source: src/validators/packageName.ts

npm Registry Naming Specification

Package names must conform to the npm registry specification, which defines:

Source: src/validators/packageName.ts

Validation Flow

sequenceDiagram
    participant Client
    participant Validator
    participant Registry
    
    Client->>Validator: packageName: "lodash"
    Validator->>Validator: Check length constraints
    Validator->>Validator: Scan for forbidden patterns
    Validator->>Validator: Validate scope format
    Validator->>Validator: Check npm naming spec compliance
    alt Valid
        Validator-->>Registry: Proceed with request
        Registry-->>Client: Package data
    else Invalid
        Validator-->>Client: ValidationError with details
    end

Zod Schema Validation

npm-sentinel-mcp uses Zod for schema-based validation of both input parameters and external API responses. Zod provides compile-time type inference combined with runtime validation, ensuring type safety throughout the application.

Core Schemas

The schemas.ts module defines validation schemas for all tool inputs and API responses:

#### Tool Input Schemas

Source: src/validators/schemas.ts

Schema Validation Example

The following demonstrates the typical validation flow for tool inputs:

import { z } from 'zod';
import { validatePackageName } from './packageName';
import { NpmDepsInputSchema } from './schemas';

async function handleNpmDepsTool(input: unknown) {
  // Step 1: Schema validation with Zod
  const parseResult = NpmDepsInputSchema.safeParse(input);
  
  if (!parseResult.success) {
    return {
      content: [{
        type: 'text',
        text: `Validation failed: ${formatZodError(parseResult.error)}`
      }]
    };
  }
  
  const { packageName } = parseResult.data;
  
  // Step 2: Security-focused package name validation
  const validationResult = validatePackageName(packageName);
  
  if (!validationResult.valid) {
    return {
      content: [{
        type: 'text',
        text: `Security validation failed: ${validationResult.reason}`
      }]
    };
  }
  
  // Proceed with validated input
  return executeDepsQuery(packageName);
}

Source: src/tools/npmDeps.ts

Error Handling

When Zod validation fails, the system provides detailed error messages:

interface ValidationError {
  issues: Array<{
    path: string[];
    message: string;
    code: string;
  }>;
}

Common validation error codes include:

Source: src/validators/schemas.ts

Type Safety Mechanisms

Runtime Type Guards

Beyond compile-time TypeScript types, npm-sentinel-mcp employs runtime type guards to validate data structures returned from external APIs. This catches inconsistencies between API providers and expected schemas.

function isValidPackageMetadata(obj: unknown): obj is PackageMetadata {
  if (typeof obj !== 'object' || obj === null) return false;
  
  const pkg = obj as Record<string, unknown>;
  return (
    typeof pkg.name === 'string' &&
    typeof pkg.version === 'string' &&
    (typeof pkg.dist === 'object' || pkg.dist === undefined)
  );
}

Source: src/utils/npmRegistry.ts

Response Validation Pipeline

External API responses undergo multi-stage validation:

graph LR
    A[API Response] --> B[HTTP Status Check]
    B --> C[Content-Type Check]
    C --> D[Schema Structure]
    D --> E[Field Type Guards]
    E --> F[Business Logic Validation]
    F --> G[Cache Store]
    
    B -.->|Non-2xx| H[Network Error]
    C -.->|Wrong Type| I[Parse Error]
    D -.->|Missing Fields| J[Schema Error]
    E -.->|Type Mismatch| K[Type Error]

Source: src/utils/npmRegistry.ts

Configuration Options

Validation Configuration

The validation system behavior can be configured via the server configuration schema:

Source: src/index.ts, package.json

Environment Variables

Validation behavior can be modified through environment variables:

# Enable debug logging for validation failures
DEBUG=validation

# Increase cache timeout for high-latency scenarios  
NPM_SENTINEL_CACHE_TTL=600000

# Disable strict mode (not recommended for production)
NPM_SENTINEL_STRICT=false

Common Failure Modes

Invalid Package Name

Symptom: ValidationError: Invalid package name format

Cause: Package name contains forbidden characters or violates npm naming conventions

Resolution: Ensure package names conform to npm registry specification:

// Valid package names
const validNames = ['lodash', '@types/node', 'my-package'];

// Invalid package names
const invalidNames = ['../etc/passwd', '$ENV_VAR', '..\\..\\windows'];

Zod Schema Mismatch

Symptom: ValidationError: Expected object, received array

Cause: Input data structure doesn't match expected schema

Resolution: Check the schema definition and ensure input matches expected structure. This was addressed in v1.16.1 for npm-registry tests.

Source: v1.16.1 Release Notes

Cache Inconsistency

Symptom: Stale validation results after schema updates

Cause: Cached data from previous schema versions

Resolution: v1.15.0 introduced robust cache invalidation mechanisms. Clear the cache or wait for TTL expiration.

Source: v1.15.0 Release Notes

Testing Validation

The validation system includes comprehensive test coverage using Jest:

# Run validation-specific tests
npm test -- --testPathPattern=validators

# Run package name validation tests
npm test -- --testNamePattern="packageName"

# Run schema validation tests
npm test -- --testNamePattern="schemas"

Source: src/validators/packageName.ts, src/validators/schemas.ts

Best Practices

Input Sanitization

Always sanitize user input before passing to tools:

// DO: Validate and sanitize
const sanitized = sanitizeInput(userInput);
const result = await tools.npmDeps({ packageName: sanitized });

// DON'T: Pass unsanitized input directly
const result = await tools.npmDeps({ packageName: userInput });

Error Handling

Implement proper error handling for validation failures:

try {
  const result = await tools.npmDeps({ packageName });
} catch (error) {
  if (error instanceof z.ZodError) {
    // Handle validation errors gracefully
    logger.warn('Validation failed', { errors: error.errors });
  }
  throw error;
}

Type Safety

Leverage TypeScript's type inference with Zod:

// Type is automatically inferred from schema
const schema = z.object({
  packageName: z.string(),
  version: z.string().optional()
});

type ToolInput = z.infer<typeof schema>;

See Also

• Getting Started - Setup and installation instructions
• Security Features - Security mechanisms overview
• Caching System - Cache invalidation and management
• API Reference - Complete tool API documentation
• Troubleshooting - Common issues and solutions

Related Pages

Related topics: Installation and Configuration, Caching System, Docker Deployment

Troubleshooting

This page provides comprehensive guidance for diagnosing and resolving common issues encountered when using npm-sentinel-mcp, a Model Context Protocol (MCP) server designed for npm package security analysis, dependency management, and vulnerability scanning.

Overview

npm-sentinel-mcp integrates with the npm registry, deps.dev API, and various vulnerability databases to provide security insights for npm packages. Troubleshooting this system requires understanding its layered architecture and the external dependencies it relies upon.

graph TD
    subgraph "Client Layer"
        A[MCP Client] --> B[Request Handler]
    end
    
    subgraph "Core Engine"
        B --> C[Security Scanner]
        C --> D[Dependency Resolver]
        D --> E[Cache Manager]
    end
    
    subgraph "External Services"
        E --> F[npm Registry API]
        E --> G[deps.dev API]
        E --> H[Vulnerability Databases]
    end
    
    subgraph "Failure Points"
        F --> I1[Rate Limiting]
        F --> I2[Network Timeout]
        G --> I3[API Errors]
        H --> I4[Stale Data]
    end

Source: src/index.ts

Common Issues and Resolutions

Connection and Network Problems

Source: src/mcp/NpmRegistry.ts

#### Diagnosing Network Issues

# Test npm registry connectivity
curl -I https://registry.npmjs.org/

# Test deps.dev connectivity  
curl -I https://deps.dev/

# Check for proxy environment variables
env | grep -i proxy

Package Name Validation Failures

Starting with v1.16.0, npm-sentinel-mcp enforces strict package name validation across all tools. Invalid package names will be rejected before any API calls are made.

graph LR
    A[Input Package Name] --> B{Valid Format?}
    B -->|No| C[Validation Error]
    B -->|Yes| D[Query Registry]
    D --> E[Package Exists?]
    E -->|No| F[Not Found Error]
    E -->|Yes| G[Return Metadata]

Source: src/config.ts

Common validation errors:

Cache-Related Problems

npm-sentinel-mcp implements robust cache invalidation mechanisms (v1.15.0) to optimize repeated queries.

graph TD
    A[Incoming Request] --> B{Cache Hit?}
    B -->|Yes| C[Return Cached Data]
    B -->|No| D[Fetch from API]
    D --> E{Data Changed?}
    E -->|Yes| F[Invalidate Cache]
    E -->|No| G[Update TTL]
    F --> H[Store Fresh Data]
    G --> H
    H --> C

Source: src/mcp/NpmRegistry.ts

#### Cache Troubleshooting Steps

1. Clear all cached data: Restart the MCP server to reset in-memory cache
2. Force fresh fetch: Use a unique query parameter to bypass cache
3. Check TTL settings: Verify cache expiration is configured correctly

// Example cache configuration in config.ts
const cacheConfig = {
  ttl: 3600000,        // 1 hour default TTL
  maxSize: 1000,        // Maximum cached entries
  staleWhileRevalidate: true
};

Error Reference

Error Codes and Messages

Source: src/mcp/NpmRegistry.ts

Zod Validation Errors

Version v1.16.1 addressed Zod validation errors in the npm registry module. If you encounter validation errors:

1. Ensure your input conforms to expected schema
2. Check that package metadata from npm is well-formed
3. Update to the latest version of npm-sentinel-mcp

Source: vitest.config.ts

Debugging Procedures

Enabling Debug Mode

Debug mode provides verbose logging for troubleshooting complex issues.

// server.json configuration
{
  "command": "npx",
  "args": ["-y", "npm-sentinel-mcp"],
  "env": {
    "DEBUG": "npm-sentinel-mcp:*",
    "LOG_LEVEL": "debug"
  }
}

Source: server.json

Diagnostic Commands

# Check Node.js version compatibility
node --version  # Must be v20 or compatible

# Verify package installation
npm list npm-sentinel-mcp

# Check for conflicting dependencies
npm ls --all | grep -A5 "npm-sentinel-mcp"

Smithery Configuration Issues

If deploying via Smithery (v1.13.3 fixed configSchema detection):

1. Ensure smithery.yaml is present at project root
2. Verify configSchema is defined at the root level
3. Check that server.json includes proper entry point

# smithery.yaml example
name: npm-sentinel-mcp
description: npm security analysis via MCP
configSchema:
  type: object
  properties:
    npmRegistryUrl:
      type: string
      default: https://registry.npmjs.org/

Source: smithery.yaml

Vulnerability Scanning Issues

Transitive Dependency Scanning Failures

Version v1.14.0 enhanced vulnerability detection with transitive scanning. If scanning fails:

1. Missing transitive data: Check deps.dev API connectivity
2. Incomplete tree: Large dependency trees may timeout; consider scanning specific scopes
3. CVE enrichment failures: Verify vulnerability database accessibility

graph TD
    A[Scan Request] --> B[Fetch Direct Dependencies]
    B --> C[Query deps.dev]
    C --> D[Resolve Transitive Tree]
    D --> E{Vulnerability Found?}
    E -->|Yes| F[Enrich with CVE Data]
    E -->|No| G[Return Clean]
    F --> H[Generate Report]
    H --> I{Has Errors?}
    I -->|Yes| J[Log & Continue]
    I -->|No| K[Complete]

Source: src/index.ts

React Ecosystem Awareness Issues

npm-sentinel-mcp includes React ecosystem awareness for better vulnerability detection. If React-specific vulnerabilities are missed:

1. Verify the package is correctly identified as React-related
2. Check that React version detection is working
3. Ensure vulnerability database includes React advisories

Performance Troubleshooting

Slow Response Times

Memory Issues

npm-sentinel-mcp may consume significant memory when processing large dependency trees:

// Recommended memory settings for large scans
process.env.NODE_OPTIONS = '--max-old-space-size=4096';

Version-Specific Issues

Upgrading from v1.15.x to v1.16.x

Version v1.16.0 introduced strict package name validation. Existing integrations may fail if:

• Package names contain special characters not validated before
• Scoped packages use incorrect format
• Dynamically generated package names bypass validation

Migration steps:

1. Review package name inputs for format compliance
2. Add input sanitization in calling code
3. Test with invalid package names to confirm rejection

Node.js Compatibility

• v1.15.1 downgraded semantic-release-github to v10 for Node 20 compatibility
• Ensure you are running Node.js v20 or v22 LTS
• Avoid Node.js v21+ until compatibility is confirmed

# Check Node version requirement
cat package.json | grep '"engines"'

Source: package.json

Getting Help

If troubleshooting steps do not resolve your issue:

1. Check the GitHub Issues page for known issues and workarounds
2. Enable debug logging and capture error traces
3. Reproduce with minimal configuration to isolate the problem
4. Submit an issue with:

• npm-sentinel-mcp version
• Node.js version
• Operating system
• Complete error message and stack trace
• Minimal reproduction case

See Also

• Installation Guide — Getting started with npm-sentinel-mcp
• Configuration Reference — Complete configuration options
• API Reference — Tool definitions and usage
• Security Features — Vulnerability scanning details
• Architecture Overview — System design documentation

Doramagic Pitfall Log

Found 7 structured pitfall item(s), including 0 high/blocking item(s). Top priority: Identity risk - Identity risk requires verification.

1. Identity risk: Identity risk requires verification

• Severity: medium
• Finding: Project evidence flags a identity risk. Review the linked source before relying on this workflow.
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: identity.distribution | mcp_registry:io.github.Nekzus/npm-sentinel-mcp:1.18.0 | https://registry.modelcontextprotocol.io/v0.1/servers/io.github.Nekzus%2Fnpm-sentinel-mcp/versions/1.18.0

2. Capability evidence risk: Capability evidence risk requires verification

• Severity: medium
• Finding: README/documentation is current enough for a first validation pass.
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: capability.assumptions | mcp_registry:io.github.Nekzus/npm-sentinel-mcp:1.18.0 | https://registry.modelcontextprotocol.io/v0.1/servers/io.github.Nekzus%2Fnpm-sentinel-mcp/versions/1.18.0

3. Maintenance risk: Maintenance risk requires verification

• Severity: medium
• Finding: Project evidence flags a maintenance risk. Review the linked source before relying on this workflow.
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: evidence.maintainer_signals | mcp_registry:io.github.Nekzus/npm-sentinel-mcp:1.18.0 | https://registry.modelcontextprotocol.io/v0.1/servers/io.github.Nekzus%2Fnpm-sentinel-mcp/versions/1.18.0

4. Security or permission risk: Security or permission risk requires verification

• Severity: medium
• Finding: no_demo
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: downstream_validation.risk_items | mcp_registry:io.github.Nekzus/npm-sentinel-mcp:1.18.0 | https://registry.modelcontextprotocol.io/v0.1/servers/io.github.Nekzus%2Fnpm-sentinel-mcp/versions/1.18.0

5. Security or permission risk: Security or permission risk requires verification

• Severity: medium
• Finding: no_demo
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: risks.scoring_risks | mcp_registry:io.github.Nekzus/npm-sentinel-mcp:1.18.0 | https://registry.modelcontextprotocol.io/v0.1/servers/io.github.Nekzus%2Fnpm-sentinel-mcp/versions/1.18.0

6. Maintenance risk: Maintenance risk requires verification

• Severity: low
• Finding: issue_or_pr_quality=unknown。
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: evidence.maintainer_signals | mcp_registry:io.github.Nekzus/npm-sentinel-mcp:1.18.0 | https://registry.modelcontextprotocol.io/v0.1/servers/io.github.Nekzus%2Fnpm-sentinel-mcp/versions/1.18.0

7. Maintenance risk: Maintenance risk requires verification

• Severity: low
• Finding: release_recency=unknown。
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: evidence.maintainer_signals | mcp_registry:io.github.Nekzus/npm-sentinel-mcp:1.18.0 | https://registry.modelcontextprotocol.io/v0.1/servers/io.github.Nekzus%2Fnpm-sentinel-mcp/versions/1.18.0

Community Discussion Evidence

Doramagic exposes project-level community discussion separately from official documentation. Review these links before using npm-sentinel-mcp with real data or production workflows.

• v1.18.0 - github / github_release
• v1.17.0 - github / github_release
• v1.16.2 - github / github_release
• v1.16.1 - github / github_release
• v1.16.0 - github / github_release
• v1.15.1 - github / github_release
• v1.15.0 - github / github_release
• v1.14.0 - github / github_release
• v1.13.3 - github / github_release
• v1.13.2 - github / github_release
• Identity risk requires verification - GitHub / issue