@agimon-ai/po-browse-tool weekly downloads statistics

@agimon-ai/po-browse-tool

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
• 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
• MCP server and modern stdio and streamable HTTP transports

Library use

import { callBrowseTool, createBrowseRuntime, runWithOwner, shutdownBrowseRuntime } from '@agimon-ai/po-browse-tool';

const runtime = createBrowseRuntime({ workspaceRoot });
const output = await runWithOwner('po-session-1', () =>
  callBrowseTool(runtime.tools.browser_launch, { headless: true, url: 'https://example.com' }),
);
console.log(output.text); // JSON with browserId and pageId
await shutdownBrowseRuntime(runtime);

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.

MCP server and transports

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:

import { createServer, StdioTransportHandler } from '@agimon-ai/po-browse-tool';

const server = createServer({ tools: ownedTools });
const transport = new StdioTransportHandler(server);
await transport.start();

// On host shutdown:
await transport.stop();

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

pnpm install
pnpm build
pnpm test

This public package retains the upstream SDK, MCP transports, snippets, specs, and extension assets. From the repository root:

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 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:

pnpm --filter @agimon-ai/po-browse-tool exec tsc --noEmit -p tsconfig.extension.json

The production Vite build is not a substitute for this extension typecheck.

Tool reference

Input tools (8)

Tool	Description
browser_click	Click on an element
browser_fill	Fill a form field with text (clears first)
browser_type	Type text into an element (appends)
browser_hover	Hover over an element
browser_select	Select an option from a dropdown
browser_drag	Drag from one element to another
browser_press_key	Press a keyboard key
browser_upload_file	Upload a file to a file input

Navigation tools (5)

Tool	Description
browser_navigate	Navigate to a URL
browser_go_back	Go back in browser history
browser_go_forward	Go forward in browser history
browser_reload	Reload the current page
browser_wait_for	Wait for an element or condition

Snapshot tools (3)

Tool	Description
browser_screenshot	Take a screenshot
browser_pdf	Generate PDF of the page
browser_snapshot	Get accessibility tree snapshot

Tab and page management tools (4)

Tool	Description
browser_list_pages	List all open pages
browser_select_page	Switch to a specific page
browser_new_page	Open a new page
browser_close_page	Close a page

Dialog, network, and console tools (8)…