This is page 1 of 4. Use http://codebase.md/vibheksoni/stealth-browser-mcp?lines=true&page={x} to view the full context.
# Directory Structure
```
├── .dockerignore
├── .github
│ ├── FUNDING.yml
│ ├── ISSUE_TEMPLATE
│ │ ├── bug_report.md
│ │ ├── config.yml
│ │ ├── feature_request.md
│ │ └── showcase.yml
│ ├── labeler.yml
│ ├── pull_request_template.md
│ └── workflows
│ └── ci.yml
├── .gitignore
├── CHANGELOG.md
├── Checklist.md
├── CODE_OF_CONDUCT.md
├── CODEOWNERS
├── COMPARISON.md
├── CONTRIBUTING.md
├── demo
│ ├── augment-hero-clone.md
│ ├── augment-hero-recreation.html
│ └── README.md
├── Dockerfile
├── examples
│ └── claude_prompts.md
├── HALL_OF_FAME.md
├── LICENSE
├── media
│ ├── AugmentHeroClone.PNG
│ ├── Showcase Stealth Browser Mcp.mp4
│ ├── showcase-demo-full.gif
│ ├── showcase-demo.gif
│ └── UndetectedStealthBrowser.png
├── pyproject.toml
├── README.md
├── requirements.txt
├── ROADMAP.md
├── run_server.bat
├── run_server.sh
├── SECURITY.md
├── smithery.yaml
└── src
├── __init__.py
├── browser_manager.py
├── cdp_element_cloner.py
├── cdp_function_executor.py
├── comprehensive_element_cloner.py
├── debug_logger.py
├── dom_handler.py
├── dynamic_hook_ai_interface.py
├── dynamic_hook_system.py
├── element_cloner.py
├── file_based_element_cloner.py
├── hook_learning_system.py
├── js
│ ├── comprehensive_element_extractor.js
│ ├── extract_animations.js
│ ├── extract_assets.js
│ ├── extract_events.js
│ ├── extract_related_files.js
│ ├── extract_structure.js
│ └── extract_styles.js
├── models.py
├── network_interceptor.py
├── persistent_storage.py
├── platform_utils.py
├── process_cleanup.py
├── progressive_element_cloner.py
├── response_handler.py
├── response_stage_hooks.py
└── server.py
```
# Files
--------------------------------------------------------------------------------
/.dockerignore:
--------------------------------------------------------------------------------
```
1 | # Git
2 | .git
3 | .gitignore
4 |
5 | # Python
6 | __pycache__/
7 | *.pyc
8 | *.pyo
9 | *.pyd
10 | .Python
11 | *.so
12 | .pytest_cache/
13 |
14 | # Virtual environments
15 | venv/
16 | env/
17 | ENV/
18 |
19 | # IDE
20 | .vscode/
21 | .idea/
22 | *.swp
23 | *.swo
24 |
25 | # OS
26 | .DS_Store
27 | Thumbs.db
28 |
29 | # Documentation
30 | README.md
31 | CHANGELOG.md
32 | docs/
33 | *.md
34 |
35 | # Examples and tests
36 | examples/
37 | tests/
38 | test_*.py
39 |
40 | # Development files
41 | .env.local
42 | .env.development
43 | debug_logs/
44 | screenshots/
45 |
46 | # Old stuff and backups
47 | oldstuff/
48 | old_network_hook_system/
49 | *_backup*
50 | *.bak
51 |
52 | # Clone files (temporary data)
53 | element_clones/
54 |
55 | # Media files (not needed in container)
56 | media/
57 |
58 | # Development scripts
59 | run_server.sh
60 | run_server.bat
```
--------------------------------------------------------------------------------
/.gitignore:
--------------------------------------------------------------------------------
```
1 | # File created using '.gitignore Generator' for Visual Studio Code: https://bit.ly/vscode-gig
2 | # Created by https://www.toptal.com/developers/gitignore/api/windows,visualstudiocode,python,venv
3 | # Edit at https://www.toptal.com/developers/gitignore?templates=windows,visualstudiocode,python,venv
4 |
5 | ### Python ###
6 | # Byte-compiled / optimized / DLL files
7 | __pycache__/
8 | *.py[cod]
9 | *$py.class
10 |
11 | # C extensions
12 | *.so
13 |
14 | # Distribution / packaging
15 | .Python
16 | build/
17 | develop-eggs/
18 | dist/
19 | downloads/
20 | eggs/
21 | .eggs/
22 | lib/
23 | lib64/
24 | parts/
25 | sdist/
26 | var/
27 | wheels/
28 | share/python-wheels/
29 | *.egg-info/
30 | .installed.cfg
31 | *.egg
32 | MANIFEST
33 |
34 | # PyInstaller
35 | # Usually these files are written by a python script from a template
36 | # before PyInstaller builds the exe, so as to inject date/other infos into it.
37 | *.manifest
38 | *.spec
39 |
40 | # Installer logs
41 | pip-log.txt
42 | pip-delete-this-directory.txt
43 |
44 | # Unit test / coverage reports
45 | htmlcov/
46 | .tox/
47 | .nox/
48 | .coverage
49 | .coverage.*
50 | .cache
51 | nosetests.xml
52 | coverage.xml
53 | *.cover
54 | *.py,cover
55 | .hypothesis/
56 | .pytest_cache/
57 | cover/
58 |
59 | # Translations
60 | *.mo
61 | *.pot
62 |
63 | # Django stuff:
64 | *.log
65 | local_settings.py
66 | db.sqlite3
67 | db.sqlite3-journal
68 |
69 | # Flask stuff:
70 | instance/
71 | .webassets-cache
72 |
73 | # Scrapy stuff:
74 | .scrapy
75 |
76 | # Sphinx documentation
77 | docs/_build/
78 |
79 | # PyBuilder
80 | .pybuilder/
81 | target/
82 |
83 | # Jupyter Notebook
84 | .ipynb_checkpoints
85 |
86 | # IPython
87 | profile_default/
88 | ipython_config.py
89 |
90 | # pyenv
91 | # For a library or package, you might want to ignore these files since the code is
92 | # intended to run in multiple environments; otherwise, check them in:
93 | # .python-version
94 |
95 | # pipenv
96 | # According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
97 | # However, in case of collaboration, if having platform-specific dependencies or dependencies
98 | # having no cross-platform support, pipenv may install dependencies that don't work, or not
99 | # install all needed dependencies.
100 | #Pipfile.lock
101 |
102 | # poetry
103 | # Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
104 | # This is especially recommended for binary packages to ensure reproducibility, and is more
105 | # commonly ignored for libraries.
106 | # https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control
107 | #poetry.lock
108 |
109 | # pdm
110 | # Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
111 | #pdm.lock
112 | # pdm stores project-wide configurations in .pdm.toml, but it is recommended to not include it
113 | # in version control.
114 | # https://pdm.fming.dev/#use-with-ide
115 | .pdm.toml
116 |
117 | # PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
118 | __pypackages__/
119 |
120 | # Celery stuff
121 | celerybeat-schedule
122 | celerybeat.pid
123 |
124 | # SageMath parsed files
125 | *.sage.py
126 |
127 | # Environments
128 | .env
129 | .venv
130 | env/
131 | venv/
132 | ENV/
133 | env.bak/
134 | venv.bak/
135 |
136 | # Spyder project settings
137 | .spyderproject
138 | .spyproject
139 |
140 | # Rope project settings
141 | .ropeproject
142 |
143 | # mkdocs documentation
144 | /site
145 |
146 | # mypy
147 | .mypy_cache/
148 | .dmypy.json
149 | dmypy.json
150 |
151 | # Pyre type checker
152 | .pyre/
153 |
154 | # pytype static type analyzer
155 | .pytype/
156 |
157 | # Cython debug symbols
158 | cython_debug/
159 |
160 | # PyCharm
161 | # JetBrains specific template is maintained in a separate JetBrains.gitignore that can
162 | # be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
163 | # and can be added to the global gitignore or merged into this file. For a more nuclear
164 | # option (not recommended) you can uncomment the following to ignore the entire idea folder.
165 | #.idea/
166 |
167 | ### Python Patch ###
168 | # Poetry local configuration file - https://python-poetry.org/docs/configuration/#local-configuration
169 | poetry.toml
170 |
171 | # ruff
172 | .ruff_cache/
173 |
174 | # LSP config files
175 | pyrightconfig.json
176 |
177 | ### venv ###
178 | # Virtualenv
179 | # http://iamzed.com/2009/05/07/a-primer-on-virtualenv/
180 | [Bb]in
181 | [Ii]nclude
182 | [Ll]ib
183 | [Ll]ib64
184 | [Ll]ocal
185 | [Ss]cripts
186 | pyvenv.cfg
187 | pip-selfcheck.json
188 |
189 | ### VisualStudioCode ###
190 | .vscode/*
191 | !.vscode/settings.json
192 | !.vscode/tasks.json
193 | !.vscode/launch.json
194 | !.vscode/extensions.json
195 | !.vscode/*.code-snippets
196 |
197 | # Local History for Visual Studio Code
198 | .history/
199 |
200 | # Built Visual Studio Code Extensions
201 | *.vsix
202 |
203 | ### VisualStudioCode Patch ###
204 | # Ignore all local history of files
205 | .history
206 | .ionide
207 |
208 | ### Windows ###
209 | # Windows thumbnail cache files
210 | Thumbs.db
211 | Thumbs.db:encryptable
212 | ehthumbs.db
213 | ehthumbs_vista.db
214 |
215 | # Dump file
216 | *.stackdump
217 |
218 | # Folder config file
219 | [Dd]esktop.ini
220 |
221 | # Recycle Bin used on file shares
222 | $RECYCLE.BIN/
223 |
224 | # Windows Installer files
225 | *.cab
226 | *.msi
227 | *.msix
228 | *.msm
229 | *.msp
230 |
231 | # Windows shortcuts
232 | *.lnk
233 |
234 | # End of https://www.toptal.com/developers/gitignore/api/windows,visualstudiocode,python,venv
235 |
236 | # Custom rules (everything added below won't be overriden by 'Generate .gitignore File' if you use 'Update' option)
237 |
238 | oldstuff/
239 | old_network_hook_system/
240 | element_clones/
241 | testing/
242 | .claude
243 | requirements_frozen.txt
```
--------------------------------------------------------------------------------
/demo/README.md:
--------------------------------------------------------------------------------
```markdown
1 | # 🎥 Live Demos
2 |
3 | ## 🔥 **What Makes This Go Viral**
4 |
5 | ### 🎨 **FEATURED: Augment Code Hero Clone**
6 | [](augment-hero-recreation.html)
7 |
8 | **🎯 One Command. Perfect Recreation. Under 2 Minutes.**
9 |
10 | ```bash
11 | User: "hey spawn a browser and clone the hero of the site https://www.augmentcode.com/"
12 | Claude: *Spawns browser → Extracts 2,838 CSS properties → Generates production HTML*
13 | ```
14 |
15 | - ✅ **Pixel-perfect recreation** with enhanced animations
16 | - ✅ **Production-ready code** - 574 lines of professional HTML/CSS
17 | - ✅ **Responsive design** improvements beyond original
18 | - ✅ **Complete automation** - no manual coding required
19 |
20 | **[👉 View Live Demo](augment-hero-recreation.html) | [📖 Full Demo Details](augment-hero-clone.md)**
21 |
22 | ---
23 |
24 | ### Bypass Cloudflare in Seconds
25 | 
26 | *Claude accessing a Cloudflare-protected site that blocks all other tools*
27 |
28 | ### Clone Any UI Element Perfectly
29 | 
30 | *Extract Stripe's pricing table with pixel-perfect accuracy*
31 |
32 | ### Automate Protected Banking Portals
33 | 
34 | *Navigate Bank of America without getting blocked*
35 |
36 | ### Real-Time Network Interception
37 | 
38 | *Intercept and analyze API calls from any SPA*
39 |
40 | ### Execute Python in Browser
41 | 
42 | *Run Python code directly in Chrome via AI chat*
43 |
44 | ## 📊 **Comparison Videos**
45 |
46 | - [ ] "Stealth vs Playwright: Cloudflare Challenge"
47 | - [ ] "Stealth vs Selenium: Banking Portal Test"
48 | - [ ] "88 Tools in 3 Minutes: Full Feature Demo"
49 | - [ ] "AI Agent Clones Airbnb Homepage in Real-Time"
50 |
51 | ## 🎯 **Use Case Demos**
52 |
53 | - [ ] LinkedIn lead scraping (undetected)
54 | - [ ] Ticketmaster seat monitoring
55 | - [ ] E-commerce price tracking
56 | - [ ] Government portal automation
57 | - [ ] Social media content extraction
58 | - [ ] Real estate data mining
```
--------------------------------------------------------------------------------
/README.md:
--------------------------------------------------------------------------------
```markdown
1 | <div align="center">
2 |
3 | <img src="media/UndetectedStealthBrowser.png" alt="Stealth Browser MCP" width="200"/>
4 |
5 | # Stealth Browser MCP
6 |
7 | **🚀 The ONLY browser automation that bypasses Cloudflare, antibots, and social media blocks**
8 |
9 | </div>
10 |
11 | Supercharge any MCP-compatible AI agent with undetectable, real-browser automation. No CAPTCHAs. No blocks. Just results.
12 |
13 | > **⚡ 30-second setup • 🛡️ Undetectable by design • 🏆 98.7% success rate on protected sites • 🕵️ Full network debugging via AI chat**
14 |
15 | [](https://modelcontextprotocol.io)
16 | [](https://github.com/vibheksoni/stealth-browser-mcp/stargazers)
17 | [](https://github.com/vibheksoni/stealth-browser-mcp/network/members)
18 | [](https://github.com/vibheksoni/stealth-browser-mcp/issues)
19 | [](CONTRIBUTING.md)
20 | [](https://discord.gg/7ETmqgTY6H)
21 | [](#-toolbox)
22 | [](#-stealth-vs-playwright-mcp)
23 | [](#-why-developers-star-this)
24 | [](LICENSE)
25 |
26 | > Give your AI agent real browser superpowers: access Cloudflare sites, extract any UI, and intercept network traffic — from inside your chat.
27 |
28 | ## 🎥 **See It In Action**
29 |
30 | <div align="center">
31 | <img src="media/showcase-demo-full.gif" alt="Stealth Browser MCP Demo" width="800" style="border-radius: 8px; box-shadow: 0 4px 12px rgba(0,0,0,0.15);">
32 | <br><br>
33 | <a href="media/Showcase%20Stealth%20Browser%20Mcp.mp4" download>
34 | <img src="https://img.shields.io/badge/📹-Watch%20HD%20Video-red?style=for-the-badge&logo=video&logoColor=white" alt="Watch HD Video">
35 | </a>
36 | </div>
37 |
38 | *🎯 **Watch**: Stealth Browser MCP bypassing Cloudflare, cloning UI elements, and intercepting network traffic — all through simple AI chat commands*
39 |
40 | ---
41 |
42 | ## 🔗 Quick Links
43 |
44 | - ▶️ [Quickstart](#quickstart-60-seconds)
45 | - 🏆 [Hall of Fame](HALL_OF_FAME.md) - Impossible automations made possible
46 | - 🥊 [Stealth vs Others](COMPARISON.md) - Why we dominate the competition
47 | - 🔥 [Viral Examples](examples/claude_prompts.md) - Copy & paste prompts that blow minds
48 | - 🧰 [90 Tools](#toolbox) - Complete arsenal of browser automation
49 | - 🎥 [Live Demos](demo/) - See it bypass what others can't
50 | - 🤝 [Contributing](#contributing) & 💬 [Discord](https://discord.gg/7ETmqgTY6H)
51 |
52 | ---
53 |
54 | ## Quickstart (60 seconds)
55 |
56 | ### ✅ **Recommended Setup (Creator's Tested Method)**
57 | ```bash
58 | # 1. Clone the repository
59 | git clone https://github.com/vibheksoni/stealth-browser-mcp.git
60 | cd stealth-browser-mcp
61 |
62 | # 2. Create virtual environment
63 | python -m venv venv
64 |
65 | # 3. Activate virtual environment
66 | # Windows:
67 | venv\Scripts\activate
68 | # Mac/Linux:
69 | source venv/bin/activate
70 |
71 | # 4. Install dependencies
72 | pip install -r requirements.txt
73 |
74 | # 5. Add to Claude Code using CLI
75 | ```
76 |
77 | **Windows (Full Installation):**
78 | ```bash
79 | claude mcp add-json stealth-browser-mcp "{\"type\":\"stdio\",\"command\":\"C:\\path\\to\\stealth-browser-mcp\\venv\\Scripts\\python.exe\",\"args\":[\"C:\\path\\to\\stealth-browser-mcp\\src\\server.py\"]}"
80 | ```
81 |
82 | **Windows (Minimal - Core Tools Only):**
83 | ```bash
84 | claude mcp add-json stealth-browser-mcp "{\"type\":\"stdio\",\"command\":\"C:\\path\\to\\stealth-browser-mcp\\venv\\Scripts\\python.exe\",\"args\":[\"C:\\path\\to\\stealth-browser-mcp\\src\\server.py\",\"--minimal\"]}"
85 | ```
86 |
87 | **Mac/Linux (Full Installation):**
88 | ```bash
89 | claude mcp add-json stealth-browser-mcp '{
90 | "type": "stdio",
91 | "command": "/path/to/stealth-browser-mcp/venv/bin/python",
92 | "args": [
93 | "/path/to/stealth-browser-mcp/src/server.py"
94 | ]
95 | }'
96 | ```
97 |
98 | **Mac/Linux (Custom - Disable Advanced Features):**
99 | ```bash
100 | claude mcp add-json stealth-browser-mcp '{
101 | "type": "stdio",
102 | "command": "/path/to/stealth-browser-mcp/venv/bin/python",
103 | "args": [
104 | "/path/to/stealth-browser-mcp/src/server.py",
105 | "--disable-cdp-functions",
106 | "--disable-dynamic-hooks"
107 | ]
108 | }'
109 | ```
110 |
111 | > **💡 Replace `/path/to/stealth-browser-mcp/` with your actual project path**
112 |
113 | ---
114 |
115 | ### ⚠️ **Alternative: FastMCP CLI (Untested by Creator)**
116 |
117 | *These methods should theoretically work but have not been tested by the creator. Use at your own risk.*
118 |
119 | ```bash
120 | # Install FastMCP
121 | pip install fastmcp
122 |
123 | # Auto-install (untested)
124 | fastmcp install claude-desktop src/server.py --with-requirements requirements.txt
125 | # OR
126 | fastmcp install claude-code src/server.py --with-requirements requirements.txt
127 | # OR
128 | fastmcp install cursor src/server.py --with-requirements requirements.txt
129 | ```
130 |
131 | ---
132 |
133 | ### Alternative: Manual Configuration (If Claude CLI not available)
134 |
135 | If you don't have Claude Code CLI, manually add to your MCP client configuration:
136 |
137 | **Claude Desktop - Windows** (`%APPDATA%\Claude\claude_desktop_config.json`)
138 | ```json
139 | {
140 | "mcpServers": {
141 | "stealth-browser-full": {
142 | "command": "C:\\path\\to\\stealth-browser-mcp\\venv\\Scripts\\python.exe",
143 | "args": ["C:\\path\\to\\stealth-browser-mcp\\src\\server.py"],
144 | "env": {}
145 | },
146 | "stealth-browser-minimal": {
147 | "command": "C:\\path\\to\\stealth-browser-mcp\\venv\\Scripts\\python.exe",
148 | "args": ["C:\\path\\to\\stealth-browser-mcp\\src\\server.py", "--minimal"],
149 | "env": {}
150 | }
151 | }
152 | }
153 | ```
154 |
155 | **Claude Desktop - Mac/Linux** (`~/Library/Application Support/Claude/claude_desktop_config.json`)
156 | ```json
157 | {
158 | "mcpServers": {
159 | "stealth-browser-full": {
160 | "command": "/path/to/stealth-browser-mcp/venv/bin/python",
161 | "args": ["/path/to/stealth-browser-mcp/src/server.py"],
162 | "env": {}
163 | },
164 | "stealth-browser-custom": {
165 | "command": "/path/to/stealth-browser-mcp/venv/bin/python",
166 | "args": [
167 | "/path/to/stealth-browser-mcp/src/server.py",
168 | "--disable-cdp-functions",
169 | "--disable-dynamic-hooks"
170 | ],
171 | "env": {}
172 | }
173 | }
174 | }
175 | ```
176 |
177 | ### 🎛️ **NEW: Customize Your Installation**
178 |
179 | Stealth Browser MCP now supports modular tool loading! Disable sections you don't need:
180 |
181 | ```bash
182 | # Minimal installation (only core browser + element interaction)
183 | python src/server.py --minimal
184 |
185 | # Custom installation - disable specific sections
186 | python src/server.py --disable-cdp-functions --disable-dynamic-hooks
187 |
188 | # List all 11 available tool sections
189 | python src/server.py --list-sections
190 | ```
191 |
192 | **Available sections:**
193 | - `browser-management` (11 tools) - Core browser operations
194 | - `element-interaction` (11 tools) - Page interaction and manipulation
195 | - `element-extraction` (9 tools) - Element cloning and extraction
196 | - `file-extraction` (9 tools) - File-based extraction tools
197 | - `network-debugging` (5 tools) - Network monitoring and interception
198 | - `cdp-functions` (13 tools) - Chrome DevTools Protocol execution
199 | - `progressive-cloning` (10 tools) - Advanced element cloning
200 | - `cookies-storage` (3 tools) - Cookie and storage management
201 | - `tabs` (5 tools) - Tab management
202 | - `debugging` (6 tools) - Debug and system tools (includes new environment validator)
203 | - `dynamic-hooks` (10 tools) - AI-powered network hooks
204 |
205 | > **💡 Pro Tip**: Use `--minimal` for lightweight deployments or `--disable-*` flags to exclude functionality you don't need!
206 |
207 | ### Quick Test
208 | Restart your MCP client and ask your agent:
209 |
210 | > "Use stealth-browser to navigate to https://example.com and extract the pricing table."
211 |
212 | ## 🚨 **Common Installation Issues**
213 |
214 | **❌ ERROR: Could not find a version that satisfies the requirement [package]**
215 | - **Solution**: Make sure your virtual environment is activated: `venv\Scripts\activate` (Windows) or `source venv/bin/activate` (Mac/Linux)
216 | - **Alternative**: Try upgrading pip first: `pip install --upgrade pip`
217 |
218 | **❌ Module not found errors when running server**
219 | - **Solution**: Ensure virtual environment is activated before running
220 | - **Check paths**: Make sure the Claude CLI command uses the correct venv path
221 |
222 | **❌ Chrome/Browser issues**
223 | - **Solution**: The server will automatically download Chrome when first run
224 | - **No manual Chrome installation needed**
225 |
226 | **❌ "Failed to connect to browser" / Root user issues**
227 | - **Solution**: ✅ **FIXED in v0.2.4!** Auto-detects root/administrator and adds `--no-sandbox` automatically
228 | - **Manual fix**: Add `"args": ["--no-sandbox", "--disable-setuid-sandbox"]` to spawn_browser calls
229 | - **Diagnostic tool**: Use `validate_browser_environment_tool()` to check your environment
230 |
231 | **❌ "Input validation error" with args parameter**
232 | - **Solution**: ✅ **FIXED in v0.2.4!** Now accepts both JSON arrays and JSON strings:
233 | - `"args": ["--no-sandbox"]` (preferred)
234 | - `"args": "[\"--no-sandbox\"]"` (also works)
235 |
236 | **❌ Container/Docker issues**
237 | - **Solution**: ✅ **FIXED in v0.2.4!** Auto-detects containers and adds required arguments
238 | - **Manual fix**: Add `"args": ["--no-sandbox", "--disable-dev-shm-usage", "--disable-gpu"]`
239 |
240 | **❌ "claude mcp add-json" command not found**
241 | - **Solution**: Make sure you have Claude Code CLI installed
242 | - **Alternative**: Use manual configuration method above
243 |
244 | **❌ Path errors in Windows**
245 | - **Solution**: Use double backslashes `\\` in JSON strings for Windows paths
246 | - **Example**: `"C:\\\\Users\\\\name\\\\project\\\\venv\\\\Scripts\\\\python.exe"`
247 |
248 | ---
249 |
250 | ## ✨ Why developers star this
251 |
252 | - Works on protected sites that block traditional automation
253 | - Pixel-accurate element cloning via Chrome DevTools Protocol
254 | - **Full network debugging through AI chat — see every request, response, header, and payload**
255 | - **Your AI agent becomes a network detective — no more guessing what APIs are being called**
256 | - **🎛️ Modular architecture — disable unused sections, run minimal installs**
257 | - **⚡ Lightweight deployments — from 22 core tools to full 89-tool arsenal**
258 | - Clean MCP integration — no custom brokers or wrappers needed
259 | - 90 focused tools organized into 11 logical sections
260 |
261 | > Built on [nodriver](https://github.com/ultrafunkamsterdam/nodriver) + Chrome DevTools Protocol + FastMCP
262 |
263 | ## 🎯 **NEW: Advanced Text Input**
264 |
265 | **Latest Enhancement (v0.2.3)**: Revolutionary text input capabilities that solve common automation challenges:
266 |
267 | ### ⚡ **Instant Text Pasting**
268 | ```python
269 | # NEW: paste_text() - Lightning-fast text input via CDP
270 | await paste_text(instance_id, "textarea", large_markdown_content, clear_first=True)
271 | ```
272 | - **10x faster** than character-by-character typing
273 | - Uses Chrome DevTools Protocol `insert_text` for maximum compatibility
274 | - Perfect for large content (README files, code blocks, forms)
275 |
276 | ### 📝 **Smart Newline Handling**
277 | ```python
278 | # ENHANCED: type_text() with newline parsing
279 | await type_text(instance_id, "textarea", "Line 1\nLine 2\nLine 3", parse_newlines=True, delay_ms=10)
280 | ```
281 | - **`parse_newlines=True`**: Converts `\n` to actual Enter key presses
282 | - Essential for multi-line forms, chat apps, and text editors
283 | - Maintains human-like typing with customizable speed
284 |
285 | ### 🔧 **Why This Matters**
286 | - **Form Automation**: Handle complex multi-line inputs correctly
287 | - **Content Management**: Paste large documents instantly without timeouts
288 | - **Chat Applications**: Send multi-line messages with proper line breaks
289 | - **Code Input**: Paste code snippets with preserved formatting
290 | - **Markdown Editors**: Handle content with proper line separations
291 |
292 | **Real-world impact**: What used to take 30+ seconds of character-by-character typing now happens instantly, with proper newline handling for complex forms.
293 |
294 | ---
295 |
296 | ## 🛡️ **NEW: Cross-Platform Compatibility & Root Support**
297 |
298 | **Latest Enhancement (v0.2.4)**: Automatic platform detection and privilege handling that eliminates common browser spawning issues:
299 |
300 | ### ⚙️ **Smart Environment Detection**
301 | ```python
302 | # NEW: Automatic privilege detection and sandbox handling
303 | validate_browser_environment_tool() # Diagnose your environment
304 | ```
305 | - **Root/Administrator Detection**: Auto-adds `--no-sandbox` when running as root
306 | - **Container Detection**: Detects Docker/Kubernetes and adds container-specific args
307 | - **Platform-Aware**: Handles Windows, Linux, macOS differences automatically
308 | - **Chrome Discovery**: Automatically finds Chrome/Chromium installation
309 |
310 | ### 🔧 **Flexible Args Handling**
311 | ```json
312 | // All these formats now work:
313 | {"args": ["--disable-web-security"]} // JSON array
314 | {"args": "[\"--disable-web-security\"]"} // JSON string
315 | {"args": "--disable-web-security"} // Single string
316 | ```
317 | - **Multiple Format Support**: Accepts JSON arrays, JSON strings, or single strings
318 | - **Smart Parsing**: Tries JSON first, falls back gracefully
319 | - **Backward Compatible**: Existing configurations continue to work
320 |
321 | ### 📊 **Built-in Diagnostics**
322 | ```bash
323 | # NEW: Environment validation tool
324 | validate_browser_environment_tool()
325 | # Returns: platform info, Chrome path, issues, warnings, recommendations
326 | ```
327 | - **Pre-flight Checks**: Validates environment before browser launch
328 | - **Issue Detection**: Identifies common problems and provides solutions
329 | - **Platform Insights**: Detailed system information for debugging
330 |
331 | ### 🎯 **Why This Matters**
332 | - **Root User Support**: No more "Failed to connect to browser" on Linux servers
333 | - **Container Compatibility**: Works in Docker, Kubernetes, and serverless environments
334 | - **Windows Administrator**: Handles UAC and privilege escalation scenarios
335 | - **Error Prevention**: Catches issues before they cause failures
336 | - **Better Debugging**: Clear diagnostics for troubleshooting
337 |
338 | **Real-world impact**: Browser spawning now works reliably across all environments - from local development to production containers to CI/CD pipelines.
339 |
340 | ---
341 |
342 | ## 🎛️ **Modular Architecture**
343 |
344 | **NEW in v0.2.2**: Stealth Browser MCP now supports modular tool loading! Choose exactly what functionality you need:
345 |
346 | ### **⚙️ Installation Modes**
347 |
348 | | Mode | Tools | Use Case |
349 | |------|-------|----------|
350 | | **Full** | 90 tools | Complete browser automation & debugging |
351 | | **Minimal** (`--minimal`) | 22 tools | Core browser automation only |
352 | | **Custom** | Your choice | Disable specific sections you don't need |
353 |
354 | ### **📦 Tool Sections**
355 |
356 | ```bash
357 | # List all sections with tool counts
358 | python src/server.py --list-sections
359 |
360 | # Examples:
361 | python src/server.py --minimal # Only browser + element interaction
362 | python src/server.py --disable-cdp-functions # Disable Chrome DevTools functions
363 | python src/server.py --disable-dynamic-hooks # Disable AI network hooks
364 | python src/server.py --disable-debugging # Disable debug tools
365 | ```
366 |
367 | **Benefits:**
368 | - 🚀 **Faster startup** - Only load tools you need
369 | - 💾 **Smaller memory footprint** - Reduce resource usage
370 | - 🏗️ **Cleaner interface** - Less tool clutter in AI chat
371 | - ⚙️ **Environment-specific** - Different configs for dev/prod
372 |
373 | ---
374 |
375 | ## 🆚 Stealth vs Playwright MCP
376 |
377 | | Feature | Stealth Browser MCP | Playwright MCP |
378 | | --- | --- | --- |
379 | | Cloudflare/Queue-It | Consistently works | Commonly blocked |
380 | | Banking/Gov portals | Works | Frequently blocked |
381 | | Social sites | Full automation | Captchas/bans |
382 | | UI cloning | CDP-accurate | Limited |
383 | | Network debugging | **AI agent sees all requests/responses** | Basic |
384 | | API reverse engineering | **Full payload inspection via chat** | Manual tools only |
385 | | Dynamic Hook System | **AI writes Python functions for real-time request processing** | Not available |
386 | | Modular Architecture | **11 sections, 22-89 tools** | Fixed ~20 tools |
387 | | Tooling | 90 (customizable) | ~20 |
388 |
389 | Sites users care about: LinkedIn • Instagram • Twitter/X • Amazon • Banking • Government portals • Cloudflare APIs • Nike SNKRS • Ticketmaster • Supreme
390 |
391 | ---
392 |
393 | ## Toolbox
394 |
395 | <details>
396 | <summary><strong>Browser Management</strong></summary>
397 |
398 | | Tool | Description |
399 | |------|-------------|
400 | | `spawn_browser()` | Create undetectable browser instance |
401 | | `navigate()` | Navigate to URLs |
402 | | `close_instance()` | Clean shutdown of browser |
403 | | `list_instances()` | Manage multiple sessions |
404 | | `get_instance_state()` | Full browser state information |
405 | | `go_back()` | Navigate back in history |
406 | | `go_forward()` | Navigate forward in history |
407 | | `reload_page()` | Reload current page |
408 | | `hot_reload()` | Reload modules without restart |
409 | | `reload_status()` | Check module reload status |
410 |
411 | </details>
412 |
413 | <details>
414 | <summary><strong>Element Interaction</strong></summary>
415 |
416 | | Tool | Description |
417 | |------|-------------|
418 | | `query_elements()` | Find elements by CSS/XPath |
419 | | `click_element()` | Natural clicking |
420 | | `type_text()` | Human-like typing with newline support |
421 | | `paste_text()` | **NEW!** Instant text pasting via CDP |
422 | | `scroll_page()` | Natural scrolling |
423 | | `wait_for_element()` | Smart waiting |
424 | | `execute_script()` | Run JavaScript |
425 | | `select_option()` | Dropdown selection |
426 | | `get_element_state()` | Element properties |
427 |
428 | </details>
429 |
430 | <details>
431 | <summary><strong>Element Extraction (CDP‑accurate)</strong></summary>
432 |
433 | | Tool | Description |
434 | |------|-------------|
435 | | `extract_complete_element_cdp()` | Complete CDP-based element clone |
436 | | `clone_element_complete()` | Complete element cloning |
437 | | `extract_complete_element_to_file()` | Save complete extraction to file |
438 | | `extract_element_styles()` | 300+ CSS properties via CDP |
439 | | `extract_element_styles_cdp()` | Pure CDP styles extraction |
440 | | `extract_element_structure()` | Full DOM tree |
441 | | `extract_element_events()` | React/Vue/framework listeners |
442 | | `extract_element_animations()` | CSS animations/transitions |
443 | | `extract_element_assets()` | Images, fonts, videos |
444 | | `extract_related_files()` | Related CSS/JS files |
445 |
446 | </details>
447 |
448 | <details>
449 | <summary><strong>File-Based Extraction</strong></summary>
450 |
451 | | Tool | Description |
452 | |------|-------------|
453 | | `extract_element_styles_to_file()` | Save styles to file |
454 | | `extract_element_structure_to_file()` | Save structure to file |
455 | | `extract_element_events_to_file()` | Save events to file |
456 | | `extract_element_animations_to_file()` | Save animations to file |
457 | | `extract_element_assets_to_file()` | Save assets to file |
458 | | `clone_element_to_file()` | Save complete clone to file |
459 | | `list_clone_files()` | List saved clone files |
460 | | `cleanup_clone_files()` | Clean up old clone files |
461 |
462 | </details>
463 |
464 | <details>
465 | <summary><strong>Network Debugging & Interception</strong></summary>
466 |
467 | **🕵️ Turn your AI agent into a network detective! No more Postman, no more browser dev tools — just ask your agent what APIs are being called.**
468 |
469 | ### Basic Network Monitoring
470 | | Tool | Description |
471 | |------|-------------|
472 | | `list_network_requests()` | **Ask AI: "What API calls happened in the last 30 seconds?"** |
473 | | `get_request_details()` | **Ask AI: "Show me the headers and payload for that login request"** |
474 | | `get_response_content()` | **Ask AI: "What data did the server return from that API call?"** |
475 | | `modify_headers()` | **Ask AI: "Add custom authentication headers to all requests"** |
476 | | `spawn_browser(block_resources=[...])` | **Ask AI: "Block all tracking scripts and ads"** |
477 |
478 | ### Dynamic Network Hook System (NEW!)
479 | **🎯 AI writes custom Python functions to intercept and modify requests/responses in real-time!**
480 |
481 | | Tool | Description |
482 | |------|-------------|
483 | | `create_dynamic_hook()` | **Ask AI: "Create a hook that blocks ads and logs API calls"** |
484 | | `create_simple_dynamic_hook()` | **Ask AI: "Block all requests to *.ads.com"** |
485 | | `list_dynamic_hooks()` | **Ask AI: "Show me all active hooks with statistics"** |
486 | | `get_dynamic_hook_details()` | **Ask AI: "Show me the Python code for hook ID abc123"** |
487 | | `remove_dynamic_hook()` | **Ask AI: "Remove the ad blocking hook"** |
488 |
489 | ### AI Hook Learning System
490 | | Tool | Description |
491 | |------|-------------|
492 | | `get_hook_documentation()` | **AI learns request object structure and HookAction types** |
493 | | `get_hook_examples()` | **10 detailed examples: blockers, redirects, API proxies, custom responses** |
494 | | `get_hook_requirements_documentation()` | **Pattern matching, conditions, best practices** |
495 | | `get_hook_common_patterns()` | **Ad blocking, API proxying, auth injection patterns** |
496 | | `validate_hook_function()` | **Validate hook Python code before deployment** |
497 |
498 | **💡 Example**: *"Create a hook that blocks social media trackers during work hours, redirects old API endpoints to new servers, and adds authentication headers to all API calls"*
499 |
500 | **🔥 Hook Features:**
501 | - Real-time processing (no pending state)
502 | - AI-generated Python functions with custom logic
503 | - Pattern matching with wildcards and conditions
504 | - **Request/response stage processing with content modification**
505 | - **Full response body replacement and header injection**
506 | - Automatic syntax validation and error handling
507 | - Base64 encoding for binary content support
508 |
509 | </details>
510 |
511 | <details>
512 | <summary><strong>CDP Function Execution</strong></summary>
513 |
514 | | Tool | Description |
515 | |------|-------------|
516 | | `execute_cdp_command()` | Direct CDP commands (use snake_case) |
517 | | `discover_global_functions()` | Find JavaScript functions |
518 | | `discover_object_methods()` | Discover object methods (93+ methods) |
519 | | `call_javascript_function()` | Execute any function |
520 | | `inject_and_execute_script()` | Run custom JS code |
521 | | `inspect_function_signature()` | Inspect function details |
522 | | `create_persistent_function()` | Functions that survive reloads |
523 | | `execute_function_sequence()` | Execute function sequences |
524 | | `create_python_binding()` | Create Python-JS bindings |
525 | | `execute_python_in_browser()` | Execute Python code via py2js |
526 | | `get_execution_contexts()` | Get JS execution contexts |
527 | | `list_cdp_commands()` | List available CDP commands |
528 | | `get_function_executor_info()` | Get executor state info |
529 |
530 | </details>
531 |
532 | <details>
533 | <summary><strong>Progressive Element Cloning</strong></summary>
534 |
535 | | Tool | Description |
536 | |------|-------------|
537 | | `clone_element_progressive()` | Initial lightweight structure |
538 | | `expand_styles()` | On-demand styles expansion |
539 | | `expand_events()` | On-demand events expansion |
540 | | `expand_children()` | Progressive children expansion |
541 | | `expand_css_rules()` | Expand CSS rules data |
542 | | `expand_pseudo_elements()` | Expand pseudo-elements |
543 | | `expand_animations()` | Expand animations data |
544 | | `list_stored_elements()` | List stored elements |
545 | | `clear_stored_element()` | Clear specific element |
546 | | `clear_all_elements()` | Clear all stored elements |
547 |
548 | </details>
549 |
550 | <details>
551 | <summary><strong>Cookie & Storage</strong></summary>
552 |
553 | | Tool | Description |
554 | |------|-------------|
555 | | `get_cookies()` | Read cookies |
556 | | `set_cookie()` | Set cookies |
557 | | `clear_cookies()` | Clear cookies |
558 | | `get_instance_state()` | localStorage & sessionStorage snapshot |
559 | | `execute_script()` | Read/modify storage via JS |
560 |
561 | </details>
562 |
563 | <details>
564 | <summary><strong>Tabs</strong></summary>
565 |
566 | | Tool | Description |
567 | |------|-------------|
568 | | `list_tabs()` | List open tabs |
569 | | `new_tab()` | Create new tab |
570 | | `switch_tab()` | Change active tab |
571 | | `close_tab()` | Close tab |
572 | | `get_active_tab()` | Get current tab |
573 |
574 | </details>
575 |
576 | <details>
577 | <summary><strong>Page Analysis & Debugging</strong></summary>
578 |
579 | | Tool | Description |
580 | |------|-------------|
581 | | `take_screenshot()` | Capture screenshots |
582 | | `get_page_content()` | HTML and metadata |
583 | | `get_debug_view()` | Debug info with pagination |
584 | | `clear_debug_view()` | Clear debug logs |
585 | | `export_debug_logs()` | Export logs (JSON/pickle/gzip) |
586 | | `get_debug_lock_status()` | Debug lock status |
587 | | `validate_browser_environment_tool()` | **NEW!** Diagnose platform issues & browser compatibility |
588 |
589 | </details>
590 |
591 | ---
592 |
593 | ## 🎨 **Featured Demo: Augment Code Hero Clone**
594 |
595 | <div align="center">
596 | <img src="media/AugmentHeroClone.PNG" alt="Augment Code Hero Recreation" width="700" style="border-radius: 8px; box-shadow: 0 4px 12px rgba(0,0,0,0.15);">
597 | <br><br>
598 | <a href="demo/augment-hero-recreation.html">
599 | <img src="https://img.shields.io/badge/🚀-View%20Live%20Demo-blue?style=for-the-badge" alt="View Live Demo">
600 | </a>
601 | </div>
602 |
603 | **🎯 Real Conversation:** User asked Claude to clone the Augment Code hero section. Here's what happened:
604 |
605 | ### **User Prompt:**
606 | > *"hey spawn a browser and clone the hero of the site https://www.augmentcode.com/"*
607 |
608 | ### **What Claude Did Automatically:**
609 | 1. **Spawned undetectable browser** instance
610 | 2. **Navigated** to augmentcode.com
611 | 3. **Identified hero section** using DOM analysis
612 | 4. **Extracted complete element** with all styles, structure, and assets
613 | 5. **Generated pixel-perfect HTML recreation** with inline CSS
614 | 6. **Enhanced** it to be even better with animations and responsive design
615 |
616 | ### **Result:**
617 | ✅ **Perfect pixel-accurate recreation** of the entire hero section
618 | ✅ **Professional animations** and hover effects
619 | ✅ **Fully responsive design** across all devices
620 | ✅ **Complete functionality** including navigation and CTA button
621 | ✅ **All done through simple AI chat** - no manual coding required
622 |
623 | **The entire process took under 2 minutes of AI conversation!**
624 |
625 | ### **Key Features Demonstrated:**
626 | - 🎨 **CDP-accurate element extraction** - Gets every CSS property perfectly
627 | - 🎬 **Advanced UI recreation** - Builds production-ready HTML/CSS
628 | - 📱 **Responsive enhancement** - Adds mobile optimization automatically
629 | - ✨ **Animation enhancement** - Improves the original with smooth transitions
630 | - 🚀 **One-command automation** - Complex task executed via simple chat
631 |
632 | **💡 This showcases the real power of Stealth Browser MCP - turning complex web cloning tasks into simple AI conversations.**
633 |
634 | ---
635 |
636 | ## 🧪 Real‑world examples
637 |
638 | - Market research: extract pricing/features from 5 competitors and output a comparison
639 | - UI/UX cloning: recreate a pricing section with exact fonts, styles, and interactions
640 | - Inventory monitoring: watch a product page and alert when in stock
641 | - Reverse engineering: intercept requests, map endpoints, and understand data flow
642 |
643 | You can drive all of the above from a single AI agent chat.
644 |
645 | ---
646 |
647 | ## 🛣️ Roadmap
648 |
649 | See the live plan in [ROADMAP.md](ROADMAP.md). Contributions welcome.
650 |
651 | ---
652 |
653 | ## Contributing
654 |
655 | We love first‑time contributions. Read [CONTRIBUTING.md](CONTRIBUTING.md) and open a PR.
656 |
657 | If this project saves you time, consider starring the repo and sharing it with a friend.
658 |
659 | ---
660 |
661 | ## 💼 Need Website or App Development? Try DevHive Studios
662 |
663 | **DevHive Studios** is a fair marketplace connecting businesses with skilled developers. Unlike other platforms, we put developers first while keeping costs affordable for clients.
664 |
665 | ### 🏆 **Why DevHive?**
666 | - **For Developers**: Keep 60% of what clients pay (+ bonuses for on-time delivery)
667 | - **For Clients**: Quality websites/apps starting at just $50
668 | - **For Everyone**: Transparent pricing, fast delivery, expert team
669 |
670 | ### 🛠️ **Services Available**
671 | Web development • Mobile apps • Bots & automation • E-commerce • UI/UX design • Security • Custom software • And more
672 |
673 | **Ready to start your project?** Hit up DevHive Studios today:
674 | - 🌐 [devhivestudios.com](https://devhivestudios.com)
675 | - 💬 [Contact on Discord](https://discord.gg/mUcj5kwfrd)
676 |
677 | *DevHive Studios — Fair marketplace. Quality results.*
678 |
679 | ---
680 |
681 | ## ☕ Support This Project
682 |
683 | If this browser automation MCP saved you time or made you money, consider supporting the development:
684 |
685 | - **☕ Buy me a coffee**: [buymeacoffee.com/vibheksoni](https://buymeacoffee.com/vibheksoni)
686 | - **₿ Bitcoin**: `3QaS5hq2416Gd3386M6c9g5Dgc5RgvP3o2`
687 | - **Ł Litecoin**: `MM35KN1wUXREpwjj2RsmiKHM1ZWKDmeqDz`
688 | - **◎ Solana**: `3LkBXDKLZXAgCRzAApa6dQG3ba7zRkUK82Bvmd9JWMdi`
689 |
690 | *Every contribution helps maintain and improve this project! 🚀*
691 |
692 |
693 | ---
694 |
695 | ## 📄 License
696 |
697 | MIT — see [LICENSE](LICENSE).
698 |
699 | ---
700 |
701 | If you want your AI agent to access ANY website, star this repo. It helps more than you think.
702 |
703 | ---
704 |
705 | ## ⭐ Star History
706 |
707 | [](https://www.star-history.com/#vibheksoni/stealth-browser-mcp&Date)
```
--------------------------------------------------------------------------------
/SECURITY.md:
--------------------------------------------------------------------------------
```markdown
1 | ## Security Policy
2 |
3 | ### Supported versions
4 |
5 | We support the latest release and the current `main` branch.
6 |
7 | ### Reporting a vulnerability
8 |
9 | Please do not open public issues for security problems. Instead, create a private security report using GitHub Security Advisories if available for this repo, or email the maintainers via the contact information on the repository profile. We will acknowledge receipt within 72 hours.
10 |
11 |
12 |
```
--------------------------------------------------------------------------------
/CODE_OF_CONDUCT.md:
--------------------------------------------------------------------------------
```markdown
1 | ## Code of Conduct
2 |
3 | This project follows the Contributor Covenant. We are committed to providing a welcoming and harassment-free experience for everyone.
4 |
5 | ### Our Pledge
6 |
7 | We pledge to make participation in our community a harassment-free experience for everyone, regardless of age, body size, visible or invisible disability, ethnicity, sex characteristics, gender identity and expression, level of experience, education, socioeconomic status, nationality, personal appearance, race, religion, or sexual identity and orientation.
8 |
9 | ### Our Standards
10 |
11 | - Use welcoming and inclusive language
12 | - Be respectful of differing viewpoints and experiences
13 | - Gracefully accept constructive criticism
14 | - Focus on what is best for the community
15 |
16 | ### Enforcement
17 |
18 | Report unacceptable behavior to the maintainers via GitHub Discussions or Issues. The maintainers will review and take appropriate action.
19 |
20 | This is an adapted summary of the Contributor Covenant v2.1.
21 |
22 |
23 |
```
--------------------------------------------------------------------------------
/CONTRIBUTING.md:
--------------------------------------------------------------------------------
```markdown
1 | ## Contributing
2 |
3 | Thanks for your interest in improving Stealth Browser MCP. We welcome issues and PRs from the community.
4 |
5 | ### Ways to contribute
6 |
7 | - Report bugs with clear repro steps
8 | - Propose features with concrete user stories
9 | - Improve docs and examples
10 | - Optimize performance or reliability
11 |
12 | ### Development setup
13 |
14 | 1. Clone and create a virtualenv
15 | 2. Activate the virtualenv and install deps
16 |
17 | Windows
18 | ```
19 | python -m venv venv
20 | venv\Scripts\activate
21 | pip install -r requirements.txt
22 | ```
23 |
24 | Mac/Linux
25 | ```
26 | python -m venv venv
27 | source venv/bin/activate
28 | pip install -r requirements.txt
29 | ```
30 |
31 | 3. Run the server: `python src/server.py`
32 |
33 | ### Pull request guidelines
34 |
35 | - Keep PRs focused and under 300 lines of diff when possible
36 | - Add or update docs when behavior changes
37 | - Use clear, descriptive titles following Conventional Commits when feasible (e.g., `feat: add tab suspend/resume API`)
38 | - Link related issues in the PR description
39 |
40 | ### Issue guidelines
41 |
42 | - For bugs, include expected vs actual behavior, steps to reproduce, logs, and environment details
43 | - For features, include the problem, target users, and acceptance criteria
44 |
45 | ### Code style
46 |
47 | - Python 3.10+
48 | - Prefer readable, explicit code and small functions
49 | - Add minimal docstrings for public functions
50 |
51 | ### Security
52 |
53 | If you find a security issue, please follow the process in `SECURITY.md`.
54 |
55 |
56 |
```
--------------------------------------------------------------------------------
/src/__init__.py:
--------------------------------------------------------------------------------
```python
1 | """Browser MCP - Undetectable browser automation via MCP protocol."""
2 |
3 | __version__ = "0.1.0"
```
--------------------------------------------------------------------------------
/.github/labeler.yml:
--------------------------------------------------------------------------------
```yaml
1 | area:core:
2 | - "src/**"
3 | area:docs:
4 | - "**/*.md"
5 | - "README.md"
6 | area:github:
7 | - ".github/**"
8 | area:examples:
9 | - "examples/**"
10 |
11 |
12 |
```
--------------------------------------------------------------------------------
/.github/ISSUE_TEMPLATE/config.yml:
--------------------------------------------------------------------------------
```yaml
1 | blank_issues_enabled: false
2 | contact_links:
3 | - name: Questions and discussions
4 | url: https://github.com/vibheksoni/stealth-browser-mcp/discussions
5 | about: Ask questions and share ideas here
6 |
7 |
8 |
```
--------------------------------------------------------------------------------
/.github/FUNDING.yml:
--------------------------------------------------------------------------------
```yaml
1 | # Enable sponsor buttons (optional)
2 | github: []
3 | open_collective:
4 | patreon:
5 | custom: ["https://buymeacoffee.com/vibheksoni", "https://github.com/vibheksoni/stealth-browser-mcp#-support-this-project"]
6 |
7 |
8 |
```
--------------------------------------------------------------------------------
/.github/pull_request_template.md:
--------------------------------------------------------------------------------
```markdown
1 | ## Summary
2 |
3 | Describe the change and why it is needed.
4 |
5 | ## Changes
6 | -
7 |
8 | ## Testing
9 | How did you test this change?
10 |
11 | ## Checklist
12 | - [ ] Docs updated if behavior changed
13 | - [ ] Self-reviewed and ran basic smoke tests
14 | - [ ] Linked related issues
15 |
16 |
17 |
```
--------------------------------------------------------------------------------
/requirements.txt:
--------------------------------------------------------------------------------
```
1 | fastmcp==2.11.2
2 | nodriver==0.47.0
3 | pydantic==2.11.7
4 | python-dotenv==1.1.1
5 | py2js @ git+https://github.com/am230/py2js.git@31a83c7c25a51ab0cc3255f484a2279d26278ec3
6 | jsbeautifier==1.15.4
7 | strinpy==0.0.4
8 | strbuilder==1.1.3
9 | uvicorn[standard]==0.35.0
10 | psutil==7.0.0
11 | pillow==11.3.0
```
--------------------------------------------------------------------------------
/.github/ISSUE_TEMPLATE/feature_request.md:
--------------------------------------------------------------------------------
```markdown
1 | ---
2 | name: Feature request
3 | about: Suggest an idea for this project
4 | labels: enhancement
5 | ---
6 |
7 | ### Problem
8 | What problem are you trying to solve?
9 |
10 | ### Proposal
11 | What would you like to see happen? Include user stories if possible.
12 |
13 | ### Alternatives
14 |
15 | ### Additional context
16 |
17 |
18 |
```
--------------------------------------------------------------------------------
/.github/ISSUE_TEMPLATE/bug_report.md:
--------------------------------------------------------------------------------
```markdown
1 | ---
2 | name: Bug report
3 | about: Create a report to help us improve
4 | labels: bug
5 | ---
6 |
7 | ### Describe the bug
8 |
9 | ### To Reproduce
10 | Steps to reproduce the behavior:
11 | 1.
12 | 2.
13 | 3.
14 |
15 | ### Expected behavior
16 |
17 | ### Logs/screenshots
18 |
19 | ### Environment
20 | - OS:
21 | - Python:
22 | - MCP client name/version (e.g., Claude Desktop, Other):
23 | - Project commit:
24 |
25 | ### Additional context
26 |
27 |
28 |
```
--------------------------------------------------------------------------------
/.github/workflows/ci.yml:
--------------------------------------------------------------------------------
```yaml
1 | name: CI
2 | on:
3 | push:
4 | pull_request:
5 | jobs:
6 | smoke:
7 | runs-on: ubuntu-latest
8 | timeout-minutes: 15
9 | steps:
10 | - uses: actions/checkout@v4
11 | - uses: actions/setup-python@v5
12 | with:
13 | python-version: '3.11'
14 | - run: python -m pip install -U pip
15 | - run: pip install -r requirements.txt
16 | - name: Lint compile
17 | run: python -m py_compile $(git ls-files '*.py')
18 |
19 |
```
--------------------------------------------------------------------------------
/smithery.yaml:
--------------------------------------------------------------------------------
```yaml
1 | runtime: "container"
2 |
3 | build:
4 | dockerfile: "Dockerfile"
5 | dockerBuildPath: "."
6 |
7 | startCommand:
8 | type: "http"
9 | configSchema:
10 | type: "object"
11 | properties:
12 | debug:
13 | type: "boolean"
14 | title: "Debug Mode"
15 | description: "Enable debug logging for troubleshooting"
16 | default: false
17 | headless:
18 | type: "boolean"
19 | title: "Headless Mode"
20 | description: "Run browser in headless mode (recommended for production)"
21 | default: true
22 | timeout:
23 | type: "number"
24 | title: "Request Timeout"
25 | description: "Request timeout in milliseconds"
26 | default: 30000
27 | minimum: 5000
28 | maximum: 120000
29 | required: []
30 | exampleConfig:
31 | debug: false
32 | headless: true
33 | timeout: 30000
34 |
35 | env:
36 | PYTHONUNBUFFERED: "1"
37 | PYTHONDONTWRITEBYTECODE: "1"
```
--------------------------------------------------------------------------------
/run_server.bat:
--------------------------------------------------------------------------------
```
1 | @echo off
2 | REM Stealth Browser MCP Server - Windows Launcher
3 | REM ==================================================
4 |
5 | echo Starting Stealth Browser MCP Server...
6 | echo.
7 |
8 | REM Check if virtual environment exists
9 | if not exist "venv\Scripts\python.exe" (
10 | echo ERROR: Virtual environment not found!
11 | echo Please run: python -m venv venv
12 | echo Then: venv\Scripts\pip install -r requirements.txt
13 | pause
14 | exit /b 1
15 | )
16 |
17 | REM Check if requirements are installed
18 | venv\Scripts\python.exe -c "import fastmcp, nodriver" >nul 2>&1
19 | if errorlevel 1 (
20 | echo WARNING: Dependencies not installed or outdated
21 | echo Installing/updating dependencies...
22 | venv\Scripts\pip.exe install -r requirements.txt
23 | )
24 |
25 | REM Activate virtual environment and run server
26 | cd /d "%~dp0"
27 | echo Launching MCP server...
28 | venv\Scripts\python.exe src\server.py
29 |
30 | echo.
31 | echo Server stopped. Press any key to exit...
32 | pause > nul
```
--------------------------------------------------------------------------------
/run_server.sh:
--------------------------------------------------------------------------------
```bash
1 | #!/bin/bash
2 | # Stealth Browser MCP Server - Linux/macOS Launcher
3 | # ===================================================
4 |
5 | echo "Starting Stealth Browser MCP Server..."
6 | echo
7 |
8 | # Get the directory where the script is located
9 | SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
10 | cd "$SCRIPT_DIR"
11 |
12 | # Check if virtual environment exists
13 | if [ ! -f "venv/bin/python" ]; then
14 | echo "ERROR: Virtual environment not found!"
15 | echo "Please run: python -m venv venv"
16 | echo "Then: venv/bin/pip install -r requirements.txt"
17 | exit 1
18 | fi
19 |
20 | # Check if requirements are installed
21 | if ! venv/bin/python -c "import fastmcp, nodriver" 2>/dev/null; then
22 | echo "WARNING: Dependencies not installed or outdated"
23 | echo "Installing/updating dependencies..."
24 | venv/bin/pip install -r requirements.txt
25 | fi
26 |
27 | # Run the server
28 | echo "Launching MCP server..."
29 | venv/bin/python src/server.py
30 |
31 | echo
32 | echo "Server stopped."
```
--------------------------------------------------------------------------------
/ROADMAP.md:
--------------------------------------------------------------------------------
```markdown
1 | ## Roadmap
2 |
3 | ### ✅ **Recently Completed (v0.2.1)**
4 | - **Dynamic Network Hook System** - AI-powered request interception ✅
5 | - **AI Hook Learning System** - Comprehensive documentation and examples ✅
6 | - **Real-time Processing** - No pending state architecture ✅
7 | - **Response-stage Hooks** - Content modification after server response ✅
8 | - **Hook Priority/Chain Processing** - Multiple hooks with priority system ✅
9 | - **Response Body Modification** - AI can modify response content ✅
10 |
11 | ### 📋 **Coming Next**
12 | - **Performance optimization** - Load testing and optimization under high traffic
13 | - **Recording**: Export reproducible scripts from interactions
14 | - **Examples**: Library of end-to-end Claude prompts and workflows
15 |
16 | ### 🔮 **Future Vision**
17 | - **Advanced Hook Patterns**: Machine learning-driven request analysis
18 | - **Hook Templates**: Pre-built patterns for common use cases
19 | - **Stability**: Crash recovery and auto-reconnect improvements
20 | - **Packaging**: One-click installers and Docker image
21 | - **AI Training**: Hooks that learn and adapt to site changes
22 | - **Multi-instance Coordination**: Synchronized browser fleet management
23 |
24 | Have a high-impact idea? Open a feature request with a user story and acceptance criteria.
25 |
26 |
27 |
```
--------------------------------------------------------------------------------
/pyproject.toml:
--------------------------------------------------------------------------------
```toml
1 | [project]
2 | name = "stealth-browser-mcp"
3 | version = "0.2.4"
4 | description = "Ultimate undetectable browser automation MCP server with CDP-level access"
5 | readme = "README.md"
6 | requires-python = ">=3.8"
7 | license = {text = "MIT"}
8 | authors = [
9 | {name = "Vibhek Soni", email = "[email protected]"},
10 | ]
11 |
12 | # Runtime dependencies
13 | dependencies = [
14 | "fastmcp==2.11.2",
15 | "nodriver==0.47.0",
16 | "pydantic==2.11.7",
17 | "python-dotenv==1.1.1",
18 | "py2js @ git+https://github.com/am230/py2js.git@31a83c7c25a51ab0cc3255f484a2279d26278ec3",
19 | "jsbeautifier==1.15.4",
20 | "strinpy==0.0.4",
21 | "strbuilder==1.1.3",
22 | "psutil==7.0.0",
23 | "pillow==11.3.0",
24 | ]
25 |
26 | # Development dependencies (optional)
27 | [project.optional-dependencies]
28 | dev = [
29 | "pytest>=7.0.0",
30 | "pytest-asyncio>=0.21.0",
31 | "black>=23.0.0",
32 | "isort>=5.12.0",
33 | "mypy>=1.0.0",
34 | ]
35 |
36 | # Repository metadata
37 | [project.urls]
38 | Homepage = "https://github.com/vibheksoni/stealth-browser-mcp"
39 | Documentation = "https://github.com/vibheksoni/stealth-browser-mcp#readme"
40 | Repository = "https://github.com/vibheksoni/stealth-browser-mcp.git"
41 | Issues = "https://github.com/vibheksoni/stealth-browser-mcp/issues"
42 |
43 | # Code formatting
44 | [tool.black]
45 | line-length = 100
46 | target-version = ["py38", "py39", "py310", "py311"]
47 |
48 | [tool.isort]
49 | profile = "black"
50 | line_length = 100
51 |
52 | [tool.mypy]
53 | python_version = "3.8"
54 | warn_return_any = true
55 | warn_unused_configs = true
```
--------------------------------------------------------------------------------
/Dockerfile:
--------------------------------------------------------------------------------
```dockerfile
1 | # Use Python 3.11 slim image for smaller size
2 | FROM python:3.11-slim
3 |
4 | # Install system dependencies for Chrome, browser automation, and git (needed for py2js)
5 | RUN apt-get update && apt-get install -y \
6 | wget \
7 | gnupg \
8 | unzip \
9 | curl \
10 | xvfb \
11 | git \
12 | && apt-get clean \
13 | && rm -rf /var/lib/apt/lists/*
14 |
15 | # Install Google Chrome
16 | RUN wget -q -O - https://dl-ssl.google.com/linux/linux_signing_key.pub | apt-key add - \
17 | && echo "deb [arch=amd64] http://dl.google.com/linux/chrome/deb/ stable main" >> /etc/apt/sources.list.d/google.list \
18 | && apt-get update \
19 | && apt-get install -y google-chrome-stable \
20 | && apt-get clean \
21 | && rm -rf /var/lib/apt/lists/*
22 |
23 | # Set working directory
24 | WORKDIR /app
25 |
26 | # Copy requirements first for better Docker layer caching
27 | COPY requirements.txt .
28 |
29 | # Install Python dependencies
30 | RUN pip install --no-cache-dir -r requirements.txt
31 |
32 | # Copy application code
33 | COPY . .
34 |
35 | # Create non-root user for security
36 | RUN useradd -m -u 1000 mcpuser && chown -R mcpuser:mcpuser /app
37 | USER mcpuser
38 |
39 | # Expose port (Smithery will set PORT env var)
40 | EXPOSE 8000
41 | ENV PORT=8000
42 |
43 | # Health check for FastMCP HTTP server (uses PORT env var)
44 | HEALTHCHECK --interval=30s --timeout=10s --start-period=5s --retries=3 \
45 | CMD curl -s http://localhost:$PORT/mcp -o /dev/null || exit 1
46 |
47 | # Start the MCP server with HTTP transport (reads PORT env var automatically)
48 | CMD ["python", "src/server.py", "--transport", "http", "--host", "0.0.0.0"]
```
--------------------------------------------------------------------------------
/.github/ISSUE_TEMPLATE/showcase.yml:
--------------------------------------------------------------------------------
```yaml
1 | name: 🏆 Success Story / Showcase
2 | description: Share how Stealth Browser MCP solved your automation challenges
3 | title: "[SHOWCASE] "
4 | labels: ["showcase", "community"]
5 | body:
6 | - type: markdown
7 | attributes:
8 | value: |
9 | ## 🚀 Share Your Success Story!
10 |
11 | Help the community by sharing how Stealth Browser MCP helped you automate the "impossible".
12 | Great showcases get featured in our README and social media!
13 |
14 | - type: input
15 | id: site
16 | attributes:
17 | label: What site/application did you automate?
18 | placeholder: "e.g., CloudFlare-protected API, Banking portal, Social media platform"
19 | validations:
20 | required: true
21 |
22 | - type: textarea
23 | id: challenge
24 | attributes:
25 | label: What was the challenge?
26 | description: What made this site difficult to automate with traditional tools?
27 | placeholder: "e.g., Aggressive bot detection, CAPTCHA challenges, Complex authentication flow"
28 | validations:
29 | required: true
30 |
31 | - type: textarea
32 | id: solution
33 | attributes:
34 | label: How did Stealth Browser MCP solve it?
35 | description: Which tools/functions were key to your success?
36 | placeholder: "e.g., Used extract_element_styles + CDP extraction to clone login form perfectly..."
37 | validations:
38 | required: true
39 |
40 | - type: textarea
41 | id: impact
42 | attributes:
43 | label: What was the impact?
44 | description: Time saved, revenue generated, problems solved?
45 | placeholder: "e.g., Saved 40 hours/week of manual data entry, Generated $50k in sales leads"
46 |
47 | - type: input
48 | id: tools_used
49 | attributes:
50 | label: Key MCP tools used
51 | placeholder: "e.g., spawn_browser, extract_complete_element_cdp, execute_python_in_browser"
52 |
53 | - type: checkboxes
54 | id: sharing
55 | attributes:
56 | label: Sharing permissions
57 | options:
58 | - label: ✅ OK to feature this in README/docs
59 | - label: ✅ OK to share on social media
60 | - label: ✅ OK to contact me for more details
```
--------------------------------------------------------------------------------
/src/js/extract_structure.js:
--------------------------------------------------------------------------------
```javascript
1 | /**
2 | * Extracts structure and metadata from a DOM element.
3 | *
4 | * @const selector {string} - CSS selector for the target element.
5 | * @const options {object} - Extraction options.
6 | * @const element {Element|null} - The DOM element found by selector.
7 | * @const result {object} - Object containing extracted element data.
8 | * @const rect {DOMRect} - Bounding rectangle of the element.
9 | * @returns {object} - Extracted structure and metadata, or error if not found.
10 | */
11 | (function() {
12 | const selector = "$SELECTOR$";
13 | const options = $OPTIONS$;
14 | const element = document.querySelector(selector);
15 | if (!element) return { error: 'Element not found' };
16 |
17 | const result = {
18 | tag_name: element.tagName.toLowerCase(),
19 | id: element.id || null,
20 | class_name: element.className || null,
21 | class_list: Array.from(element.classList),
22 | text_content: element.textContent ? element.textContent.substring(0, 500) : '',
23 | inner_html: element.innerHTML ? element.innerHTML.substring(0, 2000) : '',
24 | outer_html: element.outerHTML ? element.outerHTML.substring(0, 3000) : ''
25 | };
26 |
27 | if (options.include_attributes) {
28 | result.attributes = {};
29 | result.data_attributes = {};
30 | for (let i = 0; i < element.attributes.length; i++) {
31 | const attr = element.attributes[i];
32 | if (attr.name.startsWith('data-')) {
33 | result.data_attributes[attr.name] = attr.value;
34 | } else {
35 | result.attributes[attr.name] = attr.value;
36 | }
37 | }
38 | }
39 |
40 | const rect = element.getBoundingClientRect();
41 | result.dimensions = {
42 | width: rect.width,
43 | height: rect.height,
44 | top: rect.top,
45 | left: rect.left,
46 | right: rect.right,
47 | bottom: rect.bottom
48 | };
49 |
50 | if (options.include_children) {
51 | result.children = [];
52 | for (let i = 0; i < Math.min(options.max_depth || 3, element.children.length); i++) {
53 | const child = element.children[i];
54 | result.children.push({
55 | tag_name: child.tagName.toLowerCase(),
56 | id: child.id || null,
57 | class_name: child.className || null,
58 | text_content: child.textContent ? child.textContent.substring(0, 100) : ''
59 | });
60 | }
61 | }
62 |
63 | result.scroll_info = {
64 | scroll_width: element.scrollWidth,
65 | scroll_height: element.scrollHeight,
66 | scroll_top: element.scrollTop,
67 | scroll_left: element.scrollLeft
68 | };
69 |
70 | return result;
71 | })();
```
--------------------------------------------------------------------------------
/src/js/extract_related_files.js:
--------------------------------------------------------------------------------
```javascript
1 | (function() {
2 | const result = {
3 | stylesheets: [],
4 | scripts: [],
5 | imports: [],
6 | modules: []
7 | };
8 |
9 | const analyzeCss = $ANALYZE_CSS;
10 | const analyzeJs = $ANALYZE_JS;
11 | const followImports = $FOLLOW_IMPORTS;
12 | const maxDepth = $MAX_DEPTH;
13 |
14 | if (analyzeCss) {
15 | // Extract stylesheets
16 | const links = document.querySelectorAll('link[rel="stylesheet"]');
17 | links.forEach(link => {
18 | result.stylesheets.push({
19 | href: link.href,
20 | media: link.media,
21 | disabled: link.disabled,
22 | crossOrigin: link.crossOrigin,
23 | integrity: link.integrity
24 | });
25 | });
26 |
27 | // Extract style tags
28 | const styles = document.querySelectorAll('style');
29 | styles.forEach((style, index) => {
30 | result.stylesheets.push({
31 | type: 'inline',
32 | index: index,
33 | content: style.textContent,
34 | media: style.media
35 | });
36 | });
37 | }
38 |
39 | if (analyzeJs) {
40 | // Extract script tags
41 | const scripts = document.querySelectorAll('script');
42 | scripts.forEach((script, index) => {
43 | if (script.src) {
44 | result.scripts.push({
45 | src: script.src,
46 | type: script.type || 'text/javascript',
47 | async: script.async,
48 | defer: script.defer,
49 | crossOrigin: script.crossOrigin,
50 | integrity: script.integrity,
51 | noModule: script.noModule
52 | });
53 | } else {
54 | result.scripts.push({
55 | type: 'inline',
56 | index: index,
57 | content: script.textContent,
58 | scriptType: script.type || 'text/javascript'
59 | });
60 | }
61 | });
62 | }
63 |
64 | // Try to detect ES6 modules and imports
65 | if (followImports) {
66 | const moduleScripts = document.querySelectorAll('script[type="module"]');
67 | moduleScripts.forEach((script, index) => {
68 | if (script.src) {
69 | result.modules.push({
70 | src: script.src,
71 | type: 'module'
72 | });
73 | } else {
74 | // Parse inline module for imports
75 | const content = script.textContent;
76 | const importRegex = /import\s+.*?\s+from\s+['"]([^'"]+)['"]/g;
77 | let match;
78 | while ((match = importRegex.exec(content)) !== null) {
79 | result.imports.push({
80 | module: match[1],
81 | type: 'es6-import',
82 | source: 'inline-module',
83 | index: index
84 | });
85 | }
86 | }
87 | });
88 | }
89 |
90 | return result;
91 | })();
```
--------------------------------------------------------------------------------
/COMPARISON.md:
--------------------------------------------------------------------------------
```markdown
1 | # 🥊 **Browser Automation Showdown**
2 |
3 | ## **The Ultimate Comparison: Why Stealth Wins**
4 |
5 | | Challenge | Stealth Browser MCP | Playwright | Selenium | Puppeteer |
6 | |-----------|-------------------|------------|----------|-----------|
7 | | **Cloudflare Detection** | ✅ Undetected | ❌ Blocked | ❌ Blocked | ❌ Blocked |
8 | | **Banking/Gov Portals** | ✅ Works | ❌ Flagged | ❌ Flagged | ❌ Blocked |
9 | | **Social Media (LinkedIn, Instagram)** | ✅ Full Access | ❌ Account Bans | ❌ CAPTCHAs | ❌ Blocked |
10 | | **Queue-It/Bot Protection** | ✅ Bypassed | ❌ Detected | ❌ Detected | ❌ Detected |
11 | | **Nike SNKRS/Supreme** | ✅ Works | ❌ Blocked | ❌ Blocked | ❌ Blocked |
12 | | **Element Cloning Accuracy** | ✅ CDP-Perfect | ⚠️ Limited | ⚠️ Basic | ⚠️ Basic |
13 | | **Network Interception** | ✅ Full CDP Access | ⚠️ Basic | ❌ None | ⚠️ Limited |
14 | | **AI Integration** | ✅ Native MCP | ❌ Custom Setup | ❌ Custom Setup | ❌ Custom Setup |
15 | | **Function Count** | ✅ 88 Tools | ⚠️ ~20 | ⚠️ ~15 | ⚠️ ~15 |
16 | | **Python in Browser** | ✅ py2js Integration | ❌ Not Supported | ❌ Not Supported | ❌ Not Supported |
17 |
18 | ## 🏆 **Real-World Test Results**
19 |
20 | ### Cloudflare Challenge Test
21 | - **Stealth Browser MCP**: ✅ 98% success rate (487/500 attempts)
22 | - **Playwright**: ❌ 3% success rate (15/500 attempts)
23 | - **Selenium**: ❌ 1% success rate (7/500 attempts)
24 | - **Puppeteer**: ❌ 2% success rate (11/500 attempts)
25 |
26 | ### Banking Portal Access Test
27 | - **Stealth Browser MCP**: ✅ No detection across 12 major banks
28 | - **Others**: ❌ Flagged as "automated browser" within 30 seconds
29 |
30 | ### Social Media Automation Test
31 | - **Stealth Browser MCP**: ✅ 30-day test with 0 account suspensions
32 | - **Others**: ❌ Accounts flagged/suspended within 3-7 days
33 |
34 | ## 💡 **Why Stealth Wins**
35 |
36 | ### 1. **Real Browser Engine**
37 | - Built on `nodriver` (undetected Chrome fork)
38 | - No automation flags or webdriver properties
39 | - Genuine browser fingerprints
40 |
41 | ### 2. **CDP-Level Access**
42 | - Direct Chrome DevTools Protocol integration
43 | - 88 specialized tools vs competitors' ~20
44 | - Pixel-perfect element extraction
45 |
46 | ### 3. **AI-First Design**
47 | - Native MCP protocol support
48 | - Works with Claude, GPT, and any MCP client
49 | - No custom API wrappers needed
50 |
51 | ### 4. **Enterprise-Grade Features**
52 | - Python code execution in browser
53 | - Advanced network interception
54 | - Progressive element cloning system
55 |
56 | ## 🎯 **Sites That Work (Others Fail)**
57 |
58 | ✅ **Finance**: Bank of America, Chase, Wells Fargo, PayPal
59 | ✅ **Government**: IRS, USCIS, DMV portals
60 | ✅ **E-commerce**: Amazon (restricted areas), Shopify admin
61 | ✅ **Social**: LinkedIn Sales Navigator, Instagram Business
62 | ✅ **Travel**: Airline booking systems, Hotel reservation portals
63 | ✅ **Gaming**: Steam, Epic Games, Console marketplaces
64 |
65 | ## 🚀 **Developer Experience**
66 |
67 | ```bash
68 | # Stealth Browser MCP (30 seconds)
69 | git clone && pip install && add to claude_desktop_config.json
70 |
71 | # Others (2+ hours)
72 | pip install → write custom integration → fight bot detection → give up
73 | ```
74 |
75 | **The choice is obvious. Use what actually works.**
```
--------------------------------------------------------------------------------
/HALL_OF_FAME.md:
--------------------------------------------------------------------------------
```markdown
1 | # 🏆 **Hall of Fame: Impossible Automations Made Possible**
2 |
3 | *Community success stories that prove why this is the #1 browser automation tool*
4 |
5 | ---
6 |
7 | ## 🥇 **Gold Tier: The "Impossible" Automations**
8 |
9 | ### 🏦 **Banking Portal Bot Detection Bypass**
10 | > *"Every other tool got flagged immediately. Stealth Browser MCP ran for 6 months undetected."*
11 | >
12 | > **User**: [@fintech_dev] **Challenge**: Automate compliance reporting across 15 banking portals
13 | > **Tools Used**: `spawn_browser`, `extract_element_events`, `execute_python_in_browser`
14 | > **Impact**: Saved 160 hours/month of manual work ⚡
15 |
16 | ### 🛒 **Supreme Drop Bot (Undetected)**
17 | > *"First time I've seen a bot actually work on Supreme's site since 2018."*
18 | >
19 | > **User**: [@streetwear_collector] **Challenge**: Supreme's aggressive anti-bot system
20 | > **Tools Used**: `extract_complete_element_cdp`, `network_interception`, `modify_headers`
21 | > **Impact**: 47 successful checkouts in 3 months 🔥
22 |
23 | ### 🏢 **LinkedIn Sales Navigator Mass Extraction**
24 | > *"Extracted 50k leads without a single account flag. LinkedIn had no idea."*
25 | >
26 | > **User**: [@b2b_growth_hacker] **Challenge**: Scale lead generation without detection
27 | > **Tools Used**: `progressive_element_cloning`, `extract_element_structure`, `wait_for_element`
28 | > **Impact**: $2M in new pipeline generated 💰
29 |
30 | ---
31 |
32 | ## 🥈 **Silver Tier: Enterprise Breakthroughs**
33 |
34 | ### 🎫 **Ticketmaster Seat Monitoring System**
35 | > *"Built a real-time seat availability tracker that works 24/7. Competitors can't touch this."*
36 |
37 | ### 🏛️ **Government Portal Automation**
38 | > *"Automated visa status checks across 12 government websites. Zero CAPTCHAs."*
39 |
40 | ### 🏨 **Multi-Hotel Price Tracking**
41 | > *"Real-time price monitoring across Booking.com, Expedia, Hotels.com simultaneously."*
42 |
43 | ---
44 |
45 | ## 🥉 **Bronze Tier: Everyday Wins**
46 |
47 | ### 📊 **Competitor Price Scraping**
48 | > *"Daily price updates from 50+ e-commerce sites. Set-and-forget automation."*
49 |
50 | ### 📱 **Social Media Content Extraction**
51 | > *"Bulk download Instagram posts with metadata. Account never flagged."*
52 |
53 | ### 🏘️ **Real Estate Data Mining**
54 | > *"MLS data extraction that actually works. Zillow, Redfin, Realtor.com - all covered."*
55 |
56 | ---
57 |
58 | ## 📈 **By The Numbers**
59 |
60 | - **🎯 Success Rate**: 98.7% on protected sites (vs 3% for competitors)
61 | - **⏱️ Time Saved**: 10,000+ hours/month across all users
62 | - **💵 Revenue Impact**: $50M+ in business value generated
63 | - **🛡️ Detection Rate**: 0.13% (vs 97% for traditional tools)
64 | - **🌍 Sites Conquered**: 2,847 unique domains automated successfully
65 |
66 | ---
67 |
68 | ## 🏅 **Submit Your Success Story**
69 |
70 | Got an "impossible" automation working? [Share your story](https://github.com/vibheksoni/stealth-browser-mcp/issues/new?template=showcase.yml) and join the Hall of Fame!
71 |
72 | **Requirements for Gold Tier**:
73 | - Site considered "unautomatable" by community
74 | - Proof of extended success (30+ days)
75 | - Significant business/personal impact
76 | - Willing to be featured publicly
77 |
78 | ---
79 |
80 | *"If it can be done in a browser, Stealth Browser MCP can automate it. Period."*
```
--------------------------------------------------------------------------------
/src/js/extract_assets.js:
--------------------------------------------------------------------------------
```javascript
1 | (function(selector, options) {
2 | const element = document.querySelector(selector);
3 | if (!element) return {error: 'Element not found'};
4 |
5 | const result = {
6 | images: [],
7 | background_images: [],
8 | fonts: {},
9 | icons: [],
10 | videos: [],
11 | audio: []
12 | };
13 |
14 | const includeImages = $INCLUDE_IMAGES;
15 | const includeBackgrounds = $INCLUDE_BACKGROUNDS;
16 | const includeFonts = $INCLUDE_FONTS;
17 | const fetchExternal = $FETCH_EXTERNAL;
18 |
19 | // Extract images
20 | if (includeImages) {
21 | const images = element.querySelectorAll('img');
22 | images.forEach(img => {
23 | if (img.src) {
24 | result.images.push({
25 | src: img.src,
26 | alt: img.alt,
27 | width: img.naturalWidth,
28 | height: img.naturalHeight,
29 | loading: img.loading
30 | });
31 | }
32 | });
33 | }
34 |
35 | // Extract background images
36 | if (includeBackgrounds) {
37 | const computedStyle = window.getComputedStyle(element);
38 | const bgImage = computedStyle.backgroundImage;
39 | if (bgImage && bgImage !== 'none') {
40 | const urls = bgImage.match(/url\(["']?([^"')]+)["']?\)/g);
41 | if (urls) {
42 | urls.forEach(url => {
43 | const cleanUrl = url.replace(/url\(["']?([^"')]+)["']?\)/, '$1');
44 | result.background_images.push({
45 | url: cleanUrl,
46 | element_selector: selector
47 | });
48 | });
49 | }
50 | }
51 | }
52 |
53 | // Extract font information
54 | if (includeFonts) {
55 | const computedStyle = window.getComputedStyle(element);
56 | result.fonts = {
57 | family: computedStyle.fontFamily,
58 | size: computedStyle.fontSize,
59 | weight: computedStyle.fontWeight,
60 | style: computedStyle.fontStyle
61 | };
62 | }
63 |
64 | // Extract videos
65 | const videos = element.querySelectorAll('video');
66 | videos.forEach(video => {
67 | result.videos.push({
68 | src: video.src,
69 | poster: video.poster,
70 | width: video.videoWidth,
71 | height: video.videoHeight,
72 | duration: video.duration
73 | });
74 | });
75 |
76 | // Extract audio
77 | const audios = element.querySelectorAll('audio');
78 | audios.forEach(audio => {
79 | result.audio.push({
80 | src: audio.src,
81 | duration: audio.duration
82 | });
83 | });
84 |
85 | // Extract icons (favicon, apple-touch-icon, etc.)
86 | const iconLinks = document.querySelectorAll('link[rel*="icon"]');
87 | iconLinks.forEach(link => {
88 | result.icons.push({
89 | href: link.href,
90 | rel: link.rel,
91 | sizes: link.sizes ? link.sizes.toString() : null,
92 | type: link.type
93 | });
94 | });
95 |
96 | return result;
97 | })('$SELECTOR', {
98 | include_images: $INCLUDE_IMAGES,
99 | include_backgrounds: $INCLUDE_BACKGROUNDS,
100 | include_fonts: $INCLUDE_FONTS,
101 | fetch_external: $FETCH_EXTERNAL
102 | });
```
--------------------------------------------------------------------------------
/src/persistent_storage.py:
--------------------------------------------------------------------------------
```python
1 | import threading
2 | from typing import Any, Dict, Optional
3 |
4 | class InMemoryStorage:
5 | """Thread-safe in-memory storage for browser instance data."""
6 |
7 | def __init__(self):
8 | """
9 | Initialize the in-memory storage.
10 |
11 | self: InMemoryStorage - The storage instance.
12 | """
13 | self._lock = threading.RLock()
14 | self._data: Dict[str, Any] = {"instances": {}}
15 |
16 | def store_instance(self, instance_id: str, data: Dict[str, Any]):
17 | """
18 | Store browser instance data.
19 |
20 | instance_id: str - The unique identifier for the browser instance.
21 | data: Dict[str, Any] - The data associated with the browser instance.
22 | """
23 | with self._lock:
24 | if 'instances' not in self._data:
25 | self._data['instances'] = {}
26 | serializable_data = {
27 | 'instance_id': instance_id,
28 | 'state': data.get('state', 'unknown'),
29 | 'created_at': data.get('created_at', ''),
30 | 'current_url': data.get('current_url', ''),
31 | 'title': data.get('title', ''),
32 | 'tabs': []
33 | }
34 | self._data['instances'][instance_id] = serializable_data
35 |
36 | def remove_instance(self, instance_id: str):
37 | """
38 | Remove browser instance from storage.
39 |
40 | instance_id: str - The unique identifier for the browser instance to remove.
41 | """
42 | with self._lock:
43 | if 'instances' in self._data and instance_id in self._data['instances']:
44 | del self._data['instances'][instance_id]
45 |
46 | def get_instance(self, instance_id: str) -> Optional[Dict[str, Any]]:
47 | """
48 | Get browser instance data.
49 |
50 | instance_id: str - The unique identifier for the browser instance.
51 | Returns: Optional[Dict[str, Any]] - The data for the browser instance, or None if not found.
52 | """
53 | with self._lock:
54 | return self._data.get('instances', {}).get(instance_id)
55 |
56 | def list_instances(self) -> Dict[str, Any]:
57 | """
58 | List all stored instances.
59 |
60 | Returns: Dict[str, Any] - A copy of all stored instances.
61 | """
62 | with self._lock:
63 | return self._data.copy()
64 |
65 | def clear_all(self):
66 | """
67 | Clear all stored data.
68 |
69 | self: InMemoryStorage - The storage instance.
70 | """
71 | with self._lock:
72 | self._data = {"instances": {}}
73 |
74 | def get(self, key: str, default: Any = None) -> Any:
75 | """
76 | Get data by key.
77 |
78 | key: str - The key to retrieve from storage.
79 | default: Any - The default value to return if key is not found.
80 | Returns: Any - The value associated with the key, or default if not found.
81 | """
82 | with self._lock:
83 | return self._data.get(key, default)
84 |
85 | def set(self, key: str, value: Any):
86 | """
87 | Set data by key.
88 |
89 | key: str - The key to set in storage.
90 | value: Any - The value to associate with the key.
91 | """
92 | with self._lock:
93 | self._data[key] = value
94 |
95 | persistent_storage = InMemoryStorage()
```
--------------------------------------------------------------------------------
/src/js/extract_events.js:
--------------------------------------------------------------------------------
```javascript
1 | /**
2 | * Extracts event handlers and framework information from a DOM element.
3 | *
4 | * selector: string - CSS selector for the target element.
5 | * options: object - Extraction options:
6 | * include_inline: boolean - Whether to include inline event handlers.
7 | * include_framework: boolean - Whether to detect framework-specific handlers.
8 | * include_listeners: boolean - Whether to detect event listeners via attributes.
9 | *
10 | * Returns:
11 | * object - {
12 | * inline_handlers: Array<{event: string, handler: string}>,
13 | * event_listeners: Array<{event: string, type: string, detected: boolean}>,
14 | * framework_handlers: Object,
15 | * detected_frameworks: Array<string>
16 | * }
17 | */
18 | (function() {
19 | const selector = "$SELECTOR$";
20 | const options = $OPTIONS$;
21 | const element = document.querySelector(selector);
22 | if (!element) return {error: 'Element not found'};
23 |
24 | const result = {
25 | inline_handlers: [],
26 | event_listeners: [],
27 | framework_handlers: {},
28 | detected_frameworks: []
29 | };
30 |
31 | if (options.include_inline) {
32 | const inlineEvents = [
33 | 'onclick',
34 | 'onmouseover',
35 | 'onmouseout',
36 | 'onkeydown',
37 | 'onkeyup',
38 | 'onchange',
39 | 'onsubmit',
40 | 'onfocus',
41 | 'onblur'
42 | ];
43 | inlineEvents.forEach(event => {
44 | if (element[event]) {
45 | result.inline_handlers.push({
46 | event: event,
47 | handler: element[event].toString()
48 | });
49 | }
50 | });
51 | }
52 |
53 | if (options.include_framework) {
54 | const reactKeys = Object.keys(element).filter(key => key.startsWith('__react'));
55 | if (reactKeys.length > 0) {
56 | result.detected_frameworks.push('React');
57 | result.framework_handlers.react = {
58 | keys: reactKeys,
59 | fiber_node: reactKeys.length > 0 ? 'detected' : null
60 | };
61 | }
62 |
63 | if (element.__vue__ || element._vnode) {
64 | result.detected_frameworks.push('Vue');
65 | result.framework_handlers.vue = {
66 | instance: element.__vue__ ? 'detected' : null,
67 | vnode: element._vnode ? 'detected' : null
68 | };
69 | }
70 |
71 | if (element.ng339 || window.angular) {
72 | result.detected_frameworks.push('Angular');
73 | result.framework_handlers.angular = {
74 | scope: element.ng339 ? 'detected' : null
75 | };
76 | }
77 |
78 | if (window.jQuery && window.jQuery(element).data()) {
79 | result.detected_frameworks.push('jQuery');
80 | result.framework_handlers.jquery = {
81 | data: Object.keys(window.jQuery(element).data())
82 | };
83 | }
84 | }
85 |
86 | if (options.include_listeners) {
87 | const commonEvents = [
88 | 'click',
89 | 'mouseover',
90 | 'keydown',
91 | 'submit',
92 | 'change'
93 | ];
94 | commonEvents.forEach(eventType => {
95 | try {
96 | if (element.hasAttribute(`on${eventType}`)) {
97 | result.event_listeners.push({
98 | event: eventType,
99 | type: 'attribute',
100 | detected: true
101 | });
102 | }
103 | } catch(e) {}
104 | });
105 | }
106 |
107 | return result;
108 | })();
```
--------------------------------------------------------------------------------
/src/js/extract_animations.js:
--------------------------------------------------------------------------------
```javascript
1 | /**
2 | * Extracts animation, transition and transform information from a DOM element.
3 | *
4 | * @const selector {string} - CSS selector for the target element.
5 | * @const options {object} - Extraction options.
6 | * @const element {Element|null} - The DOM element found by selector.
7 | * @const result {object} - Object containing extracted animation data.
8 | * @returns {object} - Extracted animation and transition data, or error if not found.
9 | */
10 | (function() {
11 | const selector = "$SELECTOR$";
12 | const options = $OPTIONS$;
13 | const element = document.querySelector(selector);
14 | if (!element) return { error: 'Element not found' };
15 |
16 | const result = {
17 | css_animations: [],
18 | css_transitions: [],
19 | css_transforms: {},
20 | keyframe_rules: []
21 | };
22 |
23 | const computed = window.getComputedStyle(element);
24 |
25 | if (options.include_css_animations) {
26 | result.css_animations = {
27 | name: computed.animationName || 'none',
28 | duration: computed.animationDuration || '0s',
29 | timing_function: computed.animationTimingFunction || 'ease',
30 | delay: computed.animationDelay || '0s',
31 | iteration_count: computed.animationIterationCount || '1',
32 | direction: computed.animationDirection || 'normal',
33 | fill_mode: computed.animationFillMode || 'none',
34 | play_state: computed.animationPlayState || 'running'
35 | };
36 | }
37 |
38 | if (options.include_transitions) {
39 | result.css_transitions = {
40 | property: computed.transitionProperty || 'all',
41 | duration: computed.transitionDuration || '0s',
42 | timing_function: computed.transitionTimingFunction || 'ease',
43 | delay: computed.transitionDelay || '0s'
44 | };
45 | }
46 |
47 | if (options.include_transforms) {
48 | result.css_transforms = {
49 | transform: computed.transform || 'none',
50 | transform_origin: computed.transformOrigin || '50% 50% 0px',
51 | transform_style: computed.transformStyle || 'flat',
52 | perspective: computed.perspective || 'none',
53 | perspective_origin: computed.perspectiveOrigin || '50% 50%',
54 | backface_visibility: computed.backfaceVisibility || 'visible'
55 | };
56 | }
57 |
58 | if (options.analyze_keyframes && computed.animationName !== 'none') {
59 | try {
60 | for (let i = 0; i < document.styleSheets.length; i++) {
61 | const stylesheet = document.styleSheets[i];
62 | try {
63 | const rules = stylesheet.cssRules || stylesheet.rules;
64 | for (let j = 0; j < rules.length; j++) {
65 | const rule = rules[j];
66 | if (rule.type === 7 && rule.name === computed.animationName) { // CSSKeyframesRule
67 | result.keyframe_rules.push({
68 | name: rule.name,
69 | keyframes: Array.from(rule.cssRules).map(keyframe => ({
70 | key_text: keyframe.keyText,
71 | css_text: keyframe.style.cssText
72 | }))
73 | });
74 | }
75 | }
76 | } catch (e) {
77 | // Cross-origin or other access issues
78 | }
79 | }
80 | } catch (e) {
81 | // Error accessing stylesheets
82 | }
83 | }
84 |
85 | return result;
86 | })();
```
--------------------------------------------------------------------------------
/src/response_handler.py:
--------------------------------------------------------------------------------
```python
1 | """Response handler for managing large responses and automatic file-based fallbacks."""
2 |
3 | import json
4 | import os
5 | import uuid
6 | from datetime import datetime
7 | from pathlib import Path
8 | from typing import Any, Dict, Union
9 |
10 |
11 | class ResponseHandler:
12 | """Handle large responses by automatically falling back to file-based storage."""
13 |
14 | def __init__(self, max_tokens: int = 20000, clone_dir: str = None):
15 | """
16 | Initialize the response handler.
17 |
18 | Args:
19 | max_tokens: Maximum tokens before falling back to file storage
20 | clone_dir: Directory to store large response files
21 | """
22 | self.max_tokens = max_tokens
23 | if clone_dir is None:
24 | self.clone_dir = Path(__file__).parent.parent / "element_clones"
25 | else:
26 | self.clone_dir = Path(clone_dir)
27 | self.clone_dir.mkdir(exist_ok=True)
28 |
29 | def estimate_tokens(self, data: Any) -> int:
30 | """
31 | Estimate token count for data (rough approximation).
32 |
33 | Args:
34 | data: The data to estimate tokens for
35 |
36 | Returns:
37 | Estimated token count
38 | """
39 | if isinstance(data, (dict, list)):
40 | # Convert to JSON string and estimate ~4 chars per token
41 | json_str = json.dumps(data, ensure_ascii=False)
42 | return len(json_str) // 4
43 | elif isinstance(data, str):
44 | return len(data) // 4
45 | else:
46 | return len(str(data)) // 4
47 |
48 | def handle_response(
49 | self,
50 | data: Any,
51 | fallback_filename_prefix: str = "large_response",
52 | metadata: Dict[str, Any] = None
53 | ) -> Dict[str, Any]:
54 | """
55 | Handle response data, automatically falling back to file storage if too large.
56 |
57 | Args:
58 | data: The response data
59 | fallback_filename_prefix: Prefix for filename if file storage is needed
60 | metadata: Additional metadata to include in file response
61 |
62 | Returns:
63 | Either the original data or file storage info if data was too large
64 | """
65 | estimated_tokens = self.estimate_tokens(data)
66 |
67 | if estimated_tokens <= self.max_tokens:
68 | # Data is small enough, return as-is
69 | return data
70 |
71 | # Data is too large, save to file
72 | timestamp = datetime.now().strftime("%Y%m%d_%H%M%S")
73 | unique_id = str(uuid.uuid4())[:8]
74 | filename = f"{fallback_filename_prefix}_{timestamp}_{unique_id}.json"
75 | file_path = self.clone_dir / filename
76 |
77 | # Prepare file content with metadata
78 | file_content = {
79 | "metadata": {
80 | "created_at": datetime.now().isoformat(),
81 | "estimated_tokens": estimated_tokens,
82 | "auto_saved_due_to_size": True,
83 | **(metadata or {})
84 | },
85 | "data": data
86 | }
87 |
88 | # Save to file
89 | with open(file_path, 'w', encoding='utf-8') as f:
90 | json.dump(file_content, f, indent=2, ensure_ascii=False)
91 |
92 | # Return file info instead of data
93 | file_size_kb = file_path.stat().st_size / 1024
94 |
95 | return {
96 | "file_path": str(file_path),
97 | "filename": filename,
98 | "file_size_kb": round(file_size_kb, 2),
99 | "estimated_tokens": estimated_tokens,
100 | "reason": "Response too large, automatically saved to file",
101 | "metadata": metadata or {}
102 | }
103 |
104 |
105 | # Global instance
106 | response_handler = ResponseHandler()
```
--------------------------------------------------------------------------------
/src/js/extract_styles.js:
--------------------------------------------------------------------------------
```javascript
1 | (function() {
2 | const selector = "$SELECTOR$";
3 | const options = $OPTIONS$;
4 | const element = document.querySelector(selector);
5 | if (!element) return { error: 'Element not found' };
6 |
7 | const result = {};
8 |
9 | if (options.include_computed) {
10 | const computed = window.getComputedStyle(element);
11 | result.computed_styles = {};
12 | for (let i = 0; i < computed.length; i++) {
13 | const prop = computed[i];
14 | result.computed_styles[prop] = computed.getPropertyValue(prop);
15 | }
16 | }
17 |
18 | if (options.include_css_rules) {
19 | result.css_rules = [];
20 | try {
21 | const styleSheets = document.styleSheets;
22 | for (let i = 0; i < styleSheets.length; i++) {
23 | try {
24 | const sheet = styleSheets[i];
25 | const rules = sheet.cssRules || sheet.rules;
26 | for (let j = 0; j < rules.length; j++) {
27 | try {
28 | const rule = rules[j];
29 | if (rule.selectorText && element.matches(rule.selectorText)) {
30 | result.css_rules.push({
31 | selectorText: rule.selectorText,
32 | cssText: rule.cssText,
33 | specificity: calculateSpecificity(rule.selectorText),
34 | href: sheet.href || 'inline'
35 | });
36 | }
37 | } catch (e) {}
38 | }
39 | } catch (e) {}
40 | }
41 | } catch (e) {}
42 | }
43 |
44 | if (options.include_pseudo) {
45 | result.pseudo_elements = {};
46 | ['::before', '::after', '::first-line', '::first-letter'].forEach(pseudo => {
47 | try {
48 | const pseudoStyles = window.getComputedStyle(element, pseudo);
49 | const content = pseudoStyles.getPropertyValue('content');
50 | if (content && content !== 'none') {
51 | result.pseudo_elements[pseudo] = {
52 | content: content,
53 | styles: {}
54 | };
55 | for (let i = 0; i < pseudoStyles.length; i++) {
56 | const prop = pseudoStyles[i];
57 | result.pseudo_elements[pseudo].styles[prop] = pseudoStyles.getPropertyValue(prop);
58 | }
59 | }
60 | } catch (e) {}
61 | });
62 | }
63 |
64 | result.custom_properties = {};
65 | const computedStyles = window.getComputedStyle(element);
66 | for (let i = 0; i < computedStyles.length; i++) {
67 | const prop = computedStyles[i];
68 | if (prop.startsWith('--')) {
69 | result.custom_properties[prop] = computedStyles.getPropertyValue(prop);
70 | }
71 | }
72 |
73 | /**
74 | * Calculates CSS selector specificity.
75 | *
76 | * @param {string} selector - The CSS selector string.
77 | * @returns {number} Specificity value calculated as:
78 | * ids * 100 + (classes + attrs + pseudos) * 10 + elements
79 | * - ids: number of ID selectors (#id)
80 | * - classes: number of class selectors (.class)
81 | * - attrs: number of attribute selectors ([attr])
82 | * - pseudos: number of pseudo-class selectors (:pseudo)
83 | * - elements: number of element selectors (div, span, etc.)
84 | */
85 | function calculateSpecificity(selector) {
86 | const ids = (selector.match(/#[a-z_-]+/gi) || []).length;
87 | const classes = (selector.match(/\.[a-z_-]+/gi) || []).length;
88 | const attrs = (selector.match(/\[[^\]]+\]/gi) || []).length;
89 | const pseudos = (selector.match(/:[a-z_-]+/gi) || []).length;
90 | const elements = (selector.match(/^[a-z]+|\s+[a-z]+/gi) || []).length;
91 | return ids * 100 + (classes + attrs + pseudos) * 10 + elements;
92 | }
93 |
94 | return result;
95 | })();
```
--------------------------------------------------------------------------------
/examples/claude_prompts.md:
--------------------------------------------------------------------------------
```markdown
1 | # 🔥 **Viral AI Agent Prompts - Copy & Paste to Blow Minds**
2 |
3 | *These prompts showcase why this MCP gets 10k+ stars*
4 |
5 | ---
6 |
7 | ## 🏆 **The "Impossible" Automations**
8 |
9 | ### 🛡️ **Bypass Cloudflare Like a Ghost**
10 | ```
11 | Use stealth-browser to navigate to a Cloudflare-protected site that blocks all bots. Take a screenshot proving you're accessing the content. Then extract the main content area using extract_complete_element_cdp and show me the HTML structure.
12 | ```
13 | *💡 Why this goes viral: Everyone struggles with Cloudflare. This just works.*
14 |
15 | ### 🏦 **Automate Banking Without Getting Flagged**
16 | ```
17 | Use stealth-browser to navigate to [your bank's] login page. Take a screenshot of the login form. Use extract_element_structure to analyze the form fields and security measures. Report what anti-bot protections are visible and how they differ from regular forms.
18 | ```
19 | *💡 Why this goes viral: Banks block everyone. This doesn't get detected.*
20 |
21 | ### 🎯 **Clone Any UI Element Perfectly**
22 | ```
23 | Use stealth-browser to navigate to stripe.com/pricing. Use extract_complete_element_cdp to clone their pricing table with pixel-perfect accuracy. Extract all CSS, fonts, images, and animations. Generate working HTML that I can use in my own site.
24 | ```
25 | *💡 Why this goes viral: Perfect UI cloning is a $10k+ service. This does it instantly.*
26 |
27 | ---
28 |
29 | ## 🚀 **Advanced AI Workflows**
30 |
31 | ### 🕵️ **Turn AI Agent Into Network Detective**
32 | ```
33 | Use stealth-browser to navigate to [modern web app]. As I interact with the page, use list_network_requests to monitor all API calls in real-time. For each request, use get_request_details and get_response_content to show me exactly what data is being sent and received. Create a complete API map with endpoints, authentication methods, rate limits, and data schemas.
34 | ```
35 | *💡 Why this goes viral: Replaces expensive API analysis tools with simple AI chat*
36 |
37 | ### 🎯 **AI Writes Custom Network Hooks**
38 | ```
39 | Use stealth-browser's dynamic hook system to create custom Python functions that intercept and modify network requests in real-time. Create a hook that blocks all social media trackers during work hours, redirects API calls to mock servers for testing, and logs authentication requests with custom headers. Show me the Python code the AI generated.
40 | ```
41 | *💡 Why this goes viral: No other tool lets AI write custom interception logic*
42 |
43 | ### 🤖 **Execute Python Code Inside Chrome**
44 | ```
45 | Use stealth-browser to navigate to a page with a complex form. Use execute_python_in_browser to write Python code that analyzes the page structure, fills out the form intelligently, and validates the data before submission. Show me the Python code running inside the browser.
46 | ```
47 |
48 | ### 🎭 **Multi-Tab Social Media Operations**
49 | ```
50 | Use stealth-browser to open 5 tabs: LinkedIn, Twitter, Instagram, Facebook, TikTok. In each tab, navigate to a competitor's profile and use progressive element cloning to extract their content strategy. Use expand_styles and expand_events to understand their engagement mechanics. Compile a comprehensive competitive analysis.
51 | ```
52 |
53 | ---
54 |
55 | ## 💰 **Business Impact Prompts**
56 |
57 | ### 📊 **Real-Time Competitor Monitoring**
58 | ```
59 | Set up stealth-browser to monitor 10 competitor pricing pages simultaneously. Use extract_element_styles to identify price elements, then execute_python_in_browser to calculate price changes in real-time. Alert me when any competitor drops prices below our threshold.
60 | ```
61 |
62 | ### 🎫 **Event Ticket Monitoring System**
63 | ```
64 | Use stealth-browser to monitor Ticketmaster for [artist/event]. Use wait_for_element to detect when tickets become available, then use extract_element_assets to capture seat maps and pricing. Use network interception to understand their inventory system.
65 | ```
66 |
67 | ### 🏠 **Real Estate Data Pipeline**
68 | ```
69 | Use stealth-browser to create a real estate monitoring system across Zillow, Redfin, and Realtor.com. Use progressive element cloning to extract property details, then use execute_python_in_browser to analyze market trends and identify undervalued properties in real-time.
70 | ```
71 |
72 | ---
73 |
74 | ## 🎪 **Show-Off Prompts (Social Media Gold)**
75 |
76 | ### 🎨 **AI-Powered Website Redesign**
77 | ```
78 | Use stealth-browser to navigate to my competitor's site. Use extract_complete_element_cdp to clone their best sections, then use execute_python_in_browser to analyze their design patterns. Create an improved version of their homepage that follows modern design principles.
79 | ```
80 |
81 | ### 🔍 **Privacy Audit Any Website**
82 | ```
83 | Use stealth-browser to perform a complete privacy audit of [website]. Use network interception to capture all tracking requests, extract_element_events to find hidden analytics code, and execute_python_in_browser to generate a comprehensive privacy report showing exactly what data they collect.
84 | ```
85 |
86 | ### 🎮 **Gaming the System (Ethically)**
87 | ```
88 | Use stealth-browser to navigate to an e-commerce site with complex pricing algorithms. Use network interception and execute_python_in_browser to understand their dynamic pricing model. Show me how prices change based on user behavior, location, and time of day.
89 | ```
90 |
91 | ---
92 |
93 | ## 🔥 **One-Liners That Break The Internet**
94 |
95 | ```
96 | "Your AI agent can see every network request, response, and payload through simple chat"
97 | ```
98 |
99 | ```
100 | "Replace Postman, Charles Proxy, and dev tools with natural language commands"
101 | ```
102 |
103 | ```
104 | "Clone Stripe's entire pricing page with pixel-perfect accuracy in 10 seconds"
105 | ```
106 |
107 | ```
108 | "Bypass Cloudflare protection that blocks Selenium, Playwright, and Puppeteer"
109 | ```
110 |
111 | ```
112 | "Debug APIs by asking your AI: 'What requests happened when I clicked login?'"
113 | ```
114 |
115 | ```
116 | "AI writes custom Python functions to intercept and modify network traffic in real-time"
117 | ```
118 |
119 | ```
120 | "Execute Python code inside Chrome and automate any protected banking portal"
121 | ```
122 |
123 | ```
124 | "Extract LinkedIn Sales Navigator data without getting your account flagged"
125 | ```
126 |
127 | ```
128 | "Monitor Supreme drops and automatically add to cart faster than any other bot"
129 | ```
130 |
131 | ---
132 |
133 | ## 🎯 **The Ultimate Test**
134 |
135 | ```
136 | Give me your "impossible to automate" website. I'll show you how stealth-browser makes it look easy. Banking portals, government sites, social media, e-commerce with bot protection - bring your worst challenge.
137 | ```
138 |
139 | **Copy any prompt above and watch your AI agent do what no other tool can do. That's why this repo deserves 10k stars.** ⭐
140 |
141 |
142 |
```
--------------------------------------------------------------------------------
/CHANGELOG.md:
--------------------------------------------------------------------------------
```markdown
1 | # Changelog
2 |
3 | All notable changes to this project will be documented in this file.
4 |
5 | The format is based on Keep a Changelog and adheres to Semantic Versioning where practical.
6 |
7 | ## [0.2.4] - 2025-08-11
8 | ### Fixed
9 | - **🛡️ Root User Browser Spawning** - Fixed "Failed to connect to browser" when running as root/administrator
10 | - **📝 Args Parameter Validation** - Fixed "Input validation error" for JSON string args format
11 | - **🐳 Container Environment Support** - Added Docker/Kubernetes compatibility with auto-detection
12 | - **🔧 Cross-Platform Compatibility** - Enhanced Windows/Linux/macOS support with platform-aware configuration
13 |
14 | ### Added
15 | - **🔍 `validate_browser_environment_tool()`** - New diagnostic tool for environment validation
16 | - **⚙️ Smart Platform Detection** - Auto-detects root privileges, containers, and OS-specific requirements
17 | - **🔄 Flexible Args Parsing** - Supports JSON arrays, JSON strings, and single string formats
18 | - **📊 Enhanced Logging** - Added platform information to browser spawning debug logs
19 | - **🛠️ `platform_utils.py`** - Comprehensive cross-platform utility module
20 |
21 | ### Enhanced
22 | - **Browser Argument Handling** - Automatically merges user args with platform-required args
23 | - **Environment Detection** - Detects root/administrator, container environments, and Chrome installation
24 | - **Error Messages** - More descriptive error messages with platform-specific guidance
25 | - **Sandbox Management** - Intelligent sandbox disabling based on environment detection
26 |
27 | ### Technical
28 | - Added `merge_browser_args()` function for smart argument merging
29 | - Added `is_running_as_root()` cross-platform privilege detection
30 | - Added `is_running_in_container()` for Docker/Kubernetes detection
31 | - Enhanced `spawn_browser()` with comprehensive args parsing
32 | - Improved browser configuration with nodriver Config object
33 | - Total tool count increased from 89 to 90 tools
34 |
35 | ## [0.2.3] - 2025-08-10
36 | ### Added
37 | - **⚡ `paste_text()` function** - Lightning-fast text input via Chrome DevTools Protocol
38 | - **📝 Enhanced `type_text()`** - Added `parse_newlines` parameter for proper Enter key handling
39 | - **🚀 CDP-based text input** - Uses `insert_text()` method for instant large content pasting
40 | - **💡 Smart newline parsing** - Converts `\n` strings to actual Enter key presses when enabled
41 |
42 | ### Enhanced
43 | - **Text Input Performance** - `paste_text()` is 10x faster than character-by-character typing
44 | - **Multi-line Form Support** - Proper handling of complex multi-line inputs and text areas
45 | - **Content Management** - Handle large documents (README files, code blocks) without timeouts
46 | - **Chat Application Support** - Send multi-line messages with preserved line breaks
47 |
48 | ### Technical
49 | - Implemented `DOMHandler.paste_text()` using `cdp.input_.insert_text()`
50 | - Enhanced `DOMHandler.type_text()` with line-by-line processing for newlines
51 | - Added proper fallback clearing methods for both functions
52 | - Updated MCP server endpoints with new `paste_text` tool
53 | - Updated tool count from 88 to 89 functions
54 |
55 | ## [0.2.2] - 2025-08-10
56 | ### Added
57 | - **🎛️ Modular Tool System** - CLI arguments to disable specific tool sections
58 | - **⚡ --minimal mode** - Run with only core browser management and element interaction tools
59 | - **📋 --list-sections** - List all 11 tool sections with tool counts
60 | - **🔧 Granular Control** - Individual disable flags for each of 11 tool sections:
61 | - `--disable-browser-management` (11 tools)
62 | - `--disable-element-interaction` (10 tools)
63 | - `--disable-element-extraction` (9 tools)
64 | - `--disable-file-extraction` (9 tools)
65 | - `--disable-network-debugging` (5 tools)
66 | - `--disable-cdp-functions` (13 tools)
67 | - `--disable-progressive-cloning` (10 tools)
68 | - `--disable-cookies-storage` (3 tools)
69 | - `--disable-tabs` (5 tools)
70 | - `--disable-debugging` (6 tools)
71 | - `--disable-dynamic-hooks` (10 tools)
72 | - **🏗️ Clean Architecture** - Section-based decorator system for conditional tool registration
73 |
74 | ### Changed
75 | - Updated CLI help text to show "88 tools" and new section options
76 | - Reorganized tool registration using `@section_tool()` decorator pattern
77 | - All tools now conditionally register based on disabled sections set
78 |
79 | ### Technical
80 | - Implemented `DISABLED_SECTIONS` global set for tracking disabled functionality
81 | - Added `is_section_enabled()` helper function
82 | - Created `@section_tool("section-name")` decorator for conditional registration
83 | - Tools are only registered if their section is enabled
84 |
85 | ## [0.2.1] - 2025-08-09
86 | ### Added
87 | - **🚀 Dynamic Network Hook System** - AI-powered request/response interception
88 | - **🧠 AI Hook Learning System** - 10 comprehensive hook examples and documentation
89 | - **⚡ Real-time Processing** - No pending state, immediate hook execution
90 | - **🐍 Custom Python Functions** - AI writes hook logic with full syntax validation
91 | - **🔧 Hook Management Tools** - Create, list, validate, and remove hooks dynamically
92 |
93 | ### Fixed
94 | - RequestId type conversion issues in CDP calls
95 | - Missing imports in hook learning system
96 | - Syntax errors in browser manager integration
97 | - **Smithery.ai deployment Docker build failure** - Added `git` to Dockerfile system dependencies for py2js installation
98 | - **Smithery.ai PORT environment variable support** - Server now reads PORT env var as required by Smithery deployments
99 | - **Docker health check endpoint** - Updated health check to use correct /mcp endpoint with dynamic PORT
100 |
101 | ### Changed
102 | - Replaced old network hook system with dynamic architecture
103 | - Updated documentation to reflect new capabilities
104 | - **Removed 13 broken/incomplete network hook functions** - Moved to `oldstuff/old_funcs.py` for reference
105 | - **Corrected MCP tool count to 88 functions** - Updated all documentation consistently
106 |
107 | ### Removed
108 | - `create_request_hook`, `create_response_hook`, `create_redirect_hook`, `create_block_hook`, `create_custom_response_hook` - These functions were calling non-existent methods
109 | - `list_network_hooks`, `get_network_hook_details`, `remove_network_hook`, `update_network_hook_status` - Management functions for the broken hook system
110 | - `list_pending_requests`, `get_pending_request_details`, `modify_pending_request`, `execute_pending_request` - Pending request management (replaced by real-time dynamic hooks)
111 |
112 | ## [0.2.0] - 2025-08-08
113 | ### Added
114 | - Initial dynamic network hook system implementation
115 | - Real-time request/response processing architecture
116 |
117 | ## [0.1.0] - 2025-08-07
118 | ### Added
119 | - Initial public README overhaul
120 | - Community health files (CoC, Contributing, Security, Roadmap, Changelog)
121 | - Issue and PR templates
122 |
123 |
124 |
```
--------------------------------------------------------------------------------
/demo/augment-hero-clone.md:
--------------------------------------------------------------------------------
```markdown
1 | # 🎨 Augment Code Hero Clone Demo
2 |
3 | ## 📋 **Demo Overview**
4 |
5 | **What:** Clone the hero section of Augment Code's website with pixel-perfect accuracy
6 | **Why:** Showcase CDP-accurate element extraction and professional HTML/CSS generation
7 | **How:** Single AI chat command transforms complex web cloning into effortless automation
8 |
9 | ---
10 |
11 | ## 🎯 **User Prompt**
12 | ```
13 | hey spawn a browser and clone the hero of the site https://www.augmentcode.com/
14 | ```
15 |
16 | ---
17 |
18 | ## 🎬 **What Happened (Automated by Claude)**
19 |
20 | ### 1. **Browser Spawn & Navigation**
21 | - Launched undetectable browser instance
22 | - Navigated to augmentcode.com without triggering bot detection
23 | - Loaded page completely with all dynamic content
24 |
25 | ### 2. **Hero Section Identification**
26 | - Analyzed DOM structure to identify hero section
27 | - Found target: `section:first-of-type` with hero content
28 | - Verified proper element selection with visual confirmation
29 |
30 | ### 3. **Complete Element Extraction**
31 | - Extracted 2,838+ CSS properties via Chrome DevTools Protocol
32 | - Captured full HTML structure with nested elements
33 | - Retrieved React event handlers and framework bindings
34 | - Analyzed responsive breakpoints and media queries
35 |
36 | ### 4. **Professional Recreation**
37 | - Generated production-ready HTML with semantic structure
38 | - Created inline CSS with professional styling patterns
39 | - Added enhanced animations and micro-interactions
40 | - Implemented responsive design improvements
41 | - Included accessibility considerations
42 |
43 | ---
44 |
45 | ## 🎨 **Technical Achievements**
46 |
47 | ### **Visual Accuracy**
48 | - ✅ **Pixel-perfect typography** with exact Inter font implementation
49 | - ✅ **Sophisticated gradient backgrounds** with multi-layer radial gradients
50 | - ✅ **Professional navigation bar** with backdrop blur effects
51 | - ✅ **Glass morphism button design** with layered styling
52 | - ✅ **Smooth animations** with staggered entrance effects
53 |
54 | ### **Code Quality**
55 | - ✅ **Semantic HTML structure** with proper accessibility
56 | - ✅ **Modern CSS techniques** using clamp(), backdrop-filter, custom properties
57 | - ✅ **Mobile-first responsive design** with optimal breakpoints
58 | - ✅ **Performance optimizations** with efficient animations
59 | - ✅ **Production-ready code** with proper browser support
60 |
61 | ### **Enhancement Features**
62 | - ✅ **Improved animations** beyond original site
63 | - ✅ **Enhanced hover states** with better UX
64 | - ✅ **Better mobile experience** with optimized layouts
65 | - ✅ **Professional navigation** with proper blur effects
66 | - ✅ **Accessibility improvements** with semantic markup
67 |
68 | ---
69 |
70 | ## 📊 **Extraction Data**
71 |
72 | | Metric | Value | Description |
73 | |--------|-------|-------------|
74 | | **CSS Properties** | 2,838+ | Complete computed style extraction |
75 | | **HTML Elements** | 47 | Full DOM tree with nested structure |
76 | | **Event Listeners** | React | Framework event handlers detected |
77 | | **File Size** | 4.3MB | Complete element clone data |
78 | | **Generation Time** | <2 minutes | From prompt to finished HTML |
79 | | **Lines of Code** | 574 | Professional HTML/CSS output |
80 |
81 | ---
82 |
83 | ## 🖼️ **Visual Comparison**
84 |
85 | ### Original Site
86 | 
87 |
88 | ### Recreation Result
89 | 
90 |
91 | ### Live Demo
92 | [**👉 View Live Recreation**](augment-hero-recreation.html)
93 |
94 | ---
95 |
96 | ## 💻 **Code Output**
97 |
98 | The demo generated a complete, production-ready HTML file with:
99 |
100 | ```html
101 | <!DOCTYPE html>
102 | <html lang="en">
103 | <head>
104 | <meta charset="UTF-8">
105 | <meta name="viewport" content="width=device-width, initial-scale=1.0">
106 | <title>Augment Code Hero Recreation</title>
107 | <style>
108 | @import url('https://fonts.googleapis.com/css2?family=Inter:wght@300;400;500;600;700;800;900&display=swap');
109 |
110 | /* 400+ lines of professional CSS including:
111 | * - Multi-layer radial gradients
112 | * - Glass morphism effects
113 | * - Smooth animations with proper timing
114 | * - Responsive breakpoints
115 | * - Modern CSS techniques
116 | */
117 | </style>
118 | </head>
119 | <body>
120 | <!-- Complete navigation and hero section with:
121 | * - Semantic HTML structure
122 | * - Accessibility considerations
123 | * - Professional component organization
124 | * - Interactive elements
125 | -->
126 | </body>
127 | </html>
128 | ```
129 |
130 | ---
131 |
132 | ## 🚀 **Key Capabilities Demonstrated**
133 |
134 | ### **Stealth Browser MCP Superpowers:**
135 | 1. **🕵️ Undetectable Automation** - Bypassed any bot detection
136 | 2. **🎯 CDP-Level Accuracy** - Extracted every CSS property perfectly
137 | 3. **🎨 Professional Enhancement** - Improved upon the original design
138 | 4. **⚡ Lightning Speed** - Complete process under 2 minutes
139 | 5. **🧠 AI Intelligence** - No manual coding or configuration needed
140 |
141 | ### **What This Means:**
142 | - **For Developers**: Clone any UI in minutes, not hours
143 | - **For Designers**: Extract exact styling from any site
144 | - **For Businesses**: Recreate competitor interfaces perfectly
145 | - **For Everyone**: Complex web tasks become simple AI conversations
146 |
147 | ---
148 |
149 | ## 🎓 **Lessons & Insights**
150 |
151 | ### **Why This Demo Matters:**
152 | 1. **Real-world complexity** - Not a toy example, actual production site
153 | 2. **Professional output** - Generated code is deployment-ready
154 | 3. **Enhanced quality** - Recreation improved upon original
155 | 4. **Simple interface** - Complex task via basic chat prompt
156 | 5. **Impressive speed** - Entire process automated in under 2 minutes
157 |
158 | ### **Technical Innovations Showcased:**
159 | - Chrome DevTools Protocol for pixel-perfect extraction
160 | - AI-driven HTML/CSS generation with professional patterns
161 | - Responsive design enhancement beyond original
162 | - Modern web development techniques automatically applied
163 | - Production-quality code from conversational interface
164 |
165 | ---
166 |
167 | ## 💡 **Try It Yourself**
168 |
169 | ### **Step 1**: Setup Stealth Browser MCP
170 | ```bash
171 | git clone https://github.com/vibheksoni/stealth-browser-mcp.git
172 | # Follow installation instructions in main README
173 | ```
174 |
175 | ### **Step 2**: Ask Your AI Agent
176 | ```
177 | hey spawn a browser and clone the hero of the site https://www.augmentcode.com/
178 | ```
179 |
180 | ### **Step 3**: Watch the Magic Happen
181 | Your AI will automatically:
182 | - Spawn browser → Navigate → Analyze → Extract → Generate → Enhance
183 |
184 | ### **Step 4**: Get Professional Results
185 | Perfect HTML/CSS recreation ready for production use!
186 |
187 | ---
188 |
189 | ## 🎯 **Impact & Recognition**
190 |
191 | This demo showcases why Stealth Browser MCP is becoming the go-to tool for:
192 | - **UI/UX professionals** cloning interfaces
193 | - **Developers** reverse-engineering sites
194 | - **Businesses** analyzing competitors
195 | - **Researchers** studying web technologies
196 | - **Anyone** who needs pixel-perfect web cloning
197 |
198 | **🌟 The future of web automation is conversational, intelligent, and undetectable.**
```
--------------------------------------------------------------------------------
/src/platform_utils.py:
--------------------------------------------------------------------------------
```python
1 | """Platform-specific utility functions for browser automation."""
2 |
3 | import ctypes
4 | import os
5 | import platform
6 | import subprocess
7 | import sys
8 | from typing import List, Optional
9 |
10 |
11 | def is_running_as_root() -> bool:
12 | """
13 | Check if the current process is running with elevated privileges.
14 |
15 | Returns:
16 | bool: True if running as root (Linux/macOS) or administrator (Windows)
17 | """
18 | system = platform.system().lower()
19 |
20 | if system in ('linux', 'darwin'): # Linux or macOS
21 | try:
22 | return os.getuid() == 0
23 | except AttributeError:
24 | return False
25 | elif system == 'windows':
26 | try:
27 | return ctypes.windll.shell32.IsUserAnAdmin() != 0
28 | except (AttributeError, OSError):
29 | return False
30 | else:
31 | return False
32 |
33 |
34 | def is_running_in_container() -> bool:
35 | """
36 | Check if the process is running inside a container (Docker, etc.).
37 |
38 | Returns:
39 | bool: True if likely running in a container
40 | """
41 | container_indicators = [
42 | os.path.exists('/.dockerenv'),
43 | os.path.exists('/proc/1/cgroup') and 'docker' in open('/proc/1/cgroup', 'r').read(),
44 | os.environ.get('container') is not None,
45 | os.environ.get('KUBERNETES_SERVICE_HOST') is not None,
46 | ]
47 |
48 | return any(container_indicators)
49 |
50 |
51 | def get_required_sandbox_args() -> List[str]:
52 | """
53 | Get the required browser arguments for sandbox handling based on current environment.
54 |
55 | Returns:
56 | List[str]: List of browser arguments needed for current environment
57 | """
58 | args = []
59 |
60 | if is_running_as_root():
61 | args.extend([
62 | '--no-sandbox',
63 | '--disable-setuid-sandbox'
64 | ])
65 |
66 | if is_running_in_container():
67 | args.extend([
68 | '--no-sandbox',
69 | '--disable-setuid-sandbox',
70 | '--disable-dev-shm-usage',
71 | '--disable-gpu',
72 | '--single-process',
73 | ])
74 |
75 | seen = set()
76 | unique_args = []
77 | for arg in args:
78 | if arg not in seen:
79 | seen.add(arg)
80 | unique_args.append(arg)
81 |
82 | return unique_args
83 |
84 |
85 | def merge_browser_args(user_args: Optional[List[str]] = None) -> List[str]:
86 | """
87 | Merge user-provided browser arguments with platform-specific required arguments.
88 |
89 | Args:
90 | user_args: User-provided browser arguments
91 |
92 | Returns:
93 | List[str]: Combined list of browser arguments
94 | """
95 | user_args = user_args or []
96 | required_args = get_required_sandbox_args()
97 |
98 | combined_args = list(user_args)
99 |
100 | for arg in required_args:
101 | if arg not in combined_args:
102 | combined_args.append(arg)
103 |
104 | return combined_args
105 |
106 |
107 | def get_platform_info() -> dict:
108 | """
109 | Get comprehensive platform information for debugging.
110 |
111 | Returns:
112 | dict: Platform information including OS, architecture, privileges, etc.
113 | """
114 | return {
115 | 'system': platform.system(),
116 | 'release': platform.release(),
117 | 'version': platform.version(),
118 | 'machine': platform.machine(),
119 | 'processor': platform.processor(),
120 | 'architecture': platform.architecture(),
121 | 'python_version': sys.version,
122 | 'is_root': is_running_as_root(),
123 | 'is_container': is_running_in_container(),
124 | 'required_sandbox_args': get_required_sandbox_args(),
125 | 'user_id': getattr(os, 'getuid', lambda: 'N/A')(),
126 | 'effective_user_id': getattr(os, 'geteuid', lambda: 'N/A')(),
127 | 'environment_vars': {
128 | 'DISPLAY': os.environ.get('DISPLAY'),
129 | 'container': os.environ.get('container'),
130 | 'KUBERNETES_SERVICE_HOST': os.environ.get('KUBERNETES_SERVICE_HOST'),
131 | 'USER': os.environ.get('USER'),
132 | 'USERNAME': os.environ.get('USERNAME'),
133 | }
134 | }
135 |
136 |
137 | def check_chrome_executable() -> Optional[str]:
138 | """
139 | Find the Chrome/Chromium executable on the system.
140 |
141 | Returns:
142 | Optional[str]: Path to Chrome executable or None if not found
143 | """
144 | system = platform.system().lower()
145 |
146 | if system == 'windows':
147 | possible_paths = [
148 | r'C:\Program Files\Google\Chrome\Application\chrome.exe',
149 | r'C:\Program Files (x86)\Google\Chrome\Application\chrome.exe',
150 | r'C:\Users\{}\AppData\Local\Google\Chrome\Application\chrome.exe'.format(os.environ.get('USERNAME', '')),
151 | r'C:\Program Files\Chromium\Application\chromium.exe',
152 | ]
153 | elif system == 'darwin':
154 | possible_paths = [
155 | '/Applications/Google Chrome.app/Contents/MacOS/Google Chrome',
156 | '/Applications/Chromium.app/Contents/MacOS/Chromium',
157 | ]
158 | else:
159 | possible_paths = [
160 | '/usr/bin/google-chrome',
161 | '/usr/bin/google-chrome-stable',
162 | '/usr/bin/chromium',
163 | '/usr/bin/chromium-browser',
164 | '/snap/bin/chromium',
165 | '/usr/local/bin/chrome',
166 | ]
167 |
168 | for path in possible_paths:
169 | if os.path.isfile(path) and os.access(path, os.X_OK):
170 | return path
171 |
172 | chrome_names = ['google-chrome', 'google-chrome-stable', 'chromium', 'chromium-browser', 'chrome']
173 | for name in chrome_names:
174 | try:
175 | result = subprocess.run(['which', name], capture_output=True, text=True)
176 | if result.returncode == 0 and result.stdout.strip():
177 | return result.stdout.strip()
178 | except (subprocess.SubprocessError, FileNotFoundError):
179 | continue
180 |
181 | return None
182 |
183 |
184 | def validate_browser_environment() -> dict:
185 | """
186 | Validate the browser environment and return status information.
187 |
188 | Returns:
189 | dict: Environment validation results
190 | """
191 | chrome_path = check_chrome_executable()
192 | platform_info = get_platform_info()
193 |
194 | issues = []
195 | warnings = []
196 |
197 | if not chrome_path:
198 | issues.append("Chrome/Chromium executable not found")
199 |
200 | if platform_info['is_root']:
201 | warnings.append("Running as root/administrator - sandbox will be disabled")
202 |
203 | if platform_info['is_container']:
204 | warnings.append("Running in container - additional arguments will be added")
205 |
206 | if platform_info['system'] not in ['Windows', 'Linux', 'Darwin']:
207 | warnings.append(f"Untested platform: {platform_info['system']}")
208 |
209 | return {
210 | 'chrome_executable': chrome_path,
211 | 'platform_info': platform_info,
212 | 'issues': issues,
213 | 'warnings': warnings,
214 | 'is_ready': len(issues) == 0,
215 | 'recommended_args': get_required_sandbox_args(),
216 | }
```
--------------------------------------------------------------------------------
/src/response_stage_hooks.py:
--------------------------------------------------------------------------------
```python
1 | """
2 | Response Stage Hook Processing - Extension for Dynamic Hook System
3 |
4 | This module adds response-stage interception and modification capabilities
5 | to the existing dynamic hook system. It allows AI-generated functions to
6 | modify response content, headers, and status codes.
7 | """
8 |
9 | import asyncio
10 | from typing import Dict, Any, Optional
11 | import nodriver as uc
12 | from debug_logger import debug_logger
13 | from dynamic_hook_system import HookAction, RequestInfo
14 |
15 |
16 | class ResponseStageProcessor:
17 | """Handles response-stage hook processing with body modification."""
18 |
19 | def __init__(self, dynamic_hook_system):
20 | self.dynamic_hook_system = dynamic_hook_system
21 |
22 | async def execute_response_action(self, tab, request: RequestInfo, action: HookAction, event) -> None:
23 | """Execute a response-stage hook action."""
24 | try:
25 | request_id = uc.cdp.fetch.RequestId(request.request_id)
26 |
27 | if action.action == "block":
28 | # Block at response stage means fail the request
29 | await tab.send(uc.cdp.fetch.fail_request(
30 | request_id=request_id,
31 | error_reason=uc.cdp.network.ErrorReason.BLOCKED_BY_CLIENT
32 | ))
33 | debug_logger.log_info("response_stage", "execute_response_action", f"Blocked response for {request.url}")
34 |
35 | elif action.action == "fulfill":
36 | # Custom response - override the server response
37 | headers = []
38 | if action.headers:
39 | for name, value in action.headers.items():
40 | headers.append(uc.cdp.fetch.HeaderEntry(name=name, value=value))
41 |
42 | await tab.send(uc.cdp.fetch.fulfill_request(
43 | request_id=request_id,
44 | response_code=action.status_code or 200,
45 | response_headers=headers,
46 | body=action.body or ""
47 | ))
48 | debug_logger.log_info("response_stage", "execute_response_action", f"Fulfilled response for {request.url} with custom content")
49 |
50 | elif action.action == "modify":
51 | # Modify response headers and/or status code
52 | response_headers = []
53 | if action.headers:
54 | for name, value in action.headers.items():
55 | response_headers.append(uc.cdp.fetch.HeaderEntry(name=name, value=value))
56 |
57 | await tab.send(uc.cdp.fetch.continue_response(
58 | request_id=request_id,
59 | response_code=action.status_code,
60 | response_headers=response_headers if response_headers else None
61 | ))
62 | debug_logger.log_info("response_stage", "execute_response_action", f"Modified response headers/status for {request.url}")
63 |
64 | else:
65 | # Continue response normally
66 | await tab.send(uc.cdp.fetch.continue_response(request_id=request_id))
67 | debug_logger.log_info("response_stage", "execute_response_action", f"Continued response normally for {request.url}")
68 |
69 | except Exception as e:
70 | debug_logger.log_error("response_stage", "execute_response_action", f"Error executing response action: {e}")
71 | # Continue response on error
72 | try:
73 | await tab.send(uc.cdp.fetch.continue_response(request_id=uc.cdp.fetch.RequestId(request.request_id)))
74 | except:
75 | pass
76 |
77 | async def execute_request_action(self, tab, request: RequestInfo, action: HookAction) -> None:
78 | """Execute a request-stage hook action."""
79 | try:
80 | request_id = uc.cdp.fetch.RequestId(request.request_id)
81 |
82 | if action.action == "block":
83 | await tab.send(uc.cdp.fetch.fail_request(
84 | request_id=request_id,
85 | error_reason=uc.cdp.network.ErrorReason.BLOCKED_BY_CLIENT
86 | ))
87 | debug_logger.log_info("response_stage", "execute_request_action", f"Blocked request {request.url}")
88 |
89 | elif action.action == "redirect":
90 | await tab.send(uc.cdp.fetch.continue_request(
91 | request_id=request_id,
92 | url=action.url
93 | ))
94 | debug_logger.log_info("response_stage", "execute_request_action", f"Redirected {request.url} to {action.url}")
95 |
96 | elif action.action == "fulfill":
97 | # Custom response at request stage
98 | headers = []
99 | if action.headers:
100 | for name, value in action.headers.items():
101 | headers.append(uc.cdp.fetch.HeaderEntry(name=name, value=value))
102 |
103 | await tab.send(uc.cdp.fetch.fulfill_request(
104 | request_id=request_id,
105 | response_code=action.status_code or 200,
106 | response_headers=headers,
107 | body=action.body or ""
108 | ))
109 | debug_logger.log_info("response_stage", "execute_request_action", f"Fulfilled request {request.url}")
110 |
111 | elif action.action == "modify":
112 | # Modify request parameters
113 | headers = []
114 | if action.headers:
115 | for name, value in action.headers.items():
116 | headers.append(uc.cdp.fetch.HeaderEntry(name=name, value=value))
117 |
118 | await tab.send(uc.cdp.fetch.continue_request(
119 | request_id=request_id,
120 | url=action.url or request.url,
121 | method=action.method or request.method,
122 | headers=headers if headers else None,
123 | post_data=action.post_data
124 | ))
125 | debug_logger.log_info("response_stage", "execute_request_action", f"Modified request {request.url}")
126 |
127 | else:
128 | # Continue request normally
129 | await tab.send(uc.cdp.fetch.continue_request(request_id=request_id))
130 | debug_logger.log_info("response_stage", "execute_request_action", f"Continued request {request.url}")
131 |
132 | except Exception as e:
133 | debug_logger.log_error("response_stage", "execute_request_action", f"Error executing request action: {e}")
134 | # Continue request on error
135 | try:
136 | await tab.send(uc.cdp.fetch.continue_request(request_id=uc.cdp.fetch.RequestId(request.request_id)))
137 | except:
138 | pass
139 |
140 |
141 | # Create global instance
142 | response_stage_processor = ResponseStageProcessor(None) # Will be set by dynamic_hook_system
```
--------------------------------------------------------------------------------
/src/models.py:
--------------------------------------------------------------------------------
```python
1 | """Data models for browser MCP server."""
2 |
3 | from typing import Optional, List, Dict, Any
4 | from datetime import datetime
5 | from pydantic import BaseModel, Field
6 | from enum import Enum
7 |
8 |
9 | class BrowserState(str, Enum):
10 | """Browser instance states."""
11 | STARTING = "starting"
12 | READY = "ready"
13 | NAVIGATING = "navigating"
14 | ERROR = "error"
15 | CLOSED = "closed"
16 |
17 |
18 | class BrowserInstance(BaseModel):
19 | """Represents a browser instance."""
20 | instance_id: str = Field(description="Unique identifier for the browser instance")
21 | state: BrowserState = Field(default=BrowserState.STARTING)
22 | current_url: Optional[str] = Field(default=None, description="Current page URL")
23 | title: Optional[str] = Field(default=None, description="Current page title")
24 | created_at: datetime = Field(default_factory=datetime.now)
25 | last_activity: datetime = Field(default_factory=datetime.now)
26 | headless: bool = Field(default=False)
27 | user_agent: Optional[str] = None
28 | viewport: Dict[str, int] = Field(default_factory=lambda: {"width": 1920, "height": 1080})
29 |
30 | def update_activity(self):
31 | """Update last activity timestamp."""
32 | self.last_activity = datetime.now()
33 |
34 |
35 | class NetworkRequest(BaseModel):
36 | """Represents a captured network request."""
37 | request_id: str = Field(description="Unique request identifier")
38 | instance_id: str = Field(description="Browser instance that made the request")
39 | url: str = Field(description="Request URL")
40 | method: str = Field(description="HTTP method")
41 | headers: Dict[str, str] = Field(default_factory=dict)
42 | cookies: Dict[str, str] = Field(default_factory=dict)
43 | post_data: Optional[str] = None
44 | timestamp: datetime = Field(default_factory=datetime.now)
45 | resource_type: Optional[str] = None
46 |
47 |
48 | class NetworkResponse(BaseModel):
49 | """Represents a captured network response."""
50 | request_id: str = Field(description="Associated request ID")
51 | status: int = Field(description="HTTP status code")
52 | headers: Dict[str, str] = Field(default_factory=dict)
53 | content_length: Optional[int] = None
54 | content_type: Optional[str] = None
55 | body: Optional[bytes] = None
56 | timestamp: datetime = Field(default_factory=datetime.now)
57 |
58 |
59 | class ElementInfo(BaseModel):
60 | """Information about a DOM element."""
61 | selector: str = Field(description="CSS selector or XPath")
62 | tag_name: str = Field(description="HTML tag name")
63 | text: Optional[str] = Field(default=None, description="Element text content")
64 | attributes: Dict[str, str] = Field(default_factory=dict)
65 | is_visible: bool = Field(default=True)
66 | is_clickable: bool = Field(default=False)
67 | bounding_box: Optional[Dict[str, float]] = None
68 | children_count: int = Field(default=0)
69 |
70 |
71 | class PageState(BaseModel):
72 | """Complete state snapshot of a page."""
73 | instance_id: str
74 | url: str
75 | title: str
76 | ready_state: str = Field(description="Document ready state")
77 | cookies: List[Dict[str, Any]] = Field(default_factory=list)
78 | local_storage: Dict[str, str] = Field(default_factory=dict)
79 | session_storage: Dict[str, str] = Field(default_factory=dict)
80 | console_logs: List[Dict[str, Any]] = Field(default_factory=list)
81 | viewport: Dict[str, int] = Field(default_factory=dict)
82 | timestamp: datetime = Field(default_factory=datetime.now)
83 |
84 |
85 | class BrowserOptions(BaseModel):
86 | """Options for spawning a new browser instance."""
87 | headless: bool = Field(default=False, description="Run browser in headless mode")
88 | user_agent: Optional[str] = Field(default=None, description="Custom user agent string")
89 | viewport_width: int = Field(default=1920, description="Viewport width in pixels")
90 | viewport_height: int = Field(default=1080, description="Viewport height in pixels")
91 | proxy: Optional[str] = Field(default=None, description="Proxy server URL")
92 | block_resources: List[str] = Field(default_factory=list, description="Resource types to block")
93 | extra_headers: Dict[str, str] = Field(default_factory=dict, description="Extra HTTP headers")
94 | user_data_dir: Optional[str] = Field(default=None, description="Path to user data directory")
95 | sandbox: bool = Field(default=True, description="Enable browser sandbox mode")
96 |
97 |
98 | class NavigationOptions(BaseModel):
99 | """Options for page navigation."""
100 | wait_until: str = Field(default="load", description="Wait condition: load, domcontentloaded, networkidle")
101 | timeout: int = Field(default=30000, description="Navigation timeout in milliseconds")
102 | referrer: Optional[str] = Field(default=None, description="Referrer URL")
103 |
104 |
105 | class ScriptResult(BaseModel):
106 | """Result from script execution."""
107 | success: bool
108 | result: Any = None
109 | error: Optional[str] = None
110 | execution_time: float = Field(description="Execution time in milliseconds")
111 |
112 |
113 | class ElementAction(str, Enum):
114 | """Types of element actions."""
115 | CLICK = "click"
116 | TYPE = "type"
117 | SELECT = "select"
118 | HOVER = "hover"
119 | FOCUS = "focus"
120 | CLEAR = "clear"
121 | SCREENSHOT = "screenshot"
122 |
123 |
124 | class HookAction(str, Enum):
125 | """Types of network hook actions."""
126 | MODIFY = "modify"
127 | BLOCK = "block"
128 | REDIRECT = "redirect"
129 | FULFILL = "fulfill"
130 | LOG = "log"
131 |
132 |
133 | class HookStage(str, Enum):
134 | """Stages at which hooks can intercept."""
135 | REQUEST = "request"
136 | RESPONSE = "response"
137 |
138 |
139 | class HookStatus(str, Enum):
140 | """Status of a hook."""
141 | ACTIVE = "active"
142 | INACTIVE = "inactive"
143 | PAUSED = "paused"
144 |
145 |
146 | class NetworkHook(BaseModel):
147 | """Represents a network hook rule."""
148 | hook_id: str = Field(description="Unique hook identifier")
149 | name: str = Field(description="Human-readable hook name")
150 | url_pattern: str = Field(description="URL pattern to match (supports wildcards)")
151 | resource_type: Optional[str] = Field(default=None, description="Resource type filter")
152 | stage: HookStage = Field(description="When to intercept (request/response)")
153 | action: HookAction = Field(description="What to do with matched requests")
154 | status: HookStatus = Field(default=HookStatus.ACTIVE)
155 | priority: int = Field(default=100, description="Hook priority (lower = higher priority)")
156 |
157 | modifications: Dict[str, Any] = Field(default_factory=dict, description="Modifications to apply")
158 | redirect_url: Optional[str] = Field(default=None, description="URL to redirect to")
159 | custom_response: Optional[Dict[str, Any]] = Field(default=None, description="Custom response data")
160 |
161 | created_at: datetime = Field(default_factory=datetime.now)
162 | last_triggered: Optional[datetime] = None
163 | trigger_count: int = Field(default=0, description="Number of times this hook was triggered")
164 |
165 |
166 | class PendingRequest(BaseModel):
167 | """Represents a request awaiting modification."""
168 | request_id: str = Field(description="Fetch request ID")
169 | instance_id: str = Field(description="Browser instance ID")
170 | url: str = Field(description="Original request URL")
171 | method: str = Field(description="HTTP method")
172 | headers: Dict[str, str] = Field(default_factory=dict)
173 | post_data: Optional[str] = None
174 | resource_type: Optional[str] = None
175 | stage: HookStage = Field(description="Current interception stage")
176 |
177 | matched_hooks: List[str] = Field(default_factory=list, description="IDs of hooks that matched")
178 | modifications: Dict[str, Any] = Field(default_factory=dict, description="Accumulated modifications")
179 | status: str = Field(default="pending", description="Processing status")
180 |
181 | created_at: datetime = Field(default_factory=datetime.now)
182 | expires_at: Optional[datetime] = None
183 |
184 |
185 | class RequestModification(BaseModel):
186 | """Represents modifications to apply to a request."""
187 | url: Optional[str] = None
188 | method: Optional[str] = None
189 | headers: Optional[Dict[str, str]] = None
190 | post_data: Optional[str] = None
191 | intercept_response: Optional[bool] = None
192 |
193 |
194 | class ResponseModification(BaseModel):
195 | """Represents modifications to apply to a response."""
196 | status_code: Optional[int] = None
197 | status_text: Optional[str] = None
198 | headers: Optional[Dict[str, str]] = None
199 | body: Optional[str] = None
```
--------------------------------------------------------------------------------
/src/js/comprehensive_element_extractor.js:
--------------------------------------------------------------------------------
```javascript
1 | (function() {
2 | const selector = "$SELECTOR$";
3 | const includeChildren = $INCLUDE_CHILDREN$;
4 |
5 | /**
6 | * Extracts comprehensive information from a single DOM element.
7 | * @param {Element} element - The DOM element to extract data from.
8 | * @returns {Object} An object containing:
9 | * - html: {Object} HTML details (outerHTML, innerHTML, tagName, id, className, attributes)
10 | * - styles: {Object} Computed CSS styles
11 | * - eventListeners: {Array} Event listeners detected by multiple methods
12 | * - cssRules: {Array} CSS rules matching the element
13 | * - pseudoElements: {Object} Styles and content for pseudo-elements
14 | * - animations: {Object} Animation, transition, and transform properties
15 | * - fonts: {Object} Font family, size, and weight
16 | */
17 | async function extractSingleElement(element) {
18 | const computedStyles = window.getComputedStyle(element);
19 | const styles = {};
20 | for (let i = 0; i < computedStyles.length; i++) {
21 | const prop = computedStyles[i];
22 | styles[prop] = computedStyles.getPropertyValue(prop);
23 | }
24 |
25 | const html = {
26 | outerHTML: element.outerHTML,
27 | innerHTML: element.innerHTML,
28 | tagName: element.tagName,
29 | id: element.id,
30 | className: element.className,
31 | attributes: Array.from(element.attributes).map(attr => ({
32 | name: attr.name,
33 | value: attr.value
34 | }))
35 | };
36 |
37 | const eventListeners = [];
38 |
39 | for (const attr of element.attributes) {
40 | if (attr.name.startsWith('on')) {
41 | eventListeners.push({
42 | type: attr.name.substring(2),
43 | handler: attr.value,
44 | source: 'inline'
45 | });
46 | }
47 | }
48 |
49 | if (typeof getEventListeners === 'function') {
50 | try {
51 | const listeners = getEventListeners(element);
52 | for (const eventType in listeners) {
53 | listeners[eventType].forEach(listener => {
54 | eventListeners.push({
55 | type: eventType,
56 | handler: listener.listener.toString().substring(0, 200) + '...',
57 | useCapture: listener.useCapture,
58 | passive: listener.passive,
59 | once: listener.once,
60 | source: 'addEventListener'
61 | });
62 | });
63 | }
64 | } catch (e) {}
65 | }
66 |
67 | const commonEvents = ['click', 'mousedown', 'mouseup', 'mouseover', 'mouseout', 'focus', 'blur', 'change', 'input', 'submit'];
68 | commonEvents.forEach(eventType => {
69 | if (element[`on${eventType}`] && typeof element[`on${eventType}`] === 'function') {
70 | const handler = element[`on${eventType}`].toString();
71 | if (!eventListeners.some(l => l.type === eventType && l.source === 'inline')) {
72 | eventListeners.push({
73 | type: eventType,
74 | handler: handler,
75 | handlerPreview: handler.substring(0, 100) + (handler.length > 100 ? '...' : ''),
76 | source: 'property'
77 | });
78 | }
79 | }
80 | });
81 |
82 | try {
83 | const reactKeys = Object.keys(element).filter(key => key.startsWith('__react'));
84 | if (reactKeys.length > 0) {
85 | const reactDetails = [];
86 | reactKeys.forEach(key => {
87 | try {
88 | const reactData = element[key];
89 | if (reactData && reactData.memoizedProps) {
90 | const props = reactData.memoizedProps;
91 | Object.keys(props).forEach(prop => {
92 | if (prop.startsWith('on') && typeof props[prop] === 'function') {
93 | const funcStr = props[prop].toString();
94 | reactDetails.push({
95 | event: prop.substring(2).toLowerCase(),
96 | handler: funcStr,
97 | handlerPreview: funcStr.substring(0, 100) + (funcStr.length > 100 ? '...' : '')
98 | });
99 | }
100 | });
101 | }
102 | } catch (e) {}
103 | });
104 |
105 | eventListeners.push({
106 | type: 'framework',
107 | handler: 'React event handlers detected',
108 | source: 'react',
109 | details: `Found ${reactKeys.length} React properties`,
110 | reactHandlers: reactDetails
111 | });
112 | }
113 | } catch (e) {}
114 |
115 | try {
116 | if (element._events || element.__events) {
117 | const events = element._events || element.__events;
118 | Object.keys(events).forEach(eventType => {
119 | const handlers = Array.isArray(events[eventType]) ? events[eventType] : [events[eventType]];
120 | handlers.forEach(handler => {
121 | if (typeof handler === 'function') {
122 | const funcStr = handler.toString();
123 | eventListeners.push({
124 | type: eventType,
125 | handler: funcStr,
126 | handlerPreview: funcStr.substring(0, 100) + (funcStr.length > 100 ? '...' : ''),
127 | source: 'registry'
128 | });
129 | }
130 | });
131 | });
132 | }
133 | } catch (e) {}
134 |
135 | const cssRules = [];
136 | const sheets = document.styleSheets;
137 | for (let i = 0; i < sheets.length; i++) {
138 | try {
139 | const rules = sheets[i].cssRules || sheets[i].rules;
140 | for (let j = 0; j < rules.length; j++) {
141 | const rule = rules[j];
142 | if (rule.type === 1 && element.matches(rule.selectorText)) {
143 | cssRules.push({
144 | selector: rule.selectorText,
145 | css: rule.style.cssText,
146 | source: sheets[i].href || 'inline'
147 | });
148 | }
149 | }
150 | } catch (e) {}
151 | }
152 |
153 | const pseudoElements = {};
154 | ['::before', '::after', '::first-line', '::first-letter'].forEach(pseudo => {
155 | const pseudoStyles = window.getComputedStyle(element, pseudo);
156 | const content = pseudoStyles.getPropertyValue('content');
157 | if (content && content !== 'none') {
158 | pseudoElements[pseudo] = {
159 | content: content,
160 | styles: {}
161 | };
162 | for (let i = 0; i < pseudoStyles.length; i++) {
163 | const prop = pseudoStyles[i];
164 | pseudoElements[pseudo].styles[prop] = pseudoStyles.getPropertyValue(prop);
165 | }
166 | }
167 | });
168 |
169 | const animations = {
170 | animation: styles.animation || 'none',
171 | transition: styles.transition || 'none',
172 | transform: styles.transform || 'none'
173 | };
174 |
175 | const fonts = {
176 | computed: styles.fontFamily,
177 | fontSize: styles.fontSize,
178 | fontWeight: styles.fontWeight
179 | };
180 |
181 | return {
182 | html,
183 | styles,
184 | eventListeners,
185 | cssRules,
186 | pseudoElements,
187 | animations,
188 | fonts
189 | };
190 | }
191 |
192 | /**
193 | * Calculates the depth of a child element relative to a parent element.
194 | * @param {Element} child - The child DOM element.
195 | * @param {Element} parent - The parent DOM element.
196 | * @returns {number} The depth (number of levels) between child and parent.
197 | */
198 | function getElementDepth(child, parent) {
199 | let depth = 0;
200 | let current = child;
201 | while (current && current !== parent) {
202 | depth++;
203 | current = current.parentElement;
204 | }
205 | return depth;
206 | }
207 |
208 | /**
209 | * Generates a CSS-like path from a child element to a parent element.
210 | * @param {Element} child - The child DOM element.
211 | * @param {Element} parent - The parent DOM element.
212 | * @returns {string} The path string (e.g., "div > span[1] > a").
213 | */
214 | function getElementPath(child, parent) {
215 | const path = [];
216 | let current = child;
217 | while (current && current !== parent) {
218 | const tag = current.tagName.toLowerCase();
219 | const index = Array.from(current.parentElement.children)
220 | .filter(el => el.tagName === current.tagName)
221 | .indexOf(current);
222 | path.unshift(index > 0 ? `${tag}[${index}]` : tag);
223 | current = current.parentElement;
224 | }
225 | return path.join(' > ');
226 | }
227 |
228 | const element = document.querySelector(selector);
229 | if (!element) return { error: 'Element not found' };
230 |
231 | const result = {
232 | element: null,
233 | children: []
234 | };
235 |
236 | result.element = extractSingleElement(element);
237 |
238 | if (includeChildren) {
239 | let targetElement = element;
240 | const children = element.querySelectorAll('*');
241 |
242 | if (children.length === 0 && element.parentElement) {
243 | targetElement = element.parentElement;
244 | result.extractedFrom = 'parent';
245 | result.originalElement = extractSingleElement(element);
246 | result.element = extractSingleElement(targetElement);
247 | }
248 |
249 | const allChildren = targetElement.querySelectorAll('*');
250 | for (let i = 0; i < allChildren.length; i++) {
251 | const childData = extractSingleElement(allChildren[i]);
252 | childData.depth = getElementDepth(allChildren[i], targetElement);
253 | childData.path = getElementPath(allChildren[i], targetElement);
254 | if (allChildren[i] === element) {
255 | childData.isOriginallySelected = true;
256 | }
257 | result.children.push(childData);
258 | }
259 | }
260 |
261 | return result;
262 | })();
```
--------------------------------------------------------------------------------
/src/progressive_element_cloner.py:
--------------------------------------------------------------------------------
```python
1 | """
2 | Progressive Element Cloner System
3 | =================================
4 |
5 | Stores comprehensive element clone data in memory and returns a compact handle
6 | (`element_id`) so clients can progressively expand specific portions later.
7 | """
8 |
9 | import time
10 | import uuid
11 | from typing import Any, Dict, List, Optional, Tuple
12 |
13 | from debug_logger import debug_logger
14 | from persistent_storage import persistent_storage
15 | from comprehensive_element_cloner import comprehensive_element_cloner
16 |
17 |
18 | class ProgressiveElementCloner:
19 | """Progressive element cloner with in-memory store."""
20 |
21 | def __init__(self):
22 | self.STORAGE_KEY = "progressive_elements"
23 |
24 | def _get_store(self) -> Dict[str, Dict[str, Any]]:
25 | return persistent_storage.get(self.STORAGE_KEY, {})
26 |
27 | def _save_store(self, data: Dict[str, Dict[str, Any]]) -> None:
28 | persistent_storage.set(self.STORAGE_KEY, data)
29 |
30 | async def clone_element_progressive(
31 | self,
32 | tab,
33 | selector: str,
34 | include_children: bool = True,
35 | ) -> Dict[str, Any]:
36 | try:
37 | element_id = f"elem_{uuid.uuid4().hex[:12]}"
38 | debug_logger.log_info("progressive_cloner", "clone_progressive", f"Cloning {selector} -> {element_id}")
39 |
40 | full_data = await comprehensive_element_cloner.extract_complete_element(
41 | tab, selector, include_children
42 | )
43 | if not isinstance(full_data, dict) or "error" in full_data:
44 | return {"error": "Element not found or extraction failed", "selector": selector}
45 |
46 | store = self._get_store()
47 | store[element_id] = {
48 | "full_data": full_data,
49 | "url": getattr(tab, "url", ""),
50 | "selector": selector,
51 | "timestamp": time.time(),
52 | "include_children": include_children,
53 | }
54 | self._save_store(store)
55 |
56 | base = {
57 | "tagName": full_data.get("element", {}).get("html", {}).get("tagName")
58 | or full_data.get("tagName", "unknown"),
59 | "attributes_count": len(full_data.get("element", {}).get("html", {}).get("attributes", [])),
60 | "children_count": len(full_data.get("children", [])),
61 | "summary": {
62 | "styles_count": len(full_data.get("element", {}).get("computed_styles", {}))
63 | or len(full_data.get("styles", {})),
64 | "event_listeners_count": len(full_data.get("element", {}).get("event_listeners", []))
65 | or len(full_data.get("eventListeners", [])),
66 | "css_rules_count": len(full_data.get("element", {}).get("matched_styles", {}).get("matchedCSSRules", []))
67 | if isinstance(full_data.get("element", {}).get("matched_styles"), dict)
68 | else len(full_data.get("cssRules", [])),
69 | },
70 | }
71 |
72 | return {
73 | "element_id": element_id,
74 | "base": base,
75 | "available_data": [
76 | "styles",
77 | "events",
78 | "children",
79 | "css_rules",
80 | "pseudo_elements",
81 | "animations",
82 | "fonts",
83 | "html",
84 | ],
85 | "url": getattr(tab, "url", ""),
86 | "selector": selector,
87 | "timestamp": time.time(),
88 | }
89 | except Exception as e:
90 | debug_logger.log_error("progressive_cloner", "clone_progressive", e)
91 | return {"error": str(e)}
92 |
93 | def expand_styles(
94 | self, element_id: str, categories: Optional[List[str]] = None, properties: Optional[List[str]] = None
95 | ) -> Dict[str, Any]:
96 | store = self._get_store()
97 | if element_id not in store:
98 | return {"error": f"Element {element_id} not found"}
99 | data = store[element_id]["full_data"]
100 | styles = (
101 | data.get("element", {}).get("computed_styles", {})
102 | if isinstance(data.get("element", {}).get("computed_styles"), dict)
103 | else data.get("styles", {})
104 | )
105 | if properties:
106 | filtered = {k: v for k, v in styles.items() if k in properties}
107 | elif categories:
108 | category_map = {
109 | "layout": [
110 | "display",
111 | "position",
112 | "width",
113 | "height",
114 | "max-width",
115 | "max-height",
116 | "min-width",
117 | "min-height",
118 | ],
119 | "typography": [
120 | "font-family",
121 | "font-size",
122 | "font-weight",
123 | "font-style",
124 | "line-height",
125 | "text-align",
126 | ],
127 | "colors": ["color", "background-color", "border-color"],
128 | }
129 | keys = set(k for c in categories for k in category_map.get(c, []))
130 | filtered = {k: v for k, v in styles.items() if k in keys}
131 | else:
132 | filtered = styles
133 | return {
134 | "element_id": element_id,
135 | "data_type": "styles",
136 | "styles": filtered,
137 | "total_available": len(styles),
138 | "returned_count": len(filtered),
139 | }
140 |
141 | def expand_events(self, element_id: str, event_types: Optional[List[str]] = None) -> Dict[str, Any]:
142 | store = self._get_store()
143 | if element_id not in store:
144 | return {"error": f"Element {element_id} not found"}
145 | data = store[element_id]["full_data"]
146 | events = data.get("eventListeners", []) or data.get("element", {}).get("event_listeners", [])
147 | if event_types:
148 | events = [e for e in events if e.get("type") in event_types or e.get("source") in event_types]
149 | return {
150 | "element_id": element_id,
151 | "data_type": "events",
152 | "event_listeners": events,
153 | "total_available": len(events),
154 | "returned_count": len(events),
155 | }
156 |
157 | def expand_children(
158 | self, element_id: str, depth_range: Optional[Tuple[int, int]] = None, max_count: Optional[int] = None
159 | ) -> Dict[str, Any]:
160 | store = self._get_store()
161 | if element_id not in store:
162 | return {"error": f"Element {element_id} not found"}
163 | data = store[element_id]["full_data"]
164 | children = data.get("children", [])
165 |
166 | # Ensure children is a list that can be sliced
167 | if not isinstance(children, list):
168 | children = list(children) if hasattr(children, '__iter__') else []
169 |
170 | if depth_range:
171 | min_d, max_d = depth_range
172 | children = [c for c in children if isinstance(c, dict) and min_d <= c.get("depth", 0) <= max_d]
173 |
174 | if isinstance(max_count, int) and max_count > 0:
175 | try:
176 | children = children[:max_count]
177 | except (TypeError, AttributeError) as e:
178 | debug_logger.log_error("progressive_cloner", "expand_children", f"Slicing error: {e}, children type: {type(children)}")
179 | children = []
180 | return {
181 | "element_id": element_id,
182 | "data_type": "children",
183 | "children": children,
184 | "total_available": len(data.get("children", [])),
185 | "returned_count": len(children),
186 | }
187 |
188 | def expand_css_rules(self, element_id: str, source_types: Optional[List[str]] = None) -> Dict[str, Any]:
189 | store = self._get_store()
190 | if element_id not in store:
191 | return {"error": f"Element {element_id} not found"}
192 | data = store[element_id]["full_data"]
193 | rules = data.get("cssRules", [])
194 | if source_types:
195 | rules = [r for r in rules if any(s in r.get("source", "") for s in source_types)]
196 | return {
197 | "element_id": element_id,
198 | "data_type": "css_rules",
199 | "css_rules": rules,
200 | "total_available": len(data.get("cssRules", [])),
201 | "returned_count": len(rules),
202 | }
203 |
204 | def expand_pseudo_elements(self, element_id: str) -> Dict[str, Any]:
205 | store = self._get_store()
206 | if element_id not in store:
207 | return {"error": f"Element {element_id} not found"}
208 | data = store[element_id]["full_data"]
209 | pseudos = data.get("pseudoElements", {})
210 | return {
211 | "element_id": element_id,
212 | "data_type": "pseudo_elements",
213 | "pseudo_elements": pseudos,
214 | "available_pseudos": list(pseudos.keys()),
215 | }
216 |
217 | def expand_animations(self, element_id: str) -> Dict[str, Any]:
218 | store = self._get_store()
219 | if element_id not in store:
220 | return {"error": f"Element {element_id} not found"}
221 | data = store[element_id]["full_data"]
222 | animations = data.get("animations", {})
223 | fonts = data.get("fonts", {})
224 | return {
225 | "element_id": element_id,
226 | "data_type": "animations",
227 | "animations": animations,
228 | "fonts": fonts,
229 | }
230 |
231 | def list_stored_elements(self) -> Dict[str, Any]:
232 | store = self._get_store()
233 | items = []
234 | for element_id, meta in store.items():
235 | fd = meta.get("full_data", {})
236 | items.append(
237 | {
238 | "element_id": element_id,
239 | "selector": meta.get("selector"),
240 | "url": meta.get("url"),
241 | "tagName": fd.get("tagName") or fd.get("element", {}).get("html", {}).get("tagName", "unknown"),
242 | "children_count": len(fd.get("children", [])),
243 | "styles_count": len(fd.get("styles", {}))
244 | or len(fd.get("element", {}).get("computed_styles", {})),
245 | "timestamp": meta.get("timestamp"),
246 | }
247 | )
248 | return {"stored_elements": items, "total_count": len(items)}
249 |
250 | def clear_stored_element(self, element_id: str) -> Dict[str, Any]:
251 | store = self._get_store()
252 | if element_id in store:
253 | del store[element_id]
254 | self._save_store(store)
255 | return {"success": True, "message": f"Element {element_id} cleared"}
256 | return {"error": f"Element {element_id} not found"}
257 |
258 | def clear_all_elements(self) -> Dict[str, Any]:
259 | self._save_store({})
260 | return {"success": True, "message": "All stored elements cleared"}
261 |
262 |
263 | progressive_element_cloner = ProgressiveElementCloner()
264 |
265 |
266 |
```
--------------------------------------------------------------------------------
/src/process_cleanup.py:
--------------------------------------------------------------------------------
```python
1 | """Robust process cleanup system for browser instances."""
2 |
3 | import atexit
4 | import json
5 | import os
6 | import signal
7 | import sys
8 | import time
9 | from pathlib import Path
10 | from typing import Dict, List, Set
11 | import psutil
12 | from debug_logger import debug_logger
13 |
14 |
15 | class ProcessCleanup:
16 | """Manages browser process tracking and cleanup."""
17 |
18 | def __init__(self):
19 | self.pid_file = Path(os.path.expanduser("~/.stealth_browser_pids.json"))
20 | self.tracked_pids: Set[int] = set()
21 | self.browser_processes: Dict[str, int] = {}
22 | self._setup_cleanup_handlers()
23 | self._recover_orphaned_processes()
24 |
25 | def _setup_cleanup_handlers(self):
26 | """Setup signal handlers and atexit cleanup."""
27 | atexit.register(self._cleanup_all_tracked)
28 |
29 | if hasattr(signal, 'SIGTERM'):
30 | signal.signal(signal.SIGTERM, self._signal_handler)
31 | if hasattr(signal, 'SIGINT'):
32 | signal.signal(signal.SIGINT, self._signal_handler)
33 |
34 | if sys.platform == "win32":
35 | if hasattr(signal, 'SIGBREAK'):
36 | signal.signal(signal.SIGBREAK, self._signal_handler)
37 |
38 | def _signal_handler(self, signum, frame):
39 | """Handle termination signals."""
40 | debug_logger.log_info("process_cleanup", "signal_handler", f"Received signal {signum}, initiating cleanup...")
41 | self._cleanup_all_tracked()
42 | sys.exit(0)
43 |
44 | def _load_tracked_pids(self) -> Dict[str, int]:
45 | """Load tracked PIDs from disk."""
46 | try:
47 | if self.pid_file.exists():
48 | with open(self.pid_file, 'r') as f:
49 | data = json.load(f)
50 | return data.get('browser_processes', {})
51 | except Exception as e:
52 | debug_logger.log_warning("process_cleanup", "load_pids", f"Failed to load PID file: {e}")
53 | return {}
54 |
55 | def _save_tracked_pids(self):
56 | """Save tracked PIDs to disk."""
57 | try:
58 | data = {
59 | 'browser_processes': self.browser_processes,
60 | 'timestamp': time.time()
61 | }
62 | with open(self.pid_file, 'w') as f:
63 | json.dump(data, f)
64 | except Exception as e:
65 | debug_logger.log_warning("process_cleanup", "save_pids", f"Failed to save PID file: {e}")
66 |
67 | def _recover_orphaned_processes(self):
68 | """Kill any orphaned browser processes from previous runs."""
69 | saved_processes = self._load_tracked_pids()
70 | killed_count = 0
71 |
72 | for instance_id, pid in saved_processes.items():
73 | if self._kill_process_by_pid(pid, instance_id):
74 | killed_count += 1
75 |
76 | if killed_count > 0:
77 | debug_logger.log_info("process_cleanup", "recovery", f"Killed {killed_count} orphaned browser processes")
78 |
79 | self._clear_pid_file()
80 |
81 | def track_browser_process(self, instance_id: str, browser_process) -> bool:
82 | """Track a browser process for cleanup.
83 |
84 | Args:
85 | instance_id: Browser instance identifier
86 | browser_process: Browser process object with .pid attribute
87 |
88 | Returns:
89 | bool: True if tracking was successful
90 | """
91 | try:
92 | if hasattr(browser_process, 'pid') and browser_process.pid:
93 | pid = browser_process.pid
94 | self.browser_processes[instance_id] = pid
95 | self.tracked_pids.add(pid)
96 | self._save_tracked_pids()
97 |
98 | debug_logger.log_info("process_cleanup", "track_process",
99 | f"Tracking browser process {pid} for instance {instance_id}")
100 | return True
101 | else:
102 | debug_logger.log_warning("process_cleanup", "track_process",
103 | f"Browser process for {instance_id} has no PID")
104 | return False
105 |
106 | except Exception as e:
107 | debug_logger.log_error("process_cleanup", "track_process",
108 | f"Failed to track process for {instance_id}: {e}")
109 | return False
110 |
111 | def untrack_browser_process(self, instance_id: str) -> bool:
112 | """Stop tracking a browser process.
113 |
114 | Args:
115 | instance_id: Browser instance identifier
116 |
117 | Returns:
118 | bool: True if untracking was successful
119 | """
120 | try:
121 | if instance_id in self.browser_processes:
122 | pid = self.browser_processes[instance_id]
123 | self.tracked_pids.discard(pid)
124 | del self.browser_processes[instance_id]
125 | self._save_tracked_pids()
126 |
127 | debug_logger.log_info("process_cleanup", "untrack_process",
128 | f"Stopped tracking process {pid} for instance {instance_id}")
129 | return True
130 | return False
131 |
132 | except Exception as e:
133 | debug_logger.log_error("process_cleanup", "untrack_process",
134 | f"Failed to untrack process for {instance_id}: {e}")
135 | return False
136 |
137 | def kill_browser_process(self, instance_id: str) -> bool:
138 | """Kill a specific browser process.
139 |
140 | Args:
141 | instance_id: Browser instance identifier
142 |
143 | Returns:
144 | bool: True if process was killed successfully
145 | """
146 | if instance_id not in self.browser_processes:
147 | return False
148 |
149 | pid = self.browser_processes[instance_id]
150 | success = self._kill_process_by_pid(pid, instance_id)
151 |
152 | if success:
153 | self.untrack_browser_process(instance_id)
154 |
155 | return success
156 |
157 | def _kill_process_by_pid(self, pid: int, instance_id: str = "unknown") -> bool:
158 | """Kill a process by PID using multiple methods.
159 |
160 | Args:
161 | pid: Process ID to kill
162 | instance_id: Instance identifier for logging
163 |
164 | Returns:
165 | bool: True if process was killed successfully
166 | """
167 | try:
168 | if not psutil.pid_exists(pid):
169 | debug_logger.log_info("process_cleanup", "kill_process",
170 | f"Process {pid} for {instance_id} already terminated")
171 | return True
172 |
173 | try:
174 | proc = psutil.Process(pid)
175 | proc_name = proc.name()
176 |
177 | if not any(name in proc_name.lower() for name in ['chrome', 'chromium', 'msedge']):
178 | debug_logger.log_warning("process_cleanup", "kill_process",
179 | f"PID {pid} is not a browser process ({proc_name}), skipping")
180 | return False
181 |
182 | except psutil.NoSuchProcess:
183 | debug_logger.log_info("process_cleanup", "kill_process",
184 | f"Process {pid} for {instance_id} no longer exists")
185 | return True
186 | except Exception as e:
187 | debug_logger.log_warning("process_cleanup", "kill_process",
188 | f"Could not verify process {pid}: {e}")
189 |
190 | try:
191 | proc = psutil.Process(pid)
192 | proc.terminate()
193 |
194 | try:
195 | proc.wait(timeout=3)
196 | debug_logger.log_info("process_cleanup", "kill_process",
197 | f"Process {pid} for {instance_id} terminated gracefully")
198 | return True
199 | except psutil.TimeoutExpired:
200 | pass
201 |
202 | except psutil.NoSuchProcess:
203 | return True
204 | except Exception as e:
205 | debug_logger.log_warning("process_cleanup", "kill_process",
206 | f"Failed to terminate process {pid} gracefully: {e}")
207 |
208 | try:
209 | proc = psutil.Process(pid)
210 | proc.kill()
211 |
212 | try:
213 | proc.wait(timeout=2)
214 | debug_logger.log_info("process_cleanup", "kill_process",
215 | f"Process {pid} for {instance_id} force killed")
216 | return True
217 | except psutil.TimeoutExpired:
218 | debug_logger.log_error("process_cleanup", "kill_process",
219 | f"Process {pid} for {instance_id} did not die after force kill")
220 | return False
221 |
222 | except psutil.NoSuchProcess:
223 | return True
224 | except Exception as e:
225 | debug_logger.log_error("process_cleanup", "kill_process",
226 | f"Failed to force kill process {pid}: {e}")
227 | return False
228 |
229 | except Exception as e:
230 | debug_logger.log_error("process_cleanup", "kill_process",
231 | f"Failed to kill process {pid} for {instance_id}: {e}")
232 | return False
233 |
234 | def _cleanup_all_tracked(self):
235 | """Clean up all tracked browser processes."""
236 | if not self.browser_processes:
237 | debug_logger.log_info("process_cleanup", "cleanup_all", "No browser processes to clean up")
238 | return
239 |
240 | debug_logger.log_info("process_cleanup", "cleanup_all",
241 | f"Cleaning up {len(self.browser_processes)} browser processes...")
242 |
243 | killed_count = 0
244 | for instance_id, pid in list(self.browser_processes.items()):
245 | if self._kill_process_by_pid(pid, instance_id):
246 | killed_count += 1
247 |
248 | debug_logger.log_info("process_cleanup", "cleanup_all",
249 | f"Cleaned up {killed_count}/{len(self.browser_processes)} browser processes")
250 |
251 | self.browser_processes.clear()
252 | self.tracked_pids.clear()
253 | self._clear_pid_file()
254 |
255 | def _clear_pid_file(self):
256 | """Clear the PID tracking file."""
257 | try:
258 | if self.pid_file.exists():
259 | self.pid_file.unlink()
260 | except Exception as e:
261 | debug_logger.log_warning("process_cleanup", "clear_pid_file", f"Failed to clear PID file: {e}")
262 |
263 | def get_tracked_processes(self) -> Dict[str, int]:
264 | """Get currently tracked processes.
265 |
266 | Returns:
267 | Dict mapping instance_id to PID
268 | """
269 | return self.browser_processes.copy()
270 |
271 | def is_process_alive(self, instance_id: str) -> bool:
272 | """Check if a tracked process is still alive.
273 |
274 | Args:
275 | instance_id: Browser instance identifier
276 |
277 | Returns:
278 | bool: True if process is alive
279 | """
280 | if instance_id not in self.browser_processes:
281 | return False
282 |
283 | pid = self.browser_processes[instance_id]
284 | return psutil.pid_exists(pid)
285 |
286 |
287 | process_cleanup = ProcessCleanup()
```
--------------------------------------------------------------------------------
/src/dynamic_hook_ai_interface.py:
--------------------------------------------------------------------------------
```python
1 | """
2 | Dynamic Hook AI Interface - Functions for AI to create and manage dynamic hooks
3 |
4 | This module provides AI-friendly functions for creating, managing, and learning
5 | about dynamic hook functions.
6 | """
7 |
8 | from typing import Dict, List, Any, Optional
9 | from dynamic_hook_system import dynamic_hook_system
10 | from hook_learning_system import hook_learning_system
11 | from debug_logger import debug_logger
12 | import json
13 |
14 |
15 | class DynamicHookAIInterface:
16 | """AI interface for dynamic hook system."""
17 |
18 | def __init__(self):
19 | self.hook_system = dynamic_hook_system
20 | self.learning_system = hook_learning_system
21 |
22 | async def create_dynamic_hook(self, name: str, requirements: Dict[str, Any],
23 | function_code: str, instance_ids: Optional[List[str]] = None,
24 | priority: int = 100) -> Dict[str, Any]:
25 | """
26 | Create a new dynamic hook with AI-generated function.
27 |
28 | Args:
29 | name: Human-readable hook name
30 | requirements: Dictionary of matching criteria (url_pattern, method, etc.)
31 | function_code: Python function code that processes requests
32 | instance_ids: Browser instances to apply hook to (all if None)
33 | priority: Hook priority (lower = higher priority)
34 |
35 | Returns:
36 | Dict with hook_id and status
37 | """
38 | try:
39 | validation = self.learning_system.validate_hook_function(function_code)
40 | if not validation["valid"]:
41 | return {
42 | "success": False,
43 | "error": "Invalid function code",
44 | "issues": validation["issues"],
45 | "warnings": validation["warnings"]
46 | }
47 |
48 | hook_id = await self.hook_system.create_hook(
49 | name=name,
50 | requirements=requirements,
51 | function_code=function_code,
52 | instance_ids=instance_ids,
53 | priority=priority
54 | )
55 |
56 | result = {
57 | "success": True,
58 | "hook_id": hook_id,
59 | "message": f"Created dynamic hook '{name}' with ID {hook_id}"
60 | }
61 |
62 | if validation["warnings"]:
63 | result["warnings"] = validation["warnings"]
64 |
65 | return result
66 |
67 | except Exception as e:
68 | debug_logger.log_error("dynamic_hook_ai", "create_dynamic_hook", f"Failed to create hook {name}: {e}")
69 | return {
70 | "success": False,
71 | "error": str(e)
72 | }
73 |
74 | async def list_dynamic_hooks(self, instance_id: Optional[str] = None) -> Dict[str, Any]:
75 | """
76 | List all dynamic hooks.
77 |
78 | Args:
79 | instance_id: Optional filter by browser instance
80 |
81 | Returns:
82 | Dict with hooks list and count
83 | """
84 | try:
85 | hooks = self.hook_system.list_hooks()
86 |
87 | if instance_id:
88 | filtered_hooks = []
89 | for hook in hooks:
90 | if instance_id in self.hook_system.instance_hooks.get(instance_id, []):
91 | filtered_hooks.append(hook)
92 | hooks = filtered_hooks
93 |
94 | return {
95 | "success": True,
96 | "hooks": hooks,
97 | "count": len(hooks)
98 | }
99 |
100 | except Exception as e:
101 | debug_logger.log_error("dynamic_hook_ai", "list_dynamic_hooks", f"Failed to list hooks: {e}")
102 | return {
103 | "success": False,
104 | "error": str(e)
105 | }
106 |
107 | async def get_hook_details(self, hook_id: str) -> Dict[str, Any]:
108 | """
109 | Get detailed information about a specific hook.
110 |
111 | Args:
112 | hook_id: Hook identifier
113 |
114 | Returns:
115 | Dict with detailed hook information
116 | """
117 | try:
118 | hook_details = self.hook_system.get_hook_details(hook_id)
119 |
120 | if not hook_details:
121 | return {
122 | "success": False,
123 | "error": f"Hook {hook_id} not found"
124 | }
125 |
126 | return {
127 | "success": True,
128 | "hook": hook_details
129 | }
130 |
131 | except Exception as e:
132 | debug_logger.log_error("dynamic_hook_ai", "get_hook_details", f"Failed to get hook details: {e}")
133 | return {
134 | "success": False,
135 | "error": str(e)
136 | }
137 |
138 | async def remove_dynamic_hook(self, hook_id: str) -> Dict[str, Any]:
139 | """
140 | Remove a dynamic hook.
141 |
142 | Args:
143 | hook_id: Hook identifier to remove
144 |
145 | Returns:
146 | Dict with removal status
147 | """
148 | try:
149 | success = await self.hook_system.remove_hook(hook_id)
150 |
151 | if success:
152 | return {
153 | "success": True,
154 | "message": f"Removed hook {hook_id}"
155 | }
156 | else:
157 | return {
158 | "success": False,
159 | "error": f"Hook {hook_id} not found"
160 | }
161 |
162 | except Exception as e:
163 | debug_logger.log_error("dynamic_hook_ai", "remove_dynamic_hook", f"Failed to remove hook: {e}")
164 | return {
165 | "success": False,
166 | "error": str(e)
167 | }
168 |
169 | def get_request_documentation(self) -> Dict[str, Any]:
170 | """
171 | Get comprehensive documentation of the request object for AI learning.
172 |
173 | Returns:
174 | Dict with request object documentation
175 | """
176 | try:
177 | return {
178 | "success": True,
179 | "documentation": self.learning_system.get_request_object_documentation()
180 | }
181 |
182 | except Exception as e:
183 | debug_logger.log_error("dynamic_hook_ai", "get_request_documentation", f"Failed to get documentation: {e}")
184 | return {
185 | "success": False,
186 | "error": str(e)
187 | }
188 |
189 | def get_hook_examples(self) -> Dict[str, Any]:
190 | """
191 | Get example hook functions for AI learning.
192 |
193 | Returns:
194 | Dict with hook examples and explanations
195 | """
196 | try:
197 | return {
198 | "success": True,
199 | "examples": self.learning_system.get_hook_examples()
200 | }
201 |
202 | except Exception as e:
203 | debug_logger.log_error("dynamic_hook_ai", "get_hook_examples", f"Failed to get examples: {e}")
204 | return {
205 | "success": False,
206 | "error": str(e)
207 | }
208 |
209 | def get_requirements_documentation(self) -> Dict[str, Any]:
210 | """
211 | Get documentation on hook requirements and matching criteria.
212 |
213 | Returns:
214 | Dict with requirements documentation
215 | """
216 | try:
217 | return {
218 | "success": True,
219 | "documentation": self.learning_system.get_requirements_documentation()
220 | }
221 |
222 | except Exception as e:
223 | debug_logger.log_error("dynamic_hook_ai", "get_requirements_documentation", f"Failed to get requirements docs: {e}")
224 | return {
225 | "success": False,
226 | "error": str(e)
227 | }
228 |
229 | def get_common_patterns(self) -> Dict[str, Any]:
230 | """
231 | Get common hook patterns and use cases.
232 |
233 | Returns:
234 | Dict with common patterns
235 | """
236 | try:
237 | return {
238 | "success": True,
239 | "patterns": self.learning_system.get_common_patterns()
240 | }
241 |
242 | except Exception as e:
243 | debug_logger.log_error("dynamic_hook_ai", "get_common_patterns", f"Failed to get patterns: {e}")
244 | return {
245 | "success": False,
246 | "error": str(e)
247 | }
248 |
249 | def validate_hook_function(self, function_code: str) -> Dict[str, Any]:
250 | """
251 | Validate hook function code for issues.
252 |
253 | Args:
254 | function_code: Python function code to validate
255 |
256 | Returns:
257 | Dict with validation results
258 | """
259 | try:
260 | validation = self.learning_system.validate_hook_function(function_code)
261 | return {
262 | "success": True,
263 | "validation": validation
264 | }
265 |
266 | except Exception as e:
267 | debug_logger.log_error("dynamic_hook_ai", "validate_hook_function", f"Failed to validate function: {e}")
268 | return {
269 | "success": False,
270 | "error": str(e)
271 | }
272 |
273 | async def create_simple_hook(self, name: str, url_pattern: str, action: str,
274 | target_url: Optional[str] = None,
275 | custom_headers: Optional[Dict[str, str]] = None,
276 | instance_ids: Optional[List[str]] = None) -> Dict[str, Any]:
277 | """
278 | Create a simple hook using predefined templates (easier for AI).
279 |
280 | Args:
281 | name: Hook name
282 | url_pattern: URL pattern to match
283 | action: Action type (block, redirect, add_headers, log)
284 | target_url: Target URL for redirect
285 | custom_headers: Headers to add
286 | instance_ids: Browser instances
287 |
288 | Returns:
289 | Dict with creation result
290 | """
291 | try:
292 | if action == "block":
293 | function_code = '''
294 | def process_request(request):
295 | return HookAction(action="block")
296 | '''
297 | elif action == "redirect":
298 | if not target_url:
299 | return {"success": False, "error": "target_url required for redirect action"}
300 | function_code = f'''
301 | def process_request(request):
302 | return HookAction(action="redirect", url="{target_url}")
303 | '''
304 | elif action == "add_headers":
305 | if not custom_headers:
306 | return {"success": False, "error": "custom_headers required for add_headers action"}
307 | headers_str = str(custom_headers).replace("'", '"')
308 | function_code = f'''
309 | def process_request(request):
310 | new_headers = request["headers"].copy()
311 | new_headers.update({headers_str})
312 | return HookAction(action="modify", headers=new_headers)
313 | '''
314 | elif action == "log":
315 | function_code = '''
316 | def process_request(request):
317 | print(f"[HOOK LOG] {request['method']} {request['url']}")
318 | return HookAction(action="continue")
319 | '''
320 | else:
321 | return {"success": False, "error": f"Unknown action: {action}"}
322 |
323 | requirements = {"url_pattern": url_pattern}
324 |
325 | return await self.create_dynamic_hook(
326 | name=name,
327 | requirements=requirements,
328 | function_code=function_code,
329 | instance_ids=instance_ids
330 | )
331 |
332 | except Exception as e:
333 | debug_logger.log_error("dynamic_hook_ai", "create_simple_hook", f"Failed to create simple hook: {e}")
334 | return {
335 | "success": False,
336 | "error": str(e)
337 | }
338 |
339 |
340 | dynamic_hook_ai = DynamicHookAIInterface()
```