@darbotlabs/darbot-browser-mcp 0.1.0

package/lib/tools/install.js

@@ -0,0 +1,57 @@
+/**
+ * Copyright (c) Microsoft Corporation.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+import { fork } from 'child_process';
+import path from 'path';
+import { z } from 'zod';
+import { defineTool } from './tool.js';
+import { fileURLToPath } from 'node:url';
+const install = defineTool({
+    capability: 'install',
+    schema: {
+        name: 'browser_install',
+        title: 'Install the browser specified in the config',
+        description: 'Install the browser specified in the config. Call this if you get an error about the browser not being installed.',
+        inputSchema: z.object({}),
+        type: 'destructive',
+    },
+    handle: async (context) => {
+        const channel = context.config.browser?.launchOptions?.channel ?? context.config.browser?.browserName ?? 'msedge';
+        const cliUrl = import.meta.resolve('playwright/package.json');
+        const cliPath = path.join(fileURLToPath(cliUrl), '..', 'cli.js');
+        const child = fork(cliPath, ['install', channel], {
+            stdio: 'pipe',
+        });
+        const output = [];
+        child.stdout?.on('data', data => output.push(data.toString()));
+        child.stderr?.on('data', data => output.push(data.toString()));
+        await new Promise((resolve, reject) => {
+            child.on('close', code => {
+                if (code === 0)
+                    resolve();
+                else
+                    reject(new Error(`Failed to install browser: ${output.join('')}`));
+            });
+        });
+        return {
+            code: [`// Browser ${channel} installed`],
+            captureSnapshot: false,
+            waitForNetwork: false,
+        };
+    },
+});
+export default [
+    install,
+];

package/lib/tools/keyboard.js

@@ -0,0 +1,46 @@
+/**
+ * Copyright (c) Microsoft Corporation.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+import { z } from 'zod';
+import { defineTool } from './tool.js';
+const pressKey = captureSnapshot => defineTool({
+    capability: 'core',
+    schema: {
+        name: 'browser_press_key',
+        title: 'Press a key',
+        description: 'Press a key on the keyboard',
+        inputSchema: z.object({
+            key: z.string().describe('Name of the key to press or a character to generate, such as `ArrowLeft` or `a`'),
+        }),
+        type: 'destructive',
+    },
+    handle: async (context, params) => {
+        const tab = context.currentTabOrDie();
+        const code = [
+            `// Press ${params.key}`,
+            `await page.keyboard.press('${params.key}');`,
+        ];
+        const action = () => tab.page.keyboard.press(params.key);
+        return {
+            code,
+            action,
+            captureSnapshot,
+            waitForNetwork: true
+        };
+    },
+});
+export default (captureSnapshot) => [
+    pressKey(captureSnapshot),
+];

package/lib/tools/navigate.js

@@ -0,0 +1,93 @@
+/**
+ * Copyright (c) Microsoft Corporation.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+import { z } from 'zod';
+import { defineTool } from './tool.js';
+const navigate = captureSnapshot => defineTool({
+    capability: 'core',
+    schema: {
+        name: 'browser_navigate',
+        title: 'Navigate to a URL',
+        description: 'Navigate to a URL',
+        inputSchema: z.object({
+            url: z.string().describe('The URL to navigate to'),
+        }),
+        type: 'destructive',
+    },
+    handle: async (context, params) => {
+        const tab = await context.ensureTab();
+        await tab.navigate(params.url);
+        const code = [
+            `// Navigate to ${params.url}`,
+            `await page.goto('${params.url}');`,
+        ];
+        return {
+            code,
+            captureSnapshot,
+            waitForNetwork: false,
+        };
+    },
+});
+const goBack = captureSnapshot => defineTool({
+    capability: 'history',
+    schema: {
+        name: 'browser_navigate_back',
+        title: 'Go back',
+        description: 'Go back to the previous page',
+        inputSchema: z.object({}),
+        type: 'readOnly',
+    },
+    handle: async (context) => {
+        const tab = await context.ensureTab();
+        await tab.page.goBack();
+        const code = [
+            `// Navigate back`,
+            `await page.goBack();`,
+        ];
+        return {
+            code,
+            captureSnapshot,
+            waitForNetwork: false,
+        };
+    },
+});
+const goForward = captureSnapshot => defineTool({
+    capability: 'history',
+    schema: {
+        name: 'browser_navigate_forward',
+        title: 'Go forward',
+        description: 'Go forward to the next page',
+        inputSchema: z.object({}),
+        type: 'readOnly',
+    },
+    handle: async (context) => {
+        const tab = context.currentTabOrDie();
+        await tab.page.goForward();
+        const code = [
+            `// Navigate forward`,
+            `await page.goForward();`,
+        ];
+        return {
+            code,
+            captureSnapshot,
+            waitForNetwork: false,
+        };
+    },
+});
+export default (captureSnapshot) => [
+    navigate(captureSnapshot),
+    goBack(captureSnapshot),
+    goForward(captureSnapshot),
+];

package/lib/tools/network.js

@@ -0,0 +1,51 @@
+/**
+ * Copyright (c) Microsoft Corporation.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+import { z } from 'zod';
+import { defineTool } from './tool.js';
+const requests = defineTool({
+    capability: 'core',
+    schema: {
+        name: 'browser_network_requests',
+        title: 'List network requests',
+        description: 'Returns all network requests since loading the page',
+        inputSchema: z.object({}),
+        type: 'readOnly',
+    },
+    handle: async (context) => {
+        const requests = context.currentTabOrDie().requests();
+        const log = [...requests.entries()].map(([request, response]) => renderRequest(request, response)).join('\n');
+        return {
+            code: [`// <internal code to list network requests>`],
+            action: async () => {
+                return {
+                    content: [{ type: 'text', text: log }]
+                };
+            },
+            captureSnapshot: false,
+            waitForNetwork: false,
+        };
+    },
+});
+function renderRequest(request, response) {
+    const result = [];
+    result.push(`[${request.method().toUpperCase()}] ${request.url()}`);
+    if (response)
+        result.push(`=> [${response.status()}] ${response.statusText()}`);
+    return result.join(' ');
+}
+export default [
+    requests,
+];

package/lib/tools/pdf.js

@@ -0,0 +1,49 @@
+/**
+ * Copyright (c) Microsoft Corporation.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+import { z } from 'zod';
+import { defineTool } from './tool.js';
+import * as javascript from '../javascript.js';
+import { outputFile } from '../config.js';
+const pdfSchema = z.object({
+    filename: z.string().optional().describe('File name to save the pdf to. Defaults to `page-{timestamp}.pdf` if not specified.'),
+});
+const pdf = defineTool({
+    capability: 'pdf',
+    schema: {
+        name: 'browser_pdf_save',
+        title: 'Save as PDF',
+        description: 'Save page as PDF',
+        inputSchema: pdfSchema,
+        type: 'readOnly',
+    },
+    handle: async (context, params) => {
+        const tab = context.currentTabOrDie();
+        const fileName = await outputFile(context.config, params.filename ?? `page-${new Date().toISOString()}.pdf`);
+        const code = [
+            `// Save page as ${fileName}`,
+            `await page.pdf(${javascript.formatObject({ path: fileName })});`,
+        ];
+        return {
+            code,
+            action: async () => tab.page.pdf({ path: fileName }).then(() => { }),
+            captureSnapshot: false,
+            waitForNetwork: false,
+        };
+    },
+});
+export default [
+    pdf,
+];

package/lib/tools/profiles.js

@@ -0,0 +1,271 @@
+/**
+ * Copyright (c) Microsoft Corporation.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+import fs from 'fs';
+import path from 'path';
+import os from 'os';
+import { z } from 'zod';
+import { defineTool } from './tool.js';
+import { sanitizeForFilePath } from './utils.js';
+const saveProfileSchema = z.object({
+    name: z.string().describe('Name for the work profile'),
+    description: z.string().optional().describe('Optional description for the work profile'),
+});
+const switchProfileSchema = z.object({
+    name: z.string().describe('Name of the work profile to switch to'),
+});
+const listProfilesSchema = z.object({});
+const deleteProfileSchema = z.object({
+    name: z.string().describe('Name of the work profile to delete'),
+});
+async function getProfilesDir() {
+    let profilesDir;
+    if (process.platform === 'linux')
+        profilesDir = process.env.XDG_DATA_HOME || path.join(os.homedir(), '.local', 'share');
+    else if (process.platform === 'darwin')
+        profilesDir = path.join(os.homedir(), 'Library', 'Application Support');
+    else if (process.platform === 'win32')
+        profilesDir = process.env.APPDATA || path.join(os.homedir(), 'AppData', 'Roaming');
+    else
+        throw new Error('Unsupported platform: ' + process.platform);
+    const result = path.join(profilesDir, 'darbot-browser-mcp', 'work-profiles');
+    await fs.promises.mkdir(result, { recursive: true });
+    return result;
+}
+async function saveCurrentProfile(context, profileName, description) {
+    const profilesDir = await getProfilesDir();
+    const sanitizedName = sanitizeForFilePath(profileName);
+    const profileDir = path.join(profilesDir, sanitizedName);
+    await fs.promises.mkdir(profileDir, { recursive: true });
+    // Get current browser state
+    const tab = context.currentTabOrDie();
+    const url = tab.page.url();
+    const title = await tab.title();
+    // Save profile metadata
+    const profileData = {
+        name: profileName,
+        description: description || '',
+        created: new Date().toISOString(),
+        url,
+        title,
+    };
+    await fs.promises.writeFile(path.join(profileDir, 'profile.json'), JSON.stringify(profileData, null, 2));
+    // Save storage state (cookies, localStorage, etc.)
+    try {
+        const storageState = await tab.page.context().storageState();
+        await fs.promises.writeFile(path.join(profileDir, 'storage-state.json'), JSON.stringify(storageState, null, 2));
+    }
+    catch (error) {
+        // Storage state save failed, but we can still save the profile
+        // eslint-disable-next-line no-console
+        console.warn('Failed to save storage state:', error);
+    }
+    return profileData;
+}
+async function loadProfile(context, profileName) {
+    const profilesDir = await getProfilesDir();
+    const sanitizedName = sanitizeForFilePath(profileName);
+    const profileDir = path.join(profilesDir, sanitizedName);
+    try {
+        await fs.promises.access(profileDir);
+    }
+    catch {
+        throw new Error(`Work profile "${profileName}" not found`);
+    }
+    // Load profile metadata
+    const profileDataPath = path.join(profileDir, 'profile.json');
+    const profileData = JSON.parse(await fs.promises.readFile(profileDataPath, 'utf8'));
+    // Load storage state if available
+    const storageStatePath = path.join(profileDir, 'storage-state.json');
+    try {
+        await fs.promises.access(storageStatePath);
+        const storageState = JSON.parse(await fs.promises.readFile(storageStatePath, 'utf8'));
+        // Create new context with the stored state
+        const tab = await context.ensureTab();
+        const currentContext = tab.page.context();
+        if (currentContext) {
+            await currentContext.close();
+        }
+        const newContext = await tab.page.context().browser()?.newContext({
+            storageState,
+            viewport: null,
+        });
+        if (newContext) {
+            const newPage = await newContext.newPage();
+            await newPage.goto(profileData.url);
+            return { profileData, restored: true };
+        }
+    }
+    catch {
+        // Storage state not available or failed to load, fall through to fallback
+    }
+    // Fallback: just navigate to the URL
+    const tab = await context.ensureTab();
+    await tab.page.goto(profileData.url);
+    return { profileData, restored: false };
+}
+async function listProfiles() {
+    const profilesDir = await getProfilesDir();
+    const profiles = [];
+    try {
+        const entries = await fs.promises.readdir(profilesDir);
+        for (const entry of entries) {
+            const profileDir = path.join(profilesDir, entry);
+            const stat = await fs.promises.stat(profileDir);
+            if (stat.isDirectory()) {
+                const profileDataPath = path.join(profileDir, 'profile.json');
+                try {
+                    await fs.promises.access(profileDataPath);
+                    const profileData = JSON.parse(await fs.promises.readFile(profileDataPath, 'utf8'));
+                    profiles.push(profileData);
+                }
+                catch {
+                    // File does not exist, skip this entry
+                }
+            }
+        }
+    }
+    catch (error) {
+        // Profiles directory doesn't exist yet
+        return [];
+    }
+    return profiles;
+}
+async function deleteProfile(profileName) {
+    const profilesDir = await getProfilesDir();
+    const sanitizedName = sanitizeForFilePath(profileName);
+    const profileDir = path.join(profilesDir, sanitizedName);
+    try {
+        await fs.promises.access(profileDir);
+    }
+    catch {
+        throw new Error(`Work profile "${profileName}" not found`);
+    }
+    await fs.promises.rm(profileDir, { recursive: true, force: true });
+}
+export const browserSaveProfile = defineTool({
+    capability: 'core',
+    schema: {
+        name: 'browser_save_profile',
+        title: 'Save Work Profile',
+        description: 'Save the current browser state as a work profile',
+        inputSchema: saveProfileSchema,
+        type: 'destructive',
+    },
+    handle: async (context, { name, description }) => {
+        const profileData = await saveCurrentProfile(context, name, description);
+        return {
+            code: [`await browser_save_profile({ name: '${name}', description: '${description || ''}' })`],
+            action: async () => ({ content: [] }),
+            captureSnapshot: false,
+            waitForNetwork: false,
+            resultOverride: {
+                content: [{
+                        type: 'text',
+                        text: `Work profile "${name}" saved successfully.\n\nProfile details:\n- Name: ${profileData.name}\n- Description: ${profileData.description}\n- URL: ${profileData.url}\n- Title: ${profileData.title}\n- Created: ${profileData.created}`,
+                    }],
+            },
+        };
+    },
+});
+export const browserSwitchProfile = defineTool({
+    capability: 'core',
+    schema: {
+        name: 'browser_switch_profile',
+        title: 'Switch Work Profile',
+        description: 'Switch to a saved work profile',
+        inputSchema: switchProfileSchema,
+        type: 'destructive',
+    },
+    handle: async (context, { name }) => {
+        const result = await loadProfile(context, name);
+        return {
+            code: [`await browser_switch_profile({ name: '${name}' })`],
+            action: async () => ({ content: [] }),
+            captureSnapshot: true,
+            waitForNetwork: false,
+            resultOverride: {
+                content: [{
+                        type: 'text',
+                        text: `Switched to work profile "${name}".\n\nProfile details:\n- Name: ${result.profileData.name}\n- Description: ${result.profileData.description}\n- URL: ${result.profileData.url}\n- Title: ${result.profileData.title}\n- Storage state ${result.restored ? 'restored' : 'not available'}`,
+                    }],
+            },
+        };
+    },
+});
+export const browserListProfiles = defineTool({
+    capability: 'core',
+    schema: {
+        name: 'browser_list_profiles',
+        title: 'List Work Profiles',
+        description: 'List all saved work profiles',
+        inputSchema: listProfilesSchema,
+        type: 'readOnly',
+    },
+    handle: async (context, {}) => {
+        const profiles = await listProfiles();
+        let text = '### Saved Work Profiles\n\n';
+        if (profiles.length === 0) {
+            text += 'No work profiles saved yet. Use the "browser_save_profile" tool to save your current browser state as a work profile.';
+        }
+        else {
+            for (const profile of profiles) {
+                text += `**${profile.name}**\n`;
+                if (profile.description)
+                    text += `- Description: ${profile.description}\n`;
+                text += `- URL: ${profile.url}\n`;
+                text += `- Title: ${profile.title}\n`;
+                text += `- Created: ${new Date(profile.created).toLocaleString()}\n\n`;
+            }
+        }
+        return {
+            code: ['await browser_list_profiles()'],
+            action: async () => ({ content: [] }),
+            captureSnapshot: false,
+            waitForNetwork: false,
+            resultOverride: {
+                content: [{
+                        type: 'text',
+                        text,
+                    }],
+            },
+        };
+    },
+});
+export const browserDeleteProfile = defineTool({
+    capability: 'core',
+    schema: {
+        name: 'browser_delete_profile',
+        title: 'Delete Work Profile',
+        description: 'Delete a saved work profile',
+        inputSchema: deleteProfileSchema,
+        type: 'destructive',
+    },
+    handle: async (context, { name }) => {
+        await deleteProfile(name);
+        return {
+            code: [`await browser_delete_profile({ name: '${name}' })`],
+            action: async () => ({ content: [] }),
+            captureSnapshot: false,
+            waitForNetwork: false,
+            resultOverride: {
+                content: [{
+                        type: 'text',
+                        text: `Work profile "${name}" deleted successfully.`,
+                    }],
+            },
+        };
+    },
+});

package/lib/tools/screenshot.js

@@ -0,0 +1,77 @@
+/**
+ * Copyright (c) Microsoft Corporation.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+import { z } from 'zod';
+import { defineTool } from './tool.js';
+import * as javascript from '../javascript.js';
+import { outputFile } from '../config.js';
+import { generateLocator } from './utils.js';
+const screenshotSchema = z.object({
+    raw: z.boolean().optional().describe('Whether to return without compression (in PNG format). Default is false, which returns a JPEG image.'),
+    filename: z.string().optional().describe('File name to save the screenshot to. Defaults to `page-{timestamp}.{png|jpeg}` if not specified.'),
+    element: z.string().optional().describe('Human-readable element description used to obtain permission to screenshot the element. If not provided, the screenshot will be taken of viewport. If element is provided, ref must be provided too.'),
+    ref: z.string().optional().describe('Exact target element reference from the page snapshot. If not provided, the screenshot will be taken of viewport. If ref is provided, element must be provided too.'),
+}).refine(data => {
+    return !!data.element === !!data.ref;
+}, {
+    message: 'Both element and ref must be provided or neither.',
+    path: ['ref', 'element']
+});
+const screenshot = defineTool({
+    capability: 'core',
+    schema: {
+        name: 'browser_take_screenshot',
+        title: 'Take a screenshot',
+        description: `Take a screenshot of the current page. You can't perform actions based on the screenshot, use browser_snapshot for actions.`,
+        inputSchema: screenshotSchema,
+        type: 'readOnly',
+    },
+    handle: async (context, params) => {
+        const tab = context.currentTabOrDie();
+        const snapshot = tab.snapshotOrDie();
+        const fileType = params.raw ? 'png' : 'jpeg';
+        const fileName = await outputFile(context.config, params.filename ?? `page-${new Date().toISOString()}.${fileType}`);
+        const options = { type: fileType, quality: fileType === 'png' ? undefined : 50, scale: 'css', path: fileName };
+        const isElementScreenshot = params.element && params.ref;
+        const code = [
+            `// Screenshot ${isElementScreenshot ? params.element : 'viewport'} and save it as ${fileName}`,
+        ];
+        const locator = params.ref ? snapshot.refLocator({ element: params.element || '', ref: params.ref }) : null;
+        if (locator)
+            code.push(`await page.${await generateLocator(locator)}.screenshot(${javascript.formatObject(options)});`);
+        else
+            code.push(`await page.screenshot(${javascript.formatObject(options)});`);
+        const includeBase64 = context.clientSupportsImages();
+        const action = async () => {
+            const screenshot = locator ? await locator.screenshot(options) : await tab.page.screenshot(options);
+            return {
+                content: includeBase64 ? [{
+                        type: 'image',
+                        data: screenshot.toString('base64'),
+                        mimeType: fileType === 'png' ? 'image/png' : 'image/jpeg',
+                    }] : []
+            };
+        };
+        return {
+            code,
+            action,
+            captureSnapshot: true,
+            waitForNetwork: false,
+        };
+    }
+});
+export default [
+    screenshot,
+];