Expose browser filesystem through MCP

[masnwilliams]

summary

• add a manage_browser_files MCP tool backed by the existing browser filesystem SDK
• support text and base64 writes/uploads, embedded-resource downloads, directory archives, and filesystem management actions
• cap read, download, and download_dir_zip at max_bytes (default 10 MiB, maximum 25 MiB), refusing oversized files and archives instead of truncating them
• register the toolset and document the new model-facing capability

testing

• bun test (908 tests passed, after merging main)
• bunx tsc --noEmit
• targeted Prettier check for changed files
• bun run build compiled and typechecked successfully, then stopped during page-data collection because KERNEL_CLI_PROD_CLIENT_ID is not set in the local environment

---

Note

Medium Risk
Introduces destructive remote filesystem operations (write/delete/move/permissions) on browser VMs; mitigated by auth, size limits, and no automatic retries on mutations.

Overview
Adds a new manage_browser_files MCP tool (toolset browser_files, aliases browser_fs / manage_browser_files) so agents can work with files inside a live browser VM via the existing browsers.fs SDK.

The tool is action-based (list, read, download, write, upload, zip upload/extract, directory zip download, mkdir, move, delete, permissions). Reads and downloads enforce max_bytes (default 10 MiB, max 25 MiB) with pre-checks and streaming caps—oversized files/archives are rejected, not truncated. Binary payloads come back as embedded MCP resources; mutations use maxRetries: 0. Paths must be absolute; content is utf8/base64 only (no host filesystem access).

Wiring updates: register the toolset, include it in project-scoped tools and visibility tests, document it in README, and note that live session names work as session_id for this tool alongside other browser tools.

^{Reviewed by Cursor Bugbot for commit 0e07de8. Bugbot is set up for automated code reviews on this repo. Configure here.}

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated
mcp	Ready	Preview	Oct 6, 2026 2:59pm UTC

[cursor]

Stale Bugbot comment from a previous run.

[cursor]

Stale Bugbot comment from a previous run.

[dcruzeneil2]

LGTM overall — thin, correctly-typed adapter over browsers.fs, consistent with the other manage_* tools, bugbot findings addressed properly, tests exercise the real MCP contract. no new privilege: exec_command --as_root and browser_repl already give full VM filesystem access, this just makes it structured. approving with one should-fix and some nits.

should-fix before merge

• bound read / download / download_dir_zip. responseBuffer() buffers the whole file, base64s it, and returns it in one JSON-RPC message. nothing upstream caps this either — kernel/kernel's ReadFile buffers the full body and the in-VM API streams whatever is on disk. download_dir_zip on /home/kernel is a one-liner for a model and will OOM or blow the response limit (the same budget shell.ts caps timeout_sec for). suggest a max_bytes param (default ~10–25MB); for read/download call fileInfo first and refuse over the cap with a hint to narrow via list/get_info/exec_command; for the zip, stop at the cap and error.

nits

• paths are described as absolute but not enforced. only upload/upload_zip check IsAbs on the VM side; read/write/move/delete_* resolve relative paths against the API process cwd. encodedPath() already assumes absolute (prepends /), so a relative read returns a resource URI claiming a path that isn't where the file is. a .regex(/^\//) on path/src_path/dest_path makes the schema match its own description.
• SDK defaults (60s timeout, maxRetries: 2) apply to every action. a large write/upload that times out is re-sent up to three times, and a move that completed but lost its response gets retried and reports 404. maxRetries: 0 for the mutating actions, or longOperationOptions like shell.ts.
• session_id says "Browser session ID." — SDK param is idOrName, every other session tool says "ID or name". also add manage_browser_files to the two lists of name-accepting tools (README ~L325 and browsers.ts name description).
• read on binary returns mojibake silently; if the decoded text contains U+FFFD, append "appears binary; use download".
• the content-type fallback in download is dead — the VM API always returns application/octet-stream — so mime_type is the only way to get a real type; say so in its description.
• no tests for upload_zip or the mime_type override.

[cursor]

Cursor Bugbot has reviewed your changes using default effort and found 2 potential issues.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit 9093120. Configure here.}

[masnwilliams]

thanks @dcruzeneil2. everything from your review is addressed, mostly in 9093120, with a BugBot follow-up in 0e07de8. main is merged in at 4c06710, which also lowercases this tool's copy and adds its entry to the new annotations table so main's tests pass.

should-fix

• bounded reads (9093120): new max_bytes param, default 10 MiB, maximum 25 MiB, documented in the schema and README. read/download call fileInfo first and refuse anything over the cap with a hint to narrow via list/get_info/exec_command. The body is also read through a capped stream, so a file that grows after the size check is still refused. download_dir_zip checks content-length, then streams the archive and cancels it once the cap is exceeded. Tests cover over-cap read/download (no readFile call), a file that grows past the cap, and a streamed archive cancelled at the cap.

nits

1. absolute paths (9093120): path, src_path, dest_path, and files[].dest_path require a leading / ("must be an absolute path starting with /"). encodedPath no longer prepends one. In 0e07de8 the schema became a per-field factory so the advertised JSON schema never uses $ref.
2. retries (9093120): write, upload, upload_zip, move, delete_*, create_directory, and set_permissions pass { maxRetries: 0, signal: ctx.mcpReq.signal }, the pattern the vault/config tools use. longOperationOptions didn't fit because the fs endpoints have no server-side budget. 0e07de8 extends the same options to download_dir_zip so an archive isn't rebuilt on retry.
3. session names (9093120): session_id is now "browser session id or name.", and manage_browser_files is added to the name-accepting lists in the README and the browsers.ts name description.
4. binary reads (9093120): if the decoded text contains U+FFFD, read appends a note that the file appears binary and to use download.
5. mime_type (9093120): the description now says the VM always serves application/octet-stream, so mime_type is the only way to set a real type. The dead content-type fallback is removed and the default is application/octet-stream.
6. tests (9093120): added tests for upload_zip (archive bytes, dest path, no retries) and the mime_type override.

CI and BugBot are green on 0e07de8. The PR body's test count is updated to 908.