npm-helper

npm-helper is a Model Context Protocol (MCP) server designed to assist your AI in managing npm dependencies. It exposes tools categorized under npm-check-updates and npm search, enabling you to scan for outdated packages, upgrade dependencies to latest compatible versions, resolve conflicts, and configure version constraints. Additionally, it provides tools to search npmjs.org, fetch package details, and retrieve version histories. The server is intended to help an LLM orchestrate safe upgrades and package discovery without breaking changes, with guidance such as using the upgradePackages tool with peer set to true for safe upgrades.

To use it, connect your MCP-enabled LLM or client to the npm-helper MCP server and call the available tools. Typical workflows include running checkUpdates to identify outdated dependencies in package.json, then using upgradePackages to apply safe, compatible upgrades, and optionally using resolveConflicts and setVersionConstraints to tailor upgrade behavior. If you’re exploring new packages, you can leverage searchPackages, fetchPackageContent, getPackageVersions, and getPackageDetails to gather information before adding a dependency.

Prerequisites:

• Node.js (version 18.x or later)
• npm (version 8.x or later)

Option A: Run with npx (no local install)

1. Ensure your MCP client configuration includes the npm-helper MCP server, for example:

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

2. Run the server via your MCP client (or directly):

npx -y @pinkpixel/npm-helper-mcp

Option B: Local installation (recommended for development)

1. Install the package globally or locally:

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

2. Configure your MCP client as above (use the same JSON block).
3. Run the server:

npm-helper-mcp

Option C: Install from source

1. Clone the repository and install dependencies:

# 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 (if applicable)
npm run build

# Start the server
npm start

Configuration example when running from source:

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

Run command:

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

Tips and notes:

• The npm-helper MCP server is geared toward safe upgrades; for safer upgrades in a baseline, use upgradePackages with peer set to true. This helps ensure dependencies are upgraded to the latest compatible versions without introducing conflicts.
• When upgrading, consider using checkUpdates first to understand which packages are outdated before applying upgrades.
• The server provides a range of tools for search and retrieval of npm package data (searchPackages, fetchPackageContent, getPackageVersions, getPackageDetails) to aid decision-making before adding or upgrading dependencies.
• Ensure your environment variables (if any) are configured per your deployment environment. The provided mcp_config example currently does not require additional env vars, but you can add any necessary ones under the env field for the server configuration.