jaegis-npm-mcp-server

Version:
NPM Package Management MCP Server with 10 production-ready tools including complete 5-step security pipeline
github.com/usemanusai/npm-jaegis-mcp-server
588 lines (487 loc) • 14.8 kB
Markdown
# jaegis-npm-mcp-server

> NPM package management with 10 production-ready tools including complete 5-step security pipeline

[![npm version](https://badge.fury.io/js/jaegis-npm-mcp-server.svg)](https://www.npmjs.com/package/jaegis-npm-mcp-server)
[![Node.js](https://img.shields.io/badge/node-%3E%3D18.0.0-brightgreen)](https://nodejs.org/)
[![MCP](https://img.shields.io/badge/MCP-Model%20Context%20Protocol-blue)](https://modelcontextprotocol.io/)
[![License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)

## 🚀 Quick Start

### NPX (Recommended)
```bash
# 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
```bash
npm install -g jaegis-npm-mcp-server
npm-mcp-server --list-tools
```

## 📦 Tool Inventory (10 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 |
| `security_check` | Security | Scan project for exposed credentials and secrets | 1 | 0 |
| `health_check` | Diagnostics | Server health, version, uptime, and dependency status | 0 | 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
- **Security** (1 tool) - Security scanning and credential detection
- **Diagnostics** (1 tool) - Server health and status

## 🔧 Environment Setup

### Required Variables
```bash
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
```bash
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](https://www.npmjs.com/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
```json
{
  "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
```json
{
  "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
```json
{
  "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:**
```json
{
  "tool": "npm_package_info",
  "parameters": {
    "package_name": "express",
    "version": "4.18.0"
  }
}
```

**Response:**
```json
{
  "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:**
```json
{
  "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:**
```json
{
  "tool": "npm_list_versions",
  "parameters": {
    "package_name": "react"
  }
}
```

**Response:**
```json
{
  "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:**
```json
{
  "tool": "npm_download_stats",
  "parameters": {
    "package_name": "lodash",
    "period": "last-month"
  }
}
```

**Response:**
```json
{
  "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:**
```json
{
  "tool": "npm_validate_package",
  "parameters": {
    "package_path": "/path/to/my-package"
  }
}
```

**Response:**
```json
{
  "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:**
```json
{
  "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:**
```json
{
  "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:**
```json
{
  "tool": "npm_unpublish_package",
  "parameters": {
    "package_name": "my-package",
    "version": "1.0.0"
  }
}
```

## 📖 Usage Examples

### Package Information
```javascript
// 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
```javascript
// 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
```javascript
// 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
```javascript
// Search packages
{
  "tool": "npm_search_packages",
  "parameters": {
    "query": "jaegis web os",
    "limit": 10
  }
}
```

## 🛠️ Command Line Options

```bash
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**
   ```bash
   # Add to .gitignore
   .env
   .env.local
   .env.*.local
   ```

2. **Use environment variables for sensitive data**
   ```bash
   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"**
```bash
# 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
```bash
# 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 NPM: https://www.npmjs.com/package/jaegis-npm-mcp-server

## 📦 Package Information

- **Package**: jaegis-npm-mcp-server
- **Version**: 1.1.5
- **Node.js**: >=18.0.0
- **License**: MIT
- **NPM**: [npmjs.com/package/jaegis-npm-mcp-server](https://www.npmjs.com/package/jaegis-npm-mcp-server)
- **Tools**: 10 production-ready tools with complete security infrastructure

### Installation

```bash
# 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](LICENSE) file for details.

---

**Built with ❤️ by the JAEGIS Team**

For more information, visit [JAEGIS Documentation](https://jaegis.ai/docs)