frontprompt 0.0.2

MCP server for browser automation — an in-page inspector overlay plus programmatic page control via Playwright.

frontprompt

Annotate any web page, and drive it from an AI agent.

frontprompt is a Python tool that opens a real (headful) Chromium browser and injects an in-page overlay — a shadow-DOM HUD — onto whatever page you point it at. You click to pick elements, drag to capture regions, and draw typed relations between them. The same process runs an MCP server, so an AI agent can navigate the browser, query the page, create picks, and read your annotations as structured state.

The headline property: your annotations survive cross-origin navigation. State is authoritative in the Python process, not in the page, so navigating from one site to another never loses your picks. See ARCHITECTURE.md for how that works.

Status

Alpha. The interactive inspector is feature-complete and the MCP server exposes a working tool set (pick, navigate, screenshot, page-read, state-read). Some capabilities are intentionally deferred — see ARCHITECTURE.md § Scope.

Install

frontprompt ships as a self-contained wheel: the Svelte overlay is built and embedded into the package, so the installed tool needs no Bun or Node at runtime. The one thing a wheel can't carry is the Chromium binary — frontprompt bootstrap installs it.

# install the tool
uv tool install frontprompt

# install the Chromium driver (run once)
frontprompt bootstrap

Usage

# open a page with the inspector overlay
frontprompt show https://example.com

# run as an MCP stdio server for an AI agent
frontprompt mcp

Point your MCP client at frontprompt mcp. Each invocation owns its own private browser session and spawns Chromium lazily on the first tool call, so startup is instant. The server is ephemeral — one process per client session, it dies when the client disconnects.

Dependencies & risk

frontprompt pins scrapling==0.4.8 exactly. scrapling is a BSD-3 page extraction library that is, at the time of writing, effectively single-maintainer (a bus-factor-1 project). To contain that risk it is used behind a thin internal isolation boundary, pinned to one verified version, and never auto-upgraded — so it can be swapped out without touching the rest of the codebase if it ever needs to be.

Documentation

• ARCHITECTURE.md — system design: cross-origin survival, the expose_function bridge, single-writer state, the MCP daemon, schema histories.
• DEVELOPMENT.md — dev environment, build pipeline, tests.
• CONTRIBUTING.md — how to contribute.

License

MIT — see LICENSE.