🔄 uvx Migration Workflow

Strategy: Systematic Migration Focus: Dependencies & Risk Management
Timeline: 1-2 weeks Complexity: Medium (Dependency Management + Package Configuration)

🎯 Migration Objectives

From: Complex Multi-Service Setup

  • 70+ dependencies with complex interdependencies

  • Multi-stage Docker build with orchestration

  • Complex configuration across multiple files

  • Enterprise-grade monitoring and infrastructure

To: Simple uvx-Managed Package

  • <20 essential dependencies

  • Single command installation: uvx mcp-academic-rag-server

  • Single configuration file or environment variables

  • Focus on core MCP server functionality

📊 Current State Analysis

Dependency Audit Results

Current Dependencies (Before Migration)

Based on existing pyproject.toml analysis:

Core Dependencies: 13 packages (✅ Already simplified)

Essential MCP & Processing:
- mcp>=1.0.0                    # MCP protocol support
- PyPDF2>=3.0.0                 # PDF text extraction  
- pytesseract>=0.3.10           # OCR processing
- Pillow>=10.0.0                # Image processing

RAG Pipeline:
- haystack-ai>=2.0.0            # RAG framework
- sentence-transformers>=2.2.0   # Text embeddings
- openai>=1.0.0                 # LLM API client
- faiss-cpu>=1.7.0              # Vector similarity search

Utilities & Configuration:
- requests>=2.31.0              # HTTP client
- aiohttp>=3.9.0                # Async HTTP client
- python-dotenv>=1.0.0          # Environment config
- pydantic>=2.0.0               # Data validation
- loguru>=0.7.0                 # Logging
- jsonschema>=4.0.0             # JSON validation

Optional Dependencies: 3 groups (✅ Well organized)

dev: [pytest, black, isort, mypy, flake8]           # Development tools
enhanced: [pymilvus, redis, spacy]                  # Advanced features
web: [flask, flask-cors]                            # Web interface

Analysis: Migration Status

  • Dependencies: ✅ Already simplified to essential packages only

  • Package Structure: ✅ Ready for uvx compatibility

  • Entry Points: ✅ Configured for MCP server execution

  • Optional Features: ✅ Properly separated into extras

Conclusion: Dependency structure is already migration-ready. Focus on testing and validation.

🗺️ Migration Roadmap

Phase 1: Pre-Migration Validation (Days 1-2)

1.1 Environment Assessment

Duration: 4 hours | Risk: Medium

Current Setup Analysis

  • Document current installation process (Docker Compose, manual setup)

  • Identify configuration files and their dependencies

  • Map runtime dependencies vs. development dependencies

  • Test current functionality to establish baseline

uvx Compatibility Testing

  • Test uvx installation in clean environments (Linux, macOS, Windows)

  • Verify Python version requirements (3.9+ compatibility)

  • Check package build process (python -m build)

  • Validate entry point configuration (mcp-academic-rag-server command)

1.2 Dependency Validation

Duration: 6 hours | Risk: High

Core Dependency Testing
# Test minimal installation
pip install mcp PyPDF2 pytesseract Pillow haystack-ai sentence-transformers openai faiss-cpu requests aiohttp python-dotenv pydantic loguru jsonschema

# Verify each component works
python -c "import mcp; print('MCP OK')"
python -c "import PyPDF2; print('PDF OK')"
python -c "import pytesseract; print('OCR OK')"
python -c "from haystack import Pipeline; print('Haystack OK')"
python -c "from sentence_transformers import SentenceTransformer; print('Embeddings OK')"
python -c "import faiss; print('FAISS OK')"
Integration Testing

  • Test MCP server startup with minimal dependencies

  • Verify document processing without optional dependencies

  • Check RAG pipeline functionality with basic setup

  • Validate session management works with simple storage

1.3 Configuration Migration Planning

Duration: 3 hours | Risk: Low

Configuration Simplification

  • Consolidate configuration files into single config.json

  • Identify environment-specific settings (.env file approach)

  • Plan default configuration that works without setup

  • Document configuration options with examples

Phase 2: uvx Package Preparation (Days 3-5)

2.1 Package Structure Optimization

Duration: 8 hours | Risk: Low

Build Configuration

  • Finalize pyproject.toml with uvx-optimized settings

  • Configure entry points for all CLI tools

  • Set up package data (config templates, etc.)

  • Test package build locally

[project.scripts]
mcp-academic-rag-server = "mcp_server:main"
academic-rag-process = "cli.document_cli:main"
academic-rag-chat = "cli.chat_cli:main"

[tool.setuptools.packages.find]
where = ["."]
include = ["*"]
exclude = ["tests*", "docs*", "examples*"]

2.2 Runtime Environment Setup

Duration: 6 hours | Risk: Medium

Entry Point Implementation

  • Enhance main() function in mcp_server.py for uvx compatibility

  • Add command-line argument parsing for configuration options

  • Implement health check command (--health-check)

  • Add version information command (--version)

def main():
    """Main entry point for uvx execution"""
    import argparse
    import sys
    
    parser = argparse.ArgumentParser(description="MCP Academic RAG Server")
    parser.add_argument("--config", help="Configuration file path")
    parser.add_argument("--health-check", action="store_true", help="Run health check")
    parser.add_argument("--version", action="store_true", help="Show version")
    
    args = parser.parse_args()
    
    if args.version:
        print(f"MCP Academic RAG Server v{__version__}")
        return
        
    if args.health_check:
        return run_health_check()
    
    # Start MCP server
    asyncio.run(start_server())

2.3 Installation Testing

Duration: 10 hours | Risk: High

Local Testing Environment

  • Set up clean Python environments (virtualenv, conda, Docker)

  • Test local package installation (pip install -e .)

  • Test uvx installation from local package

  • Verify all entry points work correctly

Multi-Platform Testing
# Test on different platforms
## Linux (Ubuntu 20.04/22.04)
uvx --python 3.9 mcp-academic-rag-server
uvx --python 3.10 mcp-academic-rag-server
uvx --python 3.11 mcp-academic-rag-server

## macOS (Intel/ARM)
uvx mcp-academic-rag-server

## Windows
uvx mcp-academic-rag-server

Phase 3: Integration & Testing (Days 6-8)

3.1 MCP Client Integration

Duration: 8 hours | Risk: High

Claude Desktop Integration

  • Test uvx package with Claude Desktop MCP configuration

  • Verify all 4 MCP tools are discoverable and functional

  • Test error handling and recovery scenarios

  • Validate tool response formats match MCP standards

// claude_desktop_config.json test configuration
{
  "mcpServers": {
    "academic-rag": {
      "command": "uvx",
      "args": ["mcp-academic-rag-server"],
      "env": {
        "OPENAI_API_KEY": "test_key"
      }
    }
  }
}
Alternative MCP Clients

  • Test with other MCP-compatible clients if available

  • Verify protocol compliance using MCP debugging tools

  • Check JSON schema validation for all tool inputs

  • Test async operation handling and timeouts

3.2 End-to-End Workflow Testing

Duration: 6 hours | Risk: Medium

Complete Workflow Validation

  1. Installation Test

    # Fresh environment test
uvx mcp-academic-rag-server --health-check

  2. Document Processing Test

    • Upload test PDF through MCP client

    • Verify OCR processing for scanned documents

    • Check embedding generation and storage

  3. Query Test

    • Ask questions about processed documents

    • Verify RAG retrieval accuracy

    • Check source citation functionality

  4. Session Management Test

    • Test multi-turn conversations

    • Verify session persistence

    • Check session cleanup

3.3 Performance & Resource Testing

Duration: 4 hours | Risk: Medium

Resource Usage Validation

  • Monitor memory usage during typical operations

  • Check CPU utilization for document processing

  • Test with large documents (100+ pages)

  • Verify cleanup after processing completion

Target Metrics:

  • Memory usage < 500MB for normal operations

  • Document processing < 60 seconds for typical papers

  • Query response time < 10 seconds

  • Startup time < 30 seconds

Phase 4: Production Migration (Days 9-10)

4.1 Documentation Update

Duration: 4 hours | Risk: Low

User-Facing Documentation

  • Update README with uvx installation instructions

  • Create migration guide for existing users

  • Update configuration documentation with new simplified approach

  • Test documentation with real users

Developer Documentation

  • Update development setup instructions for uvx

  • Document new build process and testing procedures

  • Create troubleshooting guide for common uvx issues

  • Update CI/CD pipeline if needed

4.2 Rollout Strategy

Duration: 3 hours | Risk: Low

Gradual Migration Plan

  1. Alpha Release: Internal testing with uvx package

  2. Beta Release: Limited external testing with early adopters

  3. Release Candidate: Full feature testing with broader audience

  4. Stable Release: Public release with uvx as primary installation method

Backward Compatibility

  • Maintain Docker option for users who need it (separate documentation)

  • Provide migration scripts for configuration file updates

  • Support legacy installation for transition period

  • Clear deprecation timeline for old installation methods

🚨 Risk Assessment & Mitigation

High-Risk Areas

Risk: uvx Installation Failures

Probability: Medium | Impact: High

  • Causes: Platform-specific dependency conflicts, Python version issues

  • Mitigation:

    • Test on all major platforms (Windows, macOS, Linux)

    • Provide alternative installation methods

    • Clear troubleshooting documentation

Risk: MCP Client Compatibility Issues

Probability: Medium | Impact: High

  • Causes: Protocol version mismatches, tool schema changes

  • Mitigation:

    • Test with multiple MCP clients

    • Validate against MCP specification

    • Implement graceful fallback for unsupported features

Risk: Performance Regression

Probability: Low | Impact: Medium

  • Causes: Dependency changes affecting processing speed

  • Mitigation:

    • Benchmark before and after migration

    • Monitor resource usage during testing

    • Optimize critical paths if needed

Medium-Risk Areas

Risk: Configuration Migration Issues

Probability: Medium | Impact: Medium

  • Causes: Missing configuration options, format changes

  • Mitigation:

    • Provide configuration migration scripts

    • Validate all configuration paths work

    • Document breaking changes clearly

Risk: Dependency Resolution Conflicts

Probability: Low | Impact: Medium

  • Causes: Transitive dependency conflicts, version constraints

  • Mitigation:

    • Lock dependency versions in pyproject.toml

    • Test installation in clean environments

    • Provide dependency troubleshooting guide

✅ Success Criteria & Validation

Technical Success Metrics

  • Installation Success: uvx mcp-academic-rag-server works on 95% of target platforms

  • Functionality Parity: All 4 MCP tools work identically to current implementation

  • Performance Maintenance: No significant performance regression (>20% slower)

  • Resource Efficiency: Memory usage within target limits (<500MB)

User Experience Success Metrics

  • Setup Time: <5 minutes from discovery to first query

  • Error Rate: <5% failure rate for standard operations

  • Documentation Clarity: Users can complete setup without support

  • Migration Ease: Existing users can migrate in <10 minutes

Business Success Metrics

  • Adoption Rate: Time to adoption for new users

  • User Satisfaction: Positive feedback on simplified installation

  • Maintenance Reduction: Reduced support requests and issues

  • Development Velocity: Faster feature development with simpler structure

🔄 Rollback Plan

Rollback Triggers

  • Installation failure rate >20%

  • Critical functionality regression

  • MCP client compatibility issues

  • Performance degradation >50%

Rollback Process

  1. Immediate: Revert to previous Docker-based installation documentation

  2. Short-term: Fix critical issues and re-test migration

  3. Communication: Clear user communication about rollback and timeline

  4. Post-Mortem: Analyze failures and improve migration process

📋 Migration Checklist

Pre-Migration

  • All dependencies validated and tested

  • uvx compatibility confirmed

  • Baseline performance metrics recorded

  • Rollback plan prepared and tested

During Migration

  • Package build and distribution tested

  • MCP client integration verified

  • End-to-end workflows validated

  • Performance metrics within targets

Post-Migration

  • Documentation updated and accessible

  • User support ready for migration questions

  • Monitoring in place for issues

  • Success metrics tracking implemented

Migration Timeline: 10 days total Resource Requirements: 1 developer (full-time), 1 tester (part-time) Success Probability: High (85%+) - Well-defined scope and good preparation