@agimon-ai/po-browse-tool 0.0.0-alpha.21 → 0.0.0-alpha.23

package/README.md

@@ -1,16 +1,17 @@
 # @agimon-ai/po-browse-tool
 
-Browser automation library that `@agimon-ai/po-browse` runs in-process inside the Po server. Agents reach it through Po's code-mode `exec` tool as the `browser` namespace; see `po-browse`'s `po-use-browse` skill.
-
-> **Deprecated, being removed:** the standalone `po-browse-tool` command, its HTTP daemon, the MCP server (`mcp-serve`), custom tools, saved snippets, the spec runner and the dashboard. The sections below that describe them are kept until the removal lands.
+Browser automation runtime and MCP server components for `@agimon-ai/po-browse`.
+Po uses the runtime in-process and exposes it through the `browser` namespace in
+code mode `exec`.
 
 ## Features
 
-- Browser tools for complete browser control, exposed in Po as `browser.*` methods
-- Extension mode (your Chrome through the Po extension) by default, Playwright when headless
-- Multi-browser support in Playwright mode (Chromium, Firefox, WebKit)
+- Browser tools for complete browser control
+- Extension mode for controlling Chrome through the Po extension
+- Playwright mode for headless Chromium, Firefox, and WebKit
 - Profile management for persistent browser sessions
-- Page registry with per-owner pages, so one Po session cannot reach another's
+- Page registry with per-owner pages
+- MCP server and modern stdio and streamable HTTP transports
 
 ## Library use
 
@@ -25,48 +26,55 @@ console.log(output.text); // JSON with browserId and pageId
 await shutdownBrowseRuntime(runtime);
 ```
 
-`callBrowseTool` validates the input against the tool's schema and returns `{ text, images }`, throwing on a tool error. `livePage(runtime, entry)` returns the live page behind a page registry entry: Playwright's `Page`, or an extension proxy. `createBoundBrowserRuntime` stays exported for the system tests.
-
-## Installation
+`callBrowseTool` validates input against the tool schema and returns
+`{ text, images }`, throwing on a tool error. `livePage(runtime, entry)` returns
+the live page behind a page registry entry: Playwright's `Page`, or an extension
+proxy. `createBoundBrowserRuntime` remains exported for system tests.
 
-```bash
-pnpm install
-```
+## MCP server and transports
 
-## Development
+Hosts that own the browser runtime create an MCP server from their tools and
+select a transport. `ownedTools` below represents the tools owned and managed by
+the host:
 
-```bash
-pnpm dev
-```
+```ts
+import { createServer, StdioTransportHandler } from '@agimon-ai/po-browse-tool';
 
-## Build
+const server = createServer({ tools: ownedTools });
+const transport = new StdioTransportHandler(server);
+await transport.start();
 
-```bash
-pnpm build
+// On host shutdown:
+await transport.stop();
 ```
 
-## Test
+`StreamableHttpTransportHandler` accepts a session factory and transport config.
+The request passed to that factory exposes request headers, so a host may apply
+its own routing and ownership policy before returning a host-owned server context.
+The host remains responsible for binding browser ownership and runtime lifecycle.
+The transport handles MCP protocol requests and invokes any returned cleanup
+callback. Its default endpoint path is `/mcp`, and the path can be changed in
+`StreamableHttpTransportConfig`.
+
+## Installation and checks
 
 ```bash
+pnpm install
+pnpm build
 pnpm test
 ```
 
-## Private Po port checks
-
-This private port retains the upstream SDK, CLI, and extension assets.
-The profile-bound SDK is verified with synthetic local fixtures and real Chromium;
-no live credentials or email sends are used.
-
-From the repository root:
+This public package retains the upstream SDK, MCP transports, snippets, specs, and
+extension assets. From the repository root:
 
 ```bash
 pnpm exec nx run-many -t lint,typecheck,build,test -p @agimon-ai/po-browse-tool
 ```
 
 These targets cover whole-port type-aware lint, source and test typechecking,
-SDK/declaration builds, production extension assets, and synthetic Chromium tests.
-Browser evaluation and native receiver capture retain narrowly documented lint
-exceptions because those operations are intentional features.
+SDK and declaration builds, production extension assets, and synthetic Chromium
+tests. Browser evaluation and native receiver capture retain narrowly documented
+lint exceptions because those operations are intentional features.
 
 Check the extension's browser-only declarations separately:
 
@@ -76,116 +84,9 @@ pnpm --filter @agimon-ai/po-browse-tool exec tsc --noEmit -p tsconfig.extension.
 
 The production Vite build is not a substitute for this extension typecheck.
 
-## Usage with Claude Code (deprecated, being removed)
-
-Add to your Claude Code configuration (`.mcp.json`):
-
-```json
-{
-  "mcpServers": {
-    "browse-tool": {
-      "command": "npx",
-      "args": ["browse-tool", "mcp-serve"]
-    }
-  }
-}
-```
-
-### CLI Options
-
-```bash
-browse-tool mcp-serve [options]
-
-Options:
-  -t, --type <type>      Transport type: stdio, streamable-http (default: "stdio")
-  -b, --browser <type>   Default browser: chromium, firefox, webkit (default: "chromium")
-  --headless             Run browsers in headless mode
-  --no-headless          Run browsers in headed mode (visible window)
-  --host <host>          Default host for HTTP services (default: "localhost")
-  --port <port>          Port for streamable HTTP transport (default: "3201")
-  -p, --profile <name>   Default profile name for browser sessions
-  --custom-tools <path>  Expose tools from a folder containing tools.yaml
-  --snippets-dir <path>  Directory used by browser_run_code to save and load reusable snippets
-```
-
-### Streamable HTTP Transport
-
-For clients that can connect over MCP streamable HTTP, start `mcp-serve` with:
-
-```bash
-browse-tool mcp-serve --type streamable-http --host 127.0.0.1 --port 3201
-```
-
-This exposes the MCP endpoint at `http://127.0.0.1:3201/mcp` and keeps the existing browse-tool HTTP service for browser execution on its own port.
-
-This endpoint serves modern MCP `2026-07-28` only. Send `x-browse-owner: <stable-owner-id>` on **every** stateful MCP request, and send `x-profile: <profile-name>` on every request when pinning a profile. The owner is application routing identity, not authentication. Tool discovery works without an owner; tool calls without one return an error. Browser state survives individual HTTP requests and client disconnects, scoped to the owner and profile, and is cleaned up after inactivity or shutdown. Modern HTTP does not use `Mcp-Session-Id` or a legacy initialize request.
-
-## Custom Tools (deprecated, being removed)
-
-Custom tools are loaded from a folder containing:
-
-- `tools.yaml`
-- one or more `.ts` scripts referenced by the manifest
-
-`tools.yaml` entries support:
-
-- `name`
-- `description`
-- `script`
-- `capabilities`
-- `inputSchema`
-- optional `suggestionActions`
-  - a short text string describing what should be done next after the tool succeeds
-  - this value is exposed in custom-tool discovery and injected into the tool execution result
-
-If you start the MCP server with `--custom-tools <path>`, those tools are added to the MCP tool list automatically.
-
-### Expose Custom Tools Through MCP
-
-```bash
-browse-tool mcp-serve --custom-tools scripts/automation/linkedin-prospecting
-```
-
-Claude Code example:
-
-```json
-{
-  "mcpServers": {
-    "browse-tool": {
-      "command": "npx",
-      "args": ["browse-tool", "mcp-serve", "--custom-tools", "scripts/automation/linkedin-prospecting"]
-    }
-  }
-}
-```
-
-### Flat CLI Commands
-
-List tools from a custom-tool directory:
+## Tool reference
 
-```bash
-browse-tool list-custom-tools scripts/automation/linkedin-prospecting
-```
-
-Execute a custom tool:
-
-```bash
-browse-tool exec-custom-tool \
-  scripts/automation/linkedin-prospecting \
-  list_posts_from_linkedin_feed \
-  '{"pageId":"page-2","maxPosts":3}'
-```
-
-### Notes
-
-- The flat commands talk to the browse-tool HTTP server.
-- Custom tools are not exposed to MCP unless `mcp-serve` is started with `--custom-tools`.
-- For slow UI-driven tools, prefer bounded inputs such as `maxPosts` so test runs stay manageable.
-- If a manifest defines `suggestionActions`, browse-tool injects that text into the custom tool execution result.
-
-## Tool Reference
-
-### Input Tools (8)
+### Input tools (8)
 
 | Tool                  | Description                                |
 | --------------------- | ------------------------------------------ |
@@ -198,7 +99,7 @@ browse-tool exec-custom-tool \
 | `browser_press_key`   | Press a keyboard key                       |
 | `browser_upload_file` | Upload a file to a file input              |
 
-### Navigation Tools (5)
+### Navigation tools (5)
 
 | Tool                 | Description                      |
 | -------------------- | -------------------------------- |
@@ -208,7 +109,7 @@ browse-tool exec-custom-tool \
 | `browser_reload`     | Reload the current page          |
 | `browser_wait_for`   | Wait for an element or condition |
 
-### Snapshot Tools (3)
+### Snapshot tools (3)
 
 | Tool                 | Description                     |
 | -------------------- | ------------------------------- |
@@ -216,7 +117,7 @@ browse-tool exec-custom-tool \
 | `browser_pdf`        | Generate PDF of the page        |
 | `browser_snapshot`   | Get accessibility tree snapshot |
 
-### Tab/Page Management Tools (4)
+### Tab and page management tools (4)
 
 | Tool                  | Description               |
 | --------------------- | ------------------------- |
@@ -225,11 +126,11 @@ browse-tool exec-custom-tool \
 | `browser_new_page`    | Open a new page           |
 | `browser_close_page`  | Close a page              |
 
-### Dialog/Network/Console Tools (7)
+### Dialog, network, and console tools (7)
 
 | Tool                            | Description                                        |
 | ------------------------------- | -------------------------------------------------- |
-| `browser_handle_dialog`         | Handle JavaScript dialogs (alert, confirm, prompt) |
+| `browser_handle_dialog`         | Handle JavaScript dialogs                          |
 | `browser_list_network_requests` | List captured network requests                     |
 | `browser_get_network_request`   | Get details of a specific network request          |
 | `browser_list_console_messages` | List console messages                              |
@@ -237,35 +138,37 @@ browse-tool exec-custom-tool \
 | `browser_resize_page`           | Resize the browser viewport                        |
 | `browser_emulate`               | Emulate device, geolocation, or network conditions |
 
-### Code Tools (2, deprecated, being removed)
+### Code tools (2)
 
-Po code mode does not expose these; an `exec` script using `browser.page` replaces them.
+Po code mode uses an `exec` script with `browser.page` for these operations:
 
-| Tool                    | Description                                                                                        |
-| ----------------------- | -------------------------------------------------------------------------------------------------- |
-| `browser_run_code`      | Execute inline code against `{ page, context, browser }`, optionally save it as a reusable snippet |
-| `browser_list_snippets` | List saved snippets by name, description, and snippetPath                                          |
+| Tool                    | Description                                      |
+| ----------------------- | ------------------------------------------------ |
+| `browser_run_code`      | Execute code against a page, context, or browser |
+| `browser_list_snippets` | List saved snippets                              |
 
-### Testing/Tracing Tools (3)
+### Testing and tracing tools (3)
 
-| Tool                  | Description                      |
-| --------------------- | -------------------------------- |
-| `browser_expect`      | Assert conditions on elements    |
-| `browser_start_trace` | Start Playwright tracing         |
-| `browser_stop_trace`  | Stop tracing and save trace file |
+| Tool                  | Description                   |
+| --------------------- | ----------------------------- |
+| `browser_expect`      | Assert conditions on elements |
+| `browser_start_trace` | Start Playwright tracing      |
+| `browser_stop_trace`  | Stop tracing and save a trace |
 
-### Profile Management Tools (4)
+### Profile management tools (4)
 
-| Tool                         | Description                           |
-| ---------------------------- | ------------------------------------- |
-| `browser_list_profiles`      | List all saved profiles               |
-| `browser_create_profile`     | Create a new browser profile          |
-| `browser_delete_profile`     | Delete a profile                      |
-| `browser_save_profile_state` | Save current browser state to profile |
+| Tool                         | Description                     |
+| ---------------------------- | ------------------------------- |
+| `browser_list_profiles`      | List all saved profiles         |
+| `browser_create_profile`     | Create a browser profile        |
+| `browser_delete_profile`     | Delete a profile                |
+| `browser_save_profile_state` | Save browser state to a profile |
 
-## Saved Snippets (deprecated, being removed)
+## Saved snippets for library hosts
 
-If you start `mcp-serve` or `http-serve` with `--snippets-dir <path>`, `browser_run_code` can persist inline snippets and later execute them again by `snippetPath`.
+Library hosts that expose the underlying snippet tools can save and run inline
+snippets. Po's `browser` namespace does not expose saved snippet tools.
+A saved snippet has a name, description, and `snippetPath`.
 
 Save an inline snippet:
 
@@ -304,11 +207,11 @@ Run a saved snippet:
 }
 ```
 
-## Profile Management
+## Profile management
 
-Profiles allow you to persist browser state (cookies, localStorage, etc.) across sessions.
+Profiles persist browser state such as cookies and local storage across sessions.
 
-### Create a Profile
+### Create a profile
 
 ```json
 {
@@ -321,7 +224,7 @@ Profiles allow you to persist browser state (cookies, localStorage, etc.) across
 }
 ```
 
-### Save Profile State
+### Save profile state
 
 ```json
 {
@@ -333,30 +236,20 @@ Profiles allow you to persist browser state (cookies, localStorage, etc.) across
 }
 ```
 
-## Proxy Configs
+## Proxy configs
 
-`browser_launch` accepts an explicit proxy object, or `proxy: true` to load `session.yaml` from the proxy config directory.
-
-```json
-{
-  "tool": "browser_launch",
-  "arguments": {
-    "profileName": "work",
-    "proxy": true
-  }
-}
-```
-
-By default, proxy configs live beside the profiles directory. With the default profiles directory, this is `~/.browse-tool/proxy-config`.
+`browser_launch` accepts an explicit proxy object, or `proxy: true` to load
+`session.yaml` from the proxy config directory. With the default profiles
+directory, proxy configs live in `~/.browse-tool/proxy-config`.
 
 Files are resolved in this order:
 
-1. Explicit `proxy` object in the `browser_launch` arguments
+1. An explicit `proxy` object in `browser_launch` arguments
 2. `{proxy-config}/{profileName}.yaml`
 3. `{proxy-config}/session.yaml` when `proxy: true` is used
 4. `{proxy-config}/default.yaml`
 
-Example YAML:
+Set a custom directory with `BROWSE_TOOL_PROXY_CONFIG_DIR`.
 
 ```yaml
 server: http://proxy.example.com:8080
@@ -365,69 +258,39 @@ password: ${PROXY_PASSWORD}
 bypass: localhost,127.0.0.1
 ```
 
-Set a custom directory with `--proxy-config-dir <path>` or `BROWSE_TOOL_PROXY_CONFIG_DIR`.
-
 ## Configuration
 
-### Environment Variables
-
-| Variable                                  | Default                               | Description                                                                |
-| ----------------------------------------- | ------------------------------------- | -------------------------------------------------------------------------- |
-| `PLAYWRIGHT_PROFILES_DIR`                 | `~/.browse-tool/profiles`             | Directory for storing browser profiles                                     |
-| `BROWSE_TOOL_PROXY_CONFIG_DIR`            | beside profiles dir as `proxy-config` | Directory for browser proxy YAML configs                                   |
-| `PLAYWRIGHT_REGISTRY_DIR`                 | `.agiflow/registry`                   | Directory for HTTP server registry                                         |
-| `PLAYWRIGHT_PIDS_DIR`                     | `.pids`                               | Directory for tracking server PIDs                                         |
-| `PLAYWRIGHT_BROWSER_IDLE_TIMEOUT_MINUTES` | `30`                                  | Minutes a browser may sit idle before it is closed                         |
-| `BROWSE_TOOL_SERVER_IDLE_TIMEOUT_MINUTES` | `60`                                  | Minutes the daemon may sit idle before it shuts itself down (`0` disables) |
-| `NODE_ENV`                                | `development`                         | Runtime environment (`development`, `production`)                          |
-
-### CLI Flags vs Environment Variables
-
-CLI flags take precedence over environment variables. For example, `--profiles-dir /custom/path` overrides `PLAYWRIGHT_PROFILES_DIR`.
+| Variable                                  | Default                           | Description                    |
+| ----------------------------------------- | --------------------------------- | ------------------------------ |
+| `PLAYWRIGHT_PROFILES_DIR`                 | `~/.browse-tool/profiles`         | Browser profile storage        |
+| `BROWSE_TOOL_PROXY_CONFIG_DIR`            | beside profiles as `proxy-config` | Browser proxy YAML configs     |
+| `PLAYWRIGHT_BROWSER_IDLE_TIMEOUT_MINUTES` | `30`                              | Minutes a browser may sit idle |
+| `NODE_ENV`                                | `development`                     | Runtime environment            |
 
-### Idle Cleanup
+Idle cleanup closes pages after 15 minutes, browsers after the browser idle
+timeout, and browser processes with no pages after the shorter page timeout.
+An in-progress recording keeps its browser and pages alive while chunks upload.
 
-A background sweep runs every 60 seconds and tears down resources no agent is working on:
+## Error handling
 
-- **Pages** idle for more than 15 minutes are closed.
-- **Browsers** idle for more than the browser idle timeout (default 30 minutes) are closed, including their whole process tree.
-- **Browsers with no pages left** use the shorter 15-minute timeout.
-- **Stealth-mode** Chrome processes are swept on the same browser timeout.
-- **The daemon itself** exits once it has served no request and owns no browsers for the server idle timeout (default 60 minutes), releasing its port and process registry rows on the way out. Set `BROWSE_TOOL_SERVER_IDLE_TIMEOUT_MINUTES=0` to keep it running forever. Health checks do not count as requests: discovery polls them on daemons it never goes on to use.
+Structured errors include a `code` and `recovery` field.
 
-Idle is measured from the last real agent activity (a tool call against the browser, an extension task result, or a recording chunk upload). An open extension WebSocket does **not** count as activity: the extension pings and reconnects on its own, so a live socket would otherwise keep a forgotten browser alive forever. An in-progress recording does keep its browser and pages alive, because each uploaded chunk counts as activity.
+| Failure mode               | Cause                                          | Recovery                                        |
+| -------------------------- | ---------------------------------------------- | ----------------------------------------------- |
+| Browser launch failure     | Missing browser binary or incompatible version | Install the required Playwright browser         |
+| Navigation timeout         | Page took too long to load                     | Increase the wait timeout or check connectivity |
+| Element not found          | Selector did not match the DOM                 | Use `browser_snapshot` to inspect the page      |
+| Spec bundler build error   | Syntax or resolution errors in a spec file     | Check the spec and its imports                  |
+| Spec bundler runtime error | The Bun runtime is unavailable                 | Install Bun or use a supported runtime          |
 
-Set the timeout with `--idle-timeout <minutes>`, `commands.httpServe.idleTimeout` / `commands.mcpServe.idleTimeout` in `.browse-tool/config.json`, or `PLAYWRIGHT_BROWSER_IDLE_TIMEOUT_MINUTES`.
+## Spec bundler
 
-> **Note (deprecated daemon):** the HTTP daemon is long-lived and shared across worktrees, and it reads the idle timeout once at startup. A later client that attaches to an already-running daemon cannot change that daemon's timeout; restart the daemon (`browse-tool stop`) to apply a new value.
+`SpecBundlerService` bundles Playwright spec files before execution, replacing
+`@playwright/test` imports with a lightweight stub module so specs can run in
+the host runtime.
 
-> **Note:** `browse-tool stop` only stops daemons registered under the current worktree, so it will not take browsers away from an agent working in another one. Use `browse-tool stop --all` when you do want to clear every worktree's daemon.
-
-## Error Handling
-
-### Common Failure Modes
-
-| Failure                  | Cause                                              | Recovery                                                              |
-| ------------------------ | -------------------------------------------------- | --------------------------------------------------------------------- |
-| Browser launch failure   | Missing browser binary or incompatible version     | Run `npx playwright install chromium` to install browsers             |
-| Navigation timeout       | Page took too long to load                         | Increase timeout via `browser_wait_for` or check network connectivity |
-| Element not found        | Selector did not match any element                 | Use `browser_snapshot` to inspect the current DOM tree                |
-| Profile not found        | Referenced profile does not exist                  | Use `browser_list_profiles` to list available profiles                |
-| Session expired          | Browser context was closed or crashed              | Launch a new browser session with `browser_navigate`                  |
-| Spec bundler build error | Syntax errors or unresolvable imports in spec file | Check the spec file for errors; see `SpecBundlerBuildError.recovery`  |
-| Spec bundler CLI error   | `bun` not installed or not in PATH                 | Install bun: `curl -fsSL https://bun.sh/install \| bash`              |
-
-### Error Codes
-
-All structured errors include a `code` field for programmatic handling and a `recovery` field with suggested resolution steps.
-
-## Spec Bundler (deprecated, being removed)
-
-The `SpecBundlerService` bundles Playwright spec files before execution, replacing `@playwright/test` imports with a lightweight stub module so specs can run inside the MCP server.
-
-### `testInfo.attach` compatibility
-
-`run_spec` provides a stable subset of Playwright `TestInfo` to test callbacks and per-test hooks:
+`run_spec` provides a stable subset of Playwright `TestInfo` to test callbacks
+and per-test hooks:
 
 ```typescript
 test('captures evidence', async ({ page }, testInfo) => {
@@ -438,19 +301,17 @@ test('captures evidence', async ({ page }, testInfo) => {
 });
 ```
 
-Attachments may use either `body` or `path`. The runner copies the evidence to its temporary attachment directory and returns `{ name, contentType, path }` metadata on the matching test result. Accessing an unsupported `TestInfo` property fails with `RUN_SPEC_UNSUPPORTED_TEST_INFO_CAPABILITY` so compatibility failures remain distinct from browser and product failures.
+Attachments may use either `body` or `path`. The runner copies evidence to its
+temporary attachment directory and returns `{ name, contentType, path }` metadata
+on the matching test result. Unsupported `TestInfo` properties fail with
+`RUN_SPEC_UNSUPPORTED_TEST_INFO_CAPABILITY`.
 
-### Runtime Requirements
+### Runtime requirements
 
-- **Bun runtime** (preferred): When the MCP server runs under Bun, `Bun.build()` is used directly.
-- **Node.js runtime** (fallback): When running under Node.js, the service spawns `bun` as a CLI subprocess. Ensure `bun` is installed and accessible in `PATH`:
-  ```bash
-  curl -fsSL https://bun.sh/install | bash
-  # or
-  npm i -g bun
-  ```
+- Bun is preferred and uses `Bun.build()` directly.
+- Node.js can use an installed `bun` executable as a subprocess.
 
-### Programmatic Usage
+### Programmatic usage
 
 ```typescript
 import { SpecBundlerService } from 'browse-tool';
@@ -464,31 +325,23 @@ try {
 }
 ```
 
-### Error Handling
-
-| Error Class                | Code                        | When                                        |
-| -------------------------- | --------------------------- | ------------------------------------------- |
-| `SpecBundlerBuildError`    | `SPEC_BUNDLER_BUILD_FAILED` | Bundler reports syntax or resolution errors |
-| `SpecBundlerNoOutputError` | `SPEC_BUNDLER_NO_OUTPUT`    | Bundling produces no output file            |
-| `SpecBundlerCliError`      | `SPEC_BUNDLER_CLI_FAILED`   | `bun` CLI subprocess fails to execute       |
+| Error class                | Code                        | When                                         |
+| -------------------------- | --------------------------- | -------------------------------------------- |
+| `SpecBundlerBuildError`    | `SPEC_BUNDLER_BUILD_FAILED` | Bundling reports syntax or resolution errors |
+| `SpecBundlerNoOutputError` | `SPEC_BUNDLER_NO_OUTPUT`    | Bundling produces no output file             |
+| `SpecBundlerCliError`      | `SPEC_BUNDLER_CLI_FAILED`   | Bun cannot be started                        |
 
 ## Architecture
 
 ```
 browse-tool/
 ├── src/
-│   ├── commands/        # CLI commands (mcp-serve)
-│   ├── container/       # InversifyJS IoC container
-│   ├── server/          # MCP server factory
-│   ├── services/        # Core services
-│   │   ├── AutomationRunner.ts   # Script execution
-│   │   ├── BrowserService.ts     # Browser lifecycle
-│   │   ├── PageRegistry.ts       # Page tracking
-│   │   ├── PauseController.ts    # Pause/resume flow
-│   │   ├── ProfileService.ts     # Profile management
-│   │   └── SessionService.ts     # Session tracking
-│   ├── tools/           # MCP tool implementations
-│   ├── transports/      # Transport handlers (stdio, streamable HTTP)
+│   ├── container/       # In-process runtime composition
+│   ├── extension/       # Browser extension assets
+│   ├── server/          # MCP server factory and extension routes
+│   ├── services/        # Browser, page, profile, and spec services
+│   ├── tools/           # Browser tool implementations
+│   ├── transports/      # Stdio and streamable HTTP handlers
 │   └── types/           # TypeScript type definitions
 ├── tests/
 │   ├── services/        # Service unit tests