# https://github.com/alisaitteke/npm-mcp 项目说明书
生成时间：2026-05-30 18:57:28 UTC
## 目录
- [首页](#page-home)
- [项目介绍](#page-introduction)
- [安装配置](#page-installation)
- [快速入门](#page-quickstart)
- [系统架构](#page-architecture)
- [数据管理与缓存](#page-data-flow)
- [工具模块参考](#page-tools-reference)
- [安全审计功能](#page-security)
- [包比较与分析](#page-comparison)
- [开发指南](#page-development)
## 首页
### 相关页面
相关主题：[项目介绍](#page-introduction), [系统架构](#page-architecture), [工具模块参考](#page-tools-reference)
相关源码文件
以下源码文件用于生成本页说明：
- [src/index.ts](https://github.com/alisaitteke/npm-mcp/blob/main/src/index.ts)
- [src/registry-client.ts](https://github.com/alisaitteke/npm-mcp/blob/main/src/registry-client.ts)
- [src/types.ts](https://github.com/alisaitteke/npm-mcp/blob/main/src/types.ts)
- [DEVELOPMENT.md](https://github.com/alisaitteke/npm-mcp/blob/main/DEVELOPMENT.md)
- [AI_USAGE.md](https://github.com/alisaitteke/npm-mcp/blob/main/AI_USAGE.md)
- [PRODUCTIVITY.md](https://github.com/alisaitteke/npm-mcp/blob/main/PRODUCTIVITY.md)
- [CONTRIBUTING.md](https://github.com/alisaitteke/npm-mcp/blob/main/CONTRIBUTING.md)
- [server.json](https://github.com/alisaitteke/npm-mcp/blob/main/server.json)
# 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 协议层、注册表客户端层和业务逻辑层清晰分离。这种设计确保了代码的可维护性和可扩展性，同时便于独立测试各个组件。
### 整体架构图
```mermaid
graph TD
subgraph "客户端层"
A[AI Assistant
Cursor/Claude Desktop]
end
subgraph "MCP 协议层"
B[Server Entry
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
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 进行输入模式验证，确保参数的正确性和安全性。
### 数据流处理
```mermaid
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，确保类型安全和代码质量。
| 环境要求 | 最低版本 | 推荐版本 |
|---------|---------|---------|
| Node.js | 18.0.0 | 20.x LTS |
| npm | 9.0.0 | 10.x |
| TypeScript | 5.0 | 最新稳定版 |
### 安装步骤
首先克隆项目仓库到本地：
```bash
git clone https://github.com/alisaitteke/npm-mcp.git
cd npm-mcp
```
然后安装项目依赖：
```bash
npm install
```
构建 TypeScript 代码：
```bash
npm run build
```
运行测试确保一切正常：
```bash
npm test
```
### 配置 MCP 客户端
将以下配置添加到 Cursor 的 `~/.cursor/.cursorrules` 文件或 Claude Desktop 的 MCP 配置文件：
```json
{
"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 | query, size? | 搜索 npm 包 |
| get_package_details | packageName, version? | 获取包详细信息 |
| audit_security | packageName, version? | 安全漏洞审计 |
| check_compatibility | packageName, version?, targetVersion? | 版本兼容性检查 |
| analyze_quality | packageName | 包质量分析 |
| audit_project | dependencies | 项目依赖审计 |
| analyze_npx_command | command, args?, timeout? | npx 命令分析 |
### search_packages 参数详解
| 参数名 | 类型 | 必需 | 默认值 | 说明 |
|-------|------|-----|-------|------|
| query | string | 是 | - | 搜索关键词 |
| size | number | 否 | 10 | 返回结果数量 |
### get_package_details 参数详解
| 参数名 | 类型 | 必需 | 默认值 | 说明 |
|-------|------|-----|-------|------|
| packageName | string | 是 | - | npm 包名称 |
| version | string | 否 | latest | 指定版本号 |
### audit_security 返回结构
```json
{
"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 调用，提升响应速度并降低限流风险。
| 缓存类型 | TTL | 说明 |
|---------|-----|------|
| 包元数据 | 5 分钟 | package.json、版本信息等 |
| 下载统计 | 5 分钟 | 每周下载量等动态数据 |
| GitHub 数据 | 5 分钟 | stars、issues 等 GitHub 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 进行输入验证：
```typescript
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,
client: RegistryClient
): Promise {
const validated = MyToolSchema.parse(params);
// 工具实现逻辑
return JSON.stringify({ success: true });
}
```
**第二步：注册工具**
在 `src/index.ts` 中将新工具添加到 `ListToolsRequestSchema` 和 `CallToolRequestSchema` 的处理逻辑中。
**第三步：添加测试**
在 `test/` 目录下创建对应的测试文件，确保覆盖正常路径和异常路径：
```typescript
describe('My Tool', () => {
it('should work correctly', async () => {
// 测试实现
});
});
```
### 可用脚本命令
| 命令 | 功能 |
|-----|------|
| npm run build | 编译 TypeScript 到 dist/ 目录 |
| npm test | 运行所有测试 |
| npm run test:coverage | 生成测试覆盖率报告 |
| npm run typecheck | TypeScript 类型检查 |
| npm run dev | 监听模式自动编译 |
## 故障排查
### 服务器无法启动
首先确认 Node.js 版本符合要求：
```bash
node --version # 需要 18.0.0 或更高版本
```
然后尝试重新构建：
```bash
npm run build
```
如果使用 bin 可执行文件，确保其有执行权限：
```bash
chmod +x bin/npm-registry-mcp.js
```
### 测试失败
清除 node_modules 和 lock 文件后重新安装：
```bash
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`。
## 相关资源
- [开发指南](./DEVELOPMENT.md) - 详细的开发环境配置和架构说明
- [AI 使用指南](./AI_USAGE.md) - AI 助手的自动触发规则和最佳实践
- [提示词参考](./PROMPTS.md) - MCP 快捷命令和自定义工作流
- [贡献指南](./CONTRIBUTING.md) - 代码贡献规范和 Pull Request 流程
- [能力分析](./CAPABILITIES.md) - 包能力检测详解
- [ productivity 工作流](./PRODUCTIVITY.md) - 常用场景的组合使用示例
---
## 项目介绍
### 相关页面
相关主题：[首页](#page-home), [安装配置](#page-installation), [快速入门](#page-quickstart)
相关源码文件
以下源码文件用于生成本页说明：
- [server.json](https://github.com/alisaitteke/npm-mcp/blob/main/server.json)
- [AI_USAGE.md](https://github.com/alisaitteke/npm-mcp/blob/main/AI_USAGE.md)
- [PRODUCTIVITY.md](https://github.com/alisaitteke/npm-mcp/blob/main/PRODUCTIVITY.md)
- [DEVELOPMENT.md](https://github.com/alisaitteke/npm-mcp/blob/main/DEVELOPMENT.md)
- [CONTRIBUTING.md](https://github.com/alisaitteke/npm-mcp/blob/main/CONTRIBUTING.md)
- [src/tools/package-details.ts](https://github.com/alisaitteke/npm-mcp/blob/main/src/tools/package-details.ts)
- [src/tools/version-compatibility.ts](https://github.com/alisaitteke/npm-mcp/blob/main/src/tools/version-compatibility.ts)
- [src/tools/quick-start.ts](https://github.com/alisaitteke/npm-mcp/blob/main/src/tools/quick-start.ts)
- [CAPABILITIES.md](https://github.com/alisaitteke/npm-mcp/blob/main/CAPABILITIES.md)
# 项目介绍
npm-mcp 是一个基于 Model Context Protocol (MCP) 协议的 npm 注册表服务器，为 AI 助手提供 npm 包管理能力。通过集成 npm-mcp，AI 助手能够自动搜索、验证和管理 npm 包，极大提升开发效率。
## 项目概述
npm-mcp 充当 AI 助手与 npm 注册表之间的桥梁，使 AI 能够执行以下操作：
- 搜索和发现 npm 包
- 获取包详细信息
- 进行安全审计
- 检查版本兼容性
- 分析包能力和质量
- 生成快速开始代码示例
资料来源：[DEVELOPMENT.md:1-15](https://github.com/alisaitteke/npm-mcp/blob/main/DEVELOPMENT.md)
## 核心工具
npm-mcp 提供一系列 MCP 工具，每个工具负责特定的 npm 包管理功能。
### 工具列表
| 工具名称 | 功能描述 | 输入参数 |
|---------|---------|---------|
| `search_packages` | 搜索 npm 包 | `query`, `size?` |
| `package_details` | 获取包详细信息 | `packageName`, `version?` |
| `audit_security` | 安全审计 | `packageName`, `version?` |
| `check_compatibility` | 版本兼容性检查 | `packageName`, `toVersion`, `fromVersion?` |
| `analyze_capabilities` | 包能力分析 | `packageName`, `version?` |
| `analyze_quality` | 质量分析 | `packageName` |
| `compare_packages` | 包对比 | `packages` |
| `find_similar_packages` | 查找相似包 | `packageName` |
| `analyze_bundle_size` | 体积分析 | `packageName` |
| `npx_command` | NPX 命令分析 | `command`, `args?`, `timeout?` |
| `quick_start` | 快速开始代码 | `packageName`, `framework?` |
资料来源：[DEVELOPMENT.md:20-35](https://github.com/alisaitteke/npm-mcp/blob/main/DEVELOPMENT.md)
### search_packages
搜索 npm 注册表中的包，支持关键词和模糊匹配。
```typescript
search_packages({
query: "react state management",
size: 5
})
```
返回结果包含包名、描述、版本、下载量等信息。
### package_details
获取包的完整信息，包括版本、依赖、许可证、发布时间等。
```typescript
package_details({
packageName: "axios",
version: "1.6.0"
})
```
返回数据结构：
```json
{
"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](https://github.com/alisaitteke/npm-mcp/blob/main/src/tools/package-details.ts)
### check_compatibility
检查包升级时的版本兼容性，识别潜在的破坏性变更。
```typescript
check_compatibility({
packageName: "express",
fromVersion: "4.17.1",
toVersion: "4.18.2"
})
```
返回结果包含：
- 破坏性变更列表
- 依赖差异分析
- SemVer 摘要
- 兼容性建议
资料来源：[src/tools/version-compatibility.ts:1-80](https://github.com/alisaitteke/npm-mcp/blob/main/src/tools/version-compatibility.ts)
### analyze_capabilities
分析包的现代特性支持情况：
| 能力类别 | 检查项 |
|---------|--------|
| 模块系统 | ESM、CommonJS、Dual Package |
| TypeScript | 内置类型、@types 包、位置 |
| 平台支持 | Node.js、Browser、Deno、Bun |
| 导出字段 | exports 字段、Conditional exports |
```json
{
"moduleSystem": {
"esm": true,
"commonjs": true,
"dualPackage": true
},
"typescript": {
"hasTypes": true,
"typesLocation": "./dist/index.d.ts"
},
"platform": {
"node": true,
"browser": true
}
}
```
资料来源：[CAPABILITIES.md:1-60](https://github.com/alisaitteke/npm-mcp/blob/main/CAPABILITIES.md)
## 架构设计
### 技术栈
| 组件 | 技术 |
|-----|------|
| 运行时 | Node.js 18+ |
| 语言 | TypeScript |
| 协议 | MCP (Model Context Protocol) |
| HTTP 客户端 | 原生 fetch API |
资料来源：[DEVELOPMENT.md:25-30](https://github.com/alisaitteke/npm-mcp/blob/main/DEVELOPMENT.md)
### 项目结构
```
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](https://github.com/alisaitteke/npm-mcp/blob/main/DEVELOPMENT.md)
### 核心组件架构
```mermaid
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 通信。
**主要特性：**
| 特性 | 配置值 |
|-----|-------|
| 并发限制 | 10 个请求 |
| 缓存策略 | LRU，5 分钟 TTL |
| 重试机制 | 指数退避（429 响应） |
| 速率限制 | 集成 npm API 限制 |
资料来源：[DEVELOPMENT.md:22-25](https://github.com/alisaitteke/npm-mcp/blob/main/DEVELOPMENT.md)
### 请求处理流程
```mermaid
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 助手可以读取这些资源来了解包的安全状态和兼容性要求。
```json
{
"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](https://github.com/alisaitteke/npm-mcp/blob/main/AUTOMATIC.md)
### 自动化工作流
npm-mcp 支持 AI 助手自动执行安全检查，无需用户显式请求：
```mermaid
graph LR
A[用户请求] --> B{AI 检测到包名}
B -->|自动触发| C[audit_security]
C --> D{是否有漏洞?}
D -->|是| E[警告 + 建议安全版本]
D -->|否| F[继续正常流程]
E --> G[提供安全安装命令]
F --> H[执行原请求]
```
**自动化场景示例：**
| 场景 | AI 自动行为 |
|-----|------------|
| 用户说"我想用 axios" | 自动运行 `audit_security("axios")` |
| 用户粘贴 package.json | 批量审计所有依赖 |
| 用户说"安装 express" | 检查安全 + 兼容性后再安装 |
资料来源：[AI_USAGE.md:1-50](https://github.com/alisaitteke/npm-mcp/blob/main/AI_USAGE.md)
### 提示词集成
npm-mcp 支持自定义提示词，可用于自动化常见工作流：
| 提示词 | 用途 |
|-------|------|
| `/check_before_install` | 安装前检查包安全性 |
| `/audit_project` | 审计整个项目的依赖 |
| `/find_package` | 搜索合适的包 |
| `/compare_packages` | 对比多个包 |
```javascript
// 示例：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](https://github.com/alisaitteke/npm-mcp/blob/main/PROMPTS.md)
## 使用方式
### 安装
```bash
npm install -g @alisaitteke/npm-mcp
```
### 配置 Cursor
在 Cursor 设置中添加 MCP 服务器：
```json
{
"mcpServers": {
"npm-registry": {
"command": "npx",
"args": ["-y", "@alisaitteke/npm-registry-mcp"]
}
}
}
```
### 开发设置
```bash
git clone https://github.com/alisaitteke/npm-mcp.git
cd npm-mcp
npm install
npm run build
```
资料来源：[DEVELOPMENT.md:1-10](https://github.com/alisaitteke/npm-mcp/blob/main/DEVELOPMENT.md)
### 常用命令
| 命令 | 描述 |
|-----|------|
| `npm run build` | 构建 dist/ 目录 |
| `npm test` | 运行测试 |
| `npm run test:coverage` | 生成覆盖率报告 |
| `npm run typecheck` | TypeScript 类型检查 |
| `npm run dev` | 监视模式构建 |
资料来源：[DEVELOPMENT.md:5-10](https://github.com/alisaitteke/npm-mcp/blob/main/DEVELOPMENT.md)
## 常见问题排查
### 服务器无法启动
| 检查项 | 解决方法 |
|-------|---------|
| Node 版本 | 确认 Node 18+：`node --version` |
| 构建文件 | 重新构建：`npm run build` |
| 执行权限 | 赋予权限：`chmod +x bin/npm-registry-mcp.js` |
### GitHub 速率限制
质量分析工具使用 GitHub API，未认证限制为 60 请求/小时，部分包分析可能失败。
**解决方案：**
- 设置 `GITHUB_TOKEN` 环境变量
- 使用认证的 GitHub 应用
资料来源：[DEVELOPMENT.md:45-50](https://github.com/alisaitteke/npm-mcp/blob/main/DEVELOPMENT.md)
### 测试失败
```bash
rm -rf node_modules package-lock.json
npm install
npm run build
npm test
```
## 扩展开发
### 添加新工具
**步骤 1：创建工具文件**
```typescript
// 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,
client: RegistryClient
): Promise {
const validated = MyToolSchema.parse(params);
// 实现逻辑
return JSON.stringify({ success: true });
}
```
**步骤 2：注册到服务器**
在 `src/index.ts` 中：
- 在 `ListToolsRequestSchema` 处理器中添加工具列表
- 在 `CallToolRequestSchema` 处理器中调用工具处理器
**步骤 3：添加测试**
```typescript
// test/my-tool.test.ts
describe('My Tool', () => {
it('should work correctly', async () => {
// 测试实现
});
});
```
资料来源：[CONTRIBUTING.md:80-120](https://github.com/alisaitteke/npm-mcp/blob/main/CONTRIBUTING.md)
### 分支命名规范
| 前缀 | 用途 |
|-----|------|
| `feature/` | 新功能 |
| `fix/` | 错误修复 |
| `docs/` | 文档更新 |
| `test/` | 测试相关 |
| `refactor/` | 代码重构 |
### 提交规范
遵循 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](https://github.com/alisaitteke/npm-mcp/blob/main/CONTRIBUTING.md)
## 最佳实践
### 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](https://github.com/alisaitteke/npm-mcp/blob/main/CAPABILITIES.md)
## 参见
- [安全审计文档](./SECURITY.md) — 详细的漏洞检测机制
- [开发指南](./DEVELOPMENT.md) — 架构和工具参考
- [AI 使用指南](./AI_USAGE.md) — 自动化工作流配置
- [贡献指南](./CONTRIBUTING.md) — 代码贡献流程
---
## 安装配置
### 相关页面
相关主题：[项目介绍](#page-introduction), [快速入门](#page-quickstart)
相关源码文件
以下源码文件用于生成本页说明：
- [DEVELOPMENT.md](https://github.com/alisaitteke/npm-mcp/blob/main/DEVELOPMENT.md)
- [CONTRIBUTING.md](https://github.com/alisaitteke/npm-mcp/blob/main/CONTRIBUTING.md)
- [AI_USAGE.md](https://github.com/alisaitteke/npm-mcp/blob/main/AI_USAGE.md)
- [AUTOMATIC.md](https://github.com/alisaitteke/npm-mcp/blob/main/AUTOMATIC.md)
- [src/index.ts](https://github.com/alisaitteke/npm-mcp/blob/main/src/index.ts)
- [src/registry-client.ts](https://github.com/alisaitteke/npm-mcp/blob/main/src/registry-client.ts)
# 安装配置
本文档详细说明 npm-mcp 的安装、环境配置、项目初始化以及常见配置选项。npm-mcp 是一个基于 MCP（Model Context Protocol）的 npm 注册表服务器，提供包搜索、安全审计、版本兼容性检查等功能。
## 环境要求
### 系统 prerequisites
npm-mcp 基于 Node.js 原生 fetch API 构建，因此对 Node.js 版本有明确要求：
| 要求项 | 最低版本 | 推荐版本 | 说明 |
|--------|----------|----------|------|
| Node.js | 18.0.0 | 20.x LTS | 必须支持原生 fetch |
| npm | 8.x+ | 最新版 | 用于包管理 |
| 操作系统 | macOS/Linux/Windows | 任意主流系统 | 无平台限制 |
确认 Node.js 版本：
```bash
node --version
```
资料来源：[DEVELOPMENT.md:1-5](https://github.com/alisaitteke/npm-mcp/blob/main/DEVELOPMENT.md)
### GitHub API 限制说明
质量分析功能依赖 GitHub API，未认证请求限制为每小时 60 次。部分包的分析可能因此失败，这是预期行为。
## 安装步骤
### 方式一：直接安装（推荐）
通过 npm 全局安装或项目本地安装：
```bash
# 全局安装
npm install -g @alisaitteke/npm-mcp
# 或项目本地安装
npm install @alisaitteke/npm-mcp
```
安装完成后可通过 `npx` 直接运行：
```bash
npx npm-registry-mcp
```
资料来源：[DEVELOPMENT.md:1-5](https://github.com/alisaitteke/npm-mcp/blob/main/DEVELOPMENT.md)
### 方式二：源码安装（开发用途）
适用于需要自定义修改或参与开发贡献的场景：
```bash
# 克隆仓库
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](https://github.com/alisaitteke/npm-mcp/blob/main/CONTRIBUTING.md)
### 方式三：二进制执行权限设置
源码安装后需要赋予执行权限：
```bash
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](https://github.com/alisaitteke/npm-mcp/blob/main/DEVELOPMENT.md)
## MCP 服务器配置
### MCP 客户端集成
npm-mcp 作为 MCP 服务器运行，需要在 MCP 客户端（如 Cursor、Claude Desktop）中配置。以下是典型的配置文件结构：
```json
{
"mcpServers": {
"npm-registry": {
"command": "npx",
"args": ["npm-registry-mcp"]
}
}
}
```
### 资源配置（AI 自动化）
MCP 资源是**被动加载**的——当 MCP 连接时自动加载，无需额外设置。资源文件定义在 `src/index.ts` 中：
| 资源类型 | 用途 | 自动行为 |
|----------|------|----------|
| 安全规则 | 定义包安装前必须检查 | 自动触发安全审计 |
| 包信息 | 提供包元数据标准格式 | 返回包详细信息 |
| 质量标准 | 定义包质量评估规则 | 支持质量分析 |
资料来源：[AUTOMATIC.md:95-110](https://github.com/alisaitteke/npm-mcp/blob/main/AUTOMATIC.md)
## 客户端配置
### 注册表客户端参数
`RegistryClient` 是核心组件，负责与 npm 注册表 API 通信：
```typescript
// src/registry-client.ts 中的默认配置
const DEFAULT_CONFIG = {
maxConcurrent: 10, // 最大并发请求数
cacheTTL: 5 * 60 * 1000, // 缓存 TTL: 5分钟
retryAttempts: 3, // 重试次数
retryDelay: 1000, // 重试延迟基数（指数退避）
};
```
### 请求限流机制
```mermaid
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](https://github.com/alisaitteke/npm-mcp/blob/main/DEVELOPMENT.md)
### 缓存管理
内部缓存可通过以下方式清除：
```typescript
client.clearCache();
```
## 可用脚本命令
| 命令 | 描述 | 用途 |
|------|------|------|
| `npm run build` | 编译 TypeScript 到 dist/ | 生产构建 |
| `npm test` | 运行 Vitest 测试 | 单元测试 |
| `npm run test:coverage` | 生成覆盖率报告 | 测试覆盖率检查 |
| `npm run typecheck` | TypeScript 类型检查 | 类型验证 |
| `npm run dev` | 监听模式构建 | 开发调试 |
资料来源：[DEVELOPMENT.md:6-13](https://github.com/alisaitteke/npm-mcp/blob/main/DEVELOPMENT.md)
## AI 平台配置
### Cursor 配置
在 `~/.cursor/.cursorrules`（全局规则文件）中添加：
```markdown
# 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](https://github.com/alisaitteke/npm-mcp/blob/main/AI_USAGE.md)
### 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 提示
```
## 常见问题排查
### 服务器无法启动
按以下顺序排查：
1. **检查 Node.js 版本**：确保 >= 18.0.0
```bash
node --version
```
2. **重新编译**：删除 node_modules 和 lock 文件后重新安装
```bash
rm -rf node_modules package-lock.json
npm install
npm run build
```
3. **检查二进制权限**：
```bash
chmod +x bin/npm-registry-mcp.js
```
资料来源：[DEVELOPMENT.md:52-62](https://github.com/alisaitteke/npm-mcp/blob/main/DEVELOPMENT.md)
### GitHub API 速率限制
质量分析使用 GitHub API，未认证限制为 60 请求/小时。若部分包分析失败属正常现象。
解决方案：
- 使用 GitHub Personal Access Token 配置更高限制
- 等待速率限制重置（约 1 小时）
### 测试失败
完整的测试环境重置步骤：
```bash
rm -rf node_modules package-lock.json
npm install
npm run build
npm test
```
资料来源：[DEVELOPMENT.md:62-68](https://github.com/alisaitteke/npm-mcp/blob/main/DEVELOPMENT.md)
## 环境变量配置
### 可选环境变量
| 变量名 | 默认值 | 说明 |
|--------|--------|------|
| `NPM_REGISTRY_URL` | https://registry.npmjs.org | npm 注册表地址 |
| `GITHUB_TOKEN` | 无 | GitHub API Token（提高速率限制） |
| `NODE_ENV` | development | 运行环境 |
### 配置示例
```bash
# 设置 GitHub Token 提高 API 限制
export GITHUB_TOKEN=ghp_xxxxxxxxxxxx
# 使用私有注册表
export NPM_REGISTRY_URL=https://registry.mycompany.com
# 生产环境运行
export NODE_ENV=production
```
## 验证安装
安装完成后可通过以下方式验证：
```bash
# 检查 MCP 服务器是否正常运行
npx npm-registry-mcp --version
# 或通过 MCP 客户端测试工具调用
# 使用 search_packages 查询一个包
```
## 扩展配置
### 添加自定义工具
1. 在 `src/tools/` 目录下创建新的工具文件：
```typescript
// 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, client: RegistryClient) {
// 实现逻辑
}
```
2. 在 `src/index.ts` 中注册工具：
- 在 `ListToolsRequestSchema` 中列出工具
- 在 `CallToolRequestSchema` 中调用处理器
3. 添加测试用例：`test/.test.ts`
资料来源：[DEVELOPMENT.md:70-80](https://github.com/alisaitteke/npm-mcp/blob/main/DEVELOPMENT.md)
## 相关文档
- [快速入门指南](./QUICK_START.md) - 快速上手 npm-mcp
- [工具参考](./TOOLS.md) - 所有可用 MCP 工具详细说明
- [AI 集成指南](./AI_USAGE.md) - 在 AI 助手中使用 npm-mcp
- [开发指南](./DEVELOPMENT.md) - 项目开发和贡献指南
- [贡献指南](./CONTRIBUTING.md) - 代码贡献流程
---
## 快速入门
### 相关页面
相关主题：[安装配置](#page-installation), [工具模块参考](#page-tools-reference)
相关源码文件
以下源码文件用于生成本页说明：
- [AI_USAGE.md](https://github.com/alisaitteke/npm-mcp/blob/main/AI_USAGE.md)
- [PROMPTS.md](https://github.com/alisaitteke/npm-mcp/blob/main/PROMPTS.md)
- [AUTOMATIC.md](https://github.com/alisaitteke/npm-mcp/blob/main/AUTOMATIC.md)
- [PRODUCTIVITY.md](https://github.com/alisaitteke/npm-mcp/blob/main/PRODUCTIVITY.md)
- [DEVELOPMENT.md](https://github.com/alisaitteke/npm-mcp/blob/main/DEVELOPMENT.md)
- [CONTRIBUTING.md](https://github.com/alisaitteke/npm-mcp/blob/main/CONTRIBUTING.md)
# 快速入门
本页面为 `@alisaitteke/npm-mcp` 项目的快速入门指南，帮助开发者快速了解项目的安装配置、核心工具使用方法以及常见工作流程。通过本指南，您将能够在 5 分钟内完成环境搭建并开始使用 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]()
## 环境要求与安装
### 系统要求
| 要求项 | 最低版本 | 说明 |
|--------|----------|------|
| Node.js | 18.0.0+ | 需要原生 fetch 支持 |
| npm/yarn/pnpm | 最新稳定版 | 包管理器 |
| AI 客户端 | 支持 MCP 的版本 | Cursor、Claude Desktop 等 |
资料来源：[DEVELOPMENT.md:1-10]()
### 安装步骤
```bash
# 克隆项目仓库
git clone https://github.com/alisaitteke/npm-mcp.git
cd npm-mcp
# 安装项目依赖
npm install
# 构建项目
npm run build
```
安装完成后，可通过以下方式运行服务器：
```bash
# 直接运行（需要 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` 中添加：
```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 工具，每个工具专注于特定的功能领域。以下是核心工具的快速参考表：
| 工具名称 | 功能描述 | 主要输入参数 |
|----------|----------|--------------|
| `search_packages` | 搜索 NPM 包 | `query`（搜索关键词） |
| `get_package_details` | 获取包详细信息 | `packageName`、`version`（可选） |
| `audit_security` | 安全漏洞审计 | `packageName`、`version`（可选） |
| `check_compatibility` | 检查依赖兼容性 | `packageName`、`version`、`projectDeps` |
| `analyze_capabilities` | 分析包能力特性 | `packageName`、`version`（可选） |
| `analyze_npx_command` | 分析 npx 命令 | `command`、`args`（可选）、`timeout`（可选） |
资料来源：[PROMPTS.md:1-50]()
### 安全审计工具详解
`audit_security` 是使用频率最高的工具之一，用于检查 NPM 包是否存在已知的安全漏洞：
```typescript
// 调用示例
audit_security({
packageName: "express",
version: "4.18.2" // 可选，不提供则检查最新版本
})
```
**返回结果示例**
```json
{
"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
// 搜索 TypeScript 相关的 HTTP 客户端库
search_packages({
query: "typescript http client"
})
```
搜索结果按相关性排序，包含包的下载量、维护状态和质量评分等关键信息。
资料来源：[PRODUCTIVITY.md:1-30]()
## 基础使用示例
### 工作流程一：安装前安全检查
在推荐任何包安装之前，AI 助手应自动执行安全检查流程：
```mermaid
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 应自动搜索并比较：
```typescript
// 用户问：有没有比 lodash 更轻量的替代品?
find_similar_packages({ packageName: "lodash" })
// 返回类似包列表，包含：
// - date-fns（日期处理）
// - lodash-es（ESM 版本）
// - nanoid（ID 生成）
```
资料来源：[PRODUCTIVITY.md:50-80]()
### 工作流程三：批量审计项目依赖
当用户提供 `package.json` 或项目路径时，AI 应自动审计所有依赖：
```javascript
// 自动触发场景
用户: "帮我检查项目依赖安全性"
用户: "audit_project"
用户: "npm install typescript" // 隐式触发
// AI 自动执行：
1. 提取 package.json 中的 dependencies
2. 对每个包调用 audit_security（并行执行）
3. 生成漏洞报告表格
4. 提供更新命令
```
资料来源：[AUTOMATIC.md:40-70]()
## 常用工作流
### 自动触发机制
`npm-mcp` 设计了智能的自动触发机制，AI 助手无需显式调用工具即可自动执行安全检查。以下是触发规则表：
| 用户输入关键词 | 自动调用的工具 | 执行目的 |
|----------------|----------------|----------|
| "install X", "add X" | `audit_security` + `check_compatibility` | 安装前验证 |
| "which package", "best library" | `search_packages` | 包搜索 |
| "npx create-..." | `analyze_npx_command` | 命令验证 |
| 提及包名 | `get_package_details` | 显示包信息 |
| "update X", "upgrade X" | `compare_versions` + `audit_security` | 更新检查 |
| 粘贴 package.json | `audit_security`（所有依赖） | 批量审计 |
资料来源：[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
```
**典型响应**
```
✅ express@4.18.2 is safe to install
Security: No known vulnerabilities
Compatibility: ✅ No peer dependency conflicts
Maintenance: Active (last update: 2 days ago)
Install: npm install express@4.18.2
```
资料来源：[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. lodash@4.17.20 → 4.17.21
- Issue: Open redirect
- Fix: npm install lodash@4.17.21
2. moment@2.29.1 → 2.29.4
- Issue: Path traversal
- Fix: npm install moment@2.29.4
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]()
## 故障排查
### 常见问题与解决方案
| 问题现象 | 可能原因 | 解决方案 |
|----------|----------|----------|
| 服务器无法启动 | Node.js 版本过低 | 确认 Node.js >= 18.0.0：`node --version` |
| 服务器无法启动 | 缺少构建产物 | 重新构建：`npm run build` |
| 服务器无法启动 | bin 文件无执行权限 | 赋予权限：`chmod +x bin/npm-registry-mcp.js` |
| GitHub API 请求失败 | 触发速率限制 | 等待或使用认证 Token（60 req/h 限制） |
| 搜索结果为空 | NPM 注册表超时 | 检查网络连接，重试请求 |
资料来源：[DEVELOPMENT.md:35-50]()
### 测试与调试
如果遇到功能异常，可通过以下步骤进行调试：
```bash
# 清除缓存重新安装
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]()
## 相关资源
| 资源类型 | 说明 | 链接 |
|----------|------|------|
| GitHub 仓库 | 项目主仓库 | [alisaitteke/npm-mcp](https://github.com/alisaitteke/npm-mcp) |
| AI 使用指南 | AI 助手的自动化触发配置 | [AI_USAGE.md](./AI_USAGE.md) |
| 提示词参考 | MCP Prompts 完整说明 | [PROMPTS.md](./PROMPTS.md) |
| 自动执行 | 自主代理的自动检查机制 | [AUTOMATIC.md](./AUTOMATIC.md) |
| 生产力工具 | 组合工作流和比较工具 | [PRODUCTIVITY.md](./PRODUCTIVITY.md) |
| 开发指南 | 项目架构和工具添加方法 | [DEVELOPMENT.md](./DEVELOPMENT.md) |
| 贡献指南 | PR 流程和代码规范 | [CONTRIBUTING.md](./CONTRIBUTING.md) |
| 能力分析 | 包能力特性分析工具详解 | [CAPABILITIES.md](./CAPABILITIES.md) |
---
## 系统架构
### 相关页面
相关主题：[数据管理与缓存](#page-data-flow), [工具模块参考](#page-tools-reference), [开发指南](#page-development)
相关源码文件
以下源码文件用于生成本页说明：
- [src/index.ts](https://github.com/alisaitteke/npm-mcp/blob/main/src/index.ts)
- [src/registry-client.ts](https://github.com/alisaitteke/npm-mcp/blob/main/src/registry-client.ts)
- [src/types.ts](https://github.com/alisaitteke/npm-mcp/blob/main/src/types.ts)
- [DEVELOPMENT.md](https://github.com/alisaitteke/npm-mcp/blob/main/DEVELOPMENT.md)
- [CONTRIBUTING.md](https://github.com/alisaitteke/npm-mcp/blob/main/CONTRIBUTING.md)
- [src/tools/package-details.ts](https://github.com/alisaitteke/npm-mcp/blob/main/src/tools/package-details.ts)
- [src/tools/version-compatibility.ts](https://github.com/alisaitteke/npm-mcp/blob/main/src/tools/version-compatibility.ts)
# 系统架构
## 概述
npm-mcp 是一个基于 Model Context Protocol (MCP) 的 npm 注册表服务工具集，为 AI 助手提供与 npm 注册表交互的能力。该项目使 AI 能够安全地查询、审计和分析 npm 包，无需直接访问外部网络或执行危险的安装命令。 资料来源：[DEVELOPMENT.md](https://github.com/alisaitteke/npm-mcp/blob/main/DEVELOPMENT.md)
项目采用 TypeScript 开发，要求 Node.js 18 及以上版本，利用原生 fetch API 进行网络请求。架构设计遵循模块化原则，每个功能作为独立的工具实现，便于维护和扩展。 资料来源：[DEVELOPMENT.md:1-15](https://github.com/alisaitteke/npm-mcp/blob/main/DEVELOPMENT.md)
## 核心架构组件
### 组件概览
| 组件 | 文件路径 | 职责描述 |
|------|----------|----------|
| MCP 服务器入口 | `src/index.ts` | 处理 MCP 协议请求，路由工具调用 |
| 注册表客户端 | `src/registry-client.ts` | 与 npm API 通信，实现缓存和限流 |
| 类型定义 | `src/types.ts` | 共享 TypeScript 类型定义 |
| 工具模块 | `src/tools/*.ts` | 各功能工具的具体实现 |
资料来源：[CONTRIBUTING.md:65-75](https://github.com/alisaitteke/npm-mcp/blob/main/CONTRIBUTING.md)
### 系统架构图
```mermaid
graph TD
A[AI 助手] -->|MCP Protocol| B[MCP Server
src/index.ts]
B --> C[Tool Router
CallToolRequestSchema]
C --> D[search-packages
包搜索]
C --> E[package-details
包详情]
C --> F[security-audit
安全审计]
C --> G[version-compatibility
版本兼容性]
C --> H[quality-analysis
质量分析]
C --> I[npx-command
NPX 命令]
C --> J[analyze_capabilities
能力分析]
C --> K[find_similar_packages
相似包查找]
C --> L[compare_packages
包对比]
C --> M[generate_quick_start
快速入门代码]
D --> N[Registry Client
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
LRU Cache
5min TTL]
N --> R[Rate Limiter
Max 10 concurrent]
```
## 注册表客户端架构
`RegistryClient` 是整个系统的核心网络层，负责所有与外部 API 的通信。它实现了缓存机制、并发限制和指数退避策略，确保在高并发场景下的稳定性。 资料来源：[DEVELOPMENT.md:18-20](https://github.com/alisaitteke/npm-mcp/blob/main/DEVELOPMENT.md)
### 客户端配置参数
| 参数 | 默认值 | 说明 |
|------|--------|------|
| 并发限制 | 10 | 最大同时进行的 HTTP 请求数 |
| 缓存 TTL | 5 分钟 | 包元数据、下载统计的缓存过期时间 |
| 429 处理 | 指数退避 | 遇到速率限制时自动重试 |
| 重试策略 | 指数退避 | 请求失败时逐步增加等待时间 |
资料来源：[DEVELOPMENT.md:18-20](https://github.com/alisaitteke/npm-mcp/blob/main/DEVELOPMENT.md)
### 缓存机制
注册表客户端使用 LRU（最近最少使用）缓存策略，缓存内容包括包元数据、下载统计和 GitHub 信息。缓存可通过 `client.clearCache()` 方法手动清除。 资料来源：[DEVELOPMENT.md:22-23](https://github.com/alisaitteke/npm-mcp/blob/main/DEVELOPMENT.md)
```mermaid
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
```
### 速率限制处理
```mermaid
graph LR
A[请求发送] --> B{响应状态}
B -->|200 OK| C[返回数据]
B -->|429 Too Many Requests| D[指数退避等待]
D --> E[重试请求]
E --> B
B -->|其他错误| F[返回错误信息]
```
## 工具模块架构
### 工具列表与分类
| 工具名称 | 输入参数 | 功能描述 |
|----------|----------|----------|
| `search_packages` | `query`, `size?` | 搜索 npm 注册表中的包 |
| `get_package_details` | `packageName`, `version?` | 获取包详细信息 |
| `audit_security` | `packageName`, `version?` | 安全漏洞审计 |
| `check_compatibility` | `packageName`, `version?`, `existingDependencies?` | 检查版本兼容性 |
| `compare_versions` | `packageName`, `fromVersion`, `toVersion` | 版本对比分析 |
| `quality_analysis` | `packageName` | 包质量评分分析 |
| `analyze_npx_command` | `command`, `args?`, `timeout?` | NPX 命令分析 |
| `analyze_capabilities` | `packageName`, `version?` | 包能力分析 |
| `find_similar_packages` | `packageName` | 查找相似包 |
| `compare_packages` | `packages[]` | 多包对比 |
| `generate_quick_start` | `packageName`, `version?`, `framework?` | 生成快速入门代码 |
资料来源：[DEVELOPMENT.md:25-31](https://github.com/alisaitteke/npm-mcp/blob/main/DEVELOPMENT.md)
### 工具实现模式
每个工具遵循统一的实现模式，使用 Zod 进行输入验证，并通过 RegistryClient 与 npm API 交互。
```mermaid
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]
```
#### 示例：包详情工具
```typescript
// 资料来源：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,
client: RegistryClient
): Promise {
const validated = PackageDetailsSchema.parse(params);
// 实现逻辑...
}
```
#### 示例：版本兼容性检查
```typescript
// 资料来源：src/tools/version-compatibility.ts
export async function checkCompatibility(
params: z.infer,
client: RegistryClient
): Promise {
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);
}
```
## 数据模型
### 包详情响应结构
```typescript
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](https://github.com/alisaitteke/npm-mcp/blob/main/src/tools/package-details.ts)
### 兼容性检查响应结构
```typescript
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](https://github.com/alisaitteke/npm-mcp/blob/main/src/tools/version-compatibility.ts)
## MCP 协议集成
### 请求处理流程
```mermaid
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**：路由工具调用到具体处理函数
```typescript
// 资料来源：src/index.ts (架构示意)
const tools = [
{ name: 'search_packages', schema: SearchPackagesSchema, handler: searchPackages },
{ name: 'get_package_details', schema: PackageDetailsSchema, handler: getPackageDetails },
// ... 其他工具
];
```
## 错误处理机制
### 统一错误响应格式
所有工具使用一致的错误响应格式，便于 AI 助手解析和处理：
```json
{
"success": false,
"error": "错误信息描述",
"packageName": "包名称（如适用）",
"version": "版本号（如适用）"
}
```
资料来源：[src/tools/package-details.ts:80-90](https://github.com/alisaitteke/npm-mcp/blob/main/src/tools/package-details.ts)
### 错误处理流程
```mermaid
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
```
## 扩展架构
### 添加新工具的流程
```mermaid
graph LR
A[创建工具文件] -->|src/tools/<name>.ts| B[定义 Zod Schema]
B --> C[实现工具函数]
C --> D[注册到 index.ts]
D --> E[添加工具测试]
E --> F[test/<name>.test.ts]
```
### 新工具模板
```typescript
// 资料来源：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,
client: RegistryClient
): Promise {
const validated = MyToolSchema.parse(params);
// 实现逻辑
return JSON.stringify({ success: true });
}
```
### 在服务器中注册
```typescript
// 资料来源：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](https://github.com/alisaitteke/npm-mcp/blob/main/CONTRIBUTING.md)
## 技术栈
| 层级 | 技术 | 说明 |
|------|------|------|
| 语言 | TypeScript | 类型安全的 JavaScript 超集 |
| 运行时 | Node.js 18+ | 原生 fetch API 支持 |
| 协议 | MCP | Model Context Protocol |
| 验证 | Zod | Schema 验证和数据转换 |
| 测试 | Vitest | 单元测试框架 |
| 包管理 | npm | 包依赖管理 |
资料来源：[DEVELOPMENT.md:12-15](https://github.com/alisaitteke/npm-mcp/blob/main/DEVELOPMENT.md)
## 参见
- [开发指南](./DEVELOPMENT.md) - 详细的开发设置和脚本说明
- [贡献指南](./CONTRIBUTING.md) - 代码贡献流程和项目规范
- [AI 使用指南](./AI_USAGE.md) - AI 助手集成最佳实践
- [MCP 提示词](./PROMPTS.md) - 可用提示词和工作流
---
## 数据管理与缓存
### 相关页面
相关主题：[系统架构](#page-architecture)
相关源码文件
以下源码文件用于生成本页说明：
- [src/registry-client.ts](https://github.com/alisaitteke/npm-mcp/blob/main/src/registry-client.ts)
- [src/tools/package-details.ts](https://github.com/alisaitteke/npm-mcp/blob/main/src/tools/package-details.ts)
- [src/tools/version-compatibility.ts](https://github.com/alisaitteke/npm-mcp/blob/main/src/tools/version-compatibility.ts)
- [DEVELOPMENT.md](https://github.com/alisaitteke/npm-mcp/blob/main/DEVELOPMENT.md)
- [CONTRIBUTING.md](https://github.com/alisaitteke/npm-mcp/blob/main/CONTRIBUTING.md)
# 数据管理与缓存
本文档详细介绍了 npm-mcp 项目中的数据管理与缓存机制，包括注册表客户端架构、缓存策略、并发控制以及错误处理等核心组件。
## 概述
npm-mcp 作为 MCP（Model Context Protocol）服务器，需要频繁与 npm 注册表 API 进行交互以获取包信息、版本数据、安全审计结果等。为了提高性能并减少对外部 API 的依赖，项目实现了一套完整的数据管理与缓存系统。
**核心设计目标：**
- 减少重复的网络请求，提高响应速度
- 防止 API 限流，通过智能缓存和请求控制
- 确保数据一致性，在缓存过期时自动刷新
- 提供可观测性，便于调试和监控
资料来源：[DEVELOPMENT.md:1-15](https://github.com/alisaitteke/npm-mcp/blob/main/DEVELOPMENT.md)
## 架构设计
### 整体架构图
```mermaid
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
```
### 核心组件
| 组件名称 | 功能描述 | 实现位置 |
|---------|---------|---------|
| `RegistryClient` | 统一的 npm API 客户端 | `src/registry-client.ts` |
| `LRUCache` | 最近最少使用缓存 | `src/registry-client.ts` |
| `Semaphore` | 并发数量控制器 | `src/registry-client.ts` |
| `RetryHandler` | 指数退避重试逻辑 | `src/registry-client.ts` |
资料来源：[DEVELOPMENT.md:20-25](https://github.com/alisaitteke/npm-mcp/blob/main/DEVELOPMENT.md)
## 缓存策略
### 缓存类型与 TTL
npm-mcp 采用多种缓存策略以平衡数据新鲜度和性能：
```mermaid
graph LR
A[请求进来] --> B{缓存中存在?}
B -->|是,未过期| C[返回缓存数据]
B -->|否或已过期| D[发起新请求]
D --> E[更新缓存]
E --> C
```
#### 缓存数据分类
| 数据类型 | TTL（生存时间） | 说明 |
|---------|---------------|------|
| 包元数据 (Packument) | 5 分钟 | 包含版本列表、发布时间等 |
| 下载统计数据 | 5 分钟 | 每周下载量等指标 |
| GitHub 信息 | 5 分钟 | GitHub stars、issues 等 |
| 安全审计结果 | 5 分钟 | 漏洞信息 |
| 版本兼容性数据 | 5 分钟 | peerDependencies 分析结果 |
资料来源：[DEVELOPMENT.md:28-30](https://github.com/alisaitteke/npm-mcp/blob/main/DEVELOPMENT.md)
### LRU 缓存实现
缓存模块采用 LRU（Least Recently Used，最近最少使用）策略，当缓存达到容量上限时，自动清除最久未使用的数据项。
**缓存工作流程：**
```mermaid
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](https://github.com/alisaitteke/npm-mcp/blob/main/DEVELOPMENT.md)
## 并发控制
### 信号量机制
为了防止对 npm API 的过度请求，npm-mcp 使用信号量（Semaphore）模式限制并发请求数量。
**关键参数：**
| 参数 | 值 | 说明 |
|-----|-----|------|
| 最大并发数 | 10 | 同时最多发起 10 个请求 |
| 等待队列 | 无限制 | 超出并发的请求排队等待 |
资料来源：[DEVELOPMENT.md:26](https://github.com/alisaitteke/npm-mcp/blob/main/DEVELOPMENT.md)
### 并发控制流程
```mermaid
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）策略进行重试。
**重试策略参数：**
| 参数 | 说明 |
|-----|------|
| 初始延迟 | 1 秒 |
| 最大延迟 | 可配置上限 |
| 退避系数 | 2（每次重试延迟翻倍） |
| 最大重试次数 | 3-5 次（根据端点） |
**指数退避流程：**
```mermaid
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](https://github.com/alisaitteke/npm-mcp/blob/main/DEVELOPMENT.md)
### 其他错误处理
| 错误类型 | 处理方式 |
|---------|---------|
| 404 Not Found | 返回友好的错误消息，包不存在或版本不存在 |
| 500 Server Error | 自动重试 3 次，仍失败则返回错误 |
| 网络超时 | 重试机制处理，配置超时时间 |
| 无效响应 | 解析失败时返回结构化错误信息 |
## API 客户端实现
### RegistryClient 类
`RegistryClient` 是整个数据获取层的核心类，封装了所有与外部 API 的交互逻辑。
**主要方法：**
| 方法名 | 功能描述 |
|-------|---------|
| `getPackageMetadata()` | 获取包元数据（packument） |
| `getPackageVersion()` | 获取特定版本信息 |
| `getDownloadStats()` | 获取下载统计数据 |
| `getSecurityAudit()` | 获取安全审计结果 |
| `getGithubInfo()` | 获取 GitHub 仓库信息 |
| `clearCache()` | 清除所有缓存数据 |
资料来源：[src/registry-client.ts](https://github.com/alisaitteke/npm-mcp/blob/main/src/registry-client.ts)
### 请求验证
所有请求参数都经过 Zod 模式验证，确保：
- 包名称格式正确
- 版本号符合 semver 规范
- 参数类型正确
**验证示例（package-details.ts）：**
```typescript
export const PackageDetailsSchema = z.object({
packageName: z.string().min(1, "Package name is required"),
version: z.string().optional(),
});
```
资料来源：[src/tools/package-details.ts](https://github.com/alisaitteke/npm-mcp/blob/main/src/tools/package-details.ts)
## 数据模型
### 包详情数据结构
工具返回的结构化数据包含以下关键字段：
| 字段路径 | 类型 | 说明 |
|---------|-----|------|
| `success` | boolean | 请求是否成功 |
| `package.name` | string | 包名称 |
| `package.version` | string | 版本号 |
| `package.deprecated` | boolean/string | 是否废弃 |
| `metadata.license` | string | 许可证类型 |
| `metadata.maintainers` | array | 维护者列表 |
| `versions.total` | number | 版本总数 |
| `dependencies` | object | 依赖关系映射 |
| `dist.tarball` | string | tarball 下载地址 |
| `dist.integrity` | string | 完整性校验值 |
| `stats.weeklyDownloads` | string | 周下载量 |
资料来源：[src/tools/package-details.ts:80-120](https://github.com/alisaitteke/npm-mcp/blob/main/src/tools/package-details.ts)
### 版本兼容性数据结构
```json
{
"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](https://github.com/alisaitteke/npm-mcp/blob/main/src/tools/version-compatibility.ts)
## 性能优化实践
### 批量请求优化
当需要检查多个包的安全性或兼容性时，系统可以并行发起多个请求，充分利用并发控制机制。
```typescript
// 并行检查多个包
const results = await Promise.all([
client.getSecurityAudit("lodash"),
client.getSecurityAudit("express"),
client.getSecurityAudit("axios"),
]);
```
### 缓存预热
对于已知需要频繁访问的数据，可以实现缓存预热策略，在用户请求前主动获取并缓存数据。
### 请求去重
当多个请求同时发起且目标相同时，第一个请求会实际调用 API，其他请求等待结果并共享缓存数据。
## 常见问题与排查
### 服务器启动失败
| 检查项 | 解决方法 |
|-------|---------|
| Node.js 版本 | 确保 Node 18+：`node --version` |
| 构建文件 | 重新构建：`npm run build` |
| 执行权限 | 赋予执行权限：`chmod +x bin/npm-registry-mcp.js` |
资料来源：[DEVELOPMENT.md:40-45](https://github.com/alisaitteke/npm-mcp/blob/main/DEVELOPMENT.md)
### GitHub API 限流
质量分析功能依赖 GitHub API，未认证请求限额为 60 次/小时。
**现象：** 部分包的质量分析可能失败
**解决方案：** 这是设计行为，部分包的质量数据可能暂时不可用
资料来源：[DEVELOPMENT.md:46-49](https://github.com/alisaitteke/npm-mcp/blob/main/DEVELOPMENT.md)
### 测试失败
```bash
rm -rf node_modules package-lock.json
npm install
npm run build
npm test
```
资料来源：[DEVELOPMENT.md:50-54](https://github.com/alisaitteke/npm-mcp/blob/main/DEVELOPMENT.md)
### 缓存相关问题
| 问题现象 | 可能原因 | 解决方案 |
|---------|---------|---------|
| 返回过期数据 | 缓存 TTL 未到 | 等待 5 分钟或重启服务 |
| 缓存未命中 | 首次请求或缓存被清除 | 正常行为，系统会自动获取 |
## 项目结构参考
```
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](https://github.com/alisaitteke/npm-mcp/blob/main/DEVELOPMENT.md)
## 扩展开发
### 添加新的数据源
1. 在 `src/registry-client.ts` 中添加新的 API 方法
2. 实现缓存和重试逻辑
3. 在对应工具文件中调用新方法
### 自定义缓存策略
如需修改缓存 TTL 或容量，可以调整 `RegistryClient` 构造函数参数：
```typescript
const client = new RegistryClient({
cacheTTL: 5 * 60 * 1000, // 5 分钟
maxConcurrent: 10,
maxRetries: 3,
});
```
资料来源：[CONTRIBUTING.md:70-90](https://github.com/alisaitteke/npm-mcp/blob/main/CONTRIBUTING.md)
## 相关文档
- [开发指南](./DEVELOPMENT.md) - 完整的项目开发参考
- [贡献指南](./CONTRIBUTING.md) - 如何参与项目开发
- [工具使用](./AI_USAGE.md) - MCP 工具使用最佳实践
- [命令提示](./PROMPTS.md) - 快捷命令参考
---
## 工具模块参考
### 相关页面
相关主题：[安全审计功能](#page-security), [包比较与分析](#page-comparison), [快速入门](#page-quickstart)
相关源码文件
以下源码文件用于生成本页说明：
- [src/tools/search-packages.ts](https://github.com/alisaitteke/npm-mcp/blob/main/src/tools/search-packages.ts)
- [src/tools/package-details.ts](https://github.com/alisaitteke/npm-mcp/blob/main/src/tools/package-details.ts)
- [src/tools/version-compatibility.ts](https://github.com/alisaitteke/npm-mcp/blob/main/src/tools/version-compatibility.ts)
- [src/tools/quick-start.ts](https://github.com/alisaitteke/npm-mcp/blob/main/src/tools/quick-start.ts)
- [DEVELOPMENT.md](https://github.com/alisaitteke/npm-mcp/blob/main/DEVELOPMENT.md)
- [CONTRIBUTING.md](https://github.com/alisaitteke/npm-mcp/blob/main/CONTRIBUTING.md)
- [CAPABILITIES.md](https://github.com/alisaitteke/npm-mcp/blob/main/CAPABILITIES.md)
# 工具模块参考
本页面详细说明 npm-mcp 项目中所有可用的 MCP 工具模块，包括各工具的功能、输入输出参数、使用方式及架构设计。
## 1. 工具模块概述
npm-mcp 是一个基于 Model Context Protocol (MCP) 的 npm 注册表服务工具集，为 AI 助手提供与 npm registry 交互的能力。所有工具均位于 `src/tools/` 目录下，采用统一的架构模式实现。
### 1.1 工具列表
| 工具名称 | 文件路径 | 主要功能 |
|---------|----------|----------|
| `search_packages` | [search-packages.ts](src/tools/search-packages.ts) | 搜索 npm 包 |
| `package_details` | [package-details.ts](src/tools/package-details.ts) | 获取包详细信息 |
| `security_audit` | security-audit.ts | 安全漏洞审计 |
| `check_compatibility` | [version-compatibility.ts](src/tools/version-compatibility.ts) | 依赖兼容性检查 |
| `quality_analysis` | quality-analysis.ts | 包质量分析 |
| `analyze_npx_command` | npx-command.ts | NPX 命令分析 |
| `generate_quick_start` | [quick-start.ts](src/tools/quick-start.ts) | 生成快速开始代码 |
### 1.2 架构设计
工具模块采用分层架构，确保代码的可维护性和可扩展性：
```mermaid
graph TD
A[用户请求] --> B[MCP Server
index.ts]
B --> C[工具调度器
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
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. **错误处理**：捕获异常并返回友好的错误信息
```typescript
// 标准工具模块结构
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,
client: RegistryClient
): Promise {
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](https://github.com/alisaitteke/npm-mcp/blob/main/CONTRIBUTING.md)
## 2. search_packages 工具
`search_packages` 工具提供 npm 包的搜索功能，允许用户通过关键词查找相关包。
### 2.1 输入参数
| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| query | string | 是 | 搜索关键词 |
| size | number | 否 | 返回结果数量，默认 10 |
### 2.2 输出结构
```json
{
"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 使用示例
```typescript
// 搜索 React 状态管理库
search_packages({
query: "react state management",
size: 5
})
```
资料来源：[src/tools/search-packages.ts](https://github.com/alisaitteke/npm-mcp/blob/main/src/tools/search-packages.ts)
## 3. package_details 工具
`package_details` 工具提供 npm 包的完整元数据信息，包括版本、依赖、维护者等详细信息。
### 3.1 输入参数
| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| packageName | string | 是 | npm 包名称 |
| version | string | 否 | 指定版本，默认为最新版本 |
### 3.2 输出结构
```json
{
"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 核心功能
该工具从多个数据源聚合信息：
```mermaid
graph LR
A[package_details 请求] --> B[获取 Packument]
B --> C[获取版本数据]
C --> D[获取下载统计]
D --> E[聚合输出]
```
资料来源：[src/tools/package-details.ts](https://github.com/alisaitteke/npm-mcp/blob/main/src/tools/package-details.ts)
## 4. check_compatibility 工具
`check_compatibility` 工具验证包与现有依赖的兼容性，特别是检查 peer dependencies。
### 4.1 输入参数
| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| packageName | string | 是 | 要检查的包名称 |
| version | string | 否 | 指定版本 |
| peerDependencies | object | 否 | 项目现有的 peer 依赖 |
### 4.2 输出结构
```json
{
"success": true,
"package": "package-name",
"version": "1.0.0",
"compatible": true,
"analysis": {
"peerDependencies": {
"total": 3,
"compatible": 3,
"conflicts": 0,
"missing": 0
},
"details": {
"compatible": ["react@18.x", "react-dom@18.x"],
"conflicts": [],
"missing": []
}
},
"recommendation": "Package is compatible with existing dependencies. Safe to install.",
"suggestedActions": []
}
```
### 4.3 兼容性判断逻辑
```mermaid
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](https://github.com/alisaitteke/npm-mcp/blob/main/src/tools/version-compatibility.ts)
## 5. generate_quick_start 工具
`generate_quick_start` 工具根据包信息自动生成快速开始代码示例，支持多种框架和场景。
### 5.1 输入参数
| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| packageName | string | 是 | npm 包名称 |
| framework | string | 否 | 框架类型（react, vue, express, fastify 等） |
| language | string | 否 | 编程语言，默认 typescript |
### 5.2 支持的框架类型
| 框架 | 生成内容 |
|------|----------|
| react | React 组件示例 |
| vue | Vue 组件示例 |
| express | Express API 路由 |
| fastify | Fastify API 路由 |
| node | 通用 Node.js 示例 |
| browser | 浏览器使用示例 |
### 5.3 输出结构
```json
{
"packageName": "package-name",
"description": "Framework description",
"language": "typescript",
"code": "export const usage = 'example code...'"
}
```
### 5.4 代码生成示例
```typescript
// 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](https://github.com/alisaitteke/npm-mcp/blob/main/src/tools/quick-start.ts)
## 6. 工具注册与调度
### 6.1 注册流程
工具需要在 `src/index.ts` 中进行注册才能被 MCP 协议识别：
```mermaid
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/.ts`
2. **注册工具**：在 `src/index.ts` 的 `ListToolsRequestSchema` 中添加
3. **实现调度**：在 `CallToolRequestSchema` 中添加处理逻辑
```typescript
// 步骤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,
client: RegistryClient
): Promise {
// 实现逻辑
}
```
```typescript
// 步骤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](https://github.com/alisaitteke/npm-mcp/blob/main/DEVELOPMENT.md)
## 7. Registry Client 架构
Registry Client 是所有工具的底层依赖，提供统一的 API 调用能力。
### 7.1 核心功能
| 功能 | 配置 | 说明 |
|------|------|------|
| 并发限制 | 10 | 最多同时 10 个请求 |
| 缓存 | LRU, 5分钟 | 自动缓存响应 |
| 重试 | 指数退避 | 429 错误时自动重试 |
| 超时 | 30秒 | 请求超时设置 |
### 7.2 缓存策略
```mermaid
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 内部方法
```typescript
class RegistryClient {
// 缓存管理
clearCache(): void;
// 基础请求
async fetchPackument(packageName: string): Promise;
async fetchVersion(packageName: string, version: string): Promise;
async getDownloadStats(packageName: string): Promise;
}
```
资料来源：[DEVELOPMENT.md](https://github.com/alisaitteke/npm-mcp/blob/main/DEVELOPMENT.md)
## 8. 输入验证
### 8.1 Zod Schema 模式
所有工具使用 Zod 进行输入验证，确保类型安全：
```typescript
// 必填字符串
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 验证流程
```mermaid
flowchart TD
A[接收参数] --> B[Zod Schema.parse]
B --> C{验证通过?}
C -->|是| D[执行工具逻辑]
C -->|否| E[抛出 ZodError]
E --> F[捕获并返回错误 JSON]
D --> G[返回成功结果]
```
### 8.3 错误处理
```typescript
export async function toolHandler(params: any, client: RegistryClient): Promise {
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](https://github.com/alisaitteke/npm-mcp/blob/main/CONTRIBUTING.md)
## 9. 工具组合使用
### 9.1 推荐工作流
```mermaid
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 典型场景组合
| 场景 | 工具组合 |
|------|----------|
| 安装前检查 | `audit_security` + `check_compatibility` + `package_details` |
| 选择最佳包 | `search_packages` + `compare_packages` + `quality_analysis` |
| 版本升级 | `compare_versions` + `audit_security` |
| 项目审计 | `audit_project` + 批量 `audit_security` |
### 9.3 代码示例
```typescript
// 完整的安装前检查
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](https://github.com/alisaitteke/npm-mcp/blob/main/CAPABILITIES.md)
## 10. 测试工具模块
### 10.1 测试框架
项目使用 Vitest 作为测试框架，每个工具应有对应的测试文件：
```
test/
├── search-packages.test.ts
├── package-details.test.ts
├── version-compatibility.test.ts
└── ...
```
### 10.2 测试示例
```typescript
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 运行测试
```bash
# 运行所有测试
npm test
# 运行带覆盖率的测试
npm run test:coverage
# 类型检查
npm run typecheck
```
资料来源：[CONTRIBUTING.md](https://github.com/alisaitteke/npm-mcp/blob/main/CONTRIBUTING.md)
## 11. 常见问题
### 11.1 服务器无法启动
**问题**：执行 `npx npm-registry-mcp` 无响应
**解决方案**：
1. 检查 Node.js 版本（需要 18+）：
```bash
node --version
```
2. 重新构建项目：
```bash
npm run build
```
3. 检查可执行权限：
```bash
chmod +x bin/npm-registry-mcp.js
```
### 11.2 GitHub 速率限制
**问题**：质量分析工具返回错误
**原因**：GitHub API 未认证限制为 60 请求/小时
**解决方案**：某些包的 GitHub 信息可能暂时不可用，属正常现象
### 11.3 测试失败
**解决方案**：
```bash
rm -rf node_modules package-lock.json
npm install
npm run build
npm test
```
资料来源：[DEVELOPMENT.md](https://github.com/alisaitteke/npm-mcp/blob/main/DEVELOPMENT.md)
## 12. 参考链接
- [项目主仓库](https://github.com/alisaitteke/npm-mcp)
- [开发文档](./DEVELOPMENT.md)
- [贡献指南](./CONTRIBUTING.md)
- [AI 使用指南](./AI_USAGE.md)
- [生产力工具](./PRODUCTIVITY.md)
- [MCP 提示词](./PROMPTS.md)
---
## 安全审计功能
### 相关页面
相关主题：[工具模块参考](#page-tools-reference)
相关源码文件
以下源码文件用于生成本页说明：
- [src/tools/security-audit.ts](https://github.com/alisaitteke/npm-mcp/blob/main/src/tools/security-audit.ts)
- [AI_USAGE.md](https://github.com/alisaitteke/npm-mcp/blob/main/AI_USAGE.md)
- [PROMPTS.md](https://github.com/alisaitteke/npm-mcp/blob/main/PROMPTS.md)
- [CONTRIBUTING.md](https://github.com/alisaitteke/npm-mcp/blob/main/CONTRIBUTING.md)
- [DEVELOPMENT.md](https://github.com/alisaitteke/npm-mcp/blob/main/DEVELOPMENT.md)
- [PRODUCTIVITY.md](https://github.com/alisaitteke/npm-mcp/blob/main/PRODUCTIVITY.md)
# 安全审计功能
## 概述
安全审计功能是 npm-mcp 的核心功能之一，提供对 npm 包的安全漏洞检测和分析能力。该功能通过调用 npm 官方安全 API 接口，获取包的安全信息，并在 AI 助手中实现自动化的安全检查工作流。安全审计功能与其他工具（如版本兼容性检查、能力分析）协同工作，为开发者提供全面的包安装安全建议。资料来源：[AI_USAGE.md]()
## 核心功能模块
### 1. 单包安全审计 (`audit_security`)
单包安全审计是最基础的安全检查功能，用于检测指定 npm 包是否存在已知安全漏洞。资料来源：[src/tools/security-audit.ts]()
**主要功能：**
- 检查包是否存在已知安全漏洞
- 获取漏洞的详细描述信息
- 提供安全版本建议
- 支持指定具体版本或范围的审计
**使用场景：**
- 在安装任何新包之前进行安全检查
- 检查现有依赖包的安全性
- 在 AI 对话中自动触发（当用户提及包名时）
```typescript
// 基础调用示例
audit_security({
packageName: "lodash",
version?: "4.17.20" // 可选，指定版本
})
```
### 2. 项目级安全审计 (`audit_project`)
项目级安全审计用于扫描整个项目的 package.json 文件，审计所有依赖项的安全性。资料来源：[PROMPTS.md]()
**工作流程：**
1. 读取项目的 package.json 文件
2. 提取所有依赖项（dependencies、devDependencies）
3. 对每个依赖项执行并行安全检查
4. 汇总结果并提供修复建议
```json
{
"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. 显示清晰的 ✅/⚠️ 推荐结果
**响应格式：**
```
✅ express@4.18.2 is safe to install
Security: No known vulnerabilities
Compatibility: ✅ No peer dependency conflicts
Maintenance: Active (last update: 2 days ago)
Install: npm install express@4.18.2
```
## 架构设计
### 组件关系图
```mermaid
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
```
### 安全审计数据流
```mermaid
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: 后续请求从缓存获取
```
## 输出数据结构
### 安全审计响应格式
```json
{
"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"
}
```
### 漏洞严重等级说明
| 等级 | 说明 | 建议操作 |
|------|------|----------|
| critical | 严重漏洞，需要立即处理 | 必须更新到安全版本 |
| high | 高危漏洞，可能影响系统安全 | 建议尽快更新 |
| medium | 中危漏洞，需要关注 | 考虑在近期更新 |
| low | 低危漏洞，影响较小 | 可在下次维护时处理 |
## 缓存与限流机制
安全审计功能复用项目统一的缓存和限流机制。资料来源：[DEVELOPMENT.md]()
### 缓存策略
- **TTL**: 5 分钟
- **适用数据**: 包的安全漏洞信息、下载统计、GitHub 数据
- **缓存清理**: `client.clearCache()` 方法（内部调用）
### 并发限制
| 参数 | 值 | 说明 |
|------|-----|------|
| 最大并发数 | 10 | 同时处理的最大请求数 |
| 429 响应处理 | 指数退避 | 遇到速率限制时自动重试 |
## 与其他工具的集成
### 集成关系图
```mermaid
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**
```mermaid
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]()
### 触发关键词
| 触发条件 | 示例 | 自动执行 |
|----------|------|----------|
| 安装命令 | "install X", "add X" | `audit_security` + `check_compatibility` |
| 包名提及 | "express", "lodash" | `audit_security` |
| 更新命令 | "update X", "upgrade X" | `audit_security` + `compare_versions` |
| package.json 粘贴 | 修改依赖 | `audit_security`（所有依赖）|
### AI 响应模板
**安全包响应：**
```
✅ express@4.18.2 is safe to install
Security: No vulnerabilities
Compatibility: ✅ Compatible with your dependencies
Quality: 95/100 (11M weekly downloads)
Install:
npm install express@4.18.2
```
**危险包响应：**
```
⚠️ SECURITY WARNING: lodash@4.17.20 has 2 vulnerabilities
Severity: High
Issue: Prototype pollution
Safe version: lodash@4.17.21
Recommended:
npm install lodash@4.17.21
```
## 错误处理
安全审计功能实现了完善的错误处理机制。资料来源：[src/tools/security-audit.ts]()
### 常见错误类型
| 错误类型 | 原因 | 处理方式 |
|----------|------|----------|
| 网络错误 | 无法连接 NPM Registry | 返回友好错误信息，建议重试 |
| 包不存在 | 包名拼写错误 | 提示检查包名 |
| API 限流 | 请求频率过高 | 自动重试（指数退避） |
| 无漏洞数据 | 包不在漏洞库中 | 返回"无已知漏洞"状态 |
### 错误响应格式
```json
{
"success": false,
"error": "Package not found: invalid-package-name",
"packageName": "invalid-package-name",
"suggestion": "Please check the package name and try again"
}
```
## 扩展工具集成
安全审计功能可以与其他生产力工具协同使用，提供更全面的分析。资料来源：[PRODUCTIVITY.md]()
### 与包比较工具结合
```mermaid
graph TD
A["用户: axios vs node-fetch"] --> B["compare_packages"]
B --> C["axios 安全性分析"]
B --> D["node-fetch 安全性分析"]
C --> E["安全对比报告"]
D --> E
E --> F["推荐: axios"]
```
### 与包体分析工具结合
```typescript
// 组合使用示例
{
"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]()
```bash
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/` 目录下为新功能编写测试
## 相关文档
- [开发指南](./DEVELOPMENT.md) - 了解项目架构和工具开发规范
- [贡献指南](./CONTRIBUTING.md) - 了解如何为项目贡献代码
- [AI 使用指南](./AI_USAGE.md) - 了解 AI 集成最佳实践
- [MCP 提示词](./PROMPTS.md) - 了解快捷命令的使用
- [生产力工具](./PRODUCTIVITY.md) - 了解组合工作流
- [包能力分析](./CAPABILITIES.md) - 了解包的技术特性分析
---
**文档版本**: 1.0
**最后更新**: 2024年
**维护者**: npm-mcp 团队
---
## 包比较与分析
### 相关页面
相关主题：[工具模块参考](#page-tools-reference)
相关源码文件
以下源码文件用于生成本页说明：
- [src/tools/package-details.ts](https://github.com/alisaitteke/npm-mcp/blob/main/src/tools/package-details.ts)
- [src/tools/version-compatibility.ts](https://github.com/alisaitteke/npm-mcp/blob/main/src/tools/version-compatibility.ts)
- [src/tools/quality-analysis.ts](https://github.com/alisaitteke/npm-mcp/blob/main/src/tools/quality-analysis.ts)
- [src/tools/npx-command.ts](https://github.com/alisaitteke/npm-mcp/blob/main/src/tools/npx-command.ts)
- [CAPABILITIES.md](https://github.com/alisaitteke/npm-mcp/blob/main/CAPABILITIES.md)
- [PRODUCTIVITY.md](https://github.com/alisaitteke/npm-mcp/blob/main/PRODUCTIVITY.md)
- [AI_USAGE.md](https://github.com/alisaitteke/npm-mcp/blob/main/AI_USAGE.md)
# 包比较与分析
## 概述
包比较与分析是 npm-mcp 项目的核心功能模块之一，旨在帮助开发者在选择和使用 npm 包时做出明智的决策。该模块提供了全面的包分析能力，包括包兼容性检查、质量评估、依赖分析、安全审计以及多包对比等功能。
npm-mcp 通过整合 NPM Registry API、Bundlephobia API 和 GitHub API 等多个数据源，为开发者提供了一站式的包分析解决方案。这些工具可以独立使用，也可以组合形成完整的工作流程，帮助开发者在项目开发过程中快速评估和比较不同的 npm 包。
资料来源：[PRODUCTIVITY.md]()
## 核心工具架构
### 工具分类
npm-mcp 的包比较与分析功能由多个专业工具组成，每个工具专注于特定的分析维度。
| 工具名称 | 功能描述 | 数据来源 |
|---------|---------|---------|
| `package_details` | 获取包完整信息 | NPM Registry |
| `version_compatibility` | 检查版本兼容性 | NPM Registry |
| `quality_analysis` | 质量评分分析 | NPM + GitHub |
| `analyze_capabilities` | 模块系统分析 | NPM Registry |
| `compare_packages` | 多包对比 | 多个 API |
| `analyze_bundle_size` | 打包体积分析 | Bundlephobia |
| `find_similar_packages` | 查找相似包 | NPM Registry |
资料来源：[DEVELOPMENT.md]()
### 架构流程图
```mermaid
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]()
### 输出数据结构
```json
{
"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]()
### 关键字段说明
| 字段路径 | 类型 | 说明 |
|---------|------|------|
| `package.isLatest` | boolean | 是否为最新版本 |
| `versions.deprecatedVersions` | array | 已被废弃的版本列表 |
| `dependencies.peerDependencies` | object | 对等依赖关系 |
| `dist.unpackedSize` | string | 解压后的文件大小 |
| `stats.weeklyDownloads` | string | 周下载量（本地化格式） |
## 版本兼容性检查
### 功能概述
`version_compatibility` 工具用于检查目标包的版本与当前项目依赖之间的兼容性。该工具特别关注对等依赖（peer dependencies）的匹配情况，帮助开发者识别可能出现的版本冲突。
资料来源：[src/tools/version-compatibility.ts]()
### 兼容性分析流程
```mermaid
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[返回问题报告]
```
### 输出结构
```json
{
"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. **建议生成**：根据检测结果提供具体的修复建议
```typescript
const isCompatible = conflicts.length === 0 && missing.length === 0;
```
资料来源：[src/tools/version-compatibility.ts:47]()
## 包能力分析
### 模块系统分析
`analyze_capabilities` 工具深入分析包的技术特性，特别关注其模块系统支持情况。
资料来源：[CAPABILITIES.md]()
#### 支持的模块类型
| 模块类型 | 说明 | 特征 |
|---------|------|------|
| ESM | ES Modules | `import/export` 语法 |
| CommonJS | 传统模块系统 | `require/module.exports` |
| UMD | 通用模块定义 | 同时支持浏览器和服务端 |
| Dual Package | 双包支持 | 同时提供 ESM 和 CJS 版本 |
#### TypeScript 支持分析
工具会检测包是否包含 TypeScript 类型定义：
- **内置类型**：包本身包含 `.d.ts` 文件
- **类型包**：需要安装独立的 `@types/` 包
- **TypeScript 编写的包**：包使用 TypeScript 开发
```json
{
"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]()
### 平台兼容性分析
工具还检测包对不同运行时的支持情况：
| 平台 | 标识 | 说明 |
|-----|------|------|
| Node.js | `node: true` | 服务端 JavaScript 运行时 |
| Browser | `browser: true` | 浏览器环境 |
| Deno | `deno: true` | 现代 TypeScript 运行时 |
| Bun | `bun: true` | 快速全功能 JavaScript 运行时 |
| React | `react: true` | React 组件库 |
| React Native | `react-native: true` | 移动开发平台 |
```json
{
"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]()
### 对比维度
| 维度 | 分析内容 | 数据来源 |
|-----|---------|---------|
| 模块系统 | ESM/CJS/Dual 支持 | NPM Registry |
| TypeScript | 类型定义情况 | NPM Registry |
| 流行度 | 周下载量 | NPM Registry |
| 维护状态 | 最后更新时间 | NPM Registry |
| 打包体积 | gzip 大小 | Bundlephobia |
### 示例输出
```json
{
"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]()
### 体积指标说明
| 指标 | 说明 | 用途 |
|-----|------|------|
| Unpacked Size | 解压后磁盘占用 | 评估安装空间 |
| Minified Size | 压缩后大小 | 理论最小体积 |
| Gzipped Size | Gzip 压缩后大小 | 实际网络传输量 |
| Tree-shaking | 摇树优化支持 | 按需加载能力 |
### 输出结构
```json
{
"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]()
### 影响等级评估
| 等级 | Gzip 大小范围 | 建议 |
|-----|-------------|------|
| Excellent | < 10 KB | 非常适合添加 |
| Good | 10-50 KB | 可接受 |
| Medium | 50-100 KB | 谨慎考虑 |
| Large | > 100 KB | 建议寻找替代方案 |
## 相似包查找
### 功能概述
`find_similar_packages` 工具根据包的关键词和用途查找相似的替代包，帮助开发者发现可能更优的选择。
资料来源：[PRODUCTIVITY.md]()
### 工作流程
```mermaid
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]()
### 分析内容
| 检查项 | 说明 | 阈值 |
|-------|------|------|
| 包存在性 | 验证包在 NPM Registry 中存在 | - |
| 版本验证 | 确认指定版本是否存在 | - |
| 可执行文件 | 检查包是否包含 bin 入口 | - |
| 体积检查 | 评估包解压后的大小 | > 10MB 警告 |
| 包龄检查 | 检查版本发布时间 | > 365 天警告 |
| 依赖数量 | 统计直接依赖数量 | > 50 警告 |
### 输出结构
```json
{
"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]()
## 组合工作流程
### 完整包评估流程
```mermaid
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]()
## 使用建议
### 最佳实践
| 场景 | 推荐工具 | 目的 |
|-----|---------|------|
| 选择新包前 | `compare_packages` | 多维度对比 |
| 评估打包影响 | `analyze_bundle_size` | 避免大体积包 |
| 安装前检查 | `audit_security` + `version_compatibility` | 安全且兼容 |
| 查找替代品 | `find_similar_packages` | 发现更好的选择 |
| 验证 npx 命令 | `analyze_npx_command` | 安全执行 |
### 工具组合策略
1. **开发阶段**：使用 `find_similar_packages` 发现最佳选择
2. **评估阶段**：使用 `compare_packages` 进行多包对比
3. **引入前**：使用 `audit_security` + `version_compatibility` 进行安全检查
4. **上线前**：使用 `analyze_bundle_size` 评估打包影响
### 响应模板
当 AI 使用这些工具时，建议使用以下模板提供清晰的反馈：
```
✅ express@4.18.2 安全可安装
安全性: 无已知漏洞
兼容性: ✅ 与现有依赖无冲突
质量: 95/100 (周下载 1100 万)
安装命令:
npm install express@4.18.2
```
## 相关文档
| 文档 | 内容 |
|-----|------|
| [安全性审计](./安全性审计.md) | 详细的漏洞检测功能说明 |
| [版本管理](./版本管理.md) | 版本比较和升级策略 |
| [快速入门](./快速入门.md) | 基础使用指南 |
| [开发指南](./开发指南.md) | 项目架构和扩展方法 |
## 参见
- [包能力分析工具](./CAPABILITIES.md)
- [生产力工具文档](./PRODUCTIVITY.md)
- [AI 使用指南](./AI_USAGE.md)
- [版本兼容性检查](./src/tools/version-compatibility.ts)
---
## 开发指南
### 相关页面
相关主题：[系统架构](#page-architecture)
相关源码文件
以下源码文件用于生成本页说明：
- [DEVELOPMENT.md](https://github.com/alisaitteke/npm-mcp/blob/main/DEVELOPMENT.md)
- [CONTRIBUTING.md](https://github.com/alisaitteke/npm-mcp/blob/main/CONTRIBUTING.md)
- [src/index.ts](https://github.com/alisaitteke/npm-mcp/blob/main/src/index.ts)
- [src/registry-client.ts](https://github.com/alisaitteke/npm-mcp/blob/main/src/registry-client.ts)
- [src/tools/package-details.ts](https://github.com/alisaitteke/npm-mcp/blob/main/src/tools/package-details.ts)
- [src/tools/version-compatibility.ts](https://github.com/alisaitteke/npm-mcp/blob/main/src/tools/version-compatibility.ts)
# 开发指南
本开发指南面向希望为 `@alisaitteke/npm-mcp` 项目贡献代码或扩展功能的开发者。文档涵盖项目环境搭建、核心架构解析、工具开发流程以及测试规范，帮助开发者快速上手并有效地参与项目开发。
## 项目概述
npm-mcp 是一个基于 Model Context Protocol (MCP) 的 npm 注册表服务器实现，为 AI 助手提供与 npm 注册表交互的工具集。该项目使 AI 能够在不离开对话环境的情况下执行包搜索、安全审计、版本兼容性检查等操作，显著提升开发工作流的效率。
项目采用 TypeScript 开发，运行于 Node.js 18+ 环境，充分利用原生 fetch API 与现代异步编程模式。核心架构围绕注册表客户端和 MCP 工具层展开，通过模块化设计实现各功能组件的独立性与可维护性。
## 环境搭建
### 前置条件
在开始开发之前，请确保本地环境满足以下要求：
| 要求项 | 最低版本 | 说明 |
|--------|----------|------|
| Node.js | 18.0.0 | 使用原生 fetch API |
| npm | 9.0.0 | 包管理工具 |
| Git | 2.30.0 | 版本控制 |
### 初始化步骤
```bash
# 克隆仓库
git clone https://github.com/alisaitteke/npm-mcp.git
cd npm-mcp
# 安装依赖
npm install
# 构建项目
npm run build
```
资料来源：[DEVELOPMENT.md:1-10](https://github.com/alisaitteke/npm-mcp/blob/main/DEVELOPMENT.md)
### 验证安装
构建成功后，可通过以下命令验证环境配置正确：
```bash
# 运行测试套件
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](https://github.com/alisaitteke/npm-mcp/blob/main/DEVELOPMENT.md)
### 目录职责说明
| 目录/文件 | 职责 | 关键依赖 |
|-----------|------|----------|
| `src/index.ts` | MCP 服务器主入口，处理请求路由 | `@modelcontextprotocol/sdk` |
| `src/registry-client.ts` | NPM 注册表 API 客户端，含缓存和限流 | lru-cache, p-limit |
| `src/types.ts` | 共享类型定义 | TypeScript 内置 |
| `src/tools/*.ts` | 各功能工具实现 | Zod 模式验证 |
| `test/` | 单元测试与集成测试 | Vitest |
## 核心架构
### 系统组件关系
```mermaid
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](https://github.com/alisaitteke/npm-mcp/blob/main/src/registry-client.ts)
#### 缓存机制
注册表客户端使用 LRU（最近最少使用）缓存策略，缓存内容包括包元数据、下载统计和 GitHub 信息。默认配置下，缓存有效期为 5 分钟。
```typescript
this.cache = new LRUCache({
max: config.cacheMaxSize || 500,
ttl: config.cacheTTL || 5 * 60 * 1000, // 5 分钟
});
```
资料来源：[src/registry-client.ts:30-33](https://github.com/alisaitteke/npm-mcp/blob/main/src/registry-client.ts)
#### 并发控制
系统限制最大并发请求数为 10，使用 `p-limit` 库实现。当遇到 429（请求过多）响应时，客户端自动执行指数退避重试策略。
| 参数 | 默认值 | 说明 |
|------|--------|------|
| `maxConcurrent` | 10 | 最大并发请求数 |
| `cacheTTL` | 300000ms | 缓存有效期（5分钟） |
| `cacheMaxSize` | 500 | 缓存条目上限 |
| `registryUrl` | registry.npmjs.org | NPM 注册表地址 |
资料来源：[src/registry-client.ts:35-38](https://github.com/alisaitteke/npm-mcp/blob/main/src/registry-client.ts)
#### 核心 API 方法
```typescript
// 获取包元数据（packument）
async getPackage(packageName: string): Promise
// 获取特定版本信息
async getPackageVersion(packageName: string, version: string): Promise
// 搜索包
async searchPackages(query: string, options?: { limit?: number; offset?: number }): Promise
// 获取下载统计
async getDownloadStats(packageName: string, period?: 'last-day' | 'last-week' | 'last-month'): Promise
```
资料来源：[src/registry-client.ts:45-80](https://github.com/alisaitteke/npm-mcp/blob/main/src/registry-client.ts)
## 可用脚本
项目提供一组 npm 脚本用于日常开发流程。
| 命令 | 描述 |
|------|------|
| `npm run build` | 编译 TypeScript 到 `dist/` 目录 |
| `npm test` | 运行测试套件 |
| `npm run test:coverage` | 生成测试覆盖率报告 |
| `npm run typecheck` | 执行 TypeScript 类型检查 |
| `npm run dev` | 监听模式开发，自动重新构建 |
资料来源：[DEVELOPMENT.md:10-16](https://github.com/alisaitteke/npm-mcp/blob/main/DEVELOPMENT.md)
## MCP 工具开发
MCP 工具是项目的核心功能单元，每个工具对应一个独立的 TypeScript 模块。以下是现有工具及其功能说明。
### 现有工具列表
| 工具名称 | 功能描述 | 输入参数 |
|----------|----------|----------|
| `search_packages` | 搜索 npm 注册表中的包 | `query`, `limit` |
| `get_package_details` | 获取包的详细信息 | `packageName`, `version` |
| `audit_security` | 检查包的安全漏洞 | `packageName`, `version` |
| `check_compatibility` | 检查版本兼容性 | `packageName`, `targetVersion`, `installed` |
| `analyze_capabilities` | 分析包的模块系统能力 | `packageName`, `version` |
| `compare_versions` | 比较两个版本 | `packageName`, `fromVersion`, `toVersion` |
| `analyze_npx_command` | 分析 npx 命令 | `command`, `args`, `timeout` |
### 添加工具流程
#### 第一步：创建工具模块
在 `src/tools/` 目录下创建新的工具文件，例如 `src/tools/my-tool.ts`。每个工具文件应包含 Zod 模式定义和异步处理函数。
```typescript
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,
client: RegistryClient
): Promise {
// 验证输入参数
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](https://github.com/alisaitteke/npm-mcp/blob/main/CONTRIBUTING.md)
#### 第二步：注册工具
在 `src/index.ts` 中，需要在两个位置添加新工具：
1. 在 `ListToolsRequestSchema` 处理器中列出工具定义
2. 在 `CallToolRequestSchema` 处理器中调用对应的处理函数
```typescript
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](https://github.com/alisaitteke/npm-mcp/blob/main/CONTRIBUTING.md)
#### 第三步：编写测试
在 `test/` 目录下创建对应的测试文件 `test/my-tool.test.ts`。
```typescript
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](https://github.com/alisaitteke/npm-mcp/blob/main/CONTRIBUTING.md)
## 工具实现示例
### 包详情工具
`package-details.ts` 是项目中最复杂的工具之一，展示了如何聚合多个 API 调用的结果。
```mermaid
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](https://github.com/alisaitteke/npm-mcp/blob/main/src/tools/package-details.ts)
该工具返回的数据结构包含：
| 字段 | 类型 | 说明 |
|------|------|------|
| `success` | boolean | 请求是否成功 |
| `package.name` | string | 包名称 |
| `package.version` | string | 版本号 |
| `package.deprecated` | string \| null | 弃用信息 |
| `metadata.license` | string | 许可证类型 |
| `metadata.maintainers` | array | 维护者列表 |
| `versions.latest` | string | 最新版本 |
| `versions.total` | number | 版本总数 |
| `dependencies.*` | object | 各类依赖关系 |
| `stats.weeklyDownloads` | string | 周下载量 |
资料来源：[src/tools/package-details.ts:60-100](https://github.com/alisaitteke/npm-mcp/blob/main/src/tools/package-details.ts)
### 版本兼容性工具
`version-compatibility.ts` 演示了如何分析 peer dependencies 的兼容性。
```typescript
export async function checkCompatibility(
params: { packageName, targetVersion, installedPackages? },
client: RegistryClient
): Promise {
// 获取目标包的 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](https://github.com/alisaitteke/npm-mcp/blob/main/src/tools/version-compatibility.ts)
## 代码规范
### TypeScript 配置
项目使用 TypeScript 严格模式，建议编辑器配置以下检查：
```json
{
"compilerOptions": {
"strict": true,
"esModuleInterop": true,
"moduleResolution": "node",
"target": "ES2022"
}
}
```
### 代码风格要点
| 规范 | 说明 |
|------|------|
| 类型定义 | 使用 interface 和 type 定义共享类型 |
| 输入验证 | 所有工具输入必须通过 Zod 模式验证 |
| 错误处理 | 使用 try-catch，返回结构化错误信息 |
| 异步模式 | 优先使用 async/await |
| 注释规范 | 公共 API 添加 JSDoc 注释 |
资料来源：[CONTRIBUTING.md:35-45](https://github.com/alisaitteke/npm-mcp/blob/main/CONTRIBUTING.md)
### 提交规范
项目遵循 Conventional Commits 规范，提交信息格式如下：
```
:
[optional body]
[optional footer]
```
常用 type 值：
| type | 使用场景 |
|------|----------|
| `feat` | 新功能 |
| `fix` | 错误修复 |
| `docs` | 文档更新 |
| `test` | 测试相关 |
| `refactor` | 代码重构 |
资料来源：[CONTRIBUTING.md:25-33](https://github.com/alisaitteke/npm-mcp/blob/main/CONTRIBUTING.md)
## 分支管理
| 分支前缀 | 用途 | 示例 |
|----------|------|------|
| `feature/` | 新功能开发 | `feature/search-filter` |
| `fix/` | 错误修复 | `fix/cache-invalidation` |
| `docs/` | 文档更新 | `docs/api-reference` |
| `test/` | 测试相关 | `test/coverage-improvement` |
| `refactor/` | 代码重构 | `refactor/client-abstraction` |
## 测试规范
### 测试框架
项目使用 Vitest 作为测试框架，要求：
- 所有新功能必须包含测试用例
- 维护或改进代码覆盖率
- 测试成功和错误两种情况
- 使用描述性的测试名称
### 运行测试
```bash
# 运行所有测试
npm test
# 生成覆盖率报告
npm run test:coverage
# 类型检查
npm run typecheck
```
资料来源：[DEVELOPMENT.md:10-16](https://github.com/alisaitteke/npm-mcp/blob/main/DEVELOPMENT.md)
## 故障排查
### 服务器无法启动
```bash
# 检查 Node 版本
node --version # 需要 >= 18.0.0
# 重新构建项目
npm run build
# 检查可执行权限
chmod +x bin/npm-registry-mcp.js
```
### GitHub 速率限制
质量分析工具使用 GitHub API，未认证请求限制为每小时 60 次。部分包可能因此失败。
### 测试失败
```bash
# 清理并重新安装依赖
rm -rf node_modules package-lock.json
npm install
npm run build
npm test
```
资料来源：[DEVELOPMENT.md:55-68](https://github.com/alisaitteke/npm-mcp/blob/main/DEVELOPMENT.md)
## 发布流程
当代码合并到主分支后，发布流程如下：
1. 更新 `package.json` 中的版本号
2. 更新 `CHANGELOG.md`
3. 创建 Git 标签
4. 发布到 npm
```bash
# 版本更新
npm version patch # 或 minor, major
# 发布
npm publish
```
资料来源：[CONTRIBUTING.md:130-135](https://github.com/alisaitteke/npm-mcp/blob/main/CONTRIBUTING.md)
## 相关资源
- [CONTRIBUTING.md](https://github.com/alisaitteke/npm-mcp/blob/main/CONTRIBUTING.md) - 贡献指南
- [AI_USAGE.md](https://github.com/alisaitteke/npm-mcp/blob/main/AI_USAGE.md) - AI 使用指南
- [PROMPTS.md](https://github.com/alisaitteke/npm-mcp/blob/main/PROMPTS.md) - MCP 提示词参考
---
---
## Doramagic 踩坑日志
项目：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