fix(mcp): prevent test iframe from connecting to MCP and add exec_js_in_test_iframe tool

The embedded Phoenix iframe inside SpecRunner was connecting to MCP
independently, causing instance confusion. Now only the SpecRunner
connects to MCP, and a new exec_js_in_test_iframe tool bridges JS
execution to the iframe when needed.

Author: abose

phoenix-builder-mcp/mcp-tools.js

@@ -383,6 +383,39 @@ export function registerTools(server, processManager, wsControlServer, phoenixDe
         }
     );
 
+    server.tool(
+        "exec_js_in_test_iframe",
+        "Execute JavaScript in the embedded test Phoenix iframe inside the SpecRunner, NOT in the SpecRunner itself. " +
+        "The iframe is usually not present during unit tests, but for other categories tests may spawn it as needed — " +
+        "it can come and go at any time. " +
+        "Code runs async in the iframe's page context with access to the test Phoenix instance's globals " +
+        "(jQuery $, brackets.test.*, etc.). " +
+        "Returns an error if no iframe is present. " +
+        "Use exec_js to control the SpecRunner (run tests, get results); use this tool to inspect the test Phoenix instance.",
+        {
+            code: z.string().describe("JavaScript code to execute in the test Phoenix iframe"),
+            instance: z.string().optional().describe("Target a specific test runner instance by name. Required when multiple instances are connected.")
+        },
+        async ({ code, instance }) => {
+            try {
+                const result = await wsControlServer.requestExecJsInTestIframe(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(
         "run_tests",
         "Run tests in the Phoenix test runner (SpecRunner.html). Reloads the test runner with the specified " +

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

@@ -109,6 +109,19 @@ export function createWSControlServer(port) {
                     break;
                 }
 
+                case "exec_js_in_test_iframe_response": {
+                    const pending7 = pendingRequests.get(msg.id);
+                    if (pending7) {
+                        pendingRequests.delete(msg.id);
+                        if (msg.error) {
+                            pending7.reject(new Error(msg.error));
+                        } else {
+                            pending7.resolve(msg.result);
+                        }
+                    }
+                    break;
+                }
+
                 case "run_tests_response": {
                     const pendingRt = pendingRequests.get(msg.id);
                     if (pendingRt) {
@@ -412,6 +425,41 @@ export function createWSControlServer(port) {
         });
     }
 
+    function requestExecJsInTestIframe(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_in_test_iframe request timed out (30s)"));
+            }, 30000);
+
+            pendingRequests.set(id, {
+                resolve: (data) => {
+                    clearTimeout(timeout);
+                    resolve(data);
+                },
+                reject: (err) => {
+                    clearTimeout(timeout);
+                    reject(err);
+                }
+            });
+
+            client.ws.send(JSON.stringify({ type: "exec_js_in_test_iframe_request", id, code }));
+        });
+    }
+
     function requestRunTests(category, spec, instanceName) {
         return new Promise((resolve, reject) => {
             const resolved = _resolveClient(instanceName);
@@ -538,6 +586,7 @@ export function createWSControlServer(port) {
         requestLogs,
         requestExecJs,
         requestExecJsLivePreview,
+        requestExecJsInTestIframe,
         requestRunTests,
         requestTestResults,
         getBrowserLogs,

src/phoenix-builder/phoenix-builder-boot.js

@@ -33,6 +33,13 @@
     if (!window.AppConfig || AppConfig.config.environment !== "dev") {
         return;
     }
+    // Skip MCP in test windows (the embedded Phoenix iframe inside SpecRunner).
+    // Only the SpecRunner itself and the normal Phoenix app should connect to MCP.
+    // Phoenix.isTestWindow is true for both SpecRunner and the test iframe,
+    // but Phoenix.isSpecRunnerWindow is only true for the SpecRunner itself.
+    if (window.Phoenix && window.Phoenix.isTestWindow && !window.Phoenix.isSpecRunnerWindow) {
+        return;
+    }
 
     // --- Constants ---
     const LOG_TO_CONSOLE_KEY = "logToConsole";

test/phoenix-test-runner-mcp.js

@@ -185,4 +185,44 @@
         };
     }
 
+    // --- exec_js_in_test_iframe_request ---
+    // When the SpecRunner has an embedded test iframe, forward exec_js to it
+    // so MCP tools can operate on the test Phoenix instance inside the iframe.
+    // Falls back to the SpecRunner context if no iframe is present (e.g. unit tests).
+    builder.registerHandler("exec_js_in_test_iframe_request", function (msg) {
+        var iframe = document.querySelector(".phoenixIframe");
+        if (!iframe || !iframe.contentWindow) {
+            builder.sendMessage({
+                type: "exec_js_in_test_iframe_response",
+                id: msg.id,
+                error: "No test iframe present. The embedded Phoenix instance is not currently loaded."
+            });
+            return;
+        }
+        var targetWindow = iframe.contentWindow;
+        // Create the async function in the target window's context so globals
+        // like $, brackets, etc. resolve to the iframe's scope.
+        var AsyncFunction = targetWindow.eval("(async function(){}).constructor");
+        var fn = new AsyncFunction(msg.code);
+        fn().then(function (result) {
+            var text;
+            try {
+                text = (result !== undefined && result !== null) ? JSON.stringify(result) : "(undefined)";
+            } catch (e) {
+                text = String(result);
+            }
+            builder.sendMessage({
+                type: "exec_js_in_test_iframe_response",
+                id: msg.id,
+                result: text
+            });
+        }).catch(function (err) {
+            builder.sendMessage({
+                type: "exec_js_in_test_iframe_response",
+                id: msg.id,
+                error: (err && err.stack) || (err && err.message) || String(err)
+            });
+        });
+    });
+
 }());