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
• register the toolset and document the new model-facing capability

testing

• bun test (847 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
The tool enables destructive VM filesystem changes (delete, move, writes) on live browser sessions; risk is mitigated by existing Kernel API auth but agent misuse could still cause session data loss.

Overview
Adds a new manage_browser_files MCP tool that exposes the browser VM filesystem through the existing browsers.fs SDK, with project selection aligned to other session-scoped browser tools.

The tool is action-driven: list/info/read for inspection; write, upload, and upload_zip with utf8 or base64 payloads (validated before SDK calls); download and download_dir_zip return binary data as embedded MCP resources with kernel-browser-file:// URIs; plus create/move/delete and set_permissions. Text reads return raw content; mutations are marked destructive in tool annotations.

Wires the capability into MCP registration under the browser_files toolset (aliases browser_fs / manage_browser_files), extends tool-name and project-scoped registration tests, documents it in the README, and adds unit tests covering SDK routing, validation, and resource encoding.

^{Reviewed by Cursor Bugbot for commit 24ae9c8. 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 1, 2026 7:31pm UTC

[cursor]

Stale Bugbot comment from a previous run.

[cursor]

Cursor Bugbot has reviewed your changes using default effort and found 3 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 d5a2072. Configure here.}

[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.