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.
• RapidProxy — 90M+ residential IPs across 200+ countries with rotation, geo-targeting, and high concurrency. Use promo code RAPID10 for 10% off.

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

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 -Filter *.py | ForEach-Object { & .\venv\Scripts\python.exe -m py_compile $_.FullName }

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.