PyQt5 MCP v3.0

Controls ANY PyQt5 application WITHOUT modification - exactly like Playwright controls browsers

🚀 Installation

npx @archmeta1868/pyqt5-mcp@latest

✅ Key Features

• NO app modification required - Works with any unmodified PyQt5 app
• Playwright-identical API - Same tool names and interaction patterns
• Overlap detection - Finds and fixes UI layout issues automatically
• Direct control - No bridge code, flags, or cooperation needed

🎯 Usage

// Launch ANY PyQt5 app without modification
const app = await pyqt5.launch('any_app.py');

// Take accessibility snapshot (Playwright format)
const snapshot = await app.snapshot();

// Interact exactly like Playwright
await app.click('[ref=button1]');
await app.type('[ref=input1]', 'Hello');
await app.screenshot();

// Special: Detect overlapping widgets (as requested)
await app.detectOverlaps();
await app.analyzeLayout({ autoFix: true });

// Close app
await app.close();

🔧 How It Works

Uses Python's import system to automatically inject control code when PyQt5 loads. The target app has zero knowledge of being controlled, exactly like browsers don't know about Playwright.

NO modification required:

# Your app stays exactly as is:
app = QApplication(sys.argv)
window = MainWindow()
window.show()
app.exec_()  # NO MCP CODE AT ALL!

📋 Tools (Playwright-Compatible Names)

• browser_navigate - Launch PyQt5 app
• browser_snapshot - Get accessibility tree
• browser_click - Click widgets
• browser_type - Type text
• browser_screenshot - Capture screen
• browser_evaluate - Execute Python in app context
• browser_detect_overlaps - Find overlapping widgets
• browser_analyze_layout - Fix layout issues
• browser_wait_for - Wait for conditions
• browser_close - Close application

⚡ Version 3.0 - Complete Rewrite

What Changed

• Removed ALL bridge requirements - No more PyQt5Bridge
• Removed app modification - No more --mcp flag
• Removed WebSocket dependency - Direct process control
• Added Playwright compatibility - Identical tool names
• Added automatic injection - Via Python import hooks

Migration from v1.x

// OLD (v1.x) - Required bridge in app
// App needed: if "--mcp" in sys.argv: bridge = PyQt5Bridge(app)
// Then: pyqt5_click, pyqt5_type, etc.

// NEW (v3.0) - NO app modification
// App needs: NOTHING!
// Now: browser_click, browser_type (like Playwright)

🧪 Test It Yourself

# Create a normal PyQt5 app (NO MCP code)
cat > test_app.py << 'EOF'
import sys
from PyQt5.QtWidgets import *

app = QApplication(sys.argv)
button = QPushButton("Normal App - No MCP!")
button.show()
app.exec_()
EOF

# Control it WITHOUT modification!
npx @archmeta1868/pyqt5-mcp@latest test test_app.py

📊 Overlap Detection (Special Feature)

As specifically requested, PyQt5 MCP excels at detecting and fixing UI layout issues:

// Detect overlapping widgets
const overlaps = await app.detectOverlaps();
// Returns: [{ widget1: "Button1", widget2: "Label1", severity: "HIGH" }, ...]

// Analyze and auto-fix layout
const analysis = await app.analyzeLayout({ 
  autoFix: true,
  checkOverlaps: true,
  checkAlignment: true,
  checkSpacing: true
});

🔑 Why Version 3.0?

Previous versions violated the core requirement by requiring bridge code in apps. Version 3.0 is a complete rewrite that works exactly like Playwright - no target modification required.

📝 License

MIT