feat: phoenix builder mcp for phoenix to build itself

Author: abose

.gitignore

@@ -15,6 +15,9 @@ Thumbs.db
 /test/pro-test-suite.js
 /src/extensionsIntegrated/phoenix-pro
 
+# ignore node_modules inside phoenix-builder-mcp
+/phoenix-builder-mcp/node_modules
+
 # ignore node_modules inside src
 /src/node_modules
 /src-node/node_modules

.mcp.json

@@ -0,0 +1,11 @@
+{
+    "mcpServers": {
+        "phoenix-builder": {
+            "command": "node",
+            "args": ["phoenix-builder-mcp/index.js"],
+            "env": {
+                "PHOENIX_DESKTOP_PATH": "../phoenix-desktop"
+            }
+        }
+    }
+}

package-lock.json

@@ -42,6 +42,7 @@
         "lmdb": "^3.5.1"
     },
     "scripts": {
+        "postinstall": "npm install --prefix phoenix-builder-mcp",
         "lint": "eslint --quiet src test",
         "lint:fix": "eslint --quiet --fix src test",
         "prepare": "husky install",

package.json

@@ -0,0 +1,39 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { createWSControlServer } from "./ws-control-server.js";
+import { createProcessManager } from "./process-manager.js";
+import { registerTools } from "./mcp-tools.js";
+import { fileURLToPath } from "url";
+import path from "path";
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+
+const wsPort = parseInt(process.env.PHOENIX_MCP_WS_PORT || "38571", 10);
+const phoenixDesktopPath = process.env.PHOENIX_DESKTOP_PATH
+    || path.resolve(__dirname, "../../phoenix-desktop");
+
+const wsControlServer = createWSControlServer(wsPort);
+const processManager = createProcessManager();
+
+const server = new McpServer({
+    name: "phoenix-builder",
+    version: "1.0.0"
+});
+
+registerTools(server, processManager, wsControlServer, phoenixDesktopPath);
+
+const transport = new StdioServerTransport();
+await server.connect(transport);
+
+process.on("SIGINT", async () => {
+    await processManager.stop();
+    wsControlServer.close();
+    process.exit(0);
+});
+
+process.on("SIGTERM", async () => {
+    await processManager.stop();
+    wsControlServer.close();
+    process.exit(0);
+});

phoenix-builder-mcp/index.js

@@ -0,0 +1,32 @@
+const MAX_ENTRIES = 10000;
+
+export class LogBuffer {
+    constructor() {
+        this._entries = [];
+        this._readIndex = 0;
+    }
+
+    push(entry) {
+        this._entries.push(entry);
+        if (this._entries.length > MAX_ENTRIES) {
+            const overflow = this._entries.length - MAX_ENTRIES;
+            this._entries.splice(0, overflow);
+            this._readIndex = Math.max(0, this._readIndex - overflow);
+        }
+    }
+
+    getAll() {
+        return this._entries.slice();
+    }
+
+    getSinceLastRead() {
+        const newEntries = this._entries.slice(this._readIndex);
+        this._readIndex = this._entries.length;
+        return newEntries;
+    }
+
+    clear() {
+        this._entries = [];
+        this._readIndex = 0;
+    }
+}

phoenix-builder-mcp/log-buffer.js

@@ -0,0 +1,228 @@
+import { z } from "zod";
+
+export function registerTools(server, processManager, wsControlServer, phoenixDesktopPath) {
+    server.tool(
+        "start_phoenix",
+        "Start the Phoenix Code desktop app (Electron). Launches npm run serve:electron in the phoenix-desktop directory.",
+        {},
+        async () => {
+            try {
+                if (processManager.isRunning()) {
+                    return {
+                        content: [{
+                            type: "text",
+                            text: JSON.stringify({
+                                success: false,
+                                error: "Phoenix is already running",
+                                pid: processManager.getPid()
+                            })
+                        }]
+                    };
+                }
+                const result = await processManager.start(phoenixDesktopPath);
+                return {
+                    content: [{
+                        type: "text",
+                        text: JSON.stringify({
+                            success: true,
+                            pid: result.pid,
+                            wsPort: wsControlServer.getPort()
+                        })
+                    }]
+                };
+            } catch (err) {
+                return {
+                    content: [{
+                        type: "text",
+                        text: JSON.stringify({ success: false, error: err.message })
+                    }]
+                };
+            }
+        }
+    );
+
+    server.tool(
+        "stop_phoenix",
+        "Stop the running Phoenix Code desktop app.",
+        {},
+        async () => {
+            try {
+                const result = await processManager.stop();
+                return {
+                    content: [{
+                        type: "text",
+                        text: JSON.stringify(result)
+                    }]
+                };
+            } catch (err) {
+                return {
+                    content: [{
+                        type: "text",
+                        text: JSON.stringify({ success: false, error: err.message })
+                    }]
+                };
+            }
+        }
+    );
+
+    server.tool(
+        "get_terminal_logs",
+        "Get stdout/stderr output from the Electron process. By default returns new logs since last call; set clear=true to get all logs and clear the buffer.",
+        { clear: z.boolean().default(false).describe("If true, return all logs and clear the buffer. If false, return only new logs since last read.") },
+        async ({ clear }) => {
+            let logs;
+            if (clear) {
+                logs = processManager.getTerminalLogs(false);
+                processManager.clearTerminalLogs();
+            } else {
+                logs = processManager.getTerminalLogs(true);
+            }
+            const text = logs.map(e => `[${e.stream}] ${e.text}`).join("");
+            return {
+                content: [{
+                    type: "text",
+                    text: text || "(no terminal logs)"
+                }]
+            };
+        }
+    );
+
+    server.tool(
+        "get_browser_console_logs",
+        "Get console logs forwarded from the Phoenix browser runtime via WebSocket. By default returns new logs since last call; set clear=true to get all logs and clear the buffer.",
+        {
+            clear: z.boolean().default(false).describe("If true, return all logs and clear the buffer. If false, return only new logs since last read."),
+            instance: z.string().optional().describe("Target a specific Phoenix instance by name (e.g. 'Phoenix-a3f2'). Required when multiple instances are connected.")
+        },
+        async ({ clear, instance }) => {
+            let logs;
+            if (clear) {
+                logs = wsControlServer.getBrowserLogs(false, instance);
+                if (logs && logs.error) {
+                    return {
+                        content: [{ type: "text", text: JSON.stringify(logs) }]
+                    };
+                }
+                const clearResult = wsControlServer.clearBrowserLogs(instance);
+                if (clearResult && clearResult.error) {
+                    return {
+                        content: [{ type: "text", text: JSON.stringify(clearResult) }]
+                    };
+                }
+            } else {
+                logs = wsControlServer.getBrowserLogs(true, instance);
+                if (logs && logs.error) {
+                    return {
+                        content: [{ type: "text", text: JSON.stringify(logs) }]
+                    };
+                }
+            }
+            return {
+                content: [{
+                    type: "text",
+                    text: JSON.stringify(logs.length > 0 ? logs : "(no browser logs)")
+                }]
+            };
+        }
+    );
+
+    server.tool(
+        "take_screenshot",
+        "Take a screenshot of the Phoenix Code app window. Returns a PNG image.",
+        {
+            selector: z.string().optional().describe("Optional CSS selector to capture a specific element"),
+            instance: z.string().optional().describe("Target a specific Phoenix instance by name (e.g. 'Phoenix-a3f2'). Required when multiple instances are connected.")
+        },
+        async ({ selector, instance }) => {
+            try {
+                const base64Data = await wsControlServer.requestScreenshot(selector, instance);
+                return {
+                    content: [{
+                        type: "image",
+                        data: base64Data,
+                        mimeType: "image/png"
+                    }]
+                };
+            } catch (err) {
+                return {
+                    content: [{
+                        type: "text",
+                        text: JSON.stringify({ error: err.message })
+                    }]
+                };
+            }
+        }
+    );
+
+    server.tool(
+        "reload_phoenix",
+        "Reload the Phoenix Code app. Closes all open files (prompting to save unsaved changes) then reloads the app.",
+        {
+            instance: z.string().optional().describe("Target a specific Phoenix instance by name (e.g. 'Phoenix-a3f2'). Required when multiple instances are connected.")
+        },
+        async ({ instance }) => {
+            try {
+                const result = await wsControlServer.requestReload(false, instance);
+                return {
+                    content: [{
+                        type: "text",
+                        text: JSON.stringify({ success: true, message: "Phoenix is reloading" })
+                    }]
+                };
+            } catch (err) {
+                return {
+                    content: [{
+                        type: "text",
+                        text: JSON.stringify({ error: err.message })
+                    }]
+                };
+            }
+        }
+    );
+
+    server.tool(
+        "force_reload_phoenix",
+        "Force reload the Phoenix Code app without saving. Closes all open files without saving unsaved changes, then reloads the app.",
+        {
+            instance: z.string().optional().describe("Target a specific Phoenix instance by name (e.g. 'Phoenix-a3f2'). Required when multiple instances are connected.")
+        },
+        async ({ instance }) => {
+            try {
+                const result = await wsControlServer.requestReload(true, instance);
+                return {
+                    content: [{
+                        type: "text",
+                        text: JSON.stringify({ success: true, message: "Phoenix is force reloading (unsaved changes discarded)" })
+                    }]
+                };
+            } 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.",
+        {},
+        async () => {
+            return {
+                content: [{
+                    type: "text",
+                    text: JSON.stringify({
+                        processRunning: processManager.isRunning(),
+                        pid: processManager.getPid(),
+                        wsConnected: wsControlServer.isClientConnected(),
+                        connectedInstances: wsControlServer.getConnectedInstances(),
+                        wsPort: wsControlServer.getPort()
+                    })
+                }]
+            };
+        }
+    );
+}