agent-browser-priv 0.27.3-priv.7 → 0.28.0-priv.1

package/README.md

@@ -468,6 +468,7 @@ agent-browser upgrade                 # Upgrade agent-browser to the latest vers
 agent-browser doctor                  # Diagnose the install and auto-clean stale daemon files
 agent-browser doctor --fix            # Also run destructive repairs
 agent-browser doctor --offline --quick  # Skip network probes and the live launch test
+agent-browser mcp                     # Start an MCP stdio server
 ```
 
 `doctor` checks your environment, browser backend install, daemon state,
@@ -488,6 +489,74 @@ agent-browser skills path [name]      # Print skill directory path
 
 Serves bundled skill content that always matches the installed CLI version. AI agents use this to get current instructions rather than relying on cached copies. Set `AGENT_BROWSER_SKILLS_DIR` to override the skills directory path.
 
+### MCP Server
+
+```bash
+agent-browser mcp
+agent-browser mcp --tools all
+agent-browser mcp --tools core,network,react
+```
+
+Starts a Model Context Protocol server over stdio. MCP clients launch this command as a subprocess and exchange newline-delimited JSON-RPC on stdin and stdout. The server defaults to MCP protocol 2025-11-25 and accepts older supported client protocol versions during initialization.
+
+The default tools profile is `core`, which keeps MCP context small for everyday browser automation. Use `--tools all` for the full typed CLI parity surface, or combine profiles with commas, such as `--tools core,network,react`.
+
+Profiles:
+
+- `core` — Default. Navigation, snapshots, interaction, waits, reads, screenshots, JavaScript eval, close, tab basics, and profile discovery
+- `network` — Network routes, request inspection, HAR, headers, credentials, offline
+- `state` — Cookies, storage, auth, saved state, sessions, profiles, skills
+- `debug` — Console/errors, tracing, profiling, recording, clipboard, plugins, doctor, dashboard, install, upgrade, chat, diff, batch, confirm/deny
+- `tabs` — Back/forward/reload, tabs, windows, frames, dialogs
+- `react` — React tree/inspect/renders/suspense, vitals, pushstate
+- `mobile` — Viewport/device/geolocation/media, touch, swipe, mouse, keyboard
+- `all` — Every MCP tool, including the full typed CLI parity surface
+
+Common tools include:
+
+- `agent_browser_tools_profiles`
+- `agent_browser_open`
+- `agent_browser_snapshot`
+- `agent_browser_click`
+- `agent_browser_fill`
+- `agent_browser_type`
+- `agent_browser_press`
+- `agent_browser_wait_for_selector`
+- `agent_browser_screenshot`
+- `agent_browser_get_url`
+- `agent_browser_eval`
+- `agent_browser_close`
+
+Each tool has typed fields such as `url`, `selector`, `text`, `key`, and `session`, so MCP clients show meaningful approval prompts instead of raw command arrays. Each tool also accepts `extraArgs` for advanced CLI flags and exact CLI parity. Tool discovery is paginated and includes read-only/open-world annotations so modern MCP clients can load the large typed surface incrementally.
+
+Example MCP client config:
+
+```json
+{
+  "mcpServers": {
+    "agent-browser": {
+      "command": "agent-browser",
+      "args": ["mcp"]
+    }
+  }
+}
+```
+
+Full parity MCP client config:
+
+```json
+{
+  "mcpServers": {
+    "agent-browser": {
+      "command": "agent-browser",
+      "args": ["mcp", "--tools", "all"]
+    }
+  }
+}
+```
+
+Tool invocations use the same config files and environment variables as the CLI. Use `session` in the tool arguments, or set `AGENT_BROWSER_SESSION`, to isolate browser state.
+
 ## Authentication
 
 agent-browser provides multiple ways to persist login sessions so you don't re-authenticate every run.
@@ -646,6 +715,7 @@ agent-browser --session-name secure open example.com
 agent-browser includes security features for safe AI agent deployments. All features are opt-in, and existing workflows are unaffected until you explicitly enable a feature:
 
 - **Authentication Vault**: Store credentials locally (always encrypted), reference by name. The LLM never sees passwords. `auth login` navigates with `load` and then waits for login form selectors to appear (SPA-friendly, timeout follows the default action timeout). A key is auto-generated at `~/.agent-browser/.encryption-key` if `AGENT_BROWSER_ENCRYPTION_KEY` is not set: `echo "pass" | agent-browser auth save github --url https://github.com/login --username user --password-stdin` then `agent-browser auth login github`
+- **Plugin System**: Extend agent-browser with external executable plugins. Plugins run out-of-process over the `agent-browser.plugin.v1` stdio JSON protocol and declare capabilities such as `credential.read`, `browser.provider`, `launch.mutate`, or `command.run`.
 - **Content Boundary Markers**: Wrap page output in delimiters so LLMs can distinguish tool output from untrusted content: `--content-boundaries`
 - **Domain Allowlist**: Restrict navigation to trusted domains (wildcards like `*.example.com` also match the bare domain): `--allowed-domains "example.com,*.example.com"`. Sub-resource requests (scripts, images, fetch) and WebSocket/EventSource connections to non-allowed domains are also blocked. Include any CDN domains your target pages depend on (e.g., `*.cdn.example.com`).
 - **Action Policy**: Gate destructive actions with a static policy file: `--action-policy ./policy.json`
@@ -660,9 +730,97 @@ agent-browser includes security features for safe AI agent deployments. All feat
 | `AGENT_BROWSER_ACTION_POLICY`       | Path to action policy JSON file          |
 | `AGENT_BROWSER_CONFIRM_ACTIONS`     | Action categories requiring confirmation |
 | `AGENT_BROWSER_CONFIRM_INTERACTIVE` | Enable interactive confirmation prompts  |
+| `AGENT_BROWSER_PLUGINS`             | JSON plugin registry override            |
 
 See [Security documentation](https://agent-browser.dev/security) for details.
 
+### Plugin System
+
+Plugins let third-party tools integrate without becoming built-in agent-browser dependencies. Add a plugin from npm or GitHub:
+
+```bash
+agent-browser plugin add agent-browser-plugin-captcha
+agent-browser plugin add @company/agent-browser-plugin-vault --name vault
+agent-browser plugin add org/agent-browser-plugin-cloud-browser
+```
+
+References are resolved by shape: `name` uses npm, `@scope/name` uses npm, and `owner/repo` uses GitHub. `plugin add` writes `./agent-browser.json` by default; use `--global` for `~/.agent-browser/config.json`.
+
+Plugin packages should support `plugin.manifest` so `plugin add` can discover their name and capabilities automatically. If a plugin does not support manifests, pass `--capability <name>` during add.
+
+Plugins can also be configured manually in `agent-browser.json`:
+
+```json
+{
+  "plugins": [
+    {
+      "name": "vault",
+      "command": "agent-browser-plugin-vault",
+      "capabilities": ["credential.read"]
+    },
+    {
+      "name": "cloud-browser",
+      "command": "agent-browser-plugin-cloud-browser",
+      "capabilities": ["browser.provider"]
+    },
+    {
+      "name": "stealth",
+      "command": "agent-browser-plugin-stealth",
+      "capabilities": ["launch.mutate"]
+    },
+    {
+      "name": "captcha",
+      "command": "agent-browser-plugin-captcha",
+      "capabilities": ["command.run", "captcha.solve"]
+    }
+  ]
+}
+```
+
+Inspect configured plugins:
+
+```bash
+agent-browser plugin list
+agent-browser plugin show vault
+```
+
+Use a credential provider plugin for one login:
+
+```bash
+agent-browser auth login my-app --credential-provider vault --item "My App"
+agent-browser auth login my-app --credential-provider vault --item "My App" --url https://app.example.com/login --username-selector "#email" --password-selector "#password" --submit-selector "button[type=submit]"
+```
+
+Use a browser provider plugin:
+
+```bash
+agent-browser --provider cloud-browser open https://example.com
+```
+
+Use a launch mutator plugin for stealth or local launch customization. The plugin can append Chrome args, extensions, and init scripts before the browser starts:
+
+```bash
+agent-browser open https://example.com
+```
+
+Use a generic plugin command for domain-specific tools such as CAPTCHA solvers:
+
+```bash
+agent-browser plugin run captcha captcha.solve --payload '{"siteKey":"...","url":"https://example.com"}'
+```
+
+The protocol request always includes `protocol`, `type`, `capability`, and `request`. A credential plugin receives `credential.resolve`, a browser provider receives `browser.launch`, a launch mutator receives `launch.mutate`, and generic commands receive the supplied request type. `plugin run` is for `command.run` and custom capabilities; core capabilities and protocol request types use their dedicated command paths. agent-browser keeps browser automation, redaction-sensitive output, and policy enforcement in core.
+
+Gate plugin access by capability action:
+
+```bash
+agent-browser --confirm-actions plugin:vault:credential.read auth login my-app --credential-provider vault --item "My App"
+agent-browser --confirm-actions plugin:cloud-browser:browser.provider --provider cloud-browser open https://example.com
+agent-browser --confirm-actions plugin:stealth:launch.mutate open https://example.com
+```
+
+Do not put vault tokens or passwords in plugin command args. Use the vault vendor's own login/session mechanism or environment outside agent-browser config.
+
 ## Snapshot Options
 
 The `snapshot` command supports filtering to reduce output size:
@@ -728,7 +886,7 @@ This is useful for multimodal AI models that can reason about visual layout, unl
 | `--ignore-https-errors` | Ignore HTTPS certificate errors (useful for self-signed certs) |
 | `--allow-file-access` | Allow file:// URLs to access local files (Chromium only) |
 | `--hide-scrollbars <bool>` | Hide native scrollbars in headless Chromium screenshots, enabled by default (or `AGENT_BROWSER_HIDE_SCROLLBARS` env) |
-| `-p, --provider <name>` | Cloud browser provider (or `AGENT_BROWSER_PROVIDER` env) |
+| `-p, --provider <name>` | Browser provider, including configured `browser.provider` plugins (or `AGENT_BROWSER_PROVIDER` env) |
 | `--device <name>` | iOS device name, e.g. "iPhone 15 Pro" (or `AGENT_BROWSER_IOS_DEVICE` env) |
 | `--json` | JSON output (for agents) |
 | `--annotate` | Annotated screenshot with numbered element labels (or `AGENT_BROWSER_ANNOTATE` env) |
@@ -859,7 +1017,14 @@ Create an `agent-browser.json` file to set persistent defaults instead of repeat
   "profile": "./browser-data",
   "userAgent": "my-agent/1.0",
   "hideScrollbars": false,
-  "ignoreHttpsErrors": true
+  "ignoreHttpsErrors": true,
+  "plugins": [
+    {
+      "name": "vault",
+      "command": "agent-browser-plugin-vault",
+      "capabilities": ["credential.read"]
+    }
+  ]
 }
 ```
 
@@ -870,7 +1035,7 @@ agent-browser --config ./ci-config.json open example.com
 AGENT_BROWSER_CONFIG=./ci-config.json agent-browser open example.com
 ```
 
-All options from the table above can be set in the config file using camelCase keys (e.g., `--executable-path` becomes `"executablePath"`, `--proxy-bypass` becomes `"proxyBypass"`). Unknown keys are ignored for forward compatibility.
+All options from the table above can be set in the config file using camelCase keys (e.g., `--executable-path` becomes `"executablePath"`, `--proxy-bypass` becomes `"proxyBypass"`). Plugins are configured with the `"plugins"` array shown above. Unknown keys are ignored for forward compatibility.
 
 A [JSON Schema](agent-browser.schema.json) is available for IDE autocomplete and validation. Add a `$schema` key to your config file to enable it:
 
@@ -1277,9 +1442,11 @@ The daemon starts automatically on first command and persists between commands f
 | Platform    | Binary      |
 | ----------- | ----------- |
 | macOS ARM64 | Native Rust |
+| macOS x64   | Native Rust |
 | Linux ARM64 | Native Rust |
 | Linux x64   | Native Rust |
-| Windows x64 | Native Rust |
+
+Windows release artifacts are temporarily disabled while the fork stabilizes its Patchright-first CI lane.
 
 ## Usage with AI Agents
 

package/bin/agent-browser.js

@@ -38,12 +38,7 @@ function getBinaryName() {
       osKey = 'darwin';
       break;
     case 'linux':
-      if (isMusl()) {
-        console.error('Error: agent-browser-priv does not publish musl Linux binaries.');
-        console.error('Use a glibc-based Linux environment or build locally with npm run build:native.');
-        process.exit(1);
-      }
-      osKey = 'linux';
+      osKey = isMusl() ? 'linux-musl' : 'linux';
       break;
     case 'win32':
       osKey = 'win32';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-browser-priv",
-  "version": "0.27.3-priv.7",
+  "version": "0.28.0-priv.1",
   "description": "Browser automation CLI for AI agents",
   "type": "module",
   "packageManager": "pnpm@11.1.3",
@@ -24,8 +24,8 @@
     "build:native": "pnpm run version:sync && cargo build --release --manifest-path cli/Cargo.toml && node scripts/copy-native.js",
     "build:linux": "pnpm run version:sync && docker compose -f docker/docker-compose.yml run --rm build-linux",
     "build:macos": "pnpm run version:sync && cargo build --release --manifest-path cli/Cargo.toml --target aarch64-apple-darwin && cp cli/target/aarch64-apple-darwin/release/agent-browser bin/agent-browser-priv-darwin-arm64",
-    "build:windows": "pnpm run version:sync && docker compose -f docker/docker-compose.yml run --rm build-windows",
-    "build:all-platforms": "pnpm run version:sync && (pnpm run build:linux & pnpm run build:windows & wait) && pnpm run build:macos",
+    "build:windows": "echo \"Windows builds are temporarily disabled\" && exit 0",
+    "build:all-platforms": "pnpm run version:sync && pnpm run build:linux && pnpm run build:macos",
     "build:docker": "docker build --platform linux/amd64 -t agent-browser-builder -f docker/Dockerfile.build .",
     "release": "pnpm run version:sync && pnpm run build:all-platforms",
     "postinstall": "node scripts/postinstall.js",

package/scripts/build-all-platforms.sh

@@ -1,7 +1,7 @@
 #!/bin/bash
 set -euo pipefail
 
-# Build agent-browser for all platforms using Docker
+# Build agent-browser release platforms using Docker
 # Usage: ./scripts/build-all-platforms.sh
 
 SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
@@ -14,7 +14,7 @@ GREEN='\033[0;32m'
 YELLOW='\033[1;33m'
 NC='\033[0m' # No Color
 
-echo -e "${YELLOW}Building agent-browser for all platforms...${NC}"
+echo -e "${YELLOW}Building agent-browser release platforms...${NC}"
 echo ""
 
 # Ensure output directory exists
@@ -63,12 +63,22 @@ build_target "x86_64-unknown-linux-gnu" "x86_64-unknown-linux-gnu.2.28" "agent-b
 # Linux ARM64
 build_target "aarch64-unknown-linux-gnu" "aarch64-unknown-linux-gnu.2.28" "agent-browser-priv-linux-arm64"
 
-# Windows x64
-build_target "x86_64-pc-windows-gnu" "x86_64-pc-windows-gnu" "agent-browser-priv-win32-x64.exe"
+# Windows x64 is temporarily disabled. Restore this line when Windows support
+# is re-enabled:
+# build_target "x86_64-pc-windows-gnu" "x86_64-pc-windows-gnu" "agent-browser-priv-win32-x64.exe"
+
+# macOS x64 (via zig for cross-compilation)
+build_target "x86_64-apple-darwin" "x86_64-apple-darwin" "agent-browser-priv-darwin-x64"
 
 # macOS ARM64 (via zig for cross-compilation)
 build_target "aarch64-apple-darwin" "aarch64-apple-darwin" "agent-browser-priv-darwin-arm64"
 
+# Linux musl x64 (Alpine)
+build_target "x86_64-unknown-linux-musl" "x86_64-unknown-linux-musl" "agent-browser-priv-linux-musl-x64"
+
+# Linux musl ARM64 (Alpine)
+build_target "aarch64-unknown-linux-musl" "aarch64-unknown-linux-musl" "agent-browser-priv-linux-musl-arm64"
+
 echo ""
 echo -e "${GREEN}Build complete!${NC}"
 echo ""

package/scripts/postinstall.js

@@ -5,8 +5,10 @@
  * 
  * Downloads the platform-specific native binary if not present.
  * On global installs, patches npm's bin entry to use the native binary directly:
- * - Windows: Overwrites .cmd/.ps1 shims
  * - Mac/Linux: Replaces symlink to point to native binary
+ *
+ * Windows npm binaries are temporarily disabled. The shim helpers remain below
+ * for a future re-enable.
  */
 
 import { existsSync, mkdirSync, chmodSync, createWriteStream, unlinkSync, writeFileSync, symlinkSync, lstatSync } from 'fs';
@@ -37,11 +39,15 @@ if (platform() === 'linux' && isMusl()) {
   process.exit(0);
 }
 
+if (platform() === 'win32') {
+  console.log('agent-browser-priv Windows npm binaries are temporarily disabled.');
+  console.log('Use Linux x64, Linux ARM64, or macOS ARM64 for the published package.');
+  process.exit(0);
+}
+
 // Platform detection
 const osKey = platform();
-// Windows ARM64 falls back to x64 binary (no native ARM64 build available).
-// x64 binaries run via Windows' built-in emulation on ARM64.
-const effectiveArch = platform() === 'win32' && arch() === 'arm64' ? 'x64' : arch();
+const effectiveArch = arch();
 const platformKey = `${osKey}-${effectiveArch}`;
 const ext = platform() === 'win32' ? '.exe' : '';
 const binaryName = `agent-browser-priv-${platformKey}${ext}`;
@@ -138,9 +144,6 @@ async function main() {
   }
 
   console.log(`Downloading native binary for ${platformKey}...`);
-  if (platform() === 'win32' && arch() === 'arm64') {
-    console.log(`  Note: Using x64 binary on ARM64 Windows (runs via emulation)`);
-  }
   console.log(`URL: ${DOWNLOAD_URL}`);
 
   try {
@@ -236,6 +239,7 @@ function showInstallReminder() {
  */
 async function fixGlobalInstallBin() {
   if (platform() === 'win32') {
+    // Unreachable while Windows npm binaries are disabled; kept for future re-enable.
     await fixWindowsShims();
   } else {
     await fixUnixSymlink();

package/scripts/update-homebrew-formula.mjs

@@ -0,0 +1,153 @@
+#!/usr/bin/env node
+
+import { createHash } from "node:crypto";
+import { writeFileSync } from "node:fs";
+import { get } from "node:https";
+
+const ASSETS = [
+  {
+    key: "darwinArm64",
+    name: "agent-browser-priv-darwin-arm64",
+  },
+  {
+    key: "linuxArm64",
+    name: "agent-browser-priv-linux-arm64",
+  },
+  {
+    key: "linuxX64",
+    name: "agent-browser-priv-linux-x64",
+  },
+];
+
+function argValue(name) {
+  const index = process.argv.indexOf(`--${name}`);
+  return index === -1 ? undefined : process.argv[index + 1];
+}
+
+const version = argValue("version");
+const formulaPath = argValue("formula");
+
+if (!version || !formulaPath) {
+  console.error("Usage: node scripts/update-homebrew-formula.mjs --version <version> --formula <path>");
+  process.exit(1);
+}
+
+function assetUrl(name) {
+  return `https://github.com/liuwen/agent-browser-priv/releases/download/v${version}/${name}`;
+}
+
+function fetchBuffer(url, redirects = 0) {
+  return new Promise((resolve, reject) => {
+    get(url, (response) => {
+      if ([301, 302, 303, 307, 308].includes(response.statusCode)) {
+        if (!response.headers.location || redirects > 5) {
+          reject(new Error(`Too many redirects for ${url}`));
+          response.resume();
+          return;
+        }
+        response.resume();
+        resolve(fetchBuffer(response.headers.location, redirects + 1));
+        return;
+      }
+
+      if (response.statusCode !== 200) {
+        reject(new Error(`GET ${url} returned HTTP ${response.statusCode}`));
+        response.resume();
+        return;
+      }
+
+      const chunks = [];
+      response.on("data", (chunk) => chunks.push(chunk));
+      response.on("end", () => resolve(Buffer.concat(chunks)));
+    }).on("error", reject);
+  });
+}
+
+async function withRetries(label, fn) {
+  let lastError;
+  for (let attempt = 1; attempt <= 5; attempt += 1) {
+    try {
+      return await fn();
+    } catch (error) {
+      lastError = error;
+      const delayMs = attempt * 2000;
+      console.error(`${label} failed on attempt ${attempt}: ${error.message}`);
+      if (attempt < 5) {
+        await new Promise((resolve) => setTimeout(resolve, delayMs));
+      }
+    }
+  }
+  throw lastError;
+}
+
+function sha256(buffer) {
+  return createHash("sha256").update(buffer).digest("hex");
+}
+
+function renderFormula(checksums) {
+  return `class AgentBrowser < Formula
+  desc "Browser automation CLI for AI agents with Patchright as the default backend"
+  homepage "https://github.com/liuwen/agent-browser-priv"
+  version "${version}"
+  license "Apache-2.0"
+
+  on_macos do
+    if Hardware::CPU.arm?
+      url "${assetUrl("agent-browser-priv-darwin-arm64")}"
+      sha256 "${checksums.darwinArm64}"
+    end
+  end
+
+  on_linux do
+    if Hardware::CPU.arm?
+      url "${assetUrl("agent-browser-priv-linux-arm64")}"
+      sha256 "${checksums.linuxArm64}"
+    elsif Hardware::CPU.intel?
+      url "${assetUrl("agent-browser-priv-linux-x64")}"
+      sha256 "${checksums.linuxX64}"
+    end
+  end
+
+  def install
+    unsupported = "agent-browser Homebrew binary is published for macOS ARM64 and Linux x86_64/ARM64"
+    odie unsupported unless supported_platform?
+
+    binary = if OS.mac? && Hardware::CPU.arm?
+      "agent-browser-priv-darwin-arm64"
+    elsif OS.linux? && Hardware::CPU.arm?
+      "agent-browser-priv-linux-arm64"
+    elsif OS.linux? && Hardware::CPU.intel?
+      "agent-browser-priv-linux-x64"
+    else
+      odie unsupported
+    end
+
+    bin.install binary => "agent-browser"
+    bin.install_symlink bin/"agent-browser" => "agent-browser-priv"
+  end
+
+  test do
+    assert_match version.to_s, shell_output("#{bin}/agent-browser --version")
+    assert_match version.to_s, shell_output("#{bin}/agent-browser-priv --version")
+  end
+
+  def supported_platform?
+    (OS.mac? && Hardware::CPU.arm?) || (OS.linux? && (Hardware::CPU.arm? || Hardware::CPU.intel?))
+  end
+end
+`;
+}
+
+const checksums = {};
+for (const asset of ASSETS) {
+  const url = assetUrl(asset.name);
+  const data = await withRetries(asset.name, () => fetchBuffer(url));
+  if (data.length < 100_000) {
+    throw new Error(`${asset.name} is too small (${data.length} bytes)`);
+  }
+  checksums[asset.key] = sha256(data);
+  console.log(`${asset.name}: ${checksums[asset.key]}`);
+}
+
+writeFileSync(formulaPath, renderFormula(checksums));
+console.log(`Updated ${formulaPath}`);

package/skill-data/core/SKILL.md

@@ -66,6 +66,29 @@ agent-browser screenshot result.png
 The browser stays running across commands so these feel like a single
 session. Use `agent-browser close` (or `close --all`) when you're done.
 
+## MCP integration
+
+For tools that support Model Context Protocol servers, start the stdio server:
+
+```bash
+agent-browser mcp
+agent-browser mcp --tools all
+agent-browser mcp --tools core,network,react
+```
+
+Configure the MCP client to launch `agent-browser` with `["mcp"]`. The server
+defaults to MCP protocol 2025-11-25 and accepts older supported client protocol
+versions during initialization. The default tools profile is `core`, which
+keeps MCP context small for everyday browser automation. Use `--tools all` for
+the full typed CLI parity surface, or combine profiles with commas, such as
+`--tools core,network,react`. Profiles are `core`, `network`, `state`, `debug`,
+`tabs`, `react`, `mobile`, and `all`; the `debug` profile includes plugin
+registry and command.run tools. Each tool accepts typed arguments plus
+`extraArgs` for advanced CLI flags and exact CLI parity. Tool discovery is
+paginated and includes read-only/open-world annotations so modern MCP clients
+can load the large typed surface incrementally. Use the tool `session` argument
+or `AGENT_BROWSER_SESSION` to isolate browser sessions.
+
 ## Reading a page
 
 ```bash
@@ -204,6 +227,27 @@ agent-browser auth save my-app --url https://app.example.com/login \
 agent-browser auth login my-app    # fills + clicks, waits for form
 ```
 
+If credentials live in an external vault, use a configured credential provider
+plugin instead of putting secrets in the command line:
+
+```bash
+agent-browser plugin add agent-browser-plugin-vault --name vault
+agent-browser plugin list
+agent-browser auth login my-app --credential-provider vault --item "My App"
+agent-browser auth login my-app --credential-provider vault --item "My App" --url https://app.example.com/login --username-selector "#email" --password-selector "#password"
+```
+
+Plugins can also provide browser providers, launch mutators such as stealth
+setup, and arbitrary namespaced commands:
+
+```bash
+agent-browser --provider cloud-browser open https://example.com
+agent-browser plugin run captcha captcha.solve --payload '{"siteKey":"...","url":"https://example.com"}'
+```
+
+`plugin run` is for `command.run` and custom capabilities. Core capabilities
+and protocol request types use their dedicated command paths.
+
 ### Persist session across runs
 
 ```bash
@@ -484,7 +528,7 @@ That pulls in:
 
 - `references/commands.md` — every command, flag, alias
 - `references/snapshot-refs.md` — deep dive on the snapshot + ref model
-- `references/authentication.md` — auth vault, credential handling
+- `references/authentication.md` — auth vault, credential plugins, credential handling
 - `references/trust-boundaries.md` — safety rules for driving a real browser
 - `references/session-management.md` — persistence, multi-session workflows
 - `references/profiling.md` — Chrome DevTools tracing and profiling

package/skill-data/core/references/authentication.md

@@ -10,6 +10,7 @@ Login flows, session persistence, OAuth, 2FA, and authenticated browsing.
 - [Persistent Profiles](#persistent-profiles)
 - [Session Persistence](#session-persistence)
 - [Basic Login Flow](#basic-login-flow)
+- [Plugins](#plugins)
 - [Saving Authentication State](#saving-authentication-state)
 - [Restoring Authentication](#restoring-authentication)
 - [OAuth / SSO Flows](#oauth--sso-flows)
@@ -140,6 +141,80 @@ agent-browser wait --load networkidle
 agent-browser get url  # Should be dashboard, not login
 ```
 
+## Plugins
+
+Use credential provider plugins when credentials live in external vault software. Plugins are configured in `agent-browser.json` and run as external executables over the `agent-browser.plugin.v1` stdio JSON protocol.
+
+Add a plugin with `plugin add`. A plain `name` or `@scope/name` resolves from npm; `owner/repo` resolves from GitHub:
+
+```bash
+agent-browser plugin add agent-browser-plugin-vault --name vault
+agent-browser plugin add @company/agent-browser-plugin-vault --name vault
+agent-browser plugin add org/agent-browser-plugin-cloud-browser
+```
+
+```json
+{
+  "plugins": [
+    {
+      "name": "vault",
+      "command": "agent-browser-plugin-vault",
+      "capabilities": ["credential.read"]
+    },
+    {
+      "name": "cloud-browser",
+      "command": "agent-browser-plugin-cloud-browser",
+      "capabilities": ["browser.provider"]
+    },
+    {
+      "name": "stealth",
+      "command": "agent-browser-plugin-stealth",
+      "capabilities": ["launch.mutate"]
+    },
+    {
+      "name": "captcha",
+      "command": "agent-browser-plugin-captcha",
+      "capabilities": ["command.run", "captcha.solve"]
+    }
+  ]
+}
+```
+
+Inspect configured plugins before use:
+
+```bash
+agent-browser plugin list
+agent-browser plugin show vault
+```
+
+Resolve credentials just-in-time for one login:
+
+```bash
+agent-browser auth login my-app --credential-provider vault --item "My App"
+```
+
+Use a plugin as a browser provider or a generic domain command:
+
+```bash
+agent-browser --provider cloud-browser open https://example.com
+agent-browser plugin run captcha captcha.solve --payload '{"siteKey":"...","url":"https://example.com"}'
+```
+
+`plugin run` is for `command.run` and custom capabilities. Core capabilities
+and protocol request types use their dedicated command paths.
+
+Use `--url`, `--username-selector`, `--password-selector`, and `--submit-selector` on `auth login` to override plugin-provided metadata for the current login only.
+
+Gate plugin secret access separately from normal login automation:
+
+```bash
+agent-browser --confirm-actions plugin:vault:credential.read auth login my-app --credential-provider vault --item "My App"
+agent-browser --confirm-actions plugin:cloud-browser:browser.provider --provider cloud-browser open https://example.com
+agent-browser --confirm-actions plugin:stealth:launch.mutate open https://example.com
+```
+
+Do not put vault tokens or passwords in plugin command args. Use the vault vendor's own login/session mechanism or environment outside agent-browser config.
+
 ## Saving Authentication State
 
 After logging in, save state for reuse:

package/skill-data/core/references/commands.md

@@ -297,6 +297,36 @@ Array.from(links).map(a => a.href);
 EOF
 ```
 
+## Authentication and Plugins
+
+```bash
+agent-browser auth save <name> --url <url> --username <user> --password-stdin
+agent-browser auth login <name>          # Login using saved credentials
+agent-browser auth login <name> --credential-provider <plugin> [--item <ref>] [--url <url>]
+agent-browser auth login <name> --username-selector <s> --password-selector <s> [--submit-selector <s>]
+agent-browser auth list                  # List saved auth profiles
+agent-browser auth show <name>           # Show profile metadata, no passwords
+agent-browser auth delete <name>         # Delete a saved profile
+agent-browser plugin add <ref>           # Add a plugin from npm or GitHub
+agent-browser plugin list                # List configured plugins
+agent-browser plugin show <name>         # Show one configured plugin
+agent-browser plugin run <name> <type> --payload <json>
+                                          # Run an arbitrary plugin request
+```
+
+Credential provider plugins run out-of-process over the
+`agent-browser.plugin.v1` stdio JSON protocol and must declare
+`credential.read`. Use `--confirm-actions plugin:<name>:credential.read`
+to require explicit approval before a plugin resolves secrets.
+
+Other capabilities use the same protocol:
+- `browser.provider`: `agent-browser --provider <name> open <url>`
+- `launch.mutate`: append local launch args, extensions, or init scripts
+- `command.run`: `agent-browser plugin run <name> <type> --payload <json>`
+
+`plugin run` is for `command.run` and custom capabilities. Core capabilities
+and protocol request types use their dedicated command paths.
+
 ## State Management
 
 ```bash
@@ -304,6 +334,56 @@ agent-browser state save auth.json    # Save cookies, storage, auth state
 agent-browser state load auth.json    # Restore saved state
 ```
 
+## MCP Server
+
+```bash
+agent-browser mcp
+agent-browser mcp --tools all
+agent-browser mcp --tools core,network,react
+```
+
+Starts a stdio Model Context Protocol server. MCP clients should configure the
+server command as `agent-browser` with args `["mcp"]`. The server defaults to
+MCP protocol 2025-11-25 and accepts older supported client protocol versions
+during initialization.
+
+The default tools profile is `core`, which keeps MCP context small for everyday
+browser automation. Use `--tools all` for the full typed CLI parity surface, or
+combine profiles with commas, such as `--tools core,network,react`.
+
+Profiles:
+
+- `core` - Default. Navigation, snapshots, interaction, waits, reads, screenshots, JavaScript eval, close, tab basics, and profile discovery
+- `network` - Network routes, request inspection, HAR, headers, credentials, offline
+- `state` - Cookies, storage, auth, saved state, sessions, profiles, skills
+- `debug` - Console/errors, tracing, profiling, recording, clipboard, plugins, doctor, dashboard, install, upgrade, chat, diff, batch, confirm/deny
+- `tabs` - Back/forward/reload, tabs, windows, frames, dialogs
+- `react` - React tree/inspect/renders/suspense, vitals, pushstate
+- `mobile` - Viewport/device/geolocation/media, touch, swipe, mouse, keyboard
+- `all` - Every MCP tool, including the full typed CLI parity surface
+
+Common tools include:
+
+- `agent_browser_tools_profiles`
+- `agent_browser_open`
+- `agent_browser_snapshot`
+- `agent_browser_click`
+- `agent_browser_fill`
+- `agent_browser_type`
+- `agent_browser_press`
+- `agent_browser_wait_for_selector`
+- `agent_browser_screenshot`
+- `agent_browser_get_url`
+- `agent_browser_eval`
+- `agent_browser_close`
+
+Tool calls use the same config files and environment variables as the CLI. Each
+tool accepts typed arguments plus `extraArgs` for advanced CLI flags and exact
+CLI parity. Tool discovery is paginated and includes read-only/open-world
+annotations so modern MCP clients can load the large typed surface
+incrementally. Use the `session` tool argument or `AGENT_BROWSER_SESSION` to
+isolate browser state.
+
 ## Global Options
 
 ```bash
@@ -312,7 +392,7 @@ agent-browser --json ...              # JSON output for parsing
 agent-browser --headed ...            # Show browser window (not headless)
 agent-browser --cdp <port> ...        # Connect via Chrome DevTools Protocol
 agent-browser --backend <name> ...    # Local backend: patchright (default), chrome
-agent-browser -p <provider> ...       # Cloud browser provider (--provider)
+agent-browser -p <provider> ...       # Browser provider or configured provider plugin
 agent-browser --proxy <url> ...       # Use proxy server
 agent-browser --proxy-bypass <hosts>  # Hosts to bypass proxy
 agent-browser --wait-until <state>    # Navigation wait: none, domcontentloaded, load, networkidle
@@ -399,8 +479,9 @@ AGENT_BROWSER_EXTENSIONS="/ext1,/ext2"       # Comma-separated extension paths
 AGENT_BROWSER_INIT_SCRIPTS="/a.js,/b.js"     # Comma-separated init script paths
 AGENT_BROWSER_ENABLE="react-devtools"        # Comma-separated built-in init script features
 AGENT_BROWSER_HIDE_SCROLLBARS="false"        # Keep native scrollbars visible in headless Chromium screenshots
-AGENT_BROWSER_PROVIDER="browserbase"         # Cloud browser provider
+AGENT_BROWSER_PROVIDER="browserbase"         # Browser provider or configured provider plugin
 AGENT_BROWSER_STREAM_PORT="9223"             # Override WebSocket streaming port (default: OS-assigned)
 AGENT_BROWSER_CONFIG="./agent-browser.json"  # Custom config file
 AGENT_BROWSER_CDP="9222"                     # Connect daemon to CDP port or WebSocket URL
+AGENT_BROWSER_PLUGINS='[{"name":"vault","command":"agent-browser-plugin-vault","capabilities":["credential.read"]},{"name":"stealth","command":"agent-browser-plugin-stealth","capabilities":["launch.mutate"]}]'
 ```