# https://github.com/Nekzus/npm-sentinel-mcp 项目说明书

生成时间：2026-05-30 19:06:23 UTC

## 目录

- [项目概述](#page-overview)
- [安装指南](#page-installation)
- [系统架构](#page-architecture)
- [数据流与处理](#page-data-flow)
- [安全扫描功能](#page-security)
- [依赖分析](#page-dependency-analysis)
- [包管理工具集](#page-package-tools)
- [配置选项](#page-configuration)
- [部署指南](#page-deployment)
- [缓存机制](#page-caching)

<a id='page-overview'></a>

## 项目概述

### 相关页面

相关主题：[安装指南](#page-installation), [系统架构](#page-architecture)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [README.md](https://github.com/Nekzus/npm-sentinel-mcp/blob/main/README.md)
- [package.json](https://github.com/Nekzus/npm-sentinel-mcp/blob/main/package.json)
- [src/index.ts](https://github.com/Nekzus/npm-sentinel-mcp/blob/main/src/index.ts)
- [src/tools/](https://github.com/Nekzus/npm-sentinel-mcp/tree/main/src/tools)
- [src/services/](https://github.com/Nekzus/npm-sentinel-mcp/tree/main/src/services)
- [smithery.yaml](https://github.com/Nekzus/npm-sentinel-mcp/blob/main/smithery.yaml)
- [tsconfig.json](https://github.com/Nekzus/npm-sentinel-mcp/blob/main/tsconfig.json)
</details>

# 项目概述

npm-sentinel-mcp 是一个基于 Model Context Protocol (MCP) 的智能 npm 包管理与安全分析服务器。该项目旨在为大型语言模型（LLM）代理提供可靠的 npm 依赖查询、漏洞扫描及安全审计能力，帮助开发者在代码生成和依赖管理场景中做出更安全的决策。

## 核心定位与价值

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

| 价值维度 | 描述 |
|---------|------|
| **安全增强** | 集成 transitive scanning（传递依赖扫描）能力，可检测直接依赖和传递依赖中的安全漏洞 |
| **生态感知** | 内置 React 生态系统感知能力，支持识别 React 组件库的安全特性 |
| **CVE 情报** | 自动关联 CVE 漏洞数据库，提供丰富的漏洞元数据 Enrichment |
| **高效解析** | 通过 deps.dev API 实现大规模依赖树解析，绕过传统 API 的请求限制 |

## 架构设计

### 整体架构

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

```mermaid
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
```

### 核心组件

| 组件路径 | 职责说明 |
|---------|---------|
| `src/index.ts` | MCP 服务器入口，负责协议初始化和工具注册 |
| `src/tools/` | 定义所有 MCP 工具的具体实现 |
| `src/services/` | 提供外部 API 调用和数据处理服务 |
| `smithery.yaml` | Smithery 平台集成配置 |

## 主要功能模块

### 依赖查询工具 (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 引入了健壮的缓存失效机制，确保数据的实时性和一致性：

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

## 配置与部署

### Smithery 集成

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

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

### 环境要求

| 要求项 | 规格 |
|-------|------|
| Node.js | >= 20.0.0 |
| 包管理器 | npm / pnpm / yarn |
| 平台支持 | Linux / macOS / Windows |

### 安装方式

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

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

## 版本历史亮点

| 版本 | 发布日期 | 关键特性 |
|------|---------|---------|
| v1.18.0 | 2026-02-22 | 传递依赖拓扑洞察注入 |
| v1.17.0 | 2026-02-22 | deps.dev 集成，突破请求限制 |
| v1.16.1 | 2026-02-15 | Zod 验证错误修复 |
| v1.16.0 | 2026-01-02 | 严格的包名验证 |
| v1.15.0 | 2025-12-30 | 缓存失效机制 |
| v1.14.0 | 2025-12-24 | 传递扫描、CVE 丰富化 |

## 技术栈

| 技术类别 | 选用技术 |
|---------|---------|
| 运行时 | Node.js |
| 语言 | TypeScript |
| 协议 | Model Context Protocol |
| 类型校验 | Zod |
| API 集成 | deps.dev, NPM Registry |
| 发布工具 | semantic-release |

## 适用场景

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/

## 参见

- [工具使用指南](./tools-usage.md) - 详细了解各 MCP 工具的使用方法
- [API 集成说明](./api-integration.md) - deps.dev 和 NPM Registry 集成详情
- [安全配置](./security-config.md) - 安全机制配置参考

---

<a id='page-installation'></a>

## 安装指南

### 相关页面

相关主题：[项目概述](#page-overview), [部署指南](#page-deployment)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [README.md](https://github.com/Nekzus/npm-sentinel-mcp/blob/main/README.md)
- [smithery.yaml](https://github.com/Nekzus/npm-sentinel-mcp/blob/main/smithery.yaml)
- [server.json](https://github.com/Nekzus/npm-sentinel-mcp/blob/main/server.json)
- [package.json](https://github.com/Nekzus/npm-sentinel-mcp/blob/main/package.json)
- [tsconfig.json](https://github.com/Nekzus/npm-sentinel-mcp/blob/main/tsconfig.json)
</details>

# 安装指南

本文档详细说明如何在各种环境中安装和配置 `npm-sentinel-mcp`。`npm-sentinel-mcp` 是一个基于 Model Context Protocol (MCP) 的 npm 包安全扫描工具，提供漏洞检测、依赖分析、CVE 丰富化等安全功能。资料来源：[README.md:1]()

## 系统要求

### 运行环境要求

| 组件 | 最低版本 | 推荐版本 | 说明 |
|------|----------|----------|------|
| Node.js | v20.0.0 | v20.x LTS | 项目使用现代 JavaScript 特性 |
| npm | v10.0.0 | v10.x | 用于包管理和脚本执行 |
| 操作系统 | macOS/Linux/Windows | - | 支持主流操作系统 |

> **注意**：v1.15.1 版本明确将 `semantic-release-github` 降级至 v10 以确保 Node.js 20 的兼容性。资料来源：[package.json](https://github.com/Nekzus/npm-sentinel-mcp/blob/main/package.json)()

### 网络要求

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

## 安装方法

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

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

```bash
npm install -g npm-sentinel-mcp
```

安装完成后，验证安装：

```bash
npx npm-sentinel-mcp --version
```

### 方法二：本地项目安装

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

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

### 方法三：直接从源码构建

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

```bash
# 克隆仓库
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` 支持两种主要运行模式：

| 模式 | 命令 | 用途 |
|------|------|------|
| STDIO 模式 | `npx npm-sentinel-mcp` | 与本地 MCP 客户端（如 Cursor、Claude Desktop）集成 |
| HTTP 模式 | `npx npm-sentinel-mcp --http` | 支持远程 MCP 客户端连接 |

```mermaid
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
```

### 初始化配置

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

```bash
npx npm-sentinel-mcp init
```

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

## Smithery 集成配置

对于使用 [Smithery](https://smithery.ai/) 平台的用户，项目提供了专门的配置文件。资料来源：[smithery.yaml](https://github.com/Nekzus/npm-sentinel-mcp/blob/main/smithery.yaml)()

### smithery.yaml 配置

```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](https://github.com/Nekzus/npm-sentinel-mcp/blob/main/smithery.yaml)()

### server.json 配置

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

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

## 环境变量配置

### 必需的环境变量

| 变量名 | 描述 | 默认值 | 必需 |
|--------|------|--------|------|
| `NPM_REGISTRY_URL` | npm Registry 镜像地址 | `https://registry.npmjs.org` | 否 |
| `NPM_TOKEN` | npm 认证令牌 | - | 仅私有包需要 |
| `DEPS_DEV_API_KEY` | deps.dev API 密钥 | - | 高频使用建议配置 |

### 可选的环境变量

| 变量名 | 描述 | 默认值 |
|--------|------|--------|
| `CACHE_TTL` | 缓存 TTL（秒） | 3600 |
| `LOG_LEVEL` | 日志级别 | `info` |
| `MAX_CONCURRENT_REQUESTS` | 最大并发请求数 | 5 |

配置示例：

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

## 验证安装

### 基本功能测试

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

### MCP 协议握手测试

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

```typescript
// 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);
```

运行测试：

```bash
npx tsx test-mcp.ts
```

### 可用工具列表

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

| 工具名称 | 功能描述 |
|----------|----------|
| `npmDeps` | 获取 npm 包的依赖关系 |
| `npmVulnScan` | 执行安全漏洞扫描 |
| `npmSearch` | 搜索 npm 包 |
| `npmInfo` | 获取包详细信息 |
| `npmVersions` | 获取包版本列表 |

## 常见问题与故障排除

### Node.js 版本不兼容

**症状**：启动时出现 `SyntaxError` 或 `ReferenceError`

**解决方案**：

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

### MCP 连接失败

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

**排查步骤**：

1. 检查服务器是否正常启动：
   ```bash
   npx npm-sentinel-mcp &
   ```

2. 验证 STDIO 连接配置正确：
   ```json
   {
     "mcpServers": {
       "npm-sentinel-mcp": {
         "command": "npx",
         "args": ["npm-sentinel-mcp"]
       }
     }
   }
   ```

### Zod 验证错误

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

```bash
npm update -g npm-sentinel-mcp
```

资料来源：[package.json](https://github.com/Nekzus/npm-sentinel-mcp/blob/main/package.json)()

### 缓存问题

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

```bash
# 清除全局缓存
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`：

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

### Cursor 配置

编辑 `~/.cursor/mcp.json`：

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

## 卸载

如需卸载 `npm-sentinel-mcp`：

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

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

## 相关资源

- [项目主页](https://github.com/Nekzus/npm-sentinel-mcp)
- [最新发布版本 (v1.18.0)](https://github.com/Nekzus/npm-sentinel-mcp/releases/tag/v1.18.0)
- [Smithery 集成页面](https://smithery.ai/server/npm-sentinel-mcp)
- [变更日志](./CHANGELOG.md)

## 另请参见

- [安全扫描功能说明](./security-scanning.md)
- [依赖分析功能](./dependency-analysis.md)
- [CVE 数据集成](./cve-integration.md)

---

<a id='page-architecture'></a>

## 系统架构

### 相关页面

相关主题：[数据流与处理](#page-data-flow), [项目概述](#page-overview)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [index.ts](https://github.com/Nekzus/npm-sentinel-mcp/blob/main/index.ts)
- [package.json](https://github.com/Nekzus/npm-sentinel-mcp/blob/main/package.json)
- [src/index.ts](https://github.com/Nekzus/npm-sentinel-mcp/blob/main/src/index.ts)
- [src/tools/npm-registry.ts](https://github.com/Nekzus/npm-sentinel-mcp/blob/main/src/tools/npm-registry.ts)
- [src/tools/vulnerability-scanner.ts](https://github.com/Nekzus/npm-sentinel-mcp/blob/main/src/tools/vulnerability-scanner.ts)
- [src/tools/package-name-validator.ts](https://github.com/Nekzus/npm-sentinel-mcp/blob/main/src/tools/package-name-validator.ts)
- [src/services/cache.service.ts](https://github.com/Nekzus/npm-sentinel-mcp/blob/main/src/services/cache.service.ts)
- [src/services/depsdev.service.ts](https://github.com/Nekzus/npm-sentinel-mcp/blob/main/src/services/depsdev.service.ts)
</details>

# 系统架构

npm-sentinel-mcp 是一个基于 Model Context Protocol (MCP) 的 npm 包管理安全工具，为 LLM 提供 npm 包注册表查询、依赖分析、漏洞扫描等能力。本页面详细说明该项目的系统架构、核心组件及其交互关系。

## 架构概述

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

```mermaid
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
```

架构分层说明：

| 层级 | 职责 | 核心组件 |
|------|------|----------|
| 表现层 | MCP 协议通信、请求路由 | MCP Server |
| 业务逻辑层 | 工具实现、业务规则处理 | Registry Tools, Scanner, Validator |
| 服务层 | 数据获取、缓存管理、外部 API 集成 | Cache, Deps.dev, NPM Registry |
| 基础设施层 | 文件 I/O、网络请求 | FileSystem, External APIs |

资料来源：[src/index.ts](https://github.com/Nekzus/npm-sentinel-mcp/blob/main/src/index.ts)

## 核心组件详解

### MCP 服务器

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

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

**服务器配置参数：**

| 参数 | 类型 | 说明 | 默认值 |
|------|------|------|--------|
| port | number | 服务监听端口 | 3000 |
| cacheDir | string | 缓存目录路径 | .npm-sentinel-cache |
| cacheTTL | number | 缓存生存时间（秒） | 3600 |
| npmRegistryUrl | string | NPM Registry API 地址 | https://registry.npmjs.org |
| depsDevApiUrl | string | deps.dev API 地址 | https://api.deps.dev |

资料来源：[package.json](https://github.com/Nekzus/npm-sentinel-mcp/blob/main/package.json)

### NPM Registry 工具集

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

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

**主要工具函数：**

| 工具名称 | 功能 | 数据来源 |
|----------|------|----------|
| npmInfo | 获取包详细信息 | NPM Registry |
| npmDeps | 获取依赖关系树 | NPM Registry + Deps.dev |
| npmVersions | 获取版本列表 | NPM Registry |
| npmSearch | 搜索包 | NPM Registry |

资料来源：[src/tools/npm-registry.ts](https://github.com/Nekzus/npm-sentinel-mcp/blob/main/src/tools/npm-registry.ts)

### 漏洞扫描器

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

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

**扫描特性：**

| 特性 | 说明 | 版本支持 |
|------|------|----------|
| 直接依赖扫描 | 检查直接依赖的已知漏洞 | v1.14.0+ |
| 传递依赖扫描 | 递归扫描所有传递依赖 | v1.14.0+ |
| React 生态感知 | 特殊处理 React 生态系统 | v1.14.0+ |
| CVE 富化 | 关联 CVE 详细信息 | v1.14.0+ |
| Deps.dev 集成 | 突破 API 请求限制 | v1.17.0+ |

资料来源：[src/tools/vulnerability-scanner.ts](https://github.com/Nekzus/npm-sentinel-mcp/blob/main/src/tools/vulnerability-scanner.ts)

### 包名验证器

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

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

**验证规则：**

| 规则 | 正则表达式 | 说明 |
|------|------------|------|
| 作用域包 | `@scope/package-name` | 作用域包格式 |
| 普通包 | `^[a-z0-9][a-z0-9-_.]*$` | 小写字母、数字、连字符、下划线、点 |
| 长度限制 | 1-214 字符 | npm 包名长度限制 |
| 首字符 | 字母或数字 | 不能以特殊字符开头 |

资料来源：[src/tools/package-name-validator.ts](https://github.com/Nekzus/npm-sentinel-mcp/blob/main/src/tools/package-name-validator.ts)

## 服务层架构

### 缓存服务

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

```mermaid
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[返回错误]
```

**缓存配置：**

| 配置项 | 类型 | 说明 |
|--------|------|------|
| directory | string | 缓存目录路径 |
| ttl | number | 默认缓存 TTL（秒） |
| maxMemorySize | number | 内存缓存最大条目数 |
| invalidation | boolean | 启用主动失效机制 |

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

资料来源：[src/services/cache.service.ts](https://github.com/Nekzus/npm-sentinel-mcp/blob/main/src/services/cache.service.ts)

### Deps.dev 服务集成

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

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

**集成优势：**

| 特性 | 原生 NPM API | Deps.dev 集成 |
|------|--------------|---------------|
| 传递依赖解析 | 需多次请求 | 批量获取 |
| API 限流 | 严格限制 | 更宽松 |
| 漏洞数据 | 基础信息 | 完整 CVE |

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

资料来源：[src/services/depsdev.service.ts](https://github.com/Nekzus/npm-sentinel-mcp/blob/main/src/services/depsdev.service.ts)

## 数据流架构

### 请求处理流程

```mermaid
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
```

### 漏洞扫描完整流程

```mermaid
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
```

## 安全架构

### 包名验证流程

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

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

**验证错误类型：**

| 错误代码 | 说明 | 处理方式 |
|----------|------|----------|
| INVALID_LENGTH | 包名长度超出 1-214 字符 | 返回验证错误 |
| UPPERCASE_DETECTED | 包含大写字母 | 返回验证错误 |
| INVALID_CHARACTER | 包含非法字符 | 返回验证错误 |
| INVALID_SCOPE | 作用域格式错误 | 返回验证错误 |

资料来源：[src/tools/package-name-validator.ts](https://github.com/Nekzus/npm-sentinel-mcp/blob/main/src/tools/package-name-validator.ts)

## 技术栈

| 层级 | 技术选型 | 版本要求 |
|------|----------|----------|
| 运行时 | Node.js | ≥20.0.0 |
| 语言 | TypeScript | 5.x |
| 类型验证 | Zod | 最新稳定版 |
| HTTP 客户端 | 原生 fetch / axios | - |
| 缓存存储 | 文件系统 | - |
| 测试框架 | Vitest | 最新稳定版 |
| 发布工具 | semantic-release-github | v10 (Node 20 兼容) |

资料来源：[package.json](https://github.com/Nekzus/npm-sentinel-mcp/blob/main/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              # 服务器配置
```

## 版本演进与架构变更

| 版本 | 发布日期 | 架构变更 |
|------|----------|----------|
| v1.13.x | 2025-12-24 | Smithery 集成、初始架构 |
| v1.14.0 | 2025-12-24 | 漏洞扫描器引入、传递依赖分析 |
| v1.15.0 | 2025-12-30 | 缓存失效机制完善 |
| v1.16.0 | 2026-01-02 | 包名验证安全增强 |
| v1.17.0 | 2026-02-22 | Deps.dev API 集成 |
| v1.18.0 | 2026-02-22 | 传递拓扑洞察注入 |

## 常见问题与故障排除

### 缓存相关问题

| 问题 | 可能原因 | 解决方案 |
|------|----------|----------|
| 数据未更新 | 缓存未失效 | 清除缓存目录或等待 TTL 过期 |
| 缓存写入失败 | 权限问题 | 检查目录写权限 |

### API 请求问题

| 问题 | 可能原因 | 解决方案 |
|------|----------|----------|
| 请求超时 | 网络问题或限流 | 检查网络连接或配置代理 |
| 依赖树不完整 | Deps.dev API 限制 | 使用本地递归解析作为后备 |

### 包名验证问题

| 问题 | 可能原因 | 解决方案 |
|------|----------|----------|
| 合法包名被拒绝 | 验证规则过严 | 检查 npm 官方包名规范 |
| 作用域包无法识别 | 正则表达式问题 | 确认包名符合 `@scope/name` 格式 |

## 相关链接

- [npm-sentinel-mcp 官方仓库](https://github.com/Nekzus/npm-sentinel-mcp)
- [Model Context Protocol 规范](https://modelcontextprotocol.org)
- [npm Registry API 文档](https://github.com/npm/registry)
- [Deps.dev API 文档](https://deps.dev/api)
- [漏洞扫描功能详解](./vulnerability-scanning.md)
- [缓存机制说明](./caching.md)

---

<a id='page-data-flow'></a>

## 数据流与处理

### 相关页面

相关主题：[系统架构](#page-architecture), [缓存机制](#page-caching)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [src/index.ts](https://github.com/Nekzus/npm-sentinel-mcp/blob/main/src/index.ts)
- [src/tools/npm-registry.ts](https://github.com/Nekzus/npm-sentinel-mcp/blob/main/src/tools/npm-registry.ts)
- [src/tools/npm-deps.ts](https://github.com/Nekzus/npm-sentinel-mcp/blob/main/src/tools/npm-deps.ts)
- [src/tools/vulnerability-scan.ts](https://github.com/Nekzus/npm-sentinel-mcp/blob/main/src/tools/vulnerability-scan.ts)
- [src/services/cache-service.ts](https://github.com/Nekzus/npm-sentinel-mcp/blob/main/src/services/cache-service.ts)
- [src/services/deps-dev-service.ts](https://github.com/Nekzus/npm-sentinel-mcp/blob/main/src/services/deps-dev-service.ts)
- [src/validators/package-name-validator.ts](https://github.com/Nekzus/npm-sentinel-mcp/blob/main/src/validators/package-name-validator.ts)
- [package.json](https://github.com/Nekzus/npm-sentinel-mcp/blob/main/package.json)
</details>

# 数据流与处理

本文档详细说明 npm-sentinel-mcp 项目的数据流向与处理机制，涵盖从用户请求到结果返回的完整处理流程，以及各组件之间的数据交互关系。

## 概述

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

项目的主要数据来源包括：
- npm Registry API - 官方 npm 包注册表
- deps.dev API - 依赖拓扑分析与漏洞信息

资料来源：[src/index.ts:1-50](https://github.com/Nekzus/npm-sentinel-mcp/blob/main/src/index.ts)

## 架构概览

```mermaid
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](https://github.com/Nekzus/npm-sentinel-mcp/blob/main/src/index.ts)

### 工具路由机制

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

| 工具名称 | 功能描述 | 数据源 | 输出格式 |
|---------|---------|--------|---------|
| `npm-registry` | 获取 npm 包元数据信息 | npm Registry API | 包详情 JSON |
| `npm-deps` | 解析依赖关系树 | npm Registry + deps.dev | 依赖拓扑结构 |
| `vulnerability-scan` | 扫描已知安全漏洞 | npm Registry + deps.dev | 漏洞报告 |

资料来源：[src/tools/npm-registry.ts](https://github.com/Nekzus/npm-sentinel-mcp/blob/main/src/tools/npm-registry.ts)
资料来源：[src/tools/npm-deps.ts](https://github.com/Nekzus/npm-sentinel-mcp/blob/main/src/tools/npm-deps.ts)
资料来源：[src/tools/vulnerability-scan.ts](https://github.com/Nekzus/npm-sentinel-mcp/blob/main/src/tools/vulnerability-scan.ts)

## 输入数据验证

### 参数 Schema 验证

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

```typescript
// 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](https://github.com/Nekzus/npm-sentinel-mcp/blob/main/src/tools/npm-registry.ts)

### 包名称安全校验

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

```mermaid
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](https://github.com/Nekzus/npm-sentinel-mcp/blob/main/src/validators/package-name-validator.ts)
资料来源：[v1.16.0 Release](https://github.com/Nekzus/npm-sentinel-mcp/releases/tag/v1.16.0)

## 数据获取与处理

### npm Registry 数据获取

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

```mermaid
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](https://github.com/Nekzus/npm-sentinel-mcp/blob/main/src/tools/npm-registry.ts)

### 依赖树解析 (npm-deps)

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

```mermaid
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](https://github.com/Nekzus/npm-sentinel-mcp/blob/main/src/tools/npm-deps.ts)
资料来源：[src/services/deps-dev-service.ts:1-60](https://github.com/Nekzus/npm-sentinel-mcp/blob/main/src/services/deps-dev-service.ts)
资料来源：[v1.17.0 Release](https://github.com/Nekzus/npm-sentinel-mcp/releases/tag/v1.17.0)
资料来源：[v1.18.0 Release](https://github.com/Nekzus/npm-sentinel-mcp/releases/tag/v1.18.0)

### 漏洞扫描处理 (vulnerability-scan)

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

```mermaid
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](https://github.com/Nekzus/npm-sentinel-mcp/blob/main/src/tools/vulnerability-scan.ts)
资料来源：[v1.14.0 Release](https://github.com/Nekzus/npm-sentinel-mcp/releases/tag/v1.14.0)

## 缓存服务

### 缓存架构

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

```mermaid
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 版本实现了健壮的缓存失效机制：

| 失效策略 | 触发条件 | 处理方式 |
|---------|---------|---------|
| TTL 过期 | 缓存条目超过预设时间 | 自动删除 |
| 版本检测 | 检测到 npm 包新版本发布 | 标记相关缓存失效 |
| 手动失效 | 用户显式请求失效 | 清除指定缓存 |
| 启动清理 | 服务启动时 | 清理过期条目 |

资料来源：[src/services/cache-service.ts:1-100](https://github.com/Nekzus/npm-sentinel-mcp/blob/main/src/services/cache-service.ts)
资料来源：[v1.15.0 Release](https://github.com/Nekzus/npm-sentinel-mcp/releases/tag/v1.15.0)

### 缓存数据结构

```typescript
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](https://github.com/Nekzus/npm-sentinel-mcp/blob/main/src/services/cache-service.ts)

## 错误处理

### 验证错误

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

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

### API 错误

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

| 错误类型 | HTTP 状态码 | 处理策略 |
|---------|------------|---------|
| 网络超时 | - | 重试最多 3 次，指数退避 |
| 404 未找到 | 404 | 返回空结果 |
| 速率限制 | 429 | 等待后重试 |
| 服务器错误 | 500-599 | 重试 2 次 |
| 无效响应 | - | 记录日志，返回错误 |

资料来源：[src/tools/npm-registry.ts:100-150](https://github.com/Nekzus/npm-sentinel-mcp/blob/main/src/tools/npm-registry.ts)

## 数据流时序

### 完整请求处理时序

```mermaid
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: 返回最终结果
```

## 配置参数

### 环境变量配置

| 参数名 | 类型 | 默认值 | 说明 |
|-------|------|-------|------|
| `NPM_REGISTRY_URL` | string | `https://registry.npmjs.org` | npm Registry API 地址 |
| `DEPS_DEV_URL` | string | `https://api.deps.dev` | deps.dev API 地址 |
| `CACHE_TTL_SECONDS` | number | `3600` | 缓存生存时间（秒） |
| `HTTP_TIMEOUT_MS` | number | `30000` | HTTP 请求超时（毫秒） |
| `MAX_RETRIES` | number | `3` | 最大重试次数 |

资料来源：[package.json](https://github.com/Nekzus/npm-sentinel-mcp/blob/main/package.json)

### Zod 验证配置

```typescript
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](https://github.com/Nekzus/npm-sentinel-mcp/blob/main/src/index.ts)

## 常见故障模式

### 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](https://github.com/Nekzus/npm-sentinel-mcp/releases/tag/v1.17.0)

## 性能优化建议

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

---

## 参见

- [快速开始指南](./快速开始指南.md) - 项目安装与基础使用
- [工具 API 参考](./工具-API-参考.md) - 各工具详细参数说明
- [配置与部署](./配置与部署.md) - 环境配置与部署选项
- [故障排查](./故障排查.md) - 常见问题与解决方案

---

<a id='page-security'></a>

## 安全扫描功能

### 相关页面

相关主题：[依赖分析](#page-dependency-analysis), [包管理工具集](#page-package-tools)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [README.md](https://github.com/Nekzus/npm-sentinel-mcp/blob/main/README.md)
- [SECURITY.md](https://github.com/Nekzus/npm-sentinel-mcp/blob/main/SECURITY.md)
- [package.json](https://github.com/Nekzus/npm-sentinel-mcp/blob/main/package.json)
- [src/index.ts](https://github.com/Nekzus/npm-sentinel-mcp/blob/main/src/index.ts)
- [src/tools/npmVulnScan.ts](https://github.com/Nekzus/npm-sentinel-mcp/blob/main/src/tools/npmVulnScan.ts)
</details>

# 安全扫描功能

## 概述

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

## 核心架构

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

```mermaid
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[返回扫描结果]
```

### 组件说明

| 组件名称 | 功能描述 | 源码位置 |
|---------|---------|---------|
| 缓存管理器 | 管理扫描结果的本地缓存，支持失效机制 | [src/index.ts](https://github.com/Nekzus/npm-sentinel-mcp/blob/main/src/index.ts) |
| 包名验证器 | 强制严格的包名格式验证，防止注入攻击 | 工具模块 |
| deps.dev 集成 | 获取大规模依赖拓扑和传递依赖信息 | [src/tools/npmVulnScan.ts](https://github.com/Nekzus/npm-sentinel-mcp/blob/main/src/tools/npmVulnScan.ts) |
| CVE 富化器 | 增强漏洞数据，提供详细的 CVE 信息 | 漏洞扫描模块 |
| 分析引擎 | 综合评估漏洞严重程度和影响范围 | 扫描核心 |

## 传递依赖扫描

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

### 依赖解析流程

```mermaid
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](https://github.com/Nekzus/npm-sentinel-mcp/releases/tag/v1.17.0)

## 缓存失效机制

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

### 缓存策略

| 缓存类型 | 失效触发条件 | TTL 配置 |
|---------|-------------|---------|
| 漏洞元数据 | CVE 数据库更新 | 动态检测 |
| 包版本信息 | npm registry 版本变化 | 24 小时 |
| 扫描结果 | 手动触发或 TTL 到期 | 可配置 |

### 失效检测流程

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

> 资料来源：[v1.15.0 Release Notes](https://github.com/Nekzus/npm-sentinel-mcp/releases/tag/v1.15.0)

## 包名安全验证

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

### 验证规则

包名验证遵循以下规则：

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

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

### 安全意义

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

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

> 资料来源：[v1.16.0 Release Notes](https://github.com/Nekzus/npm-sentinel-mcp/releases/tag/v1.16.0)

## React 生态系统感知

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

### 特殊处理机制

| 扫描领域 | 处理方式 | 优先级 |
|---------|---------|-------|
| React 核心库 | 深度版本匹配 | 高 |
| JSX 运行时 | 特殊依赖分析 | 高 |
| React DOM | 浏览器环境特异漏洞 | 中 |
| 相关工具链 | 构建时依赖检查 | 中 |

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

> 资料来源：[v1.14.0 Release Notes](https://github.com/Nekzus/npm-sentinel-mcp/releases/tag/v1.14.0)

## CVE 富化

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

### 富化数据类型

| 数据类型 | 描述 | 来源 |
|---------|------|-----|
| CVE 编号 | 标准化的漏洞标识符 | NVD 数据库 |
| 严重程度 | CVSS 评分和等级 | 安全情报 |
| 修复版本 | 包含修复的最低版本 | npm registry |
| 引用链接 | 详细的漏洞文档 | 安全公告 |

### 输出示例

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

```json
{
  "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](https://github.com/Nekzus/npm-sentinel-mcp/releases/tag/v1.18.0)

## 使用方式

### 基本扫描

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

### 输入参数

| 参数名 | 类型 | 必填 | 描述 |
|-------|------|-----|------|
| packageName | string | 是 | 要扫描的 npm 包名称 |
| version | string | 否 | 特定版本号，默认为 latest |
| includeTransitive | boolean | 否 | 是否包含传递依赖扫描 |

### 输出结构

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

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

## 配置选项

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

| 配置项 | 默认值 | 描述 |
|-------|-------|------|
| cacheEnabled | true | 启用扫描结果缓存 |
| cacheTTL | 86400 | 缓存有效期（秒） |
| includeDevDeps | false | 包含开发依赖 |
| severityThreshold | low | 报告的最低严重程度阈值 |
| timeout | 30000 | API 请求超时（毫秒） |

## 常见问题与限制

### 性能考虑

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

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

### API 限制

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

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

### 数据准确性

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

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

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

## 另请参阅

- [项目主页](../README.md) - 完整项目文档
- [安全策略](../SECURITY.md) - 安全漏洞报告指南
- [快速开始](./快速开始.md) - 快速上手教程
- [工具参考](./工具参考.md) - MCP 工具完整列表

---

<a id='page-dependency-analysis'></a>

## 依赖分析

### 相关页面

相关主题：[安全扫描功能](#page-security), [包管理工具集](#page-package-tools)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [README.md](https://github.com/Nekzus/npm-sentinel-mcp/blob/main/README.md)
- [llms.txt](https://github.com/Nekzus/npm-sentinel-mcp/blob/main/llms.txt)
- [src/tools/npmDeps.ts](https://github.com/Nekzus/npm-sentinel-mcp/blob/main/src/tools/npmDeps.ts)
- [src/services/depsDev.ts](https://github.com/Nekzus/npm-sentinel-mcp/blob/main/src/services/depsDev.ts)
- [src/services/npmRegistry.ts](https://github.com/Nekzus/npm-sentinel-mcp/blob/main/src/services/npmRegistry.ts)
- [src/services/cache.ts](https://github.com/Nekzus/npm-sentinel-mcp/blob/main/src/services/cache.ts)
</details>

# 依赖分析

npm-sentinel-mcp 是一个基于 Model Context Protocol (MCP) 的 npm 依赖分析服务，提供全面的依赖树解析、漏洞扫描和传递依赖分析功能。本页面详细介绍依赖分析模块的架构、功能和使用方法。

## 功能概述

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

| 功能类别 | 描述 |
|---------|------|
| 依赖树解析 | 解析 npm 包的完整依赖树结构 |
| 传递依赖分析 | 分析间接依赖（transitive dependencies） |
| 漏洞检测 | 基于 OSV 数据库的漏洞扫描 |
| 生态感知 | React 生态系统的特殊识别 |
| CVE 丰富 | 漏洞情报增强 |

资料来源：[README.md:1-50](https://github.com/Nekzus/npm-sentinel-mcp/blob/main/README.md)

## 架构设计

### 整体架构

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

```mermaid
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
```

### 核心服务组件

| 组件 | 文件位置 | 职责 |
|------|---------|------|
| npmDeps | `src/tools/npmDeps.ts` | MCP 工具入口，处理依赖分析请求 |
| depsDev | `src/services/depsDev.ts` | deps.dev API 集成，解析依赖拓扑 |
| npmRegistry | `src/services/npmRegistry.ts` | npm Registry API 交互 |
| cache | `src/services/cache.ts` | 缓存管理 |

资料来源：[llms.txt](https://github.com/Nekzus/npm-sentinel-mcp/blob/main/llms.txt)

## 依赖解析流程

### 解析策略

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

```mermaid
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](https://github.com/Nekzus/npm-sentinel-mcp/blob/main/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

传递依赖分析包括：

| 分析类型 | 说明 |
|---------|------|
| 直接依赖 | package.json 中声明的依赖 |
| 间接依赖 | 传递依赖（transitive dependencies） |
| 依赖拓扑 | 依赖项之间的层级关系 |
| 版本冲突 | 同一包的不同版本检测 |

资料来源：[src/tools/npmDeps.ts](https://github.com/Nekzus/npm-sentinel-mcp/blob/main/src/tools/npmDeps.ts)

## 漏洞扫描集成

### 扫描能力

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

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

### OSV 集成

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

## 缓存机制

### 缓存策略

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

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

### 缓存失效策略

| 策略 | 说明 |
|------|------|
| TTL 失效 | 基于时间的过期机制 |
| 版本失效 | 包版本更新时失效 |
| 手动失效 | 支持强制刷新缓存 |

资料来源：[src/services/cache.ts](https://github.com/Nekzus/npm-sentinel-mcp/blob/main/src/services/cache.ts)

## 使用方法

### 基本调用

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

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

### 参数说明

| 参数 | 类型 | 必需 | 说明 |
|------|------|------|------|
| packageName | string | 是 | npm 包名称 |
| version | string | 否 | 指定版本，默认为最新版本 |
| includeTransitive | boolean | 否 | 是否包含传递依赖 |
| scanVulnerabilities | boolean | 否 | 是否执行漏洞扫描 |

## 安全特性

### 包名验证

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

> **security:** enforce strict package name validation across all tools

这确保了：

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

资料来源：[src/tools/npmDeps.ts](https://github.com/Nekzus/npm-sentinel-mcp/blob/main/src/tools/npmDeps.ts)

## 版本历史

| 版本 | 发布日期 | 依赖分析相关功能 |
|------|----------|-----------------|
| v1.18.0 | 2026-02-22 | 通过 deps.dev 注入传递拓扑洞察 |
| v1.17.0 | 2026-02-22 | 集成 deps.dev 绕过边缘子请求限制 |
| v1.15.0 | 2025-12-30 | 实现健壮的缓存失效机制 |
| v1.14.0 | 2025-12-24 | 增强传递扫描和 React 生态感知 |

资料来源：[社区发布记录](https://github.com/Nekzus/npm-sentinel-mcp/releases)

## 常见问题

### 依赖解析失败

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

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

### 缓存相关

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

## 另请参阅

- [快速开始指南](../getting-started.md) - 如何配置和使用 npm-sentinel-mcp
- [工具参考](../tools/index.md) - 所有可用 MCP 工具详细说明
- [配置参考](../configuration.md) - 完整的配置选项说明
- [故障排除](../troubleshooting.md) - 常见问题解决方案

---

<a id='page-package-tools'></a>

## 包管理工具集

### 相关页面

相关主题：[安全扫描功能](#page-security), [依赖分析](#page-dependency-analysis)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [README.md](https://github.com/Nekzus/npm-sentinel-mcp/blob/main/README.md)
- [llms-full.txt](https://github.com/Nekzus/npm-sentinel-mcp/blob/main/llms-full.txt)
- [package.json](https://github.com/Nekzus/npm-sentinel-mcp/blob/main/package.json)
- [src/index.ts](https://github.com/Nekzus/npm-sentinel-mcp/blob/main/src/index.ts)
- [src/tools/](https://github.com/Nekzus/npm-sentinel-mcp/tree/main/src/tools)
</details>

# 包管理工具集

npm-sentinel-mcp 是一个基于 Model Context Protocol (MCP) 的智能包管理工具集，专门为 npm生态系统提供全面的安全扫描、依赖分析和包信息检索能力。本工具集通过集成多个外部服务（如 npm Registry、deps.dev 和漏洞数据库）来实现企业级的包安全管理。

## 概述

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

| 工具名称 | 功能描述 | 核心能力 |
|---------|---------|----------|
| npmDeps | 依赖信息查询 | 递归解析依赖树，集成 deps.dev 转译拓扑信息 |
| npmVuln | 漏洞扫描 | 传递依赖扫描、CVE 丰富、React 生态系统感知 |
| npmSearch | 包搜索 | npm Registry 搜索接口 |
| npmInfo | 包元数据 | 版本、描述、作者、维护状态等信息 |

资料来源：[llms-full.txt](https://github.com/Nekzus/npm-sentinel-mcp/blob/main/llms-full.txt)

## 架构设计

### 整体架构

```mermaid
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
```

### 工具层设计

```mermaid
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](https://github.com/Nekzus/npm-sentinel-mcp/blob/main/llms-full.txt)

#### 输入参数

| 参数名 | 类型 | 必填 | 描述 |
|-------|------|------|------|
| packageName | string | 是 | npm 包名称 |
| version | string | 否 | 特定版本号，默认获取最新版本 |
| recursive | boolean | 否 | 是否递归解析依赖树，默认 false |

#### 输出数据结构

```typescript
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](https://github.com/Nekzus/npm-sentinel-mcp/releases/tag/v1.14.0)

#### 漏洞检测流程

```mermaid
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[缓存扫描结果]
```

#### 输出数据结构

```typescript
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 包
- 返回相关度排序的搜索结果
- 包含包的元数据摘要

#### 输入参数

| 参数名 | 类型 | 必填 | 描述 |
|-------|------|------|------|
| query | string | 是 | 搜索关键词 |
| size | number | 否 | 返回结果数量，默认 20 |

### npmInfo - 包元数据

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

#### 功能特性

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

## 安全机制

### 包名验证

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

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

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

| 错误代码 | 描述 | 处理建议 |
|---------|------|----------|
| INVALID_PACKAGE_NAME | 包名格式不符合 npm 规范 | 检查包名拼写，使用合法的 npm 包名格式 |
| PACKAGE_NOT_FOUND | 包不存在于 npm Registry | 确认包名是否正确，或包是否已被 unpublish |

资料来源：[v1.16.0 Release Notes](https://github.com/Nekzus/npm-sentinel-mcp/releases/tag/v1.16.0)

### 缓存机制

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

#### 缓存策略

| 缓存类型 | TTL | 失效条件 |
|---------|-----|---------|
| 包信息 | 1 小时 | 包版本更新、unpublish |
| 依赖树 | 30 分钟 | 直接依赖变化 |
| 漏洞数据 | 6 小时 | CVE 数据库更新 |
| 搜索结果 | 15 分钟 | 手动触发失效 |

#### 缓存失效机制

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

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

资料来源：[v1.15.0 Release Notes](https://github.com/Nekzus/npm-sentinel-mcp/releases/tag/v1.15.0)

## 外部服务集成

### npm Registry API

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

| 端点 | 用途 | 速率限制 |
|-----|------|---------|
| `registry.npmjs.org` | 包信息和版本查询 | 建议使用缓存 |
| `/[package]` | 获取包元数据 | 无明确限制 |
| `/-/v1/search` | 包搜索 | 受速率限制 |

### deps.dev API

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

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

```mermaid
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](https://github.com/Nekzus/npm-sentinel-mcp/releases/tag/v1.17.0)

## 配置选项

### 工具配置

| 配置项 | 类型 | 默认值 | 描述 |
|-------|------|-------|------|
| `npmRegistryUrl` | string | `https://registry.npmjs.org` | npm Registry 地址 |
| `depsDevApiUrl` | string | `https://api.deps.dev` | deps.dev API 地址 |
| `cacheEnabled` | boolean | `true` | 是否启用缓存 |
| `cacheDir` | string | `.npm-sentinel-cache` | 缓存目录路径 |
| `requestTimeout` | number | `30000` | 请求超时时间（毫秒） |
| `maxRecursiveDepth` | number | `10` | 最大递归深度 |
| `strictValidation` | boolean | `true` | 是否启用严格包名验证 |

### 环境变量

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

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

# 可选：禁用缓存
NPM_SENTINEL_CACHE_ENABLED=false
```

## 使用示例

### 基本使用

```typescript
// 使用 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'
});
```

### 批量扫描

```typescript
// 扫描多个包的漏洞
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} 个漏洞`);
  }
}
```

## 常见问题与故障排除

### 常见错误

| 错误类型 | 原因 | 解决方案 |
|---------|------|---------|
| `ECONNREFUSED` | 网络连接失败 | 检查网络连接，确认 Registry URL 可达 |
| `ETIMEDOUT` | 请求超时 | 增加 `requestTimeout` 配置值 |
| `ENOTFOUND` | 包不存在 | 确认包名拼写正确 |
| `ZOD_VALIDATION_ERROR` | 参数验证失败 | 检查输入参数格式是否符合 Schema |

### 性能问题

| 问题 | 原因 | 优化建议 |
|-----|------|---------|
| 首次调用慢 | 缓存预热 | 启动时预先查询常用包 |
| 依赖解析慢 | 深层嵌套依赖 | 使用 `maxRecursiveDepth` 限制深度 |
| 内存占用高 | 大型依赖树 | 启用缓存，减少重复请求 |

### 测试问题修复

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

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

资料来源：[v1.16.1 Release Notes](https://github.com/Nekzus/npm-sentinel-mcp/releases/tag/v1.16.1)

## 版本历史

| 版本 | 发布日期 | 关键变更 |
|-----|---------|---------|
| v1.18.0 | 2026-02-22 | 通过 deps.dev 注入传递拓扑洞察 |
| v1.17.0 | 2026-02-22 | 集成 deps.dev API，绕过子请求限制 |
| v1.16.0 | 2026-01-02 | 强制所有工具执行严格包名验证 |
| v1.15.0 | 2025-12-30 | 实现健壮的缓存失效机制 |
| v1.14.0 | 2025-12-24 | 增强传递依赖扫描和 CVE 丰富 |
| v1.13.x | 2025-12-24 | Smithery 集成优化 |

## See Also

- [项目主页](../README) - 完整的项目介绍和快速开始指南
- [安装指南](./Installation) - MCP Server 安装和配置
- [API 参考](./API-Reference) - 完整的工具 API 文档
- [开发指南](./Development) - 本地开发和测试说明

---

<a id='page-configuration'></a>

## 配置选项

### 相关页面

相关主题：[部署指南](#page-deployment), [安装指南](#page-installation)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [README.md](https://github.com/Nekzus/npm-sentinel-mcp/blob/main/README.md)
- [smithery.yaml](https://github.com/Nekzus/npm-sentinel-mcp/blob/main/smithery.yaml)
- [server.json](https://github.com/Nekzus/npm-sentinel-mcp/blob/main/server.json)
- [package.json](https://github.com/Nekzus/npm-sentinel-mcp/blob/main/package.json)
- [src/config/index.ts](https://github.com/Nekzus/npm-sentinel-mcp/blob/main/src/config/index.ts)
</details>

# 配置选项

npm-sentinel-mcp 是一个基于 Model Context Protocol (MCP) 的 npm 安全监控服务器，通过配置选项可以控制漏洞扫描、依赖解析缓存、包名验证等核心功能。本页面详细介绍所有可用的配置参数及其使用方法。

## 概述

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

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

资料来源：[README.md:1-50]()

## 配置架构

### 配置层级结构

```mermaid
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 平台集成配置 | 高 |
| `server.json` | MCP 协议标准配置 | 中 |
| `package.json` | npm 发布元数据 | 低 |
| 环境变量 | 运行时动态配置 | 最高 |

资料来源：[smithery.yaml](https://github.com/Nekzus/npm-sentinel-mcp/blob/main/smithery.yaml)

## Smithery 平台配置

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

### 配置 Schema

```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: []
```

### 核心配置字段

| 字段名 | 类型 | 默认值 | 说明 |
|--------|------|--------|------|
| `npmRegistryUrl` | string | https://registry.npmjs.org | NPM Registry 访问地址 |
| `enableTransitiveScanning` | boolean | true | 启用 transitive 依赖扫描 |
| `cacheDuration` | number | 3600 | 缓存有效期（秒） |

资料来源：[smithery.yaml](https://github.com/Nekzus/npm-sentinel-mcp/blob/main/smithery.yaml)

## 安全验证配置

### 包名验证 (v1.16.0+)

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

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

### 验证规则详解

| 规则类型 | 验证内容 | 错误消息 |
|---------|---------|---------|
| 长度限制 | 1 ≤ length ≤ 214 | Package name length must be between 1 and 214 characters |
| 字符集 | 仅允许 `[a-z0-9-_.]` | Package name contains invalid characters |
| 作用域 | `@scope/name` 格式 | Invalid scope format |
| 前缀禁止 | 不能以 `.` 或 `_` 开头 | Package name cannot start with '.' or '_' |
| URL 编码 | 不能包含 URL 特殊字符 | Package name contains URL-encoded characters |

资料来源：[smithery.yaml](https://github.com/Nekzus/npm-sentinel-mcp/blob/main/smithery.yaml)

## 漏洞扫描配置

### Transitive 依赖扫描

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

```mermaid
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[生成漏洞报告]
```

### 扫描配置参数

| 参数名 | 类型 | 默认值 | 说明 |
|--------|------|--------|------|
| `transitiveDepth` | number | -1 | transitive 扫描深度，-1 表示无限制 |
| `includeReactEcosystem` | boolean | true | 包含 React 生态特殊处理 |
| `cveEnrichment` | boolean | true | 启用 CVE 数据丰富 |

资料来源：[README.md](https://github.com/Nekzus/npm-sentinel-mcp/blob/main/README.md)

## deps.dev 集成配置

### API 集成特性 (v1.17.0+)

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

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

### 依赖拓扑洞察

| 字段 | 类型 | 说明 |
|------|------|------|
| `directDependencies` | string[] | 直接依赖列表 |
| `transitiveDependencies` | string[] | transitive 依赖列表 |
| `dependencyGraph` | object | 依赖关系图 |
| `vulnerabilityScore` | number | 漏洞评分 |

资料来源：[smithery.yaml](https://github.com/Nekzus/npm-sentinel-mcp/blob/main/smithery.yaml)

## 缓存管理配置

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

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

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

### 缓存配置参数

| 参数名 | 类型 | 默认值 | 说明 |
|--------|------|--------|------|
| `cacheEnabled` | boolean | true | 启用缓存 |
| `cacheDuration` | number | 3600 | 缓存有效期（秒） |
| `cacheInvalidation` | string | time-based | 失效策略：time-based 或 manual |

资料来源：[smithery.yaml](https://github.com/Nekzus/npm-sentinel-mcp/blob/main/smithery.yaml)

## MCP 协议配置

### server.json 配置结构

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

### 协议能力配置

| 能力 | 类型 | 说明 |
|------|------|------|
| `tools.enabled` | boolean | 启用 MCP 工具调用 |
| `resources.enabled` | boolean | 启用 MCP 资源访问 |
| `prompts.enabled` | boolean | 启用 MCP 提示模板 |

资料来源：[server.json](https://github.com/Nekzus/npm-sentinel-mcp/blob/main/server.json)

## 环境变量配置

### 运行时环境变量

| 变量名 | 类型 | 默认值 | 说明 |
|--------|------|--------|------|
| `NODE_ENV` | string | production | 运行环境 |
| `NPM_REGISTRY_URL` | string | https://registry.npmjs.org | NPM Registry 地址 |
| `DEPS_DEV_API_URL` | string | https://api.deps.dev | deps.dev API 地址 |
| `LOG_LEVEL` | string | info | 日志级别 |

资料来源：[package.json](https://github.com/Nekzus/npm-sentinel-mcp/blob/main/package.json)

## 配置示例

### 最小配置

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

### 完整配置

```yaml
# 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: []
```

### 环境变量配置

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

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

# 启用调试日志
export LOG_LEVEL=debug
```

## 常见配置问题

### 问题诊断

| 问题 | 可能原因 | 解决方案 |
|------|---------|---------|
| 包名验证失败 | 使用了无效字符 | 检查包名格式是否符合 npm 规范 |
| 缓存未生效 | 缓存过期时间设置过短 | 增加 `cacheDuration` 值 |
| Transitive 扫描超时 | 依赖树过深 | 设置 `transitiveDepth` 限制 |
| deps.dev API 错误 | 网络问题或 API 限制 | 检查网络连接或降低请求频率 |

### 验证配置

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

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

## 版本历史

| 版本 | 更新内容 | 相关配置变更 |
|------|---------|-------------|
| v1.18.0 | 注入 transitive topology insights | 新增 deps.dev 集成参数 |
| v1.17.0 | 集成 deps.dev API | 新增 `depsDevEnabled` 配置 |
| v1.16.0 | 严格包名验证 | 新增 `strictValidation` 配置 |
| v1.15.0 | 缓存失效机制 | 新增 `cacheInvalidation` 配置 |
| v1.14.0 | Transitive 扫描增强 | 新增 `transitiveDepth` 配置 |

资料来源：[社区发布记录](https://github.com/Nekzus/npm-sentinel-mcp/releases)

## 相关页面

- [快速开始指南](README.md) - 项目入门
- [API 参考](README.md#api) - 工具调用接口
- [安全说明](README.md#security) - 安全机制详解
- [故障排除](README.md#troubleshooting) - 常见问题解答

---

*最后更新：v1.18.0 | 项目维护者：[Nekzus](https://github.com/Nekzus)*

---

<a id='page-deployment'></a>

## 部署指南

### 相关页面

相关主题：[安装指南](#page-installation), [配置选项](#page-configuration)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [README.md](https://github.com/Nekzus/npm-sentinel-mcp/blob/main/README.md)
- [Dockerfile](https://github.com/Nekzus/npm-sentinel-mcp/blob/main/Dockerfile)
- [smithery.yaml](https://github.com/Nekzus/npm-sentinel-mcp/blob/main/smithery.yaml)
- [package.json](https://github.com/Nekzus/npm-sentinel-mcp/blob/main/package.json)
- [smithery_server.json](https://github.com/Nekzus/npm-sentinel-mcp/blob/main/smithery_server.json)
- [.npmrc](https://github.com/Nekzus/npm-sentinel-mcp/blob/main/.npmrc)
- [tsconfig.json](https://github.com/Nekzus/npm-sentinel-mcp/blob/main/tsconfig.json)
</details>

# 部署指南

本文档详细介绍 npm-sentinel-mcp 的各种部署方式、配置选项和环境要求，帮助开发者在不同环境中成功部署和运行该 MCP 服务器。

## 项目概述

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]()

## 系统要求

### 运行环境

| 要求项 | 最低版本 | 推荐版本 | 说明 |
|--------|----------|----------|------|
| Node.js | 20.0.0 | 20.x LTS | 支持 ES2022 和原生 TypeScript 编译 |
| npm | 10.0.0 | 最新稳定版 | 用于包管理和脚本执行 |
| 内存 | 512MB | 2GB | 大型依赖树扫描需要更多内存 |
| 磁盘 | 100MB | 500MB | 包含缓存数据存储空间 |
| 操作系统 | Linux/macOS/Windows | Linux (Ubuntu 22.04+) | 跨平台兼容 |

### 网络依赖

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

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

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

资料来源：[README.md:1-30]()

## 安装部署方式

### 方式一：npm 全局安装

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

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

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

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

资料来源：[package.json:1-30]()

### 方式二：Docker 容器部署

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

#### 构建镜像

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

#### 运行容器

```bash
# 基本运行
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 配置示例：

```yaml
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 平台](https://smithery.ai)，搜索 `npm-sentinel-mcp` 并按照指引完成配置。Smithery 会自动处理 MCP 服务器的启动和 AI 助手的连接。

#### 手动配置

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

```yaml
# 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]()

```json
// 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. **配置文件**：适合持久化配置管理

### 环境变量配置

| 环境变量 | 类型 | 默认值 | 说明 |
|----------|------|--------|------|
| `NODE_ENV` | string | `development` | 运行环境：`development`、`production` |
| `NPM_REGISTRY_URL` | string | `https://registry.npmjs.org` | npm Registry 地址 |
| `DEPS_DEV_API_URL` | string | `https://api.deps.dev` | deps.dev API 地址 |
| `OSV_API_URL` | string | `https://api.osv.dev` | OSV 漏洞 API 地址 |
| `LOG_LEVEL` | string | `info` | 日志级别：`debug`、`info`、`warn`、`error` |
| `CACHE_ENABLED` | boolean | `true` | 是否启用缓存 |
| `CACHE_TTL` | number | `3600` | 缓存过期时间（秒） |
| `HTTP_PROXY` | string | - | HTTP 代理地址 |
| `HTTPS_PROXY` | string | - | HTTPS 代理地址 |
| `MAX_CONCURRENT_REQUESTS` | number | `10` | 最大并发请求数 |

资料来源：[README.md:50-100]()

### 配置文件示例

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

```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 包相关的配置：

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

资料来源：[.npmrc:1-10]()

## 部署架构

### 系统架构图

```mermaid
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
```

### 数据流处理

```mermaid
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: 返回扫描结果
```

## 生产环境部署

### 高可用部署

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

```mermaid
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
```

### 性能调优参数

| 参数 | 生产环境建议值 | 说明 |
|------|----------------|------|
| `MAX_CONCURRENT_REQUESTS` | 20-50 | 根据后端 API 限流调整 |
| `CACHE_TTL` | 7200+ | 减少外部 API 调用 |
| `REQUEST_TIMEOUT` | 60000 | 长超时处理大依赖树 |
| `WORKER_THREADS` | 4-8 | 充分利用多核 |

### 监控和日志

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

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

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

## 安全配置

### 包名称验证

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

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

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

### 网络安全

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

## 常见问题排查

### 部署失败排查

| 问题现象 | 可能原因 | 解决方案 |
|----------|----------|----------|
| Node.js 版本不兼容 | 低于 20.0.0 | 升级 Node.js 或使用 Docker 部署 |
| 权限拒绝错误 | npm 全局目录无写权限 | 使用 sudo 或配置 npm prefix |
| 端口已被占用 | 3000 端口冲突 | 修改端口映射或停止冲突进程 |
| 网络超时 | 无法访问外部 API | 配置代理或检查防火墙 |

### 运行时问题

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

# 查看日志
docker logs npm-sentinel

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

### 性能问题

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

## 卸载

### npm 卸载

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

# 清理缓存
npm cache clean --force
```

### Docker 清理

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

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

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

## 相关资源

- [项目主页](https://github.com/Nekzus/npm-sentinel-mcp) - GitHub 仓库
- [变更日志](https://github.com/Nekzus/npm-sentinel-mcp/releases) - 版本历史
- [问题反馈](https://github.com/Nekzus/npm-sentinel-mcp/issues) - Bug 报告和功能请求
- [Smithery 集成](https://smithery.ai) - AI 助手平台集成

## See Also

- [安装指南](../installation) - 详细的安装步骤说明
- [配置参考](../configuration) - 完整配置选项文档
- [API 参考](../api-reference) - MCP 工具接口文档
- [架构设计](../architecture) - 系统架构详解
- [故障排除](../troubleshooting) - 常见问题解决方案

---

<a id='page-caching'></a>

## 缓存机制

### 相关页面

相关主题：[数据流与处理](#page-data-flow)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [src/cache/InMemoryCache.ts](https://github.com/Nekzus/npm-sentinel-mcp/blob/main/src/cache/InMemoryCache.ts)
- [src/cache/CacheManager.ts](https://github.com/Nekzus/npm-sentinel-mcp/blob/main/src/cache/CacheManager.ts)
- [src/cache/cacheStrategy.ts](https://github.com/Nekzus/npm-sentinel-mcp/blob/main/src/cache/cacheStrategy.ts)
- [src/utils/cacheInvalidation.ts](https://github.com/Nekzus/npm-sentinel-mcp/blob/main/src/utils/cacheInvalidation.ts)
- [src/config/schema.ts](https://github.com/Nekzus/npm-sentinel-mcp/blob/main/src/config/schema.ts)
- [src/mcp/providers/depsDev.ts](https://github.com/Nekzus/npm-sentinel-mcp/blob/main/src/mcp/providers/depsDev.ts)
</details>

# 缓存机制

## 概述

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

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

## 架构设计

### 缓存层级架构

```mermaid
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 | [src/cache/InMemoryCache.ts](https://github.com/Nekzus/npm-sentinel-mcp/blob/main/src/cache/InMemoryCache.ts) | 基于 Map 的内存缓存实现，支持 TTL 和 LRU 策略 |
| CacheManager | [src/cache/CacheManager.ts](https://github.com/Nekzus/npm-sentinel-mcp/blob/main/src/cache/CacheManager.ts) | 统一缓存入口，管理多类型缓存的生命周期 |
| CacheStrategy | [src/cache/cacheStrategy.ts](https://github.com/Nekzus/npm-sentinel-mcp/blob/main/src/cache/cacheStrategy.ts) | 定义缓存策略接口和默认实现 |
| CacheInvalidation | [src/utils/cacheInvalidation.ts](https://github.com/Nekzus/npm-sentinel-mcp/blob/main/src/utils/cacheInvalidation.ts) | 缓存失效逻辑，支持手动和自动两种模式 |

## 内存缓存实现

### InMemoryCache 核心机制

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

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

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

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

| 配置参数 | 类型 | 默认值 | 说明 |
|---------|------|--------|------|
| maxSize | number | 500 | 缓存最大条目数 |
| defaultTTL | number | 3600000 | 默认过期时间（毫秒） |
| enableLRU | boolean | true | 是否启用 LRU 驱逐 |
| cleanupInterval | number | 60000 | 过期条目清理间隔（毫秒） |

## 缓存失效机制

### 失效策略类型

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

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

### 失效策略配置

| 策略类型 | 触发条件 | 适用场景 |
|---------|---------|---------|
| ttl-based | TTL 超时后自动失效 | 频繁变化的 npm 包元数据 |
| lru-based | 缓存满时驱逐最少访问项 | 高频访问的热门包 |
| version-based | package.json 版本变化 | 依赖树结构变更 |
| manual | 显式调用 invalidate() | 调试或强制刷新 |

## 依赖关系缓存

### 依赖解析缓存

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

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

```mermaid
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]()

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

### 环境变量配置

| 环境变量 | 说明 | 默认值 |
|---------|------|--------|
| NPM_SENTINEL_CACHE_ENABLED | 启用缓存功能 | true |
| NPM_SENTINEL_CACHE_TTL | 缓存过期时间（秒） | 3600 |
| NPM_SENTINEL_CACHE_MAX | 最大缓存条目数 | 500 |
| NPM_SENTINEL_CACHE_DEBUG | 开启调试日志 | false |

## 工具级缓存集成

### MCP 工具缓存上下文

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

```mermaid
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 配置 | 失效触发 |
|---------|-----------|---------|---------|
| npmInfo | packageName:version | 1小时 | 版本发布 |
| npmDeps | packageName:version + topology | 6小时 | 版本变更 |
| npmVulns | packageName + deps hash | 30分钟 | 扫描间隔 |
| npmAudit | projectHash | 15分钟 | package.json 变更 |

## 常见问题与故障排查

### 缓存相关问题

**问题：缓存数据过期但仍在使用**
- **原因**：时钟不同步或系统休眠导致 TTL 定时器延迟
- **解决**：检查 NTP 时间同步，确保证券环境时间准确

**问题：内存缓存占用过高**
- **原因**：maxEntries 配置过大或缓存未及时释放
- **解决**：调低 maxEntries，缩短 cleanupInterval 间隔

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

### 调试缓存行为

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

```bash
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. **批量操作优化**：多个包查询时利用缓存批量命中特性

## 参见

- [快速开始指南](../getting-started.md)
- [MCP 工具参考](../tools/)
- [安全扫描机制](./security-scanning.md)
- [依赖解析](./dependency-resolution.md)

---

<!-- evidence_pipeline_checked: true -->
<!-- evidence_injected: true -->

---

## Doramagic 踩坑日志

项目：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

<!-- canonical_name: nekzus/npm-sentinel-mcp; human_manual_source: deepwiki_human_wiki -->