enhanced-mcp-tools/UV_BUILD_GUIDE.md

Building Enhanced MCP Tools with uv

🚀 Quick Start with uv (Tested ✅)

Prerequisites

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

1. Clean Build (Recommended)

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

# 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

# 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

# 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

# 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

# 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

# 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

# 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

# Run our validation script
python test_package_structure.py

🌐 Publishing (Optional)

Test on TestPyPI

# 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

# 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

# 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

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

🛠️ Common Commands Summary

# 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

uv --version

Verify pyproject.toml

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

Debug Dependency Resolution

# See what uv resolves
uv pip install -e ".[full]" --dry-run -v

Build with Verbose Output

uv build -v

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