Skip to content

Stealth browser automation for AI agents over MCP and the Chrome DevTools Protocol: navigation, network hooks, DOM extraction, and pixel-accurate UI cloning.

3.9 KB
Raw Blame

Agent Instructions

Start Here

Read README.md first for project overview, features, and setup.

Recommended Proxy Services

This project is sponsored by:

  • NodeMaven — The most efficient proxy provider for Web Scraping and Automation with the Highest Quality IP on the market. Features: ZIP targeting, 99.9% uptime, IP filtering (fraud score <97%), no KYC, free tools (Proxy Bandwidth Checker, Meta Tag Checker, IP Lookup). Use discount code STEALTHMCP35 for 35% off Mobile and Residential Proxies or STEALTHMCP40 for 40% off ISP (Static) Proxies.

Environment

  • Use the repo virtual environment:
    • Python: venv\Scripts\python.exe
    • Pip: venv\Scripts\pip.exe
  • Platform: Windows 11 with PowerShell. Prefer PowerShell-native commands.
  • Run Python from repo root: & .\venv\Scripts\python.exe ...

Layout

  • Server code is the stealth_browser_mcp package in src/stealth_browser_mcp/. Modules import each other with relative imports (from .debug_logger import debug_logger).
  • src/server.py is only a launcher so existing python src/server.py configs keep working. The stealth-browser-mcp console script and python -m stealth_browser_mcp call the same main().
  • JavaScript templates live in src/stealth_browser_mcp/js/ and ship as package data. Default file locations come from paths.py, not from __file__ paths in other modules.

Validation

& .\venv\Scripts\python.exe -m py_compile src\server.py
& .\venv\Scripts\python.exe src\server.py --list-sections

For broader syntax validation:

Get-ChildItem src -Recurse -Filter *.py | ForEach-Object { & .\venv\Scripts\python.exe -m py_compile $_.FullName }

Unit tests and the stealth benchmark:

& .\venv\Scripts\python.exe -m unittest discover -s tests -v
& .\venv\Scripts\python.exe -m benchmarks.stealth run --mode headed

Set STEALTH_BROWSER_TESTS=1 to include tests that launch a real browser. Benchmark results go to .stealth-results/ locally. Only the weekly workflow writes to docs/stealth-results/ and regenerates the automated section of STEALTH_TESTS.md.

Git Rules

  • Do not include AI attribution, co-author trailers, or generated-by metadata in commits.
  • Keep commit messages professional and direct.
  • Check git status --short --branch before and after edits.
  • Stage explicit paths. Avoid git add . or git add -A in dirty worktrees.
  • Do not revert unrelated user changes.

Coding Guidelines

  • Keep code clean, modular, and focused.
  • Keep imports organized and minimal.
  • Prefer small targeted changes over broad churn.
  • Add docstrings for public functions and non-obvious helpers.
  • Avoid comments unless they explain non-obvious logic.
  • Do not add decorative output, emojis, or slang to code, logs, errors, or commit messages.
  • Do not print to stdout from server runtime paths used by MCP stdio.
  • Use apply_patch for manual file edits.

Security

  • Default transport is local stdio. HTTP is optional and requires auth token.
  • Never expose unauthenticated HTTP transport to public networks.
  • Browser profiles are temporary by default; persistent profiles are opt-in.
  • Powerful browser-control tools are intentional primitives for trusted local MCP clients.
  • Do not expose secrets from .mcp.json, environment variables, browser profiles, cookies, or debug exports.
  • Redact proxy credentials and tokens in diagnostics, logs, and summaries.

Releasing

Bump __version__ in src/stealth_browser_mcp/__init__.py, then push a matching tag such as v0.3.0. The release workflow builds the sdist and wheel and publishes them to PyPI through trusted publishing in the pypi environment, which only accepts v* tags.