jaegis-npm-mcp-server/README.md

NPM Package Management MCP Server for JAEGIS-web-os project with 8 specialized tools

# jaegis-npm-mcp-server

> NPM package management with 8 specialized tools for JAEGIS-web-os project automation

[![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/)

## 🚀 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 (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
```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"
  }
}
```

## 📖 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
- ✅ **Environment-based Authentication** - No hardcoded credentials
- ✅ **Token Format Validation** - Validates NPM token formats
- ✅ **Registry Configuration** - Configurable NPM registry URLs
- ✅ **Error Handling** - Comprehensive error messages without credential exposure

## 🚨 Troubleshooting

### Common Issues

**"NPM token is required"**
```bash
# Set your NPM token
export NPM_TOKEN=npm_your_token_here
```

**"Package not found"**
- Check package name spelling
- Verify package exists on NPM registry
- Ensure token has access to private packages

**"Permission denied"**
- Verify token has publish permissions
- Check package ownership
- Ensure token is not expired

**"Package validation failed"**
- Check package.json syntax
- Verify required fields (name, version)
- Ensure dependencies are valid

### Debug Mode
```bash
# Enable debug logging
DEBUG=npm-mcp-server npm-mcp-server
```

## 📦 Package Information

- **Package**: `@jaegis/npm-mcp-server`
- **Version**: 1.0.0
- **Node.js**: >=18.0.0
- **License**: MIT
- **Repository**: [GitHub](https://github.com/usemanusai/npm-mcp-server)

## 🤝 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)