feat: add --file-navigations flag to reject file: URL navigations - #2853

Generally, the filesystem roots apply to the MCP server code not to the browser actions. There are probably dozens of way by which the web page can trigger file system access so I am not sure changing this makes sense. Previously we classified it as working according to the security.md (the client should validate tool calls https://github.com/ChromeDevTools/chrome-devtools-mcp/security/advisories/GHSA-gjv5-335h-4qcq).

I think this also does not work if the browser is on a different host relative to the MCP server. I do not have access to the VRP issue but I think it should be closed as a won't fix. What we could land instead is a CLI flag --file-navigations=boolean and reject the file navigations altogether without checking MCP server roots.

Thanks for the review @OrKoN . You're right on every point, so I've dropped the roots approach and implemented the CLI flag you suggested.

What the VRP issue describes

You can't see the tracker, so here it is in full.

With a client that negotiates roots, the file-aware tools enforce them. take_screenshot / take_snapshot refuse a filePath outside the roots:

take_screenshot { "filePath": "<cwd>/outside/x.png" }
-> Error: Access denied: path <cwd>/outside/x.png is not within any of the
   configured workspace roots.

new_page / navigate_page only called validateUrl(), which checks the scheme and not the path. So with those same roots configured and actively refusing the calls above:

new_page { "url": "file://<cwd>/outside/secret.txt" }   -> page created, no error
evaluate_script { "function": "() => document.body.innerText" }
-> "CANARY_SECRET_a7f3e91c_DO_NOT_LEAK"

take_snapshot returns the same content as StaticText. file:///etc/passwd and directory listings (file:///, file:///home/) behave the same way.

I reported it because SECURITY.md states:

If the client specifies them, the MCP server will check the roots when accessing files.

In fairness, the same paragraph adds that you treat MCP roots issues as low severity because roots are optional, so the severity cap was documented and I should have weighted it higher before filing.

That is the whole issue: a caller who can issue one tool call reads any file the server's user can read. It requires a tool call the client is expected to have vetted, and it goes no further than reading local files.

On your points

I agree with all four.

• Roots restrict paths on the MCP server side. Navigation is a browser action. Enforcing one through the other conflates two layers.
• The remote-browser case decides it. With --browserUrl pointing at another host, my validatePath() call resolved a path on the MCP server's filesystem, which tells you nothing about what the browser will open. That alone rules the approach out.
• Your SECURITY.md position that the calling agent validates tool calls does cover this, and GHSA-gjv5-335h-4qcq already classifies the class. Closing the VRP issue as a won't fix is reasonable.
• On the dozens of other ways a page can reach the filesystem: agreed, and this flag does not address them. It gates one thing only — whether the server accepts a file: URL as a navigation target — which is the part the server decides.

What this PR now contains

I removed the roots check, the Context.validateUrl method, and the validatePath exposure on Context. The PR no longer touches McpContext.ts or ToolDefinition.ts.

I added:

• --file-navigations (also accepted as --fileNavigations), boolean, default true. Declared in mcpOptions, so it picks up the usual negation forms (--no-file-navigations, --file-navigations=false) and docs:generate documents it in docs/configuration.md.

• fileNavigations on ValidateUrlOptions, checked in validateUrl() beside the existing gates:

  if (fileNavigations === false && parsed.protocol === 'file:') {
    throw new Error(
      `Navigating to file: URLs is not allowed when --file-navigations is disabled.`,
    );
  }

• The option threaded through all three navigation entry points: new_page, navigate_page, and the slim navigate.

The check reads parsed.protocol and nothing else, so it performs no filesystem access and behaves the same for a local or a remote browser.

Two things worth calling out:

• The flag rejects every file: navigation when disabled, including a path inside a configured root. That follows from rejecting on scheme rather than consulting roots, which is what you asked for, but it is a behaviour change for anyone who both configures roots and navigates to files inside them.
• On @Lightning00Blade's earlier point that the check is easy to forget: I made fileNavigations a required field on ValidateUrlOptions rather than optional, so a new navigation tool that calls validateUrl() without passing it fails to compile.

The default

I chose true, which keeps current behaviour and makes the flag opt-in. If you'd rather make file: navigation opt-in instead and default to false, say so and I'll flip it — it's a one-line change plus test updates.

Verification

7 tests added: flag parsing (both spellings and the negated form), validateUrl accept / reject / leaves other schemes alone, and per-tool rejection for new_page, navigate_page and slim navigate, asserting goto never runs.

I also ran the reporting client against the built server. With no flag, new_page on a file: URL still returns the file contents. With --no-file-navigations, new_page and navigate_page both return the error above, and http:// navigation keeps working in both modes.

Thanks!

If the client specifies them, the MCP server will check the roots when accessing files.

To clarify: in this case, the MCP server does not access the files, the browser does. The file URL might have been already loaded in the browser before the MCP server connects to the (potentially) browser so enforcing MCP roots on the browser end does not really work that well.

That's a fair correction, and I tested it rather than just taking the point.

I launched Chrome separately with file:///…/outside/secret.txt already open, then connected the MCP server to it with --browserUrl, roots set to a different directory, and --no-file-navigations:

list_pages      -> 1: secret.txt (file:///…/outside/secret.txt) [selected]
evaluate_script -> "CANARY_SECRET_a7f3e91c_DO_NOT_LEAK"
take_snapshot   -> RootWebArea url="file:///…/outside/secret.txt"

So the pre-existing page is reachable, the flag does not touch it, and roots have no bearing on it. You're right that the SECURITY.md sentence I quoted is about the server accessing files, and that is not what happens here — the browser holds the page and the server reads what the browser already has.

I've taken that into the flag's own description, so it doesn't get mistaken for a sandbox:

This restricts navigations the server performs. It is not a filesystem sandbox: it does not affect pages the browser already had open when the server connected, and the browser can reach the filesystem by other means. Use OS sandboxing for full filesystem confinement.

Happy to reword that if you'd put it differently.

That leaves the flag doing one narrow thing: refusing a file: navigation the server is asked to perform. That seems worth having on its own terms, but it is not a boundary and the description now says so.