@roxybrowser/playwright-mcp 0.0.5 → 0.0.6-beta.7

package/index.d.ts

@@ -1,23 +1,86 @@
-#!/usr/bin/env node
-/**
- * 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 type { Server } from '@modelcontextprotocol/sdk/server/index.js';
-import type { Config } from './config.js';
-import type { BrowserContext } from 'playwright';
-
-export declare function createConnection(config?: Config, contextGetter?: () => Promise<BrowserContext>): Promise<Server>;
-export {};
+/**
+ * @roxybrowser/playwright-mcp
+ * 类型声明：CLI + 程序化 createConnection/startServer + 可扩展 Backend/工具
+ */
+import type { BrowserContext } from 'playwright';
+
+/** 与 Playwright MCP 一致的配置（部分常用字段） */
+export interface McpConfig {
+  browser?: {
+    browserName?: string;
+    isolated?: boolean;
+    userDataDir?: string;
+    launchOptions?: Record<string, unknown>;
+    contextOptions?: Record<string, unknown>;
+    cdpEndpoint?: string;
+  };
+  server?: { port?: number; host?: string };
+  [key: string]: unknown;
+}
+
+/**
+ * 创建 MCP 服务端实例（未连接 transport）。
+ * 使用 CustomBackend（官方工具 + browser_connect_roxy）。需再 server.connect(transport)。
+ */
+export function createConnection(
+  userConfig?: McpConfig,
+  contextGetter?: () => Promise<BrowserContext>
+): Promise<import('@modelcontextprotocol/sdk').Server>;
+
+/**
+ * 以 HTTP/SSE 启动 MCP 服务（Studio 协议），返回可连接的 URL。
+ * 进程会持续运行直到退出。
+ */
+export function startServer(options: {
+  port: number;
+  host?: string;
+  config?: McpConfig;
+}): Promise<{ url: string }>;
+
+/** 自定义 Backend，继承 Playwright BrowserServerBackend 并增加 Roxy 等工具 */
+export class CustomBackend {
+  constructor(config: McpConfig, factory: unknown);
+  listTools(): Promise<unknown[]>;
+  callTool(name: string, rawArguments: unknown, progress?: (p?: unknown) => void): Promise<unknown>;
+  serverClosed?(server?: unknown): void;
+}
+
+/** 支持 reconnectToCDP 的浏览器上下文工厂，用于 Roxy 连接 */
+export class DynamicCdpContextFactory {
+  constructor(config: McpConfig, initialCdpEndpoint?: string);
+  reconnectToCDP(cdpEndpoint: string): void;
+  createContext(
+    clientInfo: unknown,
+    abortSignal?: AbortSignal,
+    options?: Record<string, unknown>
+  ): Promise<{ browserContext: BrowserContext; close: () => Promise<void> }>;
+}
+
+/** 定义额外工具的 schema + handle 的辅助函数 */
+export function defineExtraTool<TArgs>(
+  schema: {
+    name: string;
+    title: string;
+    description: string;
+    inputSchema: import('zod').ZodType<TArgs>;
+    type?: 'action' | 'readOnly' | 'destructive';
+  },
+  handle: (context: unknown, args: TArgs, progress?: (params?: unknown) => void) => Promise<{
+    content: Array<{ type: 'text'; text: string }>;
+    isError?: boolean;
+  }>
+): { schema: typeof schema; handle: typeof handle };
+
+/** 将自定义 tool 的 schema 转为 MCP listTools 返回格式 */
+export function extraToolToMcp(schema: {
+  name: string;
+  description: string;
+  title: string;
+  inputSchema: unknown;
+  type?: string;
+}): {
+  name: string;
+  description: string;
+  inputSchema: object;
+  annotations: object;
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@roxybrowser/playwright-mcp",
-  "version": "0.0.5",
+  "version": "0.0.6-beta.7",
   "description": "Playwright Tools for MCP",
   "type": "module",
   "repository": {
@@ -16,66 +16,52 @@
   },
   "license": "Apache-2.0",
   "scripts": {
-    "build": "tsc",
-    "lint": "npm run update-readme && npm run check-deps && eslint . && tsc --noEmit",
-    "lint-fix": "eslint . --fix",
-    "check-deps": "node utils/check-deps.js",
-    "update-readme": "node utils/update-readme.js",
-    "watch": "tsc --watch",
-    "test": "playwright test",
-    "ctest": "playwright test --project=chrome",
-    "ftest": "playwright test --project=firefox",
-    "wtest": "playwright test --project=webkit",
-    "run-server": "node lib/browserServer.js",
-    "clean": "npx rimraf lib",
+    "start": "node src/cli.js",
+    "dev": "node --inspect src/cli.js",
+    "dev:http": "node --inspect src/cli.js --port 9324",
+    "build:esbuild": "node build.mjs",
+    "build:webpack": "npm run clean && webpack --config webpack.config.mjs",
+    "build": "npm run build:webpack",
+    "clean": "npx rimraf dist",
     "npm-publish": "npm run clean && npm run build && npm publish",
     "publish:release": "npm run clean && npm version patch --no-git-tag-version && npm run build && npm publish",
-    "publish:beta": "npm version prerelease --preid=beta --no-git-tag-version && npm run build && npm publish --tag beta"
+    "publish:beta": "npm version prerelease --preid=beta --no-git-tag-version && npm publish --tag beta"
   },
   "publishConfig": {
     "access": "public",
     "registry": "https://registry.npmjs.org/"
   },
+  "main": "dist/index.mjs",
+  "files": [
+    "package.json",
+    "dist",
+    "index.d.ts"
+  ],
   "exports": {
     "./package.json": "./package.json",
     ".": {
       "types": "./index.d.ts",
-      "default": "./index.js"
+      "default": "./dist/index.mjs"
     }
   },
   "dependencies": {
-    "@modelcontextprotocol/sdk": "^1.18.0",
     "commander": "^13.1.0",
-    "debug": "^4.4.1",
-    "dotenv": "^17.2.0",
-    "mime": "^4.0.7",
-    "playwright": "1.55.0",
-    "playwright-core": "1.55.0",
-    "ws": "^8.18.1",
     "zod": "^3.24.1",
     "zod-to-json-schema": "^3.24.4"
   },
   "devDependencies": {
-    "@anthropic-ai/sdk": "^0.57.0",
-    "@eslint/eslintrc": "^3.2.0",
-    "@eslint/js": "^9.19.0",
-    "@playwright/test": "1.55.0",
-    "@stylistic/eslint-plugin": "^3.0.1",
-    "@types/debug": "^4.1.12",
-    "@types/node": "^22.13.10",
-    "@types/ws": "^8.18.1",
-    "@typescript-eslint/eslint-plugin": "^8.26.1",
-    "@typescript-eslint/parser": "^8.26.1",
-    "@typescript-eslint/utils": "^8.26.1",
     "esbuild": "^0.20.1",
-    "eslint": "^9.19.0",
-    "eslint-plugin-import": "^2.31.0",
-    "eslint-plugin-notice": "^1.0.0",
-    "openai": "^5.10.2",
-    "typescript": "^5.9.2",
-    "rimraf": "^6.0.1"
+    "playwright": "1.58.2",
+    "playwright-core": "1.58.2",
+    "rimraf": "^6.0.1",
+    "webpack": "^5.105.4",
+    "webpack-cli": "^5.1.4"
   },
-  "bin": {
-    "roxybrowser-mcp-server-playwright": "cli.js"
+  "bin": "dist/cli.mjs",
+  "pnpm": {
+    "patchedDependencies": {
+      "playwright@1.58.2": "patches/playwright@1.58.2.patch",
+      "playwright-core@1.58.2": "patches/playwright-core@1.58.2.patch"
+    }
   }
 }

package/cli.js

@@ -1,18 +0,0 @@
-#!/usr/bin/env node
-/**
- * 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 './lib/program.js';

package/config.d.ts

@@ -1,119 +0,0 @@
-/**
- * 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 type * as playwright from 'playwright';
-
-export type ToolCapability = 'core' | 'core-tabs' | 'core-install' | 'vision' | 'pdf';
-
-export type Config = {
-  /**
-   * The browser to use.
-   */
-  browser?: {
-    /**
-     * The type of browser to use.
-     */
-    browserName?: 'chromium' | 'firefox' | 'webkit';
-
-    /**
-     * Keep the browser profile in memory, do not save it to disk.
-     */
-    isolated?: boolean;
-
-    /**
-     * Path to a user data directory for browser profile persistence.
-     * Temporary directory is created by default.
-     */
-    userDataDir?: string;
-
-    /**
-     * Launch options passed to
-     * @see https://playwright.dev/docs/api/class-browsertype#browser-type-launch-persistent-context
-     *
-     * This is useful for settings options like `channel`, `headless`, `executablePath`, etc.
-     */
-    launchOptions?: playwright.LaunchOptions;
-
-    /**
-     * Context options for the browser context.
-     *
-     * This is useful for settings options like `viewport`.
-     */
-    contextOptions?: playwright.BrowserContextOptions;
-
-    /**
-     * Chrome DevTools Protocol endpoint to connect to an existing browser instance in case of Chromium family browsers.
-     */
-    cdpEndpoint?: string;
-
-    /**
-     * Remote endpoint to connect to an existing Playwright server.
-     */
-    remoteEndpoint?: string;
-  },
-
-  server?: {
-    /**
-     * The port to listen on for SSE or MCP transport.
-     */
-    port?: number;
-
-    /**
-     * The host to bind the server to. Default is localhost. Use 0.0.0.0 to bind to all interfaces.
-     */
-    host?: string;
-  },
-
-  /**
-   * List of enabled tool capabilities. Possible values:
-   *   - 'core': Core browser automation features.
-   *   - 'pdf': PDF generation and manipulation.
-   *   - 'vision': Coordinate-based interactions.
-   */
-  capabilities?: ToolCapability[];
-
-  /**
-   * Whether to save the Playwright session into the output directory.
-   */
-  saveSession?: boolean;
-
-  /**
-   * Whether to save the Playwright trace of the session into the output directory.
-   */
-  saveTrace?: boolean;
-
-  /**
-   * The directory to save output files.
-   */
-  outputDir?: string;
-
-  network?: {
-    /**
-     * List of origins to allow the browser to request. Default is to allow all. Origins matching both `allowedOrigins` and `blockedOrigins` will be blocked.
-     */
-    allowedOrigins?: string[];
-
-    /**
-     * List of origins to block the browser to request. Origins matching both `allowedOrigins` and `blockedOrigins` will be blocked.
-     */
-    blockedOrigins?: string[];
-  };
-
-  /**
-   * Whether to send image responses to the client. Can be "allow", "omit", or "auto". Defaults to "auto", which sends images if the client can display them.
-   */
-  imageResponses?: 'allow' | 'omit';
-};

package/index.js

@@ -1,19 +0,0 @@
-#!/usr/bin/env node
-/**
- * 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 { createConnection } from './lib/index.js';
-export { createConnection };

package/lib/browserContextFactory.js

@@ -1,264 +0,0 @@
-/**
- * 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 net from 'net';
-import path from 'path';
-import * as playwright from 'playwright';
-// @ts-ignore
-import { registryDirectory } from 'playwright-core/lib/server/registry/index';
-// @ts-ignore
-import { startTraceViewerServer } from 'playwright-core/lib/server';
-import { logUnhandledError, testDebug } from './utils/log.js';
-import { createHash } from './utils/guid.js';
-import { outputFile } from './config.js';
-export function contextFactory(config) {
-    if (config.browser.remoteEndpoint)
-        return new RemoteContextFactory(config);
-    if (config.browser.cdpEndpoint)
-        return new CdpContextFactory(config);
-    if (config.browser.isolated)
-        return new IsolatedContextFactory(config);
-    return new PersistentContextFactory(config);
-}
-export function createDynamicCdpContextFactory(config) {
-    return new DynamicCdpContextFactory(config);
-}
-class BaseContextFactory {
-    config;
-    _logName;
-    _browserPromise;
-    constructor(name, config) {
-        this._logName = name;
-        this.config = config;
-    }
-    async _obtainBrowser(clientInfo) {
-        if (this._browserPromise)
-            return this._browserPromise;
-        testDebug(`obtain browser (${this._logName})`);
-        this._browserPromise = this._doObtainBrowser(clientInfo);
-        void this._browserPromise.then(browser => {
-            browser.on('disconnected', () => {
-                this._browserPromise = undefined;
-            });
-        }).catch(() => {
-            this._browserPromise = undefined;
-        });
-        return this._browserPromise;
-    }
-    async _doObtainBrowser(clientInfo) {
-        throw new Error('Not implemented');
-    }
-    async createContext(clientInfo) {
-        testDebug(`create browser context (${this._logName})`);
-        const browser = await this._obtainBrowser(clientInfo);
-        const browserContext = await this._doCreateContext(browser);
-        return { browserContext, close: () => this._closeBrowserContext(browserContext, browser) };
-    }
-    async _doCreateContext(browser) {
-        throw new Error('Not implemented');
-    }
-    async _closeBrowserContext(browserContext, browser) {
-        testDebug(`close browser context (${this._logName})`);
-        if (browser.contexts().length === 1)
-            this._browserPromise = undefined;
-        await browserContext.close().catch(logUnhandledError);
-        if (browser.contexts().length === 0) {
-            testDebug(`close browser (${this._logName})`);
-            await browser.close().catch(logUnhandledError);
-        }
-    }
-}
-class IsolatedContextFactory extends BaseContextFactory {
-    constructor(config) {
-        super('isolated', config);
-    }
-    async _doObtainBrowser(clientInfo) {
-        await injectCdpPort(this.config.browser);
-        const browserType = playwright[this.config.browser.browserName];
-        return browserType.launch({
-            tracesDir: await startTraceServer(this.config, clientInfo.rootPath),
-            ...this.config.browser.launchOptions,
-            handleSIGINT: false,
-            handleSIGTERM: false,
-        }).catch(error => {
-            if (error.message.includes('Executable doesn\'t exist'))
-                throw new Error(`Browser specified in your config is not installed. Either install it (likely) or change the config.`);
-            throw error;
-        });
-    }
-    async _doCreateContext(browser) {
-        return browser.newContext(this.config.browser.contextOptions);
-    }
-}
-class CdpContextFactory extends BaseContextFactory {
-    constructor(config) {
-        super('cdp', config);
-    }
-    async _doObtainBrowser() {
-        return playwright.chromium.connectOverCDP(this.config.browser.cdpEndpoint);
-    }
-    async _doCreateContext(browser) {
-        return this.config.browser.isolated ? await browser.newContext() : browser.contexts()[0];
-    }
-}
-export class DynamicCdpContextFactory extends BaseContextFactory {
-    _currentCdpEndpoint;
-    _reconnecting = false;
-    constructor(config) {
-        super('dynamic-cdp', config);
-    }
-    async reconnectToCDP(cdpEndpoint) {
-        if (this._currentCdpEndpoint === cdpEndpoint && this._browserPromise) {
-            testDebug(`Already connected to CDP endpoint: ${cdpEndpoint}`);
-            return; // Already connected to this endpoint
-        }
-        testDebug(`Reconnecting to CDP endpoint: ${cdpEndpoint}`);
-        this._reconnecting = true;
-        try {
-            // Set the endpoint first to avoid race conditions
-            this._currentCdpEndpoint = cdpEndpoint;
-            // Force browser reconnection by clearing the promise
-            this._browserPromise = undefined;
-        }
-        finally {
-            this._reconnecting = false;
-        }
-    }
-    async _doObtainBrowser() {
-        const currentEndpoint = this._currentCdpEndpoint;
-        if (!currentEndpoint) {
-            testDebug(`No CDP endpoint set (reconnecting: ${this._reconnecting})`);
-            throw new Error('No CDP endpoint set. Use the browser_connect_roxy tool to connect to RoxyBrowser first. ' +
-                'Example: {"name": "browser_connect_roxy", "arguments": {"cdpEndpoint": "ws://127.0.0.1:PORT/devtools/browser/ID"}}');
-        }
-        testDebug(`Connecting to CDP endpoint: ${currentEndpoint} (reconnecting: ${this._reconnecting})`);
-        try {
-            const browser = await playwright.chromium.connectOverCDP(currentEndpoint);
-            testDebug(`Successfully connected to browser via CDP`);
-            return browser;
-        }
-        catch (error) {
-            testDebug(`Failed to connect to CDP endpoint: ${error.message}`);
-            throw new Error(`Failed to connect to RoxyBrowser at ${currentEndpoint}: ${error.message}`);
-        }
-    }
-    async _doCreateContext(browser) {
-        const context = this.config.browser.isolated ? await browser.newContext() : browser.contexts()[0];
-        testDebug(`Created browser context (isolated: ${this.config.browser.isolated})`);
-        return context;
-    }
-    getCurrentCdpEndpoint() {
-        return this._currentCdpEndpoint;
-    }
-}
-class RemoteContextFactory extends BaseContextFactory {
-    constructor(config) {
-        super('remote', config);
-    }
-    async _doObtainBrowser() {
-        const url = new URL(this.config.browser.remoteEndpoint);
-        url.searchParams.set('browser', this.config.browser.browserName);
-        if (this.config.browser.launchOptions)
-            url.searchParams.set('launch-options', JSON.stringify(this.config.browser.launchOptions));
-        return playwright[this.config.browser.browserName].connect(String(url));
-    }
-    async _doCreateContext(browser) {
-        return browser.newContext();
-    }
-}
-class PersistentContextFactory {
-    config;
-    name = 'persistent';
-    description = 'Create a new persistent browser context';
-    _userDataDirs = new Set();
-    constructor(config) {
-        this.config = config;
-    }
-    async createContext(clientInfo) {
-        await injectCdpPort(this.config.browser);
-        testDebug('create browser context (persistent)');
-        const userDataDir = this.config.browser.userDataDir ?? await this._createUserDataDir(clientInfo.rootPath);
-        const tracesDir = await startTraceServer(this.config, clientInfo.rootPath);
-        this._userDataDirs.add(userDataDir);
-        testDebug('lock user data dir', userDataDir);
-        const browserType = playwright[this.config.browser.browserName];
-        for (let i = 0; i < 5; i++) {
-            try {
-                const browserContext = await browserType.launchPersistentContext(userDataDir, {
-                    tracesDir,
-                    ...this.config.browser.launchOptions,
-                    ...this.config.browser.contextOptions,
-                    handleSIGINT: false,
-                    handleSIGTERM: false,
-                });
-                const close = () => this._closeBrowserContext(browserContext, userDataDir);
-                return { browserContext, close };
-            }
-            catch (error) {
-                if (error.message.includes('Executable doesn\'t exist'))
-                    throw new Error(`Browser specified in your config is not installed. Either install it (likely) or change the config.`);
-                if (error.message.includes('ProcessSingleton') || error.message.includes('Invalid URL')) {
-                    // User data directory is already in use, try again.
-                    await new Promise(resolve => setTimeout(resolve, 1000));
-                    continue;
-                }
-                throw error;
-            }
-        }
-        throw new Error(`Browser is already in use for ${userDataDir}, use --isolated to run multiple instances of the same browser`);
-    }
-    async _closeBrowserContext(browserContext, userDataDir) {
-        testDebug('close browser context (persistent)');
-        testDebug('release user data dir', userDataDir);
-        await browserContext.close().catch(() => { });
-        this._userDataDirs.delete(userDataDir);
-        testDebug('close browser context complete (persistent)');
-    }
-    async _createUserDataDir(rootPath) {
-        const dir = process.env.PWMCP_PROFILES_DIR_FOR_TEST ?? registryDirectory;
-        const browserToken = this.config.browser.launchOptions?.channel ?? this.config.browser?.browserName;
-        // Hesitant putting hundreds of files into the user's workspace, so using it for hashing instead.
-        const rootPathToken = rootPath ? `-${createHash(rootPath)}` : '';
-        const result = path.join(dir, `mcp-${browserToken}${rootPathToken}`);
-        await fs.promises.mkdir(result, { recursive: true });
-        return result;
-    }
-}
-async function injectCdpPort(browserConfig) {
-    if (browserConfig.browserName === 'chromium')
-        browserConfig.launchOptions.cdpPort = await findFreePort();
-}
-async function findFreePort() {
-    return new Promise((resolve, reject) => {
-        const server = net.createServer();
-        server.listen(0, () => {
-            const { port } = server.address();
-            server.close(() => resolve(port));
-        });
-        server.on('error', reject);
-    });
-}
-async function startTraceServer(config, rootPath) {
-    if (!config.saveTrace)
-        return undefined;
-    const tracesDir = await outputFile(config, rootPath, `traces-${Date.now()}`);
-    const server = await startTraceViewerServer();
-    const urlPrefix = server.urlPrefix('human-readable');
-    const url = urlPrefix + '/trace/index.html?trace=' + tracesDir + '/trace.json';
-    // eslint-disable-next-line no-console
-    console.error('\nTrace viewer listening on ' + url);
-    return tracesDir;
-}