jaegis-pypi-mcp-server/README.md

PyPI Package Management MCP Server for JAEGIS-Web-OS project with 8 specialized tools

# jaegis-pypi-mcp-server

> PyPI package management with 8 specialized tools for JAEGIS-Web-OS project automation

[![npm version](https://badge.fury.io/js/jaegis-pypi-mcp-server.svg)](https://www.npmjs.com/package/jaegis-pypi-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-pypi-mcp-server@latest --list-tools --format=table

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

# Start the MCP server
npx jaegis-pypi-mcp-server@latest
```

### Global Installation
```bash
npm install -g jaegis-pypi-mcp-server
pypi-mcp-server --list-tools
```

## 🐍 Tool Inventory (8 Tools)

| Tool Name | Category | Description | Required Params | Optional Params |
|-----------|----------|-------------|-----------------|-----------------|
| `pypi_package_info` | Package Information | Get detailed package metadata and dependencies | 1 | 1 |
| `pypi_search_packages` | Package Discovery | Search PyPI registry using keywords | 1 | 1 |
| `pypi_upload_package` | Package Publishing | Upload packages to PyPI registry | 1 | 1 |
| `pypi_list_versions` | Package Information | List all available package versions | 1 | 0 |
| `pypi_download_stats` | Package Analytics | Get download statistics and analytics | 1 | 1 |
| `pypi_validate_package` | Package Validation | Validate package metadata for publishing | 1 | 0 |
| `pypi_build_package` | Package Building | Build distribution files (sdist, wheel) | 1 | 1 |
| `pypi_check_name_availability` | Package Discovery | Check if package name is available | 1 | 0 |

### Tool Categories
- **Package Information** (2 tools) - Retrieve package metadata and versions
- **Package Discovery** (2 tools) - Search registry and check name availability
- **Package Publishing** (1 tool) - Upload packages to PyPI
- **Package Analytics** (1 tool) - Download statistics and metrics
- **Package Validation** (1 tool) - Validate package configuration
- **Package Building** (1 tool) - Build distribution files

## 🔧 Environment Setup

### Required Variables
```bash
export PYPI_TOKEN=pypi-your_token_here         # PyPI API token
export PYPI_USERNAME=__token__                 # PyPI username (use __token__ for token auth)
```

### Optional Variables
```bash
export PYPI_INDEX_URL=https://upload.pypi.org/legacy/     # PyPI upload URL
export PYPI_REPOSITORY_URL=https://pypi.org/simple/       # PyPI repository URL
export DEFAULT_PROJECT=JAEGIS-Web-OS                      # Default project name
```

### Generate PyPI Token
1. Go to [PyPI Account Settings > API tokens](https://pypi.org/manage/account/token/)
2. Click "Add API token"
3. Enter token name and select scope (entire account or specific project)
4. Copy the generated token (format: `pypi-*`)

### Token Format Validation
- ✅ `pypi-*` - PyPI API token
- ✅ `__token__` - Username for token authentication
- ❌ Other formats will show warnings

## 🎯 MCP Client Integration

### Augment Code
```json
{
  "pypi-jaegis": {
    "command": "npx",
    "args": ["@jaegis/pypi-mcp-server@latest"],
    "env": {
      "PYPI_TOKEN": "pypi-your_token_here",
      "PYPI_USERNAME": "__token__"
    }
  }
}
```

### Claude Desktop
```json
{
  "mcpServers": {
    "pypi-jaegis": {
      "command": "npx",
      "args": ["@jaegis/pypi-mcp-server@latest"],
      "env": {
        "PYPI_TOKEN": "pypi-your_token_here",
        "PYPI_USERNAME": "__token__"
      }
    }
  }
}
```

### VS Code MCP Extension
```json
{
  "name": "PyPI JAEGIS",
  "command": "npx @jaegis/pypi-mcp-server@latest",
  "env": {
    "PYPI_TOKEN": "pypi-your_token_here",
    "PYPI_USERNAME": "__token__"
  }
}
```

## 📖 Usage Examples

### Package Information
```javascript
// Get package information
{
  "tool": "pypi_package_info",
  "parameters": {
    "package_name": "JAEGIS-Web-OS",
    "version": "latest"
  }
}

// List all versions
{
  "tool": "pypi_list_versions",
  "parameters": {
    "package_name": "JAEGIS-Web-OS"
  }
}
```

### Package Publishing
```javascript
// Upload a package
{
  "tool": "pypi_upload_package",
  "parameters": {
    "package_path": "/path/to/dist/package.tar.gz",
    "repository": "pypi"
  }
}

// Build distribution files
{
  "tool": "pypi_build_package",
  "parameters": {
    "package_path": "/path/to/package",
    "build_type": "both"
  }
}
```

### Package Validation
```javascript
// Validate package
{
  "tool": "pypi_validate_package",
  "parameters": {
    "package_path": "/path/to/package"
  }
}

// Check name availability
{
  "tool": "pypi_check_name_availability",
  "parameters": {
    "package_name": "my-new-package"
  }
}
```

### Package Analytics
```javascript
// Get download statistics
{
  "tool": "pypi_download_stats",
  "parameters": {
    "package_name": "JAEGIS-Web-OS",
    "period": "last-month"
  }
}
```

### Package Discovery
```javascript
// Search packages
{
  "tool": "pypi_search_packages",
  "parameters": {
    "query": "jaegis web os",
    "limit": 10
  }
}
```

## 🛠️ Command Line Options

```bash
pypi-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:
  pypi-mcp-server --list-tools --format=table
  pypi-mcp-server --tools-json > tools-schema.json
  pypi-mcp-server  # Start MCP server
```

## 🔒 Security Features

- ✅ **Credential Sanitization** - PyPI tokens masked in logs
- ✅ **Environment-based Authentication** - No hardcoded credentials
- ✅ **Token Format Validation** - Validates PyPI token formats
- ✅ **Repository Configuration** - Configurable PyPI repository URLs
- ✅ **Error Handling** - Comprehensive error messages without credential exposure

## 🚨 Troubleshooting

### Common Issues

**"PyPI token is required"**
```bash
# Set your PyPI token
export PYPI_TOKEN=pypi-your_token_here
export PYPI_USERNAME=__token__
```

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

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

**"Package validation failed"**
- Check setup.py or pyproject.toml syntax
- Verify required metadata fields
- Ensure dependencies are valid

**"Build failed"**
- Install build dependencies (setuptools, wheel)
- Check package structure
- Verify Python version compatibility

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

## 📦 Package Information

- **Package**: `@jaegis/pypi-mcp-server`
- **Version**: 1.0.0
- **Node.js**: >=18.0.0
- **License**: MIT
- **Repository**: [GitHub](https://github.com/usemanusai/pypi-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)