chrome-devtools-mcp-for-extension 0.5.0

package/build/src/system-profile.js

@@ -0,0 +1,181 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+/**
+ * Get platform-specific Chrome user data directory paths
+ */
+function getChromeUserDataPaths() {
+    const homeDir = os.homedir();
+    const platform = os.platform();
+    const platformPaths = {
+        darwin: {
+            stable: path.join(homeDir, 'Library', 'Application Support', 'Google', 'Chrome'),
+            canary: path.join(homeDir, 'Library', 'Application Support', 'Google', 'Chrome Canary'),
+            beta: path.join(homeDir, 'Library', 'Application Support', 'Google', 'Chrome Beta'),
+            dev: path.join(homeDir, 'Library', 'Application Support', 'Google', 'Chrome Dev'),
+        },
+        win32: {
+            stable: path.join(homeDir, 'AppData', 'Local', 'Google', 'Chrome', 'User Data'),
+            canary: path.join(homeDir, 'AppData', 'Local', 'Google', 'Chrome SxS', 'User Data'),
+            beta: path.join(homeDir, 'AppData', 'Local', 'Google', 'Chrome Beta', 'User Data'),
+            dev: path.join(homeDir, 'AppData', 'Local', 'Google', 'Chrome Dev', 'User Data'),
+        },
+        linux: {
+            stable: path.join(homeDir, '.config', 'google-chrome'),
+            canary: path.join(homeDir, '.config', 'google-chrome-unstable'),
+            beta: path.join(homeDir, '.config', 'google-chrome-beta'),
+            dev: path.join(homeDir, '.config', 'google-chrome-dev'),
+        },
+    };
+    return platformPaths[platform] || {};
+}
+/**
+ * Check if Chrome profile directory exists and is valid
+ */
+function validateChromeProfile(profilePath) {
+    try {
+        if (!fs.existsSync(profilePath)) {
+            return false;
+        }
+        const stats = fs.statSync(profilePath);
+        if (!stats.isDirectory()) {
+            return false;
+        }
+        // Check for essential Chrome profile files
+        const essentialFiles = [
+            'Default', // Default profile directory
+            'Local State', // Chrome local state file
+        ];
+        for (const file of essentialFiles) {
+            const filePath = path.join(profilePath, file);
+            if (!fs.existsSync(filePath)) {
+                return false;
+            }
+        }
+        return true;
+    }
+    catch (error) {
+        return false;
+    }
+}
+/**
+ * Detect system Chrome profile for the specified channel
+ */
+export function detectSystemChromeProfile(channel = 'stable') {
+    const platform = os.platform();
+    const chromePaths = getChromeUserDataPaths();
+    if (!chromePaths[channel]) {
+        return null;
+    }
+    const profilePath = chromePaths[channel];
+    const exists = validateChromeProfile(profilePath);
+    if (exists) {
+        return {
+            path: profilePath,
+            exists: true,
+            platform,
+            channel,
+        };
+    }
+    return null;
+}
+/**
+ * Detect any available system Chrome profile with fallback priority
+ */
+export function detectAnySystemChromeProfile() {
+    const platform = os.platform();
+    const chromePaths = getChromeUserDataPaths();
+    // Priority order: stable > beta > dev > canary
+    const channelPriority = ['stable', 'beta', 'dev', 'canary'];
+    for (const channel of channelPriority) {
+        const profilePath = chromePaths[channel];
+        if (profilePath) {
+            const exists = validateChromeProfile(profilePath);
+            if (exists) {
+                return {
+                    path: profilePath,
+                    exists: true,
+                    platform,
+                    channel,
+                };
+            }
+        }
+    }
+    return null;
+}
+/**
+ * Get all available system Chrome profiles
+ */
+export function getAllSystemChromeProfiles() {
+    const platform = os.platform();
+    const chromePaths = getChromeUserDataPaths();
+    const profiles = [];
+    for (const [channel, profilePath] of Object.entries(chromePaths)) {
+        if (profilePath) {
+            const exists = validateChromeProfile(profilePath);
+            profiles.push({
+                path: profilePath,
+                exists,
+                platform,
+                channel,
+            });
+        }
+    }
+    return profiles;
+}
+/**
+ * Get the default profile path within a Chrome user data directory
+ */
+export function getDefaultProfilePath(userDataDir) {
+    return path.join(userDataDir, 'Default');
+}
+/**
+ * Check if we're running in a sandboxed environment where system profile detection might fail
+ */
+export function isSandboxedEnvironment() {
+    const platform = os.platform();
+    // Check for common sandbox indicators
+    if (platform === 'darwin') {
+        // macOS Seatbelt indicators
+        const sandboxIndicators = [
+            process.env.APP_SANDBOX_CONTAINER_ID,
+            process.env.TMPDIR?.includes('TemporaryItems'),
+        ];
+        return sandboxIndicators.some(indicator => !!indicator);
+    }
+    if (platform === 'linux') {
+        // Linux container indicators
+        const containerIndicators = [
+            fs.existsSync('/.dockerenv'),
+            process.env.container,
+            process.env.KUBERNETES_SERVICE_HOST,
+        ];
+        return containerIndicators.some(indicator => !!indicator);
+    }
+    return false;
+}
+/**
+ * Log system profile detection information for debugging
+ */
+export function logSystemProfileInfo() {
+    const platform = os.platform();
+    const profiles = getAllSystemChromeProfiles();
+    const sandboxed = isSandboxedEnvironment();
+    console.error(`System Chrome Profile Detection:`);
+    console.error(`  Platform: ${platform}`);
+    console.error(`  Sandboxed Environment: ${sandboxed}`);
+    console.error(`  Available Profiles:`);
+    if (profiles.length === 0) {
+        console.error(`    None detected`);
+    }
+    else {
+        profiles.forEach((profile, index) => {
+            console.error(`    ${index + 1}. ${profile.channel}: ${profile.path} (${profile.exists ? 'exists' : 'not found'})`);
+        });
+    }
+}

package/build/src/tools/ToolDefinition.js

@@ -0,0 +1,9 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+export function defineTool(definition) {
+    return definition;
+}
+export const CLOSE_PAGE_ERROR = 'The last open page cannot be closed. It is fine to keep it open.';

package/build/src/tools/bookmarks.js

@@ -0,0 +1,310 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { z } from 'zod';
+import * as fs from 'fs';
+import * as path from 'path';
+import * as os from 'os';
+import { ToolCategories } from './categories.js';
+import { defineTool } from './ToolDefinition.js';
+// Default hardcoded bookmarks - fallback when Chrome bookmarks cannot be loaded
+function getDefaultBookmarks() {
+    return {
+        'dashboard': 'https://chrome.google.com/webstore/devconsole',
+        'new_item': 'https://chrome.google.com/webstore/devconsole/register',
+        'analytics': 'https://chrome.google.com/webstore/devconsole/analytics',
+        'payments': 'https://chrome.google.com/webstore/devconsole/payments',
+        'support': 'https://support.google.com/chrome_webstore/contact/developer_support',
+        'extensions': 'chrome://extensions/',
+        'extensions_dev': 'chrome://extensions/?id=',
+        'policy': 'https://developer.chrome.com/docs/webstore/program-policies/',
+        'docs': 'https://developer.chrome.com/docs/extensions/',
+        'localhost': 'http://localhost:3000',
+        'localhost8080': 'http://localhost:8080',
+        'suno': 'https://suno.com/create',
+        'chatgpt': 'https://chatgpt.com'
+    };
+}
+/**
+ * Get Chrome bookmarks file path based on the operating system
+ */
+function getChromeBookmarksPath() {
+    const platform = process.platform;
+    const homeDir = os.homedir();
+    switch (platform) {
+        case 'darwin': // macOS
+            return path.join(homeDir, 'Library', 'Application Support', 'Google', 'Chrome', 'Default', 'Bookmarks');
+        case 'win32': // Windows
+            return path.join(homeDir, 'AppData', 'Local', 'Google', 'Chrome', 'User Data', 'Default', 'Bookmarks');
+        case 'linux': // Linux
+            return path.join(homeDir, '.config', 'google-chrome', 'Default', 'Bookmarks');
+        default:
+            return path.join(homeDir, '.config', 'google-chrome', 'Default', 'Bookmarks');
+    }
+}
+/**
+ * Recursively extract bookmark URLs from Chrome bookmark structure
+ */
+function extractBookmarkUrls(bookmark, prefix = '') {
+    const result = {};
+    const MAX_BOOKMARKS = 100; // Limit to 100 bookmarks to prevent response size issues
+    let bookmarkCount = 0;
+    // Helper function to recursively extract bookmarks with limit
+    function extract(node) {
+        if (bookmarkCount >= MAX_BOOKMARKS)
+            return;
+        if (node.type === 'url' && node.url && node.name) {
+            // Create a safe key from bookmark name
+            const key = node.name.toLowerCase()
+                .replace(/[^a-z0-9]/g, '_')
+                .replace(/_+/g, '_')
+                .replace(/^_|_$/g, '');
+            if (key && !result[key]) {
+                result[key] = node.url;
+                bookmarkCount++;
+            }
+        }
+        if (node.children && bookmarkCount < MAX_BOOKMARKS) {
+            for (const child of node.children) {
+                extract(child);
+                if (bookmarkCount >= MAX_BOOKMARKS)
+                    break;
+            }
+        }
+    }
+    extract(bookmark);
+    return result;
+}
+/**
+ * Load Chrome bookmarks from the user's Chrome profile
+ */
+function loadChromeBookmarks() {
+    try {
+        const bookmarksPath = getChromeBookmarksPath();
+        console.error(`📚 Attempting to load Chrome bookmarks from: ${bookmarksPath}`);
+        if (!fs.existsSync(bookmarksPath)) {
+            console.error(`⚠️  Chrome bookmarks file not found: ${bookmarksPath}`);
+            return {};
+        }
+        const bookmarksData = fs.readFileSync(bookmarksPath, 'utf8');
+        const bookmarksJson = JSON.parse(bookmarksData);
+        const allBookmarks = {};
+        // Extract bookmarks from all roots
+        Object.assign(allBookmarks, extractBookmarkUrls(bookmarksJson.roots.bookmark_bar));
+        Object.assign(allBookmarks, extractBookmarkUrls(bookmarksJson.roots.other));
+        Object.assign(allBookmarks, extractBookmarkUrls(bookmarksJson.roots.synced));
+        const bookmarkCount = Object.keys(allBookmarks).length;
+        console.error(`✅ Successfully loaded ${bookmarkCount} Chrome bookmarks${bookmarkCount >= 100 ? ' (limited to 100)' : ''}`);
+        return allBookmarks;
+    }
+    catch (error) {
+        console.error('❌ Failed to load Chrome bookmarks:');
+        console.error('   Path:', getChromeBookmarksPath());
+        console.error('   Error:', error instanceof Error ? error.message : String(error));
+        if (error instanceof Error && error.stack) {
+            console.error('   Stack:', error.stack);
+        }
+        return {};
+    }
+}
+/**
+ * Get all bookmarks: merged Chrome bookmarks with default fallback
+ */
+function getBookmarks() {
+    const defaultBookmarks = getDefaultBookmarks();
+    const chromeBookmarks = loadChromeBookmarks();
+    // Merge bookmarks: Chrome bookmarks take precedence, but defaults are always included
+    return {
+        ...defaultBookmarks,
+        ...chromeBookmarks
+    };
+}
+export const listBookmarks = defineTool({
+    name: 'list_bookmarks',
+    description: `List all available bookmarks including both Chrome bookmarks from the user's profile and default development bookmarks. Automatically loads bookmarks from Chrome's bookmark file and merges them with predefined development URLs.`,
+    annotations: {
+        category: ToolCategories.NAVIGATION_AUTOMATION,
+        readOnlyHint: true,
+    },
+    schema: {},
+    handler: async (_request, response, _context) => {
+        const defaultBookmarks = getDefaultBookmarks();
+        const chromeBookmarks = loadChromeBookmarks();
+        const allBookmarks = getBookmarks();
+        const bookmarkNames = Object.keys(allBookmarks);
+        if (bookmarkNames.length === 0) {
+            response.appendResponseLine('No bookmarks configured.');
+            response.appendResponseLine('');
+            response.appendResponseLine('💡 **Tip:** Chrome bookmarks could not be loaded. Check if Chrome is installed and has bookmarks.');
+            return;
+        }
+        response.appendResponseLine('📚 **Available Bookmarks:**');
+        response.appendResponseLine('');
+        // Show loading status
+        const chromeBookmarkCount = Object.keys(chromeBookmarks).length;
+        const defaultBookmarkCount = Object.keys(defaultBookmarks).length;
+        if (chromeBookmarkCount > 0) {
+            response.appendResponseLine(`✅ Loaded ${chromeBookmarkCount} bookmarks from Chrome profile${chromeBookmarkCount >= 100 ? ' (limited to 100)' : ''}`);
+            response.appendResponseLine(`📋 ${defaultBookmarkCount} default development bookmarks included`);
+        }
+        else {
+            response.appendResponseLine(`⚠️  Could not load Chrome bookmarks, using ${defaultBookmarkCount} default bookmarks`);
+        }
+        response.appendResponseLine('');
+        bookmarkNames.forEach(name => {
+            const url = allBookmarks[name];
+            const source = chromeBookmarks[name] ? '🌐' : '🔧';
+            response.appendResponseLine(`${source} **${name}**: ${url}`);
+        });
+        response.appendResponseLine('');
+        response.appendResponseLine('**Legend:** 🌐 = Chrome bookmark, 🔧 = Default bookmark');
+        response.appendResponseLine('');
+        response.appendResponseLine(`Use \`navigate_bookmark name="<bookmark_name>"\` to navigate to any of these URLs.`);
+    },
+});
+export const navigateBookmark = defineTool({
+    name: 'navigate_bookmark',
+    description: `Navigate to a bookmark URL from Chrome bookmarks or default development bookmarks. Automatically includes bookmarks from the user's Chrome profile merged with predefined development resources.`,
+    annotations: {
+        category: ToolCategories.NAVIGATION_AUTOMATION,
+        readOnlyHint: false,
+    },
+    schema: {
+        name: z
+            .string()
+            .describe('The name of the bookmark to navigate to. Use list_bookmarks to see available options.'),
+    },
+    handler: async (request, response, context) => {
+        const { name } = request.params;
+        const bookmarks = getBookmarks();
+        if (!bookmarks[name]) {
+            response.appendResponseLine(`❌ Bookmark "${name}" not found.`);
+            response.appendResponseLine('');
+            const availableBookmarks = Object.keys(bookmarks);
+            if (availableBookmarks.length > 0) {
+                response.appendResponseLine('Available bookmarks:');
+                availableBookmarks.forEach(bookmarkName => {
+                    response.appendResponseLine(`• ${bookmarkName}`);
+                });
+            }
+            else {
+                response.appendResponseLine('No bookmarks are currently configured.');
+            }
+            return;
+        }
+        const url = bookmarks[name];
+        const page = context.getSelectedPage();
+        await context.waitForEventsAfterAction(async () => {
+            await page.goto(url, { waitUntil: 'networkidle0' });
+            response.appendResponseLine(`✅ Navigated to bookmark "${name}": ${url}`);
+        });
+    },
+});
+export const openExtensionById = defineTool({
+    name: 'open_extension_by_id',
+    description: `Open a specific Chrome extension page by its ID. Useful for quickly accessing extension details, options, or management pages.`,
+    annotations: {
+        category: ToolCategories.EXTENSION_DEVELOPMENT,
+        readOnlyHint: false,
+    },
+    schema: {
+        extensionId: z
+            .string()
+            .describe('The Chrome extension ID (e.g., "abcdefghijklmnopqrstuvwxyz")'),
+        page: z
+            .enum(['details', 'options'])
+            .default('details')
+            .describe('The extension page to open'),
+    },
+    handler: async (request, response, context) => {
+        const { extensionId, page: extensionPage } = request.params;
+        const pageContext = context.getSelectedPage();
+        let url;
+        if (extensionPage === 'details') {
+            url = `chrome://extensions/?id=${extensionId}`;
+        }
+        else {
+            url = `chrome-extension://${extensionId}/options.html`;
+        }
+        await context.waitForEventsAfterAction(async () => {
+            try {
+                await pageContext.goto(url, { waitUntil: 'networkidle0' });
+                response.appendResponseLine(`✅ Opened ${extensionPage} page for extension: ${extensionId}`);
+            }
+            catch (error) {
+                response.appendResponseLine(`❌ Failed to open extension page: ${error instanceof Error ? error.message : String(error)}`);
+                response.appendResponseLine('');
+                response.appendResponseLine('💡 **Possible reasons:**');
+                response.appendResponseLine('• Extension ID is invalid or extension is not installed');
+                response.appendResponseLine('• Extension does not have an options page (for options page requests)');
+                response.appendResponseLine('• Extension is disabled');
+            }
+        });
+    },
+});
+export const openWebstoreDashboard = defineTool({
+    name: 'open_webstore_dashboard',
+    description: `Open the Chrome Web Store developer dashboard. Provides quick access to extension management, analytics, and publishing tools.`,
+    annotations: {
+        category: ToolCategories.EXTENSION_DEVELOPMENT,
+        readOnlyHint: false,
+    },
+    schema: {},
+    handler: async (_request, response, context) => {
+        const page = context.getSelectedPage();
+        const dashboardUrl = 'https://chrome.google.com/webstore/devconsole';
+        await context.waitForEventsAfterAction(async () => {
+            await page.goto(dashboardUrl, { waitUntil: 'networkidle0' });
+            response.appendResponseLine('✅ Opened Chrome Web Store Developer Dashboard');
+            response.appendResponseLine('');
+            response.appendResponseLine('🚀 **Quick Actions Available:**');
+            response.appendResponseLine('• View and manage your published extensions');
+            response.appendResponseLine('• Check analytics and user feedback');
+            response.appendResponseLine('• Upload new versions or create new items');
+            response.appendResponseLine('• Review policy compliance and store listing details');
+        });
+    },
+});
+export const openExtensionDocs = defineTool({
+    name: 'open_extension_docs',
+    description: `Open the Chrome Extensions documentation. Provides access to the official development guides, API references, and best practices.`,
+    annotations: {
+        category: ToolCategories.EXTENSION_DEVELOPMENT,
+        readOnlyHint: false,
+    },
+    schema: {
+        section: z
+            .enum([
+            'overview',
+            'getting-started',
+            'api',
+            'manifest',
+            'examples',
+            'best-practices',
+        ])
+            .optional()
+            .describe('Specific documentation section to open'),
+    },
+    handler: async (request, response, context) => {
+        const { section } = request.params;
+        const page = context.getSelectedPage();
+        let url = 'https://developer.chrome.com/docs/extensions/';
+        if (section) {
+            const sectionUrls = {
+                overview: 'https://developer.chrome.com/docs/extensions/',
+                'getting-started': 'https://developer.chrome.com/docs/extensions/get-started/',
+                api: 'https://developer.chrome.com/docs/extensions/reference/',
+                manifest: 'https://developer.chrome.com/docs/extensions/reference/manifest',
+                examples: 'https://github.com/GoogleChrome/chrome-extensions-samples',
+                'best-practices': 'https://developer.chrome.com/docs/extensions/develop/migrate',
+            };
+            url = sectionUrls[section] || url;
+        }
+        await context.waitForEventsAfterAction(async () => {
+            await page.goto(url, { waitUntil: 'networkidle0' });
+            response.appendResponseLine(`✅ Opened Chrome Extensions ${section ? `${section} ` : ''}documentation`);
+        });
+    },
+});

package/build/src/tools/categories.js

@@ -0,0 +1,15 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+export var ToolCategories;
+(function (ToolCategories) {
+    ToolCategories["INPUT_AUTOMATION"] = "Input automation";
+    ToolCategories["NAVIGATION_AUTOMATION"] = "Navigation automation";
+    ToolCategories["EMULATION"] = "Emulation";
+    ToolCategories["PERFORMANCE"] = "Performance";
+    ToolCategories["NETWORK"] = "Network";
+    ToolCategories["DEBUGGING"] = "Debugging";
+    ToolCategories["EXTENSION_DEVELOPMENT"] = "Extension development";
+})(ToolCategories || (ToolCategories = {}));

package/build/src/tools/console.js

@@ -0,0 +1,19 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { ToolCategories } from './categories.js';
+import { defineTool } from './ToolDefinition.js';
+export const consoleTool = defineTool({
+    name: 'list_console_messages',
+    description: 'List all console messages for the currently selected page',
+    annotations: {
+        category: ToolCategories.DEBUGGING,
+        readOnlyHint: true,
+    },
+    schema: {},
+    handler: async (_request, response) => {
+        response.setIncludeConsoleData(true);
+    },
+});

package/build/src/tools/emulation.js

@@ -0,0 +1,61 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { PredefinedNetworkConditions } from 'puppeteer-core';
+import z from 'zod';
+import { ToolCategories } from './categories.js';
+import { defineTool } from './ToolDefinition.js';
+const throttlingOptions = [
+    'No emulation',
+    ...Object.keys(PredefinedNetworkConditions),
+];
+export const emulateNetwork = defineTool({
+    name: 'emulate_network',
+    description: `Emulates network conditions such as throttling on the selected page.`,
+    annotations: {
+        category: ToolCategories.EMULATION,
+        readOnlyHint: false,
+    },
+    schema: {
+        throttlingOption: z
+            .enum(throttlingOptions)
+            .describe(`The network throttling option to emulate. Available throttling options are: ${throttlingOptions.join(', ')}. Set to "No emulation" to disable.`),
+    },
+    handler: async (request, _response, context) => {
+        const page = context.getSelectedPage();
+        const conditions = request.params.throttlingOption;
+        if (conditions === 'No emulation') {
+            await page.emulateNetworkConditions(null);
+            context.setNetworkConditions(null);
+            return;
+        }
+        if (conditions in PredefinedNetworkConditions) {
+            const networkCondition = PredefinedNetworkConditions[conditions];
+            await page.emulateNetworkConditions(networkCondition);
+            context.setNetworkConditions(conditions);
+        }
+    },
+});
+export const emulateCpu = defineTool({
+    name: 'emulate_cpu',
+    description: `Emulates CPU throttling by slowing down the selected page's execution.`,
+    annotations: {
+        category: ToolCategories.EMULATION,
+        readOnlyHint: false,
+    },
+    schema: {
+        throttlingRate: z
+            .number()
+            .min(1)
+            .max(20)
+            .describe('The CPU throttling rate representing the slowdown factor 1-20x. Set the rate to 1 to disable throttling'),
+    },
+    handler: async (request, _response, context) => {
+        const page = context.getSelectedPage();
+        const { throttlingRate } = request.params;
+        await page.emulateCPUThrottling(throttlingRate);
+        context.setCpuThrottlingRate(throttlingRate);
+    },
+});