@n8n/mcp-browser 0.1.0-rc1

package/LICENSE.md

@@ -0,0 +1,88 @@
+# License
+
+Portions of this software are licensed as follows:
+
+- Content of branches other than the main branch (i.e. "master") are not licensed.
+- Source code files that contain ".ee." in their filename or ".ee" in their dirname are NOT licensed under
+  the Sustainable Use License.
+  To use source code files that contain ".ee." in their filename or ".ee" in their dirname you must hold a
+	valid n8n Enterprise License specifically allowing you access to such source code files and as defined
+	in "LICENSE_EE.md".
+- All third party components incorporated into the n8n Software are licensed under the original license
+  provided by the owner of the applicable component.
+- Content outside of the above mentioned files or restrictions is available under the "Sustainable Use
+  License" as defined below.
+
+## Sustainable Use License
+
+Version 1.0
+
+### Acceptance
+
+By using the software, you agree to all of the terms and conditions below.
+
+### Copyright License
+
+The licensor grants you a non-exclusive, royalty-free, worldwide, non-sublicensable, non-transferable license
+to use, copy, distribute, make available, and prepare derivative works of the software, in each case subject
+to the limitations below.
+
+### Limitations
+
+You may use or modify the software only for your own internal business purposes or for non-commercial or
+personal use. You may distribute the software or provide it to others only if you do so free of charge for
+non-commercial purposes. You may not alter, remove, or obscure any licensing, copyright, or other notices of
+the licensor in the software. Any use of the licensor’s trademarks is subject to applicable law.
+
+### Patents
+
+The licensor grants you a license, under any patent claims the licensor can license, or becomes able to
+license, to make, have made, use, sell, offer for sale, import and have imported the software, in each case
+subject to the limitations and conditions in this license. This license does not cover any patent claims that
+you cause to be infringed by modifications or additions to the software. If you or your company make any
+written claim that the software infringes or contributes to infringement of any patent, your patent license
+for the software granted under these terms ends immediately. If your company makes such a claim, your patent
+license ends immediately for work on behalf of your company.
+
+### Notices
+
+You must ensure that anyone who gets a copy of any part of the software from you also gets a copy of these
+terms. If you modify the software, you must include in any modified copies of the software a prominent notice
+stating that you have modified the software.
+
+### No Other Rights
+
+These terms do not imply any licenses other than those expressly granted in these terms.
+
+### Termination
+
+If you use the software in violation of these terms, such use is not licensed, and your license will
+automatically terminate. If the licensor provides you with a notice of your violation, and you cease all
+violation of this license no later than 30 days after you receive that notice, your license will be reinstated
+retroactively. However, if you violate these terms after such reinstatement, any additional violation of these
+terms will cause your license to terminate automatically and permanently.
+
+### No Liability
+
+As far as the law allows, the software comes as is, without any warranty or condition, and the licensor will
+not be liable to you for any damages arising out of these terms or the use or nature of the software, under
+any kind of legal claim.
+
+### Definitions
+
+The “licensor” is the entity offering these terms.
+
+The “software” is the software the licensor makes available under these terms, including any portion of it.
+
+“You” refers to the individual or entity agreeing to these terms.
+
+“Your company” is any legal entity, sole proprietorship, or other kind of organization that you work for, plus
+all organizations that have control over, are under the control of, or are under common control with that
+organization. Control means ownership of substantially all the assets of an entity, or the power to direct its
+management and policies by vote, contract, or otherwise. Control can be direct or indirect.
+
+“Your license” is the license granted to you for the software under these terms.
+
+“Use” means anything you do with the software requiring your license.
+
+“Trademark” means trademarks, service marks, and similar rights.

package/README.md

@@ -0,0 +1,175 @@
+# @n8n/mcp-browser
+
+MCP server that gives AI agents full control over Chrome. Connects to the
+user's real installed browser via the **n8n AI Browser Bridge** extension, using
+their actual profile, cookies, and sessions. Action tools return an
+accessibility snapshot with every response for single-roundtrip interaction.
+
+See [spec/browser-mcp.md](spec/browser-mcp.md) for the full feature spec and
+[spec/technical-spec.md](spec/technical-spec.md) for the technical design.
+
+## Usage
+
+### Library mode
+
+```typescript
+import { createBrowserTools } from '@n8n/mcp-browser';
+
+const { tools, connection } = createBrowserTools({
+  defaultBrowser: 'chrome',
+  headless: false,
+  viewport: { width: 1280, height: 720 },
+});
+
+// Register tools on any MCP server
+for (const tool of tools) {
+  server.tool(tool.name, tool.description, tool.inputSchema, tool.execute);
+}
+
+// Cleanup on shutdown
+process.on('SIGTERM', () => connection.shutdown());
+```
+
+### Standalone mode
+
+```bash
+# HTTP transport (default)
+npx @n8n/mcp-browser --browser chrome --transport http --port 3100
+
+# stdio transport
+npx @n8n/mcp-browser --browser chrome --transport stdio
+```
+
+### CLI flags
+
+| Flag | Alias | Env var | Default | Description |
+|------|-------|---------|---------|-------------|
+| `--browser` | `-b` | `N8N_MCP_BROWSER_DEFAULT_BROWSER` | `chrome` | Default browser |
+| `--headless` | | `N8N_MCP_BROWSER_HEADLESS` | `false` | Headless mode |
+| `--viewport` | | `N8N_MCP_BROWSER_VIEWPORT` | `1280x720` | Viewport (WxH) |
+| `--transport` | `-t` | `N8N_MCP_BROWSER_TRANSPORT` | `http` | `http` or `stdio` |
+| `--port` | `-p` | `N8N_MCP_BROWSER_PORT` | `3100` | HTTP port |
+
+CLI flags take precedence over environment variables.
+
+## Prerequisites
+
+1. **Chrome** (or Brave/Edge) installed
+2. **n8n AI Browser Bridge** extension loaded in Chrome:
+   - Open `chrome://extensions`
+   - Enable Developer mode
+   - Click "Load unpacked" and select the `mcp-browser-extension` directory
+
+## Testing with AI clients
+
+Start the server:
+
+```bash
+npx @n8n/mcp-browser --transport http --port 3100
+```
+
+Or from the monorepo:
+
+```bash
+npx tsx packages/@n8n/mcp-browser/src/server.ts --transport http --port 3100
+```
+
+Then point your client at `http://localhost:3100/mcp`:
+
+<details>
+<summary>Claude Desktop</summary>
+
+Add to `~/Library/Application Support/Claude/claude_desktop_config.json`
+(macOS) or `%APPDATA%\Claude\claude_desktop_config.json` (Windows):
+
+```json
+{
+  "mcpServers": {
+    "n8n-browser": {
+      "url": "http://localhost:3100/mcp"
+    }
+  }
+}
+```
+
+</details>
+
+<details>
+<summary>Claude Code</summary>
+
+Add to `.mcp.json` in your project root (per-project) or
+`~/.claude/mcp.json` (global):
+
+```json
+{
+  "mcpServers": {
+    "n8n-browser": {
+      "url": "http://localhost:3100/mcp"
+    }
+  }
+}
+```
+
+Or add interactively with `/mcp add`.
+
+</details>
+
+<details>
+<summary>Cursor</summary>
+
+Add to `.cursor/mcp.json` in your project root:
+
+```json
+{
+  "mcpServers": {
+    "n8n-browser": {
+      "url": "http://localhost:3100/mcp"
+    }
+  }
+}
+```
+
+</details>
+
+<details>
+<summary>Windsurf</summary>
+
+Add to `~/.codeium/windsurf/mcp_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "n8n-browser": {
+      "url": "http://localhost:3100/mcp"
+    }
+  }
+}
+```
+
+</details>
+
+<details>
+<summary>VS Code (GitHub Copilot)</summary>
+
+Add to `.vscode/mcp.json` in your project root. Note: VS Code uses `"servers"`
+instead of `"mcpServers"`.
+
+```json
+{
+  "servers": {
+    "n8n-browser": {
+      "url": "http://localhost:3100/mcp"
+    }
+  }
+}
+```
+
+</details>
+
+## Development
+
+```bash
+pnpm dev    # start standalone MCP server with hot reload
+pnpm build  # build for production
+pnpm test   # run tests
+```

package/dist/adapters/playwright.d.ts

@@ -0,0 +1,72 @@
+import type { ClickOptions, ConnectConfig, ConsoleEntry, Cookie, ElementTarget, ModalState, NavigateResult, NetworkEntry, PageInfo, ResolvedConfig, ScreenshotOptions, ScrollOptions, SnapshotResult, TypeOptions, WaitOptions } from '../types';
+export declare class PlaywrightAdapter {
+    readonly name = "playwright";
+    private resolvedConfig;
+    private browser?;
+    private context?;
+    private pageStates;
+    private relay?;
+    private pendingActivation?;
+    constructor(config: ResolvedConfig);
+    launch(config: ConnectConfig): Promise<void>;
+    close(): Promise<void>;
+    newPage(url?: string): Promise<PageInfo>;
+    closePage(pageId: string): Promise<void>;
+    focusPage(pageId: string): Promise<void>;
+    listPages(): Promise<PageInfo[]>;
+    listTabs(): Promise<PageInfo[]>;
+    listTabSessionIds(): string[];
+    listTabIds(): Promise<string[]>;
+    navigate(pageId: string, url: string, waitUntil?: 'load' | 'domcontentloaded' | 'networkidle'): Promise<NavigateResult>;
+    back(pageId: string): Promise<NavigateResult>;
+    forward(pageId: string): Promise<NavigateResult>;
+    reload(pageId: string, waitUntil?: 'load' | 'domcontentloaded' | 'networkidle'): Promise<NavigateResult>;
+    click(pageId: string, target: ElementTarget, options?: ClickOptions): Promise<void>;
+    type(pageId: string, target: ElementTarget, text: string, options?: TypeOptions): Promise<void>;
+    select(pageId: string, target: ElementTarget, values: string[]): Promise<string[]>;
+    hover(pageId: string, target: ElementTarget): Promise<void>;
+    press(pageId: string, keys: string): Promise<void>;
+    drag(pageId: string, from: ElementTarget, to: ElementTarget): Promise<void>;
+    scroll(pageId: string, target?: ElementTarget, options?: ScrollOptions): Promise<void>;
+    upload(pageId: string, target: ElementTarget | undefined, files: string[]): Promise<void>;
+    dialog(pageId: string, action: 'accept' | 'dismiss', text?: string): Promise<string>;
+    screenshot(pageId: string, target?: ElementTarget, options?: ScreenshotOptions): Promise<string>;
+    snapshot(pageId: string, target?: ElementTarget): Promise<SnapshotResult>;
+    getText(pageId: string, target?: ElementTarget): Promise<string>;
+    evaluate(pageId: string, script: string): Promise<unknown>;
+    getConsole(pageId: string, level?: string, clear?: boolean): Promise<ConsoleEntry[]>;
+    getConsoleSummary(pageId: string): {
+        errors: number;
+        warnings: number;
+    };
+    pdf(pageId: string, options?: {
+        format?: string;
+        landscape?: boolean;
+    }): Promise<{
+        data: string;
+        pages: number;
+    }>;
+    getNetwork(pageId: string, filter?: string, clear?: boolean): Promise<NetworkEntry[]>;
+    wait(pageId: string, options: WaitOptions): Promise<number>;
+    getCookies(pageId: string, url?: string): Promise<Cookie[]>;
+    setCookies(pageId: string, cookies: Cookie[]): Promise<void>;
+    clearCookies(pageId: string): Promise<void>;
+    getStorage(pageId: string, kind: 'local' | 'session'): Promise<Record<string, string>>;
+    setStorage(pageId: string, kind: 'local' | 'session', data: Record<string, string>): Promise<void>;
+    clearStorage(pageId: string, kind: 'local' | 'session'): Promise<void>;
+    waitForCompletion<T>(pageId: string, action: () => Promise<T>): Promise<T>;
+    getModalStates(pageId: string): ModalState[];
+    getContent(pageId: string, selector?: string): Promise<{
+        html: string;
+        url: string;
+    }>;
+    resolveRef(pageId: string, ref: string): Promise<unknown>;
+    private requireContext;
+    private requirePage;
+    private ensurePage;
+    private findPageState;
+    private trackPage;
+    getPageUrl(pageId: string): string | undefined;
+    private resolveLocator;
+    private globToRegex;
+}