From d80752d03447370a0e16b7023dbb97dbac6eaee6 Mon Sep 17 00:00:00 2001
From: Anthony Ettinger <anthony@chovy.com>
Date: Sat, 4 Jul 2026 14:43:46 +0000
Subject: [PATCH] feat(m3.6): local MCP server (tron mcp)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Adds `tron mcp`, a local Model Context Protocol server over stdio (PRD §14),
exposing TronBrowser's browser + analyze tools to any MCP host.

Dependency-free protocol layer (packages/sdk/src/mcp) — a minimal JSON-RPC 2.0
server (initialize/tools/list/tools/call/ping) so the shipped runtime stays
self-contained (no @modelcontextprotocol/sdk). Tools wrap the SDK Browser/Page,
so M3.1–M3.5 are reused rather than reimplemented.

Tools: browser_open/snapshot/click/fill/type/press/select/scroll/wait/extract/
screenshot/tabs/close, plus the AI-assisted browser_analyze (non-mutating
dry-run), browser_step, and browser_run_task. Mutating tools return a fresh
snapshot; screenshot returns image content.

The managed session launches lazily on first tool use and tears down on
browser_close. install.sh routes `tron mcp` via tron-node.mjs with
TRON_SESSION_BIN; the server ships in the existing sdk/ payload.

Tests (+11): protocol (initialize/list/call/ping/unknown/notification), all
tools against a fake page (mutations return snapshots, screenshot image,
analyze dry-run, close), and the newline-delimited stdio transport. Verified the
full server end-to-end over stdio (initialize -> tools/list -> browser_open ->
browser_close) against a WS CDP stub session. Full workspace suite green.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
---
 apps/web/public/install.sh       |   9 ++
 docs/mcp.md                      |  67 ++++++++++++
 packages/sdk/src/mcp-bin.ts      |  25 +++++
 packages/sdk/src/mcp/index.ts    |   8 ++
 packages/sdk/src/mcp/mcp.test.ts | 128 ++++++++++++++++++++++
 packages/sdk/src/mcp/protocol.ts | 104 ++++++++++++++++++
 packages/sdk/src/mcp/server.ts   |  42 +++++++
 packages/sdk/src/mcp/session.ts  |  66 +++++++++++
 packages/sdk/src/mcp/tools.ts    | 181 +++++++++++++++++++++++++++++++
 9 files changed, 630 insertions(+)
 create mode 100644 docs/mcp.md
 create mode 100644 packages/sdk/src/mcp-bin.ts
 create mode 100644 packages/sdk/src/mcp/index.ts
 create mode 100644 packages/sdk/src/mcp/mcp.test.ts
 create mode 100644 packages/sdk/src/mcp/protocol.ts
 create mode 100644 packages/sdk/src/mcp/server.ts
 create mode 100644 packages/sdk/src/mcp/session.ts
 create mode 100644 packages/sdk/src/mcp/tools.ts

diff --git a/apps/web/public/install.sh b/apps/web/public/install.sh
index ecf2d94..e842fd1 100755
--- a/apps/web/public/install.sh
+++ b/apps/web/public/install.sh
@@ -92,6 +92,7 @@ Usage:
   tron headless <url>   One-shot: --snapshot | --screenshot <p> | --extract <mode>
   tron run <script>     Run a JS/TS script using @tronbrowser/sdk (--headless/--trace)
   tron analyze [goal]   Analyze/fill a form or page (--data, --execute, --json)
+  tron mcp              Run a local MCP server over stdio (--headless)
   tron upgrade          Update to the latest release
   tron remove           Uninstall TronBrowser (keeps your profile data)
   tron version          Print the installed version
@@ -188,6 +189,14 @@ case "${1:-}" in
   headless)
     # One-shot: launch a headless ephemeral session, navigate, act, tear down.
     run_automation "$@" ;;
+  mcp)
+    # Local Model Context Protocol server over stdio (PRD M3.6).
+    shift
+    _ld="$(dirname "$(readlink -f "$CURRENT" 2>/dev/null || echo "$CURRENT")")"
+    ENTRY="$_ld/sdk/mcp-bin.js"
+    command -v node >/dev/null 2>&1 || { echo "tron mcp needs Node.js (>=22) on PATH." >&2; exit 1; }
+    [ -f "$ENTRY" ] || { echo "This TronBrowser build lacks the MCP server. Run: tron upgrade" >&2; exit 1; }
+    exec env TRON_SESSION_BIN="$(session_bin)" node "$_ld/tron-node.mjs" "$ENTRY" "$@" ;;
   run)
     # Execute a JS/TS automation script that imports @tronbrowser/sdk (PRD M3.4).
     shift
diff --git a/docs/mcp.md b/docs/mcp.md
new file mode 100644
index 0000000..3dd75b5
--- /dev/null
+++ b/docs/mcp.md
@@ -0,0 +1,67 @@
+# MCP server (M3.6)
+
+`tron mcp` runs a local [Model Context Protocol](https://modelcontextprotocol.io)
+server over **stdio**, exposing TronBrowser's browser + analyze tools to any MCP
+host (Claude Desktop, IDE agents, etc.).
+
+```sh
+tron mcp                # headed managed session
+tron mcp --headless     # headless
+tron mcp --profile work
+```
+
+It speaks newline-delimited JSON-RPC 2.0 on stdin/stdout — **local only**, never
+a network listener. The managed session launches lazily on the first tool call
+and is torn down on `browser_close` (or when the host disconnects).
+
+## Example host config
+
+```json
+{
+  "mcpServers": {
+    "tronbrowser": { "command": "tron", "args": ["mcp", "--headless"] }
+  }
+}
+```
+
+## Tools
+
+Primitive browser tools:
+
+```
+browser_open      browser_snapshot   browser_click     browser_fill
+browser_type      browser_press      browser_select    browser_scroll
+browser_wait      browser_extract    browser_screenshot browser_tabs
+browser_close
+```
+
+AI-assisted unknown-interface tools:
+
+```
+browser_analyze   # non-mutating: analyze the page / map a form to data (dry-run)
+browser_step      # one validated action toward a goal
+browser_run_task  # bounded unknown-interface task
+```
+
+- **Mutating tools return a fresh snapshot** (open/click/fill/type/press/select/
+  scroll), so the host always sees current, ref-tagged page state.
+- `browser_screenshot` returns image content (PNG); `browser_extract`,
+  `browser_analyze`, `browser_step`, `browser_run_task`, and `browser_tabs`
+  return JSON text.
+- `browser_analyze`/`step`/`run_task` are backed by the deterministic analyze
+  engine (M3.5), so form-fill works without an AI provider; open-ended goals
+  report `AI_PROVIDER_NOT_CONFIGURED`.
+
+## How it works
+
+- The shell `tron` dispatcher runs `sdk/mcp-bin.js` via `tron-node.mjs` (which
+  resolves the `@tronbrowser/*` imports) with `TRON_SESSION_BIN` set so the
+  server can launch/close its managed session.
+- The MCP protocol layer is a small, dependency-free JSON-RPC 2.0 server
+  (`packages/sdk/src/mcp`) — no `@modelcontextprotocol/sdk` dependency, keeping
+  the shipped runtime self-contained. Tools wrap the SDK `Browser`/`Page`.
+
+## Scope
+
+- Requires Node ≥22. Runs over stdio; remote transports are out of scope.
+- Cookies/local storage are not exposed as tools.
diff --git a/packages/sdk/src/mcp-bin.ts b/packages/sdk/src/mcp-bin.ts
new file mode 100644
index 0000000..691b85d
--- /dev/null
+++ b/packages/sdk/src/mcp-bin.ts
@@ -0,0 +1,25 @@
+/**
+ * `tron mcp` — local MCP server over stdio (PRD M3.6). Built into the launcher
+ * payload (sdk/mcp-bin.js) and run via tron-node.mjs so @tronbrowser/* resolve.
+ */
+import { createMcpServer } from './mcp/server.js';
+import { serveStdio } from './mcp/server.js';
+import { McpBrowserSession } from './mcp/session.js';
+
+const argv = process.argv.slice(2);
+const headless = argv.includes('--headless');
+const profileIdx = argv.indexOf('--profile');
+const profile = profileIdx >= 0 ? argv[profileIdx + 1] : undefined;
+
+const session = McpBrowserSession.fromSdk({ headless, ...(profile ? { profile } : {}) });
+const server = createMcpServer(session);
+
+process.stderr.write('tron mcp: TronBrowser MCP server on stdio\n');
+
+serveStdio(server, {
+  input: process.stdin,
+  write: (line) => process.stdout.write(line),
+}).catch((err: unknown) => {
+  process.stderr.write(`tron mcp: ${err instanceof Error ? err.message : String(err)}\n`);
+  process.exit(1);
+});
diff --git a/packages/sdk/src/mcp/index.ts b/packages/sdk/src/mcp/index.ts
new file mode 100644
index 0000000..e1507fd
--- /dev/null
+++ b/packages/sdk/src/mcp/index.ts
@@ -0,0 +1,8 @@
+/**
+ * @tronbrowser/sdk — MCP server (PRD M3.6). Local stdio Model Context Protocol
+ * server exposing TronBrowser's browser + analyze tools.
+ */
+export * from './protocol.js';
+export * from './session.js';
+export * from './tools.js';
+export * from './server.js';
diff --git a/packages/sdk/src/mcp/mcp.test.ts b/packages/sdk/src/mcp/mcp.test.ts
new file mode 100644
index 0000000..3bc8c6a
--- /dev/null
+++ b/packages/sdk/src/mcp/mcp.test.ts
@@ -0,0 +1,128 @@
+import { Readable } from 'node:stream';
+import { describe, expect, it } from 'vitest';
+import type { AgentSnapshot } from '@tronbrowser/browser-core';
+import { McpServer } from './protocol.js';
+import { McpBrowserSession, type McpPage } from './session.js';
+import { createMcpServer, serveStdio } from './server.js';
+
+const SNAP: AgentSnapshot = {
+  url: 'https://x/', title: 'X', timestamp: 't',
+  elements: [{ ref: '@e1', role: 'link', name: 'More', tag: 'a', interactive: true, visible: true }],
+};
+
+function fakePage() {
+  const calls: string[] = [];
+  const page: McpPage = {
+    id: 'p1',
+    goto: async (u) => { calls.push('goto:' + u); },
+    snapshot: async () => SNAP,
+    click: async (r) => { calls.push('click:' + r); },
+    fill: async (r, v) => { calls.push('fill:' + r + '=' + v); },
+    extract: async (m) => ({ mode: m }),
+    screenshot: async () => Buffer.from('PNG'),
+    eval: async () => { calls.push('eval'); return null as never; },
+    url: async () => 'https://x/',
+    title: async () => 'X',
+    analyze: async (g) => ({ ok: true, mode: 'dry-run', status: 'planned', page: { url: 'x', title: 'X' }, ...(g ? { goal: g } : {}) }),
+    step: async () => ({ ok: true, mode: 'execute', status: 'acted', page: { url: 'x', title: 'X' } }),
+    runTask: async () => ({ ok: true, mode: 'execute', status: 'complete', page: { url: 'x', title: 'X' } }),
+  };
+  return { page, calls };
+}
+
+function harness() {
+  const { page, calls } = fakePage();
+  let closed = false;
+  const session = new McpBrowserSession(async () => ({ page, close: async () => { closed = true; } }));
+  const server = createMcpServer(session);
+  const call = async (name: string, args: Record<string, unknown> = {}) =>
+    server.handle({ jsonrpc: '2.0', id: 1, method: 'tools/call', params: { name, arguments: args } });
+  return { server, call, calls, isClosed: () => closed };
+}
+
+describe('MCP protocol', () => {
+  const { server } = harness();
+  it('handles initialize with capabilities + serverInfo', async () => {
+    const r = await server.handle({ jsonrpc: '2.0', id: 1, method: 'initialize', params: { protocolVersion: '2025-06-18' } });
+    expect((r!.result as { serverInfo: { name: string } }).serverInfo.name).toBe('tronbrowser');
+    expect((r!.result as { protocolVersion: string }).protocolVersion).toBe('2025-06-18');
+    expect((r!.result as { capabilities: { tools: unknown } }).capabilities.tools).toBeDefined();
+  });
+  it('lists all browser tools', async () => {
+    const r = await server.handle({ jsonrpc: '2.0', id: 2, method: 'tools/list' });
+    const names = (r!.result as { tools: Array<{ name: string }> }).tools.map((t) => t.name);
+    expect(names).toEqual(expect.arrayContaining([
+      'browser_open', 'browser_snapshot', 'browser_click', 'browser_fill', 'browser_extract',
+      'browser_screenshot', 'browser_tabs', 'browser_close', 'browser_analyze', 'browser_step', 'browser_run_task',
+    ]));
+  });
+  it('returns null for a notification (no id)', async () => {
+    expect(await server.handle({ jsonrpc: '2.0', method: 'notifications/initialized' })).toBeNull();
+  });
+  it('answers ping and errors on unknown method', async () => {
+    expect((await server.handle({ jsonrpc: '2.0', id: 3, method: 'ping' }))!.result).toEqual({});
+    const e = await server.handle({ jsonrpc: '2.0', id: 4, method: 'nope' });
+    expect(e!.error!.code).toBe(-32601);
+  });
+});
+
+describe('MCP tools', () => {
+  it('browser_open navigates and returns a fresh snapshot', async () => {
+    const { call, calls } = harness();
+    const r = await call('browser_open', { url: 'https://x/' });
+    expect(calls).toContain('goto:https://x/');
+    expect((r!.result as { content: Array<{ text: string }> }).content[0].text).toContain('@e1 link "More"');
+  });
+  it('browser_click / browser_fill act then return a snapshot', async () => {
+    const { call, calls } = harness();
+    await call('browser_click', { ref: '@e1' });
+    await call('browser_fill', { ref: '@e2', value: 'hi' });
+    expect(calls).toContain('click:@e1');
+    expect(calls).toContain('fill:@e2=hi');
+  });
+  it('browser_screenshot returns image content', async () => {
+    const { call } = harness();
+    const r = await call('browser_screenshot');
+    const content = (r!.result as { content: Array<{ type: string; data: string; mimeType: string }> }).content[0];
+    expect(content.type).toBe('image');
+    expect(content.mimeType).toBe('image/png');
+    expect(Buffer.from(content.data, 'base64').toString()).toBe('PNG');
+  });
+  it('browser_analyze returns a dry-run result', async () => {
+    const { call } = harness();
+    const r = await call('browser_analyze', { goal: 'Fill form' });
+    const parsed = JSON.parse((r!.result as { content: Array<{ text: string }> }).content[0].text);
+    expect(parsed.status).toBe('planned');
+    expect(parsed.goal).toBe('Fill form');
+  });
+  it('browser_close closes an opened session', async () => {
+    const { call, isClosed } = harness();
+    await call('browser_snapshot'); // opens the session
+    await call('browser_close');
+    expect(isClosed()).toBe(true);
+  });
+  it('reports isError for an unknown tool', async () => {
+    const { call } = harness();
+    const r = await call('browser_bogus');
+    expect((r!.result as { isError: boolean }).isError).toBe(true);
+  });
+});
+
+describe('MCP stdio transport', () => {
+  it('reads newline-delimited requests and writes responses', async () => {
+    const server = new McpServer({ name: 'tronbrowser', version: '3.7' });
+    const out: string[] = [];
+    await serveStdio(server, {
+      input: Readable.from([
+        '{"jsonrpc":"2.0","id":1,"method":"initialize"}\n',
+        '{"jsonrpc":"2.0","method":"notifications/initialized"}\n',
+        '{"jsonrpc":"2.0","id":2,"method":"tools/list"}\n',
+      ]),
+      write: (line) => out.push(line.trim()),
+    });
+    // one response for initialize, none for the notification, one for tools/list
+    expect(out).toHaveLength(2);
+    expect(JSON.parse(out[0]).id).toBe(1);
+    expect(JSON.parse(out[1]).id).toBe(2);
+  });
+});
diff --git a/packages/sdk/src/mcp/protocol.ts b/packages/sdk/src/mcp/protocol.ts
new file mode 100644
index 0000000..1376404
--- /dev/null
+++ b/packages/sdk/src/mcp/protocol.ts
@@ -0,0 +1,104 @@
+/**
+ * Minimal Model Context Protocol server core (PRD M3.6). Dependency-free:
+ * implements the JSON-RPC 2.0 methods an MCP host needs (initialize, tools/list,
+ * tools/call, ping) so the shipped runtime stays self-contained. Transport-
+ * agnostic — `handle()` maps a parsed message to a response (or null for
+ * notifications); `mcp-bin` wires it to newline-delimited stdio.
+ */
+
+export interface JsonRpcMessage {
+  jsonrpc: '2.0';
+  id?: number | string;
+  method?: string;
+  params?: Record<string, unknown>;
+  result?: unknown;
+  error?: { code: number; message: string };
+}
+
+export type McpContent =
+  | { type: 'text'; text: string }
+  | { type: 'image'; data: string; mimeType: string };
+
+export interface McpTool {
+  name: string;
+  description: string;
+  inputSchema: Record<string, unknown>;
+  handler(args: Record<string, unknown>): Promise<McpContent[]>;
+}
+
+export interface McpServerInfo {
+  name: string;
+  version: string;
+}
+
+const DEFAULT_PROTOCOL_VERSION = '2024-11-05';
+
+function ok(id: number | string, result: unknown): JsonRpcMessage {
+  return { jsonrpc: '2.0', id, result };
+}
+function fail(id: number | string, code: number, message: string): JsonRpcMessage {
+  return { jsonrpc: '2.0', id, error: { code, message } };
+}
+
+export class McpServer {
+  readonly #info: McpServerInfo;
+  readonly #tools = new Map<string, McpTool>();
+
+  constructor(info: McpServerInfo) {
+    this.#info = info;
+  }
+
+  register(tool: McpTool): void {
+    this.#tools.set(tool.name, tool);
+  }
+
+  tools(): McpTool[] {
+    return [...this.#tools.values()];
+  }
+
+  /** Handle one JSON-RPC message; returns a response, or null for notifications. */
+  async handle(msg: JsonRpcMessage): Promise<JsonRpcMessage | null> {
+    // Notifications have no id and expect no response.
+    if (msg.id === undefined) return null;
+    const id = msg.id;
+
+    switch (msg.method) {
+      case 'initialize': {
+        const requested = (msg.params?.protocolVersion as string | undefined) ?? DEFAULT_PROTOCOL_VERSION;
+        return ok(id, {
+          protocolVersion: requested,
+          capabilities: { tools: { listChanged: false } },
+          serverInfo: this.#info,
+        });
+      }
+      case 'ping':
+        return ok(id, {});
+      case 'tools/list':
+        return ok(id, {
+          tools: this.tools().map((t) => ({
+            name: t.name,
+            description: t.description,
+            inputSchema: t.inputSchema,
+          })),
+        });
+      case 'tools/call': {
+        const name = msg.params?.name as string | undefined;
+        const args = (msg.params?.arguments as Record<string, unknown> | undefined) ?? {};
+        const tool = name ? this.#tools.get(name) : undefined;
+        if (!tool) {
+          return ok(id, { content: [{ type: 'text', text: `Unknown tool: ${name ?? '(none)'}` }], isError: true });
+        }
+        try {
+          return ok(id, { content: await tool.handler(args) });
+        } catch (err) {
+          return ok(id, {
+            content: [{ type: 'text', text: `Error: ${err instanceof Error ? err.message : String(err)}` }],
+            isError: true,
+          });
+        }
+      }
+      default:
+        return fail(id, -32601, `Method not found: ${msg.method ?? '(none)'}`);
+    }
+  }
+}
diff --git a/packages/sdk/src/mcp/server.ts b/packages/sdk/src/mcp/server.ts
new file mode 100644
index 0000000..bd1c4a8
--- /dev/null
+++ b/packages/sdk/src/mcp/server.ts
@@ -0,0 +1,42 @@
+/**
+ * Assemble the MCP server from a browser session, and a newline-delimited stdio
+ * transport (PRD M3.6). Local only — the host speaks JSON-RPC over stdin/stdout.
+ */
+import { McpServer, type McpServerInfo } from './protocol.js';
+import type { McpBrowserSession } from './session.js';
+import { browserTools } from './tools.js';
+
+const DEFAULT_INFO: McpServerInfo = { name: 'tronbrowser', version: '3.7' };
+
+export function createMcpServer(session: McpBrowserSession, info: McpServerInfo = DEFAULT_INFO): McpServer {
+  const server = new McpServer(info);
+  for (const tool of browserTools(session)) server.register(tool);
+  return server;
+}
+
+export interface StdioTransport {
+  input: AsyncIterable<string | Uint8Array>;
+  write(line: string): void;
+}
+
+/** Read newline-delimited JSON-RPC from input, write responses to output. */
+export async function serveStdio(server: McpServer, io: StdioTransport): Promise<void> {
+  let buffer = '';
+  for await (const chunk of io.input) {
+    buffer += typeof chunk === 'string' ? chunk : Buffer.from(chunk).toString('utf8');
+    let nl: number;
+    while ((nl = buffer.indexOf('\n')) >= 0) {
+      const line = buffer.slice(0, nl).trim();
+      buffer = buffer.slice(nl + 1);
+      if (!line) continue;
+      let msg: unknown;
+      try {
+        msg = JSON.parse(line);
+      } catch {
+        continue; // skip malformed lines
+      }
+      const response = await server.handle(msg as never);
+      if (response) io.write(JSON.stringify(response) + '\n');
+    }
+  }
+}
diff --git a/packages/sdk/src/mcp/session.ts b/packages/sdk/src/mcp/session.ts
new file mode 100644
index 0000000..1d4f515
--- /dev/null
+++ b/packages/sdk/src/mcp/session.ts
@@ -0,0 +1,66 @@
+/**
+ * The browser session an MCP server drives (PRD M3.6). Lazily launches a managed
+ * session on first tool use and hands out a page. Structural `McpPage` keeps it
+ * testable — the concrete SDK Page satisfies it, and fakes can too.
+ */
+import type { AgentSnapshot } from '@tronbrowser/browser-core';
+import type { AnalyzeOptions, AnalyzeResult } from '@tronbrowser/agent-runtime';
+import { Browser, type LaunchOptions } from '../browser.js';
+
+export interface McpPage {
+  id: string;
+  goto(url: string): Promise<void>;
+  snapshot(): Promise<AgentSnapshot>;
+  click(ref: string): Promise<void>;
+  fill(ref: string, value: string): Promise<void>;
+  extract(target: string): Promise<unknown>;
+  screenshot(): Promise<Uint8Array>;
+  eval<T = unknown>(code: string): Promise<T>;
+  url(): Promise<string>;
+  title(): Promise<string>;
+  analyze(goal?: string, options?: AnalyzeOptions): Promise<AnalyzeResult>;
+  step(goal: string, options?: AnalyzeOptions): Promise<AnalyzeResult>;
+  runTask(goal: string, options?: AnalyzeOptions): Promise<AnalyzeResult>;
+}
+
+export interface Tab {
+  id: string;
+  url: string;
+  title: string;
+}
+
+export type SessionLauncher = () => Promise<{ page: McpPage; close: () => Promise<void> }>;
+
+export class McpBrowserSession {
+  readonly #launch: SessionLauncher;
+  #current: { page: McpPage; close: () => Promise<void> } | undefined;
+
+  constructor(launch: SessionLauncher) {
+    this.#launch = launch;
+  }
+
+  /** Default launcher: a managed SDK Browser + one page. */
+  static fromSdk(options: LaunchOptions = {}): McpBrowserSession {
+    return new McpBrowserSession(async () => {
+      const browser = await Browser.launch(options);
+      const page = (await browser.newPage()) as unknown as McpPage;
+      return { page, close: () => browser.close() };
+    });
+  }
+
+  async getPage(): Promise<McpPage> {
+    this.#current ??= await this.#launch();
+    return this.#current.page;
+  }
+
+  async tabs(): Promise<Tab[]> {
+    const page = await this.getPage();
+    return [{ id: page.id, url: await page.url(), title: await page.title() }];
+  }
+
+  async close(): Promise<void> {
+    const current = this.#current;
+    this.#current = undefined;
+    await current?.close();
+  }
+}
diff --git a/packages/sdk/src/mcp/tools.ts b/packages/sdk/src/mcp/tools.ts
new file mode 100644
index 0000000..43c36dd
--- /dev/null
+++ b/packages/sdk/src/mcp/tools.ts
@@ -0,0 +1,181 @@
+/**
+ * Browser tools exposed over MCP (PRD §14). Primitive tools plus the AI-assisted
+ * browser_analyze / browser_step / browser_run_task. Mutating tools return a
+ * fresh snapshot (PRD §10). All action on the managed session's current page.
+ */
+import { formatSnapshotText, type AgentSnapshot } from '@tronbrowser/browser-core';
+import type { McpContent, McpTool } from './protocol.js';
+import type { McpBrowserSession, McpPage } from './session.js';
+
+const str = (v: unknown, fallback = ''): string => (typeof v === 'string' ? v : v === undefined ? fallback : String(v));
+const snapshotContent = (snap: AgentSnapshot): McpContent[] => [{ type: 'text', text: formatSnapshotText(snap) }];
+const jsonContent = (data: unknown): McpContent[] => [{ type: 'text', text: JSON.stringify(data, null, 2) }];
+
+async function freshSnapshot(page: McpPage): Promise<McpContent[]> {
+  return snapshotContent(await page.snapshot());
+}
+
+const obj = (properties: Record<string, unknown>, required: string[] = []) => ({
+  type: 'object' as const,
+  properties,
+  ...(required.length ? { required } : {}),
+});
+
+export function browserTools(session: McpBrowserSession): McpTool[] {
+  const page = () => session.getPage();
+  return [
+    {
+      name: 'browser_open',
+      description: 'Open a URL in the managed session and return a page snapshot.',
+      inputSchema: obj({ url: { type: 'string' } }, ['url']),
+      handler: async (a) => {
+        const p = await page();
+        await p.goto(str(a.url));
+        return freshSnapshot(p);
+      },
+    },
+    {
+      name: 'browser_snapshot',
+      description: 'Return a structured, ref-tagged snapshot of the current page.',
+      inputSchema: obj({}),
+      handler: async () => snapshotContent(await (await page()).snapshot()),
+    },
+    {
+      name: 'browser_click',
+      description: 'Click a snapshot ref (e.g. @e3) and return a fresh snapshot.',
+      inputSchema: obj({ ref: { type: 'string' } }, ['ref']),
+      handler: async (a) => {
+        const p = await page();
+        await p.click(str(a.ref));
+        return freshSnapshot(p);
+      },
+    },
+    {
+      name: 'browser_fill',
+      description: 'Fill an input by ref with a value; returns a fresh snapshot.',
+      inputSchema: obj({ ref: { type: 'string' }, value: { type: 'string' } }, ['ref', 'value']),
+      handler: async (a) => {
+        const p = await page();
+        await p.fill(str(a.ref), str(a.value));
+        return freshSnapshot(p);
+      },
+    },
+    {
+      name: 'browser_type',
+      description: 'Type text into an input by ref (alias of fill).',
+      inputSchema: obj({ ref: { type: 'string' }, value: { type: 'string' } }, ['ref', 'value']),
+      handler: async (a) => {
+        const p = await page();
+        await p.fill(str(a.ref), str(a.value));
+        return freshSnapshot(p);
+      },
+    },
+    {
+      name: 'browser_press',
+      description: 'Dispatch a key press (e.g. Enter) to the focused element.',
+      inputSchema: obj({ key: { type: 'string' } }, ['key']),
+      handler: async (a) => {
+        const p = await page();
+        const key = JSON.stringify(str(a.key));
+        await p.eval(`(() => { const el = document.activeElement || document.body; for (const t of ['keydown','keyup']) el.dispatchEvent(new KeyboardEvent(t, { key: ${key}, bubbles: true, cancelable: true })); })()`);
+        return freshSnapshot(p);
+      },
+    },
+    {
+      name: 'browser_select',
+      description: 'Select an option by value in a <select> referenced by ref.',
+      inputSchema: obj({ ref: { type: 'string' }, value: { type: 'string' } }, ['ref', 'value']),
+      handler: async (a) => {
+        const p = await page();
+        const ref = JSON.stringify(str(a.ref).replace(/^@/, ''));
+        const value = JSON.stringify(str(a.value));
+        await p.eval(`(() => { const el = document.querySelector('[data-tron-ref=' + ${JSON.stringify(ref)} + ']'); if (el) { el.value = ${value}; el.dispatchEvent(new Event('change', { bubbles: true })); } })()`);
+        return freshSnapshot(p);
+      },
+    },
+    {
+      name: 'browser_scroll',
+      description: 'Scroll the page by a pixel amount (positive = down).',
+      inputSchema: obj({ amount: { type: 'number' } }),
+      handler: async (a) => {
+        const p = await page();
+        const amount = typeof a.amount === 'number' ? a.amount : 600;
+        await p.eval(`window.scrollBy(0, ${amount})`);
+        return freshSnapshot(p);
+      },
+    },
+    {
+      name: 'browser_wait',
+      description: 'Wait for a number of milliseconds.',
+      inputSchema: obj({ ms: { type: 'number' } }),
+      handler: async (a) => {
+        const ms = Math.min(typeof a.ms === 'number' ? a.ms : 500, 15000);
+        await new Promise((r) => setTimeout(r, ms));
+        return [{ type: 'text', text: `Waited ${ms}ms.` }];
+      },
+    },
+    {
+      name: 'browser_extract',
+      description: 'Extract structured JSON: text|links|forms|tables|main or a CSS selector.',
+      inputSchema: obj({ mode: { type: 'string' } }),
+      handler: async (a) => jsonContent(await (await page()).extract(str(a.mode, 'text'))),
+    },
+    {
+      name: 'browser_screenshot',
+      description: 'Capture a PNG screenshot of the current page.',
+      inputSchema: obj({}),
+      handler: async () => {
+        const png = await (await page()).screenshot();
+        return [{ type: 'image', data: Buffer.from(png).toString('base64'), mimeType: 'image/png' }];
+      },
+    },
+    {
+      name: 'browser_tabs',
+      description: 'List the managed session tabs.',
+      inputSchema: obj({}),
+      handler: async () => jsonContent(await session.tabs()),
+    },
+    {
+      name: 'browser_close',
+      description: 'Close the managed browser session.',
+      inputSchema: obj({}),
+      handler: async () => {
+        await session.close();
+        return [{ type: 'text', text: 'Session closed.' }];
+      },
+    },
+    {
+      name: 'browser_analyze',
+      description: 'Non-mutating: analyze the page / map a form to data. Dry-run.',
+      inputSchema: obj({ goal: { type: 'string' }, data: { type: 'object' }, mode: { type: 'string' } }),
+      handler: async (a) => {
+        const p = await page();
+        const goal = a.goal !== undefined ? str(a.goal) : undefined;
+        return jsonContent(await p.analyze(goal, { ...(a.data !== undefined ? { data: a.data } : {}) }));
+      },
+    },
+    {
+      name: 'browser_step',
+      description: 'Execute one validated AI-selected action toward a goal.',
+      inputSchema: obj({ goal: { type: 'string' }, data: { type: 'object' } }, ['goal']),
+      handler: async (a) => {
+        const p = await page();
+        return jsonContent(await p.step(str(a.goal), { ...(a.data !== undefined ? { data: a.data } : {}) }));
+      },
+    },
+    {
+      name: 'browser_run_task',
+      description: 'Run a bounded unknown-interface task toward a goal.',
+      inputSchema: obj({ goal: { type: 'string' }, data: { type: 'object' }, maxSteps: { type: 'number' } }, ['goal']),
+      handler: async (a) => {
+        const p = await page();
+        return jsonContent(
+          await p.runTask(str(a.goal), {
+            ...(a.data !== undefined ? { data: a.data } : {}),
+            ...(typeof a.maxSteps === 'number' ? { maxSteps: a.maxSteps } : {}),
+          }),
+        );
+      },
+    },
+  ];
+}