npm-mcp 文档中心

项目概述

npm-mcp 是一个基于 Model Context Protocol (MCP) 的 npm 注册表服务器，它为 AI 助手提供了一套完整的 npm 包管理工具集。通过这个 MCP 服务器，AI 能够在代码编写过程中自动执行包搜索、安全审计、版本兼容性检查、质量分析等操作，极大地提升了开发效率和代码安全性。

该项目的主要目标是解决 AI 编程助手在处理 npm 包时的两大痛点：一是缺乏对包的安全性和兼容性的主动检查能力，二是难以获取包的详细元数据和最佳实践建议。npm-mcp 通过封装 npm 注册表 API 和多种分析工具，使 AI 能够像经验丰富的开发者一样审慎地评估和选择依赖包。

核心功能模块

npm-mcp 提供了六大核心工具模块，每个模块都专注于特定的包管理场景，共同构成了一个完整的包管理辅助系统。

包搜索与发现

search_packages 工具提供了强大的 npm 包搜索能力，支持通过关键词查找相关包，并根据下载量、维护状态等指标对结果进行排序。这个工具是用户寻找合适包的起点，能够快速缩小选择范围。

search_packages 的输入参数包括搜索关键词和可选的结果数量限制，返回结果包含包名、描述、版本、下载量、维护者信息等关键数据。通过与后续的质量分析工具结合使用，AI 能够从搜索结果中筛选出最优选择。

包详情查询

get_package_details 工具用于获取包的详细元数据信息，包括版本历史、依赖关系、发布时间线、维护者列表等。这个工具是了解一个包的完整信息的核心入口，对于评估包的成熟度和稳定性至关重要。

该工具返回的信息结构化程度高，便于 AI 进行后续处理。返回数据包含：包的基本信息（名称、版本、描述）、许可协议和作者信息、版本列表及弃用状态、所有类型的依赖声明、发布节点的时间戳、以及 CDN 分发信息如 tarball 地址和完整性校验值。

安全审计

audit_security 工具集成了 npm 安全审计能力，能够检测已知漏洞并提供修复建议。该工具是 npm-mcp 中最重要的安全功能，确保 AI 在推荐任何包之前都能验证其安全性。

安全审计功能会检查目标包的已知漏洞数据库，对比版本号识别已披露的安全问题，并输出漏洞的严重程度、类型描述和推荐升级版本。对于依赖链较深的项目，这个工具还能递归检查传递依赖的安全状态。

版本兼容性检查

check_compatibility 工具用于检查包与现有依赖的兼容性，特别是 peer dependencies 的满足情况。这个工具对于避免运行时错误至关重要，能够在安装前发现潜在的依赖冲突。

兼容性检查的核心逻辑是验证目标包的 peer dependencies 是否与项目中已安装的包版本相匹配。当检测到冲突时，工具会列出具体的冲突项和缺失的依赖，并提供具体的修复建议。分析结果包括兼容性状态、peer dependencies 详情、冲突和缺失项列表、以及针对问题的具体操作建议。

质量分析

analyze_quality 工具提供全面的包质量评估，涵盖维护状态、下载量、stars、测试覆盖率等多个维度。这个综合评分帮助开发者和 AI 在众多选项中快速识别高质量的包。

质量评估的核心指标包括：维护活跃度（通过 GitHub 活动和数据更新时间判断）、社区认可度（npm 下载量和 GitHub stars）、代码质量（测试覆盖率和 CI 状态）、以及安全性（已知漏洞数量）。分析结果以结构化 JSON 格式返回，便于 AI 进行比较和决策。

依赖项审计

audit_project 工具用于审计项目 package.json 中的所有依赖项。这个工具特别适合在引入新依赖前进行全面的安全检查，确保项目的依赖树中没有已知漏洞。

审计过程会逐个检查 dependencies 和 devDependencies 中的包，针对每个有问题的包输出漏洞信息、严重程度和修复建议。最终生成一个汇总报告，列出需要优先更新的包及其安全影响。

系统架构

npm-mcp 采用分层架构设计，将 MCP 协议层、注册表客户端层和业务逻辑层清晰分离。这种设计确保了代码的可维护性和可扩展性，同时便于独立测试各个组件。

整体架构图

graph TD
    subgraph "客户端层"
        A[AI Assistant<br/>Cursor/Claude Desktop]
    end
    
    subgraph "MCP 协议层"
        B[Server Entry<br/>src/index.ts]
        C[ListToolsRequestSchema]
        D[CallToolRequestSchema]
    end
    
    subgraph "业务逻辑层"
        E[search_packages]
        F[get_package_details]
        G[audit_security]
        H[check_compatibility]
        I[analyze_quality]
        J[audit_project]
    end
    
    subgraph "服务层"
        K[RegistryClient<br/>registry-client.ts]
        L[Cache Manager]
        M[Rate Limiter]
        N[Retry Handler]
    end
    
    subgraph "外部 API"
        O[npm Registry API]
        P[Bundlephobia API]
        Q[GitHub API]
    end
    
    A --> B
    B --> C
    B --> D
    C --> E
    D --> E
    D --> F
    D --> G
    D --> H
    D --> I
    D --> J
    
    E --> K
    F --> K
    G --> K
    H --> K
    I --> K
    J --> K
    
    K --> L
    K --> M
    K --> N
    
    K --> O
    K --> P
    K --> Q

核心组件说明

MCP 服务器入口 (src/index.ts)：负责初始化 MCP 协议处理器，处理工具列表请求和工具调用请求。它将请求路由到对应的工具处理函数，并返回格式化的结果。这个入口文件是整个系统的调度中心，确保 AI 发送的请求能够正确路由到相应的功能模块。

注册表客户端 (registry-client.ts)：封装了与 npm 注册表通信的所有逻辑，包括请求发送、响应解析、缓存管理和限流处理。该客户端实现了以下关键特性：并发限制设置为 10 个请求，防止过度占用 npm API 配额；5 分钟 TTL 的 LRU 缓存，减少重复请求；指数退避重试机制，处理 429 限流响应；以及请求去重，避免同一时间发送相同请求。

工具模块：每个工具都有独立的文件，采用一致的架构模式。工具接收参数、执行验证、执行核心逻辑、格式化结果并返回。所有工具都使用 Zod 进行输入模式验证，确保参数的正确性和安全性。

数据流处理

sequenceDiagram
    participant AI as AI Assistant
    participant MCP as MCP Server
    participant Client as Registry Client
    participant Cache as Cache Layer
    participant API as npm Registry API

    AI->>MCP: Call Tool (search_packages)
    MCP->>Client: Execute Search
    
    alt Cache Hit
        Client->>Cache: Check Cache
        Cache-->>Client: Return Cached
    end
    
    alt Cache Miss
        Client->>API: GET /-/v1/search
        API-->>Client: Search Results
        Client->>Cache: Store Result
    end
    
    Client-->>MCP: Formatted Results
    MCP-->>AI: Tool Response

快速开始

环境要求

npm-mcp 基于 Node.js 18+ 开发，使用原生 fetch API 进行 HTTP 请求。项目构建使用 TypeScript，确保类型安全和代码质量。

安装步骤

首先克隆项目仓库到本地：

git clone https://github.com/alisaitteke/npm-mcp.git
cd npm-mcp

然后安装项目依赖：

npm install

构建 TypeScript 代码：

npm run build

运行测试确保一切正常：

npm test

配置 MCP 客户端

将以下配置添加到 Cursor 的 ~/.cursor/.cursorrules 文件或 Claude Desktop 的 MCP 配置文件：

{
  "mcpServers": {
    "npm-registry": {
      "command": "node",
      "args": ["/path/to/npm-mcp/bin/npm-registry-mcp.js"]
    }
  }
}

使用场景与工作流

场景一：AI 自动安全检查

当 AI 检测到用户请求安装任何 npm 包时，应自动触发安全审计流程，无需用户显式要求。

用户: "安装 express"
    
AI 自动执行:
1. audit_security("express") → 检查已知漏洞
2. get_package_details("express") → 验证维护状态
3. check_compatibility("express") → 确保无依赖冲突
4. 展示结果并推荐安全版本

场景二：智能包推荐

当用户询问关于某个功能需求时，AI 应主动搜索并比较相关包，提供数据驱动的推荐。

用户: "有什么好的日期处理库？"
    
AI 自动执行:
1. search_packages("date time library") → 搜索候选包
2. analyze_quality(date-fns) → 评估质量
3. analyze_quality(dayjs) → 评估质量
4. compare_packages → 对比分析
5. 提供推荐和理由

场景三：项目依赖审计

定期审计项目的完整依赖树，确保没有已知安全漏洞。

用户: "审计我的项目依赖"
    
AI 自动执行:
1. 读取项目 package.json
2. 对每个依赖并行执行 audit_security
3. 汇总所有安全问题
4. 按严重程度排序
5. 提供批量修复命令

API 工具参考

工具列表

search_packages 参数详解

get_package_details 参数详解

audit_security 返回结构

{
  "success": true,
  "package": "package-name",
  "version": "1.0.0",
  "vulnerabilities": {
    "critical": 0,
    "high": 1,
    "medium": 2,
    "low": 0
  },
  "details": [
    {
      "id": "SNYK-JS-PACKAGENAME",
      "severity": "high",
      "title": "Prototype Pollution",
      "url": "https://security.snyk.io/...",
      "fix": "Upgrade to 1.0.1"
    }
  ]
}

缓存与限流机制

缓存策略

注册表客户端实现了智能缓存机制，显著减少重复 API 调用，提升响应速度并降低限流风险。

缓存采用 LRU (Least Recently Used) 策略，当缓存空间不足时自动清理最久未使用的数据。内部可通过 client.clearCache() 方法手动清除缓存。

请求限流

为了遵守 npm Registry 的使用限制，系统实现了严格的并发控制：

• 最大并发请求数：10
• 429 响应处理：指数退避重试
• 指数退避初始延迟：1 秒
• 最大重试次数：3 次

GitHub API 限流说明

质量分析功能使用 GitHub API 获取包的维护者活动和仓库状态。未认证请求的 GitHub API 限制为每小时 60 次请求。在处理大量包时，部分请求可能因限流而失败，这是预期行为。

开发指南

项目结构

npm-mcp/
├── src/
│   ├── index.ts              # MCP 服务器入口
│   ├── registry-client.ts    # npm API 客户端
│   ├── types.ts              # TypeScript 类型定义
│   └── tools/                # MCP 工具实现
│       ├── search-packages.ts
│       ├── package-details.ts
│       ├── security-audit.ts
│       ├── version-compatibility.ts
│       ├── quality-analysis.ts
│       └── npx-command.ts
├── test/                     # Vitest 测试文件
├── bin/                      # 可执行文件
│   └── npm-registry-mcp.js   # npx 入口点
├── server.json               # MCP 注册表元数据
└── package.json

添加新工具流程

第一步：创建工具文件

在 src/tools/ 目录下创建新的工具文件，使用 Zod 进行输入验证：

import { z } from 'zod';
import { RegistryClient } from '../registry-client.js';

export const MyToolSchema = z.object({
  param: z.string(),
});

export async function myTool(
  params: z.infer<typeof MyToolSchema>,
  client: RegistryClient
): Promise<string> {
  const validated = MyToolSchema.parse(params);
  // 工具实现逻辑
  return JSON.stringify({ success: true });
}

第二步：注册工具

在 src/index.ts 中将新工具添加到 ListToolsRequestSchema 和 CallToolRequestSchema 的处理逻辑中。

第三步：添加测试

在 test/ 目录下创建对应的测试文件，确保覆盖正常路径和异常路径：

describe('My Tool', () => {
  it('should work correctly', async () => {
    // 测试实现
  });
});

可用脚本命令

故障排查

服务器无法启动

首先确认 Node.js 版本符合要求：

node --version  # 需要 18.0.0 或更高版本

然后尝试重新构建：

npm run build

如果使用 bin 可执行文件，确保其有执行权限：

chmod +x bin/npm-registry-mcp.js

测试失败

清除 node_modules 和 lock 文件后重新安装：

rm -rf node_modules package-lock.json
npm install
npm run build
npm test

GitHub API 限流

质量分析使用 GitHub API 获取数据，未认证请求每小时限制 60 次。部分包的质量分析可能因限流而返回不完整数据，这是正常的外部依赖限制。

参与贡献

我们欢迎社区贡献！请阅读 CONTRIBUTING.md 了解详细的贡献指南。核心贡献流程包括：创建功能分支（使用 feature/、fix/、docs/ 等前缀）、遵循 Conventional Commits 规范编写提交信息、为新功能添加测试、确保所有测试通过后提交 Pull Request。

分支命名规范：feature/ 用于新功能、fix/ 用于错误修复、docs/ 用于文档更新、test/ 用于测试相关、refactor/ 用于代码重构。

提交信息应遵循以下格式：feat: add new feature、fix: resolve bug、docs: update documentation、test: add test coverage、refactor: simplify logic。

相关资源

• 开发指南 - 详细的开发环境配置和架构说明
• AI 使用指南 - AI 助手的自动触发规则和最佳实践
• 提示词参考 - MCP 快捷命令和自定义工作流
• 贡献指南 - 代码贡献规范和 Pull Request 流程
• 能力分析 - 包能力检测详解
• productivity 工作流 - 常用场景的组合使用示例

项目概述

npm-mcp 充当 AI 助手与 npm 注册表之间的桥梁，使 AI 能够执行以下操作：

• 搜索和发现 npm 包
• 获取包详细信息
• 进行安全审计
• 检查版本兼容性
• 分析包能力和质量
• 生成快速开始代码示例

资料来源：DEVELOPMENT.md:1-15

核心工具

npm-mcp 提供一系列 MCP 工具，每个工具负责特定的 npm 包管理功能。

工具列表

资料来源：DEVELOPMENT.md:20-35

search_packages

搜索 npm 注册表中的包，支持关键词和模糊匹配。

search_packages({
  query: "react state management",
  size: 5
})

返回结果包含包名、描述、版本、下载量等信息。

package_details

获取包的完整信息，包括版本、依赖、许可证、发布时间等。

package_details({
  packageName: "axios",
  version: "1.6.0"
})

返回数据结构：

{
  "success": true,
  "package": {
    "name": "axios",
    "version": "1.6.0",
    "description": "Promise based HTTP client",
    "isLatest": true
  },
  "metadata": {
    "license": "MIT",
    "maintainers": [...],
    "keywords": [...]
  },
  "dependencies": {
    "dependencies": {...},
    "devDependencies": {...},
    "peerDependencies": {...}
  },
  "stats": {
    "weeklyDownloads": "45,000,000",
    "period": "2024-01-01 to 2024-01-08"
  }
}

资料来源：src/tools/package-details.ts:1-100

check_compatibility

检查包升级时的版本兼容性，识别潜在的破坏性变更。

check_compatibility({
  packageName: "express",
  fromVersion: "4.17.1",
  toVersion: "4.18.2"
})

返回结果包含：

• 破坏性变更列表
• 依赖差异分析
• SemVer 摘要
• 兼容性建议

资料来源：src/tools/version-compatibility.ts:1-80

analyze_capabilities

分析包的现代特性支持情况：

{
  "moduleSystem": {
    "esm": true,
    "commonjs": true,
    "dualPackage": true
  },
  "typescript": {
    "hasTypes": true,
    "typesLocation": "./dist/index.d.ts"
  },
  "platform": {
    "node": true,
    "browser": true
  }
}

资料来源：CAPABILITIES.md:1-60

架构设计

技术栈

资料来源：DEVELOPMENT.md:25-30

项目结构

npm-mcp/
├── src/
│   ├── index.ts              # MCP 服务器入口
│   ├── registry-client.ts    # NPM API 客户端
│   ├── types.ts              # 共享类型定义
│   └── tools/
│       ├── search-packages.ts    # 搜索工具
│       ├── package-details.ts   # 包详情工具
│       ├── security-audit.ts    # 安全审计工具
│       ├── version-compatibility.ts  # 版本兼容性工具
│       ├── quality-analysis.ts   # 质量分析工具
│       └── npx-command.ts       # NPX 命令工具
├── test/                     # Vitest 测试
├── bin/
│   └── npm-registry-mcp.js   # npx 入口点
├── server.json              # MCP 注册表元数据
└── package.json

资料来源：DEVELOPMENT.md:10-20

核心组件架构

graph TD
    A[AI 助手] -->|MCP 协议| B[MCP 服务器]
    B --> C[工具调度器]
    C --> D[registry-client]
    D -->|HTTP 请求| E[NPM 注册表 API]
    E -->|缓存响应| F[LRU 缓存]
    D -->|并发控制| G[请求限流器]
    F -->|5分钟 TTL| D
    G -->|最多 10 并发| D

注册表客户端

registry-client.ts 是核心 HTTP 客户端，负责与 npm 注册表 API 通信。

主要特性：

资料来源：DEVELOPMENT.md:22-25

请求处理流程

sequenceDiagram
    participant AI as AI 助手
    participant MCP as MCP 服务器
    participant Client as Registry Client
    participant Cache as 缓存
    participant NPM as NPM API

    AI->>MCP: search_packages("axios")
    MCP->>Client: fetchPackage(query)
    Client->>Cache: check(key)
    alt 缓存命中
        Cache-->>Client: 返回缓存数据
    else 缓存未命中
        Client->>NPM: GET /-/v1/search
        NPM-->>Client: 搜索结果
        Client->>Cache: store(key, data)
    end
    Client-->>MCP: 结果数据
    MCP-->>AI: JSON 响应

与 AI 助手的集成

MCP 资源

npm-mcp 通过 MCP 协议暴露资源，AI 助手可以读取这些资源来了解包的安全状态和兼容性要求。

{
  "resources": {
    "security-check": "MUST check security before adding packages",
    "compatibility-check": "Verify version compatibility before install",
    "capabilities-check": "Analyze package capabilities for modern projects"
  }
}

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

自动化工作流

npm-mcp 支持 AI 助手自动执行安全检查，无需用户显式请求：

graph LR
    A[用户请求] --> B{AI 检测到包名}
    B -->|自动触发| C[audit_security]
    C --> D{是否有漏洞?}
    D -->|是| E[警告 + 建议安全版本]
    D -->|否| F[继续正常流程]
    E --> G[提供安全安装命令]
    F --> H[执行原请求]

自动化场景示例：

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

提示词集成

npm-mcp 支持自定义提示词，可用于自动化常见工作流：

// 示例：check_before_install 使用流程
User: "check_before_install axios"
AI 自动执行:
  1. audit_security("axios")
  2. check_compatibility("axios")
  3. analyze_capabilities("axios")
  4. 返回综合建议

资料来源：PROMPTS.md:1-40

使用方式

安装

npm install -g @alisaitteke/npm-mcp

配置 Cursor

在 Cursor 设置中添加 MCP 服务器：

{
  "mcpServers": {
    "npm-registry": {
      "command": "npx",
      "args": ["-y", "@alisaitteke/npm-registry-mcp"]
    }
  }
}

开发设置

git clone https://github.com/alisaitteke/npm-mcp.git
cd npm-mcp
npm install
npm run build

资料来源：DEVELOPMENT.md:1-10

常用命令

资料来源：DEVELOPMENT.md:5-10

常见问题排查

服务器无法启动

GitHub 速率限制

质量分析工具使用 GitHub API，未认证限制为 60 请求/小时，部分包分析可能失败。

解决方案：

• 设置 GITHUB_TOKEN 环境变量
• 使用认证的 GitHub 应用

资料来源：DEVELOPMENT.md:45-50

测试失败

rm -rf node_modules package-lock.json
npm install
npm run build
npm test

扩展开发

添加新工具

步骤 1：创建工具文件

// src/tools/my-tool.ts
import { z } from 'zod';
import { RegistryClient } from '../registry-client.js';

export const MyToolSchema = z.object({
  param: z.string(),
});

export async function myTool(
  params: z.infer<typeof MyToolSchema>,
  client: RegistryClient
): Promise<string> {
  const validated = MyToolSchema.parse(params);
  // 实现逻辑
  return JSON.stringify({ success: true });
}

步骤 2：注册到服务器

在 src/index.ts 中：

• 在 ListToolsRequestSchema 处理器中添加工具列表
• 在 CallToolRequestSchema 处理器中调用工具处理器

步骤 3：添加测试

// test/my-tool.test.ts
describe('My Tool', () => {
  it('should work correctly', async () => {
    // 测试实现
  });
});

资料来源：CONTRIBUTING.md:80-120

分支命名规范

提交规范

遵循 Conventional Commits 格式：

feat: add new search filter
fix: resolve caching issue
docs: update README examples
test: add coverage for quality analysis
refactor: simplify version comparison logic

资料来源：CONTRIBUTING.md:30-45

最佳实践

AI 助手使用建议

1. 始终检查安全性 — 推荐安装前先运行 audit_security
2. 主动检查 — 不要等待用户询问，AI 应自动检测包名
3. 批量操作 — 并行检查多个包
4. 清晰警告 — 使用 ⚠️ 🔒 ✅ 表情符号提高可见性
5. 可操作的输出 — 始终提供安全的安装命令

现代化项目检查项

应具备的特性：

• ✅ dualPackage: true 或 esm: true
• ✅ hasTypes: true
• ✅ exports.hasExports: true
• ✅ 最近的 engines.node 版本

危险信号：

• ⚠️ 无 ESM 支持（仅 CommonJS）
• ⚠️ 无 TypeScript 类型
• ⚠️ 旧的 Node.js 引擎要求
• ⚠️ 无 exports 字段（遗留结构）

资料来源：CAPABILITIES.md:70-90

参见

• 安全审计文档 — 详细的漏洞检测机制
• 开发指南 — 架构和工具参考
• AI 使用指南 — 自动化工作流配置
• 贡献指南 — 代码贡献流程

环境要求

系统 prerequisites

npm-mcp 基于 Node.js 原生 fetch API 构建，因此对 Node.js 版本有明确要求：

确认 Node.js 版本：

node --version

资料来源：DEVELOPMENT.md:1-5

GitHub API 限制说明

质量分析功能依赖 GitHub API，未认证请求限制为每小时 60 次。部分包的分析可能因此失败，这是预期行为。

安装步骤

方式一：直接安装（推荐）

通过 npm 全局安装或项目本地安装：

# 全局安装
npm install -g @alisaitteke/npm-mcp

# 或项目本地安装
npm install @alisaitteke/npm-mcp

安装完成后可通过 npx 直接运行：

npx npm-registry-mcp

资料来源：DEVELOPMENT.md:1-5

方式二：源码安装（开发用途）

适用于需要自定义修改或参与开发贡献的场景：

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

# 安装依赖
npm install

# 编译 TypeScript
npm run build

编译成功后，可执行文件位于 bin/npm-registry-mcp.js。

资料来源：CONTRIBUTING.md:5-12

方式三：二进制执行权限设置

源码安装后需要赋予执行权限：

chmod +x bin/npm-registry-mcp.js

项目结构

npm-mcp/
├── src/
│   ├── index.ts              # MCP 服务器主入口
│   ├── registry-client.ts    # NPM API 客户端（包含缓存、重试、限流）
│   ├── types.ts              # TypeScript 类型定义
│   └── tools/
│       ├── search-packages.ts        # 包搜索工具
│       ├── package-details.ts        # 包详情工具
│       ├── security-audit.ts         # 安全审计工具
│       ├── version-compatibility.ts  # 版本兼容性检查
│       ├── quality-analysis.ts       # 质量分析工具
│       └── npx-command.ts            # npx 命令分析
├── test/                     # Vitest 测试用例
├── bin/
│   └── npm-registry-mcp.js   # npx 入口点
├── server.json              # MCP 注册表元数据
└── package.json

资料来源：DEVELOPMENT.md:15-32

MCP 服务器配置

MCP 客户端集成

npm-mcp 作为 MCP 服务器运行，需要在 MCP 客户端（如 Cursor、Claude Desktop）中配置。以下是典型的配置文件结构：

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

资源配置（AI 自动化）

MCP 资源是被动加载的——当 MCP 连接时自动加载，无需额外设置。资源文件定义在 src/index.ts 中：

资料来源：AUTOMATIC.md:95-110

客户端配置

注册表客户端参数

RegistryClient 是核心组件，负责与 npm 注册表 API 通信：

// src/registry-client.ts 中的默认配置
const DEFAULT_CONFIG = {
  maxConcurrent: 10,        // 最大并发请求数
  cacheTTL: 5 * 60 * 1000,  // 缓存 TTL: 5分钟
  retryAttempts: 3,         // 重试次数
  retryDelay: 1000,         // 重试延迟基数（指数退避）
};

请求限流机制

graph TD
    A[发起请求] --> B{并发数 < 10?}
    B -->|是| C[执行请求]
    B -->|否| D[等待队列]
    D --> C
    C --> E{响应状态}
    E -->|200| F[返回结果]
    E -->|429| G[指数退避等待]
    G --> C
    E -->|5xx| H[重试]
    H -->|attempt < 3| C
    H -->|attempt >= 3| I[返回错误]

• 并发限制：最多 10 个并发请求
• 429 处理：收到速率限制响应时自动指数退避
• 缓存：包元数据、下载统计、GitHub 数据缓存 5 分钟

资料来源：DEVELOPMENT.md:34-38

缓存管理

内部缓存可通过以下方式清除：

client.clearCache();

可用脚本命令

资料来源：DEVELOPMENT.md:6-13

AI 平台配置

Cursor 配置

在 ~/.cursor/.cursorrules（全局规则文件）中添加：

# Global NPM Safety Rules

For ANY project with package.json:
- Before suggesting npm install: use npm-registry-mcp audit_security
- On package.json edit: scan new dependencies
- On npx mention: use npm-registry-mcp analyze_npx_command
- Auto-suggest updates for vulnerable packages

资料来源：AI_USAGE.md:80-90

Claude Desktop 配置

Claude Desktop 用户可在对话中自然提及需求：

"Can you check if express is safe to install?"
→ AI 自动使用 check_before_install 提示

"Find me a good date library"
→ AI 自动使用 find_package 提示

常见问题排查

服务器无法启动

按以下顺序排查：

``bash node --version ``

1. 检查 Node.js 版本：确保 >= 18.0.0

``bash rm -rf node_modules package-lock.json npm install npm run build ``

1. 重新编译：删除 node_modules 和 lock 文件后重新安装

``bash chmod +x bin/npm-registry-mcp.js ``

1. 检查二进制权限：

资料来源：DEVELOPMENT.md:52-62

GitHub API 速率限制

质量分析使用 GitHub API，未认证限制为 60 请求/小时。若部分包分析失败属正常现象。

解决方案：

• 使用 GitHub Personal Access Token 配置更高限制
• 等待速率限制重置（约 1 小时）

测试失败

完整的测试环境重置步骤：

rm -rf node_modules package-lock.json
npm install
npm run build
npm test

资料来源：DEVELOPMENT.md:62-68

环境变量配置

可选环境变量

配置示例

# 设置 GitHub Token 提高 API 限制
export GITHUB_TOKEN=ghp_xxxxxxxxxxxx

# 使用私有注册表
export NPM_REGISTRY_URL=https://registry.mycompany.com

# 生产环境运行
export NODE_ENV=production

验证安装

安装完成后可通过以下方式验证：

# 检查 MCP 服务器是否正常运行
npx npm-registry-mcp --version

# 或通过 MCP 客户端测试工具调用
# 使用 search_packages 查询一个包

扩展配置

添加自定义工具

```typescript // src/tools/my-tool.ts import { z } from 'zod'; import { RegistryClient } from '../registry-client.js';

1. 在 src/tools/ 目录下创建新的工具文件：

export const MyToolSchema = z.object({ param: z.string(), });

export async function myTool(params, client: RegistryClient) { // 实现逻辑 } ```

1. 在 src/index.ts 中注册工具：

• 在 ListToolsRequestSchema 中列出工具
• 在 CallToolRequestSchema 中调用处理器

1. 添加测试用例：test/<name>.test.ts

资料来源：DEVELOPMENT.md:70-80

相关文档

• 快速入门指南 - 快速上手 npm-mcp
• 工具参考 - 所有可用 MCP 工具详细说明
• AI 集成指南 - 在 AI 助手中使用 npm-mcp
• 开发指南 - 项目开发和贡献指南
• 贡献指南 - 代码贡献流程

概述

npm-mcp 是一个基于 MCP（Model Context Protocol）协议的服务器实现，专门用于与 NPM 注册表进行交互。该项目为 AI 助手（如 Cursor、Claude Desktop）提供了原生的 NPM 包管理能力，使其能够在代码生成过程中自动执行安全检查、依赖分析和包搜索等操作，而无需依赖外部网络搜索。资料来源：AI_USAGE.md:1-15

核心价值

该项目解决了 AI 编程助手在依赖管理方面的关键痛点。传统方式下，AI 助手在生成代码时可能使用过时版本或存在安全漏洞的包，而 npm-mcp 通过在服务端集成 NPM 注册表 API，使得 AI 能够自动验证包的版本安全性、兼容性以及质量指标。资料来源：AUTOMATIC.md:1-20

环境要求与安装

系统要求

资料来源：DEVELOPMENT.md:1-10

安装步骤

# 克隆项目仓库
git clone https://github.com/alisaitteke/npm-mcp.git
cd npm-mcp

# 安装项目依赖
npm install

# 构建项目
npm run build

安装完成后，可通过以下方式运行服务器：

# 直接运行（需要 Node.js 18+）
node bin/npm-registry-mcp.js

# 或使用 npx
npx @alisaitteke/npm-mcp

资料来源：CONTRIBUTING.md:1-15

在 AI 客户端中配置

不同 AI 客户端的配置方式略有差异，但核心都是将 MCP 服务器路径添加到配置文件中。

Cursor 配置示例

在 ~/.cursor/mcp.json 或项目 .cursor/mcp.json 中添加：

{
  "mcpServers": {
    "npm-registry-mcp": {
      "command": "node",
      "args": ["/path/to/npm-mcp/bin/npm-registry-mcp.js"]
    }
  }
}

Claude Desktop 配置示例

在 ~/Library/Application Support/Claude/claude_desktop_config.json 中添加相同配置。

资料来源：AI_USAGE.md:80-95

核心工具快速参考

npm-mcp 提供了多个 MCP 工具，每个工具专注于特定的功能领域。以下是核心工具的快速参考表：

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

安全审计工具详解

audit_security 是使用频率最高的工具之一，用于检查 NPM 包是否存在已知的安全漏洞：

// 调用示例
audit_security({
  packageName: "express",
  version: "4.18.2"  // 可选，不提供则检查最新版本
})

返回结果示例

{
  "success": true,
  "package": "express",
  "version": "4.18.2",
  "vulnerabilities": {
    "critical": 0,
    "high": 0,
    "medium": 0,
    "low": 0
  },
  "recommendation": "✅ No known vulnerabilities. Safe to install."
}

资料来源：AI_USAGE.md:30-60

包搜索工具详解

search_packages 允许通过关键词搜索 NPM 注册表中的包：

// 搜索 TypeScript 相关的 HTTP 客户端库
search_packages({
  query: "typescript http client"
})

搜索结果按相关性排序，包含包的下载量、维护状态和质量评分等关键信息。

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

基础使用示例

工作流程一：安装前安全检查

在推荐任何包安装之前，AI 助手应自动执行安全检查流程：

graph TD
    A[用户请求安装包] --> B{调用 audit_security}
    B --> C{发现漏洞?}
    C -->|是| D[显示安全警告]
    D --> E[推荐安全版本]
    C -->|否| F{调用 check_compatibility}
    F --> G{兼容?}
    G -->|是| H[✅ 允许安装]
    G -->|否| I[⚠️ 显示兼容问题]
    H --> J[提供安装命令]
    I --> J

该工作流程确保每个包安装都经过安全和兼容性验证。资料来源：AI_USAGE.md:20-35

工作流程二：查找替代包

当用户询问某个包的替代方案时，AI 应自动搜索并比较：

// 用户问：有没有比 lodash 更轻量的替代品?
find_similar_packages({ packageName: "lodash" })

// 返回类似包列表，包含：
// - date-fns（日期处理）
// - lodash-es（ESM 版本）
// - nanoid（ID 生成）

资料来源：PRODUCTIVITY.md:50-80

工作流程三：批量审计项目依赖

当用户提供 package.json 或项目路径时，AI 应自动审计所有依赖：

// 自动触发场景
用户: "帮我检查项目依赖安全性"
用户: "audit_project"
用户: "npm install typescript"  // 隐式触发

// AI 自动执行：
1. 提取 package.json 中的 dependencies
2. 对每个包调用 audit_security（并行执行）
3. 生成漏洞报告表格
4. 提供更新命令

资料来源：AUTOMATIC.md:40-70

常用工作流

自动触发机制

npm-mcp 设计了智能的自动触发机制，AI 助手无需显式调用工具即可自动执行安全检查。以下是触发规则表：

资料来源：AI_USAGE.md:100-120

智能提示词（Prompts）

项目提供了预定义的 MCP Prompts，可以作为 AI 助手的快捷命令使用：

#### /check_before_install

安装前的完整安全检查，执行流程如下：

1. 运行 audit_security 检查漏洞
2. 获取 package_details 验证维护状态
3. 检查 compatibility 兼容性
4. 显示清晰的 ✅/⚠️ 推荐结果

使用示例

/check_before_install express

典型响应

✅ [email protected] is safe to install

Security: No known vulnerabilities
Compatibility: ✅ No peer dependency conflicts
Maintenance: Active (last update: 2 days ago)

Install: npm install [email protected]

资料来源：PROMPTS.md:10-40

#### /find_package

根据用例查找并比较包：

/find_package state management
/find_package date library
/find_package testing framework

执行流程

1. 搜索 NPM 注册表
2. 获取前 3 名结果
3. 检查每个包的安全性和质量
4. 推荐最佳选项

资料来源：PROMPTS.md:45-70

#### /audit_project

批量审计项目所有依赖：

/audit_project

典型输出

🔍 Auditing 25 dependencies...

⚠️ 2 packages need updates:

1. [email protected] → 4.17.21
   - Issue: Open redirect
   - Fix: npm install [email protected]

2. [email protected] → 2.29.4
   - Issue: Path traversal
   - Fix: npm install [email protected]

Total: 25 packages, 2 need updates

资料来源：PROMPTS.md:75-95

响应模板

为保持输出的一致性，建议使用以下模板：

安全响应模板

✅ {packageName}@{version} is safe to install

Security: No vulnerabilities
Compatibility: ✅ Compatible with your dependencies
Quality: {score}/100 ({downloads} weekly downloads)

Install:
npm install {packageName}@{version}

警告响应模板

⚠️ SECURITY WARNING: {packageName}@{version} has {count} vulnerabilities

Severity: {severity}
Issue: {description}
Safe version: {safeVersion}

Recommended:
npm install {packageName}@{safeVersion}

资料来源：AI_USAGE.md:130-160

故障排查

常见问题与解决方案

资料来源：DEVELOPMENT.md:35-50

测试与调试

如果遇到功能异常，可通过以下步骤进行调试：

# 清除缓存重新安装
rm -rf node_modules package-lock.json
npm install

# 重新构建
npm run build

# 运行测试套件
npm test

# 检查 TypeScript 类型
npm run typecheck

资料来源：CONTRIBUTING.md:45-55

缓存与请求限制

项目内置了以下优化机制：

• 缓存策略：包元数据、下载统计、GitHub 数据缓存 5 分钟
• 并发限制：最大 10 个并发请求
• 429 处理：遇到速率限制时自动指数退避重试

如需清除内部缓存，可调用 client.clearCache() 方法。资料来源：DEVELOPMENT.md:20-25

相关资源

概述

npm-mcp 是一个基于 Model Context Protocol (MCP) 的 npm 注册表服务工具集，为 AI 助手提供与 npm 注册表交互的能力。该项目使 AI 能够安全地查询、审计和分析 npm 包，无需直接访问外部网络或执行危险的安装命令。 资料来源：DEVELOPMENT.md

项目采用 TypeScript 开发，要求 Node.js 18 及以上版本，利用原生 fetch API 进行网络请求。架构设计遵循模块化原则，每个功能作为独立的工具实现，便于维护和扩展。 资料来源：DEVELOPMENT.md:1-15

核心架构组件

组件概览

资料来源：CONTRIBUTING.md:65-75

系统架构图

graph TD
    A[AI 助手] -->|MCP Protocol| B[MCP Server<br/>src/index.ts]
    B --> C[Tool Router<br/>CallToolRequestSchema]
    
    C --> D[search-packages<br/>包搜索]
    C --> E[package-details<br/>包详情]
    C --> F[security-audit<br/>安全审计]
    C --> G[version-compatibility<br/>版本兼容性]
    C --> H[quality-analysis<br/>质量分析]
    C --> I[npx-command<br/>NPX 命令]
    C --> J[analyze_capabilities<br/>能力分析]
    C --> K[find_similar_packages<br/>相似包查找]
    C --> L[compare_packages<br/>包对比]
    C --> M[generate_quick_start<br/>快速入门代码]
    
    D --> N[Registry Client<br/>registry-client.ts]
    E --> N
    F --> N
    G --> N
    H --> N
    I --> N
    J --> N
    K --> N
    L --> N
    M --> N
    
    N -->|HTTP| O[npm Registry API]
    N -->|HTTP| P[GitHub API]
    
    N --> Q[Cache Layer<br/>LRU Cache<br/>5min TTL]
    N --> R[Rate Limiter<br/>Max 10 concurrent]

注册表客户端架构

RegistryClient 是整个系统的核心网络层，负责所有与外部 API 的通信。它实现了缓存机制、并发限制和指数退避策略，确保在高并发场景下的稳定性。 资料来源：DEVELOPMENT.md:18-20

客户端配置参数

资料来源：DEVELOPMENT.md:18-20

缓存机制

注册表客户端使用 LRU（最近最少使用）缓存策略，缓存内容包括包元数据、下载统计和 GitHub 信息。缓存可通过 client.clearCache() 方法手动清除。 资料来源：DEVELOPMENT.md:22-23

sequenceDiagram
    participant Client as RegistryClient
    participant Cache as LRU Cache
    participant API as npm Registry API
    
    Client->>Cache: 检查缓存
    alt 缓存命中
        Cache-->>Client: 返回缓存数据
    else 缓存未命中
        Client->>API: 请求数据
        API-->>Client: 返回数据
        Client->>Cache: 存储数据 (TTL: 5min)
    end

速率限制处理

graph LR
    A[请求发送] --> B{响应状态}
    B -->|200 OK| C[返回数据]
    B -->|429 Too Many Requests| D[指数退避等待]
    D --> E[重试请求]
    E --> B
    B -->|其他错误| F[返回错误信息]

工具模块架构

工具列表与分类

资料来源：DEVELOPMENT.md:25-31

工具实现模式

每个工具遵循统一的实现模式，使用 Zod 进行输入验证，并通过 RegistryClient 与 npm API 交互。

graph TD
    A[工具入口] --> B[Zod Schema 验证]
    B --> C{验证结果}
    C -->|失败| D[返回错误 JSON]
    C -->|成功| E[RegistryClient 调用]
    E --> F{npm API 响应}
    F -->|成功| G[数据处理]
    F -->|失败| H[错误处理]
    G --> I[返回成功 JSON]
    H --> J[返回错误 JSON]

#### 示例：包详情工具

// 资料来源：src/tools/package-details.ts
import { z } from 'zod';
import { RegistryClient } from '../registry-client.js';

// Zod 输入验证 Schema
export const PackageDetailsSchema = z.object({
  packageName: z.string(),
  version: z.string().optional(),
});

// 工具处理函数
export async function getPackageDetails(
  params: z.infer<typeof PackageDetailsSchema>,
  client: RegistryClient
): Promise<string> {
  const validated = PackageDetailsSchema.parse(params);
  // 实现逻辑...
}

#### 示例：版本兼容性检查

// 资料来源：src/tools/version-compatibility.ts
export async function checkCompatibility(
  params: z.infer<typeof CompatibilitySchema>,
  client: RegistryClient
): Promise<string> {
  const validated = CompatibilitySchema.parse(params);
  
  const result = {
    success: true,
    compatible: isCompatible,
    analysis: {
      peerDependencies: {
        total: Object.keys(peerDeps).length,
        compatible: compatible.length,
        conflicts: conflicts.length,
        missing: missing.length,
      }
    },
    recommendation: isCompatible 
      ? 'Package is compatible...'
      : 'Compatibility issues detected...'
  };
  
  return JSON.stringify(result, null, 2);
}

数据模型

包详情响应结构

interface PackageDetailsResponse {
  success: boolean;
  package: {
    name: string;
    version: string;
    description: string;
    isLatest: boolean;
    deprecated: string | null;
  };
  metadata: {
    license: string;
    author: object;
    maintainers: object[];
    keywords: string[];
    homepage: string;
    repository: object;
    bugs: object;
  };
  versions: {
    latest: string;
    tags: object;
    total: number;
    recent: string[];
    deprecatedVersions: Array<{ version: string; message: string }>;
  };
  dependencies: {
    dependencies: object;
    devDependencies: object;
    peerDependencies: object;
    optionalDependencies: object;
  };
  dist: {
    tarball: string;
    shasum: string;
    integrity: string;
    fileCount: number;
    unpackedSize: string;
  };
  timestamps: {
    created: string;
    modified: string;
    versionPublished: string;
  };
  stats: {
    weeklyDownloads: string;
    period: string;
  };
}

资料来源：src/tools/package-details.ts:1-50

兼容性检查响应结构

interface CompatibilityResponse {
  success: boolean;
  package: string;
  version: string;
  compatible: boolean;
  analysis: {
    peerDependencies: {
      total: number;
      compatible: number;
      conflicts: number;
      missing: number;
    };
    details: {
      compatible: Array<{ package: string; required: string; installed: string }>;
      conflicts: Array<{ package: string; required: string; installed: string; neededBy: string }>;
      missing: Array<{ package: string; required: string }>;
    };
  };
  recommendation: string;
  suggestedActions: string[];
}

资料来源：src/tools/version-compatibility.ts:60-90

MCP 协议集成

请求处理流程

graph TD
    A[MCP Request] --> B[ListToolsRequestSchema]
    A --> C[CallToolRequestSchema]
    
    B --> D[返回工具列表]
    D --> E[工具名称、描述、参数 Schema]
    
    C --> F{工具名称匹配}
    F -->|search_packages| G[调用搜索工具]
    F -->|get_package_details| H[调用详情工具]
    F -->|audit_security| I[调用安全审计]
    F -->|check_compatibility| J[调用兼容性检查]
    F -->|其他| K[调用对应工具]
    
    G --> L[RegistryClient]
    H --> L
    I --> L
    J --> L
    K --> L
    
    L --> M[JSON 响应]
    M --> N[MCP Response]

工具注册机制

在 src/index.ts 中，所有工具需要在两个 schema 中注册：

1. ListToolsRequestSchema：声明工具列表、描述和输入参数
2. CallToolRequestSchema：路由工具调用到具体处理函数

// 资料来源：src/index.ts (架构示意)
const tools = [
  { name: 'search_packages', schema: SearchPackagesSchema, handler: searchPackages },
  { name: 'get_package_details', schema: PackageDetailsSchema, handler: getPackageDetails },
  // ... 其他工具
];

错误处理机制

统一错误响应格式

所有工具使用一致的错误响应格式，便于 AI 助手解析和处理：

{
  "success": false,
  "error": "错误信息描述",
  "packageName": "包名称（如适用）",
  "version": "版本号（如适用）"
}

资料来源：src/tools/package-details.ts:80-90

错误处理流程

graph TD
    A[执行工具函数] --> B{捕获异常}
    B -->|无异常| C[返回成功 JSON]
    B -->|有异常| D{异常类型}
    D -->|Zod 验证错误| E[返回验证错误信息]
    D -->|Registry 错误| F[返回 API 错误信息]
    D -->|其他异常| G[返回未知错误信息]
    
    E --> H[错误 JSON 响应]
    F --> H
    G --> H

扩展架构

添加新工具的流程

graph LR
    A[创建工具文件] -->|src/tools/<name>.ts| B[定义 Zod Schema]
    B --> C[实现工具函数]
    C --> D[注册到 index.ts]
    D --> E[添加工具测试]
    E --> F[test/<name>.test.ts]

新工具模板

// 资料来源：CONTRIBUTING.md:80-95
import { z } from 'zod';
import { RegistryClient } from '../registry-client.js';

// 1. 定义 Zod Schema
export const MyToolSchema = z.object({
  param: z.string(),
});

// 2. 实现工具函数
export async function myTool(
  params: z.infer<typeof MyToolSchema>,
  client: RegistryClient
): Promise<string> {
  const validated = MyToolSchema.parse(params);
  // 实现逻辑
  return JSON.stringify({ success: true });
}

在服务器中注册

// 资料来源：CONTRIBUTING.md:97-105
// src/index.ts
import { myTool } from './tools/my-tool.js';

// 添加到 ListToolsRequestSchema handler
// 添加到 CallToolRequestSchema handler

项目目录结构

npm-mcp/
├── src/
│   ├── index.ts              # MCP 服务器入口
│   ├── registry-client.ts    # npm API 客户端
│   ├── types.ts              # TypeScript 类型定义
│   └── tools/
│       ├── search-packages.ts      # 包搜索
│       ├── package-details.ts      # 包详情
│       ├── security-audit.ts       # 安全审计
│       ├── version-compatibility.ts # 版本兼容性
│       ├── quality-analysis.ts     # 质量分析
│       ├── npx-command.ts          # NPX 命令
│       ├── analyze_capabilities.ts # 能力分析
│       ├── find_similar_packages.ts # 相似包查找
│       ├── compare_packages.ts      # 包对比
│       └── quick-start.ts          # 快速入门代码
├── test/                     # Vitest 测试
├── bin/
│   └── npm-registry-mcp.js   # npx 入口点
├── server.json               # MCP 注册表元数据
├── package.json
├── DEVELOPMENT.md
└── CONTRIBUTING.md

资料来源：CONTRIBUTING.md:65-78

技术栈

资料来源：DEVELOPMENT.md:12-15

参见

• 开发指南 - 详细的开发设置和脚本说明
• 贡献指南 - 代码贡献流程和项目规范
• AI 使用指南 - AI 助手集成最佳实践
• MCP 提示词 - 可用提示词和工作流

概述

npm-mcp 作为 MCP（Model Context Protocol）服务器，需要频繁与 npm 注册表 API 进行交互以获取包信息、版本数据、安全审计结果等。为了提高性能并减少对外部 API 的依赖，项目实现了一套完整的数据管理与缓存系统。

核心设计目标：

• 减少重复的网络请求，提高响应速度
• 防止 API 限流，通过智能缓存和请求控制
• 确保数据一致性，在缓存过期时自动刷新
• 提供可观测性，便于调试和监控

资料来源：DEVELOPMENT.md:1-15

架构设计

整体架构图

graph TD
    A[工具层 Tools] --> B[注册表客户端 RegistryClient]
    B --> C[缓存层 LRU Cache]
    B --> D[并发控制器 Semaphore]
    B --> E[重试机制 Retry Logic]
    D --> F[NPM Registry API]
    D --> G[Bundlephobia API]
    D --> H[GitHub API]
    C --> I{数据可用?}
    I -->|是| J[返回缓存数据]
    I -->|否| F
    F --> C

核心组件

资料来源：DEVELOPMENT.md:20-25

缓存策略

缓存类型与 TTL

npm-mcp 采用多种缓存策略以平衡数据新鲜度和性能：

graph LR
    A[请求进来] --> B{缓存中存在?}
    B -->|是,未过期| C[返回缓存数据]
    B -->|否或已过期| D[发起新请求]
    D --> E[更新缓存]
    E --> C

#### 缓存数据分类

资料来源：DEVELOPMENT.md:28-30

LRU 缓存实现

缓存模块采用 LRU（Least Recently Used，最近最少使用）策略，当缓存达到容量上限时，自动清除最久未使用的数据项。

缓存工作流程：

sequenceDiagram
    participant Client as 客户端
    participant Cache as LRU 缓存
    participant API as npm API

    Client->>Cache: 请求数据
    Cache->>Cache: 检查缓存键
    alt 缓存命中且未过期
        Cache-->>Client: 返回缓存数据
    else 缓存未命中或已过期
        Cache->>API: 获取新数据
        API-->>Cache: 返回数据
        Cache->>Cache: 更新缓存
        Cache-->>Client: 返回数据
    end

缓存清除机制

虽然缓存是自动管理的，但在某些场景下可能需要手动清除缓存。项目提供了内部方法 client.clearCache() 用于清除所有缓存数据。

资料来源：DEVELOPMENT.md:30

并发控制

信号量机制

为了防止对 npm API 的过度请求，npm-mcp 使用信号量（Semaphore）模式限制并发请求数量。

关键参数：

资料来源：DEVELOPMENT.md:26

并发控制流程

graph TD
    A[发起请求] --> B{有可用信号量?}
    B -->|是| C[获取信号量]
    B -->|否| D[等待释放]
    D --> B
    C --> E[发起 HTTP 请求]
    E --> F[请求完成]
    F --> G[释放信号量]
    G --> H[返回响应]

请求合并策略

当多个工具同时请求相同数据时，缓存机制确保每个请求只触发一次外部 API 调用。后续请求直接从缓存获取数据，有效减少了 API 调用次数。

错误处理与重试机制

限流响应处理

当 npm API 返回 429 (Too Many Requests) 状态码时，系统采用指数退避（Exponential Backoff）策略进行重试。

重试策略参数：

指数退避流程：

graph TD
    A[请求失败 429] --> B{重试次数 < 最大?}
    B -->|是| C[计算延迟时间]
    C --> D[延迟 = 初始延迟 × 2^重试次数]
    D --> E[等待延迟]
    E --> F[重新发起请求]
    F --> G{成功?}
    G -->|是| H[返回数据]
    G -->|否| B
    B -->|否| I[抛出错误]

资料来源：DEVELOPMENT.md:26

其他错误处理

API 客户端实现

RegistryClient 类

RegistryClient 是整个数据获取层的核心类，封装了所有与外部 API 的交互逻辑。

主要方法：

资料来源：src/registry-client.ts

请求验证

所有请求参数都经过 Zod 模式验证，确保：

• 包名称格式正确
• 版本号符合 semver 规范
• 参数类型正确

验证示例（package-details.ts）：

export const PackageDetailsSchema = z.object({
  packageName: z.string().min(1, "Package name is required"),
  version: z.string().optional(),
});

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

数据模型

包详情数据结构

工具返回的结构化数据包含以下关键字段：

资料来源：src/tools/package-details.ts:80-120

版本兼容性数据结构

{
  "success": true,
  "package": "react",
  "version": "18.2.0",
  "compatible": true,
  "analysis": {
    "peerDependencies": {
      "total": 1,
      "compatible": 1,
      "conflicts": 0,
      "missing": 0
    },
    "details": {
      "compatible": [...],
      "conflicts": [],
      "missing": []
    }
  },
  "recommendation": "Package is compatible with existing dependencies. Safe to install.",
  "suggestedActions": []
}

资料来源：src/tools/version-compatibility.ts

性能优化实践

批量请求优化

当需要检查多个包的安全性或兼容性时，系统可以并行发起多个请求，充分利用并发控制机制。

// 并行检查多个包
const results = await Promise.all([
  client.getSecurityAudit("lodash"),
  client.getSecurityAudit("express"),
  client.getSecurityAudit("axios"),
]);

缓存预热

对于已知需要频繁访问的数据，可以实现缓存预热策略，在用户请求前主动获取并缓存数据。

请求去重

当多个请求同时发起且目标相同时，第一个请求会实际调用 API，其他请求等待结果并共享缓存数据。

常见问题与排查

服务器启动失败

资料来源：DEVELOPMENT.md:40-45

GitHub API 限流

质量分析功能依赖 GitHub API，未认证请求限额为 60 次/小时。

现象： 部分包的质量分析可能失败

解决方案： 这是设计行为，部分包的质量数据可能暂时不可用

资料来源：DEVELOPMENT.md:46-49

测试失败

rm -rf node_modules package-lock.json
npm install
npm run build
npm test

资料来源：DEVELOPMENT.md:50-54

缓存相关问题

项目结构参考

npm-mcp/
├── src/
│   ├── index.ts              # MCP 服务器入口
│   ├── registry-client.ts    # npm API 客户端（核心）
│   ├── types.ts              # TypeScript 类型定义
│   └── tools/
│       ├── search-packages.ts
│       ├── package-details.ts
│       ├── security-audit.ts
│       ├── version-compatibility.ts
│       ├── quality-analysis.ts
│       └── npx-command.ts
├── test/                     # Vitest 测试
├── bin/npm-registry-mcp.js   # npx 入口点
└── package.json

资料来源：DEVELOPMENT.md:12-24

扩展开发

添加新的数据源

1. 在 src/registry-client.ts 中添加新的 API 方法
2. 实现缓存和重试逻辑
3. 在对应工具文件中调用新方法

自定义缓存策略

如需修改缓存 TTL 或容量，可以调整 RegistryClient 构造函数参数：

const client = new RegistryClient({
  cacheTTL: 5 * 60 * 1000,  // 5 分钟
  maxConcurrent: 10,
  maxRetries: 3,
});

资料来源：CONTRIBUTING.md:70-90

相关文档

• 开发指南 - 完整的项目开发参考
• 贡献指南 - 如何参与项目开发
• 工具使用 - MCP 工具使用最佳实践
• 命令提示 - 快捷命令参考

1. 工具模块概述

npm-mcp 是一个基于 Model Context Protocol (MCP) 的 npm 注册表服务工具集，为 AI 助手提供与 npm registry 交互的能力。所有工具均位于 src/tools/ 目录下，采用统一的架构模式实现。

1.1 工具列表

1.2 架构设计

工具模块采用分层架构，确保代码的可维护性和可扩展性：

graph TD
    A[用户请求] --> B[MCP Server<br/>index.ts]
    B --> C[工具调度器<br/>CallToolRequestSchema]
    C --> D1[search_packages]
    C --> D2[package_details]
    C --> D3[security_audit]
    C --> D4[check_compatibility]
    C --> D5[quality_analysis]
    C --> D6[generate_quick_start]
    D1 --> E[Registry Client<br/>registry-client.ts]
    D2 --> E
    D3 --> E
    D4 --> E
    D5 --> E
    D6 --> E
    E --> F[NPM Registry API]
    E --> G[GitHub API]
    E --> H[Bundlephobia API]

1.3 通用模式

每个工具模块遵循统一的实现模式：

1. 输入验证：使用 Zod 定义输入 schema
2. 参数验证：验证和规范化输入参数
3. 业务逻辑：调用 Registry Client 执行实际请求
4. 结果处理：格式化返回 JSON 结果
5. 错误处理：捕获异常并返回友好的错误信息

// 标准工具模块结构
import { z } from 'zod';
import { RegistryClient } from '../registry-client.js';

export const ToolSchema = z.object({
  param1: z.string(),
  param2: z.number().optional(),
});

export async function toolHandler(
  params: z.infer<typeof ToolSchema>,
  client: RegistryClient
): Promise<string> {
  try {
    const validated = ToolSchema.parse(params);
    // 业务逻辑
    return JSON.stringify(result, null, 2);
  } catch (error) {
    return JSON.stringify({
      success: false,
      error: error instanceof Error ? error.message : 'Unknown error',
    });
  }
}

资料来源：CONTRIBUTING.md

2. search_packages 工具

search_packages 工具提供 npm 包的搜索功能，允许用户通过关键词查找相关包。

2.1 输入参数

2.2 输出结构

{
  "query": "search term",
  "count": 5,
  "results": [
    {
      "name": "package-name",
      "version": "1.0.0",
      "description": "Package description",
      "maintainers": ["maintainer1"],
      "date": "2024-01-01",
      "links": {
        "npm": "https://www.npmjs.com/package/name",
        "homepage": "https://example.com",
        "repository": "https://github.com/user/repo"
      },
      "flags": {
        "deprecated": false
      },
      "score": {
        "final": 0.95
      },
      "searchScore": 10000
    }
  ]
}

2.3 使用示例

// 搜索 React 状态管理库
search_packages({
  query: "react state management",
  size: 5
})

资料来源：src/tools/search-packages.ts

3. package_details 工具

package_details 工具提供 npm 包的完整元数据信息，包括版本、依赖、维护者等详细信息。

3.1 输入参数

3.2 输出结构

{
  "success": true,
  "package": {
    "name": "package-name",
    "version": "1.0.0",
    "description": "...",
    "isLatest": true,
    "deprecated": false
  },
  "metadata": {
    "license": "MIT",
    "author": "Author Name",
    "maintainers": [...],
    "keywords": [...],
    "homepage": "...",
    "repository": {...},
    "bugs": {...}
  },
  "versions": {
    "latest": "1.0.0",
    "tags": { "latest": "1.0.0", "next": "2.0.0" },
    "total": 25,
    "recent": ["1.0.0", "0.9.0"],
    "deprecatedVersions": []
  },
  "dependencies": {
    "dependencies": {},
    "devDependencies": {},
    "peerDependencies": {},
    "optionalDependencies": {}
  },
  "dist": {
    "tarball": "...",
    "shasum": "...",
    "integrity": "...",
    "fileCount": 15,
    "unpackedSize": "125.34 KB"
  },
  "timestamps": {
    "created": "...",
    "modified": "...",
    "versionPublished": "..."
  },
  "stats": {
    "weeklyDownloads": "1,250,000",
    "period": "2024-01-01 to 2024-01-08"
  }
}

3.3 核心功能

该工具从多个数据源聚合信息：

graph LR
    A[package_details 请求] --> B[获取 Packument]
    B --> C[获取版本数据]
    C --> D[获取下载统计]
    D --> E[聚合输出]

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

4. check_compatibility 工具

check_compatibility 工具验证包与现有依赖的兼容性，特别是检查 peer dependencies。

4.1 输入参数

4.2 输出结构

{
  "success": true,
  "package": "package-name",
  "version": "1.0.0",
  "compatible": true,
  "analysis": {
    "peerDependencies": {
      "total": 3,
      "compatible": 3,
      "conflicts": 0,
      "missing": 0
    },
    "details": {
      "compatible": ["[email protected]", "[email protected]"],
      "conflicts": [],
      "missing": []
    }
  },
  "recommendation": "Package is compatible with existing dependencies. Safe to install.",
  "suggestedActions": []
}

4.3 兼容性判断逻辑

flowchart TD
    A[获取包的 peerDependencies] --> B{是否为空}
    B -->|是| C[返回兼容]
    B -->|否| D[检查每个 peer dep]
    D --> E{版本是否匹配}
    E -->|是| F[标记为兼容]
    E -->|否| G{版本范围重叠}
    G -->|是| H[标记为兼容]
    G -->|否| I[标记为冲突]
    F --> J{所有检查完成}
    H --> J
    I --> J
    J --> K{存在冲突?}
    K -->|否| L[返回 compatible: true]
    K -->|是| M[返回 compatible: false]

工具通过 semver 范围比较来判断兼容性，支持 caret (^)、tilde (~) 和精确版本等格式。

资料来源：src/tools/version-compatibility.ts

5. generate_quick_start 工具

generate_quick_start 工具根据包信息自动生成快速开始代码示例，支持多种框架和场景。

5.1 输入参数

5.2 支持的框架类型

5.3 输出结构

{
  "packageName": "package-name",
  "description": "Framework description",
  "language": "typescript",
  "code": "export const usage = 'example code...'"
}

5.4 代码生成示例

// Express 框架生成示例
generate_quick_start({
  packageName: "express",
  framework: "express"
})
// 输出:
// import express from 'express';
// const app = express();
// app.use(express.json());
// app.get('/api/users', (req, res) => {...});

工具自动检测包的类型和导出结构，选择最合适的代码模板进行生成。

资料来源：src/tools/quick-start.ts

6. 工具注册与调度

6.1 注册流程

工具需要在 src/index.ts 中进行注册才能被 MCP 协议识别：

sequenceDiagram
    participant MCP as MCP Server
    participant Index as index.ts
    participant Tool as Tool Module
    
    MCP->>Index: ListToolsRequestSchema
    Index->>Index: 加载所有工具定义
    Index-->>MCP: 返回工具列表
    
    MCP->>Index: CallToolRequestSchema
    Index->>Tool: 调用工具函数
    Tool-->>Index: 返回结果
    Index-->>MCP: 返回格式化结果

6.2 添加新工具

添加新工具需要三个步骤：

1. 创建工具文件：src/tools/<tool-name>.ts
2. 注册工具：在 src/index.ts 的 ListToolsRequestSchema 中添加
3. 实现调度：在 CallToolRequestSchema 中添加处理逻辑

// 步骤1: src/tools/my-tool.ts
import { z } from 'zod';
import { RegistryClient } from '../registry-client.js';

export const MyToolSchema = z.object({
  param: z.string(),
});

export async function myTool(
  params: z.infer<typeof MyToolSchema>,
  client: RegistryClient
): Promise<string> {
  // 实现逻辑
}

// 步骤2 & 3: src/index.ts
import { myTool, MyToolSchema } from './tools/my-tool.js';

// 在 ListToolsRequestSchema 中注册
tools: [
  {
    name: 'my_tool',
    description: '工具描述',
    inputSchema: MyToolSchema,
  },
]

// 在 CallToolRequestSchema 中调度
case 'my_tool':
  return await myTool(args, registryClient);

资料来源：DEVELOPMENT.md

7. Registry Client 架构

Registry Client 是所有工具的底层依赖，提供统一的 API 调用能力。

7.1 核心功能

7.2 缓存策略

graph TD
    A[请求] --> B{缓存中存在?}
    B -->|是| C{缓存有效?}
    B -->|否| D[发起请求]
    C -->|是| E[返回缓存]
    C -->|否| D
    D --> F{请求成功?}
    D --> G[更新缓存]
    F -->|否| H[指数退避重试]
    G --> I[返回数据]
    H --> D
    E --> I

7.3 内部方法

class RegistryClient {
  // 缓存管理
  clearCache(): void;
  
  // 基础请求
  async fetchPackument(packageName: string): Promise<Packument>;
  async fetchVersion(packageName: string, version: string): Promise<PackageVersion>;
  async getDownloadStats(packageName: string): Promise<DownloadStats>;
}

资料来源：DEVELOPMENT.md

8. 输入验证

8.1 Zod Schema 模式

所有工具使用 Zod 进行输入验证，确保类型安全：

// 必填字符串
z.string()

// 可选参数
z.string().optional()

// 带默认值的可选
z.number().default(10)

// 枚举类型
z.enum(['react', 'vue', 'angular'])

// 对象验证
z.object({
  name: z.string(),
  age: z.number().positive(),
})

8.2 验证流程

flowchart TD
    A[接收参数] --> B[Zod Schema.parse]
    B --> C{验证通过?}
    C -->|是| D[执行工具逻辑]
    C -->|否| E[抛出 ZodError]
    E --> F[捕获并返回错误 JSON]
    D --> G[返回成功结果]

8.3 错误处理

export async function toolHandler(params: any, client: RegistryClient): Promise<string> {
  try {
    const validated = ToolSchema.parse(params);
    // 业务逻辑
    return JSON.stringify(result, null, 2);
  } catch (error) {
    const errorMessage = error instanceof Error ? error.message : 'Unknown error';
    return JSON.stringify({
      success: false,
      error: errorMessage,
    });
  }
}

资料来源：CONTRIBUTING.md

9. 工具组合使用

9.1 推荐工作流

graph TD
    A[安装新包前] --> B[audit_security]
    A --> C[check_compatibility]
    A --> D[package_details]
    B --> E{是否有漏洞?}
    C --> F{是否兼容?}
    D --> G[查看维护状态]
    E -->|是| H[建议更新版本]
    E -->|否| I[继续]
    F -->|是| I
    F -->|否| J[解决冲突]
    G --> K[检查是否活跃]
    K --> L[最终决策]
    H --> L
    J --> L
    I --> L
    L --> M[执行安装]

9.2 典型场景组合

9.3 代码示例

// 完整的安装前检查
async function checkBeforeInstall(packageName) {
  const security = await audit_security(packageName);
  const details = await package_details(packageName);
  const compat = await check_compatibility(packageName);
  
  return {
    canInstall: security.success && compat.compatible,
    securityIssues: security.issues,
    compatibilityIssues: compat.analysis,
    packageInfo: details
  };
}

资料来源：CAPABILITIES.md

10. 测试工具模块

10.1 测试框架

项目使用 Vitest 作为测试框架，每个工具应有对应的测试文件：

test/
├── search-packages.test.ts
├── package-details.test.ts
├── version-compatibility.test.ts
└── ...

10.2 测试示例

import { describe, it, expect } from 'vitest';
import { toolHandler, ToolSchema } from '../src/tools/my-tool';

describe('my-tool', () => {
  it('should validate input correctly', () => {
    const validInput = { param: 'test' };
    const result = ToolSchema.safeParse(validInput);
    expect(result.success).toBe(true);
  });

  it('should handle invalid input gracefully', async () => {
    const invalidInput = { param: 123 }; // 应该是 string
    const result = await toolHandler(invalidInput, mockClient);
    const parsed = JSON.parse(result);
    expect(parsed.success).toBe(false);
  });
});

10.3 运行测试

# 运行所有测试
npm test

# 运行带覆盖率的测试
npm run test:coverage

# 类型检查
npm run typecheck

资料来源：CONTRIBUTING.md

11. 常见问题

11.1 服务器无法启动

问题：执行 npx npm-registry-mcp 无响应

解决方案：

``bash node --version ``

1. 检查 Node.js 版本（需要 18+）：

``bash npm run build ``

1. 重新构建项目：

``bash chmod +x bin/npm-registry-mcp.js ``

1. 检查可执行权限：

11.2 GitHub 速率限制

问题：质量分析工具返回错误

原因：GitHub API 未认证限制为 60 请求/小时

解决方案：某些包的 GitHub 信息可能暂时不可用，属正常现象

11.3 测试失败

解决方案：

rm -rf node_modules package-lock.json
npm install
npm run build
npm test

资料来源：DEVELOPMENT.md

12. 参考链接

• 项目主仓库
• 开发文档
• 贡献指南
• AI 使用指南
• 生产力工具
• MCP 提示词

概述

安全审计功能是 npm-mcp 的核心功能之一，提供对 npm 包的安全漏洞检测和分析能力。该功能通过调用 npm 官方安全 API 接口，获取包的安全信息，并在 AI 助手中实现自动化的安全检查工作流。安全审计功能与其他工具（如版本兼容性检查、能力分析）协同工作，为开发者提供全面的包安装安全建议。资料来源：AI_USAGE.md

核心功能模块

1. 单包安全审计 (`audit_security`)

单包安全审计是最基础的安全检查功能，用于检测指定 npm 包是否存在已知安全漏洞。资料来源：src/tools/security-audit.ts

主要功能：

• 检查包是否存在已知安全漏洞
• 获取漏洞的详细描述信息
• 提供安全版本建议
• 支持指定具体版本或范围的审计

使用场景：

• 在安装任何新包之前进行安全检查
• 检查现有依赖包的安全性
• 在 AI 对话中自动触发（当用户提及包名时）

// 基础调用示例
audit_security({
  packageName: "lodash",
  version?: "4.17.20"  // 可选，指定版本
})

2. 项目级安全审计 (`audit_project`)

项目级安全审计用于扫描整个项目的 package.json 文件，审计所有依赖项的安全性。资料来源：PROMPTS.md

工作流程：

1. 读取项目的 package.json 文件
2. 提取所有依赖项（dependencies、devDependencies）
3. 对每个依赖项执行并行安全检查
4. 汇总结果并提供修复建议

{
  "dependencies": {
    "express": "4.18.2",
    "axios": "1.6.0",
    "lodash": "4.17.21"
  }
}

// 审计报告格式
{
  "total": 3,
  "safe": 2,
  "vulnerable": 1,
  "results": [
    { "name": "express", "status": "safe" },
    { "name": "axios", "status": "safe" },
    { "name": "lodash", "status": "vulnerable", "severity": "high" }
  ]
}

3. 安装前检查 (`check_before_install`)

这是一个组合型检查工作流，在推荐安装任何包之前自动执行全面的安全和兼容性检查。资料来源：PROMPTS.md

检查步骤：

1. 执行 audit_security 检查漏洞
2. 获取 package_details 验证维护状态
3. 检查 compatibility 与现有依赖的兼容性
4. 显示清晰的 ✅/⚠️ 推荐结果

响应格式：

✅ [email protected] is safe to install

Security: No known vulnerabilities
Compatibility: ✅ No peer dependency conflicts
Maintenance: Active (last update: 2 days ago)

Install: npm install [email protected]

架构设计

组件关系图

graph TD
    A[用户/AI 助手] --> B[audit_security 工具]
    A --> C[audit_project 工具]
    A --> D[check_before_install 提示词]
    
    B --> E[NPM Registry API]
    C --> E
    D --> B
    D --> F[package_details 工具]
    D --> G[compatibility 工具]
    
    E --> H[安全漏洞数据]
    F --> E
    G --> E
    
    H --> I[安全报告]
    I --> A

安全审计数据流

sequenceDiagram
    participant U as 用户/AI
    participant MCP as MCP Server
    participant API as NPM Registry API
    participant DB as 缓存层
    
    U->>MCP: audit_security("lodash")
    MCP->>DB: 检查缓存
    DB-->>MCP: Cache Miss
    MCP->>API: GET /-/vuln/npm/{package}
    API-->>MCP: 漏洞数据
    MCP->>DB: 存入缓存 (5min TTL)
    MCP-->>U: 安全报告
    
    Note over U,MCP: 后续请求从缓存获取

输出数据结构

安全审计响应格式

{
  "success": true,
  "package": "lodash",
  "version": "4.17.20",
  "vulnerabilities": [
    {
      "id": "SNYK-JS-LODASH-567746",
      "severity": "high",
      "title": "Prototype Pollution",
      "url": "https://www.npmjs.com/advisories/1673",
      "fixVersion": "4.17.21"
    }
  ],
  "summary": {
    "total": 1,
    "critical": 0,
    "high": 1,
    "medium": 0,
    "low": 0
  },
  "recommendation": "⚠️ 1 vulnerability found. Safe version: 4.17.21"
}

漏洞严重等级说明

缓存与限流机制

安全审计功能复用项目统一的缓存和限流机制。资料来源：DEVELOPMENT.md

缓存策略

• TTL: 5 分钟
• 适用数据: 包的安全漏洞信息、下载统计、GitHub 数据
• 缓存清理: client.clearCache() 方法（内部调用）

并发限制

与其他工具的集成

集成关系图

graph LR
    A[security-audit] --> B[package-details]
    A --> C[version-compatibility]
    A --> D[analyze_capabilities]
    A --> E[compare_packages]
    
    B -->|获取维护状态| F[响应数据]
    C -->|检查兼容性| G[响应数据]
    D -->|分析能力| H[响应数据]
    E -->|对比评分| I[响应数据]

组合工作流示例

场景：用户询问是否安全安装 axios

graph LR
    A["用户: 安装 axios 安全吗?"] --> B["audit_security"]
    B --> C{"发现漏洞?"}
    C -->|是| D["显示漏洞详情"]
    C -->|否| E["check_compatibility"]
    E --> F{"冲突?"}
    F -->|是| G["显示冲突信息"]
    F -->|否| H["✅ 建议安装"]
    D --> I["建议安全版本"]
    I --> J["npm install axios@版本号"]
    G --> J
    H --> J

自动触发机制

安全审计功能支持在 AI 助手中的自动触发，无需用户显式调用。资料来源：AI_USAGE.md

触发关键词

AI 响应模板

安全包响应：

✅ [email protected] is safe to install

Security: No vulnerabilities
Compatibility: ✅ Compatible with your dependencies
Quality: 95/100 (11M weekly downloads)

Install:
npm install [email protected]

危险包响应：

⚠️ SECURITY WARNING: [email protected] has 2 vulnerabilities

Severity: High
Issue: Prototype pollution
Safe version: [email protected]

Recommended:
npm install [email protected]

错误处理

安全审计功能实现了完善的错误处理机制。资料来源：src/tools/security-audit.ts

常见错误类型

错误响应格式

{
  "success": false,
  "error": "Package not found: invalid-package-name",
  "packageName": "invalid-package-name",
  "suggestion": "Please check the package name and try again"
}

扩展工具集成

安全审计功能可以与其他生产力工具协同使用，提供更全面的分析。资料来源：PRODUCTIVITY.md

与包比较工具结合

graph TD
    A["用户: axios vs node-fetch"] --> B["compare_packages"]
    B --> C["axios 安全性分析"]
    B --> D["node-fetch 安全性分析"]
    C --> E["安全对比报告"]
    D --> E
    E --> F["推荐: axios"]

与包体分析工具结合

// 组合使用示例
{
  "bundle_size": {
    "name": "moment",
    "gzip": "232 KB",
    "warning": "⚠️ Large bundle + No tree-shaking"
  },
  "security": {
    "vulnerabilities": 0,
    "status": "✅ No known vulnerabilities"
  },
  "recommendation": "Consider date-fns (14KB) as alternative"
}

常见问题与解决方案

问题 1：GitHub 速率限制

原因：质量分析功能使用 GitHub API，未认证请求限制为 60 次/小时。资料来源：DEVELOPMENT.md

解决方案：

• 等待速率限制重置
• 使用缓存数据
• 减少不必要的请求

问题 2：缓存数据过期

原因：安全漏洞数据库持续更新，缓存数据可能有 5 分钟延迟。

解决方案：

• 调用 client.clearCache() 清除缓存
• 等待缓存自然过期
• 使用 forceRefresh 参数（如果支持）

问题 3：测试失败

解决方案：资料来源：DEVELOPMENT.md

rm -rf node_modules package-lock.json
npm install
npm run build
npm test

使用建议

最佳实践

1. 始终先检查安全：在任何安装建议之前自动执行安全审计
2. 保持主动：不要等待用户询问"这个包安全吗？"
3. 批量操作：并行检查多个包以提高效率
4. 清晰警告：使用 ⚠️ 🔒 ✅ 等表情符号提高可见性
5. 提供可执行命令：始终提供安全的安装命令

开发建议

在开发 npm-mcp 扩展时，遵循以下原则添加安全审计功能：资料来源：CONTRIBUTING.md

1. 遵循项目结构：在 src/tools/ 目录下创建工具文件
2. 使用 Zod 验证：输入参数使用 Zod schema 验证
3. 返回 JSON 字符串：工具返回 JSON 格式字符串
4. 错误处理：捕获异常并返回友好的错误信息
5. 添加测试：在 test/ 目录下为新功能编写测试

相关文档

• 开发指南 - 了解项目架构和工具开发规范
• 贡献指南 - 了解如何为项目贡献代码
• AI 使用指南 - 了解 AI 集成最佳实践
• MCP 提示词 - 了解快捷命令的使用
• 生产力工具 - 了解组合工作流
• 包能力分析 - 了解包的技术特性分析

概述

包比较与分析是 npm-mcp 项目的核心功能模块之一，旨在帮助开发者在选择和使用 npm 包时做出明智的决策。该模块提供了全面的包分析能力，包括包兼容性检查、质量评估、依赖分析、安全审计以及多包对比等功能。

npm-mcp 通过整合 NPM Registry API、Bundlephobia API 和 GitHub API 等多个数据源，为开发者提供了一站式的包分析解决方案。这些工具可以独立使用，也可以组合形成完整的工作流程，帮助开发者在项目开发过程中快速评估和比较不同的 npm 包。

资料来源：PRODUCTIVITY.md

核心工具架构

工具分类

npm-mcp 的包比较与分析功能由多个专业工具组成，每个工具专注于特定的分析维度。

资料来源：DEVELOPMENT.md

架构流程图

graph TD
    A[用户请求] --> B{分析类型}
    B -->|单包分析| C[package_details]
    B -->|兼容性检查| D[version_compatibility]
    B -->|质量评估| E[quality_analysis]
    B -->|能力分析| F[analyze_capabilities]
    B -->|多包对比| G[compare_packages]
    B -->|体积分析| H[analyze_bundle_size]
    B -->|相似包查找| I[find_similar_packages]
    
    C --> J[NPM Registry API]
    D --> J
    E --> K[GitHub API]
    F --> J
    G --> J
    G --> H
    G --> K
    H --> L[Bundlephobia API]
    I --> J
    
    J --> M[结果聚合]
    K --> M
    L --> M
    M --> N[统一输出格式]

包详情分析

功能概述

package_details 工具提供单个包的完整元数据信息，包括版本信息、依赖关系、分发信息、维护状态等。该工具是所有其他分析工具的基础，为进一步的分析提供数据支撑。

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

输出数据结构

{
  "success": true,
  "package": {
    "name": "包名称",
    "version": "版本号",
    "description": "包描述",
    "isLatest": true
  },
  "metadata": {
    "license": "许可证类型",
    "author": "作者信息",
    "maintainers": ["维护者列表"],
    "keywords": ["关键词"],
    "homepage": "主页地址",
    "repository": "仓库地址",
    "bugs": "问题追踪地址"
  },
  "versions": {
    "latest": "最新版本",
    "tags": {"latest": "4.18.2", "next": "5.0.0"},
    "total": 版本总数,
    "recent": ["最近版本列表"],
    "deprecatedVersions": [{"version": "v1.0.0", "message": "deprecated"}]
  },
  "dependencies": {
    "dependencies": {},
    "devDependencies": {},
    "peerDependencies": {},
    "optionalDependencies": {}
  },
  "dist": {
    "tarball": "下载链接",
    "shasum": "校验和",
    "integrity": "完整性哈希",
    "fileCount": "文件数量",
    "unpackedSize": "解压后大小"
  },
  "timestamps": {
    "created": "创建时间",
    "modified": "修改时间",
    "versionPublished": "版本发布时间"
  },
  "stats": {
    "weeklyDownloads": "周下载量",
    "period": "统计周期"
  }
}

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

关键字段说明

版本兼容性检查

功能概述

version_compatibility 工具用于检查目标包的版本与当前项目依赖之间的兼容性。该工具特别关注对等依赖（peer dependencies）的匹配情况，帮助开发者识别可能出现的版本冲突。

资料来源：src/tools/version-compatibility.ts

兼容性分析流程

graph TD
    A[输入: 包名 + 版本] --> B[获取包元数据]
    B --> C[提取 peerDependencies]
    D[获取项目现有依赖] --> E{逐一比对版本}
    E --> F{检查冲突}
    F -->|有冲突| G[记录冲突详情]
    F -->|无冲突| H{检查缺失}
    H -->|有缺失| I[记录缺失依赖]
    H -->|无缺失| J[兼容性通过]
    
    G --> K[生成建议]
    I --> K
    J --> L[返回成功结果]
    K --> M[返回问题报告]

输出结构

{
  "success": true,
  "package": "包名称",
  "version": "版本号",
  "compatible": false,
  "analysis": {
    "peerDependencies": {
      "total": 5,
      "compatible": 3,
      "conflicts": 1,
      "missing": 1
    },
    "details": {
      "compatible": [
        {"package": "react@^18.0.0", "status": "compatible"}
      ],
      "conflicts": [
        {"package": "lodash@^4.0.0", "required": "^5.0.0", "installed": "^4.17.21"}
      ],
      "missing": [
        {"package": "moment@required", "required": "^2.29.0"}
      ]
    }
  },
  "recommendation": "兼容性存在冲突",
  "suggestedActions": [
    "更新冲突的依赖到兼容版本",
    "安装缺失的对等依赖"
  ]
}

资料来源：src/tools/version-compatibility.ts

兼容性判断逻辑

工具通过以下步骤判断兼容性：

1. 冲突检测：检查已安装的依赖版本是否满足对等依赖的版本要求
2. 缺失检测：识别项目中缺失但被目标包要求的对等依赖
3. 建议生成：根据检测结果提供具体的修复建议

const isCompatible = conflicts.length === 0 && missing.length === 0;

资料来源：src/tools/version-compatibility.ts:47

包能力分析

模块系统分析

analyze_capabilities 工具深入分析包的技术特性，特别关注其模块系统支持情况。

资料来源：CAPABILITIES.md

#### 支持的模块类型

#### TypeScript 支持分析

工具会检测包是否包含 TypeScript 类型定义：

• 内置类型：包本身包含 .d.ts 文件
• 类型包：需要安装独立的 @types/ 包
• TypeScript 编写的包：包使用 TypeScript 开发

{
  "moduleSystem": {
    "esm": true,
    "commonjs": true,
    "dualPackage": true,
    "details": [
      "Package type: 'module' (native ESM)",
      "Dual package: ESM + CommonJS support"
    ]
  },
  "typescript": {
    "hasTypes": true,
    "typesLocation": "./dist/index.d.ts",
    "isTypeScriptPackage": true
  }
}

资料来源：CAPABILITIES.md

平台兼容性分析

工具还检测包对不同运行时的支持情况：

{
  "platform": {
    "node": true,
    "browser": true,
    "deno": false,
    "bun": false
  },
  "summary": "✅ Dual Package: ESM + CommonJS\n✅ Platforms: Node.js, Browser"
}

资料来源：CAPABILITIES.md

多包对比功能

功能概述

compare_packages 工具支持同时分析多个包，提供全面的对比视图，帮助开发者选择最适合项目需求的包。

资料来源：PRODUCTIVITY.md

对比维度

示例输出

{
  "comparison": {
    "moduleSystem": {
      "axios": { "summary": "Dual (ESM + CJS)" },
      "node-fetch": { "summary": "ESM only" },
      "undici": { "summary": "Dual (ESM + CJS)" }
    },
    "typescript": {
      "axios": { "hasTypes": true },
      "node-fetch": { "hasTypes": true },
      "undici": { "hasTypes": true }
    },
    "popularity": {
      "axios": { "weeklyDownloads": "45M", "relative": "Very popular" },
      "node-fetch": { "weeklyDownloads": "32M", "relative": "Very popular" },
      "undici": { "weeklyDownloads": "8M", "relative": "Popular" }
    }
  },
  "recommendation": {
    "winner": "undici",
    "summary": "undici 得分最高，支持现代 ESM，体积小"
  }
}

资料来源：PRODUCTIVITY.md

打包体积分析

功能概述

analyze_bundle_size 工具使用 Bundlephobia API 提供准确的包体积数据，帮助开发者评估包对最终打包体积的影响。

资料来源：PRODUCTIVITY.md

体积指标说明

输出结构

{
  "sizes": {
    "unpacked": "1.41 MB",
    "minified": "531.48 KB",
    "gzip": "94.17 KB"
  },
  "impact": {
    "level": "Moderate",
    "rating": "⚠️ Medium",
    "description": "此包将增加约 94.17 KB 的 gzip 传输体积"
  },
  "treeshaking": {
    "supported": false,
    "description": "❌ CommonJS - 不支持摇树优化"
  },
  "recommendations": [
    "⚠️ 较大的打包体积 - 考虑替代方案或代码分割",
    "💡 包使用 CommonJS - 寻找 ESM 版本以获得更好的摇树支持",
    "💡 考虑使用按方法导入的轻量级替代方案"
  ]
}

资料来源：PRODUCTIVITY.md

影响等级评估

相似包查找

功能概述

find_similar_packages 工具根据包的关键词和用途查找相似的替代包，帮助开发者发现可能更优的选择。

资料来源：PRODUCTIVITY.md

工作流程

graph TD
    A[输入: 包名称/关键词] --> B[获取目标包元数据]
    B --> C[提取关键词和分类]
    C --> D[搜索 NPM Registry]
    D --> E{相关性评分}
    E --> F[排序并过滤]
    F --> G[补充其他包的详情]
    G --> H[返回排名列表]
    
    E -->|高相似度| I[主要推荐]
    E -->|中相似度| J[备选推荐]
    E -->|低相似度| K[相关参考]

示例场景

当用户询问 "request" 包的替代方案时：

1. find_similar_packages("request")
2. 找到: axios, node-fetch, got, undici
3. audit_security 针对每个进行安全审计
4. 返回推荐结果:

"request 已废弃！以下是现代替代方案：

1. **axios** - 最受欢迎 (45M/周)
   - ✅ 浏览器 + Node.js
   - ✅ 拦截器、转换器
   
2. **got** - 功能丰富 (8M/周)
   - ✅ 重试、缓存、钩子
   - ✅ 现代 API
   
3. **undici** - 速度最快 (8M/周)
   - ✅ Node.js 官方维护
   - ✅ HTTP/1.1 keep-alive

推荐: axios 通用性强，undici 性能最佳"

资料来源：PRODUCTIVITY.md

NPX 命令分析

功能概述

analyze_npx_command 工具对 npx 命令进行安全分析，验证包的存在性、检查版本、分析依赖并提供安全建议。该工具不执行命令，只进行分析。

资料来源：src/tools/npx-command.ts

分析内容

输出结构

{
  "success": true,
  "analysis": {
    "package": "包名称",
    "version": "版本号",
    "command": "npx package-name@version",
    "isLatest": true
  },
  "validation": {
    "packageExists": true,
    "versionExists": true,
    "hasExecutable": true,
    "sizeKB": 1234,
    "dependencyCount": 12,
    "publishedDaysAgo": 45
  },
  "metadata": {
    "description": "包描述",
    "license": "许可证",
    "author": "作者",
    "repository": "仓库地址"
  },
  "warnings": [
    "⚠️ 包体积较大: 1234 KB",
    "📦 包含 12 个依赖 - 请一并审查"
  ],
  "recommendations": [
    "🔒 执行前务必审查包内容",
    "📝 检查包的口碑和维护者信任度"
  ],
  "safeCommand": "npx package-name@version",
  "note": "命令已分析但未执行。审查后手动执行。"
}

资料来源：src/tools/npx-command.ts

组合工作流程

完整包评估流程

graph TD
    A[发现需求] --> B[搜索包]
    B --> C[compare_packages]
    C --> D{选择候选}
    D --> E[analyze_bundle_size]
    E --> F{体积可接受?}
    F -->|是| G[audit_security]
    F -->|否| H[查找替代]
    H --> C
    G --> I{安全通过?}
    I -->|是| J[version_compatibility]
    I -->|否| K[建议更新]
    K --> L{有新版本?}
    L -->|是| M[更新建议]
    L -->|否| H
    J --> N[最终推荐]
    M --> N
    
    style G fill:#90EE90
    style N fill:#87CEEB
    style H fill:#FFB6C1

AI 自动执行流程

npm-mcp 设计为可供 AI 助手自动调用，以下是典型的工作流程：

用户: "express 和 koa 哪个更好?"

AI 自动执行:
1. compare_packages(["express", "koa"])
2. analyze_bundle_size("express")
3. analyze_bundle_size("koa")
4. audit_security("express")
5. audit_security("koa")
6. 返回对比结果

资料来源：AI_USAGE.md

使用建议

最佳实践

工具组合策略

1. 开发阶段：使用 find_similar_packages 发现最佳选择
2. 评估阶段：使用 compare_packages 进行多包对比
3. 引入前：使用 audit_security + version_compatibility 进行安全检查
4. 上线前：使用 analyze_bundle_size 评估打包影响

响应模板

当 AI 使用这些工具时，建议使用以下模板提供清晰的反馈：

✅ [email protected] 安全可安装

安全性: 无已知漏洞
兼容性: ✅ 与现有依赖无冲突
质量: 95/100 (周下载 1100 万)

安装命令:
npm install [email protected]

相关文档

参见

• 包能力分析工具
• 生产力工具文档
• AI 使用指南
• 版本兼容性检查

项目概述

npm-mcp 是一个基于 Model Context Protocol (MCP) 的 npm 注册表服务器实现，为 AI 助手提供与 npm 注册表交互的工具集。该项目使 AI 能够在不离开对话环境的情况下执行包搜索、安全审计、版本兼容性检查等操作，显著提升开发工作流的效率。

项目采用 TypeScript 开发，运行于 Node.js 18+ 环境，充分利用原生 fetch API 与现代异步编程模式。核心架构围绕注册表客户端和 MCP 工具层展开，通过模块化设计实现各功能组件的独立性与可维护性。

环境搭建

前置条件

在开始开发之前，请确保本地环境满足以下要求：

初始化步骤

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

# 安装依赖
npm install

# 构建项目
npm run build

资料来源：DEVELOPMENT.md:1-10

验证安装

构建成功后，可通过以下命令验证环境配置正确：

# 运行测试套件
npm test

# 类型检查
npm run typecheck

项目结构

npm-mcp 采用清晰的目录结构组织代码，各模块职责分明，便于维护和扩展。

npm-mcp/
├── src/
│   ├── index.ts              # MCP 服务器入口
│   ├── registry-client.ts    # NPM API 客户端
│   ├── types.ts              # TypeScript 类型定义
│   └── tools/
│       ├── search-packages.ts       # 包搜索工具
│       ├── package-details.ts       # 包详情工具
│       ├── security-audit.ts        # 安全审计工具
│       ├── version-compatibility.ts # 版本兼容性工具
│       ├── quality-analysis.ts      # 质量分析工具
│       └── npx-command.ts           # npx 命令分析工具
├── test/                     # Vitest 测试文件
├── bin/
│   └── npm-registry-mcp.js   # npx 入口脚本
├── server.json               # MCP 注册表元数据
└── package.json

资料来源：DEVELOPMENT.md:18-34

目录职责说明

核心架构

系统组件关系

graph TD
    A[AI Assistant] --> B[MCP Client]
    B --> C[index.ts - MCP Server]
    C --> D[Tool Handlers]
    
    D --> E[search-packages]
    D --> F[package-details]
    D --> G[security-audit]
    D --> H[version-compatibility]
    D --> I[quality-analysis]
    D --> J[npx-command]
    
    E --> K[Registry Client]
    F --> K
    G --> K
    H --> K
    I --> K
    J --> K
    
    K --> L[Cache Layer - LRU]
    K --> M[Rate Limiter - 10 concurrent]
    K --> N[NPM Registry API]
    
    N --> O[Search API]
    N --> P[Package Metadata]
    N --> Q[Download Stats]

注册表客户端架构

RegistryClient 是整个项目的核心模块，负责与 npm 注册表 API 的所有通信。该客户端实现了请求缓存、并发限制和指数退避重试机制，确保在高并发场景下的稳定性。

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

#### 缓存机制

注册表客户端使用 LRU（最近最少使用）缓存策略，缓存内容包括包元数据、下载统计和 GitHub 信息。默认配置下，缓存有效期为 5 分钟。

this.cache = new LRUCache({
  max: config.cacheMaxSize || 500,
  ttl: config.cacheTTL || 5 * 60 * 1000, // 5 分钟
});

资料来源：src/registry-client.ts:30-33

#### 并发控制

系统限制最大并发请求数为 10，使用 p-limit 库实现。当遇到 429（请求过多）响应时，客户端自动执行指数退避重试策略。

资料来源：src/registry-client.ts:35-38

#### 核心 API 方法

// 获取包元数据（packument）
async getPackage(packageName: string): Promise<Packument>

// 获取特定版本信息
async getPackageVersion(packageName: string, version: string): Promise<VersionData>

// 搜索包
async searchPackages(query: string, options?: { limit?: number; offset?: number }): Promise<SearchResponse>

// 获取下载统计
async getDownloadStats(packageName: string, period?: 'last-day' | 'last-week' | 'last-month'): Promise<DownloadStats>

资料来源：src/registry-client.ts:45-80

可用脚本

项目提供一组 npm 脚本用于日常开发流程。

资料来源：DEVELOPMENT.md:10-16

MCP 工具开发

MCP 工具是项目的核心功能单元，每个工具对应一个独立的 TypeScript 模块。以下是现有工具及其功能说明。

现有工具列表

添加工具流程

#### 第一步：创建工具模块

在 src/tools/ 目录下创建新的工具文件，例如 src/tools/my-tool.ts。每个工具文件应包含 Zod 模式定义和异步处理函数。

import { z } from 'zod';
import { RegistryClient } from '../registry-client.js';

// 定义输入参数模式
export const MyToolSchema = z.object({
  param: z.string(),
});

// 工具处理函数
export async function myTool(
  params: z.infer<typeof MyToolSchema>,
  client: RegistryClient
): Promise<string> {
  // 验证输入参数
  const validated = MyToolSchema.parse(params);
  
  // 实现工具逻辑
  // 使用 client 访问注册表 API
  const packageData = await client.getPackage(validated.param);
  
  // 返回 JSON 字符串结果
  return JSON.stringify({ success: true, data: packageData }, null, 2);
}

资料来源：CONTRIBUTING.md:60-85

#### 第二步：注册工具

在 src/index.ts 中，需要在两个位置添加新工具：

1. 在 ListToolsRequestSchema 处理器中列出工具定义
2. 在 CallToolRequestSchema 处理器中调用对应的处理函数

import { myTool } from './tools/my-tool.js';

// 在 ListTools 处理器中添加
case 'my-tool':
  return {
    description: '工具描述',
    inputSchema: {
      type: 'object',
      properties: {
        param: { type: 'string', description: '参数描述' }
      }
    }
  };

// 在 CallTool 处理器中添加
case 'my-tool':
  return await myTool(args, client);

资料来源：CONTRIBUTING.md:86-100

#### 第三步：编写测试

在 test/ 目录下创建对应的测试文件 test/my-tool.test.ts。

import { describe, it, expect } from 'vitest';
import { MyToolSchema, myTool } from '../src/tools/my-tool.js';

describe('My Tool', () => {
  it('应正确处理有效输入', async () => {
    // 模拟 RegistryClient
    const mockClient = {
      getPackage: async () => ({ name: 'test', versions: {} })
    };
    
    const result = await myTool({ param: 'test' }, mockClient as any);
    const parsed = JSON.parse(result);
    
    expect(parsed.success).toBe(true);
  });

  it('应处理无效参数', async () => {
    await expect(
      MyToolSchema.parseAsync({})
    ).rejects.toThrow();
  });
});

资料来源：CONTRIBUTING.md:103-125

工具实现示例

包详情工具

package-details.ts 是项目中最复杂的工具之一，展示了如何聚合多个 API 调用的结果。

graph LR
    A[输入: packageName, version] --> B[获取 packument]
    B --> C[获取下载统计]
    C --> D[聚合数据]
    D --> E[返回详细信息]
    
    F[packument.name] --> D
    G[versionData.dependencies] --> D
    H[downloadStats.weeklyDownloads] --> D

资料来源：src/tools/package-details.ts:1-50

该工具返回的数据结构包含：

资料来源：src/tools/package-details.ts:60-100

版本兼容性工具

version-compatibility.ts 演示了如何分析 peer dependencies 的兼容性。

export async function checkCompatibility(
  params: { packageName, targetVersion, installedPackages? },
  client: RegistryClient
): Promise<string> {
  // 获取目标包的 peer dependencies
  const versionData = await client.getPackageVersion(packageName, targetVersion);
  const peerDeps = versionData.peerDependencies || {};
  
  // 分析兼容性
  const compatible = [];
  const conflicts = [];
  const missing = [];
  
  for (const [pkg, required] of Object.entries(peerDeps)) {
    const installed = installedPackages?.[pkg];
    if (!installed) {
      missing.push({ package: pkg, required });
    } else if (semver.satisfies(installed, required)) {
      compatible.push({ package: pkg, installed, required });
    } else {
      conflicts.push({ package: pkg, installed, required });
    }
  }
  
  return JSON.stringify({
    success: true,
    compatible: isCompatible,
    analysis: { compatible, conflicts, missing }
  }, null, 2);
}

资料来源：src/tools/version-compatibility.ts:1-60

代码规范

TypeScript 配置

项目使用 TypeScript 严格模式，建议编辑器配置以下检查：

{
  "compilerOptions": {
    "strict": true,
    "esModuleInterop": true,
    "moduleResolution": "node",
    "target": "ES2022"
  }
}

代码风格要点

资料来源：CONTRIBUTING.md:35-45

提交规范

项目遵循 Conventional Commits 规范，提交信息格式如下：

<type>: <description>

[optional body]

[optional footer]

常用 type 值：

资料来源：CONTRIBUTING.md:25-33

分支管理

测试规范

测试框架

项目使用 Vitest 作为测试框架，要求：

• 所有新功能必须包含测试用例
• 维护或改进代码覆盖率
• 测试成功和错误两种情况
• 使用描述性的测试名称

运行测试

# 运行所有测试
npm test

# 生成覆盖率报告
npm run test:coverage

# 类型检查
npm run typecheck

资料来源：DEVELOPMENT.md:10-16

故障排查

服务器无法启动

# 检查 Node 版本
node --version  # 需要 >= 18.0.0

# 重新构建项目
npm run build

# 检查可执行权限
chmod +x bin/npm-registry-mcp.js

GitHub 速率限制

质量分析工具使用 GitHub API，未认证请求限制为每小时 60 次。部分包可能因此失败。

测试失败

# 清理并重新安装依赖
rm -rf node_modules package-lock.json
npm install
npm run build
npm test

资料来源：DEVELOPMENT.md:55-68

发布流程

当代码合并到主分支后，发布流程如下：

1. 更新 package.json 中的版本号
2. 更新 CHANGELOG.md
3. 创建 Git 标签
4. 发布到 npm

# 版本更新
npm version patch  # 或 minor, major

# 发布
npm publish

资料来源：CONTRIBUTING.md:130-135

相关资源

• CONTRIBUTING.md - 贡献指南
• AI_USAGE.md - AI 使用指南
• PROMPTS.md - MCP 提示词参考

Pitfall Log / 踩坑日志

项目：alisaitteke/npm-mcp

摘要：发现 6 个潜在踩坑项，其中 0 个为 high/blocking；最高优先级：能力坑 - 能力判断依赖假设。

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

• 严重度：medium
• 证据强度：source_linked
• 发现：README/documentation is current enough for a first validation pass.
• 对用户的影响：假设不成立时，用户拿不到承诺的能力。
• 建议检查：将假设转成下游验证清单。
• 防护动作：假设必须转成验证项；没有验证结果前不能写成事实。
• 证据：capability.assumptions | mcp_registry:io.github.alisaitteke/npm-mcp:0.0.3 | https://registry.modelcontextprotocol.io/v0.1/servers/io.github.alisaitteke%2Fnpm-mcp/versions/0.0.3 | README/documentation is current enough for a first validation pass.

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

• 严重度：medium
• 证据强度：source_linked
• 发现：未记录 last_activity_observed。
• 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。
• 建议检查：补 GitHub 最近 commit、release、issue/PR 响应信号。
• 防护动作：维护活跃度未知时，推荐强度不能标为高信任。
• 证据：evidence.maintainer_signals | mcp_registry:io.github.alisaitteke/npm-mcp:0.0.3 | https://registry.modelcontextprotocol.io/v0.1/servers/io.github.alisaitteke%2Fnpm-mcp/versions/0.0.3 | last_activity_observed missing

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

• 严重度：medium
• 证据强度：source_linked
• 发现：no_demo
• 对用户的影响：下游已经要求复核，不能在页面中弱化。
• 建议检查：进入安全/权限治理复核队列。
• 防护动作：下游风险存在时必须保持 review/recommendation 降级。
• 证据：downstream_validation.risk_items | mcp_registry:io.github.alisaitteke/npm-mcp:0.0.3 | https://registry.modelcontextprotocol.io/v0.1/servers/io.github.alisaitteke%2Fnpm-mcp/versions/0.0.3 | no_demo; severity=medium

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

• 严重度：medium
• 证据强度：source_linked
• 发现：no_demo
• 对用户的影响：风险会影响是否适合普通用户安装。
• 建议检查：把风险写入边界卡，并确认是否需要人工复核。
• 防护动作：评分风险必须进入边界卡，不能只作为内部分数。
• 证据：risks.scoring_risks | mcp_registry:io.github.alisaitteke/npm-mcp:0.0.3 | https://registry.modelcontextprotocol.io/v0.1/servers/io.github.alisaitteke%2Fnpm-mcp/versions/0.0.3 | no_demo; severity=medium

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

• 严重度：low
• 证据强度：source_linked
• 发现：issue_or_pr_quality=unknown。
• 对用户的影响：用户无法判断遇到问题后是否有人维护。
• 建议检查：抽样最近 issue/PR，判断是否长期无人处理。
• 防护动作：issue/PR 响应未知时，必须提示维护风险。
• 证据：evidence.maintainer_signals | mcp_registry:io.github.alisaitteke/npm-mcp:0.0.3 | https://registry.modelcontextprotocol.io/v0.1/servers/io.github.alisaitteke%2Fnpm-mcp/versions/0.0.3 | issue_or_pr_quality=unknown

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

• 严重度：low
• 证据强度：source_linked
• 发现：release_recency=unknown。
• 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。
• 建议检查：确认最近 release/tag 和 README 安装命令是否一致。
• 防护动作：发布节奏未知或过期时，安装说明必须标注可能漂移。
• 证据：evidence.maintainer_signals | mcp_registry:io.github.alisaitteke/npm-mcp:0.0.3 | https://registry.modelcontextprotocol.io/v0.1/servers/io.github.alisaitteke%2Fnpm-mcp/versions/0.0.3 | release_recency=unknown