Skip to content

v2.0.0 - Complete Architecture Rewrite & Import Fix

Choose a tag to compare

View all tags
@withLinda withLinda released this 02 Aug 13:29
· 13 commits to main since this release
v2.0.0
36492ad

🚀 Chrome DevTools MCP Fork v2.0.0 - Complete Architecture Rewrite

🎯 Critical Fix: Import Error Resolution

This release completely eliminates the "attempted relative import beyond top-level package" errors that made versions 1.0.6 and 1.0.7 unusable in Claude Code and other MCP environments.

🔧 Major Changes

✅ Architecture Modernization

  • Complete rewrite using official FastMCP patterns from MCP Python SDK
  • Absolute imports throughout - No more complex import fallback mechanisms
  • Clean package structure with proper separation of concerns
  • Simplified entry points that work in all execution contexts

✅ Import System Fix

  • Eliminated the flawed "triple fallback import strategy" from v1.0.7
  • Replaced complex relative imports with clean absolute imports
  • Resolved fundamental conflicts with Python's __main__ module restrictions
  • Ensured compatibility with Claude Code and other MCP clients

✅ Dependencies Cleanup

  • Removed: aiohttp>=3.9.0 (no longer needed)
  • Added: websocket-client>=1.0.0 (simplified Chrome communication)
  • Kept: mcp>=1.0.0, requests>=2.25.0 (core requirements)

✅ Code Modernization

  • FastMCP decorators: Using @app.tool() instead of custom registration
  • Standardized responses: New utils package with consistent error/success formats
  • Simplified Chrome client: Synchronous WebSocket approach for better reliability
  • Tool reorganization: Renamed chrome_management.py → browser.py for clarity

📦 What's New

New Files

  • chrome_devtools_mcp_fork/utils/__init__.py - Utilities package
  • chrome_devtools_mcp_fork/utils/helpers.py - Standardized response helpers
  • chrome_devtools_mcp_fork/tools/browser.py - Browser management tools (renamed)

Updated Files

  • chrome_devtools_mcp_fork/main.py - Complete FastMCP rewrite
  • chrome_devtools_mcp_fork/__init__.py - Clean package initialization
  • chrome_devtools_mcp_fork/client.py - Simplified Chrome client
  • All tool modules - Updated to use absolute imports and FastMCP patterns
  • pyproject.toml - Version 2.0.0 with clean dependency management

Removed Files

  • chrome_devtools_mcp_fork/cdp_context.py - Complex import context (no longer needed)
  • chrome_devtools_mcp_fork/run_server.py - Redundant server entry point
  • fix-package.md - Superseded by new architecture

🧪 Verification

All critical tests now pass:

✅ python -c "import chrome_devtools_mcp_fork"
✅ chrome-devtools-mcp-fork --help
✅ pip show chrome-devtools-mcp-fork | grep "Version: 2.0.0"
✅ All MCP tool functions importable without errors

🔄 Migration Guide

For Users

# Simple upgrade - no configuration changes needed
pip install --upgrade chrome-devtools-mcp-fork==2.0.0

For Developers

  • API compatibility maintained - All tool function signatures unchanged
  • Response formats preserved - Existing integrations continue to work
  • Entry points unchanged - Same command-line interface

🐛 Bug Fixes

  • Fixed: "attempted relative import beyond top-level package" errors in all contexts
  • Fixed: Import failures when executed as __main__ module
  • Fixed: Complex import fallback race conditions
  • Fixed: Inconsistent behavior across different execution environments
  • Fixed: Package installation and entry point issues

🏗️ Breaking Changes

Architecture

  • Migration to FastMCP - Internal architecture completely rewritten
  • Import system changed - Now uses absolute imports throughout
  • Dependency changes - See dependencies section above

Compatibility

  • ✅ Public API unchanged - All MCP tool functions work the same way
  • ✅ Configuration compatible - Existing setups continue to work
  • ✅ Entry points preserved - Same command-line interface

🔗 References

  • Issue #3: Complete technical analysis and implementation details
  • Documentation: Updated for new architecture patterns
  • Testing: Comprehensive 5-phase validation protocol followed

This release represents a complete modernization of the chrome-devtools-mcp-fork package, eliminating all import-related technical debt while maintaining full backward compatibility for end users.

For detailed technical analysis, see Issue #3.

Assets 2
Loading