feat: phoenix builder mcp server comunication with live preview

Author: abose

phoenix-builder-mcp/mcp-tools.js

@@ -340,6 +340,37 @@ export function registerTools(server, processManager, wsControlServer, phoenixDe
         }
     );
 
+    server.tool(
+        "exec_js_in_live_preview",
+        "Execute JavaScript in the live preview iframe (the page being previewed), NOT in Phoenix itself. " +
+        "Auto-opens the live preview panel if it is not already visible. " +
+        "Code is evaluated via eval() in the global scope of the previewed page. " +
+        "Note: eval() is synchronous — async/await is NOT supported. " +
+        "Use this to inspect or manipulate the user's live-previewed web page (e.g. document.title, DOM queries).",
+        {
+            code: z.string().describe("JavaScript code to execute in the live preview iframe"),
+            instance: z.string().optional().describe("Target a specific Phoenix instance by name (e.g. 'Phoenix-a3f2'). Required when multiple instances are connected.")
+        },
+        async ({ code, instance }) => {
+            try {
+                const result = await wsControlServer.requestExecJsLivePreview(code, instance);
+                return {
+                    content: [{
+                        type: "text",
+                        text: result !== undefined ? String(result) : "(undefined)"
+                    }]
+                };
+            } catch (err) {
+                return {
+                    content: [{
+                        type: "text",
+                        text: JSON.stringify({ error: err.message })
+                    }]
+                };
+            }
+        }
+    );
+
     server.tool(
         "get_phoenix_status",
         "Check the status of the Phoenix process and WebSocket connection.",

phoenix-builder-mcp/ws-control-server.js

@@ -96,6 +96,19 @@ export function createWSControlServer(port) {
                     break;
                 }
 
+                case "exec_js_live_preview_response": {
+                    const pending6 = pendingRequests.get(msg.id);
+                    if (pending6) {
+                        pendingRequests.delete(msg.id);
+                        if (msg.error) {
+                            pending6.reject(new Error(msg.error));
+                        } else {
+                            pending6.resolve(msg.result);
+                        }
+                    }
+                    break;
+                }
+
                 case "reload_response": {
                     const pending3 = pendingRequests.get(msg.id);
                     if (pending3) {
@@ -342,6 +355,41 @@ export function createWSControlServer(port) {
         });
     }
 
+    function requestExecJsLivePreview(code, instanceName) {
+        return new Promise((resolve, reject) => {
+            const resolved = _resolveClient(instanceName);
+            if (resolved.error) {
+                reject(new Error(resolved.error));
+                return;
+            }
+
+            const { client } = resolved;
+            if (client.ws.readyState !== 1) {
+                reject(new Error("Phoenix client \"" + resolved.name + "\" is not connected"));
+                return;
+            }
+
+            const id = ++requestIdCounter;
+            const timeout = setTimeout(() => {
+                pendingRequests.delete(id);
+                reject(new Error("exec_js_live_preview request timed out (60s)"));
+            }, 60000);
+
+            pendingRequests.set(id, {
+                resolve: (data) => {
+                    clearTimeout(timeout);
+                    resolve(data);
+                },
+                reject: (err) => {
+                    clearTimeout(timeout);
+                    reject(err);
+                }
+            });
+
+            client.ws.send(JSON.stringify({ type: "exec_js_live_preview_request", id, code }));
+        });
+    }
+
     function getBrowserLogs(sinceLast, instanceName) {
         const resolved = _resolveClient(instanceName);
         if (resolved.error) {
@@ -393,6 +441,7 @@ export function createWSControlServer(port) {
         requestReload,
         requestLogs,
         requestExecJs,
+        requestExecJsLivePreview,
         getBrowserLogs,
         clearBrowserLogs,
         isClientConnected,

src/phoenix-builder/phoenix-builder-client.js

@@ -27,6 +27,9 @@ define(function (require, exports, module) {
 
     const CommandManager = require("command/CommandManager");
     const Commands = require("command/Commands");
+    const LiveDevProtocol = require("LiveDevelopment/MultiBrowserImpl/protocol/LiveDevProtocol");
+    const LiveDevMain = require("LiveDevelopment/main");
+    const WorkspaceManager = require("view/WorkspaceManager");
 
     const boot = window._phoenixBuilder || null;
 
@@ -87,10 +90,90 @@ define(function (require, exports, module) {
             });
     }
 
+    function _handleExecJsLivePreviewRequest(msg) {
+        function _evaluate() {
+            LiveDevProtocol.evaluate(msg.code)
+                .done(function (evalResult) {
+                    boot.sendMessage({
+                        type: "exec_js_live_preview_response",
+                        id: msg.id,
+                        result: JSON.stringify(evalResult)
+                    });
+                })
+                .fail(function (err) {
+                    boot.sendMessage({
+                        type: "exec_js_live_preview_response",
+                        id: msg.id,
+                        error: (err && err.message) || String(err) || "evaluate() failed"
+                    });
+                });
+        }
+
+        // Fast path: already connected
+        if (LiveDevProtocol.getConnectionIds().length > 0) {
+            _evaluate();
+            return;
+        }
+
+        // Need to ensure live preview is open and connected
+        const panel = WorkspaceManager.getPanelForID("live-preview-panel");
+        if (!panel || !panel.isVisible()) {
+            CommandManager.execute("file.liveFilePreview");
+        } else {
+            LiveDevMain.openLivePreview();
+        }
+
+        // Wait for a live preview connection (up to 30s)
+        const TIMEOUT = 30000;
+        const POLL_INTERVAL = 500;
+        let settled = false;
+        let pollTimer = null;
+
+        function cleanup() {
+            settled = true;
+            if (pollTimer) {
+                clearInterval(pollTimer);
+                pollTimer = null;
+            }
+            LiveDevProtocol.off("ConnectionConnect.execJsLivePreview");
+        }
+
+        const timeoutTimer = setTimeout(function () {
+            if (settled) { return; }
+            cleanup();
+            boot.sendMessage({
+                type: "exec_js_live_preview_response",
+                id: msg.id,
+                error: "Timed out waiting for live preview connection (30s)"
+            });
+        }, TIMEOUT);
+
+        function onConnected() {
+            if (settled) { return; }
+            cleanup();
+            clearTimeout(timeoutTimer);
+            _evaluate();
+        }
+
+        LiveDevProtocol.on("ConnectionConnect.execJsLivePreview", onConnected);
+
+        // Safety-net poll in case the event was missed
+        pollTimer = setInterval(function () {
+            if (settled) {
+                clearInterval(pollTimer);
+                return;
+            }
+            if (LiveDevProtocol.getConnectionIds().length > 0) {
+                onConnected();
+            }
+        }, POLL_INTERVAL);
+    }
+
     // Register handlers on the boot module
     if (boot) {
         boot.registerHandler("screenshot_request", _handleScreenshotRequest);
         boot.registerHandler("reload_request", _handleReloadRequest);
+        boot.registerHandler("exec_js_live_preview_request", _handleExecJsLivePreviewRequest);
     }
 
     exports.connect = function (url) { if (boot) { boot.connect(url); } };