{"id":28135516,"url":"https://github.com/pinkpixel-dev/npm-helper-mcp","last_synced_at":"2025-05-16T17:14:33.555Z","repository":{"id":292538568,"uuid":"981188900","full_name":"pinkpixel-dev/npm-helper-mcp","owner":"pinkpixel-dev","description":"A Model Context Protocol (MCP) server providing tools for NPM package management and dependency updates. Helps LLMs like Claude interact with npm packages, search npm registry, and keep dependencies up-to-date.","archived":false,"fork":false,"pushed_at":"2025-05-10T15:54:51.000Z","size":288,"stargazers_count":3,"open_issues_count":0,"forks_count":1,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-05-15T16:16:03.855Z","etag":null,"topics":["ai-tool","claude","cursor","dependency-manager","dependency-manager-update","developer-tools","mcp","mcp-server","mcp-tools","model-context-protocol","model-context-protocol-servers","nodejs","npm","npm-check-updates","npm-package","npm-search","npmjs","package-management","package-manager","typescript"],"latest_commit_sha":null,"homepage":"https://pinkpixel.dev","language":"JavaScript","has_issues":false,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/pinkpixel-dev.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-05-10T14:41:21.000Z","updated_at":"2025-05-15T02:13:55.000Z","dependencies_parsed_at":"2025-05-14T15:19:04.789Z","dependency_job_id":null,"html_url":"https://github.com/pinkpixel-dev/npm-helper-mcp","commit_stats":null,"previous_names":["pinkpixel-dev/npm-helper-mcp"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pinkpixel-dev%2Fnpm-helper-mcp","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pinkpixel-dev%2Fnpm-helper-mcp/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pinkpixel-dev%2Fnpm-helper-mcp/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pinkpixel-dev%2Fnpm-helper-mcp/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/pinkpixel-dev","download_url":"https://codeload.github.com/pinkpixel-dev/npm-helper-mcp/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254464805,"owners_count":22075565,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai-tool","claude","cursor","dependency-manager","dependency-manager-update","developer-tools","mcp","mcp-server","mcp-tools","model-context-protocol","model-context-protocol-servers","nodejs","npm","npm-check-updates","npm-package","npm-search","npmjs","package-management","package-manager","typescript"],"created_at":"2025-05-14T15:19:01.914Z","updated_at":"2025-05-16T17:14:33.535Z","avatar_url":"https://github.com/pinkpixel-dev.png","language":"JavaScript","funding_links":[],"categories":["Developer Tools"],"sub_categories":["How to Submit"],"readme":"\u003cdiv align=\"center\"\u003e\n  \u003cimg src=\"https://res.cloudinary.com/di7ctlowx/image/upload/v1746886361/npm-helper-mcp-icon_tkot9i.png\" alt=\"NPM Helper MCP Logo\" width=\"300\" height=\"300\"/\u003e\n\u003c/div\u003e\n\n# 📦 NPM Helper - A tool to help your ai assistant with npm package management.🤖 [![npm version](https://img.shields.io/npm/v/@pinkpixel/npm-helper-mcp.svg)](https://www.npmjs.com/package/@pinkpixel/npm-helper-mcp)\n\nA 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.\n\n**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.**\n\nIf 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.\n\nThere 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.\n\n## ✨ Features\n\n### npm-check-updates Tools\n\n- 🔍 **checkUpdates**: Scan package.json for outdated dependencies\n- 🚀 **upgradePackages**: Upgrade dependencies to latest versions\n- 🔎 **filterUpdates**: Check updates for specific packages\n- 🔄 **resolveConflicts**: Handle dependency conflicts\n- ⚙️ **setVersionConstraints**: Configure version upgrade rules\n- 🩺 **runDoctor**: Iteratively run upgrades and tests to detect breaking changes\n\n### NPM Search Tools\n\n- 🔍 **searchPackages**: Search npmjs.org registry for packages\n- 📝 **fetchPackageContent**: Scrape and extract content from npm package pages\n- 📋 **getPackageVersions**: Retrieve version history of packages\n- 📝 **getPackageDetails**: Fetch detailed package metadata\n\n# 🚀 npm-helper-mcp Installation Guide\n\nThis guide will help you set up and run the npm-helper-mcp server.\n\n## 📋 Prerequisites\n\nBefore you begin, ensure you have the following installed:\n\n- Node.js (version 18.x or later)\n- npm (version 8.x or later)\n\n## 🔧 Configuration\n\nThe npm-helper-mcp server implements the Model Context Protocol, which enables it to communicate with LLM applications that support the protocol.\n\nConfiguration 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.\n\n### Option 1: Run with npx\n\nThe 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:\n\n1. Copy and paste the json configuration into your application's mcp configuration file.\n\n```json\n{\n    \"mcpServers\": {\n      \"npm-helper\": {\n        \"command\": \"npx\",\n        \"args\": [\n            \"-y\",\n            \"@pinkpixel/npm-helper-mcp\"\n        ]\n      }\n    }\n  }\n```\n\n2. Enter the command to run the server in your application's mcp configuration settings.\n\n```bash\n  npx -y @pinkpixel/npm-helper-mcp\n```\n\n### Option 2: Local installation\n\nIf you prefer to install the server locally, you can do so with the following command:\n\n```bash\n# Install the package globally\nnpm install -g npm-helper-mcp\n```\n\nConfiguration:\n\n1. Copy and paste the json configuration into your application's mcp configuration file.\n\n```json\n{\n    \"mcpServers\": {\n      \"npm-helper\": {\n        \"command\": \"npx\",\n        \"args\": [\n            \"-y\",\n            \"@pinkpixel/npm-helper-mcp\"\n        ]\n      }\n    }\n  }\n```\n\n2. Enter the command to run the server in your application's mcp configuration settings.\n\n```bash\n  npm-helper-mcp\n```\n\n### Option 3: Install from source\n\n```bash\n# Clone the repository\ngit clone https://github.com/pinkpixel-dev/npm-helper-mcp.git\ncd npm-helper-mcp\n\n# Install dependencies\nnpm install\n\n# Build the project\nnpm run build\n\n# Optionally run/test the server\nnpm start\n```\n\nConfiguration:\n\n1. Copy and paste the json configuration into your application's mcp configuration file.\n\n```json\n{\n    \"mcpServers\": {\n      \"npm-helper\": {\n        \"command\": \"node\",\n        \"args\": [\n            \"/path/to/npm-helper-mcp/dist/index.js\"\n        ]\n      }\n    }\n  }\n```\n\n2. Enter the command to run the server in your application's mcp configuration settings.\n\n```bash\n node /path/to/npm-helper-mcp/dist/index.js\n```\n\n## Using with LLMs\n\nThis 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.\n\n### Available Tools\n\n#### Tool: check_updates\n\nScans package.json for outdated dependencies.\n\nParameters:\n\n- `packagePath` (optional): Path to package.json file (default: ./package.json)\n- `filter` (optional): List of package names to check\n- `reject` (optional): List of package names to exclude\n- `target` (optional): Target version to upgrade to (latest, newest, greatest, minor, patch, semver)\n- `interactive` (optional): Enable interactive mode for choosing updates\n- `peer` (optional): Check peer dependencies of installed packages\n- `minimal` (optional): Do not upgrade newer versions that are already satisfied by the version range\n- `packageManager` (optional): Package manager to use (npm, yarn, pnpm, deno, bun, staticRegistry)\n\nExample:\n\n```json\n{\n  \"name\": \"check_updates\",\n  \"arguments\": {\n    \"packagePath\": \"./package.json\",\n    \"filter\": [\"react\", \"lodash\"],\n    \"peer\": true,\n    \"minimal\": true,\n    \"packageManager\": \"npm\"\n  }\n}\n```\n\n#### Tool: upgrade_packages\n\nUpgrades dependencies to their latest versions.\n\nParameters:\n\n- `packagePath` (optional): Path to package.json file (default: ./package.json)\n- `upgradeType` (optional): Target version to upgrade to (latest, newest, greatest, minor, patch, semver)\n- `interactive` (optional): Enable interactive mode for choosing updates\n- `peer` (optional): Check peer dependencies of installed packages\n- `minimal` (optional): Do not upgrade newer versions that are already satisfied by the version range\n- `packageManager` (optional): Package manager to use (npm, yarn, pnpm, deno, bun, staticRegistry)\n\nExample:\n\n```json\n{\n  \"name\": \"upgrade_packages\",\n  \"arguments\": {\n    \"upgradeType\": \"minor\",\n    \"peer\": true,\n    \"minimal\": true,\n    \"packageManager\": \"yarn\"\n  }\n}\n```\n\n#### Tool: filter_updates\n\nChecks updates for specific packages.\n\nParameters:\n\n- `packagePath` (optional): Path to package.json file (default: ./package.json)\n- `filter` (required): List of package names to check\n- `upgrade` (optional): Whether to upgrade the package.json file or just check\n- `minimal` (optional): Do not upgrade newer versions that are already satisfied by the version range\n- `packageManager` (optional): Package manager to use (npm, yarn, pnpm, deno, bun, staticRegistry)\n\nExample:\n\n```json\n{\n  \"name\": \"filter_updates\",\n  \"arguments\": {\n    \"filter\": [\"react\", \"react-dom\"],\n    \"upgrade\": false,\n    \"minimal\": true\n  }\n}\n```\n\n#### Tool: resolve_conflicts\n\nHandles dependency conflicts using peer dependencies.\n\nParameters:\n\n- `packagePath` (optional): Path to package.json file (default: ./package.json)\n- `upgrade` (optional): Whether to upgrade the package.json file or just check\n- `minimal` (optional): Do not upgrade newer versions that are already satisfied by the version range\n- `packageManager` (optional): Package manager to use (npm, yarn, pnpm, deno, bun, staticRegistry)\n\nExample:\n\n```json\n{\n  \"name\": \"resolve_conflicts\",\n  \"arguments\": {\n    \"upgrade\": true,\n    \"packageManager\": \"npm\"\n  }\n}\n```\n\n#### Tool: set_version_constraints\n\nConfigures version upgrade rules.\n\nParameters:\n\n- `packagePath` (optional): Path to package.json file (default: ./package.json)\n- `target` (required): Target version constraint strategy (latest, newest, greatest, minor, patch, semver)\n- `removeRange` (optional): Remove version ranges from the final package version\n- `upgrade` (optional): Whether to upgrade the package.json file or just check\n- `minimal` (optional): Do not upgrade newer versions that are already satisfied by the version range\n- `packageManager` (optional): Package manager to use (npm, yarn, pnpm, deno, bun, staticRegistry)\n\nExample:\n\n```json\n{\n  \"name\": \"set_version_constraints\",\n  \"arguments\": {\n    \"target\": \"minor\",\n    \"removeRange\": false,\n    \"upgrade\": true,\n    \"packageManager\": \"pnpm\"\n  }\n}\n```\n\n#### Tool: run_doctor\n\nIteratively installs upgrades and runs tests to identify breaking upgrades. It automatically reverts breaking upgrades and keeps working ones.\n\nParameters:\n\n- `packagePath` (optional): Path to package.json file (default: ./package.json)\n- `doctorInstall` (optional): Custom install script to use (default: 'npm install' or 'yarn')\n- `doctorTest` (optional): Custom test script to use (default: 'npm test')\n- `packageManager` (optional): Package manager to use (npm, yarn, pnpm, deno, bun, staticRegistry)\n\nExample:\n\n```json\n{\n  \"name\": \"run_doctor\",\n  \"arguments\": {\n    \"packagePath\": \"./package.json\",\n    \"doctorInstall\": \"npm ci\",\n    \"doctorTest\": \"npm run test:ci\",\n    \"packageManager\": \"npm\"\n  }\n}\n```\n\n#### Tool: search_npm\n\nSearches for npm packages.\n\nParameters:\n\n- `query` (required): Search query for npm packages\n- `maxResults` (optional): Maximum number of results to return (default: 10)\n\nExample:\n\n```json\n{\n  \"name\": \"search_npm\",\n  \"arguments\": {\n    \"query\": \"react state management\",\n    \"maxResults\": 5\n  }\n}\n```\n\n#### Tool: fetch_package_content\n\nFetch and parse detailed content from an npm package page.\n\nParameters:\n\n- `url` (required): URL of the npm package page\n\nExample:\n\n```json\n{\n  \"name\": \"fetch_package_content\",\n  \"arguments\": {\n    \"url\": \"https://www.npmjs.com/package/react\"\n  }\n}\n```\n\n#### Tool: get_package_versions\n\nGets available versions for an npm package.\n\nParameters:\n\n- `packageName` (required): Name of the npm package\n\nExample:\n\n```json\n{\n  \"name\": \"get_package_versions\",\n  \"arguments\": {\n    \"packageName\": \"react\"\n  }\n}\n```\n\n#### Tool: get_package_details\n\nGets detailed information about an npm package.\n\nParameters:\n\n- `packageName` (required): Name of the npm package\n\nExample:\n\n```json\n{\n  \"name\": \"get_package_details\",\n  \"arguments\": {\n    \"packageName\": \"react\"\n  }\n}\n```\n\n## 📝 Response Format\n\nAll tools return responses in a standard format:\n\n```json\n{\n  \"status\": \"success\" | \"error\",\n  \"data\": {}, // Tool-specific data\n  \"message\": \"Human-readable message\"\n}\n```\n\n## 🆘 Troubleshooting\n\n### Connection Issues**:\n\n- Ensure your LLM application is correctly configured to use the Model Context Protocol.\n- Check your .json file for any errors, or verify your start command is correct.\n- If running locally, verify your path to the index.js file. Use absolute paths if necessary.\n\n### Getting Help\n\nIf you encounter any issues not covered here:\n\n- Check the [GitHub issues](https://github.com/pinkpixel-dev/npm-helper-mcp/issues) for similar problems and solutions.\n- Create a new issue with a detailed description of your problem.\n\n## 📄 License\n\nMIT\n\n## 🙏 Credits\n\n- [npm-check-updates](https://www.npmjs.com/package/npm-check-updates)\n- [@modelcontextprotocol/sdk](https://github.com/anthropics/model-context-protocol)\n\nMade with ❤️ by Pink Pixel\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpinkpixel-dev%2Fnpm-helper-mcp","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fpinkpixel-dev%2Fnpm-helper-mcp","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpinkpixel-dev%2Fnpm-helper-mcp/lists"}