Coldaine/llm-site-controller

LLM Site Controller Framework

Status: ✅ Production Ready (v1.0.0) | 13 MCP Tools Available |

AI-powered browser automation framework for LLM chat interfaces via Model Context Protocol (MCP)

📋 Quick Links

• 📊 - What works, what doesn't
• 📖 - Development phases (reference)
• 🏗️ - Design specification

✅ What's Working

Answer: "Is everything exposed through MCP tools?" YES - All functionality is accessible via 13 MCP tools. See Available MCP Tools below.

⚠️ Known Limitations

• ❌ Browser Support: Chrome only (Firefox/Edge not implemented)
• ❌ Shadow DOM: Limited support for shadow DOM traversal
• ❌ iframes: Cross-origin iframes not fully supported
• ⚠️ Platform Testing: Linux tested; macOS/Windows should work but less tested
• ⚠️ CSP Sites: Strict Content Security Policy may require manual script adjustments

🚀 Quick Start

Prerequisites

• Node.js 18+ and npm
• Google Chrome or Chromium
• (Optional) Tampermonkey extension for generated scripts

Installation

# 1. Clone repository
git clone <repository-url>
cd llm-site-controller

# 2. Install dependencies
npm install

# 3. Build project
npm run build

# 4. Configure MCP (automatic)
npm run install-mcp

# OR manually add to ~/.config/claude/claude_desktop_config.json:
# {
#   "mcpServers": {
#     "llm-site-controller": {
#       "command": "node",
#       "args": ["/absolute/path/to/llm-site-controller/dist/mcp-server/index.js"]
#     }
#   }
# }

Usage

Step 1: Launch Chrome with remote debugging

# Linux/Mac
google-chrome --remote-debugging-port=9222 --user-data-dir=/tmp/chrome-debug

# Windows
"C:\Program Files\Google\Chrome\Application\chrome.exe" --remote-debugging-port=9222 --user-data-dir=C:\temp\chrome-debug

Step 2: Use via Claude Desktop (or any MCP client)

1. In Claude: "Connect to Chrome on port 9222"
2. Navigate to any site in Chrome
3. In Claude: "Analyze this page"
4. In Claude: "Generate a Tampermonkey script for ChatGPT"

🛠️ Available MCP Tools (18/18)

Chrome Connection

Browser Control (NEW in v1.1.0)

Page Analysis & Interaction

Image Collection (Advanced)

🚨 CRITICAL: Tampermonkey @match Pattern Best Practice

Always use BOTH patterns for each domain:

// @match        https://example.com/*
// @match        https://*.example.com/*

Why This Matters:

The *. wildcard before the domain catches:

• https://example.com/* ✓
• https://www.example.com/* ✓
• https://api.example.com/* ✓
• https://cdn.example.com/* ✓
• https://any-subdomain.example.com/* ✓

Without the wildcard, you ONLY match the exact domain. Modern sites use subdomains extensively (www, api, cdn, auth, etc.). Missing this = broken scripts on most pages.

See: for complete guide.

🎯 Target Sites (Script Development)

This repo is building and refining weapon-grade Tampermonkey scripts for:

• chat.qwen.ai
• z.ai
• gemini.google.com
• chat.openai.com (ChatGPT)
• claude.ai
• gro https://grok.com/chat

Each site has a dedicated folder under src/tampermonkey/targets/ for scripts, strategies, and notes.

🚀 Iterative Workflow (#codebase)

• Scripts are developed and tested in their target folders.
• MCP tools (analyzer, recorder) support script calibration and refinement.
• Iteration is expected: scripts are improved based on real-world feedback and calibration.
• All changes and experiments should be committed to the repo for traceability.
• #codebase is central: all plans, docs, and scripts live here and evolve together.

📖 Example Workflows

Workflow 1: Generate Userscript for LLM Chat

1. Launch Chrome with remote debugging
2. Claude: "Connect to Chrome"
3. Navigate to chat.openai.com in Chrome
4. Claude: "Analyze this page"
5. Claude: "Start recording interactions"
6. Manually type and send a message in ChatGPT
7. Claude: "Get the recorded interactions"
8. Claude: "Generate a Tampermonkey script called 'ChatGPT Controller'"
9. Install generated script in Tampermonkey

Workflow 2: Scrape Images from a Site

1. Launch Chrome with remote debugging
2. Claude: "Connect to Chrome"
3. Navigate to an image gallery site
4. Claude: "Inject the image collector with minimum dimensions 1200x1200"
5. Scroll through the page (the HUD shows count)
6. Claude: "Get the top 20 collected images"
7. Claude: "Scrape all images to ~/Downloads/scraped_images"

Workflow 3: Download Models (NEW in v1.1.0)

1. Launch Chrome with remote debugging
2. Claude: "Connect to Chrome on port 9222"
3. Claude: "Navigate to https://civet.ai/models"
4. Claude: "Wait for the .model-list selector"
5. Claude: "Type 'llama-3' into input.search"
6. Claude: "Wait for .search-results to appear"
7. Claude: "Click .model-card:first-child a.download"
8. Claude: "Download the model to /downloads/llama3.bin using selector button.download-btn"

Pro tip: You can chain commands in a single request:

"Navigate to civet.ai/models, wait for the page to load,
search for 'llama-3', click the first result,
and download it to ~/Downloads/llama3.bin"

🧪 Development

Running Tests

npm test              # Run all tests with coverage
npm run dev           # Development mode with hot reload
npm run lint          # Lint code
npm run ncommit       # Smart grouped commits helper

Project Structure

llm-site-controller/
├── src/
│   ├── mcp-server/
│   │   ├── index.ts                  # MCP server entry (13 tools)
│   │   ├── chrome-connector.ts       # Chrome connection
│   │   ├── dom-analyzer.ts           # DOM analysis
│   │   ├── interaction-recorder.ts   # Interaction recording
│   │   ├── script-generator.ts       # Userscript generation
│   │   ├── image-collector.ts        # Image collection (bonus)
│   │   └── media-scraper.ts          # Media scraping (bonus)
│   └── templates/
│       └── tampermonkey-template.ts  # Script template
├── tests/                            # Jest tests (100% coverage)
├── dist/                             # Compiled JavaScript
├── configs/                          # MCP configuration
├── scripts/                          # Helper scripts
└── docs/                             # Documentation

🔧 Troubleshooting

Chrome Connection Fails

Problem: "Failed to connect to Chrome"

Solutions:

• Verify Chrome is running: curl http://localhost:9222/json/version
• Check port matches (default 9222)
• Restart Chrome with debug flags
• Check firewall isn't blocking localhost

MCP Server Not Found

Problem: Claude doesn't recognize the server

Solutions:

• Use absolute path in MCP config (not relative)
• Verify dist/mcp-server/index.js exists
• Run npm run build to compile
• Restart Claude Desktop after config changes

Generated Script Doesn't Work

Problem: Tampermonkey script fails on target site

Solutions:

• Re-analyze page (DOM may have changed)
• Use interaction recording instead of text-based selectors
• Check browser console for errors
• Verify selectors in DevTools (F12)

TypeScript Build Errors

Problem: npm run build fails

Solutions:

# Clean rebuild
rm -rf node_modules dist
npm install
npm run build

🌐 Accessibility & i18n

Accessibility Features

• Prioritizes ARIA labels (aria-label, role)
• Falls back to stable IDs and data attributes
• Supports semantic HTML element selection
• Text-based element finding as last resort

Recommendations:

• Test generated scripts with screen readers
• Verify keyboard navigation isn't broken
• Ensure focus management works correctly

Internationalization (i18n)

Best Practices for Multi-Language Sites:

1. Use analyze_page to find data attributes (language-independent)
2. Prefer recording interactions over text-based finding
3. Test scripts with different language settings
4. Maintain separate configs per language if needed

Known Limitations:

• RTL (right-to-left) language support not tested
• Generated script UI text is English-only
• Text-based selectors fail on multi-language sites

🔒 Security Considerations

• ✅ Localhost Only: Chrome debug connection restricted to localhost
• ⚠️ Userscripts: Review generated scripts before installing
• ⚠️ Sensitive Data: Don't record on pages with passwords/API keys
• ⚠️ CSP: Some sites have strict Content Security Policy

📚 Additional Documentation

• - Detailed implementation status (what works/doesn't)
• - 29-step implementation plan (reference)
• - Original architecture specification
• - Extended usage guide

🗺️ Roadmap

v1.0.0 (Current - 95% Complete)

• ✅ All 13 MCP tools
• ✅ Core modules (Chrome, DOM, Interaction, Script)
• ✅ Image scraping (bonus feature)
• ⏳ Final documentation polish (CHANGELOG.md, docs/tools.md)

Future (Post-v1.0)

• Multi-browser support (Firefox via Playwright)
• Enhanced shadow DOM traversal
• CSP bypass detection & warnings
• WCAG compliance testing
• Community script marketplace

📄 License

MIT License - See for details

🤝 Contributing

1. Fork the repository
2. Create feature branch: git checkout -b feature/amazing-feature
3. Write tests for new functionality
4. Ensure tests pass: npm test
5. Commit changes: npm run ncommit (or standard git commit)
6. Push to branch: git push origin feature/amazing-feature
7. Open a Pull Request

Code Style:

• Follow existing TypeScript conventions
• Add JSDoc comments for public APIs
• Keep functions focused and single-purpose
• Write tests for new features (aim for 80%+ coverage)

🙏 Acknowledgments

Built with:

• Model Context Protocol SDK
• Puppeteer
• Zod
• Jest
• TypeScript

📞 Support

• 🐛 Issues: GitHub Issues
• 💬 Questions: Check existing issues first
• 📖 Docs: See for details

📊 Project Status

• Version: 1.0.0
• Status: Production Ready (95% complete)
• Build: ✅ Passing
• Tests: ✅ 100% coverage (ScriptGenerator)
• MCP Tools: ✅ 13/13 implemented
• Last Updated: 2025-10-09

For detailed implementation tracking, see .