NPM Plus - JavaScript Package Manager for AI

🚀 Production-ready MCP server for intelligent JavaScript package management
Works seamlessly with Claude, Windsurf, Cursor, VS Code, and any MCP-compatible AI editor.

🎉 Latest Updates (v12.0.16)

✅ ALL TOOLS NOW FULLY OPERATIONAL - Enhanced Install Tools: Robust package installation with intelligent retry logic - Fixed Directory Resolution: No more "Invalid project directory: /" errors - Enhanced Vulnerability Checking: Now works reliably with graceful error handling
- Improved Package Installation: Better npm idealTree error handling with automatic retries - Debug Tools: New debug_version tool for troubleshooting - 100% Compatibility: All operations now work with both relative (.) and absolute paths

📊 Current Status: 16/16 tools fully functional with comprehensive error handling

🛠️ Available Tools (16/16 Fully Functional)

🎯 Key Improvements in v12.0.16

✅ All 16 Tools Fully Operational: Complete functionality across all package management operations
✅ Robust Installation: Intelligent retry logic with automatic recovery from npm errors
✅ Fixed Directory Resolution: All tools now properly handle relative paths (.)
✅ Enhanced Error Handling: Clear, actionable error messages with recovery suggestions
✅ Automatic Retries: Intelligent retry logic for npm idealTree and other transient errors
✅ Graceful Degradation: Tools continue to work even when external APIs are unavailable

✨ Features

🔍 Smart Package Discovery

• Search npm registry with intelligent relevance scoring
• View detailed package metadata, keywords, and maintainers
• Pagination support for comprehensive results

📦 Intelligent Package Management

• Install, update, and remove packages across NPM, Yarn, and pnpm
• Support for dev dependencies, global packages, and version constraints
• Automatic package manager detection with retry logic

🔒 Security & Compliance

• Real-time vulnerability scanning with fallback mechanisms
• Automated security fix suggestions and implementation
• License compliance tracking and analysis

📊 Advanced Analytics

• Bundle size analysis before installation
• Dependency tree visualization with circular dependency detection
• Download statistics and popularity metrics
• Orphaned file detection

🚀 Quick Start

Using Hosted Service (Recommended)

The easiest way to get started:

{
  "mcpServers": {
    "npmplus-mcp": {
      "transport": "http",
      "url": "https://api.npmplus.dev/mcp"
    }
  }
}

Self-Hosting (Advanced)

For customization or private deployment:

git clone https://github.com/shacharsol/js-package-manager-mcp.git
cd js-package-manager-mcp
npm install
npm run build
npm start

For web deployment (Netlify, Vercel, etc.):

# Run the automated setup script
./deployment/setup-deployment.sh

# Customize the deployment URLs
nano scripts/test-deployment.sh

# Deploy to your own infrastructure
npm run deploy:netlify

🔒 Security Note: The production service at api.npmplus.dev has automatic deployments disabled. Only the maintainer can deploy to production using npm run deploy:production.

See deployment/README.md for detailed deployment instructions.

🛠️ Editor Setup

{
  "mcpServers": {
    "npmplus-mcp": {
      "transport": "http",
      "url": "https://api.npmplus.dev/mcp"
    }
  }
}

{
  "mcpServers": {
    "npmplus-mcp": {
      "serverUrl": "https://api.npmplus.dev/mcp"
    }
  }
}

{
  "mcp": {
    "servers": {
      "npmplus-mcp": {
        "command": "npx",
        "args": [
          "-y",
          "npmplus-mcp-server"
        ],
        "disabled": false
      }
    }
  }
}

{
  "mcp": {
    "servers": {
      "npmplus-mcp": {
        "command": "node",
        "args": [
          "./dist/index.js"
        ],
        "cwd": "./",
        "disabled": false
      }
    }
  }
}

{
  "mcpServers": {
    "npmplus-mcp": {
      "command": "npx",
      "args": ["-y", "npmplus-mcp-server"]
    }
  }
}

# NPM Plus MCP Integration
This project uses NPM Plus (https://api.npmplus.dev/mcp) for AI-powered package management.

Available features:
- Package search and installation
- Security vulnerability scanning  
- Bundle size analysis
- Dependency management

In Cline chat: "add a tool for JavaScript package management using npmplus-mcp-server"

{
  "mcpServers": {
    "npmplus-mcp": {
      "command": "npx",
      "args": ["-y", "npmplus-mcp-server"]
    }
  }
}

{
  "mcpServers": {
    "npmplus-mcp": {
      "command": "npx",
      "args": ["-y", "npmplus-mcp-server"]
    }
  }
}

🔧 Available Tools

💡 Usage Examples

Security-focused:

"Check if lodash has any security vulnerabilities"
"Audit all dependencies and suggest fixes"
"Find packages with MIT licenses only"

Performance-focused:

"What's the bundle size impact of adding moment.js?"
"Show me lightweight alternatives to lodash"
"Find circular dependencies in my project"

Development workflow:

"Install typescript as a dev dependency"
"Update all outdated packages"
"Search for React form validation libraries"

🏗️ Self-Hosting (Advanced)

For enterprise or custom deployments:

git clone https://github.com/shacharsol/js-package-manager-mcp.git
cd js-package-manager-mcp
npm install
npm run build
npm start

Via npx (Recommended):

{
  "mcpServers": {
    "npmplus-mcp": {
      "command": "npx",
      "args": ["-y", "npmplus-mcp-server"]
    }
  }
}

Local development:

{
  "mcpServers": {
    "npmplus-mcp": {
      "command": "node",
      "args": ["./dist/index.js"],
      "cwd": "/path/to/js-package-manager-mcp"
    }
  }
}

🧪 Testing & Validation

# Test deployment health
npm run test:deployment

# Run unit tests  
npm test

# Development mode
npm run dev

🚀 Version Management & Publishing

# Bump version only (patch/minor/major)
npm run bump

# Full production deployment (maintainer only)
# - Interactive version bumping
# - Automated npm publishing  
# - Git tagging and pushing
# - Netlify deployment
# - Endpoint testing
npm run deploy:production

Production deployment includes: - ✅ Prerequisites check (npm login, netlify login, clean git) - 📦 Interactive version bumping (patch/minor/major) - 🧪 Automated testing - 📤 NPM package publishing - 🏷️ Git tagging and pushing - 🌐 Netlify deployment - 🔍 Endpoint health checks

🏗️ Architecture

Built with modern tools: - TypeScript - Type safety and developer experience - MCP SDK - Official Model Context Protocol implementation - Zod - Runtime type validation and parsing - Execa - Secure subprocess execution - Pacote - Official npm registry client - Node-cache - Intelligent response caching

Performance optimizations: - ⚡ Intelligent caching with configurable TTLs - 🎯 Rate limiting to prevent API throttling
- 📦 Parallel operations for batch processing - 🪶 Optimized responses for AI context windows

🔐 Security

• ✅ Isolated subprocess execution
• ✅ Input validation prevents injection attacks
• ✅ Official vulnerability databases only
• ✅ No credential storage or sensitive data handling
• ✅ CORS-enabled for secure web integration

🤝 Contributing

We welcome contributions! Please see our Contributing Guidelines.

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Add tests for new functionality
4. Commit changes (git commit -m 'Add amazing feature')
5. Push to branch (git push origin feature/amazing-feature)
6. Open a Pull Request

📊 Analytics & Monitoring

NPM Plus includes optional analytics for self-hosted deployments:

Analytics Features:

• 📊 Basic tracking - Console logging for debugging and monitoring
• 🔧 Tool usage - Track which MCP tools are being used
• 🚀 Performance metrics - Response times and success rates
• 🔒 Privacy-first - Minimal data collection, IP hashing
• ⚙️ Configurable - Enable via environment variables

Enable Analytics (Optional)

For self-hosted deployments, you can enable analytics logging:

# Enable analytics logging
ENABLE_ANALYTICS=true
ANALYTICS_SALT=your-random-salt

Analytics data will be logged to console output for monitoring and debugging.

🔧 Troubleshooting & Known Issues

✅ All Issues Resolved (v12.0.16)

All major issues have been resolved in the latest version:

🛠️ Common Solutions

1. npm idealTree Error

# If you see: "Tracker 'idealTree' already exists"
# Solution 1: Use the clean cache tool
"Clean the npm cache first"

# Solution 2: Manual cleanup (if needed)
npm cache clean --force

# Solution 3: Restart Claude Desktop to reset MCP connection

2. Directory Resolution Issues

# Problem: "Invalid project directory: /"  
# ✅ SOLVED - all tools now work with relative paths
"Install lodash in the current directory"  # Works correctly now

3. Vulnerability Check Not Working

# ✅ SOLVED - now provides graceful fallback
"Check vulnerabilities for express@4.17.0"  # Works with helpful information

🔍 Debug Tools

Use the debug tool to check server status:

"Run debug_version tool"

This will show: - Current version running - Server uptime and status
- Working directory - Environment details

📋 Testing Commands

Verify everything is working:

# Quick production test
npm run test:production

# Comprehensive feature test  
npm run test:comprehensive

# Test specific issues that were fixed
npm run test:issues

🆘 Getting Help

If you encounter issues:

1. Check Version: Use debug_version tool to confirm you're running v12.0.16+
2. Restart: Restart Claude Desktop to pick up latest version
3. Clear Cache: Try clean_cache tool first
4. Check Logs: Look for [npmplus-mcp] messages in console
5. Report: Open issue at GitHub Issues

Include in bug reports: - Version from debug_version output - Exact error message - Steps to reproduce - Operating system

🔄 Version Update Process

To ensure you're running the latest version:

For Hosted Service Users: - Updates are automatic - Restart Claude Desktop to refresh connection

For Self-Hosted Users:

# Update to latest version
npm update npmplus-mcp-server

# Or reinstall
npm uninstall -g npmplus-mcp-server
npm install -g npmplus-mcp-server@latest

📄 License

MIT License - see LICENSE for details.

🙋‍♂️ About

Created with ❤️ by Shachar Solomon in 2025.

Star this repo if NPM Plus helps your AI development workflow!

Built with ❤️ for the open source community