firefox-css-theme-mcp 0.1.4 → 0.1.6

package/README.md

@@ -2,11 +2,12 @@
 
 Model Context Protocol (MCP) server for inspecting, querying, and live-debugging Firefox UI DOM and CSS themes (`userChrome.css`).
 
+![MCP Usage Example - Customising Close Tab Button](./assets/image.jpg)
+
 ## Requirements
 
 - Node.js >= 18
 - Firefox Browser
-- `geckodriver` available on your `PATH` or managed via Selenium
 
 ## Installation & Usage
 
@@ -68,14 +69,16 @@ npm run build
 
 ## Command-line Flags
 
-| Flag        | Type      | Description                                                                                                                      |
-| :---------- | :-------- | :------------------------------------------------------------------------------------------------------------------------------- |
-| `--nova-ui` | `boolean` | Enables the Firefox Nova UI redesign preferences (`browser.nova.enabled` and `browser.newtabpage.activity-stream.nova.enabled`). |
+| Flag         | Type      | Description                                                                                                                      |
+| :----------- | :-------- | :------------------------------------------------------------------------------------------------------------------------------- |
+| `--nova-ui`  | `boolean` | Enables the Firefox Nova UI redesign preferences (`browser.nova.enabled` and `browser.newtabpage.activity-stream.nova.enabled`). |
+| `--headless` | `boolean` | Runs Firefox in headless mode without displaying a graphical user interface window.                                              |
 
 ## Available MCP Tools
 
 - `launch_browser`: Launches Firefox with chrome debugging capabilities enabled.
 - `close_browser`: Terminates the browser instance.
+- `customize_toolbar`: Activates or controls the Firefox "Customize Toolbar" mode.
 - `get_ui_tree`: Dumps the hierarchical DOM tree of the chrome window.
 - `query_ui_elements`: Queries elements matching a CSS selector in the browser chrome.
 - `get_computed_styles`: Extracts computed CSS property values of a specific UI element.

package/dist/firefox.js

@@ -1,60 +1,63 @@
 import { Builder, By } from "selenium-webdriver";
 import * as firefox from "selenium-webdriver/firefox.js";
-export class FirefoxBrowserManager {
-    driverInstance = null;
+export class FirefoxManager {
+    driver = null;
     async initialiseBrowser(binaryPath, profileDirectory) {
-        if (this.driverInstance)
+        if (this.driver)
             return;
         const isNovaUiEnabled = process.argv.includes("--nova-ui");
-        const firefoxOptions = new firefox.Options();
-        firefoxOptions.addArguments("-no-remote", "-new-instance");
-        firefoxOptions.setPreference("devtools.chrome.enabled", true);
-        firefoxOptions.setPreference("devtools.debugger.remote-enabled", true);
-        firefoxOptions.setPreference("devtools.debugger.prompt-connection", false);
-        firefoxOptions.setPreference("toolkit.legacyUserProfileCustomizations.stylesheets", true);
-        firefoxOptions.setPreference("marionette.allow-system-access", true);
-        firefoxOptions.setPreference("remote.allow-system-access", true);
-        firefoxOptions.setPreference("browser.nova.enabled", isNovaUiEnabled);
-        firefoxOptions.setPreference("browser.newtabpage.activity-stream.nova.enabled", isNovaUiEnabled);
+        const isHeadlessEnabled = process.argv.includes("--headless");
+        const options = new firefox.Options();
+        options.addArguments("-no-remote", "-new-instance");
+        if (isHeadlessEnabled)
+            options.addArguments("-headless");
+        options.setPreference("devtools.chrome.enabled", true);
+        options.setPreference("devtools.debugger.remote-enabled", true);
+        options.setPreference("devtools.debugger.prompt-connection", false);
+        options.setPreference("toolkit.legacyUserProfileCustomizations.stylesheets", true);
+        options.setPreference("marionette.allow-system-access", true);
+        options.setPreference("remote.allow-system-access", true);
+        options.setPreference("browser.nova.enabled", isNovaUiEnabled);
+        options.setPreference("browser.newtabpage.activity-stream.nova.enabled", isNovaUiEnabled);
         if (binaryPath)
-            firefoxOptions.setBinary(binaryPath);
+            options.setBinary(binaryPath);
         if (profileDirectory)
-            firefoxOptions.setProfile(profileDirectory);
-        const firefoxService = new firefox.ServiceBuilder()
+            options.setProfile(profileDirectory);
+        const service = new firefox.ServiceBuilder()
             .enableVerboseLogging(true)
             .addArguments("--allow-system-access");
         try {
-            this.driverInstance = await new Builder()
+            this.driver = await new Builder()
                 .forBrowser("firefox")
-                .setFirefoxOptions(firefoxOptions)
-                .setFirefoxService(firefoxService)
+                .setFirefoxOptions(options)
+                .setFirefoxService(service)
                 .build();
             await this.ensureChromeContext();
             await this.openBrowserToolbox().catch(() => { });
         }
         catch (error) {
-            if (this.driverInstance) {
-                await this.driverInstance.quit().catch(() => { });
-                this.driverInstance = null;
+            if (this.driver) {
+                await this.driver.quit().catch(() => { });
+                this.driver = null;
             }
             throw error;
         }
     }
     async terminateBrowser() {
-        if (!this.driverInstance)
+        if (!this.driver)
             return;
-        await this.driverInstance.quit();
-        this.driverInstance = null;
+        await this.driver.quit();
+        this.driver = null;
     }
     async ensureChromeContext() {
-        if (!this.driverInstance) {
+        if (!this.driver) {
             throw new Error("Firefox driver instance is not initialised.");
         }
-        await this.driverInstance.setContext("chrome");
+        await this.driver.setContext("chrome");
     }
     async executeChromeScript(script, ...argumentsList) {
         await this.ensureChromeContext();
-        return (await this.driverInstance.executeScript(script, ...argumentsList));
+        return (await this.driver.executeScript(script, ...argumentsList));
     }
     async queryElements(selector) {
         await this.ensureChromeContext();
@@ -114,28 +117,92 @@ export class FirefoxBrowserManager {
                 throw new Error("Root element not found for selector: " +
                     targetSelector);
             }
-            function serializeNode(node, currentDepth) {
-                const attributeMap = {};
-                for (const attribute of Array.from(node.attributes)) {
-                    attributeMap[attribute.name] = attribute.value;
+            const rootNodeHierarchy = {
+                tagName: rootTarget.tagName.toLowerCase(),
+                id: rootTarget.id || "",
+                className: rootTarget.className || "",
+                attributes: {},
+                children: [],
+            };
+            for (const attribute of Array.from(rootTarget.attributes)) {
+                rootNodeHierarchy.attributes[attribute.name] =
+                    attribute.value;
+            }
+            const nodeQueue = [
+                {
+                    domNode: rootTarget,
+                    hierarchyNode: rootNodeHierarchy,
+                    currentDepth: 0,
+                },
+            ];
+            while (nodeQueue.length > 0) {
+                const queueItem = nodeQueue.shift();
+                if (!queueItem ||
+                    queueItem.currentDepth >= maximumTraversalDepth) {
+                    continue;
                 }
-                const serializedChildren = [];
-                if (currentDepth < maximumTraversalDepth) {
-                    for (const child of Array.from(node.children)) {
-                        serializedChildren.push(serializeNode(child, currentDepth + 1));
+                for (const childElement of Array.from(queueItem.domNode.children)) {
+                    const childAttributes = {};
+                    for (const attribute of Array.from(childElement.attributes)) {
+                        childAttributes[attribute.name] = attribute.value;
                     }
+                    const childHierarchyNode = {
+                        tagName: childElement.tagName.toLowerCase(),
+                        id: childElement.id || "",
+                        className: childElement.className || "",
+                        attributes: childAttributes,
+                        children: [],
+                    };
+                    queueItem.hierarchyNode.children.push(childHierarchyNode);
+                    nodeQueue.push({
+                        domNode: childElement,
+                        hierarchyNode: childHierarchyNode,
+                        currentDepth: queueItem.currentDepth + 1,
+                    });
                 }
-                return {
-                    tagName: node.tagName.toLowerCase(),
-                    id: node.id || "",
-                    className: node.className || "",
-                    attributes: attributeMap,
-                    children: serializedChildren,
-                };
             }
-            return serializeNode(rootTarget, 0);
+            return rootNodeHierarchy;
         }, rootSelector, maximumDepth);
     }
+    async customizeToolbar(action = "enter") {
+        await this.ensureChromeContext();
+        return await this.executeChromeScript(async (requestedAction) => {
+            const customizeMode = window.gCustomizeMode;
+            const documentElement = document.documentElement;
+            if (!customizeMode) {
+                const customizeCommand = document.getElementById("cmd_CustomizeToolbars");
+                if (customizeCommand) {
+                    customizeCommand.doCommand();
+                    return {
+                        isCustomizing: documentElement.hasAttribute("customizing"),
+                        success: true,
+                    };
+                }
+                throw new Error("Customize toolbar mode is not available in the current context.");
+            }
+            const isCurrentlyCustomizing = documentElement.hasAttribute("customizing") ||
+                Boolean(customizeMode.visible);
+            const shouldEnter = requestedAction === "enter";
+            if (shouldEnter !== isCurrentlyCustomizing) {
+                const transitionEventName = shouldEnter
+                    ? "customizationready"
+                    : "aftercustomization";
+                await new Promise((resolve) => {
+                    const timeoutIdentifier = setTimeout(resolve, 5000);
+                    window.addEventListener(transitionEventName, () => {
+                        clearTimeout(timeoutIdentifier);
+                        resolve();
+                    }, { once: true });
+                    customizeMode[requestedAction]();
+                });
+            }
+            return {
+                isCustomizing: documentElement.hasAttribute("customizing") ||
+                    Boolean(customizeMode.visible),
+                success: true,
+            };
+        }, action);
+    }
     async injectUserInterfaceStyle(cascadingStyleSheetContent, styleIdentifier = "mcp-injected-style") {
         await this.ensureChromeContext();
         return await this.executeChromeScript((identifier, cssSource) => {
@@ -164,11 +231,11 @@ export class FirefoxBrowserManager {
     async captureScreenshot(targetSelector) {
         await this.ensureChromeContext();
         if (targetSelector) {
-            const targetWebElement = await this.driverInstance.findElement(By.css(targetSelector));
+            const targetWebElement = await this.driver.findElement(By.css(targetSelector));
             const elementScreenshotBase64 = await targetWebElement.takeScreenshot();
             return { base64Image: elementScreenshotBase64, format: "png" };
         }
-        const fullWindowScreenshotBase64 = await this.driverInstance.takeScreenshot();
+        const fullWindowScreenshotBase64 = await this.driver.takeScreenshot();
         return { base64Image: fullWindowScreenshotBase64, format: "png" };
     }
     async openBrowserToolbox() {
@@ -185,4 +252,4 @@ export class FirefoxBrowserManager {
         });
     }
 }
-export const globalFirefoxManager = new FirefoxBrowserManager();
+export const firefoxManager = new FirefoxManager();

package/dist/index.js

@@ -1,13 +1,15 @@
 #!/usr/bin/env node
+import { readFileSync } from "node:fs";
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { z } from "zod";
-import { globalFirefoxManager } from "./firefox.js";
-const serverInstance = new McpServer({
-    name: "firefox-css-theme-mcp",
-    version: "0.1.4",
+import { firefoxManager } from "./firefox.js";
+const packageJson = JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8"));
+const server = new McpServer({
+    name: packageJson.name,
+    version: packageJson.version,
 });
-serverInstance.registerTool("launch_browser", {
+server.registerTool("launch_browser", {
     description: "Launch a Firefox instance with chrome debugging capabilities enabled.",
     inputSchema: {
         binaryPath: z
@@ -20,7 +22,7 @@ serverInstance.registerTool("launch_browser", {
             .describe("Optional path to custom Firefox profile directory."),
     },
 }, async (parameters) => {
-    await globalFirefoxManager.initialiseBrowser(parameters.binaryPath, parameters.profileDirectory);
+    await firefoxManager.initialiseBrowser(parameters.binaryPath, parameters.profileDirectory);
     return {
         content: [
             {
@@ -30,13 +32,27 @@ serverInstance.registerTool("launch_browser", {
         ],
     };
 });
-serverInstance.registerTool("close_browser", { description: "Close the running Firefox instance." }, async () => {
-    await globalFirefoxManager.terminateBrowser();
+server.registerTool("close_browser", { description: "Close the running Firefox instance." }, async () => {
+    await firefoxManager.terminateBrowser();
     return {
         content: [{ type: "text", text: "Firefox closed successfully." }],
     };
 });
-serverInstance.registerTool("get_ui_tree", {
+server.registerTool("customize_toolbar", {
+    description: "Activate or manage the Firefox Customize Toolbar mode in the browser chrome.",
+    inputSchema: {
+        action: z
+            .enum(["enter", "exit"])
+            .default("enter")
+            .describe("Action to perform on customize toolbar mode ('enter' or 'exit'). Defaults to 'enter'."),
+    },
+}, async (parameters) => {
+    const result = await firefoxManager.customizeToolbar(parameters.action);
+    return {
+        content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
+    };
+});
+server.registerTool("get_ui_tree", {
     description: "Retrieve the hierarchical DOM tree of the Firefox chrome user interface window.",
     inputSchema: {
         rootSelector: z
@@ -49,14 +65,14 @@ serverInstance.registerTool("get_ui_tree", {
             .describe("Maximum recursive depth to traverse."),
     },
 }, async (parameters) => {
-    const treeData = await globalFirefoxManager.getUserInterfaceTree(parameters.rootSelector, parameters.maximumDepth);
+    const treeData = await firefoxManager.getUserInterfaceTree(parameters.rootSelector, parameters.maximumDepth);
     return {
         content: [
             { type: "text", text: JSON.stringify(treeData, null, 2) },
         ],
     };
 });
-serverInstance.registerTool("query_ui_elements", {
+server.registerTool("query_ui_elements", {
     description: "Find elements in the Firefox UI chrome document matching a CSS selector.",
     inputSchema: {
         selector: z
@@ -64,14 +80,14 @@ serverInstance.registerTool("query_ui_elements", {
             .describe("CSS selector to query in chrome document (e.g. '#nav-bar', '#TabsToolbar')."),
     },
 }, async (parameters) => {
-    const elements = await globalFirefoxManager.queryElements(parameters.selector);
+    const elements = await firefoxManager.queryElements(parameters.selector);
     return {
         content: [
             { type: "text", text: JSON.stringify(elements, null, 2) },
         ],
     };
 });
-serverInstance.registerTool("get_computed_styles", {
+server.registerTool("get_computed_styles", {
     description: "Extract computed CSS properties for a Firefox UI chrome element.",
     inputSchema: {
         selector: z
@@ -83,12 +99,12 @@ serverInstance.registerTool("get_computed_styles", {
             .describe("Optional list of specific CSS property names."),
     },
 }, async (parameters) => {
-    const styles = await globalFirefoxManager.getComputedStyles(parameters.selector, parameters.properties);
+    const styles = await firefoxManager.getComputedStyles(parameters.selector, parameters.properties);
     return {
         content: [{ type: "text", text: JSON.stringify(styles, null, 2) }],
     };
 });
-serverInstance.registerTool("inject_theme_css", {
+server.registerTool("inject_theme_css", {
     description: "Inject or replace a live stylesheet in the Firefox chrome window for immediate visual testing.",
     inputSchema: {
         css: z
@@ -100,12 +116,12 @@ serverInstance.registerTool("inject_theme_css", {
             .describe("Identifier for the style tag."),
     },
 }, async (parameters) => {
-    const result = await globalFirefoxManager.injectUserInterfaceStyle(parameters.css, parameters.styleId);
+    const result = await firefoxManager.injectUserInterfaceStyle(parameters.css, parameters.styleId);
     return {
         content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
     };
 });
-serverInstance.registerTool("remove_theme_css", {
+server.registerTool("remove_theme_css", {
     description: "Remove an injected stylesheet from the Firefox chrome window.",
     inputSchema: {
         styleId: z
@@ -113,12 +129,12 @@ serverInstance.registerTool("remove_theme_css", {
             .describe("Identifier of the style tag to remove."),
     },
 }, async (parameters) => {
-    const result = await globalFirefoxManager.removeUserInterfaceStyle(parameters.styleId);
+    const result = await firefoxManager.removeUserInterfaceStyle(parameters.styleId);
     return {
         content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
     };
 });
-serverInstance.registerTool("take_ui_screenshot", {
+server.registerTool("take_ui_screenshot", {
     description: "Capture a PNG screenshot of the Firefox browser chrome window or a specific UI component.",
     inputSchema: {
         selector: z
@@ -127,7 +143,7 @@ serverInstance.registerTool("take_ui_screenshot", {
             .describe("Optional CSS selector to screenshot a specific element."),
     },
 }, async (parameters) => {
-    const screenshot = await globalFirefoxManager.captureScreenshot(parameters.selector);
+    const screenshot = await firefoxManager.captureScreenshot(parameters.selector);
     return {
         content: [
             {
@@ -138,7 +154,7 @@ serverInstance.registerTool("take_ui_screenshot", {
         ],
     };
 });
-serverInstance.registerTool("execute_chrome_javascript", {
+server.registerTool("execute_chrome_javascript", {
     description: "Execute privileged JavaScript code in the Firefox chrome window context.",
     inputSchema: {
         script: z
@@ -146,14 +162,14 @@ serverInstance.registerTool("execute_chrome_javascript", {
             .describe("JavaScript code string to evaluate in chrome context."),
     },
 }, async (parameters) => {
-    const result = await globalFirefoxManager.executeChromeScript(parameters.script);
+    const result = await firefoxManager.executeChromeScript(parameters.script);
     return {
         content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
     };
 });
 async function main() {
-    const transportInstance = new StdioServerTransport();
-    await serverInstance.connect(transportInstance);
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
 }
 main().catch((error) => {
     console.error("Server initialisation failure:", error);

package/dist/types.js

@@ -0,0 +1 @@
+export {};

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "firefox-css-theme-mcp",
-	"version": "0.1.4",
+	"version": "0.1.6",
 	"description": "Model Context Protocol server for inspecting and live-debugging Firefox UI DOM and CSS themes.",
 	"homepage": "https://github.com/easonwong-de/Firefox-CSS-Theme-MCP#readme",
 	"bugs": {
@@ -24,7 +24,8 @@
 		"build": "tsc",
 		"format": "prettier --write --list-different .",
 		"prepublishOnly": "npm run build",
-		"start": "node dist/index.js"
+		"start": "node dist/index.js",
+		"test": "tsx tests/run.ts --headless"
 	},
 	"dependencies": {
 		"@modelcontextprotocol/sdk": "^1.30.0",
@@ -35,6 +36,7 @@
 		"@types/node": "^26.2.0",
 		"@types/selenium-webdriver": "^4.35.6",
 		"prettier": "^3.9.6",
+		"tsx": "^4.23.12",
 		"typescript": "^7.0.2"
 	}
 }