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.

Critical Issue Fixed: "Cannot find module 'pyodide.asm.js' imported from pyodide.js"

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
• Complete package download with all essential files
• 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. Enhanced npm install:
   • Strategy 1: Install in project root (when package.json found)
   • Strategy 2: Install in temporary directory (for uvx scenarios)
3. Complete direct download (via aiohttp) - downloads all essential files:
   • pyodide.js (main JavaScript file)
   • pyodide.asm.js (WebAssembly JavaScript glue)
   • pyodide.asm.wasm (WebAssembly binary)
   • python_stdlib.zip (Python standard library)
   • pyodide_py.tar (Python packages)
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
• Dual npm strategy: project root + temporary directory fallback
• Complete file verification before confirming success
• 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 (301 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 (project root): Automatic detection and installation
• ✅ npm install (temp directory): Works for uvx scenarios without package.json
• ✅ Complete download: All essential Pyodide files (js, asm.js, asm.wasm, stdlib.zip)
• ✅ 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

Integration Testing

• ✅ Pyodide initialization: All essential files present and verified
• ✅ PuLP integration: Import and problem setup successful
• ✅ File generation: LP format output working correctly
• ✅ Library detection: Correctly identifies MIP libraries

Impact

Before

uvx --from=https://github.com/ohtaman/mip-mcp.git mip-mcp
# ❌ RuntimeError: Pyodide module not found. Please install: npm install pyodide
# ❌ Cannot find module 'pyodide.asm.js' imported from pyodide.js
# 😔 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
• Fixes critical Pyodide file missing errors in WebAssembly environment

🤖 Generated with Claude Code