@ejazullah/browser-mcp 0.0.56

package/lib/program.js

@@ -0,0 +1,113 @@
+/**
+ * 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 { program, Option } from 'commander';
+// @ts-ignore
+import { startTraceViewerServer } from 'playwright-core/lib/server';
+import * as mcpTransport from './mcp/transport.js';
+import { commaSeparatedList, resolveCLIConfig, semicolonSeparatedList } from './config.js';
+import { buildAuthConfig } from './auth.js';
+import { packageJSON } from './package.js';
+import { createExtensionContextFactory, runWithExtension } from './extension/main.js';
+import { BrowserServerBackend } from './browserServerBackend.js';
+import { Context } from './context.js';
+import { contextFactory } from './browserContextFactory.js';
+import { runLoopTools } from './loopTools/main.js';
+program
+    .version('Version ' + packageJSON.version)
+    .name(packageJSON.name)
+    .option('--allowed-origins <origins>', 'semicolon-separated list of origins to allow the browser to request. Default is to allow all.', semicolonSeparatedList)
+    .option('--blocked-origins <origins>', 'semicolon-separated list of origins to block the browser from requesting. Blocklist is evaluated before allowlist. If used without the allowlist, requests not matching the blocklist are still allowed.', semicolonSeparatedList)
+    .option('--block-service-workers', 'block service workers')
+    .option('--browser <browser>', 'browser or chrome channel to use, possible values: chrome, firefox, webkit, msedge.')
+    .option('--caps <caps>', 'comma-separated list of additional capabilities to enable, possible values: vision, pdf.', commaSeparatedList)
+    .option('--cdp-endpoint <endpoint>', 'CDP endpoint to connect to.')
+    .option('--config <path>', 'path to the configuration file.')
+    .option('--device <device>', 'device to emulate, for example: "iPhone 15"')
+    .option('--executable-path <path>', 'path to the browser executable.')
+    .option('--headless', 'run browser in headless mode, headed by default')
+    .option('--host <host>', 'host to bind server to. Default is localhost. Use 0.0.0.0 to bind to all interfaces.')
+    .option('--ignore-https-errors', 'ignore https errors')
+    .option('--isolated', 'keep the browser profile in memory, do not save it to disk.')
+    .option('--image-responses <mode>', 'whether to send image responses to the client. Can be "allow" or "omit", Defaults to "allow".')
+    .option('--no-sandbox', 'disable the sandbox for all process types that are normally sandboxed.')
+    .option('--output-dir <path>', 'path to the directory for output files.')
+    .option('--port <port>', 'port to listen on for SSE transport.')
+    .option('--proxy-bypass <bypass>', 'comma-separated domains to bypass proxy, for example ".com,chromium.org,.domain.com"')
+    .option('--proxy-server <proxy>', 'specify proxy server, for example "http://myproxy:3128" or "socks5://myproxy:8080"')
+    .option('--save-session', 'Whether to save the Playwright MCP session into the output directory.')
+    .option('--save-trace', 'Whether to save the Playwright Trace of the session into the output directory.')
+    .option('--storage-state <path>', 'path to the storage state file for isolated sessions.')
+    .option('--user-agent <ua string>', 'specify user agent string')
+    .option('--user-data-dir <path>', 'path to the user data directory. If not specified, a temporary directory will be created.')
+    .option('--viewport-size <size>', 'specify browser viewport size in pixels, for example "1280, 720"')
+    .option('--mongodb-url <url>', 'MongoDB connection URL. Example: mongodb://localhost:27017')
+    .option('--mongodb-db <name>', 'MongoDB database name. Default: playwright_mcp')
+    .option('--mongodb-collection <name>', 'MongoDB collection name. Default: element_interactions')
+    .option('--auth', 'Enable OAuth2/JWT authentication for HTTP transport.')
+    .option('--jwt-secret <secret>', 'JWT signing secret. Auto-generated if not provided.')
+    .option('--token-expiry <duration>', 'JWT token expiry (e.g. 1h, 30m, 7d). Default: 1h')
+    .option('--api-keys <keys>', 'Comma-separated API keys for simple authentication.')
+    .option('--oauth-clients <json>', 'JSON string of OAuth2 client configurations.')
+    .addOption(new Option('--extension', 'Connect to a running browser instance (Edge/Chrome only). Requires the "Playwright MCP Bridge" browser extension to be installed.').hideHelp())
+    .addOption(new Option('--connect-tool', 'Allow to switch between different browser connection methods.').hideHelp())
+    .addOption(new Option('--loop-tools', 'Run loop tools').hideHelp())
+    .addOption(new Option('--vision', 'Legacy option, use --caps=vision instead').hideHelp())
+    .action(async (options) => {
+    setupExitWatchdog();
+    if (options.vision) {
+        // eslint-disable-next-line no-console
+        console.error('The --vision option is deprecated, use --caps=vision instead');
+        options.caps = 'vision';
+    }
+    const config = await resolveCLIConfig(options);
+    if (options.extension) {
+        await runWithExtension(config);
+        return;
+    }
+    if (options.loopTools) {
+        await runLoopTools(config);
+        return;
+    }
+    const browserContextFactory = contextFactory(config);
+    const factories = [browserContextFactory];
+    if (options.connectTool)
+        factories.push(createExtensionContextFactory(config));
+    const serverBackendFactory = () => new BrowserServerBackend(config, factories);
+    const authConfig = buildAuthConfig(options);
+    await mcpTransport.start(serverBackendFactory, config.server, authConfig);
+    if (config.saveTrace) {
+        const server = await startTraceViewerServer();
+        const urlPrefix = server.urlPrefix('human-readable');
+        const url = urlPrefix + '/trace/index.html?trace=' + config.browser.launchOptions.tracesDir + '/trace.json';
+        // eslint-disable-next-line no-console
+        console.error('\nTrace viewer listening on ' + url);
+    }
+});
+function setupExitWatchdog() {
+    let isExiting = false;
+    const handleExit = async () => {
+        if (isExiting)
+            return;
+        isExiting = true;
+        setTimeout(() => process.exit(0), 15000);
+        await Context.disposeAll();
+        process.exit(0);
+    };
+    process.stdin.on('close', handleExit);
+    process.on('SIGINT', handleExit);
+    process.on('SIGTERM', handleExit);
+}
+void program.parseAsync(process.argv);

package/lib/response.js

@@ -0,0 +1,172 @@
+/**
+ * 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 { renderModalStates } from './tab.js';
+export class Response {
+    _result = [];
+    _code = [];
+    _images = [];
+    _context;
+    _includeSnapshot = false;
+    _includeTabs = false;
+    _tabSnapshot;
+    _elementInteraction;
+    toolName;
+    toolArgs;
+    _isError;
+    constructor(context, toolName, toolArgs) {
+        this._context = context;
+        this.toolName = toolName;
+        this.toolArgs = toolArgs;
+    }
+    addResult(result) {
+        this._result.push(result);
+    }
+    addError(error) {
+        this._result.push(error);
+        this._isError = true;
+    }
+    isError() {
+        return this._isError;
+    }
+    result() {
+        return this._result.join('\n');
+    }
+    addCode(code) {
+        this._code.push(code);
+    }
+    code() {
+        return this._code.join('\n');
+    }
+    addImage(image) {
+        this._images.push(image);
+    }
+    images() {
+        return this._images;
+    }
+    setIncludeSnapshot() {
+        this._includeSnapshot = true;
+    }
+    setIncludeTabs() {
+        this._includeTabs = true;
+    }
+    async finish() {
+        // All the async snapshotting post-action is happening here.
+        // Everything below should race against modal states.
+        if (this._includeSnapshot && this._context.currentTab())
+            this._tabSnapshot = await this._context.currentTabOrDie().captureSnapshot();
+        for (const tab of this._context.tabs())
+            await tab.updateTitle();
+    }
+    tabSnapshot() {
+        return this._tabSnapshot;
+    }
+    setElementInteraction(interaction) {
+        this._elementInteraction = interaction;
+    }
+    getElementInteraction() {
+        return this._elementInteraction;
+    }
+    serialize() {
+        const response = [];
+        // Start with command result.
+        if (this._result.length) {
+            response.push('### Result');
+            response.push(this._result.join('\n'));
+            response.push('');
+        }
+        // Add code if it exists.
+        if (this._code.length) {
+            response.push(`### Ran Playwright code
+\`\`\`js
+${this._code.join('\n')}
+\`\`\``);
+            response.push('');
+        }
+        // List browser tabs.
+        if (this._includeSnapshot || this._includeTabs)
+            response.push(...renderTabsMarkdown(this._context.tabs(), this._includeTabs));
+        // Add snapshot if provided.
+        if (this._tabSnapshot?.modalStates.length) {
+            response.push(...renderModalStates(this._context, this._tabSnapshot.modalStates));
+            response.push('');
+        }
+        else if (this._tabSnapshot) {
+            response.push(renderTabSnapshot(this._tabSnapshot));
+            response.push('');
+        }
+        // Main response part
+        const content = [
+            { type: 'text', text: response.join('\n') },
+        ];
+        // Image attachments.
+        if (this._context.config.imageResponses !== 'omit') {
+            for (const image of this._images)
+                content.push({ type: 'image', data: image.data.toString('base64'), mimeType: image.contentType });
+        }
+        return { content, isError: this._isError };
+    }
+}
+function renderTabSnapshot(tabSnapshot) {
+    const lines = [];
+    if (tabSnapshot.consoleMessages.length) {
+        lines.push(`### New console messages`);
+        for (const message of tabSnapshot.consoleMessages)
+            lines.push(`- ${trim(message.toString(), 100)}`);
+        lines.push('');
+    }
+    if (tabSnapshot.downloads.length) {
+        lines.push(`### Downloads`);
+        for (const entry of tabSnapshot.downloads) {
+            if (entry.finished)
+                lines.push(`- Downloaded file ${entry.download.suggestedFilename()} to ${entry.outputFile}`);
+            else
+                lines.push(`- Downloading file ${entry.download.suggestedFilename()} ...`);
+        }
+        lines.push('');
+    }
+    lines.push(`### Page state`);
+    lines.push(`- Page URL: ${tabSnapshot.url}`);
+    lines.push(`- Page Title: ${tabSnapshot.title}`);
+    lines.push(`- Page Snapshot:`);
+    lines.push('```yaml');
+    lines.push(tabSnapshot.ariaSnapshot);
+    lines.push('```');
+    return lines.join('\n');
+}
+function renderTabsMarkdown(tabs, force = false) {
+    if (tabs.length === 1 && !force)
+        return [];
+    if (!tabs.length) {
+        return [
+            '### Open tabs',
+            'No open tabs. Use the "browser_navigate" tool to navigate to a page first.',
+            '',
+        ];
+    }
+    const lines = ['### Open tabs'];
+    for (let i = 0; i < tabs.length; i++) {
+        const tab = tabs[i];
+        const current = tab.isCurrentTab() ? ' (current)' : '';
+        lines.push(`- ${i}:${current} [${tab.lastTitle()}] (${tab.page.url()})`);
+    }
+    lines.push('');
+    return lines;
+}
+function trim(text, maxLength) {
+    if (text.length <= maxLength)
+        return text;
+    return text.slice(0, maxLength) + '...';
+}

package/lib/sessionLog.js

@@ -0,0 +1,156 @@
+/**
+ * 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 { logUnhandledError } from './log.js';
+import { outputFile } from './config.js';
+import { createDatabaseLogger } from './databaseLogger.js';
+export class SessionLog {
+    _folder;
+    _file;
+    _ordinal = 0;
+    _pendingEntries = [];
+    _sessionFileQueue = Promise.resolve();
+    _flushEntriesTimeout;
+    _dbLogger;
+    constructor(sessionFolder, config) {
+        this._folder = sessionFolder;
+        this._file = path.join(this._folder, 'session.md');
+        // Extract MongoDB config from FullConfig
+        const mongoConfig = config?.mongodb ? {
+            mongoUrl: config.mongodb.url,
+            dbName: config.mongodb.dbName,
+            collectionName: config.mongodb.collectionName,
+        } : undefined;
+        this._dbLogger = createDatabaseLogger(sessionFolder, mongoConfig);
+    }
+    static async create(config, rootPath) {
+        const sessionFolder = await outputFile(config, rootPath, `session-${Date.now()}`);
+        await fs.promises.mkdir(sessionFolder, { recursive: true });
+        // eslint-disable-next-line no-console
+        console.error(`Session: ${sessionFolder}`);
+        // eslint-disable-next-line no-console
+        console.error(`Database: ${path.join(sessionFolder, 'interactions.json')}`);
+        return new SessionLog(sessionFolder, config);
+    }
+    getDatabaseLogger() {
+        return this._dbLogger;
+    }
+    logResponse(response) {
+        const entry = {
+            timestamp: performance.now(),
+            toolCall: {
+                toolName: response.toolName,
+                toolArgs: response.toolArgs,
+                result: response.result(),
+                isError: response.isError(),
+            },
+            code: response.code(),
+            tabSnapshot: response.tabSnapshot(),
+        };
+        this._appendEntry(entry);
+        // Log element interaction to database if available
+        const elementInteraction = response.getElementInteraction();
+        if (elementInteraction && elementInteraction.elementRef) {
+            const tabSnapshot = response.tabSnapshot();
+            const interaction = {
+                timestamp: new Date().toISOString(),
+                toolName: response.toolName,
+                elementRef: elementInteraction.elementRef,
+                elementDescription: elementInteraction.elementDescription || '',
+                playwrightSelector: elementInteraction.playwrightSelector || '',
+                resolvedSelector: elementInteraction.resolvedSelector,
+                url: tabSnapshot?.url || '',
+                pageTitle: tabSnapshot?.title || '',
+                additionalArgs: this._extractAdditionalArgs(response.toolArgs),
+            };
+            this._dbLogger.logInteraction(interaction);
+        }
+    }
+    _extractAdditionalArgs(toolArgs) {
+        const { element, ref, ...rest } = toolArgs;
+        return rest;
+    }
+    logUserAction(action, tab, code, isUpdate) {
+        code = code.trim();
+        if (isUpdate) {
+            const lastEntry = this._pendingEntries[this._pendingEntries.length - 1];
+            if (lastEntry.userAction?.name === action.name) {
+                lastEntry.userAction = action;
+                lastEntry.code = code;
+                return;
+            }
+        }
+        if (action.name === 'navigate') {
+            // Already logged at this location.
+            const lastEntry = this._pendingEntries[this._pendingEntries.length - 1];
+            if (lastEntry?.tabSnapshot?.url === action.url)
+                return;
+        }
+        const entry = {
+            timestamp: performance.now(),
+            userAction: action,
+            code,
+            tabSnapshot: {
+                url: tab.page.url(),
+                title: '',
+                ariaSnapshot: action.ariaSnapshot || '',
+                modalStates: [],
+                consoleMessages: [],
+                downloads: [],
+            },
+        };
+        this._appendEntry(entry);
+    }
+    _appendEntry(entry) {
+        this._pendingEntries.push(entry);
+        if (this._flushEntriesTimeout)
+            clearTimeout(this._flushEntriesTimeout);
+        this._flushEntriesTimeout = setTimeout(() => this._flushEntries(), 1000);
+    }
+    async _flushEntries() {
+        clearTimeout(this._flushEntriesTimeout);
+        const entries = this._pendingEntries;
+        this._pendingEntries = [];
+        const lines = [''];
+        for (const entry of entries) {
+            const ordinal = (++this._ordinal).toString().padStart(3, '0');
+            if (entry.toolCall) {
+                lines.push(`### Tool call: ${entry.toolCall.toolName}`, `- Args`, '```json', JSON.stringify(entry.toolCall.toolArgs, null, 2), '```');
+                if (entry.toolCall.result) {
+                    lines.push(entry.toolCall.isError ? `- Error` : `- Result`, '```', entry.toolCall.result, '```');
+                }
+            }
+            if (entry.userAction) {
+                const actionData = { ...entry.userAction };
+                delete actionData.ariaSnapshot;
+                delete actionData.selector;
+                delete actionData.signals;
+                lines.push(`### User action: ${entry.userAction.name}`, `- Args`, '```json', JSON.stringify(actionData, null, 2), '```');
+            }
+            if (entry.code) {
+                lines.push(`- Code`, '```js', entry.code, '```');
+            }
+            if (entry.tabSnapshot) {
+                const fileName = `${ordinal}.snapshot.yml`;
+                fs.promises.writeFile(path.join(this._folder, fileName), entry.tabSnapshot.ariaSnapshot).catch(logUnhandledError);
+                lines.push(`- Snapshot: ${fileName}`);
+            }
+            lines.push('', '');
+        }
+        this._sessionFileQueue = this._sessionFileQueue.then(() => fs.promises.appendFile(this._file, lines.join('\n')));
+    }
+}