firefox-css-theme-mcp 0.1.6 → 0.1.7

package/README.md

@@ -1,88 +1,33 @@
-# Firefox CSS Theme MCP
+# Firefox CSS Theme MCP (Deprecated)
 
-Model Context Protocol (MCP) server for inspecting, querying, and live-debugging Firefox UI DOM and CSS themes (`userChrome.css`).
+> [!WARNING]
+> This package (`firefox-css-theme-mcp`) has been renamed and superseded by [`firefox-css-theme`](https://www.npmjs.com/package/firefox-css-theme).
 
-![MCP Usage Example - Customising Close Tab Button](./assets/image.jpg)
+Please update your configurations to use `firefox-css-theme`.
 
-## Requirements
+## Migration
 
-- Node.js >= 18
-- Firefox Browser
-
-## Installation & Usage
-
-### Option A — CLI
-
-#### Claude Code
+### Claude Code
 
 ```bash
-claude mcp add firefox-css-theme -- npx -y firefox-css-theme-mcp --nova-ui
+claude mcp add firefox-css-theme -- npx -y firefox-css-theme mcp
 ```
 
-#### Codex
+### Codex
 
 ```bash
-codex mcp add firefox-css-theme -- npx -y firefox-css-theme-mcp --nova-ui
+codex mcp add firefox-css-theme -- npx -y firefox-css-theme mcp
 ```
 
-### Option B — IDE Configuration
-
-Add the server configuration to your MCP settings file:
+### MCP Settings File
 
 ```json
 {
 	"mcpServers": {
 		"firefox-css-theme": {
 			"command": "npx",
-			"args": ["-y", "firefox-css-theme-mcp", "--nova-ui"]
+			"args": ["-y", "firefox-css-theme", "mcp"]
 		}
 	}
 }
 ```
-
-### Option C — From Source
-
-1. Clone the repository and build the project:
-
-```bash
-git clone https://github.com/easonwong-de/Firefox-CSS-Theme-MCP.git
-cd Firefox-CSS-Theme-MCP
-npm install
-npm run build
-```
-
-2. Add the local build to your MCP configuration:
-
-```json
-{
-	"mcpServers": {
-		"firefox-css-theme": {
-			"command": "node",
-			"args": [
-				"/path/to/Firefox-CSS-Theme-MCP/dist/index.js",
-				"--nova-ui"
-			]
-		}
-	}
-}
-```
-
-## 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`). |
-| `--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.
-- `inject_theme_css`: Dynamically injects or updates stylesheets in the live UI for instant feedback.
-- `remove_theme_css`: Removes an injected stylesheet.
-- `take_ui_screenshot`: Captures a screenshot of the browser window or a specific UI component.
-- `execute_chrome_javascript`: Runs privileged JavaScript in the browser chrome window context.

package/index.js

@@ -0,0 +1,42 @@
+#!/usr/bin/env node
+
+import { spawn } from "node:child_process";
+
+console.warn(
+	"\x1b[33m[DEPRECATED]\x1b[0m 'firefox-css-theme-mcp' has been renamed to 'firefox-css-theme'. " +
+		"Please update your configuration to use 'npx -y firefox-css-theme mcp'.",
+);
+
+const arguments_ = ["mcp", ...process.argv.slice(2)];
+
+const childProcess = spawn("firefox-css-theme", arguments_, {
+	stdio: "inherit",
+	shell: process.platform === "win32",
+});
+
+childProcess.on("error", (error) => {
+	if (error && "code" in error && error.code === "ENOENT") {
+		const fallbackProcess = spawn(
+			"npx",
+			["-y", "firefox-css-theme@latest", ...arguments_],
+			{ stdio: "inherit", shell: process.platform === "win32" },
+		);
+		fallbackProcess.on("exit", (code, signal) => {
+			if (signal) {
+				process.kill(process.pid, signal);
+			} else {
+				process.exit(code ?? 0);
+			}
+		});
+		return;
+	}
+	throw error;
+});
+
+childProcess.on("exit", (code, signal) => {
+	if (signal) {
+		process.kill(process.pid, signal);
+	} else {
+		process.exit(code ?? 0);
+	}
+});

package/package.json

@@ -1,7 +1,7 @@
 {
 	"name": "firefox-css-theme-mcp",
-	"version": "0.1.6",
-	"description": "Model Context Protocol server for inspecting and live-debugging Firefox UI DOM and CSS themes.",
+	"version": "0.1.7",
+	"description": "DEPRECATED: Renamed to firefox-css-theme. Use 'npx -y firefox-css-theme mcp' instead.",
 	"homepage": "https://github.com/easonwong-de/Firefox-CSS-Theme-MCP#readme",
 	"bugs": {
 		"url": "https://github.com/easonwong-de/Firefox-CSS-Theme-MCP/issues"
@@ -13,30 +13,20 @@
 	"license": "MIT",
 	"author": "Eason Wong <me@easonwong.de> (https://easonwong.de/)",
 	"type": "module",
-	"main": "dist/index.js",
+	"main": "index.js",
 	"bin": {
-		"firefox-css-theme-mcp": "dist/index.js"
+		"firefox-css-theme-mcp": "index.js"
 	},
 	"files": [
-		"dist"
+		"index.js"
 	],
 	"scripts": {
-		"build": "tsc",
-		"format": "prettier --write --list-different .",
-		"prepublishOnly": "npm run build",
-		"start": "node dist/index.js",
-		"test": "tsx tests/run.ts --headless"
+		"format": "prettier --write --list-different ."
 	},
 	"dependencies": {
-		"@modelcontextprotocol/sdk": "^1.30.0",
-		"selenium-webdriver": "^4.47.0",
-		"zod": "^4.4.3"
+		"firefox-css-theme": ">=0.1.0"
 	},
 	"devDependencies": {
-		"@types/node": "^26.2.0",
-		"@types/selenium-webdriver": "^4.35.6",
-		"prettier": "^3.9.6",
-		"tsx": "^4.23.12",
-		"typescript": "^7.0.2"
+		"prettier": "^3.9.6"
 	}
 }

package/dist/firefox.js

@@ -1,255 +0,0 @@
-import { Builder, By } from "selenium-webdriver";
-import * as firefox from "selenium-webdriver/firefox.js";
-export class FirefoxManager {
-    driver = null;
-    async initialiseBrowser(binaryPath, profileDirectory) {
-        if (this.driver)
-            return;
-        const isNovaUiEnabled = process.argv.includes("--nova-ui");
-        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)
-            options.setBinary(binaryPath);
-        if (profileDirectory)
-            options.setProfile(profileDirectory);
-        const service = new firefox.ServiceBuilder()
-            .enableVerboseLogging(true)
-            .addArguments("--allow-system-access");
-        try {
-            this.driver = await new Builder()
-                .forBrowser("firefox")
-                .setFirefoxOptions(options)
-                .setFirefoxService(service)
-                .build();
-            await this.ensureChromeContext();
-            await this.openBrowserToolbox().catch(() => { });
-        }
-        catch (error) {
-            if (this.driver) {
-                await this.driver.quit().catch(() => { });
-                this.driver = null;
-            }
-            throw error;
-        }
-    }
-    async terminateBrowser() {
-        if (!this.driver)
-            return;
-        await this.driver.quit();
-        this.driver = null;
-    }
-    async ensureChromeContext() {
-        if (!this.driver) {
-            throw new Error("Firefox driver instance is not initialised.");
-        }
-        await this.driver.setContext("chrome");
-    }
-    async executeChromeScript(script, ...argumentsList) {
-        await this.ensureChromeContext();
-        return (await this.driver.executeScript(script, ...argumentsList));
-    }
-    async queryElements(selector) {
-        await this.ensureChromeContext();
-        return await this.executeChromeScript((querySelector) => {
-            const matchedElements = Array.from(document.querySelectorAll(querySelector));
-            return matchedElements.map((element) => {
-                const attributeMap = {};
-                for (const attribute of Array.from(element.attributes)) {
-                    attributeMap[attribute.name] = attribute.value;
-                }
-                return {
-                    tagName: element.tagName.toLowerCase(),
-                    id: element.id || "",
-                    className: element.className || "",
-                    childCount: element.children.length,
-                    textContent: (element.textContent || "")
-                        .trim()
-                        .slice(0, 100),
-                    attributes: attributeMap,
-                };
-            });
-        }, selector);
-    }
-    async getComputedStyles(selector, stylePropertyNames) {
-        await this.ensureChromeContext();
-        return await this.executeChromeScript((targetSelector, requestedProperties) => {
-            const targetElement = document.querySelector(targetSelector);
-            if (!targetElement) {
-                throw new Error("Element not found for selector: " + targetSelector);
-            }
-            const computedStyleDeclaration = window.getComputedStyle(targetElement);
-            const styleResult = {};
-            if (Array.isArray(requestedProperties) &&
-                requestedProperties.length > 0) {
-                for (const propertyName of requestedProperties) {
-                    styleResult[propertyName] =
-                        computedStyleDeclaration.getPropertyValue(propertyName);
-                }
-            }
-            else {
-                for (let index = 0; index < computedStyleDeclaration.length; index++) {
-                    const propertyName = computedStyleDeclaration[index];
-                    styleResult[propertyName] =
-                        computedStyleDeclaration.getPropertyValue(propertyName);
-                }
-            }
-            return styleResult;
-        }, selector, stylePropertyNames);
-    }
-    async getUserInterfaceTree(rootSelector = "window", maximumDepth = 3) {
-        await this.ensureChromeContext();
-        return await this.executeChromeScript((targetSelector, maximumTraversalDepth) => {
-            const rootTarget = targetSelector === "window"
-                ? document.documentElement
-                : document.querySelector(targetSelector);
-            if (!rootTarget) {
-                throw new Error("Root element not found for selector: " +
-                    targetSelector);
-            }
-            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;
-                }
-                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 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) => {
-            let existingStyleElement = document.getElementById(identifier);
-            if (!existingStyleElement) {
-                existingStyleElement = document.createElement("style");
-                existingStyleElement.id = identifier;
-                existingStyleElement.setAttribute("type", "text/css");
-                document.documentElement.appendChild(existingStyleElement);
-            }
-            existingStyleElement.textContent = cssSource;
-            return { success: true, identifier: identifier };
-        }, styleIdentifier, cascadingStyleSheetContent);
-    }
-    async removeUserInterfaceStyle(styleIdentifier) {
-        await this.ensureChromeContext();
-        return await this.executeChromeScript((identifier) => {
-            const targetStyleElement = document.getElementById(identifier);
-            if (targetStyleElement) {
-                targetStyleElement.remove();
-                return { removed: true, identifier: identifier };
-            }
-            return { removed: false, identifier: identifier };
-        }, styleIdentifier);
-    }
-    async captureScreenshot(targetSelector) {
-        await this.ensureChromeContext();
-        if (targetSelector) {
-            const targetWebElement = await this.driver.findElement(By.css(targetSelector));
-            const elementScreenshotBase64 = await targetWebElement.takeScreenshot();
-            return { base64Image: elementScreenshotBase64, format: "png" };
-        }
-        const fullWindowScreenshotBase64 = await this.driver.takeScreenshot();
-        return { base64Image: fullWindowScreenshotBase64, format: "png" };
-    }
-    async openBrowserToolbox() {
-        await this.ensureChromeContext();
-        return await this.executeChromeScript(() => {
-            try {
-                const { BrowserToolboxLauncher } = ChromeUtils.importESModule("resource://devtools/client/framework/browser-toolbox/Launcher.sys.mjs");
-                BrowserToolboxLauncher.init();
-                return { success: true };
-            }
-            catch {
-                return { success: false };
-            }
-        });
-    }
-}
-export const firefoxManager = new FirefoxManager();

package/dist/index.js

@@ -1,177 +0,0 @@
-#!/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 { 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,
-});
-server.registerTool("launch_browser", {
-    description: "Launch a Firefox instance with chrome debugging capabilities enabled.",
-    inputSchema: {
-        binaryPath: z
-            .string()
-            .optional()
-            .describe("Optional path to Firefox executable binary."),
-        profileDirectory: z
-            .string()
-            .optional()
-            .describe("Optional path to custom Firefox profile directory."),
-    },
-}, async (parameters) => {
-    await firefoxManager.initialiseBrowser(parameters.binaryPath, parameters.profileDirectory);
-    return {
-        content: [
-            {
-                type: "text",
-                text: "Firefox launched successfully in chrome context.",
-            },
-        ],
-    };
-});
-server.registerTool("close_browser", { description: "Close the running Firefox instance." }, async () => {
-    await firefoxManager.terminateBrowser();
-    return {
-        content: [{ type: "text", text: "Firefox closed successfully." }],
-    };
-});
-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
-            .string()
-            .default("window")
-            .describe("CSS selector for root element."),
-        maximumDepth: z
-            .number()
-            .default(3)
-            .describe("Maximum recursive depth to traverse."),
-    },
-}, async (parameters) => {
-    const treeData = await firefoxManager.getUserInterfaceTree(parameters.rootSelector, parameters.maximumDepth);
-    return {
-        content: [
-            { type: "text", text: JSON.stringify(treeData, null, 2) },
-        ],
-    };
-});
-server.registerTool("query_ui_elements", {
-    description: "Find elements in the Firefox UI chrome document matching a CSS selector.",
-    inputSchema: {
-        selector: z
-            .string()
-            .describe("CSS selector to query in chrome document (e.g. '#nav-bar', '#TabsToolbar')."),
-    },
-}, async (parameters) => {
-    const elements = await firefoxManager.queryElements(parameters.selector);
-    return {
-        content: [
-            { type: "text", text: JSON.stringify(elements, null, 2) },
-        ],
-    };
-});
-server.registerTool("get_computed_styles", {
-    description: "Extract computed CSS properties for a Firefox UI chrome element.",
-    inputSchema: {
-        selector: z
-            .string()
-            .describe("CSS selector of the UI element (e.g. '#urlbar-background')."),
-        properties: z
-            .array(z.string())
-            .optional()
-            .describe("Optional list of specific CSS property names."),
-    },
-}, async (parameters) => {
-    const styles = await firefoxManager.getComputedStyles(parameters.selector, parameters.properties);
-    return {
-        content: [{ type: "text", text: JSON.stringify(styles, null, 2) }],
-    };
-});
-server.registerTool("inject_theme_css", {
-    description: "Inject or replace a live stylesheet in the Firefox chrome window for immediate visual testing.",
-    inputSchema: {
-        css: z
-            .string()
-            .describe("CSS rules to inject into chrome document."),
-        styleId: z
-            .string()
-            .default("mcp-injected-style")
-            .describe("Identifier for the style tag."),
-    },
-}, async (parameters) => {
-    const result = await firefoxManager.injectUserInterfaceStyle(parameters.css, parameters.styleId);
-    return {
-        content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
-    };
-});
-server.registerTool("remove_theme_css", {
-    description: "Remove an injected stylesheet from the Firefox chrome window.",
-    inputSchema: {
-        styleId: z
-            .string()
-            .describe("Identifier of the style tag to remove."),
-    },
-}, async (parameters) => {
-    const result = await firefoxManager.removeUserInterfaceStyle(parameters.styleId);
-    return {
-        content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
-    };
-});
-server.registerTool("take_ui_screenshot", {
-    description: "Capture a PNG screenshot of the Firefox browser chrome window or a specific UI component.",
-    inputSchema: {
-        selector: z
-            .string()
-            .optional()
-            .describe("Optional CSS selector to screenshot a specific element."),
-    },
-}, async (parameters) => {
-    const screenshot = await firefoxManager.captureScreenshot(parameters.selector);
-    return {
-        content: [
-            {
-                type: "image",
-                data: screenshot.base64Image,
-                mimeType: "image/png",
-            },
-        ],
-    };
-});
-server.registerTool("execute_chrome_javascript", {
-    description: "Execute privileged JavaScript code in the Firefox chrome window context.",
-    inputSchema: {
-        script: z
-            .string()
-            .describe("JavaScript code string to evaluate in chrome context."),
-    },
-}, async (parameters) => {
-    const result = await firefoxManager.executeChromeScript(parameters.script);
-    return {
-        content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
-    };
-});
-async function main() {
-    const transport = new StdioServerTransport();
-    await server.connect(transport);
-}
-main().catch((error) => {
-    console.error("Server initialisation failure:", error);
-    process.exit(1);
-});

package/dist/types.js

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