stealth-browser-mcp: Instructions file for Codex

Agent Instructions

Start Here

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

• Repository: https://github.com/vibheksoni/stealth-browser-mcp
• Language: Python 3.10+
• Framework: FastMCP + nodriver (Chrome DevTools Protocol)
• Platform: Windows, macOS, Linux

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