📦 NPM Helper - A tool to help your ai assistant with npm package management.🤖

📦 NPM Helper - 帮助 AI 助手管理 npm 包的工具。🤖

用于管理 NPM 依赖项的 Model Context Protocol 服务。此服务提供 NPM 包搜索工具和 npm 包更新工具，确保项目依赖项保持最新，并更新到兼容的最新版本，避免冲突和麻烦。

作为安全升级任何项目 package.json 的基准方案，助手可以调用 upgradePackagets 工具，并将 'peer' 参数设为 true。这可能不会将所有依赖项都更新到最新版本，但可以安全地将它们升级到兼容的最新版本，且不会产生错误。

如果你想完整升级所有依赖项，助手可以使用许多工具和参数进行安全探索。参数选项和示例见下方“可用工具”部分。你也可以在 'docs' 目录中找到更多信息。

如果你正在探索要添加到项目的新包，或想了解特定包的信息，也可以使用相关工具搜索并检索 npmjs 上的信息。

✨ 功能

npm-check-updates 工具

• 🔍 checkUpdates：扫描 package.json，查找过时的依赖项
• 🚀 upgradePackages：将依赖项升级到最新版本
• 🔎 filterUpdates：检查特定包的更新
• 🔄 resolveConflicts：处理依赖冲突
• ⚙️ setVersionConstraints：配置版本升级规则
• 🩺 runDoctor：迭代运行升级和测试，以检测不兼容变更

NPM 搜索工具

• 🔍 searchPackages：在 npmjs.org 注册表中搜索包
• 📝 fetchPackageContent：抓取并提取 npm 包页面的内容
• 📋 getPackageVersions：检索包的版本历史
• 📝 getPackageDetails：获取详细的包元数据

🚀 npm-helper-mcp 安装指南

本指南将帮助你设置并运行 npm-helper-mcp 服务。

📋 前提条件

开始之前，请确保已安装以下内容：

• Node.js（版本 18.x 或更高版本）
• npm（版本 8.x 或更高版本）

🔧 配置

npm-helper-mcp 服务实现了 Model Context Protocol，因此能够与支持该协议的大模型应用进行通信。

配置因应用而异。一般来说，大多数 MCP 客户端应用都有一个 .json 配置文件，或提供用于输入运行服务命令的位置。这两种选项通常都适用。

选项 1：使用 npx 运行

使用该服务最简单的方式是通过 npx 运行，无需本地安装。根据你的 MCP 客户端，采用以下两种方法之一：

1. 将 json 配置复制并粘贴到应用的 MCP 配置文件中。

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

2. 在应用的 MCP 配置设置中输入运行服务的命令。

  npx -y @pinkpixel/npm-helper-mcp

选项 2：本地安装

如果你更喜欢在本地安装该服务，可以运行以下命令：

# Install the package globally
npm install -g npm-helper-mcp

配置：

1. 将 json 配置复制并粘贴到应用的 MCP 配置文件中。

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

2. 在应用的 MCP 配置设置中输入运行服务的命令。

  npm-helper-mcp

选项 3：从源代码安装

# Clone the repository
git clone https://github.com/pinkpixel-dev/npm-helper-mcp.git
cd npm-helper-mcp

# Install dependencies
npm install

# Build the project
npm run build

# Optionally run/test the server
npm start

配置：

1. 将 json 配置复制并粘贴到应用的 mcp 配置文件中。

{
    "mcpServers": {
      "npm-helper": {
        "command": "node",
        "args": [
            "/path/to/npm-helper-mcp/dist/index.js"
        ]
      }
    }
  }

2. 在应用的 mcp 配置设置中输入运行服务的命令。

 node /path/to/npm-helper-mcp/dist/index.js

与大模型搭配使用

此服务遵循 Model Context Protocol，因此可以供 Claude 等大模型使用。大模型可以使用此服务的工具执行各种 npm 操作。

可用工具

工具：check_updates

扫描 package.json，查找过时的依赖项。

参数：

• packagePath（可选）：package.json 文件的路径（默认：./package.json）
• filter（可选）：要检查的软件包名称列表
• reject（可选）：要排除的软件包名称列表
• target（可选）：要升级到的目标版本（latest、newest、greatest、minor、patch、semver）
• interactive（可选）：启用交互模式以选择更新
• peer（可选）：检查已安装软件包的对等依赖项
• minimal（可选）：不升级版本范围已满足的较新版本
• packageManager（可选）：要使用的软件包管理器（npm、yarn、pnpm、deno、bun、staticRegistry）

示例：

{
  "name": "check_updates",
  "arguments": {
    "packagePath": "./package.json",
    "filter": ["react", "lodash"],
    "peer": true,
    "minimal": true,
    "packageManager": "npm"
  }
}

工具：upgrade_packages

将依赖项升级到最新版本。

参数：

• packagePath（可选）：package.json 文件的路径（默认：./package.json）
• upgradeType（可选）：要升级到的目标版本（latest、newest、greatest、minor、patch、semver）
• interactive（可选）：启用交互模式以选择更新
• peer（可选）：检查已安装软件包的对等依赖项
• minimal（可选）：不升级版本范围已满足的较新版本
• packageManager（可选）：要使用的软件包管理器（npm、yarn、pnpm、deno、bun、staticRegistry）

示例：

{
  "name": "upgrade_packages",
  "arguments": {
    "upgradeType": "minor",
    "peer": true,
    "minimal": true,
    "packageManager": "yarn"
  }
}

工具：filter_updates

检查指定软件包的更新。

参数：

• packagePath（可选）：package.json 文件的路径（默认：./package.json）
• filter（必需）：要检查的软件包名称列表
• upgrade（可选）：是否升级 package.json 文件，还是仅进行检查
• minimal（可选）：不升级版本范围已满足的较新版本
• packageManager（可选）：要使用的软件包管理器（npm、yarn、pnpm、deno、bun、staticRegistry）

示例：

{
  "name": "filter_updates",
  "arguments": {
    "filter": ["react", "react-dom"],
    "upgrade": false,
    "minimal": true
  }
}

工具：resolve_conflicts

使用对等依赖项处理依赖冲突。

参数：

• packagePath（可选）：package.json 文件的路径（默认：./package.json）
• upgrade（可选）：是否升级 package.json 文件，还是仅进行检查
• minimal（可选）：不升级版本范围已满足的较新版本
• packageManager（可选）：要使用的软件包管理器（npm、yarn、pnpm、deno、bun、staticRegistry）

示例：

{
  "name": "resolve_conflicts",
  "arguments": {
    "upgrade": true,
    "packageManager": "npm"
  }
}

工具：set_version_constraints

配置版本升级规则。

参数：

• packagePath（可选）：package.json 文件的路径（默认：./package.json）
• target（必需）：目标版本约束策略（latest、newest、greatest、minor、patch、semver）
• removeRange（可选）：从最终软件包版本中移除版本范围
• upgrade（可选）：是否升级 package.json 文件，还是仅进行检查
• minimal（可选）：不升级版本范围已满足的较新版本
• packageManager（可选）：要使用的软件包管理器（npm、yarn、pnpm、deno、bun、staticRegistry）

示例：

{
  "name": "set_version_constraints",
  "arguments": {
    "target": "minor",
    "removeRange": false,
    "upgrade": true,
    "packageManager": "pnpm"
  }
}

工具：run_doctor

迭代安装升级并运行测试，以识别会导致问题的升级。它会自动回退有问题的升级，并保留正常工作的升级。

参数：

• packagePath（可选）：package.json 文件的路径（默认：./package.json）
• doctorInstall（可选）：要使用的自定义安装脚本（默认：'npm install' 或 'yarn'）
• doctorTest（可选）：要使用的自定义测试脚本（默认：'npm test'）
• packageManager（可选）：要使用的包管理器（npm、yarn、pnpm、deno、bun、staticRegistry）

示例：

{
  "name": "run_doctor",
  "arguments": {
    "packagePath": "./package.json",
    "doctorInstall": "npm ci",
    "doctorTest": "npm run test:ci",
    "packageManager": "npm"
  }
}

工具：search_npm

搜索 npm 包。

参数：

• query（必填）：npm 包的搜索查询
• maxResults（可选）：要返回的结果数量上限（默认：10）

示例：

{
  "name": "search_npm",
  "arguments": {
    "query": "react state management",
    "maxResults": 5
  }
}

工具：fetch_package_content

从 npm 包页面获取并解析详细内容。

参数：

• url（必填）：npm 包页面的 URL

示例：

{
  "name": "fetch_package_content",
  "arguments": {
    "url": "https://www.npmjs.com/package/react"
  }
}

工具：get_package_versions

获取 npm 包的可用版本。

参数：

• packageName（必填）：npm 包名称

示例：

{
  "name": "get_package_versions",
  "arguments": {
    "packageName": "react"
  }
}

工具：get_package_details

获取 npm 包的详细信息。

参数：

• packageName（必填）：npm 包名称

示例：

{
  "name": "get_package_details",
  "arguments": {
    "packageName": "react"
  }
}

📝 响应格式

所有工具都以标准格式返回响应：

{
  "status": "success" | "error",
  "data": {}, // Tool-specific data
  "message": "Human-readable message"
}

🆘 故障排除

连接问题**：

• 确保你的大模型应用已正确配置为使用 Model Context Protocol。
• 检查你的 .json 文件是否有错误，或确认启动命令是否正确。
• 如果在本地运行，请确认 index.js 文件的路径。必要时使用绝对路径。

获取帮助

如果你遇到此处未涵盖的问题：

• 查看 GitHub issues，寻找类似问题及解决方案。
• 创建新 issue，并详细描述你的问题。

📄 许可证

MIT

🙏 致谢

• npm-check-updates
• @modelcontextprotocol/sdk

由 Pink Pixel 倾心打造 ❤️