Metadata-Version: 2.4
Name: frontprompt
Version: 0.0.1
Summary: MCP server for browser automation — an in-page inspector overlay plus programmatic page control via Playwright.
Keywords: mcp,browser-automation,websocket,json-rpc,pydantic,playwright
Author: SurrealMind
Author-email: SurrealMind <admin@surrealmind.ai>
License-Expression: MIT
License-File: LICENSE
Classifier: Development Status :: 2 - Pre-Alpha
Classifier: Framework :: Pydantic :: 2
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.13
Classifier: Typing :: Typed
Requires-Dist: anyio>=4.13,<5
Requires-Dist: click>=8.1,<9
Requires-Dist: filelock>=3.16,<4
Requires-Dist: mcp>=1.0,<2
Requires-Dist: pydantic>=2.13,<3
Requires-Dist: scrapling==0.4.8
Requires-Dist: browserforge>=1.2,<2
Requires-Dist: curl-cffi>=0.7,<1
Requires-Dist: msgspec>=0.18,<1
Requires-Dist: playwright>=1.50,<2
Requires-Dist: starlette>=1.0,<2
Requires-Dist: uvicorn>=0.34,<1
Requires-Dist: structlog>=25.1,<26
Requires-Dist: websockets>=14,<17
Requires-Dist: pydantic-zod-codegen>=1.0,<2
Requires-Python: >=3.13
Project-URL: Homepage, https://github.com/SurrealMindAI/frontprompt
Project-URL: Repository, https://github.com/SurrealMindAI/frontprompt
Project-URL: Issues, https://github.com/SurrealMindAI/frontprompt/issues
Description-Content-Type: text/markdown

# 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](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](ARCHITECTURE.md#scope-alpha).

## 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.

```bash
# install the tool
uv tool install frontprompt

# install the Chromium driver (run once)
frontprompt bootstrap
```

## Usage

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

# run as an MCP stdio server for an AI agent
frontprompt daemon
```

Point your MCP client at `frontprompt daemon`. Each daemon owns its own private
browser session and spawns Chromium lazily on the first tool call, so startup
is instant.

## 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](ARCHITECTURE.md) — system design: cross-origin survival,
  the `expose_function` bridge, single-writer state, the MCP daemon, schema
  histories.
- [DEVELOPMENT.md](DEVELOPMENT.md) — dev environment, build pipeline, tests.
- [CONTRIBUTING.md](CONTRIBUTING.md) — how to contribute.

## License

MIT — see [LICENSE](LICENSE).
