核心定位与价值

npm-sentinel-mcp 定位为 npm 生态系统的安全哨兵，通过标准化的 MCP 接口为 AI 助手提供实时、准确的包信息查询服务。其核心价值体现在以下几个方面：

架构设计

整体架构

npm-sentinel-mcp 采用分层架构设计，将协议处理、业务逻辑和数据访问层清晰分离：

graph TD
    subgraph "MCP 协议层"
        A["MCP Client<br/>(Claude/GPT)"] --> B["MCP Server<br/>(npm-sentinel-mcp)"]
    end
    
    subgraph "工具服务层"
        B --> C["npmDeps<br/>依赖查询"]
        B --> D["npmVulnScan<br/>漏洞扫描"]
        B --> E["npmPackageInfo<br/>包信息查询"]
    end
    
    subgraph "数据访问层"
        C --> F["NPM Registry API"]
        D --> G["deps.dev API"]
        D --> H["CVE Database"]
        E --> F
    end
    
    subgraph "缓存层"
        F --> I["Memory Cache<br/>缓存管理"]
        G --> I
    end
    
    style A fill:#e1f5fe
    style B fill:#b3e5fc
    style I fill:#fff9c4

核心组件

主要功能模块

依赖查询工具 (npmDeps)

npmDeps 工具提供 npm 包依赖树的深度查询能力，支持解析直接依赖和传递依赖关系。

功能特性：

• 通过 deps.dev API 获取完整的依赖拓扑结构
• 支持查询 npm 包的直接依赖和传递依赖
• 提供依赖版本信息和依赖关系可视化

版本演进（v1.17.0 - v1.18.0）：

• v1.17.0：集成 deps.dev API，突破 npm registry 的子请求限制
• v1.18.0：注入传递依赖拓扑洞察，增强依赖关系分析能力

漏洞扫描工具 (npmVulnScan)

npmVulnScan 工具执行 npm 包的安全漏洞扫描，检测已知的安全问题。

功能特性：

• 支持 transitive scanning，可扫描传递依赖中的漏洞
• 自动关联 CVE 漏洞数据库
• React 生态系统感知，识别 React 特定的安全问题
• CVE Enrichment，提供漏洞的详细元数据

版本演进：

• v1.14.0：增强漏洞检测，支持传递扫描、React 生态感知和 CVE 丰富化

包信息查询 (npmPackageInfo)

npmPackageInfo 工具提供 npm 包的详细元信息查询，包括版本、描述、作者等基本信息。

安全机制

包名验证

从 v1.16.0 起，项目实现了严格的包名验证机制，所有工具均强制执行包名格式校验，防止恶意输入。

缓存失效机制

v1.15.0 引入了健壮的缓存失效机制，确保数据的实时性和一致性：

graph LR
    A["请求到达"] --> B{"缓存有效?"}
    B -->|是| C["返回缓存数据"]
    B -->|否| D["调用外部 API"]
    D --> E["更新缓存"]
    E --> F["返回新数据"]
    C --> G["响应"]
    F --> G

配置与部署

Smithery 集成

npm-sentinel-mcp 原生支持 Smithery 平台，可通过配置文件自动发现和集成：

# smithery.yaml
name: npm-sentinel-mcp
description: MCP server for npm package security and management
configSchema:
  # 配置文件定义

环境要求

安装方式

# 通过 npm 全局安装
npm install -g npm-sentinel-mcp

# 或通过 Smithery 平台安装
npx @smithery/cli install npm-sentinel-mcp

版本历史亮点

技术栈

适用场景

npm-sentinel-mcp 特别适用于以下场景：

1. AI 代码助手集成：为 LLM 代理提供 npm 包安全性判断能力
2. CI/CD 安全扫描：在持续集成流程中自动检测依赖漏洞
3. 依赖管理审查：评估项目依赖的安全状态和健康度
4. 自动化审计：定期执行 npm 包安全审计任务

相关链接

• 源码仓库：https://github.com/Nekzus/npm-sentinel-mcp
• NPM 包：https://www.npmjs.com/package/npm-sentinel-mcp
• Smithery 平台：https://smithery.ai/

参见

• 工具使用指南 - 详细了解各 MCP 工具的使用方法
• API 集成说明 - deps.dev 和 NPM Registry 集成详情
• 安全配置 - 安全机制配置参考

系统要求

运行环境要求

注意：v1.15.1 版本明确将 semantic-release-github 降级至 v10 以确保 Node.js 20 的兼容性。资料来源：package.json()

网络要求

• 访问 npm Registry：用于获取包元数据和漏洞信息
• 访问 deps.dev API：用于解析传递依赖拓扑（v1.17.0+ 新增功能）
• 访问漏洞数据源：用于 CVE 数据丰富化

安装方法

方法一：全局安装（推荐）

全局安装允许您在任何目录下使用 Sentinel 工具：

npm install -g npm-sentinel-mcp

安装完成后，验证安装：

npx npm-sentinel-mcp --version

方法二：本地项目安装

作为开发依赖安装在特定项目中：

cd /path/to/your/project
npm install --save-dev npm-sentinel-mcp

方法三：直接从源码构建

适用于需要最新功能或参与项目开发的用户：

# 克隆仓库
git clone https://github.com/Nekzus/npm-sentinel-mcp.git
cd npm-sentinel-mcp

# 安装依赖
npm install

# 编译 TypeScript
npm run build

# 链接为全局包
npm link

MCP 服务器配置

服务器启动模式

npm-sentinel-mcp 支持两种主要运行模式：

graph TD
    A[MCP 客户端] --> B{连接模式}
    B -->|STDIO| C[标准输入输出]
    B -->|HTTP| D[HTTP 服务器]
    C --> E[npm-sentinel-mcp]
    D --> F[端口 3000]
    E --> G[npm Registry]
    F --> G

初始化配置

首次运行需要初始化配置文件：

npx npm-sentinel-mcp init

这将在用户主目录创建配置文件 ~/.npm-sentinel-mcp/config.json。

Smithery 集成配置

对于使用 Smithery 平台的用户，项目提供了专门的配置文件。资料来源：smithery.yaml()

smithery.yaml 配置

name: npm-sentinel-mcp
description: MCP server for npm package security scanning
version: 1.18.0
installCommand: npm install -g npm-sentinel-mcp

重要：v1.13.2 和 v1.13.3 版本修复了 Smithery 平台的配置检测问题，将 configSchema 明确置于根级别以提高检测率。资料来源：smithery.yaml()

server.json 配置

Smithery 平台使用的标准服务器配置文件：

{
  "name": "npm-sentinel-mcp",
  "displayName": "npm Sentinel MCP",
  "description": "Security scanner for npm packages with vulnerability detection",
  "version": "1.18.0"
}

环境变量配置

必需的环境变量

可选的环境变量

配置示例：

export NPM_REGISTRY_URL=https://registry.npmmirror.com
export NPM_TOKEN=npm_xxxxxxxxxxxxx
export DEPS_DEV_API_KEY=depsdev_xxxxxxxxxxxxx
export LOG_LEVEL=debug

验证安装

基本功能测试

# 测试服务器启动
npx npm-sentinel-mcp --help

MCP 协议握手测试

创建一个简单的测试脚本来验证 MCP 协议兼容性：

// test-mcp.ts
import { Client } from '@modelcontextprotocol/sdk/client/index.js';

const client = new Client({
  name: 'test-client',
  version: '1.0.0',
}, {
  capabilities: {}
});

await client.connect({
  transport: 'stdio',
});

const tools = await client.listTools();
console.log('Available tools:', tools);

运行测试：

npx tsx test-mcp.ts

可用工具列表

成功安装后，以下工具将可通过 MCP 协议访问：

常见问题与故障排除

Node.js 版本不兼容

症状：启动时出现 SyntaxError 或 ReferenceError

解决方案：

# 使用 nvm 切换到兼容版本
nvm install 20
nvm use 20

MCP 连接失败

症状：客户端无法连接到服务器

排查步骤：

``bash npx npm-sentinel-mcp & ``

1. 检查服务器是否正常启动：

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

1. 验证 STDIO 连接配置正确：

Zod 验证错误

v1.16.1 版本修复了 Zod 验证相关的问题。如果遇到验证错误，请确保使用最新版本：

npm update -g npm-sentinel-mcp

资料来源：package.json()

缓存问题

v1.15.0 引入了健壮的缓存失效机制。如果发现数据过期：

# 清除全局缓存
rm -rf ~/.npm-sentinel-mcp/cache

# 重启服务器
pkill -f npm-sentinel-mcp
npx npm-sentinel-mcp &

IDE 集成

Claude Desktop 配置

编辑 ~/Library/Application Support/Claude/claude_desktop_config.json：

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

Cursor 配置

编辑 ~/.cursor/mcp.json：

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

卸载

如需卸载 npm-sentinel-mcp：

# 卸载全局包
npm uninstall -g npm-sentinel-mcp

# 清理配置和缓存
rm -rf ~/.npm-sentinel-mcp

相关资源

• 项目主页
• 最新发布版本 (v1.18.0)
• Smithery 集成页面
• 变更日志

另请参见

• 安全扫描功能说明
• 依赖分析功能
• CVE 数据集成

架构概述

npm-sentinel-mcp 采用分层架构设计，将 MCP 协议层、业务逻辑层和数据服务层分离，以实现高内聚、低耦合的模块化结构。

graph TB
    subgraph "表现层 (Presentation Layer)"
        MCP[MCP Server]
    end
    
    subgraph "业务逻辑层 (Business Logic Layer)"
        NPM[NPM Registry 工具集]
        VS[Vulnerability Scanner]
        PNV[Package Name Validator]
    end
    
    subgraph "服务层 (Service Layer)"
        Cache[Cache Service]
        DepsDev[Deps.dev Service]
        NPMRegistry[NPM Registry API]
    end
    
    subgraph "基础设施层 (Infrastructure Layer)"
        FileSystem[文件系统]
        ExternalAPIs[外部 API]
    end
    
    MCP --> NPM
    MCP --> VS
    MCP --> PNV
    NPM --> Cache
    VS --> Cache
    VS --> DepsDev
    NPM --> NPMRegistry
    Cache --> FileSystem
    DepsDev --> ExternalAPIs
    NPMRegistry --> ExternalAPIs

架构分层说明：

资料来源：src/index.ts

核心组件详解

MCP 服务器

MCP 服务器是整个系统的入口点，负责接收来自 LLM 客户端的请求并路由到相应的工具处理。

graph LR
    Request[LLM 请求] --> Parse[协议解析]
    Parse --> Route[工具路由]
    Route --> Tool[业务工具]
    Tool --> Response[标准化响应]
    Response --> JSON[JSON-RPC 格式]

服务器配置参数：

资料来源：package.json

NPM Registry 工具集

NPM Registry 工具集提供 npm 包元数据查询能力，包括包信息、版本列表、依赖关系等。

graph TD
    Start[查询请求] --> Validate[包名验证]
    Validate -->|通过| CheckCache{缓存命中?}
    Validate -->|失败| Error[验证错误]
    CheckCache -->|是| ReturnCache[返回缓存数据]
    CheckCache -->|否| Fetch[API 获取]
    Fetch --> UpdateCache[更新缓存]
    UpdateCache --> ReturnFresh[返回新数据]

主要工具函数：

资料来源：src/tools/npm-registry.ts

漏洞扫描器

漏洞扫描器是 v1.14.0 引入的核心安全功能，支持传递依赖扫描和 CVE 漏洞富化。

graph TD
    ScanRequest[扫描请求] --> ParseDeps[解析依赖树]
    ParseDeps --> Direct[直接依赖]
    ParseDeps --> Transitive[传递依赖]
    Direct --> Scan[漏洞检测]
    Transitive --> Scan
    Scan --> DepsDevAPI[查询 Deps.dev]
    DepsDevAPI --> Enrich[CVE 富化]
    Enrich --> Report[生成报告]

扫描特性：

资料来源：src/tools/vulnerability-scanner.ts

包名验证器

v1.16.0 引入的严格包名验证机制，确保所有工具使用的包名符合 npm 规范。

graph LR
    Input[包名输入] --> Regex[正则校验]
    Regex --> Valid{有效?}
    Valid -->|是| Allow[允许请求]
    Valid -->|否| Block[拒绝请求]
    Block --> ErrorMsg[返回验证错误]

验证规则：

资料来源：src/tools/package-name-validator.ts

服务层架构

缓存服务

缓存服务采用多级缓存策略，支持内存缓存和文件系统持久化缓存。

graph TD
    Request[数据请求] --> Memory{Memory Cache?}
    Memory -->|命中| ReturnMem[返回内存数据]
    Memory -->|未命中| File{File Cache?}
    File -->|命中| ReadFile[读取文件]
    ReadFile --> PopulateMem[填充内存]
    PopulateMem --> ReturnMem
    File -->|未命中| API{Fetch API?}
    API -->|成功| WriteFile[写入文件]
    WriteFile --> PopulateMem
    API -->|失败| ReturnErr[返回错误]

缓存配置：

v1.15.0 引入了健壮的缓存失效机制，支持基于时间和事件驱动的缓存清理。

资料来源：src/services/cache.service.ts

Deps.dev 服务集成

v1.17.0 集成了 deps.dev API，用于大规模依赖树解析和漏洞信息查询。

graph LR
    Request[依赖分析请求] --> Batch[批量请求]
    Batch --> DepsDev[Deps.dev API]
    DepsDev --> Topology[传递拓扑分析]
    Topology --> Insights[拓扑洞察注入]
    Insights --> EnrichDeps[丰富依赖数据]

集成优势：

v1.18.0 进一步增强，通过 deps.dev 注入传递拓扑洞察到 npmDeps 工具中。

资料来源：src/services/depsdev.service.ts

数据流架构

请求处理流程

sequenceDiagram
    participant LLM as LLM Client
    participant MCP as MCP Server
    participant Tool as Business Tool
    participant Cache as Cache Service
    participant API as External API

    LLM->>MCP: JSON-RPC Request
    MCP->>Tool: Route Request
    Tool->>Cache: Check Cache
    Cache-->>Tool: Cache Hit/Miss
    
    alt Cache Miss
        Tool->>API: Fetch Data
        API-->>Tool: Raw Data
        Tool->>Cache: Store Result
        Tool-->>MCP: Processed Result
    else Cache Hit
        Tool-->>MCP: Cached Result
    end
    
    MCP-->>LLM: JSON-RPC Response

漏洞扫描完整流程

graph TD
    subgraph "Phase 1: 依赖收集"
        A1[读取 package.json] --> A2[解析 dependencies]
        A2 --> A3[解析 devDependencies]
        A3 --> A4[收集所有依赖项]
    end
    
    subgraph "Phase 2: 拓扑分析"
        A4 --> B1[直接依赖列表]
        B1 --> B2[查询 Deps.dev]
        B2 --> B3[获取传递依赖]
        B3 --> B4[构建依赖图谱]
    end
    
    subgraph "Phase 3: 漏洞检测"
        B4 --> C1[匹配已知 CVE]
        C1 --> C2[评估影响范围]
        C2 --> C3[计算风险等级]
    end
    
    subgraph "Phase 4: 报告生成"
        C3 --> D1[格式化结果]
        D1 --> D2[生成漏洞报告]
        D2 --> D3[返回结构化数据]
    end

安全架构

包名验证流程

所有工具请求在处理前必须经过严格的包名验证：

graph TD
    Input[包名输入] --> Length{长度检查<br/>1-214}
    Length -->|通过| Case{小写检查}
    Length -->|失败| RejectL[拒绝: 长度超出范围]
    Case -->|通过| Charset{字符集检查}
    Case -->|失败| RejectC[拒绝: 包含大写字母]
    Charset -->|通过| Scope{作用域检查}
    Charset -->|失败| RejectCS[拒绝: 非法字符]
    Scope -->|有效| Accept[接受请求]
    Scope -->|无效| RejectS[拒绝: 作用域格式错误]

验证错误类型：

资料来源：src/tools/package-name-validator.ts

技术栈

资料来源：package.json

目录结构

npm-sentinel-mcp/
├── src/
│   ├── index.ts              # 主入口
│   ├── tools/                # 业务工具
│   │   ├── npm-registry.ts   # NPM 注册表工具
│   │   ├── vulnerability-scanner.ts  # 漏洞扫描器
│   │   └── package-name-validator.ts  # 包名验证器
│   └── services/             # 服务层
│       ├── cache.service.ts  # 缓存服务
│       └── depsdev.service.ts # Deps.dev 服务
├── tests/                    # 测试文件
├── package.json
├── tsconfig.json
├── smithery.yaml            # Smithery 集成配置
└── server.json              # 服务器配置

版本演进与架构变更

常见问题与故障排除

缓存相关问题

API 请求问题

包名验证问题

相关链接

• npm-sentinel-mcp 官方仓库
• Model Context Protocol 规范
• npm Registry API 文档
• Deps.dev API 文档
• 漏洞扫描功能详解
• 缓存机制说明

概述

npm-sentinel-mcp 是一个基于 Model Context Protocol (MCP) 的 npm 包管理辅助工具，通过 MCP 协议提供一组 npm 包相关的工具函数。该项目的数据流设计围绕三个核心处理阶段展开：请求验证、数据获取与处理、结果缓存与返回。

项目的主要数据来源包括：

• npm Registry API - 官方 npm 包注册表
• deps.dev API - 依赖拓扑分析与漏洞信息

资料来源：src/index.ts:1-50

架构概览

graph TD
    subgraph "MCP 客户端层"
        A[用户请求]
    end
    
    subgraph "MCP Server 核心"
        B[请求入口]
        C[包名称验证]
        D[工具路由]
        
        subgraph "数据处理层"
            E[npm-registry]
            F[npm-deps]
            G[vulnerability-scan]
        end
        
        subgraph "服务层"
            H[缓存服务]
            I[deps.dev 服务]
            J[npm Registry API]
        end
        
        subgraph "验证层"
            K[Zod Schema 验证]
            L[包名称白名单验证]
        end
    end
    
    A --> B
    B --> C
    C --> L
    L --> D
    D --> E
    D --> F
    D --> G
    E --> J
    F --> J
    F --> I
    G --> J
    G --> I
    E --> H
    F --> H
    G --> H
    J --> K
    I --> K
    K --> A

核心数据处理流程

工具调用入口

MCP 协议通过 handleRequest() 方法接收来自客户端的工具调用请求。每个工具请求都经过以下处理阶段：

1. 请求接收 - 解析 MCP 请求协议格式
2. 参数验证 - 使用 Zod Schema 验证输入参数
3. 包名称安全校验 - 验证包名称符合 npm 命名规范
4. 缓存查询 - 检查是否存在有效缓存
5. 数据获取 - 调用外部 API 获取数据
6. 数据处理 - 解析、转换、增强数据
7. 结果缓存 - 将结果存入缓存
8. 响应返回 - 返回符合 MCP 协议的结果

资料来源：src/index.ts:50-150

工具路由机制

每个 MCP 工具对应一个独立的处理模块：

资料来源：src/tools/npm-registry.ts 资料来源：src/tools/npm-deps.ts 资料来源：src/tools/vulnerability-scan.ts

输入数据验证

参数 Schema 验证

所有工具输入参数都经过 Zod Schema 验证，确保数据类型和格式正确：

// npm-registry 工具输入 Schema
{
  packageName: z.string().min(1),
  version: z.string().optional(),
  options: z.object({
    fields: z.array(z.string()).optional()
  }).optional()
}

资料来源：src/tools/npm-registry.ts:20-30

包名称安全校验

v1.16.0 版本引入了严格的包名称验证机制，防止潜在的安全风险：

graph LR
    A[输入包名称] --> B{格式验证}
    B -->|通过| C{白名单检查}
    B -->|失败| D[抛出验证错误]
    C -->|通过| E[继续处理]
    C -->|失败| F[拒绝请求]

验证规则包括：

• 必须符合 npm 包命名规范（ scoped 包支持 @scope/name 格式）
• 不允许包含路径遍历字符（如 ../）
• 不允许包含协议前缀（如 https://）
• 长度限制在 214 字符以内

资料来源：src/validators/package-name-validator.ts:1-50 资料来源：v1.16.0 Release

数据获取与处理

npm Registry 数据获取

npm-registry 工具通过 HTTP 请求从 npm Registry API 获取包元数据：

sequenceDiagram
    participant Client as MCP Client
    participant Tool as npm-registry 工具
    participant Cache as 缓存服务
    participant API as npm Registry API
    
    Client->>Tool: 请求包信息
    Tool->>Cache: 查询缓存
    Cache-->>Tool: 缓存未命中
    Tool->>API: GET /package/{name}
    API-->>Tool: 包元数据 JSON
    Tool->>Tool: Zod Schema 验证
    Tool->>Cache: 存储结果
    Tool-->>Client: 返回包详情

API 端点：https://registry.npmjs.org/{packageName}

资料来源：src/tools/npm-registry.ts:50-100

依赖树解析 (npm-deps)

npm-deps 工具提供依赖树解析功能，整合了 npm Registry 和 deps.dev 两个数据源：

graph TD
    A[请求包名称] --> B[查询 npm Registry]
    B --> C[获取直接依赖列表]
    C --> D{deps.dev 集成}
    D -->|v1.17.0+| E[查询 deps.dev API]
    E --> F[获取传递依赖拓扑]
    F --> G[注入传递依赖洞察]
    G --> H[构建增强依赖树]
    D -->|无 deps.dev| I[使用基础依赖信息]
    I --> H
    H --> J[返回完整依赖结构]

v1.17.0 和 v1.18.0 版本增强了与 deps.dev 的集成：

• v1.17.0：集成 deps.dev 突破漏洞扫描中的边缘子请求限制
• v1.18.0：将传递依赖拓扑洞察注入到 npmDeps 结果中

资料来源：src/tools/npm-deps.ts:1-80 资料来源：src/services/deps-dev-service.ts:1-60 资料来源：v1.17.0 Release 资料来源：v1.18.0 Release

漏洞扫描处理 (vulnerability-scan)

vulnerability-scan 工具整合了漏洞检测、React 生态感知和 CVE 丰富化功能：

graph TD
    A[目标包列表] --> B[获取依赖树]
    B --> C[查询 npm Registry 漏洞数据]
    C --> D[查询 deps.dev 漏洞 API]
    D --> E[合并漏洞信息]
    E --> F[CVE 数据丰富化]
    F --> G[React 生态标记]
    G --> H[生成漏洞报告]
    H --> I{是否包含传递依赖}
    I -->|是| J[递归扫描传递依赖]
    J --> K[汇总所有漏洞]
    I -->|否| L[返回单层报告]
    K --> L

处理特性（v1.14.0+）：

• 传递依赖扫描 - 检测间接依赖中的漏洞
• React 生态系统感知 - 识别 React 相关包的特殊漏洞
• CVE 数据丰富化 - 提供详细的 CVE 编号和严重程度

资料来源：src/tools/vulnerability-scan.ts:1-120 资料来源：v1.14.0 Release

缓存服务

缓存架构

项目实现了健壮的缓存机制以提高响应速度并减少 API 调用：

graph TD
    subgraph "缓存层"
        A[内存缓存]
        B[持久化缓存]
    end
    
    subgraph "缓存键"
        C[包名称]
        D[版本号]
        E[工具类型]
        F[请求参数]
    end
    
    subgraph "缓存策略"
        G[TTL 过期]
        H[手动失效]
        I[版本更新检测]
    end
    
    C --> J[缓存键生成]
    D --> J
    E --> J
    F --> J
    J --> K{缓存查找}
    K -->|命中| L[返回缓存数据]
    K -->|未命中| M[获取新数据]
    M --> N[写入缓存]
    N --> L
    G --> O[后台清理]
    H --> O
    I --> O

缓存失效机制

v1.15.0 版本实现了健壮的缓存失效机制：

资料来源：src/services/cache-service.ts:1-100 资料来源：v1.15.0 Release

缓存数据结构

interface CacheEntry<T> {
  key: string;
  value: T;
  createdAt: number;
  expiresAt: number;
  metadata: {
    packageName: string;
    version?: string;
    tool: 'npm-registry' | 'npm-deps' | 'vulnerability-scan';
  };
}

资料来源：src/services/cache-service.ts:30-45

错误处理

验证错误

参数验证失败时，系统返回结构化的错误信息：

interface ValidationError {
  code: 'VALIDATION_ERROR';
  details: {
    field: string;
    message: string;
    received: unknown;
  }[];
}

API 错误

外部 API 调用失败时，根据错误类型采取不同策略：

资料来源：src/tools/npm-registry.ts:100-150

数据流时序

完整请求处理时序

sequenceDiagram
    participant User as 用户
    participant MCP as MCP Server
    participant Val as 验证器
    participant Cache as 缓存服务
    participant npmAPI as npm Registry
    participant depsDev as deps.dev
    participant Trans as 数据转换器
    
    User->>MCP: 工具调用请求
    MCP->>Val: 验证参数
    Val-->>MCP: 验证通过
    MCP->>Cache: 检查缓存
    Cache-->>MCP: 缓存命中
    MCP-->>User: 返回缓存结果
    
    Note over User,Cache: 缓存未命中场景
    
    User->>MCP: 工具调用请求
    MCP->>Val: 验证参数
    Val-->>MCP: 验证通过
    MCP->>Cache: 检查缓存
    Cache-->>MCP: 缓存未命中
    MCP->>npmAPI: 请求 npm 数据
    npmAPI-->>MCP: 返回原始数据
    MCP->>depsDev: 查询依赖拓扑
    depsDev-->>MCP: 返回拓扑数据
    MCP->>Trans: 合并转换数据
    Trans-->>MCP: 处理后数据
    MCP->>Cache: 存储结果
    MCP-->>User: 返回最终结果

配置参数

环境变量配置

资料来源：package.json

Zod 验证配置

const configSchema = z.object({
  npmRegistryUrl: z.string().url().optional(),
  depsDevUrl: z.string().url().optional(),
  cacheEnabled: z.boolean().default(true),
  maxCacheAge: z.number().positive().default(3600),
});

资料来源：src/index.ts:80-95

常见故障模式

1. 缓存数据不一致

症状：返回的包信息与 npm Registry 实际数据不一致

原因：

• 缓存 TTL 设置过长
• 包版本更新后缓存未及时失效

解决方案：

• 缩短缓存 TTL
• 使用手动失效 API 清除缓存
• 启用版本检测自动失效

2. 依赖解析超时

症状：npm-deps 工具调用超时

原因：

• 依赖树过深过大
• deps.dev API 响应延迟
• 网络连接不稳定

解决方案：

• 增加 HTTP_TIMEOUT_MS 配置
• 启用缓存避免重复请求
• 检查网络连接状态

3. 验证错误

症状：VALIDATION_ERROR 返回

原因：

• 包名称格式不符合规范
• Zod Schema 验证失败
• 参数类型不匹配

解决方案：

• 检查包名称是否符合 npm 命名规范
• 确保参数类型正确
• 参考工具 Schema 定义

4. deps.dev 集成失败

症状：漏洞扫描结果不完整

原因：

• deps.dev API 不可用
• API 速率限制
• 网络问题

解决方案：

• 降级到仅使用 npm Registry 数据
• 实现本地缓存减少 API 调用
• 监控 API 可用性状态

资料来源：v1.17.0 Release

性能优化建议

1. 合理配置缓存 TTL：根据包更新频率调整缓存时间
2. 批量请求优化：合并多个包请求减少 API 调用
3. 连接复用：使用 HTTP Keep-Alive 减少连接开销
4. 异步处理：非关键路径数据采用异步获取
5. 本地镜像：高频访问的包使用本地镜像缓存

概述

npm-sentinel-mcp 的安全扫描功能是一个全面的漏洞检测系统，专门用于分析 npm 包及其依赖树中的安全威胁。该功能通过集成 deps.dev API 获取大规模依赖拓扑信息，实现了对传递依赖的深度扫描能力。安全扫描功能旨在帮助开发者在项目早期发现潜在的安全漏洞，从而采取预防措施。

核心架构

安全扫描功能采用多层次的架构设计，结合本地缓存、远程 API 查询和智能分析引擎。以下架构图展示了整体数据流动和处理流程：

graph TD
    A[用户请求扫描] --> B{缓存检查}
    B -->|命中| C[返回缓存结果]
    B -->|未命中| D[包名验证]
    D --> E{deps.dev API}
    E -->|传递拓扑| F[依赖树解析]
    F --> G[CVE 数据富化]
    G --> H[漏洞分析引擎]
    H --> I[生成报告]
    I --> J[写入缓存]
    J --> K[返回扫描结果]

组件说明

传递依赖扫描

传递依赖扫描是安全扫描功能的核心特性之一。在 v1.14.0 版本中，该功能得到显著增强，引入了对 React 生态系统的特殊感知能力，并实现了 CVE 数据富化功能。

依赖解析流程

graph LR
    A[直接依赖] --> B[一级依赖]
    B --> C[传递依赖]
    C --> D[深层传递]
    D --> E[边界依赖]
    E -->|子请求限制| F[deps.dev 批量获取]
    F --> G[完整拓扑视图]

传递依赖扫描通过以下步骤实现：

1. 直接依赖分析：解析用户项目的 package.json 中的直接依赖
2. 拓扑构建：通过 deps.dev API 获取完整的依赖树拓扑结构
3. 漏洞匹配：将依赖版本与已知 CVE 数据库进行匹配
4. 影响评估：分析漏洞对项目的实际影响程度

deps.dev 集成

v1.17.0 版本集成了 deps.dev 服务，这一集成解决了传统漏洞扫描中边缘子请求限制的问题。通过 deps.dev，可以一次性获取大规模的依赖树信息，显著提升了扫描效率和完整性。

资料来源：v1.17.0 Release Notes

缓存失效机制

v1.15.0 版本实现了强大的缓存失效机制，确保扫描结果能够及时反映最新的安全情报。该机制采用多层策略来平衡性能和准确性。

缓存策略

失效检测流程

缓存失效机制通过监听外部变化和内部定时检查相结合的方式运作。当检测到依赖包版本更新或 CVE 数据库变化时，系统会自动标记相关缓存条目为失效状态，并在下次请求时触发重新扫描。

资料来源：v1.15.0 Release Notes

包名安全验证

v1.16.0 版本引入了严格的包名验证机制，这是防御供应链攻击的第一道防线。所有工具入口都强制执行包名格式验证，确保输入的包名符合 npm 官方规范。

验证规则

包名验证遵循以下规则：

• 必须以字母或数字开头
• 只能包含小写字母、数字、连字符和下划线
• 不能超过 214 个字符
• 不能以点或下划线开头或结尾
• scoped 包必须遵循 @scope/package 格式

graph TD
    A[输入包名] --> B{格式验证}
    B -->|通过| C{长度检查}
    C -->|通过| D{字符验证}
    D -->|通过| E[放行]
    B -->|失败| F[拒绝并报错]
    C -->|失败| F
    D -->|失败| F

安全意义

严格的包名验证可以有效防止以下攻击向量：

• 依赖混淆攻击：通过注册与合法包名相似的恶意包
• typosquatting：利用常见的拼写错误诱骗开发者安装恶意包
• 命令注入：通过特殊字符在脚本执行时注入恶意命令

资料来源：v1.16.0 Release Notes

React 生态系统感知

v1.14.0 版本增强了 React 生态系统的安全扫描能力。由于 React 生态系统的高度模块化和复杂的依赖关系，传统的扫描方法往往无法完整覆盖所有潜在风险。

特殊处理机制

React 生态系统感知功能会识别项目中使用的 React 相关包，并针对这些包应用额外的安全检查规则，确保扫描结果的全面性和准确性。

资料来源：v1.14.0 Release Notes

CVE 富化

CVE 富化功能为扫描结果提供更详细的漏洞上下文信息，帮助开发者更好地理解和评估安全风险。

富化数据类型

输出示例

扫描结果中的 CVE 富化数据通常包含以下结构化信息：

{
  "cveId": "CVE-2024-XXXXX",
  "severity": "HIGH",
  "cvssScore": 7.5,
  "affectedVersions": "<1.2.3",
  "fixedVersion": "1.2.3",
  "description": "详细漏洞描述",
  "references": ["链接1", "链接2"]
}

v1.18.0 新特性

v1.18.0 版本进一步增强了传递依赖拓扑洞察能力，通过将 deps.dev 的拓扑信息注入到依赖扫描结果中，提供了更清晰的依赖关系可视化。

新增功能

• 传递路径追踪：显示漏洞包到直接依赖的完整路径
• 影响范围评估：基于拓扑结构计算漏洞的实际影响范围
• 优先排序优化：根据传递依赖层级调整漏洞修复优先级

资料来源：v1.18.0 Release Notes

使用方式

基本扫描

安全扫描功能通过 MCP 工具接口调用，核心工具为 npmVulnScan。该工具接受包名和版本参数，返回完整的漏洞分析报告。

输入参数

输出结构

扫描结果包含以下关键部分：

• summary：扫描摘要，包括总依赖数和发现漏洞数
• vulnerabilities：详细漏洞列表，按严重程度排序
• dependencyPath：完整的依赖路径信息
• recommendations：修复建议和优先级

配置选项

安全扫描功能支持多种配置选项，可通过项目配置文件进行定制。

常见问题与限制

性能考虑

大规模项目的完整传递依赖扫描可能耗时较长，建议：

• 启用缓存以加速重复扫描
• 使用 severityThreshold 过滤低风险漏洞
• 定期执行完整扫描，而非每次构建都执行

API 限制

deps.dev API 存在速率限制，在扫描大量包时可能遇到节流。建议：

• 实现重试逻辑处理 429 错误
• 使用缓存减少重复 API 调用
• 考虑批量请求优化

数据准确性

漏洞检测的准确性依赖于：

• CVE 数据库的及时更新
• 包版本信息的准确性
• 依赖解析的完整性

建议定期更新项目依赖并重新执行扫描，以获取最新的安全评估。

另请参阅

• 项目主页 - 完整项目文档
• 安全策略 - 安全漏洞报告指南
• 快速开始 - 快速上手教程
• 工具参考 - MCP 工具完整列表

功能概述

npm-sentinel-mcp 的依赖分析模块（npmDeps）为核心工具，提供以下主要功能：

资料来源：README.md:1-50

架构设计

整体架构

依赖分析模块采用分层架构设计，核心组件包括 MCP 协议层、服务层和外部 API 集成层。

graph TD
    A[MCP 客户端] --> B[npmDeps 工具]
    B --> C[依赖解析服务]
    C --> D[npm Registry API]
    C --> E[deps.dev API]
    C --> F[OSV API]
    G[缓存层] --> C
    F --> G

核心服务组件

资料来源：llms.txt

依赖解析流程

解析策略

依赖解析采用双重数据源策略，确保获取完整的依赖信息：

graph LR
    A[请求包名] --> B{首选数据源}
    B -->|deps.dev| C[deps.dev API]
    B -->|fallback| D[npm Registry]
    C --> E[传递依赖拓扑]
    D --> F[基础依赖信息]
    E --> G[结果聚合]
    F --> G

1. deps.dev API (首选)：提供完整的传递依赖拓扑结构，支持大规模依赖树解析
2. npm Registry (备用)：提供基础的依赖元数据

资料来源：src/services/depsDev.ts

传递依赖分析

从 v1.17.0 版本开始，系统集成了 deps.dev 用于绕过传统漏洞扫描中的边缘子请求限制：

mcp: integrate deps.dev for massive dependency tree resolution bypassing edge subrequest limits in vulnerability scans

传递依赖分析包括：

资料来源：src/tools/npmDeps.ts

漏洞扫描集成

扫描能力

从 v1.14.0 版本起，漏洞检测得到显著增强：

• 传递扫描：不仅扫描直接依赖，还扫描传递依赖
• React 生态感知：对 React 生态系统有特殊识别能力
• CVE 丰富：漏洞情报增强，提供更详细的漏洞信息

OSV 集成

漏洞数据来源于 OSV (Open Source Vulnerabilities) 数据库，系统通过 API 查询获取实时漏洞情报。

缓存机制

缓存策略

从 v1.15.0 版本起，实现了健壮的缓存失效机制：

graph TD
    A[API 请求] --> B{缓存命中?}
    B -->|是| C[检查缓存有效性]
    C -->|有效| D[返回缓存数据]
    C -->|过期| E[重新获取]
    B -->|否| E
    E --> F[更新缓存]
    F --> D

缓存失效策略

资料来源：src/services/cache.ts

使用方法

基本调用

通过 MCP 协议调用 npmDeps 工具进行依赖分析：

{
  "name": "npmDeps",
  "arguments": {
    "packageName": "react",
    "version": "18.2.0"
  }
}

参数说明

安全特性

包名验证

从 v1.16.0 版本起，所有工具都强制执行严格的包名验证：

security: enforce strict package name validation across all tools

这确保了：

• 防止包名混淆攻击
• 验证包的合法性
• 阻止潜在恶意输入

资料来源：src/tools/npmDeps.ts

版本历史

资料来源：社区发布记录

常见问题

依赖解析失败

如果依赖解析失败，可能原因包括：

1. 网络问题：无法访问 npm Registry 或 deps.dev
2. 包不存在：指定的包名或版本不存在
3. 私有包：私有 registry 中的包需要额外配置

缓存相关

• 缓存数据存储在本地文件系统
• 缓存键基于包名、版本和请求参数生成
• 长时间不使用的缓存会被自动清理

另请参阅

• 快速开始指南 - 如何配置和使用 npm-sentinel-mcp
• 工具参考 - 所有可用 MCP 工具详细说明
• 配置参考 - 完整的配置选项说明
• 故障排除 - 常见问题解决方案

概述

npm-sentinel-mcp 工具集为开发者提供了以下核心功能模块：

资料来源：llms-full.txt

架构设计

整体架构

graph TD
    A[客户端/MCP Host] --> B[npm-sentinel-mcp Server]
    B --> C[工具路由层]
    C --> D[npmDeps]
    C --> E[npmVuln]
    C --> F[npmSearch]
    C --> G[npmInfo]
    D --> H[npm Registry API]
    D --> I[deps.dev API]
    E --> H
    E --> I
    E --> J[漏洞数据库]
    F --> H
    G --> H
    H --> K[缓存层]
    I --> K
    J --> K
    K --> L[响应格式化]
    L --> A

工具层设计

graph TD
    A[工具调用请求] --> B{工具类型判定}
    B -->|npmDeps| C[依赖解析器]
    B -->|npmVuln| D[漏洞扫描器]
    B -->|npmSearch| E[搜索处理器]
    B -->|npmInfo| F[信息检索器]
    
    C --> G[包名验证]
    D --> G
    E --> G
    F --> G
    
    G --> H[Zod Schema 校验]
    H -->|验证失败| I[返回错误]
    H -->|验证成功| J[执行逻辑]
    
    J --> K[缓存查询]
    K -->|命中| L[返回缓存数据]
    K -->|未命中| M[调用外部 API]
    M --> N[缓存写入]
    N --> L

核心工具详解

npmDeps - 依赖信息查询

npmDeps 工具提供 npm 包的依赖树解析能力，支持递归获取直接依赖和传递依赖信息。

#### 功能特性

• 直接依赖解析：获取指定包的所有直接依赖项
• 传递依赖分析：递归解析完整的依赖树
• deps.dev 集成：通过 deps.dev API 获取大规模依赖树，绕过 npm Registry 的边缘子请求限制
• 转译拓扑洞察：从 v1.18.0 开始，注入传递拓扑洞察信息

资料来源：llms-full.txt

#### 输入参数

#### 输出数据结构

interface NpmDepsResponse {
  name: string;
  version: string;
  dependencies: {
    name: string;
    version: string;
    dependencies?: RecursiveDeps[];
  }[];
  transitiveInsights?: {
    totalPackages: number;
    depth: number;
    criticalPaths: string[];
  };
}

npmVuln - 漏洞扫描

npmVuln 工具提供企业级的安全漏洞检测能力，支持传递依赖扫描和 CVE 丰富。

#### 功能特性

• 传递依赖扫描：从 v1.14.0 开始，支持扫描传递依赖中的漏洞
• CVE 丰富：增强漏洞数据，包含 CVE 标识符和严重等级
• React 生态系统感知：从 v1.14.0 开始，识别 React 生态中的特殊漏洞模式
• deps.dev 集成：绕过子请求限制，实现大规模依赖树扫描

资料来源：v1.14.0 Release Notes

#### 漏洞检测流程

graph LR
    A[输入包名] --> B[解析依赖树]
    B --> C[deps.dev 批量查询]
    C --> D[获取包版本信息]
    D --> E[匹配漏洞数据库]
    E --> F{CVE 匹配}
    F -->|匹配成功| G[CVE 丰富处理]
    F -->|无匹配| H[继续扫描]
    G --> I[生成漏洞报告]
    H --> I
    I --> J[缓存扫描结果]

#### 输出数据结构

interface NpmVulnResponse {
  packageName: string;
  version: string;
  vulnerabilities: {
    id: string;
    severity: 'critical' | 'high' | 'medium' | 'low';
    cve?: string;
    title: string;
    url: string;
    affectedVersions: string;
    recommendation?: string;
  }[];
  summary: {
    total: number;
    critical: number;
    high: number;
    medium: number;
    low: number;
  };
}

npmSearch - 包搜索

npmSearch 工具提供 npm Registry 的搜索能力，帮助用户发现和评估 npm 包。

#### 功能特性

• 支持按关键字搜索 npm 包
• 返回相关度排序的搜索结果
• 包含包的元数据摘要

#### 输入参数

npmInfo - 包元数据

npmInfo 工具提供 npm 包的详细信息检索，包括版本历史、维护状态和包描述。

#### 功能特性

• 获取包的基本信息
• 列出所有可用版本
• 返回维护者信息
• 识别包的发布状态

安全机制

包名验证

从 v1.16.0 开始，npm-sentinel-mcp 在所有工具中强制执行严格的包名验证。

// 包名验证规则
const packageNameRegex = /^(?:@[a-z0-9-*~][a-z0-9-*._~]*\/)?[a-z0-9-~][a-z0-9-._~]*$/;

验证失败时返回以下错误：

资料来源：v1.16.0 Release Notes

缓存机制

npm-sentinel-mcp 实现了健壮的缓存失效机制。

#### 缓存策略

#### 缓存失效机制

从 v1.15.0 开始，实现了一套完整的缓存失效机制：

1. 基于时间的自动失效：每条缓存记录带有 TTL 标记
2. 事件驱动的主动失效：当检测到包版本更新时，失效相关缓存
3. 手动失效接口：提供管理接口强制失效特定缓存

资料来源：v1.15.0 Release Notes

外部服务集成

npm Registry API

npm-sentinel-mcp 使用 npm Registry 的官方 API 端点：

deps.dev API

从 v1.17.0 开始，集成 deps.dev API 解决大规模依赖树解析问题：

• 批量查询：一次请求获取多个包的依赖信息
• 绕过子请求限制：避免 npm Registry 的边缘子请求限制
• 传递拓扑分析：获取完整的依赖传递关系图

graph TD
    A[请求依赖树] --> B{规模判定}
    B -->|小规模 < 50 包| C[npm Registry]
    B -->|大规模 >= 50 包| D[deps.dev API]
    C --> E[单次查询]
    D --> F[批量查询]
    E --> G[合并结果]
    F --> G
    G --> H[注入拓扑洞察]
    H --> I[返回完整依赖信息]

资料来源：v1.17.0 Release Notes

配置选项

工具配置

环境变量

# 可选：使用自定义 npm Registry
NPM_REGISTRY_URL=https://registry.npmmirror.com

# 可选：设置缓存目录
NPM_SENTINEL_CACHE_DIR=/tmp/npm-sentinel-cache

# 可选：禁用缓存
NPM_SENTINEL_CACHE_ENABLED=false

使用示例

基本使用

// 使用 MCP SDK 调用 npmDeps 工具
const depsResult = await mcpClient.callTool('npmDeps', {
  packageName: 'express',
  recursive: true
});

// 使用 npmVuln 工具扫描漏洞
const vulnResult = await mcpClient.callTool('npmVuln', {
  packageName: 'react',
  version: '18.2.0'
});

批量扫描

// 扫描多个包的漏洞
const packages = ['lodash', 'axios', 'moment'];

for (const pkg of packages) {
  const result = await mcpClient.callTool('npmVuln', {
    packageName: pkg
  });
  
  if (result.vulnerabilities.length > 0) {
    console.log(`发现 ${result.vulnerabilities.length} 个漏洞`);
  }
}

常见问题与故障排除

常见错误

性能问题

测试问题修复

在 v1.16.1 中修复了 Zod 验证错误问题：

• 解决了 npm-registry.test.ts 中的 Zod 验证错误
• 清理了过时的测试用例

资料来源：v1.16.1 Release Notes

版本历史

See Also

• 项目主页 - 完整的项目介绍和快速开始指南
• 安装指南 - MCP Server 安装和配置
• API 参考 - 完整的工具 API 文档
• 开发指南 - 本地开发和测试说明

概述

npm-sentinel-mcp 的配置系统采用声明式架构，支持通过环境变量和配置文件两种方式进行参数管理。配置选项涵盖以下核心领域：

• 安全验证：包名格式验证、恶意包检测
• 漏洞扫描： transitive 依赖扫描、CVE 数据丰富
• 缓存管理：依赖解析缓存、缓存失效机制
• 外部集成：deps.dev API 集成、npm Registry 访问

资料来源：README.md:1-50

配置架构

配置层级结构

graph TD
    A[npm-sentinel-mcp 配置] --> B[环境变量配置]
    A --> C[smithery.yaml 配置]
    A --> D[server.json 配置]
    
    B --> E[MCP 服务器启动参数]
    C --> F[Smithery 平台配置]
    D --> G[MCP 协议配置]
    
    E --> H[运行时配置]
    F --> H
    G --> H
    
    H --> I[安全验证模块]
    H --> J[漏洞扫描模块]
    H --> K[依赖解析模块]
    H --> L[缓存管理模块]

配置文件位置

资料来源：smithery.yaml

Smithery 平台配置

s smithery.yaml 文件定义了 Smithery AI 平台发现和配置 npm-sentinel-mcp 服务器所需的关键参数。

配置 Schema

name: npm-sentinel-mcp
description: MCP server for npm security monitoring, vulnerability scanning and dependency analysis
configSchema:
  type: object
  properties:
    npmRegistryUrl:
      type: string
      description: NPM Registry URL
      default: https://registry.npmjs.org
    enableTransitiveScanning:
      type: boolean
      description: Enable transitive dependency vulnerability scanning
      default: true
    cacheDuration:
      type: number
      description: Cache duration in seconds
      default: 3600
  required: []

核心配置字段

资料来源：smithery.yaml

安全验证配置

包名验证 (v1.16.0+)

从 v1.16.0 版本开始，项目实施了严格的包名验证机制，防止恶意包名攻击。

graph LR
    A[输入包名] --> B[格式验证]
    B --> C{验证通过?}
    C -->|是| D[安全包名]
    C -->|否| E[抛出 ValidationError]
    
    F[安全验证规则] --> B
    F --> G[长度检查: 1-214 字符]
    F --> H[字符集检查: 小写字母、数字、连字符、下划线、点号]
    F --> I[作用域检查: @scope/name 格式]

验证规则详解

资料来源：smithery.yaml

漏洞扫描配置

Transitive 依赖扫描

v1.14.0 版本增强了漏洞检测功能，支持 transitive 依赖扫描和 React 生态系统感知。

graph TD
    A[扫描请求] --> B[获取直接依赖]
    B --> C[解析依赖树]
    C --> D[查询 deps.dev API]
    D --> E{启用 transitive 扫描?}
    E -->|是| F[递归获取 transitive 依赖]
    E -->|否| G[仅扫描直接依赖]
    F --> H[CVE 数据丰富]
    G --> H
    H --> I[生成漏洞报告]

扫描配置参数

资料来源：README.md

deps.dev 集成配置

API 集成特性 (v1.17.0+)

v1.17.0 版本集成了 deps.dev API，用于大规模依赖树解析，绕过 npm Registry 的请求限制。

graph TD
    A[npmDeps 工具调用] --> B[请求 deps.dev API]
    B --> C[获取完整依赖拓扑]
    C --> D[注入 transitive insights]
    D --> E[返回 enriched 依赖信息]
    
    F[deps.dev 缓存] --> B
    G[本地缓存] --> D

依赖拓扑洞察

资料来源：smithery.yaml

缓存管理配置

缓存失效机制 (v1.15.0+)

v1.15.0 版本实现了健壮的缓存失效机制，确保数据新鲜度。

graph LR
    A[缓存条目] --> B{过期检查}
    B --> C{是否过期?}
    C -->|是| D[重新获取数据]
    C -->|否| E[返回缓存数据]
    D --> F[更新缓存]
    F --> E

缓存配置参数

资料来源：smithery.yaml

MCP 协议配置

server.json 配置结构

{
  "mcp": {
    "server": {
      "name": "npm-sentinel-mcp",
      "version": "1.18.0"
    },
    "capabilities": {
      "tools": true,
      "resources": true
    }
  }
}

协议能力配置

资料来源：server.json

环境变量配置

运行时环境变量

资料来源：package.json

配置示例

最小配置

# smithery.yaml - 最小配置示例
name: npm-sentinel-mcp
description: MCP server for npm security monitoring

完整配置

# smithery.yaml - 完整配置示例
name: npm-sentinel-mcp
description: MCP server for npm security monitoring, vulnerability scanning and dependency analysis
configSchema:
  type: object
  properties:
    npmRegistryUrl:
      type: string
      description: NPM Registry URL
      default: https://registry.npmjs.org
    enableTransitiveScanning:
      type: boolean
      description: Enable transitive dependency vulnerability scanning
      default: true
    cacheDuration:
      type: number
      description: Cache duration in seconds
      default: 3600
  required: []

环境变量配置

# 设置自定义 NPM Registry
export NPM_REGISTRY_URL=https://registry.npmmirror.com

# 设置缓存有效期为 2 小时
export CACHE_DURATION=7200

# 启用调试日志
export LOG_LEVEL=debug

常见配置问题

问题诊断

验证配置

# 检查配置是否正确加载
npm run test

# 验证 smithery.yaml 格式
npm run validate:config

版本历史

资料来源：社区发布记录

相关页面

• 快速开始指南 - 项目入门
• API 参考 - 工具调用接口
• 安全说明 - 安全机制详解
• 故障排除 - 常见问题解答

项目概述

npm-sentinel-mcp 是一个基于 Model Context Protocol (MCP) 的服务器，专为 npm 生态系统提供全面的安全扫描和依赖分析能力。该项目集成了多个数据源，包括 npm Registry、deps.dev 和 OSV 漏洞数据库，能够执行传递依赖分析、漏洞扫描和 CVE 富化等高级功能。

项目当前版本为 v1.18.0，支持 Node.js 20 及以上版本，并提供 Docker 容器化部署和 Smithery 平台集成两种主流部署方式。资料来源：README.md:1-50

系统要求

运行环境

网络依赖

npm-sentinel-mcp 在运行过程中需要访问以下外部服务：

• npm Registry (registry.npmjs.org)：获取 npm 包元数据和依赖信息
• deps.dev API (api.deps.dev)：获取传递依赖拓扑信息
• OSV 漏洞数据库 (osv.dev)：查询安全漏洞数据

部署时需确保服务器能够访问这些端点，部分企业环境可能需要配置代理或防火墙规则。

资料来源：README.md:1-30

安装部署方式

方式一：npm 全局安装

这是最简单的部署方式，适合本地开发环境和单用户场景。

# 安装最新稳定版本
npm install -g npm-sentinel-mcp

# 验证安装
npm-sentinel-mcp --version

安装完成后，CLI 工具将全局可用。该方式会自动配置必要的符号链接和执行权限。

资料来源：package.json:1-30

方式二：Docker 容器部署

对于生产环境和容器化基础设施，Docker 部署提供了更好的隔离性和可移植性。

#### 构建镜像

# 从源码构建
git clone https://github.com/Nekzus/npm-sentinel-mcp.git
cd npm-sentinel-mcp
docker build -t npm-sentinel-mcp:latest .

#### 运行容器

# 基本运行
docker run -d \
  --name npm-sentinel \
  -p 3000:3000 \
  -v $(pwd)/config:/app/config \
  -v npm-sentinel-cache:/app/cache \
  npm-sentinel-mcp:latest

Docker 镜像基于 Node.js 20 官方镜像，包含所有运行时依赖，并预配置了工作目录和入口脚本。资料来源：Dockerfile:1-30

#### Docker Compose 配置

以下是一个完整的生产级 Docker Compose 配置示例：

version: '3.8'

services:
  npm-sentinel:
    image: npm-sentinel-mcp:latest
    container_name: npm-sentinel
    ports:
      - "3000:3000"
    volumes:
      - ./config:/app/config:ro
      - sentinel-cache:/app/.cache
    environment:
      - NODE_ENV=production
      - NPM_REGISTRY_URL=https://registry.npmjs.org
      - DEPS_DEV_API_URL=https://api.deps.dev
      - LOG_LEVEL=info
    restart: unless-stopped
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:3000/health"]
      interval: 30s
      timeout: 10s
      retries: 3

volumes:
  sentinel-cache:

资料来源：Dockerfile:1-50

方式三：Smithery 平台部署

Smithery 是一个专门为 AI 助手提供工具集成的平台，npm-sentinel-mcp 原生支持 Smithery 集成。

#### 自动部署

访问 Smithery 平台，搜索 npm-sentinel-mcp 并按照指引完成配置。Smithery 会自动处理 MCP 服务器的启动和 AI 助手的连接。

#### 手动配置

对于高级用户，可以手动配置 Smithery 连接：

# smithery.yaml
name: npm-sentinel-mcp
description: npm 依赖安全和漏洞扫描 MCP 服务器
version: 1.18.0
installCommand: npm install -g npm-sentinel-mcp
startCommand: npm-sentinel-mcp start

configSchema:
  type: object
  properties:
    npmRegistry:
      type: string
      default: https://registry.npmjs.org
    depsDevApi:
      type: string
      default: https://api.deps.dev
    cacheEnabled:
      type: boolean
      default: true
    cacheTtl:
      type: number
      default: 3600

资料来源：smithery.yaml:1-20

// smithery_server.json
{
  "serverInfo": {
    "name": "npm-sentinel-mcp",
    "version": "1.18.0"
  },
  "capabilities": [
    "npm_search",
    "npm_dependencies",
    "npm_vulnerabilities",
    "npm_metadata"
  ]
}

资料来源：smithery_server.json:1-15

配置指南

配置文件结构

项目支持多种配置方式，按优先级从高到低依次为：

1. 命令行参数：最高优先级，用于临时覆盖
2. 环境变量：适合容器化和 CI/CD 环境
3. 配置文件：适合持久化配置管理

环境变量配置

资料来源：README.md:50-100

配置文件示例

在项目根目录创建 config.json 或在配置目录中放置 default.json：

{
  "registry": {
    "npm": {
      "url": "https://registry.npmjs.org",
      "timeout": 30000,
      "retries": 3
    }
  },
  "depsDev": {
    "enabled": true,
    "apiUrl": "https://api.deps.dev",
    "timeout": 20000
  },
  "vulnerability": {
    "provider": "osv",
    "transitiveScanning": true,
    "cveEnrichment": true,
    "reactEcosystemAwareness": true
  },
  "cache": {
    "enabled": true,
    "ttl": 3600,
    "maxSize": "100mb",
    "directory": "/app/.cache"
  },
  "security": {
    "strictPackageNameValidation": true
  }
}

资料来源：package.json:1-50

包管理器配置

项目使用 .npmrc 文件管理 npm 包相关的配置：

registry=https://registry.npmjs.org/
@nekzus:registry=https://registry.npmjs.org/
save-exact=true
engine-strict=true

资料来源：.npmrc:1-10

部署架构

系统架构图

graph TD
    A[AI 助手 / MCP 客户端] --> B[npm-sentinel-mcp 服务器]
    B --> C{请求类型}
    C -->|包搜索| D[npm Registry API]
    C -->|依赖分析| E[deps.dev API]
    C -->|漏洞扫描| F[OSV API]
    C -->|元数据| G[npm Registry API]
    
    D --> H{缓存层}
    E --> H
    F --> H
    G --> H
    
    H --> I[本地缓存存储]
    
    D --> J[(npm Registry)]
    E --> K[(deps.dev)]
    F --> L[(OSV Database)]
    G --> J
    
    subgraph 传递依赖分析
    E --> M[依赖拓扑解析]
    M --> N[传递漏洞扫描]
    N --> F
    end

数据流处理

sequenceDiagram
    participant Client as MCP 客户端
    participant Server as Sentinel Server
    participant Cache as 缓存层
    participant External as 外部 API
    
    Client->>Server: 请求: scan-vulnerabilities(lodash)
    Server->>Cache: 检查缓存
    Cache-->>Server: 缓存未命中
    
    Server->>External: 请求依赖树 (deps.dev)
    External-->>Server: 传递依赖列表
    
    Server->>External: 并发查询漏洞 (OSV)
    External-->>Server: 漏洞报告
    
    Server->>Server: CVE 富化处理
    Server->>Cache: 写入缓存
    Server->>Client: 返回扫描结果

生产环境部署

高可用部署

对于生产环境，建议采用以下高可用架构：

graph LR
    A[负载均衡器] --> B[Server 1]
    A --> C[Server 2]
    A --> D[Server N]
    
    B -.-> E[(Redis 缓存)]
    C -.-> E
    D -.-> E
    
    E -.-> F[(共享存储)]
    
    B --> G[npm Registry]
    C --> G
    D --> G

性能调优参数

监控和日志

生产环境应配置适当的监控机制：

# 导出结构化日志
docker run -d \
  -e LOG_LEVEL=info \
  -e LOG_FORMAT=json \
  npm-sentinel-mcp:latest

日志输出格式兼容主流日志收集系统，便于集成 Prometheus、Grafana 等监控工具。

安全配置

包名称验证

v1.16.0 引入了严格的包名称验证机制，所有工具调用都会执行包名格式校验：

// 验证规则示例
const validPackageName = /^[a-zA-Z0-9][a-zA-Z0-9._-]*$/;

此功能可防止注入攻击和无效查询。资料来源：README.md:100-150

网络安全

• 使用 HTTPS 连接所有外部 API
• 配置防火墙规则限制暴露端口
• 敏感配置使用环境变量而非明文文件
• 生产环境启用日志审计

常见问题排查

部署失败排查

运行时问题

# 检查健康状态
curl http://localhost:3000/health

# 查看日志
docker logs npm-sentinel

# 清理缓存
npm-sentinel-mcp cache:clear

性能问题

• 首次调用慢：正常现象，需要预热缓存和建立连接
• 依赖解析超时：增加 REQUEST_TIMEOUT 或检查网络
• 内存占用过高：限制缓存大小或减少并发数

卸载

npm 卸载

# 卸载全局包
npm uninstall -g npm-sentinel-mcp

# 清理缓存
npm cache clean --force

Docker 清理

# 停止并删除容器
docker stop npm-sentinel && docker rm npm-sentinel

# 删除镜像
docker rmi npm-sentinel-mcp:latest

# 清理未使用资源
docker system prune -f

相关资源

• 项目主页 - GitHub 仓库
• 变更日志 - 版本历史
• 问题反馈 - Bug 报告和功能请求
• Smithery 集成 - AI 助手平台集成

See Also

• 安装指南 - 详细的安装步骤说明
• 配置参考 - 完整配置选项文档
• API 参考 - MCP 工具接口文档
• 架构设计 - 系统架构详解
• 故障排除 - 常见问题解决方案

概述

npm-sentinel-mcp 实现了一套多层次的缓存系统，旨在优化 npm registry 交互性能、减少网络请求次数，并加速依赖解析流程。该缓存机制贯穿于整个 MCP 服务器的工具调用链路，覆盖从 npm 包元数据查询到漏洞扫描的完整生命周期。

项目在 v1.15.0 版本中引入了健壮的缓存失效机制（commit: 2966672），标志着缓存系统从简单的数据存储升级为具有智能更新策略的自适应缓存管理方案。资料来源：cacheStrategy.ts

架构设计

缓存层级架构

graph TD
    A[MCP 工具调用] --> B{CacheManager}
    B --> C[内存缓存<br/>InMemoryCache]
    B --> D[TTL 缓存策略]
    B --> E[LRU 驱逐策略]
    
    C --> F[npm Registry 响应]
    C --> G[依赖关系图]
    C --> H[漏洞扫描结果]
    C --> I[deps.dev 数据]
    
    F --> J{缓存未命中?}
    J -->|是| K[发起网络请求]
    J -->|否| L[直接返回缓存]
    K --> M[更新缓存]
    M --> L

核心组件

内存缓存实现

InMemoryCache 核心机制

InMemoryCache 是项目的核心缓存组件，采用以下设计原则：

数据结构选择：使用 TypeScript Map 作为底层存储，利用其有序性和 O(1) 的查找性能。资料来源：InMemoryCache.ts:15-30

// 简化的缓存条目结构
interface CacheEntry<T> {
  value: T;
  timestamp: number;
  ttl: number;
  accessCount: number;
  lastAccessed: number;
}

LRU 驱逐策略：当缓存达到配置的最大容量时，系统自动驱逐最近最少使用的条目，确保内存使用保持在可控范围内。资料来源：InMemoryCache.ts:45-60

缓存失效机制

失效策略类型

v1.15.0 引入的缓存失效机制是系统可靠性的关键保障。资料来源：cacheInvalidation.ts

graph LR
    A[缓存条目] --> B{失效检查}
    B --> C[TTL 超时]
    B --> D[容量溢出]
    B --> E[手动失效]
    B --> F[版本更新触发]
    
    C --> G[标记为过期]
    D --> H[LRU 驱逐]
    E --> I[主动清除]
    F --> J[关联失效]

失效策略配置

依赖关系缓存

依赖解析缓存

依赖关系缓存是性能优化的关键环节，特别是对于包含大量传递依赖的项目。npm-sentinel-mcp 通过以下方式优化依赖解析：

npmDeps 工具缓存：依赖查询结果会被缓存，结合 deps.dev API 的拓扑数据注入（v1.18.0），显著提升大型依赖树的解析效率。资料来源：depsDev.ts

sequenceDiagram
    participant Client
    participant CacheManager
    participant npmRegistry
    participant DepsDevAPI
    
    Client->>CacheManager: 请求依赖解析
    CacheManager->>CacheManager: 检查内存缓存
    alt 缓存命中
        CacheManager-->>Client: 返回缓存数据
    else 缓存未命中
        CacheManager->>npmRegistry: 查询 npm registry
        npmRegistry-->>CacheManager: 返回直接依赖
        CacheManager->>DepsDevAPI: 查询传递依赖拓扑
        DepsDevAPI-->>CacheManager: 返回完整依赖图
        CacheManager->>CacheManager: 存储到缓存
        CacheManager-->>Client: 返回结果
    end

传递依赖拓扑注入

v1.17.0 集成了 deps.dev API 用于解决漏洞扫描中的边缘子请求限制问题，v1.18.0 进一步将传递依赖拓扑洞察注入到 npmDeps 结果中。这两层数据的组合大幅提升了依赖分析的完整性和准确性。资料来源：depsDev.ts:1-50

配置管理

缓存配置 Schema

缓存行为通过配置文件进行精细化控制，配置定义位于 schema.ts。资料来源：schema.ts

// 缓存相关配置选项
interface CacheConfig {
  enabled: boolean;                    // 是否启用缓存
  maxEntries: number;                  // 最大缓存条目数
  ttlMs: number;                       // 默认 TTL（毫秒）
  strategy: 'lru' | 'lfu' | 'fifo';   // 驱逐策略
  invalidationMode: 'auto' | 'manual'; // 失效模式
  debug: boolean;                      // 调试模式开关
}

环境变量配置

工具级缓存集成

MCP 工具缓存上下文

每个 MCP 工具在调用时自动获得缓存上下文，实现零配置的性能优化。资料来源：CacheManager.ts

graph TD
    subgraph MCP 工具层
        A[npmInfo]
        B[npmDeps]
        C[npmVulns]
        D[npmAudit]
    end
    
    subgraph 缓存管理层
        E[CacheManager 实例]
        F[缓存键生成器]
        G[策略选择器]
    end
    
    subgraph 存储层
        H[InMemoryCache]
        I[TTL 定时器]
        J[LRU 队列]
    end
    
    A --> E
    B --> E
    C --> E
    D --> E
    E --> F
    E --> G
    G --> H
    H --> I
    H --> J

各工具缓存策略

常见问题与故障排查

缓存相关问题

问题：缓存数据过期但仍在使用

• 原因：时钟不同步或系统休眠导致 TTL 定时器延迟
• 解决：检查 NTP 时间同步，确保证券环境时间准确

问题：内存缓存占用过高

• 原因：maxEntries 配置过大或缓存未及时释放
• 解决：调低 maxEntries，缩短 cleanupInterval 间隔

问题：deps.dev 数据与 npm 不一致

• 原因：deps.dev 数据更新存在延迟
• 解决：在 v1.17.0+ 版本中，工具会自动验证数据新鲜度，必要时触发重新获取

调试缓存行为

启用调试模式后，CacheManager 会输出详细的缓存操作日志：

NPM_SENTINEL_CACHE_DEBUG=true npm run start

调试日志格式示例：

[CACHE] HIT: npmDeps:lodash:4.17.21 (age: 45s)
[CACHE] MISS: npmDeps:react:18.2.0
[CACHE] STORE: npmDeps:react:18.2.0 (ttl: 21600s)
[CACHE] INVALIDATE: npmInfo:express:4.18.0 (manual)

性能优化建议

1. 合理设置 TTL：根据数据变化频率调整，对于稳定版本可延长 TTL
2. 监控内存使用：通过 maxEntries 控制缓存大小，避免 OOM
3. 使用版本感知的缓存键：确保同一包的不同版本有独立的缓存条目
4. 批量操作优化：多个包查询时利用缓存批量命中特性

参见

• 快速开始指南
• MCP 工具参考
• 安全扫描机制
• 依赖解析

Pitfall Log / 踩坑日志

项目：nekzus/npm-sentinel-mcp

摘要：发现 7 个潜在踩坑项，其中 0 个为 high/blocking；最高优先级：身份坑 - 仓库名和安装名不一致。

1. 身份坑 · 仓库名和安装名不一致

• 严重度：medium
• 证据强度：runtime_trace
• 发现：仓库名 npm-sentinel-mcp 与安装入口 @nekzus/mcp-server 不完全一致。
• 对用户的影响：用户照着仓库名搜索包或照着包名找仓库时容易走错入口。
• 建议检查：在 npm/PyPI/GitHub 上确认包名映射和官方 README 说明。
• 复现命令：npx @nekzus/mcp-server
• 防护动作：页面必须同时展示 repo 名和真实安装入口，避免用户搜索错包。
• 证据：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 | repo=npm-sentinel-mcp; install=@nekzus/mcp-server

2. 能力坑 · 能力判断依赖假设

• 严重度：medium
• 证据强度：source_linked
• 发现：README/documentation is current enough for a first validation pass.
• 对用户的影响：假设不成立时，用户拿不到承诺的能力。
• 建议检查：将假设转成下游验证清单。
• 防护动作：假设必须转成验证项；没有验证结果前不能写成事实。
• 证据：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 | README/documentation is current enough for a first validation pass.

3. 维护坑 · 维护活跃度未知

• 严重度：medium
• 证据强度：source_linked
• 发现：未记录 last_activity_observed。
• 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。
• 建议检查：补 GitHub 最近 commit、release、issue/PR 响应信号。
• 防护动作：维护活跃度未知时，推荐强度不能标为高信任。
• 证据：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 | last_activity_observed missing

4. 安全/权限坑 · 下游验证发现风险项

• 严重度：medium
• 证据强度：source_linked
• 发现：no_demo
• 对用户的影响：下游已经要求复核，不能在页面中弱化。
• 建议检查：进入安全/权限治理复核队列。
• 防护动作：下游风险存在时必须保持 review/recommendation 降级。
• 证据：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 | no_demo; severity=medium

5. 安全/权限坑 · 存在评分风险

• 严重度：medium
• 证据强度：source_linked
• 发现：no_demo
• 对用户的影响：风险会影响是否适合普通用户安装。
• 建议检查：把风险写入边界卡，并确认是否需要人工复核。
• 防护动作：评分风险必须进入边界卡，不能只作为内部分数。
• 证据：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 | no_demo; severity=medium

6. 维护坑 · issue/PR 响应质量未知

• 严重度：low
• 证据强度：source_linked
• 发现：issue_or_pr_quality=unknown。
• 对用户的影响：用户无法判断遇到问题后是否有人维护。
• 建议检查：抽样最近 issue/PR，判断是否长期无人处理。
• 防护动作：issue/PR 响应未知时，必须提示维护风险。
• 证据：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 | issue_or_pr_quality=unknown

7. 维护坑 · 发布节奏不明确

• 严重度：low
• 证据强度：source_linked
• 发现：release_recency=unknown。
• 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。
• 建议检查：确认最近 release/tag 和 README 安装命令是否一致。
• 防护动作：发布节奏未知或过期时，安装说明必须标注可能漂移。
• 证据：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 | release_recency=unknown