📦 NPM Helper - A tool to help your ai assistant with npm package management.🤖 
A Model Context Protocol server for NPM dependency management. This server provides tools for NPM package search and tools for updating npm packages, ensuring your project's dependencies are up to date and updated to their latest compatible versions, without any conflicts or headaches.
As a baseline, for a safe upgrade of any project's package.json, your assistant can call the upgradePackagets tool with the 'peer' parameter set to true. This will likely not update all of your dependencies to the latest versions, but it will safely upgrade them to the latest compatible versions, without any errors.
If you are looking for a full upgrade of all dependencies, your assistant has many tools and parameters to safely explore. Parameter options and examples are provider below, in the "Available Tools" section. You can also find more information in the 'docs' directory.
There are also tools available to search and retrieve information from npmjs, if you are exploring options for new packages to add to your project, or if you are looking for information on a specific package.
✨ Features
npm-check-updates Tools
- 🔍 checkUpdates: Scan package.json for outdated dependencies
- 🚀 upgradePackages: Upgrade dependencies to latest versions
- 🔎 filterUpdates: Check updates for specific packages
- 🔄 resolveConflicts: Handle dependency conflicts
- ⚙️ setVersionConstraints: Configure version upgrade rules
- 🩺 runDoctor: Iteratively run upgrades and tests to detect breaking changes
NPM Search Tools
- 🔍 searchPackages: Search npmjs.org registry for packages
- 📝 fetchPackageContent: Scrape and extract content from npm package pages
- 📋 getPackageVersions: Retrieve version history of packages
- 📝 getPackageDetails: Fetch detailed package metadata
🚀 npm-helper-mcp Installation Guide
This guide will help you set up and run the npm-helper-mcp server.
📋 Prerequisites
Before you begin, ensure you have the following installed:
- Node.js (version 18.x or later)
- npm (version 8.x or later)
🔧 Configuration
The npm-helper-mcp server implements the Model Context Protocol, which enables it to communicate with LLM applications that support the protocol.
Configuration varies depending on the application. Generally, most mcp client applications will have a .json configuration file, or a place to enter the command to run the server. One of these 2 options should work in most cases.
Option 1: Run with npx
The easiest way to use the server is to run it with npx, which requires no local installation. Depending on your mcp client, use one of the following 2 methods:
- Copy and paste the json configuration into your application's mcp configuration file.
{
"mcpServers": {
"npm-helper": {
"command": "npx",
"args": [
"-y",
"@pinkpixel/npm-helper-mcp"
]
}
}
}
- Enter the command to run the server in your application's mcp configuration settings.
npx -y @pinkpixel/npm-helper-mcp
Option 2: Local installation
If you prefer to install the server locally, you can do so with the following command:
# Install the package globally
npm install -g npm-helper-mcp
Configuration:
- Copy and paste the json configuration into your application's mcp configuration file.
{
"mcpServers": {
"npm-helper": {
"command": "npx",
"args": [
"-y",
"@pinkpixel/npm-helper-mcp"
]
}
}
}
- Enter the command to run the server in your application's mcp configuration settings.
npm-helper-mcp
Option 3: Install from source
# 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
Configuration:
- Copy and paste the json configuration into your application's mcp configuration file.
{
"mcpServers": {
"npm-helper": {
"command": "node",
"args": [
"/path/to/npm-helper-mcp/dist/index.js"
]
}
}
}
- Enter the command to run the server in your application's mcp configuration settings.
node /path/to/npm-helper-mcp/dist/index.js
Using with LLMs
This server follows the Model Context Protocol, which allows it to be used by LLMs like Claude. The LLM can use the server's tools to perform various npm operations.
Available Tools
Tool: check_updates
Scans package.json for outdated dependencies.
Parameters:
packagePath(optional): Path to package.json file (default: ./package.json)filter(optional): List of package names to checkreject(optional): List of package names to excludetarget(optional): Target version to upgrade to (latest, newest, greatest, minor, patch, semver)interactive(optional): Enable interactive mode for choosing updatespeer(optional): Check peer dependencies of installed packagesminimal(optional): Do not upgrade newer versions that are already satisfied by the version rangepackageManager(optional): Package manager to use (npm, yarn, pnpm, deno, bun, staticRegistry)
Example:
{
"name": "check_updates",
"arguments": {
"packagePath": "./package.json",
"filter": ["react", "lodash"],
"peer": true,
"minimal": true,
"packageManager": "npm"
}
}
Tool: upgrade_packages
Upgrades dependencies to their latest versions.
Parameters:
packagePath(optional): Path to package.json file (default: ./package.json)upgradeType(optional): Target version to upgrade to (latest, newest, greatest, minor, patch, semver)interactive(optional): Enable interactive mode for choosing updatespeer(optional): Check peer dependencies of installed packagesminimal(optional): Do not upgrade newer versions that are already satisfied by the version rangepackageManager(optional): Package manager to use (npm, yarn, pnpm, deno, bun, staticRegistry)
Example:
{
"name": "upgrade_packages",
"arguments": {
"upgradeType": "minor",
"peer": true,
"minimal": true,
"packageManager": "yarn"
}
}
Tool: filter_updates
Checks updates for specific packages.
Parameters:
packagePath(optional): Path to package.json file (default: ./package.json)filter(required): List of package names to checkupgrade(optional): Whether to upgrade the package.json file or just checkminimal(optional): Do not upgrade newer versions that are already satisfied by the version rangepackageManager(optional): Package manager to use (npm, yarn, pnpm, deno, bun, staticRegistry)
Example:
{
"name": "filter_updates",
"arguments": {
"filter": ["react", "react-dom"],
"upgrade": false,
"minimal": true
}
}
Tool: resolve_conflicts
Handles dependency conflicts using peer dependencies.
Parameters:
packagePath(optional): Path to package.json file (default: ./package.json)upgrade(optional): Whether to upgrade the package.json file or just checkminimal(optional): Do not upgrade newer versions that are already satisfied by the version rangepackageManager(optional): Package manager to use (npm, yarn, pnpm, deno, bun, staticRegistry)
Example:
{
"name": "resolve_conflicts",
"arguments": {
"upgrade": true,
"packageManager": "npm"
}
}
Tool: set_version_constraints
Configures version upgrade rules.
Parameters:
packagePath(optional): Path to package.json file (default: ./package.json)target(required): Target version constraint strategy (latest, newest, greatest, minor, patch, semver)removeRange(optional): Remove version ranges from the final package versionupgrade(optional): Whether to upgrade the package.json file or just checkminimal(optional): Do not upgrade newer versions that are already satisfied by the version rangepackageManager(optional): Package manager to use (npm, yarn, pnpm, deno, bun, staticRegistry)
Example:
{
"name": "set_version_constraints",
"arguments": {
"target": "minor",
"removeRange": false,
"upgrade": true,
"packageManager": "pnpm"
}
}
Tool: run_doctor
Iteratively installs upgrades and runs tests to identify breaking upgrades. It automatically reverts breaking upgrades and keeps working ones.
Parameters:
packagePath(optional): Path to package.json file (default: ./package.json)doctorInstall(optional): Custom install script to use (default: 'npm install' or 'yarn')doctorTest(optional): Custom test script to use (default: 'npm test')packageManager(optional): Package manager to use (npm, yarn, pnpm, deno, bun, staticRegistry)
Example:
{
"name": "run_doctor",
"arguments": {
"packagePath": "./package.json",
"doctorInstall": "npm ci",
"doctorTest": "npm run test:ci",
"packageManager": "npm"
}
}
Tool: search_npm
Searches for npm packages.
Parameters:
query(required): Search query for npm packagesmaxResults(optional): Maximum number of results to return (default: 10)
Example:
{
"name": "search_npm",
"arguments": {
"query": "react state management",
"maxResults": 5
}
}
Tool: fetch_package_content
Fetch and parse detailed content from an npm package page.
Parameters:
url(required): URL of the npm package page
Example:
{
"name": "fetch_package_content",
"arguments": {
"url": "https://www.npmjs.com/package/react"
}
}
Tool: get_package_versions
Gets available versions for an npm package.
Parameters:
packageName(required): Name of the npm package
Example:
{
"name": "get_package_versions",
"arguments": {
"packageName": "react"
}
}
Tool: get_package_details
Gets detailed information about an npm package.
Parameters:
packageName(required): Name of the npm package
Example:
{
"name": "get_package_details",
"arguments": {
"packageName": "react"
}
}
📝 Response Format
All tools return responses in a standard format:
{
"status": "success" | "error",
"data": {}, // Tool-specific data
"message": "Human-readable message"
}
🆘 Troubleshooting
Connection Issues**:
- Ensure your LLM application is correctly configured to use the Model Context Protocol.
- Check your .json file for any errors, or verify your start command is correct.
- If running locally, verify your path to the index.js file. Use absolute paths if necessary.
Getting Help
If you encounter any issues not covered here:
- Check the GitHub issues for similar problems and solutions.
- Create a new issue with a detailed description of your problem.
📄 License
MIT
🙏 Credits
Made with ❤️ by Pink Pixel