Enable uvx GitHub repository usage with automatic Pyodide setup

[ohtaman]

Summary

🚀 Major enhancement: Enable seamless uvx --from=https://github.com/... usage with automatic Pyodide setup and zero manual configuration required.

Problem Solved

Previously, users trying to run:

uvx --from=https://github.com/ohtaman/mip-mcp.git mip-mcp

Would encounter Pyodide dependency issues requiring manual npm install or complex setup.

Solution Implemented

🔧 PyodideManager: Centralized Installation System

• Multi-layered fallback: bundled → npm install → direct download
• Thread-safe initialization with async locks
• Automatic dependency detection and installation
• Comprehensive error handling with actionable messages

⚡ Server Startup Integration

• Pyodide availability check during server startup (not code execution)
• Clear status messages: ✓ Pyodide setup ready - auto-install from /path
• Zero execution delays - setup happens once at startup

🛡️ Robust Fallback Chain

1. Bundled Pyodide (from PyPI wheel) - fastest option
2. Auto npm install (when package.json found) - seamless for GitHub repos
3. Direct download (via aiohttp) - works anywhere with internet
4. Graceful error with clear next steps

Key Features

🎯 Zero User Friction

# Works immediately - no setup required\!
uvx --from=https://github.com/ohtaman/mip-mcp.git mip-mcp
# ✓ Pyodide setup ready - auto-install from /path/to/project

📦 Smart Dependency Management

• Automatic package.json detection across multiple path contexts
• npm install executed transparently when needed
• Download fallback for environments without Node.js
• Performance optimization - cached paths for subsequent usage

🔍 Enhanced User Experience

• Clear startup messages indicating Pyodide status
• Actionable error messages with specific next steps
• No hanging processes or confusing timeouts
• Consistent behavior across installation methods

Technical Implementation

Files Added/Modified

• src/mip_mcp/utils/pyodide_manager.py ✨ New centralized Pyodide management (209 lines)
• src/mip_mcp/server.py: Add startup Pyodide checking with _check_pyodide_sync()
• src/mip_mcp/mcp_server.py: Use server.run() for proper initialization flow
• src/mip_mcp/executor/pyodide_executor.py: Integrate PyodideManager for path resolution
• pyproject.toml: Add aiohttp>=3.8.0 for download functionality
• README.md: Document uvx GitHub usage with automatic setup

Architecture Benefits

• Centralized logic: Single source of truth for Pyodide management
• Event loop safe: No conflicts with FastMCP's async handling
• Resource efficient: One-time setup, cached for all subsequent operations
• Extensible: Easy to add new installation methods or sources

Testing Verified ✅

Startup Behavior

uv run mip-mcp
# 2025-08-03 10:22:46,099 - mip_mcp.server - INFO - Starting MIP MCP Server...
# 2025-08-03 10:22:46,099 - mip_mcp.server - INFO - ✓ Pyodide setup ready - auto-install from /path

Installation Scenarios

• ✅ Bundled Pyodide (PyPI wheel): Instant startup
• ✅ npm install: Automatic detection and installation
• ✅ Direct download: Works without Node.js
• ✅ Error handling: Clear messages for troubleshooting

Code Quality

• ✅ All pre-commit hooks passed: ruff linting, formatting, trailing whitespace
• ✅ Type hints: Full typing support with proper Optional/Union usage
• ✅ Error handling: Comprehensive exception handling with logging
• ✅ Documentation: Clear docstrings and inline comments

Impact

Before

uvx --from=https://github.com/ohtaman/mip-mcp.git mip-mcp
# ❌ RuntimeError: Pyodide module not found. Please install: npm install pyodide
# 😔 Manual setup required, confusing for users

After

uvx --from=https://github.com/ohtaman/mip-mcp.git mip-mcp
# ✅ ✓ Pyodide setup ready - auto-install from /path/to/project
# 🎉 Works immediately, zero configuration needed\!

Breaking Changes

• None: Fully backward compatible with existing usage patterns
• Enhanced: All existing installation methods continue to work
• Improved: Better error messages and user guidance

Future Extensibility

• Plugin architecture: Easy to add new Pyodide sources
• Caching system: Ready for persistent installation caching
• Metrics integration: Can track installation success rates
• Multi-version support: Framework for supporting different Pyodide versions

This enhancement transforms MIP-MCP into a truly plug-and-play optimization library that works seamlessly with modern Python tooling like uvx. Users can now focus on their optimization problems instead of dependency management! 🚀

Related Issues

• Resolves user friction with uvx + GitHub repository usage
• Enables broader adoption through simplified installation
• Supports the growing uvx ecosystem for Python tool distribution

🤖 Generated with Claude Code