Metadata-Version: 2.4
Name: frontprompt
Version: 0.1.0
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: BSD-3-Clause
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: Programming Language :: Python :: 3.14
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-Dist: sounddevice>=0.5,<1
Requires-Dist: huggingface-hub>=0.24,<1
Requires-Dist: mlx-whisper>=0.4,<1 ; platform_machine == 'arm64' and sys_platform == 'darwin'
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

<p align="center">
  <img src="assets/frontprompt-logo.svg" alt="frontprompt" width="96" height="96">
</p>

# 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

### As a Claude Code plugin (recommended)

```bash
claude plugin marketplace add SurrealMindAI/frontprompt
claude plugin install frontprompt@frontprompt
```

The `frontprompt` MCP server is wired automatically: it launches via `uvx` from
PyPI and the Chromium browser self-installs on first use — zero manual setup.

After a CLI install, restart Claude Code or run `/reload-plugins` to activate the
server. Each plugin version pins an exact PyPI release, so updating is just:

```bash
claude plugin update frontprompt@frontprompt
```

### As a standalone CLI / MCP tool

frontprompt ships as a self-contained wheel — the Svelte overlay is embedded in
the package, so the installed tool needs no Bun or Node at runtime, and Chromium
auto-installs on first run.

```bash
uv tool install frontprompt
frontprompt bootstrap          # optional — eagerly pre-installs the Chromium driver
```

## 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 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](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

BSD-3-Clause — see [LICENSE](LICENSE).
