refactor(browser): serve the in-app browser's tools from the desktop over client MCP - #59477

Draft to look at the shape of the code. The in-app browser now registers its tools the way James's client MCP does (#57502–#57506): the desktop hosts an MCP server called browser over /api/experimental/client-mcp, and the server has no browser code at all. @opencode/plugin-browser is deleted.

Before / after

flowchart LR
  subgraph Before
    direction LR
    A1[Agent] --> T1[plugin-browser tools<br/>server]
    T1 --> C1[connection.ts<br/>pending map, grants, state copy]
    C1 -- "event: control {requestID}" --> D1[Desktop pane]
    D1 -- "rpc.command(requestID)" --> C1
    D1 -- "rpc.result(outcome)" --> C1
    D1 -- "rpc.state(inventory)" --> C1
    D1 <-- "rpc.tunnel.*" --> C1
  end
  subgraph After
    direction LR
    A2[Agent] --> M2[core MCP<br/>attached client 'browser']
    M2 -- "tools/call + _meta.sessionID" --> D2[Desktop pane]
    D2 -- "result + structuredContent" --> M2
  end

The whole desktop side

packages/gui-plugins/src/browser/pane.ts serves one connection per server and directory and routes each call by session:

connectClientMcp({
  url: entry.server.url,
  headers: entry.server.headers,
  name: "browser",
  directory,
  instructions,
  tools: browserTools((sessionID) => {
    const pane = Array.from(served).find((item) => item.sessionID === sessionID)
    return pane && {
      execute: (command, signal) => run(pane, command, signal),
      read: (path, signal) => client.file.read({ path, location: { directory } }, { signal }),
    }
  }),
})

packages/gui-plugins/src/browser/mcp.ts turns Browser.Operations into tools: it decodes the input, runs the page, checks the output against the operation's schema, and returns structuredContent. Screenshots go back as image parts. Other captures go back as resource blobs, which the server saves to a file.

What the SDK and core needed

• connectClientMcp (packages/client/src/mcp.ts):
  • instructions option.
  • Per-tool outputSchema.
  • structuredContent and resource parts in results.
  • ctx.signal, which aborts on notifications/cancelled or when the socket closes.
• Mcp.instructions() includes the instructions of the attached client that serves each name, so the browser skill becomes server instructions.
• McpTool content: textual resources over 32 KiB are saved to a file instead of inlined, so a Lighthouse JSON report or a .cpuprofile does not flood the context.

Behavior changes to decide on

• Network: pages load on the desktop's network. localhost is the user's machine, not the server. The tunnel/proxy is gone, so a remote server's dev ports are no longer reachable.
• Tool visibility: tools are scoped to the folder, not the session. Every session in a directory that a desktop pane shows sees browser_*. A session with no pane gets [browser.disconnected]. Before, a deny rule hid the tools until a pane attached to that exact session.
• Permissions: browser tools use the default MCP action names (browser_<tool>), not the browser action.
• Screenshots: returned as an image only, with no server-local path.
• Uploads: paths are relative to the workspace and read through GET /api/fs/read. Absolute server paths are no longer accepted.
• Error messages: many still say browser.tabs.list({}); Code Mode now uses browser.tabs_list.