jaegis-npm-mcp-server

NPM package management with 8 fully implemented tools for JAEGIS-web-os project automation

🚀 Quick Start

NPX (Recommended)

# List all available tools
npx jaegis-npm-mcp-server@latest --list-tools --format=table

# Get tools schema for MCP integration
npx jaegis-npm-mcp-server@latest --tools-json

# Start the MCP server
npx jaegis-npm-mcp-server@latest

Global Installation

npm install -g jaegis-npm-mcp-server
npm-mcp-server --list-tools

📦 Tool Inventory (8 Tools)

Tool Name	Category	Description	Required Params	Optional Params
npm_package_info	Package Information	Get detailed package metadata and dependencies	1	1
npm_search_packages	Package Discovery	Search NPM registry using keywords	1	1
npm_publish_package	Package Publishing	Publish packages to NPM registry	1	2
npm_unpublish_package	Package Management	Remove packages from NPM (irreversible)	1	1
npm_deprecate_package	Package Management	Deprecate package versions with message	3	0
npm_list_versions	Package Information	List all available package versions	1	0
npm_download_stats	Package Analytics	Get download statistics and analytics	1	1
npm_validate_package	Package Validation	Validate package.json for publishing	1	0

Tool Categories

• Package Information (2 tools) - Retrieve package metadata and versions
• Package Discovery (1 tool) - Search and explore NPM registry
• Package Publishing (1 tool) - Publish packages to NPM
• Package Management (2 tools) - Unpublish and deprecate packages
• Package Analytics (1 tool) - Download statistics and metrics
• Package Validation (1 tool) - Validate package configuration

🔧 Environment Setup

Required Variables

export NPM_TOKEN=npm_your_token_here           # NPM access token
export NPM_USERNAME=your_npm_username          # NPM username
export NPM_EMAIL=your_email@example.com        # NPM email

Optional Variables

export NPM_REGISTRY=https://registry.npmjs.org/  # NPM registry URL
export DEFAULT_PACKAGE=JAEGIS-web-os             # Default package name

Generate NPM Token

1. Go to NPM Settings > Tokens
2. Click "Generate New Token"
3. Select "Automation" for CI/CD or "Publish" for manual publishing
4. Copy the generated token (format: npm_*)

Token Format Validation

• ✅ npm_* - NPM access token
• ❌ Other formats will show warnings

🎯 MCP Client Integration

Augment Code

{
  "npm-jaegis": {
    "command": "npx",
    "args": ["@jaegis/npm-mcp-server@latest"],
    "env": {
      "NPM_TOKEN": "npm_your_token_here",
      "NPM_USERNAME": "your_username",
      "NPM_EMAIL": "your_email@example.com"
    }
  }
}

Claude Desktop

{
  "mcpServers": {
    "npm-jaegis": {
      "command": "npx",
      "args": ["@jaegis/npm-mcp-server@latest"],
      "env": {
        "NPM_TOKEN": "npm_your_token_here",
        "NPM_USERNAME": "your_username",
        "NPM_EMAIL": "your_email@example.com"
      }
    }
  }
}

VS Code MCP Extension

{
  "name": "NPM JAEGIS",
  "command": "npx @jaegis/npm-mcp-server@latest",
  "env": {
    "NPM_TOKEN": "npm_your_token_here",
    "NPM_USERNAME": "your_username"
  }
}

📖 Complete Tool Reference

1. npm_package_info

Get detailed information about an NPM package including metadata, dependencies, and download statistics.

Parameters:

• package_name (required): Name of the NPM package
• version (optional): Specific version (defaults to latest)

Example:

{
  "tool": "npm_package_info",
  "parameters": {
    "package_name": "express",
    "version": "4.18.0"
  }
}

Response:

{
  "name": "express",
  "version": "4.18.0",
  "description": "Fast, unopinionated, minimalist web framework",
  "author": "TJ Holowaychuk",
  "license": "MIT",
  "dependencies": { ... },
  "downloads": 25000000,
  "lastPublished": "2022-04-29T00:00:00.000Z",
  "success": true
}

2. npm_search_packages

Search for NPM packages using keywords and filters.

Parameters:

• query (required): Search query
• limit (optional): Maximum number of results (default: 20, max: 100)

Example:

{
  "tool": "npm_search_packages",
  "parameters": {
    "query": "web framework",
    "limit": 10
  }
}

3. npm_list_versions

List all available versions of a package with release information.

Parameters:

• package_name (required): Name of the package

Example:

{
  "tool": "npm_list_versions",
  "parameters": {
    "package_name": "react"
  }
}

Response:

{
  "package": "react",
  "totalVersions": 150,
  "versions": ["18.2.0", "18.1.0", "18.0.0", ...],
  "latest": "18.2.0",
  "success": true
}

4. npm_download_stats

Get download statistics and analytics for a package.

Parameters:

• package_name (required): Name of the package
• period (optional): Time period - last-day, last-week, last-month, last-year (default: last-month)

Example:

{
  "tool": "npm_download_stats",
  "parameters": {
    "package_name": "lodash",
    "period": "last-month"
  }
}

Response:

{
  "package": "lodash",
  "period": "last-month",
  "downloads": 50000000,
  "start": "2025-09-23",
  "end": "2025-10-23",
  "success": true
}

5. npm_validate_package

Validate package.json and check for publishing readiness.

Parameters:

• package_path (required): Path to package directory

Example:

{
  "tool": "npm_validate_package",
  "parameters": {
    "package_path": "/path/to/my-package"
  }
}

Response:

{
  "package": "my-package",
  "version": "1.0.0",
  "isValid": true,
  "issues": [],
  "warnings": "Package is ready to publish",
  "success": true
}

6. npm_publish_package

Validate and prepare a package for publishing to NPM registry.

Parameters:

• package_path (required): Path to package directory
• tag (optional): Distribution tag (default: latest)
• access (optional): Package access level - public or restricted (default: public)

Example:

{
  "tool": "npm_publish_package",
  "parameters": {
    "package_path": "/path/to/my-package",
    "tag": "latest",
    "access": "public"
  }
}

7. npm_deprecate_package

Deprecate a package version with a custom message.

Parameters:

• package_name (required): Name of the package
• version (required): Version range to deprecate
• message (required): Deprecation message

Example:

{
  "tool": "npm_deprecate_package",
  "parameters": {
    "package_name": "old-package",
    "version": "1.0.0",
    "message": "This version has security vulnerabilities. Please upgrade to 2.0.0"
  }
}

8. npm_unpublish_package

Unpublish a package version from NPM registry (irreversible operation).

Parameters:

• package_name (required): Name of the package
• version (optional): Specific version to unpublish (unpublishes entire package if not specified)

Example:

{
  "tool": "npm_unpublish_package",
  "parameters": {
    "package_name": "my-package",
    "version": "1.0.0"
  }
}

📖 Usage Examples

Package Information

// Get package information
{
  "tool": "npm_package_info",
  "parameters": {
    "package_name": "JAEGIS-web-os",
    "version": "latest"
  }
}

// List all versions
{
  "tool": "npm_list_versions",
  "parameters": {
    "package_name": "JAEGIS-web-os"
  }
}

Package Publishing

// Publish a package
{
  "tool": "npm_publish_package",
  "parameters": {
    "package_path": "/path/to/package",
    "tag": "latest",
    "access": "public"
  }
}

// Validate before publishing
{
  "tool": "npm_validate_package",
  "parameters": {
    "package_path": "/path/to/package"
  }
}

Package Management

// Deprecate a version
{
  "tool": "npm_deprecate_package",
  "parameters": {
    "package_name": "JAEGIS-web-os",
    "version": "1.0.0",
    "message": "This version has security vulnerabilities"
  }
}

// Get download statistics
{
  "tool": "npm_download_stats",
  "parameters": {
    "package_name": "JAEGIS-web-os",
    "period": "last-month"
  }
}

Package Discovery

// Search packages
{
  "tool": "npm_search_packages",
  "parameters": {
    "query": "jaegis web os",
    "limit": 10
  }
}

🛠️ Command Line Options

npm-mcp-server [OPTIONS]

OPTIONS:
  --list-tools         List all available tools with descriptions
  --tools-json         Output complete MCP tools schema as JSON
  --format=table       Use table format for tool listings (default: JSON)
  --help, -h          Show this help message

EXAMPLES:
  npm-mcp-server --list-tools --format=table
  npm-mcp-server --tools-json > tools-schema.json
  npm-mcp-server  # Start MCP server

🔒 Security Features

• ✅ Credential Sanitization - NPM tokens masked in logs (shows only first/last 4 chars)
• ✅ Environment-based Authentication - No hardcoded credentials in source code
• ✅ Token Format Validation - Validates NPM token formats (npm_* prefix)
• ✅ Registry Configuration - Configurable NPM registry URLs
• ✅ Error Handling - Comprehensive error messages without credential exposure
• ✅ Portable Configuration - No hardcoded paths, works from any directory
• ✅ Secure Environment Loading - Cascade loading from HOME/.mcp/.env

Security Best Practices

1. Never commit credentials to version control

   # Add to .gitignore
   .env
   .env.local
   .env.*.local
   

2. Use environment variables for sensitive data

   export NPM_TOKEN=npm_your_token_here
   export NPM_USERNAME=your_username
   export NPM_EMAIL=your_email@example.com
   

3. Rotate tokens regularly

   • Visit https://www.npmjs.com/settings/tokens
   • Generate new tokens periodically
   • Revoke old tokens

4. Use token scopes appropriately

   • Automation: For CI/CD pipelines
   • Publish: For manual publishing
   • Read-only: For package information queries

5. Verify package ownership before publishing

   • Ensure you own the package name
   • Check for typosquatting attempts
   • Use 2FA on NPM account

🚨 Troubleshooting

Common Issues and Solutions

"NPM token is required"

# Set your NPM token
export NPM_TOKEN=npm_your_token_here
export NPM_USERNAME=your_username
export NPM_EMAIL=your_email@example.com

# Verify it's set
echo $NPM_TOKEN

"Package not found"

• Check package name spelling (case-sensitive)
• Verify package exists on NPM registry: https://www.npmjs.com/package/package-name
• Ensure token has access to private packages
• Try searching first: npm_search_packages with the package name

"Permission denied" when publishing

• Verify token has publish permissions
• Check package ownership: npm owner ls package-name
• Ensure token is not expired
• Verify you're publishing to the correct registry
• Check if package name is already taken

"Package validation failed"

• Check package.json syntax (valid JSON)
• Verify required fields: name, version
• Ensure version follows semver format (e.g., 1.0.0)
• Validate dependencies are valid package names
• Check for circular dependencies

"Invalid version format"

• Version must follow semantic versioning: MAJOR.MINOR.PATCH
• Examples: 1.0.0, 2.1.3, 0.0.1
• Pre-release versions: 1.0.0-alpha, 1.0.0-beta.1
• Build metadata: 1.0.0+build.123

"Connection timeout"

• Check internet connection
• Verify NPM registry is accessible
• Try using a different registry: NPM_REGISTRY=https://registry.npmjs.org/
• Check firewall/proxy settings

"Tool returns empty results"

• Verify package name is correct
• Check if package has been published
• Ensure you're using the correct registry
• Try with a popular package first (e.g., "react", "lodash")

Debug Mode

# Enable verbose logging
DEBUG=npm-mcp-server npm-mcp-server

# Check server health
npx jaegis-npm-mcp-server@latest --list-tools

# Validate your setup
npx jaegis-npm-mcp-server@latest --tools-json

Getting Help

1. Check the logs - Look for error messages in stderr
2. Verify credentials - Ensure NPM_TOKEN, NPM_USERNAME, NPM_EMAIL are set
3. Test connectivity - Try accessing NPM registry directly
4. Check package.json - Validate syntax and required fields
5. Review examples - See usage examples in this README

Reporting Issues

If you encounter issues:

1. Collect error messages and logs
2. Note the tool name and parameters used
3. Include your Node.js version: node --version
4. Include package version: npm list jaegis-npm-mcp-server
5. Report on GitHub: https://github.com/usemanusai/npm-jaegis-mcp-server/issues

📦 Package Information

• Package: jaegis-npm-mcp-server
• Version: 1.1.0
• Node.js: >=18.0.0
• License: MIT
• Repository: GitHub
• NPM: npmjs.com

Installation

# Via NPX (recommended)
npx jaegis-npm-mcp-server@latest

# Via NPM
npm install -g jaegis-npm-mcp-server
npm-mcp-server

# Via Yarn
yarn global add jaegis-npm-mcp-server
npm-mcp-server

System Requirements

• Node.js: 18.0.0 or higher
• NPM: 8.0.0 or higher
• Internet: Required for NPM registry access
• Credentials: NPM token for authentication-required operations

🤝 Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests
5. Submit a pull request

📄 License

MIT License - see LICENSE file for details.

---

Built with ❤️ by the JAEGIS Team

For more information, visit JAEGIS Documentation