@debugelectron/debug-electron-mcp 1.6.9 → 1.7.0

package/README.md

@@ -1,67 +1,86 @@
-# Debug Electron MCP
+# Debug Electron MCP
 
-[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)
 [![npm version](https://img.shields.io/npm/v/@debugelectron/debug-electron-mcp)](https://www.npmjs.com/package/@debugelectron/debug-electron-mcp)
+[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)
 [![MCP](https://img.shields.io/badge/MCP-Model%20Context%20Protocol-blue)](https://modelcontextprotocol.io)
 
-A powerful Model Context Protocol (MCP) server that provides comprehensive Electron application automation, debugging, and observability capabilities. Supercharge your Electron development workflow with AI-powered automation through Chrome DevTools Protocol integration.
+**The ultimate Model Context Protocol (MCP) server for automating, debugging, and testing Electron applications.**
+
+Use the power of AI to interact with ANY Electron application. Inspect the DOM, click buttons by text, fill forms, capture screenshots, and read console logs—all through a standardized protocol compatible with Claude Code, Claude Desktop, Cursor, and other MCP clients.
+
+Install it once globally — it auto-detects which project you're in and scopes itself. Works with multiple Electron apps across multiple sessions with zero extra config.
 
-## 🎯 What Makes This Special
+---
 
-Transform your Electron development experience with **AI-powered automation**:
+## Table of Contents
+
+- [Features](#features)
+- [Quick Start](#quick-start)
+- [How Multi-Project Works](#how-multi-project-works)
+- [Enabling Remote Debugging (Required)](#enabling-remote-debugging-required)
+- [Usage Guide](#usage-guide)
+  - [Core Workflow](#core-workflow)
+  - [Tool Reference](#tool-reference)
+  - [Project Management Tools](#project-management-tools)
+  - [Interaction Commands](#interaction-commands)
+- [Advanced: HTTP Server Mode](#advanced-http-server-mode)
+- [Development](#development)
+- [Troubleshooting](#troubleshooting)
+- [License](#license)
 
-- **🔄 Real-time UI Automation**: Click buttons, fill forms, and interact with any Electron app programmatically
-- **📸 Visual Debugging**: Take screenshots and capture application state without interrupting development
-- **🔍 Deep Inspection**: Extract DOM elements, application data, and performance metrics in real-time
-- **⚡ DevTools Protocol Integration**: Universal compatibility with any Electron app - no modifications required
-- **🚀 Development Observability**: Monitor logs, system info, and application behavior seamlessly
+---
 
-## 🚀 Key Features
+## Features
 
-### 🎮 Application Control & Automation
+### Universal Compatibility
+- **Works with ANY Electron app**: No source code modifications required.
+- **Zero-setup integration**: Connects purely via Chrome DevTools Protocol (CDP).
+- **Cross-platform**: Supports Windows, macOS, and Linux.
 
-- **Launch & Manage**: Start, stop, and monitor Electron applications with full lifecycle control
-- **Interactive Automation**: Execute JavaScript code directly in running applications via WebSocket
-- **UI Testing**: Automate button clicks, form interactions, and user workflows
-- **Process Management**: Track PIDs, monitor resource usage, and handle graceful shutdowns
+### Auto-Detect & Multi-Project
+- **Automatic project detection**: Reads your `package.json` name or folder name — each project gets its own port automatically.
+- **No config per project**: Install the MCP once globally. Open Claude Code in any Electron project and it just works.
+- **Multiple apps, no conflicts**: App A on port 9222, App B on port 9223 — each Claude Code session only talks to its own app.
+- **Shared registry on disk**: `~/.debug-electron-mcp.json` persists port assignments across sessions and restarts.
 
-### 📊 Advanced Observability
+### Smart UI Automation
+- **Semantic Interaction**: specific `click_by_text` and `fill_input` commands that "just work."
+- **Visual Intelligence**: Take screenshots of specific windows to verify state.
+- **Robust Actions**: Advanced `drag`, `hover`, `type`, and `wait` commands for complex workflows.
 
-- **Screenshot Capture**: Non-intrusive visual snapshots using Playwright and Chrome DevTools Protocol
-- **Real-time Logs**: Stream application logs (main process, renderer, console) with filtering
-- **Window Information**: Get detailed window metadata, titles, URLs, and target information
-- **System Monitoring**: Track memory usage, uptime, and performance metrics
+### Deep Observability
+- **DOM Inspection**: `get_page_structure` gives AI a clean copy of the interactive operational map.
+- **Log Streaming**: Read main process, renderer, and console logs in real-time.
+- **Performance**: Monitor memory, timing, and system metrics.
 
-### 🛠️ Development Productivity
+---
 
-- **Universal Compatibility**: Works with any Electron app without requiring code modifications
-- **DevTools Integration**: Leverage Chrome DevTools Protocol for powerful debugging capabilities
-- **Build Automation**: Cross-platform building for Windows, macOS, and Linux
-- **Environment Management**: Clean environment handling and debugging port configuration
+## Quick Start
 
-## 🚀 Quick Start
+### Step 1: Add to your MCP config (one time)
 
-**Just add to your MCP config and go!** No environment variables needed.
+#### Claude Code (Global — recommended)
 
-**VS Code:**
+Add to `~/.claude/settings.json`:
 ```json
 {
-  "mcp": {
-    "servers": {
-      "electron": {
-        "command": "npx",
-        "args": ["-y", "@debugelectron/debug-electron-mcp@latest"]
-      }
+  "mcpServers": {
+    "debug-electron-mcp": {
+      "command": "npx",
+      "args": ["-y", "@debugelectron/debug-electron-mcp@latest"]
     }
   }
 }
 ```
 
-**Claude Desktop:**
+Done. Every Claude Code session now has the Electron tools available.
+
+#### VS Code / Cursor
+
 ```json
 {
   "mcpServers": {
-    "electron": {
+    "debug-electron-mcp": {
       "command": "npx",
       "args": ["-y", "@debugelectron/debug-electron-mcp@latest"]
     }
@@ -69,11 +88,12 @@ Transform your Electron development experience with **AI-powered automation**:
 }
 ```
 
-**Cursor IDE** (`%APPDATA%\Cursor\mcp_config.json`):
+#### Claude Desktop
+
 ```json
 {
   "mcpServers": {
-    "electron": {
+    "debug-electron-mcp": {
       "command": "npx",
       "args": ["-y", "@debugelectron/debug-electron-mcp@latest"]
     }
@@ -81,749 +101,286 @@ Transform your Electron development experience with **AI-powered automation**:
 }
 ```
 
-That's it! The server is ready to use.
-
-## 📦 Installation
+### Step 2: Start your Electron app with remote debugging
 
-See [Quick Start](#-quick-start) above for MCP configuration. For global installation:
+The first time you use the MCP in a project, it auto-registers the project and assigns a port. Check `list_projects()` to see your assigned port, then start your app:
 
 ```bash
-npm install -g @debugelectron/debug-electron-mcp
-```
-
-## Demo
-
-See the Electron MCP Server in action:
-
-[![Watch Demo Video](https://vumbnail.com/1104937830.jpg)](https://vimeo.com/1104937830)
-
-**[🎬 Watch Full Demo on Vimeo](https://vimeo.com/1104937830)**
-
-*Watch how easy it is to automate Electron applications with AI-powered MCP commands.*
-
-
-## ⚡ Enabling Remote Debugging (Required)
-
-**CRITICAL**: For the Electron MCP Server to communicate with your Electron application, the app **MUST** be started with Chrome DevTools Protocol (CDP) remote debugging enabled on port 9222. Without this, the MCP server cannot connect to or control the application.
-
-### 🔍 How It Works
-
-The Electron MCP Server uses the Chrome DevTools Protocol (CDP) to:
-- Connect to your Electron app via WebSocket
-- Execute JavaScript in the renderer process
-- Capture screenshots and inspect the DOM
-- Automate UI interactions (clicks, form fills, etc.)
-
-The server automatically scans ports **9222-9225** to find running Electron apps with debugging enabled.
-
-### 📋 Configuration Methods
-
-Choose **ONE** of the following methods to enable remote debugging:
-
----
-
-#### Method 1: Command Line Flag (Recommended for Quick Testing)
-
-Start your Electron app with the `--remote-debugging-port` flag:
-
-```bash
-# Using electron directly
 electron . --remote-debugging-port=9222
-
-# Using npx
-npx electron . --remote-debugging-port=9222
-
-# Via npm script
-npm start -- --remote-debugging-port=9222
-```
-
----
-
-#### Method 2: Modify package.json Scripts (Recommended for Projects)
-
-This is the most reliable method. It creates a dedicated command for launching your app with AI capabilities enabled.
-
-**Step 1: Open your `package.json` file**
-Locate the file in the root of your project.
-
-**Step 2: Find the `"scripts"` section**
-It usually looks like this:
-```json
-"scripts": {
-  "start": "electron .",
-  "build": "electron-builder"
-}
 ```
 
-**Step 3: Add the debug script**
-Add a new script (e.g., `"dev"`) that includes the `--remote-debugging-port=9222` flag.
-*Make sure to add a comma (`,`) to the end of the previous line!*
-
-```json
-"scripts": {
-  "start": "electron .",  <-- Add comma here if needed
-  "build": "electron-builder", <-- Add comma here
-  "dev": "electron . --remote-debugging-port=9222"  <-- ADD THIS LINE
-}
-```
-
-**Note for Frameworks:**
-- If you use **Electron Forge**: `"dev": "electron-forge start -- -- --remote-debugging-port=9222"`
-- If you use **Electron Builder**: `"dev": "electron-builder start -- --remote-debugging-port=9222"`
-- Generally, append the flag after your usual start command.
-
-**Step 4: Run the script**
-Execute the command in your terminal:
-
-```bash
-npm run dev
-```
-
-Your app will launch with port 9222 open, ready for the MCP server to connect.
+That's it. The MCP auto-detects your project and scopes all commands to it.
 
 ---
 
-#### Method 3: Programmatic Configuration (Best for Production Apps)
+## How Multi-Project Works
 
-Add this code to your Electron app's **main process** file (usually `main.js` or `main.ts`):
+The MCP automatically detects which project it's running in — no flags, no `projectName` in every call, no per-project config.
 
-```javascript
-const { app } = require('electron');
+### What happens when Claude Code opens in your project:
 
-// Enable remote debugging based on environment or command line args
-const enableRemoteDebugging = 
-  process.env.NODE_ENV === 'development' ||
-  process.env.ELECTRON_MCP_DEBUG === 'true' ||
-  process.argv.includes('--dev') ||
-  process.argv.includes('--remote-debugging-port=9222');
-
-if (enableRemoteDebugging) {
-  // IMPORTANT: This must be called BEFORE app.whenReady()
-  app.commandLine.appendSwitch('remote-debugging-port', '9222');
-  console.log('🔧 Remote debugging enabled on port 9222');
-}
-
-// Rest of your app initialization...
-app.whenReady().then(() => {
-  // Create windows, etc.
-});
-```
+1. Claude Code spawns the MCP server from your project directory
+2. The MCP reads your `package.json` name (or uses the folder name)
+3. If the project is already registered, it uses the existing port
+4. If it's new, it auto-registers and assigns the next free port
+5. All tool calls are automatically scoped to that project's port
 
-**TypeScript version:**
+### Example: Two apps, two sessions
 
-```typescript
-import { app } from 'electron';
-
-const enableRemoteDebugging = 
-  process.env.NODE_ENV === 'development' ||
-  process.env.ELECTRON_MCP_DEBUG === 'true' ||
-  process.argv.includes('--dev');
-
-if (enableRemoteDebugging) {
-  app.commandLine.appendSwitch('remote-debugging-port', '9222');
-  console.log('🔧 Remote debugging enabled on port 9222');
-}
-```
-
----
-
-#### Method 4: Environment Variable (CI/CD Friendly)
-
-Set an environment variable before starting your app:
-
-**Windows (PowerShell):**
-```powershell
-$env:ELECTRON_MCP_DEBUG = "true"
-npm start
-```
-
-**Windows (CMD):**
-```cmd
-set ELECTRON_MCP_DEBUG=true && npm start
 ```
+# Session A: Claude Code in ~/projects/music-app/
+# MCP auto-detects "music-app" → port 9222
+take_screenshot()  # only sees music-app
 
-**macOS/Linux:**
-```bash
-ELECTRON_MCP_DEBUG=true npm start
+# Session B: Claude Code in ~/projects/todo-app/
+# MCP auto-detects "todo-app" → port 9223
+take_screenshot()  # only sees todo-app
 ```
 
-Then check for this variable in your main process (see Method 3).
+No cross-talk. No manual setup. Each session knows its app.
 
----
-
-### ✅ Verifying Remote Debugging is Enabled
+### Check your assigned port
 
-When remote debugging is properly enabled, you'll see a message like this in your console:
+Use `list_projects()` from any session to see all registered projects and their ports:
 
 ```
-DevTools listening on ws://127.0.0.1:9222/devtools/browser/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
+list_projects()
+# -> Registered projects (2):
+#    - music-app: port 9222 [connected (1 window(s))]
+#    - todo-app: port 9223 [not connected]
 ```
 
-You can also verify by opening this URL in a browser:
-```
-http://localhost:9222/json
-```
-
-This should return a JSON array of available debugging targets.
-
-### 🚨 Common Issues
-
-| Issue | Cause | Solution |
-|-------|-------|----------|
-| "No running Electron application found" | App not started with debugging | Use `--remote-debugging-port=9222` flag |
-| Port 9222 already in use | Another debugger or Electron app is running | Close other apps or use a different port (9223-9225) |
-| Connection refused | Firewall blocking localhost | Check firewall settings for port 9222 |
-| `app.commandLine.appendSwitch` not working | Called after `app.whenReady()` | Move the call to the top of main.js, before any async code |
-
-### 🤖 For AI Assistants
-
-When configuring an Electron app for MCP Server:
-
-1. **Check if already configured**: Look for `--remote-debugging-port` in `package.json` scripts or `app.commandLine.appendSwitch` in the main process file
-2. **Preferred method**: Modify `package.json` to add a `dev` or `debug` script with `--remote-debugging-port=9222`
-3. **Always verify**: After starting the app, use `get_electron_window_info` or `list_electron_windows` to confirm connection
-4. **Port range**: The MCP server scans ports 9222-9225, so any of these ports will work
-
-## 🎯 Proper MCP Usage Guide
-
-### ⚠️ Critical: Argument Structure
-
-**The most common mistake** when using this MCP server is incorrect argument structure for the `send_command_to_electron` tool.
-
-#### ❌ Wrong (causes "selector is empty" errors):
-
-```javascript
-{
-  "command": "click_by_selector",
-  "args": "button.submit-btn"  // ❌ Raw string - WRONG!
-}
-```
+### Registry persistence
 
-#### ✅ Correct:
+Port assignments are saved to `~/.debug-electron-mcp.json` and shared across all sessions:
 
-```javascript
+```json
 {
-  "command": "click_by_selector",
-  "args": {
-    "selector": "button.submit-btn"  // ✅ Object with selector property
+  "portRange": [9222, 9322],
+  "projects": {
+    "music-app": { "port": 9222 },
+    "todo-app": { "port": 9223 }
   }
 }
 ```
 
-### 📋 Command Argument Reference
-
-| Command                                 | Required Args                                                                       | Example                                          |
-| --------------------------------------- | ----------------------------------------------------------------------------------- | ------------------------------------------------ |
-| `click_by_selector`                     | `{"selector": "css-selector"}`                                                      | `{"selector": "button.primary"}`                 |
-| `click_by_text`                         | `{"text": "button text"}`                                                           | `{"text": "Submit"}`                             |
-| `fill_input`                            | `{"value": "text", "selector": "..."}` or `{"value": "text", "placeholder": "..."}` | `{"placeholder": "Enter name", "value": "John"}` |
-| `send_keyboard_shortcut`                | `{"text": "key combination"}`                                                       | `{"text": "Ctrl+N"}`                             |
-| `eval`                                  | `{"code": "javascript"}`                                                            | `{"code": "document.title"}`                     |
-| `get_title`, `get_url`, `get_body_text` | No args needed                                                                      | `{}` or omit args                                |
-
-### 🔄 Recommended Workflow
-
-1. **Inspect**: Start with `get_page_structure` or `debug_elements`
-2. **Target**: Use specific selectors or text-based targeting
-3. **Interact**: Use the appropriate command with correct argument structure
-4. **Verify**: Take screenshots or check page state
-
-```javascript
-// Step 1: Understand the page
-{
-  "command": "get_page_structure"
-}
-
-// Step 2: Click button using text (most reliable)
-{
-  "command": "click_by_text",
-  "args": {
-    "text": "Create New Encyclopedia"
-  }
-}
+### Manual project management
 
-// Step 3: Fill form field
-{
-  "command": "fill_input",
-  "args": {
-    "placeholder": "Enter encyclopedia name",
-    "value": "AI and Machine Learning"
-  }
-}
+You can also manage projects explicitly with the built-in tools:
 
-// Step 4: Submit with selector
-{
-  "command": "click_by_selector",
-  "args": {
-    "selector": "button[type='submit']"
-  }
-}
 ```
-
-### 🐛 Troubleshooting Common Issues
-
-| Error                            | Cause                            | Solution                       |
-| -------------------------------- | -------------------------------- | ------------------------------ |
-| "The provided selector is empty" | Passing string instead of object | Use `{"selector": "..."}`      |
-| "Element not found"              | Wrong selector                   | Use `get_page_structure` first |
-| "Click prevented - too soon"     | Rapid consecutive clicks         | Wait before retrying           |
-
-
-
-
-
-
-## 🔧 Available Tools
-
-### `launch_electron_app`
-
-Launch an Electron application with debugging capabilities.
-
-```javascript
-{
-  "appPath": "/path/to/electron-app",
-  "devMode": true,  // Enables Chrome DevTools Protocol on port 9222
-  "args": ["--enable-logging", "--dev"]
-}
+register_project({ projectName: "my-app" })                    # register with auto-assigned port
+register_project({ projectName: "my-app", port: 9250 })        # register with specific port
+unregister_project({ projectName: "old-app" })                  # free a port
+list_projects()                                                  # see all projects
 ```
 
-**Returns**: Process ID and launch confirmation
-
-### `get_electron_window_info`
-
-Get comprehensive window and target information via Chrome DevTools Protocol.
+### Override with projectName
 
-```javascript
-{
-  "includeChildren": true  // Include child windows and DevTools instances
-}
+If you need to target a different project from the current session, pass `projectName` explicitly:
 ```
-
-**Returns**:
-
-- Window IDs, titles, URLs, and types
-- DevTools Protocol target information
-- Platform details and process information
-
-### `take_screenshot`
-
-Capture high-quality screenshots using Playwright and Chrome DevTools Protocol.
-
-```javascript
-{
-  "outputPath": "/path/to/screenshot.png",  // Optional: defaults to temp directory
-  "windowTitle": "My App"  // Optional: target specific window
-}
+take_screenshot({ projectName: "other-app" })
 ```
 
-**Features**:
+---
 
-- Non-intrusive capture (doesn't bring window to front)
-- Works with any Electron app
-- Fallback to platform-specific tools if needed
+## Enabling Remote Debugging (Required)
 
-### `send_command_to_electron`
+Your Electron app **must be running with remote debugging enabled** on the port assigned to your project.
 
-Execute JavaScript commands in the running Electron application via WebSocket.
+Use `list_projects()` to check your assigned port, then start your app with that port.
 
-```javascript
-{
-  "command": "eval",  // Built-in commands: eval, get_title, get_url, click_button, console_log
-  "args": {
-    "code": "document.querySelector('button').click(); 'Button clicked!'"
-  }
-}
+### Method 1: Command Line Flag (Easiest)
+```bash
+electron . --remote-debugging-port=9222
 ```
 
-**Enhanced UI Interaction Commands**:
-
-- `find_elements`: Analyze all interactive UI elements with their properties and positions
-- `click_by_text`: Click elements by their visible text, aria-label, or title (more reliable than selectors)
-- `fill_input`: Fill input fields by selector, placeholder text, or associated label text
-- `select_option`: Select dropdown options by value or visible text
-- `get_page_structure`: Get organized overview of all page elements (buttons, inputs, selects, links)
-- `get_title`: Get document title
-- `get_url`: Get current URL
-- `get_body_text`: Extract visible text content
-- `click_button`: Click buttons by CSS selector (basic method)
-- `console_log`: Send console messages
-- `eval`: Execute custom JavaScript code
-
-**Recommended workflow**: Use `get_page_structure` first to understand available elements, then use specific interaction commands like `click_by_text` or `fill_input`.
-
-### `read_electron_logs`
-
-Stream application logs from main process, renderer, and console.
-
-```javascript
-{
-  "logType": "all",  // Options: "all", "main", "renderer", "console"
-  "lines": 50,       // Number of recent lines
-  "follow": false    // Stream live logs
+### Method 2: package.json (Persistent)
+```json
+"scripts": {
+  "start": "electron .",
+  "dev:debug": "electron . --remote-debugging-port=9222"
 }
 ```
+Then run `npm run dev:debug`.
 
-### `close_electron_app`
-
-Gracefully close the Electron application.
-
+### Method 3: Programmatic (Best for Codebase)
 ```javascript
-{
-  "force": false  // Force kill if unresponsive
-}
-```
-
-### `build_electron_app`
-
-Build Electron applications for distribution.
+const { app } = require('electron');
 
-```javascript
-{
-  "projectPath": "/path/to/project",
-  "platform": "darwin",  // win32, darwin, linux
-  "arch": "x64",         // x64, arm64, ia32
-  "debug": false
+if (process.env.NODE_ENV === 'development' || process.argv.includes('--dev')) {
+  const port = process.env.DEBUG_PORT || '9222';
+  app.commandLine.appendSwitch('remote-debugging-port', port);
+  console.log(`Remote debugging enabled on port ${port}`);
 }
 ```
 
-## 🎮 Demo Application
-
-Try the interactive demo app to test all MCP Server features:
-
-```bash
-cd examples/demo-app
-npm install
-npm run dev
-```
+### Verification
+Open `http://localhost:<port>/json` in your browser. If you see a JSON list of targets, you are ready.
 
-The demo app includes:
-- **Interactive UI Elements**: Buttons, forms, dropdowns, checkboxes
-- **Real-time Event Logging**: Monitor all interactions
-- **MCP Command Examples**: Built-in usage guide
-- **DevTools Integration**: Automatically enabled on port 9222
+---
 
-See [examples/demo-app/README.md](examples/demo-app/README.md) for detailed instructions.
+## Usage Guide
+
+### Core Workflow
+
+1.  **Inspect**: Use `get_page_structure` to see what buttons and inputs are available.
+2.  **Target**: Identify the element you want (e.g., a button with text "Login").
+3.  **Act**: Send a command like `click_by_text` or `fill_input`.
+4.  **Verify**: Use `take_screenshot` or `get_title` to confirm the action succeeded.
+
+### Tool Reference
+
+| Tool | Description |
+|------|-------------|
+| `get_electron_window_info` | Lists all open windows, their titles, and connection IDs. |
+| `list_electron_windows` | Lists all available window targets across applications. |
+| `take_screenshot` | Captures a screenshot of a specific window or the active one. |
+| `read_electron_logs` | Streams console logs from the app (great for debugging errors). |
+| **`send_command_to_electron`** | **The main tool.** Executes specific actions inside the app. |
+
+### Project Management Tools
+
+| Tool | Description |
+|------|-------------|
+| `register_project` | Register a project name, auto-assigns a debugging port. |
+| `unregister_project` | Remove a project, free its port. |
+| `list_projects` | Show all registered projects with ports and connection status. |
+
+### Interaction Commands
+
+Use these inside `send_command_to_electron`:
+
+#### Clicking & Selection
+| Command | Description |
+|---------|-------------|
+| **`click_by_text`** | *Best for buttons/links.* Usage: `{"text": "Submit"}` |
+| **`click_by_selector`** | *Precise control.* Usage: `{"selector": ".submit-btn"}` |
+| **`click_button`** | *Legacy click command.* Usage: `{"selector": "#btn"}` |
+| **`select_option`** | *For dropdowns.* Usage: `{"text": "Category", "value": "Books"}` |
+| **`hover`** | *Hover over elements.* Usage: `{"selector": ".tooltip-trigger"}` |
+| **`drag`** | *Drag and drop.* Usage: `{"startSelector": "#item", "endSelector": "#cart"}` |
+
+#### Input & Forms
+| Command | Description |
+|---------|-------------|
+| **`fill_input`** | *Smart filling.* Usage: `{"placeholder": "Username", "value": "admin"}` |
+| **`type`** | *Simulates real typing.* Usage: `{"text": "Hello World", "slowly": true}` |
+| **`verify_form_state`** | *Checks validity of all forms.* |
+| **`send_keyboard_shortcut`** | *Send key combinations.* Usage: `{"text": "Ctrl+S"}` |
+
+#### Observation
+| Command | Description |
+|---------|-------------|
+| **`get_page_structure`** | *Returns a simplified JSON map of the UI.* |
+| **`find_elements`** | *Detailed list of all interactive elements.* |
+| **`is_visible`** | *Checks visibility.* Usage: `{"selector": "#error-modal"}` |
+| **`get_attribute`** | *Get attributes.* Usage: `{"selector": "img", "attribute": "src"}` |
+| **`count`** | *Count matching elements.* Usage: `{"selector": "li.item"}` |
+| **`debug_elements`** | *Get detailed debug info for buttons and inputs.* |
+| **`get_title`** | *Get the document title.* |
+| **`get_url`** | *Get the current URL.* |
+| **`get_body_text`** | *Get the visible body text.* |
+
+#### Advanced
+| Command | Description |
+|---------|-------------|
+| **`wait`** | *Wait for element/time.* Usage: `{"duration": 1000}` or `{"text": "Loading"}` |
+| **`navigate_to_hash`** | *Navigate to hash routes.* Usage: `{"text": "settings"}` |
+| **`eval`** | *Execute custom JavaScript.* Usage: `{"code": "alert('Hello')"}` |
+| **`console_log`** | *Write to app console.* Usage: `{"message": "Hello"}` |
 
-## 💡 Usage Examples
+---
 
-### Smart UI Interaction Workflow
+## Advanced: HTTP Server Mode
 
-```javascript
-// 1. First, understand the page structure
-await send_command_to_electron({
-  command: 'get_page_structure',
-});
-
-// 2. Click a button by its text (much more reliable than selectors)
-await send_command_to_electron({
-  command: 'click_by_text',
-  args: {
-    text: 'Login', // Finds buttons containing "Login" in text, aria-label, or title
-  },
-});
-
-// 3. Fill inputs by their label or placeholder text
-await send_command_to_electron({
-  command: 'fill_input',
-  args: {
-    text: 'username', // Finds input with label "Username" or placeholder "Enter username"
-    value: 'john.doe@example.com',
-  },
-});
-
-await send_command_to_electron({
-  command: 'fill_input',
-  args: {
-    text: 'password',
-    value: 'secretpassword',
-  },
-});
-
-// 4. Select dropdown options by visible text
-await send_command_to_electron({
-  command: 'select_option',
-  args: {
-    text: 'country', // Finds select with label containing "country"
-    value: 'United States', // Selects option with this text
-  },
-});
-
-// 5. Take a screenshot to verify the result
-await take_screenshot();
-```
+For advanced use cases where you want a single long-lived server that multiple AI clients share, you can run the server in HTTP mode.
 
-### Advanced Element Detection
+> **Note:** Most users don't need this. The standard setup auto-detects projects and handles multiple apps with zero extra config.
 
-```javascript
-// Find all interactive elements with detailed information
-await send_command_to_electron({
-  command: 'find_elements',
-});
-
-// This returns detailed info about every clickable element and input:
-// {
-//   "type": "clickable",
-//   "text": "Submit Form",
-//   "id": "submit-btn",
-//   "className": "btn btn-primary",
-//   "ariaLabel": "Submit the registration form",
-//   "position": { "x": 100, "y": 200, "width": 120, "height": 40 },
-//   "visible": true
-// }
+**Step 1:** Start the server:
+```bash
+npx @debugelectron/debug-electron-mcp@latest serve
+npx @debugelectron/debug-electron-mcp@latest serve --port 4000
 ```
 
-### Automated UI Testing
-
-```javascript
-// Launch app in development mode
-await launch_electron_app({
-  appPath: '/path/to/app',
-  devMode: true,
-});
-
-// Take a screenshot
-await take_screenshot();
-
-// Click a button programmatically
-await send_command_to_electron({
-  command: 'eval',
-  args: {
-    code: "document.querySelector('#submit-btn').click()",
-  },
-});
-
-// Verify the result
-await send_command_to_electron({
-  command: 'get_title',
-});
+**Step 2:** Point your MCP config to the URL:
+```json
+{
+  "mcpServers": {
+    "debug-electron-mcp": {
+      "url": "http://localhost:3100/mcp"
+    }
+  }
+}
 ```
 
-### Development Debugging
-
-```javascript
-// Get window information
-const windowInfo = await get_electron_window_info();
-
-// Extract application data
-await send_command_to_electron({
-  command: 'eval',
-  args: {
-    code: 'JSON.stringify(window.appState, null, 2)',
-  },
-});
-
-// Monitor logs
-await read_electron_logs({
-  logType: 'all',
-  lines: 100,
-});
+**Step 3:** Pass `projectName` in tool calls (no auto-detect in HTTP mode):
 ```
-
-### Performance Monitoring
-
-```javascript
-// Get system information
-await send_command_to_electron({
-  command: 'eval',
-  args: {
-    code: '({memory: performance.memory, timing: performance.timing})',
-  },
-});
-
-// Take periodic screenshots for visual regression testing
-await take_screenshot({
-  outputPath: '/tests/screenshots/current.png',
-});
+send_command_to_electron({ projectName: "music-app", command: "get_title" })
 ```
 
-## 🏗️ Architecture
-
-### Chrome DevTools Protocol Integration
-
-- **Universal Compatibility**: Works with any Electron app that has remote debugging enabled
-- **Real-time Communication**: WebSocket-based command execution with the renderer process
-- **No App Modifications**: Zero changes required to target applications
-
-### Process Management
-
-- **Clean Environment**: Handles `ELECTRON_RUN_AS_NODE` and other environment variables
-- **Resource Tracking**: Monitors PIDs, memory usage, and application lifecycle
-- **Graceful Shutdown**: Proper cleanup and process termination
+**Health check:** `http://localhost:3100/health`
 
-### Cross-Platform Support
-
-- **macOS**: Uses Playwright CDP with screencapture fallback
-- **Windows**: PowerShell-based window detection and capture
-- **Linux**: X11 window management (planned)
+---
 
-## 🧪 Development
+## Development
 
 ### Prerequisites
-
 - Node.js 18+
-- TypeScript 4.5+
-- **Electron** - Required for running and testing Electron applications
-
-  ```bash
-  # Install Electron globally (recommended)
-  npm install -g electron
-
-  # Or install locally in your project
-  npm install electron --save-dev
-  ```
-
-### Target Application Setup
-
-For the MCP server to work with your Electron application, you need to enable remote debugging. Add this code to your Electron app's main process:
-
-```javascript
-const { app } = require('electron');
-const isDev = process.env.NODE_ENV === 'development' || process.argv.includes('--dev');
-
-// Enable remote debugging in development mode
-if (isDev) {
-  app.commandLine.appendSwitch('remote-debugging-port', '9222');
-}
-```
-
-**Alternative approaches:**
-
-```bash
-# Launch your app with debugging enabled
-electron . --remote-debugging-port=9222
-
-# Or via npm script
-npm run dev -- --remote-debugging-port=9222
-```
-
-**Note:** The MCP server automatically scans ports 9222-9225 to detect running Electron applications with remote debugging enabled.
+- npm or pnpm
 
 ### Setup
-
 ```bash
 git clone https://github.com/TheDarkSkyXD/debug-electron-mcp.git
 cd debug-electron-mcp
-
 npm install
 npm run build
-
-# Run tests
-npm test
-
-# Development mode with auto-rebuild
-npm run dev
 ```
 
-### Testing
-
-The project includes comprehensive test files for React compatibility:
-
+### Running Locally
 ```bash
-# Run React compatibility tests
-cd tests/integration/react-compatibility
-electron test-react-electron.js
+npm run dev                               # stdio mode
+npx tsx src/index.ts --project my-app     # explicit project scope
+npx tsx src/index.ts serve                # HTTP mode
 ```
 
-See [`tests/integration/react-compatibility/README.md`](tests/integration/react-compatibility/README.md) for detailed testing instructions and scenarios.
-
-### React Compatibility
-
-This MCP server has been thoroughly tested with React applications and handles common React patterns correctly:
-
-- **✅ React Event Handling**: Properly handles `preventDefault()` in click handlers
-- **✅ Form Input Detection**: Advanced scoring algorithm works with React-rendered inputs
-- **✅ Component Interaction**: Compatible with React components, hooks, and state management
-
-### Project Structure
-
-```
-src/
-├── handlers.ts      # MCP tool handlers
-├── index.ts         # Server entry point
-├── tools.ts         # Tool definitions
-├── screenshot.ts    # Screenshot functionality
-├── utils/
-│   ├── process.ts   # Process management & DevTools Protocol
-│   ├── logs.ts      # Log management
-│   └── project.ts   # Project scaffolding
-└── schemas/         # JSON schemas for validation
+### Testing
+```bash
+npm test                  # unit tests
+npm run test:react        # integration tests
 ```
 
-## 🔐 Security & Best Practices
-
-- **Sandboxed Execution**: All JavaScript execution is contained within the target Electron app
-- **Path Validation**: Only operates on explicitly provided application paths
-- **Process Isolation**: Each launched app runs in its own process space
-- **No Persistent Access**: No permanent modifications to target applications
-
-## 🤝 Contributing
-
-We welcome contributions! Please see our [Contributing Guide](CONTRIBUTING.md) for details.
-
-**Before reporting issues**: Please use the standardized [`ISSUE_TEMPLATE.md`](ISSUE_TEMPLATE.md) for proper bug reporting format. For React compatibility problems or similar technical issues, also review [`REACT_COMPATIBILITY_ISSUES.md`](REACT_COMPATIBILITY_ISSUES.md) for detailed debugging examples, including proper command examples, error outputs, and reproduction steps.
-
-1. Fork the repository
-2. Create a feature branch (`git checkout -b feature/awesome-feature`)
-3. Commit your changes (`git commit -m 'Add awesome feature'`)
-4. Push to the branch (`git push origin feature/awesome-feature`)
-5. Open a Pull Request
-
-## 📄 License
-
-This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
-
-## 🙌 Credits & Attribution
-
-**Original Author**: [Halil Ural](https://github.com/halilural)
-
-This project is a fork of [halilural/electron-mcp-server](https://github.com/halilural/electron-mcp-server) with enhancements for **Cursor IDE compatibility** and improved stability.
-
-### Forked & Maintained By
-
-- [Antigravity](https://github.com/TheDarkSkyXD) - Cursor IDE integration improvements, bug fixes, and ongoing maintenance
-
-### Key Improvements in This Fork
-
-- ✅ **Cursor IDE Compatibility**: Full integration with Cursor IDE for seamless AI-powered Electron automation
-- ✅ **Enhanced Stability**: Improved error handling and reliability
-- ✅ **Better Documentation**: Added comprehensive guides for local development and troubleshooting
-- ✅ **Scoped Package**: Published as `@debugelectron/electron-mcp-server` on npm
-
-### Contributing to This Fork
-
-We welcome contributions! If you have improvements or bug fixes, please feel free to:
-1. Fork this repository
-2. Create a feature branch
-3. Submit a pull request with your improvements
-
 ---
 
-## ☕ Support
+## Troubleshooting
 
-If this project helped you, consider buying me a coffee! ☕
+**"Target not found" / "No running Electron application"**
+- Check your assigned port with `list_projects()`.
+- Start your Electron app with `--remote-debugging-port=<port>`.
+- Verify: open `http://localhost:<port>/json` in your browser.
 
-[![Ko-fi](https://ko-fi.com/img/githubbutton_sm.svg)](https://ko-fi.com/)
+**"Project 'xyz' is not registered"**
+- This shouldn't happen with auto-detect. If it does, run `register_project({ projectName: "xyz" })`.
+- Check `list_projects()` to see registered projects.
 
-Your support helps me maintain and improve this project. Thank you! 🙏
+**Wrong project detected**
+- The MCP uses your `package.json` name, or the folder name if no package.json exists.
+- To override, use `--project` flag: `"args": ["-y", "@debugelectron/debug-electron-mcp@latest", "--project", "correct-name"]`
 
-## 🙏 Acknowledgments
+**"No free ports available"**
+- Default range is 9222-9322 (100 ports).
+- Free unused ports: `unregister_project({ projectName: "old-app" })`.
 
-- **[Model Context Protocol](https://modelcontextprotocol.io)** - Standardized AI-application interface
-- **[Chrome DevTools Protocol](https://chromedevtools.github.io/devtools-protocol/)** - Universal debugging interface
-- **[Playwright](https://playwright.dev)** - Reliable browser automation
-- **[Electron](https://electronjs.org)** - Cross-platform desktop applications
+**"Selector is empty" error**
+- **Wrong:** `{"command": "click_by_selector", "args": ".btn"}`
+- **Correct:** `{"command": "click_by_selector", "args": {"selector": ".btn"}}`
 
-## 🔗 Links
+---
 
-- **[GitHub Repository](https://github.com/TheDarkSkyXD/electron-mcp-server)**
-- **[NPM Package](https://www.npmjs.com/package/@debugelectron/electron-mcp-server)**
-- **[Original Repository](https://github.com/halilural/electron-mcp-server)** - Original project by Halil Ural
-- **[Model Context Protocol](https://modelcontextprotocol.io)**
-- **[Chrome DevTools Protocol Docs](https://chromedevtools.github.io/devtools-protocol/)**
-- **[Cursor IDE Setup Guide](./CURSOR_SETUP.md)** - Complete setup guide for Cursor IDE integration
-- **[Issue Template](./ISSUE_TEMPLATE.md)** - Standardized bug reporting format
-- **[React Compatibility Issues Documentation](./REACT_COMPATIBILITY_ISSUES.md)** - Technical debugging guide for React applications
+## License
 
----
+MIT License. See [LICENSE](LICENSE) for details.
 
-**Ready to supercharge your Electron development with AI-powered automation?** Install the MCP server and start building smarter workflows today! 🚀
+### Credits
+Forked and maintained by [Antigravity](https://github.com/TheDarkSkyXD), originally based on work by [halilural](https://github.com/halilural).