enhanced-mcp-tools/docs/UV_BUILD_GUIDE.md

# Building Enhanced MCP Tools with uv

## 🚀 Quick Start with uv (Tested ✅)

### Prerequisites
```bash
# Ensure uv is installed
uv --version  # Should show uv 0.7.x or later
```

### 1. Clean Build (Recommended)
```bash
cd /home/rpm/claude/enhanced-mcp-tools

# Clean any previous builds
rm -rf dist/ build/ *.egg-info/

# Build both wheel and source distribution
uv build

# Verify build artifacts
ls -la dist/
# Should show:
# enhanced_mcp_tools-1.0.0-py3-none-any.whl
# enhanced_mcp_tools-1.0.0.tar.gz
```

### 2. Test Installation (Verified ✅)
```bash
# Create clean test environment
uv venv test-env
source test-env/bin/activate

# Install from built wheel
uv pip install dist/enhanced_mcp_tools-1.0.0-py3-none-any.whl

# Test core functionality
python -c "from enhanced_mcp import create_server; print('✅ Core works')"

# Install with enhanced features
uv pip install "enhanced-mcp-tools[enhanced]" --find-links dist/

# Verify enhanced-mcp command is available
enhanced-mcp --help
```

### 3. Development Installation
```bash
# Install in development mode with all features
uv pip install -e ".[dev]"

# Run validation
python test_package_structure.py
```

## 🔧 Development Workflow with uv

### Create Development Environment
```bash
# Create and activate virtual environment
uv venv enhanced-mcp-dev
source enhanced-mcp-dev/bin/activate

# Install in development mode with all dependencies
uv pip install -e ".[dev]"

# Run tests
pytest

# Run linting
ruff check .
black --check .
```

### Dependency Management
```bash
# Add a new dependency
uv add "new-package>=1.0.0"

# Add a development dependency
uv add --dev "new-dev-tool>=2.0.0"

# Update dependencies
uv pip install --upgrade -e ".[dev]"

# Show dependency tree
uv pip list --tree
```

## 📦 Distribution Building

### Build All Distributions
```bash
# Clean previous builds
rm -rf dist/ build/ *.egg-info/

# Build both wheel and source distribution
uv build

# Check what was built
ls -la dist/
```

### Build Specific Formats
```bash
# Only wheel (faster, recommended for most uses)
uv build --wheel

# Only source distribution (for PyPI)
uv build --sdist

# Build with specific Python version
uv build --python 3.11
```

## 🧪 Testing the Built Package

### Test Installation from Wheel
```bash
# Create clean test environment
uv venv test-env
source test-env/bin/activate

# Install from built wheel
uv pip install dist/enhanced_mcp_tools-1.0.0-py3-none-any.whl

# Test core functionality
python -c "from enhanced_mcp import create_server; print('✅ Core import works')"

# Test enhanced features (if dependencies available)
python -c "
try:
    from enhanced_mcp.sneller_analytics import SnellerAnalytics
    print('✅ Enhanced features available')
except Exception as e:
    print(f'⚠️ Enhanced features: {e}')
"
```

### Run Package Validation
```bash
# Run our validation script
python test_package_structure.py
```

## 🌐 Publishing (Optional)

### Test on TestPyPI
```bash
# Build first
uv build

# Upload to TestPyPI (requires account and API token)
uvx twine upload --repository testpypi dist/*

# Test installation from TestPyPI
uv pip install --index-url https://test.pypi.org/simple/ enhanced-mcp-tools
```

### Publish to PyPI
```bash
# Upload to PyPI (requires account and API token)
uvx twine upload dist/*

# Install from PyPI
uv pip install enhanced-mcp-tools
```

## ⚡ uv Advantages for This Project

### Speed Benefits
- **🚀 10-100x faster** than pip for dependency resolution
- **⚡ Parallel downloads** and installations  
- **🗜️ Efficient caching** of packages and metadata

### Perfect for Optional Dependencies
```bash
# uv handles optional dependencies elegantly
uv pip install enhanced-mcp-tools[enhanced]  # Fast resolution
uv pip install enhanced-mcp-tools[full]      # All features
uv pip install enhanced-mcp-tools[dev]       # Development
```

### Development Workflow
```bash
# Hot reload during development
uv pip install -e . && python -m enhanced_mcp.mcp_server
```

## 🛠️ Common Commands Summary

```bash
# Setup
uv venv .venv && source .venv/bin/activate

# Install for development  
uv pip install -e ".[dev]"

# Build package
uv build

# Test installation
uv pip install dist/*.whl

# Run tests
pytest

# Format code
black .
ruff check --fix .

# Clean build
rm -rf dist/ build/ *.egg-info/
```

## 🔍 Troubleshooting

### Check uv Version
```bash
uv --version
```

### Verify pyproject.toml
```bash
# uv can validate your pyproject.toml
uv pip compile pyproject.toml --dry-run
```

### Debug Dependency Resolution
```bash
# See what uv resolves
uv pip install -e ".[full]" --dry-run -v
```

### Build with Verbose Output
```bash
uv build -v
```

This workflow gives you the fastest possible build and dependency management experience! 🚀