jaegis-pypi-mcp-server

PyPI package management with 8 fully implemented tools for JAEGIS-Web-OS project automation

🚀 Quick Start

NPX (Recommended)

# 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

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

🐍 Tool Inventory (8 Tools)

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

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

Optional Variables

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
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

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

Claude Desktop

{
  "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

{
  "name": "PyPI JAEGIS",
  "command": "npx @jaegis/pypi-mcp-server@latest",
  "env": {
    "PYPI_TOKEN": "pypi-your_token_here",
    "PYPI_USERNAME": "__token__"
  }
}

📖 Usage Examples

Package Information

// 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

// 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

// 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

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

Package Discovery

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

🛠️ Command Line Options

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"

# 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

# 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

🤝 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