Superset Electron MCP built on Puppeteer

.mcp.json

@@ -23,6 +23,10 @@
 		"sentry": {
 			"type": "http",
 			"url": "https://mcp.sentry.dev/mcp"
+		},
+		"desktop-automation": {
+			"command": "bun",
+			"args": ["run", "packages/desktop-mcp/src/bin.ts"]
 		}
 	}
 }

apps/desktop/package.json

@@ -52,6 +52,7 @@
 		"@superset/agent": "workspace:*",
 		"@superset/auth": "workspace:*",
 		"@superset/db": "workspace:*",
+		"@superset/desktop-mcp": "workspace:*",
 		"@superset/durable-session": "workspace:*",
 		"@superset/local-db": "workspace:*",
 		"@superset/shared": "workspace:*",

apps/desktop/src/lib/electron-app/factories/app/setup.ts

@@ -82,3 +82,10 @@ PLATFORM.IS_WINDOWS &&
 	);
 
 app.commandLine.appendSwitch("force-color-profile", "srgb");
+
+// Enable CDP for desktop automation MCP (playwright-core connects via this port)
+if (env.NODE_ENV === "development") {
+	const cdpPort = String(process.env.DESKTOP_AUTOMATION_PORT || 9223);
+	app.commandLine.appendSwitch("remote-debugging-port", cdpPort);
+	app.commandLine.appendSwitch("remote-allow-origins", "*");
+}

apps/desktop/src/shared/env.shared.ts

@@ -20,6 +20,7 @@ const envSchema = z.object({
 	DESKTOP_VITE_PORT: z.coerce.number().default(5173),
 	DESKTOP_NOTIFICATIONS_PORT: z.coerce.number().default(5174),
 	ELECTRIC_PORT: z.coerce.number().default(5133),
+	DESKTOP_AUTOMATION_PORT: z.coerce.number().default(9223),
 	// Workspace name for instance isolation
 	SUPERSET_WORKSPACE_NAME: z.string().default("superset"),
 });
@@ -36,6 +37,7 @@ export const env = envSchema.parse({
 	DESKTOP_VITE_PORT: process.env.DESKTOP_VITE_PORT,
 	DESKTOP_NOTIFICATIONS_PORT: process.env.DESKTOP_NOTIFICATIONS_PORT,
 	ELECTRIC_PORT: process.env.ELECTRIC_PORT,
+	DESKTOP_AUTOMATION_PORT: process.env.DESKTOP_AUTOMATION_PORT,
 	SUPERSET_WORKSPACE_NAME: process.env.SUPERSET_WORKSPACE_NAME,
 });
 

packages/desktop-mcp/package.json

@@ -0,0 +1,28 @@
+{
+	"name": "@superset/desktop-mcp",
+	"version": "0.1.0",
+	"private": true,
+	"type": "module",
+	"bin": {
+		"desktop-mcp": "./src/bin.ts"
+	},
+	"exports": {
+		".": {
+			"types": "./src/index.ts",
+			"default": "./src/index.ts"
+		}
+	},
+	"scripts": {
+		"typecheck": "tsc --noEmit --emitDeclarationOnly false"
+	},
+	"dependencies": {
+		"@modelcontextprotocol/sdk": "^1.25.3",
+		"puppeteer-core": "^24.37.3",
+		"zod": "^4.3.5"
+	},
+	"devDependencies": {
+		"@superset/typescript": "workspace:*",
+		"@types/node": "^24.9.1",
+		"typescript": "^5.9.3"
+	}
+}

packages/desktop-mcp/src/bin.ts

@@ -0,0 +1,7 @@
+#!/usr/bin/env node
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { createMcpServer } from "./mcp/index.js";
+
+const server = createMcpServer();
+const transport = new StdioServerTransport();
+await server.connect(transport);

packages/desktop-mcp/src/index.ts

@@ -0,0 +1,13 @@
+export { createMcpServer } from "./mcp/index.js";
+export type {
+	ClickResponse,
+	ConsoleLogEntry,
+	ConsoleLogsResponse,
+	DomElement,
+	DomResponse,
+	EvaluateResponse,
+	NavigateResponse,
+	ScreenshotResponse,
+	TypeResponse,
+	WindowInfoResponse,
+} from "./zod.js";

packages/desktop-mcp/src/mcp/connection/connection-manager.ts

@@ -0,0 +1,59 @@
+import puppeteer, { type Browser, type Page } from "puppeteer-core";
+import { ConsoleCapture } from "../console-capture/index.js";
+import { FocusLock } from "../focus-lock/index.js";
+
+const CDP_PORT = Number(process.env.DESKTOP_AUTOMATION_PORT) || 9223;
+
+/**
+ * Manages a CDP connection to the Electron renderer via puppeteer-core.
+ *
+ * - Lazy connect on first tool call (Electron might not be running yet)
+ * - Auto-reconnect if connection drops (Electron restart/hot reload)
+ * - Re-injects focus lock and console capture on reconnect
+ */
+export class ConnectionManager {
+	private browser: Browser | null = null;
+	private page: Page | null = null;
+
+	readonly consoleCapture = new ConsoleCapture();
+	readonly focusLock = new FocusLock();
+
+	async getPage(): Promise<Page> {
+		if (this.page && this.browser?.connected) {
+			await this.focusLock.inject(this.page);
+			return this.page;
+		}
+		return this.connect();
+	}
+
+	private async connect(): Promise<Page> {
+		this.browser = await puppeteer.connect({
+			browserURL: `http://127.0.0.1:${CDP_PORT}`,
+			protocolTimeout: 60_000,
+			defaultViewport: null,
+		});
+		const pages = await this.browser.pages();
+
+		// Find the actual app page, skipping chrome-extension:// background pages
+		const appPage = pages.find(
+			(p) => !p.url().startsWith("chrome-extension://"),
+		);
+		if (!appPage) {
+			throw new Error(
+				`[desktop-mcp] No app pages found via CDP (found ${pages.length} pages, all extensions)`,
+			);
+		}
+		this.page = appPage;
+
+		this.consoleCapture.attach(this.page);
+		this.focusLock.attach(this.page);
+		await this.focusLock.inject(this.page);
+
+		this.browser.on("disconnected", () => {
+			this.browser = null;
+			this.page = null;
+		});
+
+		return this.page;
+	}
+}

packages/desktop-mcp/src/mcp/connection/index.ts

@@ -0,0 +1 @@
+export { ConnectionManager } from "./connection-manager.js";

packages/desktop-mcp/src/mcp/console-capture/console-capture.ts

@@ -0,0 +1,53 @@
+import type { ConsoleMessage, Page } from "puppeteer-core";
+import type { ConsoleLogEntry } from "../../zod.js";
+
+const LEVEL_MAP: Record<string, number> = {
+	verbose: 0,
+	debug: 0,
+	info: 1,
+	log: 1,
+	warning: 2,
+	warn: 2,
+	error: 3,
+};
+
+export class ConsoleCapture {
+	private logs: ConsoleLogEntry[] = [];
+	private maxSize = 500;
+
+	attach(page: Page) {
+		page.on("console", (msg: ConsoleMessage) => {
+			const level = LEVEL_MAP[msg.type()] ?? 1;
+			const location = msg.location();
+			this.logs.push({
+				level,
+				message: msg.text(),
+				source: location.url ?? "",
+				line: location.lineNumber ?? 0,
+				timestamp: Date.now(),
+			});
+			if (this.logs.length > this.maxSize) this.logs.shift();
+		});
+	}
+
+	getLogs({
+		level,
+		limit,
+	}: {
+		level?: number;
+		limit?: number;
+	}): ConsoleLogEntry[] {
+		let filtered = this.logs;
+		if (level !== undefined) {
+			filtered = filtered.filter((log) => log.level === level);
+		}
+		if (limit !== undefined) {
+			filtered = filtered.slice(-limit);
+		}
+		return filtered;
+	}
+
+	clear() {
+		this.logs = [];
+	}
+}

packages/desktop-mcp/src/mcp/console-capture/index.ts

@@ -0,0 +1 @@
+export { ConsoleCapture } from "./console-capture.js";

packages/desktop-mcp/src/mcp/dom-inspector/dom-inspector.ts

@@ -0,0 +1,92 @@
+/**
+ * JavaScript source to inject into the renderer via page.evaluate().
+ * Walks the DOM and returns a flat list of visible elements with metadata.
+ */
+export const DOM_INSPECTOR_SCRIPT = `function inspectDom({ selector, interactiveOnly }) {
+  const INTERACTIVE_TAGS = new Set([
+    'A', 'BUTTON', 'INPUT', 'SELECT', 'TEXTAREA', 'DETAILS', 'SUMMARY'
+  ]);
+  const INTERACTIVE_ROLES = new Set([
+    'button', 'link', 'checkbox', 'radio', 'tab', 'menuitem',
+    'switch', 'textbox', 'combobox', 'listbox', 'option', 'slider', 'spinbutton'
+  ]);
+
+  const root = selector ? document.querySelector(selector) : document.body;
+  if (!root) return [];
+
+  const elements = [];
+  const walker = document.createTreeWalker(root, NodeFilter.SHOW_ELEMENT);
+
+  let node = walker.currentNode;
+  while (node) {
+    if (node instanceof HTMLElement) {
+      const rect = node.getBoundingClientRect();
+      const style = window.getComputedStyle(node);
+
+      // Skip invisible elements
+      if (rect.width === 0 && rect.height === 0) { node = walker.nextNode(); continue; }
+      if (style.display === 'none' || style.visibility === 'hidden') { node = walker.nextNode(); continue; }
+      if (parseFloat(style.opacity) === 0) { node = walker.nextNode(); continue; }
+
+      const tag = node.tagName.toLowerCase();
+      const role = node.getAttribute('role') || undefined;
+      const testId = node.getAttribute('data-testid') || undefined;
+      const isInteractive = INTERACTIVE_TAGS.has(node.tagName)
+        || INTERACTIVE_ROLES.has(role || '')
+        || node.hasAttribute('onclick')
+        || node.getAttribute('tabindex') !== null;
+
+      if (interactiveOnly && !isInteractive) { node = walker.nextNode(); continue; }
+
+      // Build a unique CSS selector
+      let cssSelector;
+      if (node.id) {
+        cssSelector = '#' + CSS.escape(node.id);
+      } else if (testId) {
+        cssSelector = '[data-testid="' + testId + '"]';
+      } else {
+        const path = [];
+        let el = node;
+        while (el && el !== document.body) {
+          const parent = el.parentElement;
+          if (!parent) break;
+          const siblings = Array.from(parent.children).filter(s => s.tagName === el.tagName);
+          if (siblings.length > 1) {
+            const idx = siblings.indexOf(el) + 1;
+            path.unshift(el.tagName.toLowerCase() + ':nth-of-type(' + idx + ')');
+          } else {
+            path.unshift(el.tagName.toLowerCase());
+          }
+          el = parent;
+        }
+        cssSelector = path.join(' > ');
+      }
+
+      const text = (node.textContent || '').trim().slice(0, 200);
+
+      elements.push({
+        tag,
+        id: node.id || undefined,
+        classes: Array.from(node.classList),
+        text,
+        selector: cssSelector,
+        bounds: {
+          x: Math.round(rect.x),
+          y: Math.round(rect.y),
+          width: Math.round(rect.width),
+          height: Math.round(rect.height),
+        },
+        role,
+        testId,
+        interactive: isInteractive,
+        disabled: node.hasAttribute('disabled'),
+        checked: 'checked' in node ? node.checked : undefined,
+        focused: document.activeElement === node,
+        visible: true,
+      });
+    }
+    node = walker.nextNode();
+  }
+
+  return elements;
+}`;

packages/desktop-mcp/src/mcp/dom-inspector/index.ts

@@ -0,0 +1 @@
+export { DOM_INSPECTOR_SCRIPT } from "./dom-inspector.js";