@mindstone/mcp-server-browser-automation 0.1.8 → 0.2.0

package/README.md

@@ -9,9 +9,9 @@ Browser control you can watch: open pages, sign in, click around, fill forms, ta
 
 ## Status
 
-- **Version:** [0.1.7](./CHANGELOG.md) · [npm](https://www.npmjs.com/package/@mindstone/mcp-server-browser-automation)
+- **Version:** [0.2.0](./CHANGELOG.md) · [npm](https://www.npmjs.com/package/@mindstone/mcp-server-browser-automation)
 - **Auth:** None ([`server.json`](./server.json))
-- **Tools:** [18](./src/tools/) (navigation, observation, interaction, sessions)
+- **Tools:** [21](./src/tools/) (navigation, observation, interaction, sessions, files)
 - **Surface:** browser-automation
 - **Machine-readable:** [`STATUS.json`](./STATUS.json)
 
@@ -99,7 +99,7 @@ This server requires the `agent-browser` CLI binary to control the browser.
 ### Binary Resolution
 
 1. **PATH lookup** (preferred): If `agent-browser` is on your PATH, it is used directly.
-2. **npx fallback**: If the binary is not found, the server automatically falls back to `npx -y agent-browser@0.26.0`.
+2. **npx fallback**: If the binary is not found, the server automatically falls back to `npx -y agent-browser@0.33.2`.
 
 ### Installing agent-browser
 
@@ -118,6 +118,7 @@ No API keys or credentials are required. The server communicates with the browse
 | `AGENT_BROWSER_SESSION_NAME` | No | Session name for browser persistence (default: `mcp`) |
 | `AGENT_BROWSER_SHOW_WINDOW` | No | Set to `false` to run without a visible browser window. Default is visible (`true`). |
 | `BROWSER_AUTOMATION_ALLOW_EVAL` | No | Set to `1` to register the `browser_evaluate` tool. Off by default. See [Security notes](#security-notes). |
+| `MCP_WORKSPACE_PATH` | No | Workspace directory that `browser_pdf` writes into and `browser_upload` reads from. Defaults to the system temp directory. See [Security notes](#security-notes). |
 
 ### MCP Host Configuration
 
@@ -132,7 +133,7 @@ No API keys or credentials are required. The server communicates with the browse
 }
 ```
 
-## Available Tools (17 by default; +1 when `BROWSER_AUTOMATION_ALLOW_EVAL=1`)
+## Available Tools (20 by default; +1 when `BROWSER_AUTOMATION_ALLOW_EVAL=1`)
 
 ### Navigation
 - **browser_navigate** — Navigate to a URL
@@ -144,6 +145,8 @@ No API keys or credentials are required. The server communicates with the browse
 - **browser_snapshot** — Get the page accessibility tree with interactive element references
 - **browser_screenshot** — Take a screenshot of the current page
 - **browser_get_page_info** — Get the current page URL and title
+- **browser_get_text** — Get the text content of the page or a single element
+- **browser_pdf** — Save the current page as a PDF inside the workspace directory (refuses to overwrite existing files unless `overwrite: true`)
 
 ### Interaction
 - **browser_click** — Click an element using @ref or CSS selector
@@ -153,6 +156,7 @@ No API keys or credentials are required. The server communicates with the browse
 - **browser_scroll** — Scroll the page in a direction
 - **browser_select** — Select an option from a dropdown
 - **browser_hover** — Hover over an element
+- **browser_upload** — Upload workspace files to a file input (regular files only, staged privately before upload)
 - **browser_evaluate** — Execute JavaScript in the page context (gated; see [Security notes](#security-notes))
 
 ### Session Management
@@ -205,7 +209,19 @@ To override the session name (for example, to keep separate profiles per project
 - **Run the connector against a separate browser profile** — a dedicated `AGENT_BROWSER_SESSION_NAME` per MCP host. Do not reuse your daily browser profile: the connector reads and overwrites cookies in whichever profile it is pointed at, and a malicious page can ride the existing session of any site you are logged into.
 - **Leave `browser_evaluate` disabled** unless the host implements user confirmation for every call. The default (off) is the safe choice.
 - **Require host confirmation** for `browser_authenticate` and any flow that may navigate to authenticated sites — otherwise prompt injection in fetched content can drive the browser at sites the user is logged into.
-- **Treat returned page content as untrusted** — accessibility snapshots, screenshots, and JavaScript-evaluation outputs come from arbitrary websites and may contain prompt-injection attempts.
+- **Returned page content is enveloped as untrusted** — accessibility snapshots, page text, titles, URLs, tab lists, and `browser_evaluate` outputs come from arbitrary websites and may contain prompt-injection attempts. The connector wraps them in `<untrusted-content source="…">` envelopes (with close-tag breakout escaping) so hosts and models treat them as data, not instructions. Keep that treatment on your side: don't strip the envelopes, and don't let page text alone trigger irreversible actions.
+
+### Workspace sandbox for file tools
+
+`browser_pdf` writes PDF files and `browser_upload` reads files, and both are constrained to a workspace directory: `MCP_WORKSPACE_PATH` when set, otherwise the system temp directory. Paths are canonicalised before use, so `..` traversal, absolute paths outside the workspace, and in-workspace symlinks pointing outside it are all refused before the `agent-browser` CLI runs. Set `MCP_WORKSPACE_PATH` explicitly to control exactly where page captures land and which files the model can attach to a page. A `MCP_WORKSPACE_PATH` that cannot be resolved fails closed: file tools refuse to run rather than fall back to weaker checks.
+
+Both tools are marked `destructiveHint: true`, so hosts can require user confirmation: `browser_upload` can trigger an immediate remote upload on pages that submit when the file input changes, and `browser_pdf` writes a local file.
+
+Additional hardening:
+
+- **Staged file hand-off.** Validated files are never re-opened by pathname. `browser_upload` sources are opened once, verified to be regular files (directories, devices, and FIFOs are refused), and copied into a fresh private staging directory that the CLI consumes; `browser_pdf` has the CLI write into a fresh private staging directory and then installs the PDF at the requested path with exclusive-create semantics. A file or symlink planted after validation cannot redirect the read or the write.
+- **No silent overwrite.** `browser_pdf` refuses an existing `file_path` with a `FILE_EXISTS` error unless the caller explicitly passes `overwrite: true`.
+- **Enveloped errors.** Error output from the `agent-browser` CLI can contain page-authored text; it is wrapped in `<untrusted-content>` envelopes (with close-tag breakout escaping) before reaching the model, and timeout errors do not echo the command's argument values.
 
 ## Licence
 

package/dist/browser-client.js

@@ -1,6 +1,7 @@
 import { execFile } from 'node:child_process';
 import { promisify } from 'node:util';
 import { ConnectorError, DEFAULT_TIMEOUT_MS, SESSION_NAME } from './types.js';
+import { wrapUntrusted } from './untrusted-content.js';
 const execFileAsync = promisify(execFile);
 let resolvedBinary = null;
 function resolveAgentBrowser() {
@@ -49,8 +50,30 @@ function resolveHeaded(optionHeaded, env) {
  * Why pinned: keeps fallback behavior reproducible. Bump when verified against
  * a newer release. Do not use `latest` — npx caches by spec, and an unpinned
  * spec produces flaky behavior across machines.
+ *
+ * 0.33.2 verified 2026-08-05 against the connector's full command surface
+ * (open, snapshot -i, screenshot, pdf, get url/title/text, tab, click/fill/
+ * type/press/scroll/select/hover, eval, back/forward, wait, close).
+ */
+const NPX_FALLBACK_VERSION = '0.33.2';
+/**
+ * Build the ConnectorError message for a failed CLI invocation.
+ *
+ * stdout/stderr from the CLI can carry page-derived, attacker-controlled
+ * text (including prompt injection and forged envelope close tags), so the
+ * detail is wrapped in an untrusted-content envelope before it can reach the
+ * model. When neither stream has content, fall back to a static description
+ * naming only the subcommand: Node's own error message echoes the full
+ * argument vector, which may carry sensitive values (URLs with userinfo,
+ * typed text, evaluation scripts).
  */
-const NPX_FALLBACK_VERSION = '0.26.0';
+function cliFailureMessage(command, stderr, stdout) {
+    const detail = stderr?.trim() || stdout?.trim() || '';
+    if (!detail) {
+        return `agent-browser ${command} exited with a non-zero status and produced no error output`;
+    }
+    return `agent-browser ${command} failed: ${wrapUntrusted(detail, 'browser-automation:cli-error')}`;
+}
 /**
  * Execute an agent-browser CLI command.
  *
@@ -110,22 +133,20 @@ export async function execAgentBrowser(args, options) {
                         'Or ensure npx is available on PATH.');
                 }
                 // npx ran but the underlying CLI exited non-zero — propagate as CLI_ERROR
-                // with the actual stderr for diagnosis.
-                const npxStderr = npxErr.stderr?.trim() ?? '';
-                const npxStdout = npxErr.stdout?.trim() ?? '';
-                throw new ConnectorError(npxStderr || npxStdout || npxErr.message || String(npxError), 'CLI_ERROR', 'The agent-browser CLI command failed (via npx fallback). ' +
+                // with the (enveloped) stderr for diagnosis.
+                throw new ConnectorError(cliFailureMessage(args[0], npxErr.stderr, npxErr.stdout), 'CLI_ERROR', 'The agent-browser CLI command failed (via npx fallback). ' +
                     'Check the error details above. ' +
                     'For best performance, install agent-browser globally: npm install -g agent-browser');
             }
         }
-        // Timeout
+        // Timeout — name only the subcommand: the full argument vector may carry
+        // sensitive values (URLs with userinfo, selectors, filenames, typed
+        // values, evaluation scripts) and must not be echoed to the model.
         if (err.code === 'ERR_CHILD_PROCESS_STDIO_MAXBUFFER' || err.killed) {
-            throw new ConnectorError(`Command timed out after ${timeoutMs}ms: agent-browser ${args.join(' ')}`, 'TIMEOUT', 'The browser operation took too long. Try a simpler action or increase the timeout.');
+            throw new ConnectorError(`Command timed out after ${timeoutMs}ms: agent-browser ${args[0]}`, 'TIMEOUT', 'The browser operation took too long. Try a simpler action or increase the timeout.');
         }
-        // Other errors — include stderr for diagnostics
-        const stderr = err.stderr?.trim() ?? '';
-        const stdout = err.stdout?.trim() ?? '';
-        throw new ConnectorError(stderr || stdout || err.message || String(error), 'CLI_ERROR', 'The agent-browser CLI command failed. Check that agent-browser is installed and the browser session is active.');
+        // Other errors — include the (enveloped) stderr for diagnostics
+        throw new ConnectorError(cliFailureMessage(args[0], err.stderr, err.stdout), 'CLI_ERROR', 'The agent-browser CLI command failed. Check that agent-browser is installed and the browser session is active.');
     }
 }
 /**

package/dist/path-safety.d.ts

@@ -0,0 +1,90 @@
+export type ResolveResult = {
+    ok: true;
+    path: string;
+} | {
+    ok: false;
+    error: string;
+};
+/**
+ * Derive the canonical workspace root for files the connector reads from or
+ * writes to on behalf of the model (`browser_pdf` output, `browser_upload`
+ * sources).
+ *
+ * Mirrors the pandadoc connector's sandbox helper:
+ *   - Use `MCP_WORKSPACE_PATH` if set and non-empty, else `os.tmpdir()`.
+ *   - The root is canonicalised through `fs.realpathSync` so the prefix
+ *     checks are stable on platforms where the tmpdir itself is reached
+ *     through a symlink (macOS: `/tmp` → `/private/tmp`).
+ *   - If `realpathSync` fails (e.g. the env var points at a non-existent
+ *     directory), FAIL CLOSED: a root we cannot canonicalise makes every
+ *     downstream containment check unreliable, so file operations are
+ *     refused. The failed pre-check is made observable via a stderr warning.
+ */
+export declare function getWorkspaceRoot(): string;
+/**
+ * Validate that `inputPath` resolves to a real file inside the workspace
+ * root, even after symlink resolution (for `browser_upload` sources).
+ * Returns the canonical path on success.
+ */
+export declare function resolveWorkspaceReadPath(inputPath: string): ResolveResult;
+/**
+ * Validate that `inputPath` is a safe WRITE target inside the workspace
+ * root (for `browser_pdf` output). The leaf need not exist yet; when it
+ * does exist it must not be a symlink escaping the workspace.
+ */
+export declare function resolveWorkspaceWritePath(inputPath: string): ResolveResult;
+/**
+ * Create a fresh, unpredictable staging directory directly under the
+ * canonical workspace root (mode 0700). Because it is created atomically
+ * with a random suffix, another local principal cannot pre-create, rename,
+ * or symlink-swap any component of paths inside it — which is what makes a
+ * staged file swap-proof between our write and the agent-browser CLI's
+ * later open. The validated user-supplied pathname is never re-trusted.
+ */
+export declare function createStagingDir(prefix: string): string;
+/** Best-effort removal of a staging directory and everything in it. */
+export declare function discardStagingDir(stagingDir: string): void;
+/**
+ * Stage one `browser_upload` source into `stagingDir` and return the path
+ * the CLI should consume.
+ *
+ * The source is validated inside the workspace root, then opened EXACTLY
+ * ONCE and fstat-verified through that fd to be a regular file —
+ * directories, FIFOs, sockets, and devices pass realpathSync but must not
+ * become upload payloads. The content is streamed through the same fd into
+ * a private staging slot carrying over only the requested basename, so the
+ * CLI never re-opens the validated pathname and a post-validation swap of
+ * the original cannot redirect the upload.
+ */
+export declare function stageUploadSource(inputPath: string, stagingDir: string, index: number): string;
+export interface PdfStagingTarget {
+    /** Validated final destination for the PDF. */
+    destPath: string;
+    /** Private staging path the CLI should write to. */
+    stagingPath: string;
+    /** Remove with discardStagingDir once installed (or on failure). */
+    stagingDir: string;
+}
+/**
+ * Resolve the `browser_pdf` destination and prepare a private staging
+ * target. The CLI writes into the staging path — never the validated
+ * pathname — so an attacker cannot redirect the write by swapping an
+ * intermediate directory or leaf after validation.
+ *
+ * An existing destination is refused up front unless `overwrite` was
+ * explicitly requested; installStagedFile enforces the same invariant
+ * race-safely with exclusive-create at install time.
+ */
+export declare function createPdfStagingTarget(filePath: string, overwrite: boolean): PdfStagingTarget;
+/**
+ * Install a staged PDF at its validated destination.
+ *
+ * The install never writes through a pre-existing filesystem entry:
+ * exclusive-create (COPYFILE_EXCL) fails with EEXIST on anything already at
+ * the destination — including a planted symlink. With `overwrite`, the old
+ * entry is removed first and the same exclusive-create follows, so a swap
+ * planted in between still surfaces as an EEXIST refusal instead of a write
+ * through an attacker-chosen path.
+ */
+export declare function installStagedFile(stagingPath: string, destPath: string, overwrite: boolean): void;
+//# sourceMappingURL=path-safety.d.ts.map

package/dist/path-safety.js

@@ -0,0 +1,280 @@
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import * as os from 'node:os';
+import { ConnectorError } from './types.js';
+/**
+ * Derive the canonical workspace root for files the connector reads from or
+ * writes to on behalf of the model (`browser_pdf` output, `browser_upload`
+ * sources).
+ *
+ * Mirrors the pandadoc connector's sandbox helper:
+ *   - Use `MCP_WORKSPACE_PATH` if set and non-empty, else `os.tmpdir()`.
+ *   - The root is canonicalised through `fs.realpathSync` so the prefix
+ *     checks are stable on platforms where the tmpdir itself is reached
+ *     through a symlink (macOS: `/tmp` → `/private/tmp`).
+ *   - If `realpathSync` fails (e.g. the env var points at a non-existent
+ *     directory), FAIL CLOSED: a root we cannot canonicalise makes every
+ *     downstream containment check unreliable, so file operations are
+ *     refused. The failed pre-check is made observable via a stderr warning.
+ */
+export function getWorkspaceRoot() {
+    const envRoot = process.env.MCP_WORKSPACE_PATH;
+    const explicit = Boolean(envRoot && envRoot.trim());
+    const raw = explicit ? envRoot.trim() : os.tmpdir();
+    const lexical = path.resolve(raw);
+    try {
+        return fs.realpathSync(lexical);
+    }
+    catch (err) {
+        const reason = err instanceof Error ? err.message : String(err);
+        console.error(`[browser-automation] Workspace root ${JSON.stringify(lexical)} cannot be canonicalised (${reason}); refusing file operations.`);
+        throw new ConnectorError(explicit
+            ? `MCP_WORKSPACE_PATH (${lexical}) cannot be resolved: ${reason}`
+            : `System temp directory (${lexical}) cannot be resolved: ${reason}`, 'WORKSPACE_ROOT_UNAVAILABLE', 'Set MCP_WORKSPACE_PATH to an existing directory the process can read, or unset it to use the system temp directory.');
+    }
+}
+/**
+ * Canonicalise the deepest existing ancestor of an absolute path and
+ * re-append the missing tail. This lets the lexical-prefix containment check
+ * accept in-workspace paths supplied via a symlinked alias of the workspace
+ * root (e.g. `/tmp` → `/private/tmp` on macOS) while still rejecting `..`
+ * traversal and out-of-root absolutes deterministically WITHOUT requiring
+ * the leaf to exist.
+ */
+function canonicalisePrefix(absoluteLexical) {
+    const tail = [];
+    let cur = absoluteLexical;
+    while (true) {
+        try {
+            const real = fs.realpathSync(cur);
+            return tail.length === 0 ? real : path.join(real, ...tail.reverse());
+        }
+        catch (err) {
+            const code = err.code;
+            if (code !== 'ENOENT' && code !== 'ENOTDIR') {
+                throw err;
+            }
+        }
+        const parent = path.dirname(cur);
+        if (parent === cur) {
+            return absoluteLexical;
+        }
+        tail.push(path.basename(cur));
+        cur = parent;
+    }
+}
+function isInsideRoot(p, root) {
+    return p === root || p.startsWith(root + path.sep);
+}
+function absolutise(inputPath, root) {
+    const expanded = inputPath.startsWith('~')
+        ? path.join(os.homedir(), inputPath.slice(1))
+        : inputPath;
+    // Relative inputs resolve against the workspace root — an MCP server's
+    // process cwd is unpredictable, so anchoring anywhere else would be
+    // arbitrary. Absolute inputs must still land inside the root.
+    return path.isAbsolute(expanded)
+        ? path.resolve(expanded)
+        : path.resolve(root, expanded);
+}
+/**
+ * Validate that `inputPath` resolves to a real file inside the workspace
+ * root, even after symlink resolution (for `browser_upload` sources).
+ * Returns the canonical path on success.
+ */
+export function resolveWorkspaceReadPath(inputPath) {
+    const root = getWorkspaceRoot();
+    const lexical = absolutise(inputPath, root);
+    const canonicalCandidate = canonicalisePrefix(lexical);
+    if (!isInsideRoot(canonicalCandidate, root)) {
+        return { ok: false, error: `file_path is outside the workspace sandbox root (${root}). Got: ${inputPath}` };
+    }
+    let canonical;
+    try {
+        canonical = fs.realpathSync(lexical);
+    }
+    catch (err) {
+        if (err.code === 'ENOENT') {
+            return { ok: false, error: `File not found: ${inputPath}` };
+        }
+        throw err;
+    }
+    if (!isInsideRoot(canonical, root)) {
+        return {
+            ok: false,
+            error: `file_path resolves outside the workspace sandbox root (${root}); ` +
+                `symlinks may not escape the workspace. Got: ${inputPath}`,
+        };
+    }
+    return { ok: true, path: canonical };
+}
+/**
+ * Validate that `inputPath` is a safe WRITE target inside the workspace
+ * root (for `browser_pdf` output). The leaf need not exist yet; when it
+ * does exist it must not be a symlink escaping the workspace.
+ */
+export function resolveWorkspaceWritePath(inputPath) {
+    const root = getWorkspaceRoot();
+    const lexical = absolutise(inputPath, root);
+    // Deepest-existing-ancestor canonicalisation catches `..` traversal,
+    // out-of-root absolutes, and symlinked intermediate directories pointing
+    // outside the root — all without requiring the leaf file to exist.
+    const canonicalCandidate = canonicalisePrefix(lexical);
+    if (!isInsideRoot(canonicalCandidate, root)) {
+        return { ok: false, error: `file_path is outside the workspace sandbox root (${root}). Got: ${inputPath}` };
+    }
+    // If the leaf itself exists as a symlink, resolve it too so a planted
+    // symlink cannot redirect the write outside the workspace.
+    try {
+        const canonicalLeaf = fs.realpathSync(lexical);
+        if (!isInsideRoot(canonicalLeaf, root)) {
+            return {
+                ok: false,
+                error: `file_path resolves outside the workspace sandbox root (${root}); ` +
+                    `symlinks may not escape the workspace. Got: ${inputPath}`,
+            };
+        }
+    }
+    catch (err) {
+        if (err.code !== 'ENOENT') {
+            throw err;
+        }
+    }
+    return { ok: true, path: canonicalCandidate };
+}
+const STAGING_DIR_MODE = 0o700;
+const STAGING_FILE_MODE = 0o600;
+const COPY_CHUNK_BYTES = 1024 * 1024;
+/**
+ * Create a fresh, unpredictable staging directory directly under the
+ * canonical workspace root (mode 0700). Because it is created atomically
+ * with a random suffix, another local principal cannot pre-create, rename,
+ * or symlink-swap any component of paths inside it — which is what makes a
+ * staged file swap-proof between our write and the agent-browser CLI's
+ * later open. The validated user-supplied pathname is never re-trusted.
+ */
+export function createStagingDir(prefix) {
+    const root = getWorkspaceRoot();
+    const dir = fs.mkdtempSync(path.join(root, prefix));
+    fs.chmodSync(dir, STAGING_DIR_MODE);
+    return dir;
+}
+/** Best-effort removal of a staging directory and everything in it. */
+export function discardStagingDir(stagingDir) {
+    try {
+        fs.rmSync(stagingDir, { recursive: true, force: true });
+    }
+    catch { /* best effort */ }
+}
+function sanitiseBasename(p, fallback) {
+    const base = path.basename(p);
+    return base === '' || base === '.' || base === '..' ? fallback : base;
+}
+/**
+ * Stage one `browser_upload` source into `stagingDir` and return the path
+ * the CLI should consume.
+ *
+ * The source is validated inside the workspace root, then opened EXACTLY
+ * ONCE and fstat-verified through that fd to be a regular file —
+ * directories, FIFOs, sockets, and devices pass realpathSync but must not
+ * become upload payloads. The content is streamed through the same fd into
+ * a private staging slot carrying over only the requested basename, so the
+ * CLI never re-opens the validated pathname and a post-validation swap of
+ * the original cannot redirect the upload.
+ */
+export function stageUploadSource(inputPath, stagingDir, index) {
+    const resolved = resolveWorkspaceReadPath(inputPath);
+    if (!resolved.ok) {
+        throw new ConnectorError(resolved.error, 'PATH_OUTSIDE_WORKSPACE', 'Pass file paths inside the workspace directory (MCP_WORKSPACE_PATH, or the system temp directory when unset).');
+    }
+    const slot = path.join(stagingDir, String(index));
+    fs.mkdirSync(slot, { mode: STAGING_DIR_MODE });
+    const stagingPath = path.join(slot, sanitiseBasename(resolved.path, `upload-${index}`));
+    const inFd = fs.openSync(resolved.path, 'r');
+    try {
+        const stat = fs.fstatSync(inFd);
+        if (!stat.isFile()) {
+            throw new ConnectorError(`file_path is not a regular file: ${inputPath}`, 'NOT_A_REGULAR_FILE', 'Pass a path to a regular file inside the workspace directory.');
+        }
+        const outFd = fs.openSync(stagingPath, 'wx', STAGING_FILE_MODE);
+        try {
+            const chunk = Buffer.allocUnsafe(COPY_CHUNK_BYTES);
+            let bytesRead;
+            do {
+                bytesRead = fs.readSync(inFd, chunk, 0, chunk.length, null);
+                if (bytesRead > 0)
+                    fs.writeSync(outFd, chunk, 0, bytesRead);
+            } while (bytesRead > 0);
+        }
+        finally {
+            fs.closeSync(outFd);
+        }
+    }
+    finally {
+        fs.closeSync(inFd);
+    }
+    return stagingPath;
+}
+/**
+ * Resolve the `browser_pdf` destination and prepare a private staging
+ * target. The CLI writes into the staging path — never the validated
+ * pathname — so an attacker cannot redirect the write by swapping an
+ * intermediate directory or leaf after validation.
+ *
+ * An existing destination is refused up front unless `overwrite` was
+ * explicitly requested; installStagedFile enforces the same invariant
+ * race-safely with exclusive-create at install time.
+ */
+export function createPdfStagingTarget(filePath, overwrite) {
+    const resolved = resolveWorkspaceWritePath(filePath);
+    if (!resolved.ok) {
+        throw new ConnectorError(resolved.error, 'PATH_OUTSIDE_WORKSPACE', 'Pass a file path inside the workspace directory (MCP_WORKSPACE_PATH, or the system temp directory when unset).');
+    }
+    if (!overwrite && fs.existsSync(resolved.path)) {
+        throw new ConnectorError(`file_path already exists: ${filePath}`, 'FILE_EXISTS', 'Pass overwrite: true to replace the existing file, or choose a different file_path.');
+    }
+    const stagingDir = createStagingDir('browser-pdf-');
+    return {
+        destPath: resolved.path,
+        stagingPath: path.join(stagingDir, sanitiseBasename(resolved.path, 'page.pdf')),
+        stagingDir,
+    };
+}
+/**
+ * Install a staged PDF at its validated destination.
+ *
+ * The install never writes through a pre-existing filesystem entry:
+ * exclusive-create (COPYFILE_EXCL) fails with EEXIST on anything already at
+ * the destination — including a planted symlink. With `overwrite`, the old
+ * entry is removed first and the same exclusive-create follows, so a swap
+ * planted in between still surfaces as an EEXIST refusal instead of a write
+ * through an attacker-chosen path.
+ */
+export function installStagedFile(stagingPath, destPath, overwrite) {
+    let staged;
+    try {
+        staged = fs.lstatSync(stagingPath);
+    }
+    catch {
+        throw new ConnectorError('The agent-browser CLI did not produce an output file.', 'CLI_ERROR', 'Retry the call, or check that a page is open in the browser session.');
+    }
+    if (!staged.isFile()) {
+        throw new ConnectorError('The agent-browser CLI did not produce a regular output file.', 'CLI_ERROR', 'Retry the call, or check that a page is open in the browser session.');
+    }
+    if (overwrite) {
+        fs.rmSync(destPath, { force: true });
+    }
+    // Parent directories were validated as inside the workspace by
+    // resolveWorkspaceWritePath; create any missing tail before installing.
+    fs.mkdirSync(path.dirname(destPath), { recursive: true });
+    try {
+        fs.copyFileSync(stagingPath, destPath, fs.constants.COPYFILE_EXCL);
+    }
+    catch (err) {
+        if (err.code === 'EEXIST') {
+            throw new ConnectorError(`Destination already exists: ${destPath}`, 'FILE_EXISTS', 'Pass overwrite: true to replace the existing file, or choose a different file_path.');
+        }
+        throw err;
+    }
+}
+//# sourceMappingURL=path-safety.js.map

package/dist/server.js

@@ -1,6 +1,6 @@
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { SERVER_NAME, SERVER_VERSION } from './types.js';
-import { registerNavigationTools, registerInteractionTools, registerObservationTools, registerSessionTools, } from './tools/index.js';
+import { registerNavigationTools, registerInteractionTools, registerObservationTools, registerSessionTools, registerFileTools, } from './tools/index.js';
 export function createServer() {
     const server = new McpServer({
         name: SERVER_NAME,
@@ -10,6 +10,7 @@ export function createServer() {
     registerInteractionTools(server);
     registerObservationTools(server);
     registerSessionTools(server);
+    registerFileTools(server);
     return server;
 }
 //# sourceMappingURL=server.js.map

package/dist/tools/files.d.ts

@@ -0,0 +1,3 @@
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+export declare function registerFileTools(server: McpServer): void;
+//# sourceMappingURL=files.d.ts.map

package/dist/tools/files.js

@@ -0,0 +1,44 @@
+import { z } from 'zod';
+import { execAgentBrowser } from '../browser-client.js';
+import { withErrorHandling } from '../utils.js';
+import { createStagingDir, discardStagingDir, stageUploadSource } from '../path-safety.js';
+export function registerFileTools(server) {
+    server.registerTool('browser_upload', {
+        description: `Upload one or more files to a file input on the page. Use @ref from browser_snapshot or a CSS selector for the <input type="file">.
+
+WORKFLOW: browser_snapshot → find file input @ref → browser_upload.
+
+Files must live inside the workspace directory (MCP_WORKSPACE_PATH, or the system temp directory when unset) — paths outside it are refused, and only regular files (not directories or devices) are accepted. Validated files are copied into a private staging directory before upload, so the upload cannot be redirected after validation.`,
+        inputSchema: {
+            ref: z.string().min(1).describe('Element ref (e.g., "@e3") or CSS selector for the file input'),
+            file_paths: z.array(z.string().min(1)).min(1).describe('Files to upload. Relative paths resolve inside the workspace directory; absolute paths must be inside it.'),
+        },
+        annotations: {
+            readOnlyHint: false,
+            // Uploading a file to a page can trigger an immediate remote upload
+            // (pages that submit on the input's change event) — an external,
+            // production-impacting write.
+            destructiveHint: true,
+            idempotentHint: false,
+            openWorldHint: true,
+        },
+    }, withErrorHandling(async (args) => {
+        // Stage every source into one private staging dir and hand the CLI the
+        // staged paths — never the validated pathnames — so a swap of the
+        // original file or an ancestor after validation cannot redirect the
+        // upload. The staging dir is always discarded afterwards.
+        const stagingDir = createStagingDir('browser-upload-');
+        try {
+            const staged = [];
+            for (const [index, filePath] of args.file_paths.entries()) {
+                staged.push(stageUploadSource(filePath, stagingDir, index));
+            }
+            await execAgentBrowser(['upload', args.ref, ...staged]);
+            return JSON.stringify({ ok: true, message: `Uploaded ${staged.length} file(s) to ${args.ref}` });
+        }
+        finally {
+            discardStagingDir(stagingDir);
+        }
+    }));
+}
+//# sourceMappingURL=files.js.map

package/dist/tools/index.d.ts

@@ -2,4 +2,5 @@ export { registerNavigationTools } from './navigation.js';
 export { registerInteractionTools } from './interaction.js';
 export { registerObservationTools } from './observation.js';
 export { registerSessionTools } from './session.js';
+export { registerFileTools } from './files.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/tools/index.js

@@ -2,4 +2,5 @@ export { registerNavigationTools } from './navigation.js';
 export { registerInteractionTools } from './interaction.js';
 export { registerObservationTools } from './observation.js';
 export { registerSessionTools } from './session.js';
+export { registerFileTools } from './files.js';
 //# sourceMappingURL=index.js.map

package/dist/tools/interaction.js

@@ -1,6 +1,7 @@
 import { z } from 'zod';
 import { execAgentBrowser } from '../browser-client.js';
 import { withErrorHandling } from '../utils.js';
+import { wrapUntrusted } from '../untrusted-content.js';
 export function registerInteractionTools(server) {
     server.registerTool('browser_click', {
         description: `Click an element. Use @ref from browser_snapshot (preferred) or a CSS selector.
@@ -142,7 +143,7 @@ WORKFLOW: browser_snapshot → find input @ref → browser_fill`,
             },
         }, withErrorHandling(async (args) => {
             const result = await execAgentBrowser(['eval', args.script]);
-            return JSON.stringify({ ok: true, result: result.stdout.trim() });
+            return JSON.stringify({ ok: true, result: wrapUntrusted(result.stdout.trim(), 'browser-automation:evaluate') });
         }));
     }
 }

package/dist/tools/navigation.js

@@ -1,6 +1,7 @@
 import { z } from 'zod';
 import { execAgentBrowser } from '../browser-client.js';
 import { validateUrlScheme, withErrorHandling } from '../utils.js';
+import { wrapUntrusted } from '../untrusted-content.js';
 // URL scheme deny-list (validated by `validateUrlScheme` in utils.ts):
 // only http: and https: are permitted; about:blank is special-cased.
 // Refused: file:, chrome:, chrome-extension:, javascript:, data:,
@@ -28,7 +29,7 @@ IMPORTANT: After navigating, call browser_snapshot to see the page content befor
         return JSON.stringify({
             ok: true,
             message: `Navigated to ${args.url}`,
-            title: titleResult.stdout.trim(),
+            title: wrapUntrusted(titleResult.stdout.trim(), 'browser-automation:page-title'),
             hint: 'Call browser_snapshot to see page elements before interacting.',
         });
     }));

package/dist/tools/observation.js

@@ -2,6 +2,8 @@ import { z } from 'zod';
 import { execAgentBrowser } from '../browser-client.js';
 import { withErrorHandling, withErrorHandlingRaw } from '../utils.js';
 import { SNAPSHOT_TIMEOUT_MS, SCREENSHOT_TIMEOUT_MS } from '../types.js';
+import { wrapUntrusted } from '../untrusted-content.js';
+import { createPdfStagingTarget, discardStagingDir, installStagedFile } from '../path-safety.js';
 export function registerObservationTools(server) {
     server.registerTool('browser_snapshot', {
         description: `Get the page accessibility tree with interactive element references.
@@ -22,7 +24,7 @@ Use the -i flag (default) to see only interactive elements, keeping output focus
     }, withErrorHandling(async (args) => {
         const cliArgs = args.full ? ['snapshot'] : ['snapshot', '-i'];
         const result = await execAgentBrowser(cliArgs, { timeoutMs: SNAPSHOT_TIMEOUT_MS });
-        return JSON.stringify({ ok: true, snapshot: result.stdout });
+        return JSON.stringify({ ok: true, snapshot: wrapUntrusted(result.stdout, 'browser-automation:snapshot') });
     }));
     server.registerTool('browser_screenshot', {
         description: 'Take a screenshot of the current page. Returns an image.',
@@ -56,7 +58,9 @@ Use the -i flag (default) to see only interactive elements, keeping output focus
             };
         }
         return {
-            content: [{ type: 'text', text: JSON.stringify({ ok: true, message: 'Screenshot taken', note: data }) }],
+            // Short stdout is not an image — it is CLI/page-derived text and must
+            // be enveloped like every other external string.
+            content: [{ type: 'text', text: JSON.stringify({ ok: true, message: 'Screenshot taken', note: wrapUntrusted(data, 'browser-automation:screenshot') }) }],
         };
     }));
     server.registerTool('browser_get_page_info', {
@@ -73,9 +77,57 @@ Use the -i flag (default) to see only interactive elements, keeping output focus
         const titleResult = await execAgentBrowser(['get', 'title']);
         return JSON.stringify({
             ok: true,
-            url: urlResult.stdout.trim(),
-            title: titleResult.stdout.trim(),
+            url: wrapUntrusted(urlResult.stdout.trim(), 'browser-automation:page-url'),
+            title: wrapUntrusted(titleResult.stdout.trim(), 'browser-automation:page-title'),
         });
     }));
+    server.registerTool('browser_get_text', {
+        description: `Get the text content of the page (or of a single element).
+
+Use this for reading and summarising page content — it returns clean text, unlike browser_snapshot which returns the interactive-element accessibility tree.`,
+        inputSchema: {
+            ref: z.string().optional().describe('Element ref from snapshot (e.g., "@e2") or CSS selector. Omit to get the whole page body text.'),
+        },
+        annotations: {
+            readOnlyHint: true,
+            destructiveHint: false,
+            idempotentHint: true,
+            openWorldHint: true,
+        },
+    }, withErrorHandling(async (args) => {
+        const selector = args.ref ?? 'body';
+        const result = await execAgentBrowser(['get', 'text', selector]);
+        return JSON.stringify({ ok: true, text: wrapUntrusted(result.stdout.trim(), 'browser-automation:page-text') });
+    }));
+    server.registerTool('browser_pdf', {
+        description: `Save the current page as a PDF file.
+
+The file is written inside the workspace directory (MCP_WORKSPACE_PATH, or the system temp directory when unset) — file_path must resolve inside that workspace. Existing files are refused unless overwrite is set to true.`,
+        inputSchema: {
+            file_path: z.string().min(1).describe('Target file path for the PDF. Relative paths resolve inside the workspace directory; absolute paths must be inside it (e.g., "reports/page.pdf").'),
+            overwrite: z.boolean().optional().default(false).describe('Replace an existing file at file_path. Default: false — existing files are refused.'),
+        },
+        annotations: {
+            readOnlyHint: false,
+            // Writes (and, with overwrite: true, replaces) a local file.
+            destructiveHint: true,
+            idempotentHint: false,
+            openWorldHint: true,
+        },
+    }, withErrorHandling(async (args) => {
+        // The CLI writes into a private staging dir, and the PDF is installed
+        // at the validated destination with exclusive-create semantics, so a
+        // post-validation swap cannot redirect the write or clobber an
+        // existing file.
+        const target = createPdfStagingTarget(args.file_path, args.overwrite);
+        try {
+            await execAgentBrowser(['pdf', target.stagingPath]);
+            installStagedFile(target.stagingPath, target.destPath, args.overwrite);
+            return JSON.stringify({ ok: true, file_path: target.destPath });
+        }
+        finally {
+            discardStagingDir(target.stagingDir);
+        }
+    }));
 }
 //# sourceMappingURL=observation.js.map

package/dist/tools/session.js

@@ -1,6 +1,7 @@
 import { z } from 'zod';
 import { execAgentBrowser } from '../browser-client.js';
 import { validateUrlScheme, withErrorHandling } from '../utils.js';
+import { wrapUntrusted } from '../untrusted-content.js';
 // URL scheme deny-list applied to browser_authenticate (validated by
 // `validateUrlScheme` in utils.ts): only http: and https: URLs are
 // permitted; about:blank is special-cased. Refused: file:, chrome:,
@@ -26,7 +27,7 @@ export function registerSessionTools(server) {
         }
         const cliAction = args.action ?? 'list';
         const result = await execAgentBrowser(['tab', cliAction]);
-        return JSON.stringify({ ok: true, tabs: result.stdout.trim() });
+        return JSON.stringify({ ok: true, tabs: wrapUntrusted(result.stdout.trim(), 'browser-automation:tabs') });
     }));
     server.registerTool('browser_close', {
         description: 'Close the browser session. Sessions are saved automatically.',

package/dist/untrusted-content.d.ts

@@ -0,0 +1,33 @@
+/**
+ * AGENTS.md security invariant #6 — content fetched from an external system
+ * MUST be wrapped in an `<untrusted-content source="…">…</untrusted-content>`
+ * envelope (with close-tag breakout escaping) before it is returned to the
+ * LLM, so the model treats third-party / attacker-controllable text as DATA,
+ * not as instructions.
+ *
+ * This is the canonical implementation a new connector ships with. It is a
+ * VENDORED copy of the shared reference in `test-harness/src/untrusted-content.ts`
+ * — connectors cannot `import` the test-harness at runtime (it is a
+ * test/dev-only `file:` dependency that is never published into a connector's
+ * `dist/`), so the helper lives in the connector's own runtime source. Keep
+ * this byte-for-byte in sync with the shared reference; do NOT weaken the
+ * escaping back to a simple `replaceAll` (that family misses whitespace / case
+ * close-tag variants like `</untrusted-content >` / `</UNTRUSTED-CONTENT>`).
+ *
+ * `scripts/check-untrusted-coverage.mjs` greps for a reference to
+ * `untrusted-content` in any connector that talks to an external system; this
+ * file (and the call sites that import from it) is what satisfies that gate.
+ */
+/**
+ * Wrap a single untrusted string in an `<untrusted-content source="…">`
+ * envelope, escaping any embedded close-tag variant so the envelope cannot be
+ * broken out of. `undefined` passes through untouched. Idempotent for the same
+ * `source`.
+ */
+export declare function wrapUntrusted(text: string | null | undefined, source: string): string | undefined;
+/**
+ * Recursively wrap every string value reachable inside `value`. Object keys are
+ * structural and NOT wrapped; non-string leaves pass through unchanged.
+ */
+export declare function wrapUntrustedJsonStrings<T>(value: T, source: string): T;
+//# sourceMappingURL=untrusted-content.d.ts.map

package/dist/untrusted-content.js

@@ -0,0 +1,66 @@
+/**
+ * AGENTS.md security invariant #6 — content fetched from an external system
+ * MUST be wrapped in an `<untrusted-content source="…">…</untrusted-content>`
+ * envelope (with close-tag breakout escaping) before it is returned to the
+ * LLM, so the model treats third-party / attacker-controllable text as DATA,
+ * not as instructions.
+ *
+ * This is the canonical implementation a new connector ships with. It is a
+ * VENDORED copy of the shared reference in `test-harness/src/untrusted-content.ts`
+ * — connectors cannot `import` the test-harness at runtime (it is a
+ * test/dev-only `file:` dependency that is never published into a connector's
+ * `dist/`), so the helper lives in the connector's own runtime source. Keep
+ * this byte-for-byte in sync with the shared reference; do NOT weaken the
+ * escaping back to a simple `replaceAll` (that family misses whitespace / case
+ * close-tag variants like `</untrusted-content >` / `</UNTRUSTED-CONTENT>`).
+ *
+ * `scripts/check-untrusted-coverage.mjs` greps for a reference to
+ * `untrusted-content` in any connector that talks to an external system; this
+ * file (and the call sites that import from it) is what satisfies that gate.
+ */
+const UNTRUSTED_CLOSE_TAG_VARIANT = /<\/untrusted-content\s*>/gi;
+const ESCAPED_UNTRUSTED_CLOSE_TAG = '<\\/untrusted-content>';
+function escapeAttr(s) {
+    return s.replaceAll('&', '&amp;').replaceAll('"', '&quot;').replaceAll('<', '&lt;').replaceAll('>', '&gt;');
+}
+function escapeCloseTagSentinels(s) {
+    return s.replace(UNTRUSTED_CLOSE_TAG_VARIANT, ESCAPED_UNTRUSTED_CLOSE_TAG);
+}
+/**
+ * Wrap a single untrusted string in an `<untrusted-content source="…">`
+ * envelope, escaping any embedded close-tag variant so the envelope cannot be
+ * broken out of. `undefined` passes through untouched. Idempotent for the same
+ * `source`.
+ */
+export function wrapUntrusted(text, source) {
+    if (text === undefined || text === null)
+        return undefined;
+    const open = `<untrusted-content source="${escapeAttr(source)}">`;
+    const close = '</untrusted-content>';
+    if (text.startsWith(open) && text.endsWith(close) && text.length >= open.length + close.length) {
+        const inner = text.slice(open.length, text.length - close.length);
+        if (!UNTRUSTED_CLOSE_TAG_VARIANT.test(inner)) {
+            UNTRUSTED_CLOSE_TAG_VARIANT.lastIndex = 0;
+            return text;
+        }
+        UNTRUSTED_CLOSE_TAG_VARIANT.lastIndex = 0;
+    }
+    return `${open}${escapeCloseTagSentinels(text)}${close}`;
+}
+/**
+ * Recursively wrap every string value reachable inside `value`. Object keys are
+ * structural and NOT wrapped; non-string leaves pass through unchanged.
+ */
+export function wrapUntrustedJsonStrings(value, source) {
+    if (typeof value === 'string') {
+        return wrapUntrusted(value, source);
+    }
+    if (Array.isArray(value)) {
+        return value.map((item) => wrapUntrustedJsonStrings(item, source));
+    }
+    if (value && typeof value === 'object') {
+        return Object.fromEntries(Object.entries(value).map(([key, item]) => [key, wrapUntrustedJsonStrings(item, source)]));
+    }
+    return value;
+}
+//# sourceMappingURL=untrusted-content.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mindstone/mcp-server-browser-automation",
-  "version": "0.1.8",
+  "version": "0.2.0",
   "mcpName": "io.github.mindstone/mcp-server-browser-automation",
   "description": "Browser automation MCP server — visible-by-default browser control via accessibility snapshots, navigation, form filling, screenshots, and tab management. Set AGENT_BROWSER_SHOW_WINDOW=false to run quietly.",
   "license": "FSL-1.1-MIT",