electron-dev-bridge 0.1.0

package/dist/utils/load-config.js

@@ -0,0 +1,17 @@
+import { pathToFileURL } from 'node:url';
+/**
+ * Load an electron-mcp config file, with TypeScript support via tsx.
+ */
+export async function loadConfig(configPath) {
+    let mod;
+    if (configPath.endsWith('.ts')) {
+        // Use tsx's tsImport for TypeScript configs
+        const { tsImport } = await import('tsx/esm/api');
+        mod = await tsImport(configPath, import.meta.url);
+    }
+    else {
+        // Standard import for .js/.mjs configs
+        mod = await import(pathToFileURL(configPath).href);
+    }
+    return mod.default;
+}

package/package.json

@@ -0,0 +1,75 @@
+{
+  "name": "electron-dev-bridge",
+  "version": "0.1.0",
+  "description": "Expose Electron IPC handlers as MCP tools for Claude Code, with 22 built-in CDP tools for DOM automation",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "bin": {
+    "electron-mcp": "dist/cli/index.js"
+  },
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch",
+    "test": "node --test dist/**/*.test.js",
+    "lint": "tsc --noEmit"
+  },
+  "keywords": [
+    "electron",
+    "mcp",
+    "model-context-protocol",
+    "claude",
+    "claude-code",
+    "cdp",
+    "chrome-devtools-protocol",
+    "ipc",
+    "testing",
+    "automation",
+    "desktop-app"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/nicholasgriffintn/electron-dev-bridge.git"
+  },
+  "bugs": {
+    "url": "https://github.com/nicholasgriffintn/electron-dev-bridge/issues"
+  },
+  "homepage": "https://github.com/nicholasgriffintn/electron-dev-bridge#readme",
+  "author": "",
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.12.1",
+    "chrome-remote-interface": "^0.33.2",
+    "tsx": "^4.19.0",
+    "zod-to-json-schema": "^3.24.5"
+  },
+  "peerDependencies": {
+    "zod": "^3.0.0"
+  },
+  "peerDependenciesMeta": {
+    "zod": {
+      "optional": true
+    }
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "files": [
+    "dist",
+    "skills",
+    "LICENSE",
+    "!dist/**/*.test.js",
+    "!dist/**/*.test.d.ts"
+  ],
+  "license": "MIT",
+  "devDependencies": {
+    "@types/chrome-remote-interface": "^0.33.0",
+    "@types/node": "^25.3.2",
+    "typescript": "^5.9.3"
+  }
+}

package/skills/electron-app-dev/SKILL.md

@@ -0,0 +1,140 @@
+---
+name: electron-app-dev
+description: >
+  Develop and automate Electron apps using the electron-dev-bridge bridge.
+  Trigger on: Electron app, desktop app, UI automation, DOM inspection,
+  IPC handler, screenshot, BrowserWindow, webContents, CDP tools,
+  electron-mcp, preload script, contextBridge.
+---
+
+# Electron App Development with electron-dev-bridge
+
+Use the MCP bridge to connect, inspect, interact with, and screenshot your Electron app directly from Claude Code.
+
+## Prerequisites
+
+1. Install: `npm install electron-dev-bridge`
+2. Generate config: `npx electron-mcp init`
+3. Register: `npx electron-mcp register`
+4. Start your app with `--remote-debugging-port=9229`
+
+## Connecting
+
+```
+# Launch and connect in one step
+electron_launch  appPath="/path/to/{YOUR_APP}"
+
+# Or connect to an already-running app (uses the port from your config)
+electron_connect
+```
+
+Always connect before using any other tools.
+
+## Tool Reference
+
+### Connection
+| Tool | Use for |
+|------|---------|
+| `electron_launch` | Launch app with debug port and connect |
+| `electron_connect` | Connect to running app |
+
+### DOM Queries
+| Tool | Use for |
+|------|---------|
+| `electron_query_selector` | Find one element by CSS selector |
+| `electron_query_selector_all` | Find all matching elements (max 50) |
+| `electron_find_by_text` | Find elements by visible text content |
+| `electron_find_by_role` | Find elements by ARIA role |
+| `electron_get_accessibility_tree` | Full a11y tree with roles and names |
+
+### Interaction
+| Tool | Use for |
+|------|---------|
+| `electron_click` | Click by selector or coordinates |
+| `electron_type_text` | Type into input (provide `selector` to auto-focus) |
+| `electron_press_key` | Press Enter, Tab, Escape, arrows, etc. |
+| `electron_select_option` | Select dropdown option by value or text |
+
+### State Reading
+| Tool | Use for |
+|------|---------|
+| `electron_get_text` | Get innerText of element |
+| `electron_get_value` | Get input/textarea/select value |
+| `electron_get_attribute` | Get specific attribute |
+| `electron_get_bounding_box` | Get element position and size |
+| `electron_get_url` | Get current page URL |
+
+### Navigation & Viewport
+| Tool | Use for |
+|------|---------|
+| `electron_wait_for_selector` | Wait for element to appear (default 5s) |
+| `electron_set_viewport` | Override viewport metrics for responsive testing (`width`, `height` required) |
+| `electron_scroll` | Scroll page or element (`direction`: up/down/left/right, `amount`: pixels, `selector`: optional) |
+
+### Screenshots & Visual
+| Tool | Use for |
+|------|---------|
+| `electron_screenshot` | Capture full page or element |
+| `electron_compare_screenshots` | Byte-level diff of two screenshots (returns `diffPercent`) |
+| `electron_highlight_element` | Outline element in red for 3 seconds |
+
+## Selector Strategy (priority order)
+
+1. `[data-testid="..."]` -- most stable
+2. `[role="..."]`, `[aria-label="..."]` -- semantic
+3. `.bem-class-name` -- reasonably stable
+4. Element hierarchy -- last resort
+
+## Waiting Pattern
+
+Always wait before interacting or capturing:
+
+```
+electron_wait_for_selector  selector=".content-loaded"  timeout=10000
+electron_screenshot
+```
+
+Never use arbitrary sleep/delays.
+
+## IPC Tools
+
+If the app uses electron-dev-bridge with configured IPC handlers, tools are named by replacing colons with underscores:
+
+| IPC channel | MCP tool name | Preload path |
+|-------------|---------------|--------------|
+| `{domain}:{action}` | `{domain}_{action}` | `window.electronAPI.{domain}.{action}` |
+
+Call IPC tools directly by name once the server is registered. Tool names depend on your app's config — e.g., `profiles_query`, `settings_get`.
+
+## Playbook: Build & Verify
+
+1. Make code changes
+2. `electron_launch` (or restart the app)
+3. `electron_wait_for_selector` on the changed element
+4. `electron_screenshot` to capture current state
+5. Evaluate the screenshot visually
+6. If issues: fix code, restart, re-verify
+
+## Playbook: Explore App Structure
+
+1. `electron_connect`
+2. `electron_get_accessibility_tree  maxDepth=5` to see the component hierarchy
+3. `electron_query_selector_all  selector="[data-testid]"` to find test hooks
+4. `electron_screenshot` for visual context
+5. Use findings to plan automation or testing
+
+## Playbook: Call IPC Handlers
+
+1. `electron_connect`
+2. Call the IPC tool directly, e.g. `profiles_query  query="test"`
+3. Inspect the returned JSON
+4. Use `electron_screenshot` to verify UI updated
+
+## Screenshot Evaluation Checklist
+
+When reviewing a screenshot, check:
+- Layout: positioning, overlaps, overflow, alignment
+- Text: visibility, truncation, correct content
+- Colors: contrast, theme consistency
+- States: hover, focus, disabled, loading, error, empty
+- Responsiveness: behavior at current viewport size

package/skills/electron-debugging/SKILL.md

@@ -0,0 +1,203 @@
+---
+name: electron-debugging
+description: >
+  Debug and troubleshoot Electron apps via electron-dev-bridge bridge tools.
+  Trigger on: debug, bug, broken, not working, UI issue, element not found,
+  blank screen, can't connect, crash, stale, timeout, click not working,
+  missing element, wrong text, layout broken.
+---
+
+# Electron App Debugging with electron-dev-bridge
+
+Systematic debugging workflows for Electron apps using the MCP bridge.
+
+## Diagnostic Flowchart
+
+```
+Problem reported
+  |
+  +-- Can you connect?
+  |     NO  --> See "Connection Troubleshooting"
+  |     YES
+  |
+  +-- Take screenshot. Is the UI visible?
+  |     NO  --> See "Blank Screen / Loading Issues"
+  |     YES
+  |
+  +-- Is the expected element present?
+  |     NO  --> See "Element Not Found"
+  |     YES
+  |
+  +-- Does interaction work?
+  |     NO  --> See "Interaction Failures"
+  |     YES
+  |
+  +-- Is the displayed content correct?
+        NO  --> See "Wrong Content / State"
+        YES --> Issue may be intermittent. Add waits and retry.
+```
+
+## Connection Troubleshooting
+
+**Symptom:** `electron_connect` or `electron_launch` fails.
+
+```
+# Step 1: Verify the app is running with debug port
+# (run in terminal)
+lsof -i :9229
+
+# Step 2: If no process on port, launch with debug flag
+electron_launch  appPath="/path/to/{YOUR_APP}"
+
+# Step 3: If port is in use by another process, use a different port
+electron_connect  port=9230
+```
+
+| Error | Cause | Fix |
+|-------|-------|-----|
+| Connection refused | App not running or no debug port | Start app with `--remote-debugging-port=9229` |
+| Port already in use | Another process on 9229 | Kill the process or use `electron_connect port=9230` |
+| Target not found | App has no renderer window | Ensure a BrowserWindow is created |
+| Connection lost mid-session | App crashed or reloaded | `electron_connect` to reconnect |
+
+## Blank Screen / Loading Issues
+
+**Symptom:** Screenshot shows blank or loading state.
+
+```
+# 1. Screenshot to confirm state
+electron_screenshot
+
+# 2. Check the URL -- is the app loading the right page?
+electron_get_url
+
+# 3. Wait for a known root element
+electron_wait_for_selector  selector="{YOUR_APP_ROOT}"  timeout=15000
+
+# 4. If timeout: check the accessibility tree for any content
+electron_get_accessibility_tree  maxDepth=3
+
+# 5. Re-screenshot after waiting
+electron_screenshot
+```
+
+**Common causes:**
+- App still loading (increase timeout)
+- Wrong URL loaded (check `electron_get_url`)
+- JavaScript error blocking render (check app console logs)
+- Missing preload script (app can't access IPC)
+
+## Element Not Found
+
+**Symptom:** `electron_query_selector` returns no match.
+
+```
+# 1. Verify what IS on the page
+electron_get_accessibility_tree  maxDepth=5
+
+# 2. Search by text instead of selector
+electron_find_by_text  text="Submit"
+
+# 3. Search by role
+electron_find_by_role  role="button"
+
+# 4. Try a broader selector
+electron_query_selector_all  selector="button"
+
+# 5. Check if element is in a different part of the tree
+electron_query_selector_all  selector="iframe"
+# If iframes exist, the element may be inside one
+
+# 6. Highlight a similar element to verify targeting
+electron_highlight_element  selector=".some-visible-element"
+electron_screenshot
+```
+
+**Common causes:**
+- Selector typo or stale selector (class names changed)
+- Element not yet rendered (add `electron_wait_for_selector`)
+- Element inside shadow DOM or iframe
+- Element conditionally rendered (check app state)
+
+## Interaction Failures
+
+**Symptom:** `electron_click` or `electron_type_text` has no visible effect.
+
+```
+# 1. Verify the element exists and is visible
+electron_get_bounding_box  selector="{TARGET_SELECTOR}"
+# Check: width/height > 0, coordinates are within viewport
+
+# 2. Check if element is obscured by an overlay
+electron_screenshot
+# Look for modals, tooltips, or overlapping elements
+
+# 3. Check element attributes
+electron_get_attribute  selector="{TARGET_SELECTOR}"  attribute="disabled"
+electron_get_attribute  selector="{TARGET_SELECTOR}"  attribute="readonly"
+
+# 4. Try clicking by coordinates instead
+electron_get_bounding_box  selector="{TARGET_SELECTOR}"
+# Use returned x + width/2, y + height/2 as click coordinates
+electron_click  x=150  y=200
+
+# 5. For type_text: ensure element is focused
+electron_click  selector="{TARGET_SELECTOR}"
+electron_type_text  text="test input"
+```
+
+| Problem | Cause | Fix |
+|---------|-------|-----|
+| Click no effect | Overlay blocking | Dismiss the overlay first |
+| Click no effect | Element disabled | Check and resolve disabled state |
+| Click no effect | Wrong coordinates | Use `electron_get_bounding_box` to verify |
+| Type not appearing | Element not focused | Click element first, then type |
+| Type not appearing | Input is readonly | Check `readonly`/`disabled` attributes |
+| Key press ignored | Wrong key name | Supported: `Enter`, `Tab`, `Escape`, `Backspace`, `Delete`, `ArrowUp`, `ArrowDown`, `ArrowLeft`, `ArrowRight`, `Home`, `End`, `Space` |
+
+## Wrong Content / State
+
+**Symptom:** UI shows incorrect text, values, or layout.
+
+```
+# 1. Read the actual content
+electron_get_text  selector="{TARGET_SELECTOR}"
+electron_get_value  selector="{INPUT_SELECTOR}"
+
+# 2. Screenshot for visual comparison
+electron_screenshot
+
+# 3. Check the accessibility tree for the full component context
+electron_get_accessibility_tree  maxDepth=5
+
+# 4. Highlight the problematic element
+electron_highlight_element  selector="{TARGET_SELECTOR}"
+electron_screenshot
+```
+
+## Recovery Steps
+
+```
+# 1. Screenshot current state
+electron_screenshot
+
+# 2. Reconnect if stale
+electron_connect
+
+# 3. Check URL
+electron_get_url
+
+# 4. If app is in bad state, restart
+electron_launch  appPath="/path/to/{YOUR_APP}"
+electron_wait_for_selector  selector="{YOUR_APP_ROOT}"  timeout=15000
+```
+
+## Common Error Patterns
+
+| Error | Cause | Fix |
+|-------|-------|-----|
+| "No target found" | No renderer connected | `electron_connect` |
+| "Selector not found" | Bad CSS selector | Use `electron_get_accessibility_tree` |
+| "Timeout waiting" | Element didn't appear | Increase timeout or check conditional rendering |
+| "Cannot find context" | CDP session expired | `electron_connect` again |
+| "Execution context destroyed" | Page navigated | Wait for new page, retry |

package/skills/electron-e2e-testing/SKILL.md

@@ -0,0 +1,181 @@
+---
+name: electron-e2e-testing
+description: >
+  End-to-end testing workflows for Electron apps via electron-dev-bridge.
+  Trigger on: test, e2e, end-to-end, regression, form testing,
+  UI verification, test flow, smoke test, integration test,
+  visual regression, form fill, submit, assertion.
+---
+
+# Electron E2E Testing with electron-dev-bridge
+
+Structured test patterns for verifying Electron app behavior using the MCP bridge tools.
+
+## Test Pattern: Launch, Wait, Act, Assert, Screenshot
+
+Every test follows this structure:
+
+```
+1. electron_launch / electron_connect     -- establish connection
+2. electron_wait_for_selector             -- wait for ready state
+3. electron_click / electron_type_text    -- perform actions
+4. electron_wait_for_selector             -- wait for result
+5. electron_get_text / electron_get_value -- assert expected state
+6. electron_screenshot                    -- capture evidence
+```
+
+## Playbook: Basic Interaction Test
+
+**Goal:** Verify a button click produces the expected result.
+
+```
+# 1. Connect
+electron_connect
+
+# 2. Wait for the target element
+electron_wait_for_selector  selector="[data-testid='submit-btn']"  timeout=5000
+
+# 3. Click
+electron_click  selector="[data-testid='submit-btn']"
+
+# 4. Wait for the result
+electron_wait_for_selector  selector="[data-testid='result-message']"  timeout=5000
+
+# 5. Assert
+electron_get_text  selector="[data-testid='result-message']"
+# Expected: "Success" or similar
+
+# 6. Evidence
+electron_screenshot
+```
+
+**Pass criteria:** `electron_get_text` returns the expected string. Screenshot shows correct UI state.
+
+## Playbook: Form Fill & Submit
+
+**Goal:** Complete a form and verify submission.
+
+```
+# 1. Connect and wait for form
+electron_connect
+electron_wait_for_selector  selector="form"
+
+# 2. Discover fields
+electron_get_accessibility_tree  maxDepth=5
+
+# 3. Fill text inputs
+electron_type_text  selector="#name"  text="Jane Doe"
+electron_type_text  selector="#email"  text="jane@example.com"
+
+# 4. Fill dropdown
+electron_select_option  selector="#role"  value="admin"
+
+# 5. Screenshot before submit (evidence of filled state)
+electron_screenshot
+
+# 6. Submit
+electron_click  selector="[type='submit']"
+
+# 7. Wait for result
+electron_wait_for_selector  selector=".success-message"  timeout=10000
+
+# 8. Assert
+electron_get_text  selector=".success-message"
+# Expected: contains "submitted" or "saved"
+
+# 9. Screenshot after submit
+electron_screenshot
+```
+
+**Pass criteria:** Success message appears. Both before/after screenshots look correct.
+
+## Playbook: Visual Regression
+
+**Goal:** Detect unintended UI changes after a code modification.
+
+```
+# Phase 1: Capture baseline (before changes)
+electron_connect
+electron_wait_for_selector  selector="{YOUR_APP_ROOT}"
+electron_screenshot
+# Save as baseline -- note the returned file path
+
+# Phase 2: After making code changes, restart app
+electron_launch  appPath="/path/to/{YOUR_APP}"
+electron_wait_for_selector  selector="{YOUR_APP_ROOT}"
+electron_screenshot
+# Save as current -- note the returned file path
+
+# Phase 3: Compare
+electron_compare_screenshots  pathA="baseline.png"  pathB="current.png"
+# Returns: { identical: false, diffPercent: 0.5, totalBytes: 120000, diffBytes: 600 }
+```
+
+**Thresholds** (note: this is a byte-level diff, not pixel-aware):
+- `< 1%` diff: likely acceptable (compression variance, anti-aliasing)
+- `1-5%` diff: review the screenshot -- may be intentional
+- `> 5%` diff: likely a regression, investigate
+
+## Playbook: Multi-Page Flow
+
+**Goal:** Test a workflow spanning multiple views/pages.
+
+```
+# Step 1: Login page
+electron_connect
+electron_wait_for_selector  selector="#login-form"
+electron_type_text  selector="#username"  text="testuser"
+electron_type_text  selector="#password"  text="testpass"
+electron_click  selector="[data-testid='login-btn']"
+electron_screenshot
+
+# Step 2: Dashboard (after login)
+electron_wait_for_selector  selector="[data-testid='dashboard']"  timeout=10000
+electron_get_text  selector="[data-testid='welcome-msg']"
+# Assert: contains "testuser"
+electron_screenshot
+
+# Step 3: Navigate to settings
+electron_click  selector="[data-testid='settings-link']"
+electron_wait_for_selector  selector="[data-testid='settings-page']"
+electron_screenshot
+
+# Step 4: Verify and return
+electron_get_url
+# Assert: URL contains "/settings"
+```
+
+**Pass criteria:** Each step transitions correctly. No errors. URLs and text match expectations.
+
+## Key Practices
+
+### Always wait, never sleep
+Use `electron_wait_for_selector` between every action that changes the UI. This eliminates race conditions and makes tests deterministic.
+
+### Screenshot at checkpoints
+Capture screenshots at key moments: before actions, after actions, on errors. These serve as test evidence.
+
+### Use data-testid selectors
+Prefer `[data-testid="..."]` selectors for test stability. They survive refactors and style changes.
+
+### Assert with get_text / get_value
+Use `electron_get_text` and `electron_get_value` to verify expected content, not just visual inspection.
+
+### Handle timeouts as failures
+If `electron_wait_for_selector` times out, the element didn't appear. This is a test failure -- report it with the last screenshot for debugging context.
+
+## IPC-Based Assertions
+
+When the app has IPC tools configured, use them for deeper assertions. Tool names depend on your app's config — these are examples:
+
+```
+# After a form submit, verify via IPC (example tool names)
+profiles_query  query="Jane Doe"
+# Assert: returned array contains the submitted profile
+
+# Check app state directly (example tool name)
+session_getStatus
+# Assert: status is "authenticated"
+```
+
+IPC tools give you backend verification alongside UI assertions.