moltbrowser-mcp-server 1.0.0

package/cli.js

@@ -0,0 +1,24 @@
+#!/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.
+ */
+
+const { program } = require('playwright-core/lib/utilsBundle');
+const { decorateCommand } = require('playwright/lib/mcp/program');
+
+const packageJSON = require('./package.json');
+const p = program.version('Version ' + packageJSON.version).name('Playwright MCP');
+decorateCommand(p, packageJSON.version)
+void program.parseAsync(process.argv);

package/config.d.ts

@@ -0,0 +1,241 @@
+/**
+ * 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 =
+  'config' |
+  'core' |
+  'core-navigation' |
+  'core-tabs' |
+  'core-input' |
+  'core-install' |
+  'network' |
+  'pdf' |
+  'storage' |
+  'testing' |
+  'vision' |
+  'devtools';
+
+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;
+
+    /**
+     * CDP headers to send with the connect request.
+     */
+    cdpHeaders?: Record<string, string>;
+
+    /**
+     * Timeout in milliseconds for connecting to CDP endpoint. Defaults to 30000 (30 seconds). Pass 0 to disable timeout.
+     */
+    cdpTimeout?: number;
+
+    /**
+     * Remote endpoint to connect to an existing Playwright server.
+     */
+    remoteEndpoint?: string;
+
+    /**
+     * Paths to TypeScript files to add as initialization scripts for Playwright page.
+     */
+    initPage?: string[];
+
+    /**
+     * Paths to JavaScript files to add as initialization scripts.
+     * The scripts will be evaluated in every page before any of the page's scripts.
+     */
+    initScript?: string[];
+  },
+
+  /**
+   * Connect to a running browser instance (Edge/Chrome only). If specified, `browser`
+   * config is ignored.
+   * Requires the "Playwright MCP Bridge" browser extension to be installed.
+   */
+  extension?: boolean;
+
+  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;
+
+    /**
+     * The hosts this server is allowed to serve from. Defaults to the host server is bound to.
+     * This is not for CORS, but rather for the DNS rebinding protection.
+     */
+    allowedHosts?: string[];
+  },
+
+  /**
+   * List of enabled tool capabilities. Possible values:
+   *   - 'core': Core browser automation features.
+   *   - 'pdf': PDF generation and manipulation.
+   *   - 'vision': Coordinate-based interactions.
+   *   - 'devtools': Developer tools features.
+   */
+  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;
+
+  /**
+   * If specified, saves the Playwright video of the session into the output directory.
+   */
+  saveVideo?: {
+    width: number;
+    height: number;
+  };
+
+  /**
+   * Reuse the same browser context between all connected HTTP clients.
+   */
+  sharedBrowserContext?: boolean;
+
+  /**
+   * Secrets are used to prevent LLM from getting sensitive data while
+   * automating scenarios such as authentication.
+   * Prefer the browser.contextOptions.storageState over secrets file as a more secure alternative.
+   */
+  secrets?: Record<string, string>;
+
+  /**
+   * The directory to save output files.
+   */
+  outputDir?: string;
+
+  /**
+   * Whether to save snapshots, console messages, network logs and other session logs to a file or to the standard output. Defaults to "stdout".
+   */
+  outputMode?: 'file' | 'stdout';
+
+  console?: {
+    /**
+     * The level of console messages to return. Each level includes the messages of more severe levels. Defaults to "info".
+     */
+    level?: 'error' | 'warning' | 'info' | 'debug';
+  },
+
+  network?: {
+    /**
+     * List of origins to allow the browser to request. Default is to allow all. Origins matching both `allowedOrigins` and `blockedOrigins` will be blocked.
+     *
+     * Supported formats:
+     * - Full origin: `https://example.com:8080` - matches only that origin
+     * - Wildcard port: `http://localhost:*` - matches any port on localhost with http protocol
+     */
+    allowedOrigins?: string[];
+
+    /**
+     * List of origins to block the browser to request. Origins matching both `allowedOrigins` and `blockedOrigins` will be blocked.
+     *
+     * Supported formats:
+     * - Full origin: `https://example.com:8080` - matches only that origin
+     * - Wildcard port: `http://localhost:*` - matches any port on localhost with http protocol
+     */
+    blockedOrigins?: string[];
+  };
+
+  /**
+   * Specify the attribute to use for test ids, defaults to "data-testid".
+   */
+  testIdAttribute?: string;
+
+  timeouts?: {
+    /*
+     * Configures default action timeout: https://playwright.dev/docs/api/class-page#page-set-default-timeout. Defaults to 5000ms.
+     */
+    action?: number;
+
+    /*
+     * Configures default navigation timeout: https://playwright.dev/docs/api/class-page#page-set-default-navigation-timeout. Defaults to 60000ms.
+     */
+    navigation?: number;
+  };
+
+  /**
+   * 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';
+
+  snapshot?: {
+    /**
+     * When taking snapshots for responses, specifies the mode to use.
+     */
+    mode?: 'incremental' | 'full' | 'none';
+  };
+
+  /**
+   * Whether to allow file uploads from anywhere on the file system.
+   * By default (false), file uploads are restricted to paths within the MCP roots only.
+   */
+  allowUnrestrictedFileAccess?: boolean;
+
+  /**
+   * Specify the language to use for code generation.
+   */
+  codegen?: 'typescript' | 'none';
+};

package/hub-cli.js

@@ -0,0 +1,72 @@
+#!/usr/bin/env node
+/**
+ * Playwright WebMCP Hub — CLI Entry Point
+ *
+ * Starts the proxy MCP server that wraps upstream Playwright MCP
+ * with WebMCP Hub integration for dynamic, per-site tools.
+ *
+ * Usage:
+ *   npx moltbrowser-mcp [options]
+ *
+ * Hub options:
+ *   --hub-url=<url>        Override hub URL (default: https://webmcp-hub.com)
+ *   --hub-api-key=<key>    API key for hub write operations (also HUB_API_KEY env)
+ *   --no-hub               Disable hub integration (behaves as vanilla Playwright MCP)
+ *
+ * All standard Playwright MCP options are also supported and passed through:
+ *   --browser=<name>       Browser to use (chromium, firefox, webkit, chrome, msedge)
+ *   --headless             Run in headless mode
+ *   --caps=<list>          Comma-separated list of capabilities
+ *   --config=<path>        Path to config JSON file
+ *   --port=<number>        Port for SSE transport
+ *   --host=<host>          Host for SSE transport
+ *   etc.
+ */
+
+const { startProxy } = require('./src/proxy-server.js');
+const hubClient = require('./src/hub-client.js');
+
+// Parse our custom args, pass the rest through to upstream
+const args = process.argv.slice(2);
+
+let noHub = false;
+const upstreamArgs = [];
+
+for (const arg of args) {
+  if (arg === '--no-hub') {
+    noHub = true;
+  } else if (arg.startsWith('--hub-url=')) {
+    process.env.HUB_URL = arg.split('=').slice(1).join('=');
+  } else if (arg.startsWith('--hub-api-key=')) {
+    process.env.HUB_API_KEY = arg.split('=').slice(1).join('=');
+  } else {
+    // Pass through to upstream Playwright MCP
+    upstreamArgs.push(arg);
+  }
+}
+
+(async () => {
+  let keyWarning = null;
+
+  if (!noHub) {
+    if (!process.env.HUB_API_KEY) {
+      keyWarning = 'No HUB_API_KEY is configured. Contribution and reading your own configs and tools will fail until you add one. Get a free API key at https://www.webmcp-hub.com and add it to your MCP config.';
+      process.stderr.write(`[moltbrowser-mcp] Warning: ${keyWarning}\n`);
+    } else {
+      const verification = await hubClient.verifyApiKey();
+      if (verification.unreachable) {
+        process.stderr.write('[moltbrowser-mcp] Warning: Hub unreachable, could not verify API key. Proceeding anyway.\n');
+      } else if (!verification.valid) {
+        keyWarning = `Your HUB_API_KEY is invalid or expired (${verification.error}). Contribution and reading your own configs and tools will fail until you fix it. Check or regenerate your key at https://www.webmcp-hub.com.`;
+        process.stderr.write(`[moltbrowser-mcp] Warning: ${keyWarning}\n`);
+      } else {
+        process.stderr.write(`[moltbrowser-mcp] Authenticated as ${verification.username}.\n`);
+      }
+    }
+  }
+
+  await startProxy({ upstreamArgs, noHub, keyWarning });
+})().catch(err => {
+  process.stderr.write(`[moltbrowser-mcp] Fatal error: ${err.message}\n${err.stack}\n`);
+  process.exit(1);
+});

package/index.d.ts

@@ -0,0 +1,23 @@
+#!/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';
+import type { BrowserContext } from 'playwright';
+
+export declare function createConnection(config?: Config, contextGetter?: () => Promise<BrowserContext>): Promise<Server>;
+export {};

package/index.js

@@ -0,0 +1,19 @@
+#!/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.
+ */
+
+const { createConnection } = require('playwright/lib/mcp/index');
+module.exports = { createConnection };

package/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "moltbrowser-mcp-server",
+  "version": "1.0.0",
+  "description": "Playwright MCP with WebMCP Hub integration — dynamic, per-site tools for browser agents",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Joakim-Sael/moltbrowser-mcp.git"
+  },
+  "homepage": "https://webmcp-hub.com",
+  "engines": {
+    "node": ">=18"
+  },
+  "author": {
+    "name": "Joakim Saelemyr"
+  },
+  "license": "Apache-2.0",
+  "files": [
+    "index.js",
+    "index.d.ts",
+    "config.d.ts",
+    "cli.js",
+    "hub-cli.js",
+    "src/**/*.js",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "lint": "node update-readme.js",
+    "test": "playwright test",
+    "ctest": "playwright test --project=chrome",
+    "ftest": "playwright test --project=firefox",
+    "wtest": "playwright test --project=webkit",
+    "build": "echo OK",
+    "npm-publish": "npm run lint && npm run test && npm publish"
+  },
+  "exports": {
+    "./package.json": "./package.json",
+    ".": {
+      "types": "./index.d.ts",
+      "default": "./index.js"
+    }
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.26.0",
+    "playwright": "^1.58.2",
+    "playwright-core": "^1.58.2"
+  },
+  "bin": {
+    "playwright-mcp": "cli.js",
+    "moltbrowser-mcp": "hub-cli.js"
+  }
+}