@eddym06/custom-chrome-mcp 1.0.2

package/.npmrc.example

@@ -0,0 +1,2 @@
+//npm.pkg.github.com/:_authToken=${GITHUB_TOKEN}
+@eddym06:registry=https://npm.pkg.github.com

package/CHANGELOG.md

@@ -0,0 +1,87 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+## [1.0.0] - 2026-01-07
+
+### ✨ Features
+
+#### Core
+- Initial release of Custom Chrome MCP
+- Connect to existing Chrome instances via CDP (port 9222)
+- Full MCP protocol implementation with 44 tools
+
+#### Navigation & Tabs (8 tools)
+- Navigate to URLs with wait conditions
+- Browser history (back/forward)
+- Page reload with cache options
+- Multi-tab management (list, create, close, switch)
+- Get current URL and page info
+
+#### Interaction (8 tools)
+- Click elements with human-like delays
+- Type text with realistic timing
+- Get text content and attributes
+- Execute custom JavaScript
+- Scroll pages and elements
+- Wait for selectors with timeout
+- Select options from dropdowns
+
+#### Anti-Detection (5 tools)
+- Stealth mode with navigator.webdriver masking
+- Custom user agent configuration
+- Viewport and device emulation
+- Geolocation spoofing
+- Timezone override
+
+#### Service Workers (9 tools)
+- List all registered service workers
+- Get detailed worker information
+- Unregister service workers
+- Force update registrations
+- Start/stop workers
+- Inspect workers in DevTools
+- Skip waiting phase
+- Manage service worker caches
+
+#### Capture & Export (5 tools)
+- Screenshots (PNG/JPEG, full page, custom areas)
+- Export to PDF
+- Get HTML content
+- Page layout metrics
+- Accessibility tree export
+
+#### Sessions & Cookies (9 tools)
+- Cookie management (get, set, delete, clear)
+- localStorage operations
+- sessionStorage support
+- Full session export/import
+- Cross-session persistence
+
+### 🛡️ Security
+- Anti-detection measures
+- Realistic browser fingerprinting
+- Human-like interaction patterns
+
+### 📚 Documentation
+- Comprehensive README
+- Usage examples
+- Troubleshooting guide
+- API documentation
+
+### 🔧 Technical
+- TypeScript implementation
+- Zod schema validation
+- Error handling
+- Graceful shutdown
+- Modular architecture
+
+## [Unreleased]
+
+### Planned Features
+- Visual regression testing
+- Network throttling
+- Performance profiling
+- Video recording
+- Auto-recovery mechanisms
+- Multi-profile support (future)

package/INSTALL.md

@@ -0,0 +1,148 @@
+# 🚀 Guía de Instalación Rápida
+
+## Paso 1: Instalar Dependencias
+
+```bash
+cd custom-chrome-mcp
+npm install
+```
+
+## Paso 2: Compilar el Proyecto
+
+```bash
+npm run build
+```
+
+## Paso 3: Lanzar Chrome con Debugging
+
+### Windows (PowerShell)
+```powershell
+start chrome --remote-debugging-port=9222
+```
+
+### Windows (CMD)
+```cmd
+"C:\Program Files\Google\Chrome\Application\chrome.exe" --remote-debugging-port=9222
+```
+
+### macOS
+```bash
+/Applications/Google\ Chrome.app/Contents/MacOS/Google\ Chrome --remote-debugging-port=9222 &
+```
+
+### Linux
+```bash
+google-chrome --remote-debugging-port=9222 &
+```
+
+## Paso 4: Configurar en VS Code / Cline
+
+Edita tu archivo de configuración MCP (usualmente en `.vscode/mcp.json` o en la configuración de Cline):
+
+### Opción A: Desarrollo Local
+```json
+{
+  "mcpServers": {
+    "custom-chrome-mcp": {
+      "command": "node",
+      "args": ["C:/Users/eddym/Downloads/devTools-Advance/custom-chrome-mcp/dist/index.js"],
+      "env": {}
+    }
+  }
+}
+```
+
+### Opción B: Después de publicar en npm
+```json
+{
+  "mcpServers": {
+    "custom-chrome-mcp": {
+      "command": "npx",
+      "args": ["custom-chrome-mcp", "--port=9222"]
+    }
+  }
+}
+```
+
+## Paso 5: Probar la Conexión
+
+Una vez configurado, puedes probarlo desde VS Code / Cline:
+
+```
+User: Lista las pestañas abiertas en Chrome
+
+AI: [Usará la herramienta list_tabs]
+```
+
+## Verificar que todo funciona
+
+1. **Verificar puerto abierto:**
+```powershell
+netstat -an | findstr 9222
+```
+
+Deberías ver algo como:
+```
+TCP    127.0.0.1:9222         0.0.0.0:0              LISTENING
+```
+
+2. **Probar en el navegador:**
+Abre: http://localhost:9222/json
+
+Deberías ver un JSON con las pestañas abiertas.
+
+3. **Probar el MCP:**
+```bash
+npm start
+```
+
+Deberías ver:
+```
+🚀 Custom Chrome MCP Server starting...
+📡 Connecting to Chrome on port 9222
+✅ Connected to Chrome/131.0.0.0 (...)
+📑 Found X open tab(s)
+🔧 Tools available: 44
+✨ Server ready! Waiting for requests...
+```
+
+## Solución de Problemas
+
+### Error: "Failed to connect to Chrome"
+- Verifica que Chrome esté corriendo con `--remote-debugging-port=9222`
+- Verifica que el puerto 9222 esté libre
+- Cierra otras instancias de Chrome y vuelve a lanzar con el flag
+
+### Error: "Cannot find module"
+- Ejecuta `npm install` de nuevo
+- Ejecuta `npm run build` para compilar
+
+### Chrome se cierra al iniciar con el flag
+- No uses perfiles con extensiones que bloqueen debugging
+- Usa un perfil limpio: `--user-data-dir="C:\ChromeDebug"`
+
+```powershell
+start chrome --remote-debugging-port=9222 --user-data-dir="C:\ChromeDebug"
+```
+
+## Próximos Pasos
+
+- Lee el [README.md](README.md) completo para ver todas las herramientas disponibles
+- Prueba el modo stealth: `enable_stealth_mode`
+- Exporta/importa sesiones para reutilizar logins
+- Gestiona Service Workers
+
+## Publicar en npm (para el autor)
+
+```bash
+# Actualizar versión
+npm version patch  # o minor, o major
+
+# Publicar
+npm publish
+
+# Ahora otros usuarios pueden instalar con:
+npm install -g custom-chrome-mcp
+```
+
+¡Listo! Ya tienes tu MCP personalizado funcionando 🎉

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Eddy M
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,403 @@
+# Custom Chrome MCP 🚀
+
+Cross-platform Model Context Protocol (MCP) server for advanced Chrome browser automation and control. Works on Windows, macOS, and Linux.
+
+## 📦 Quick Install for VS Code
+
+Add this to your `mcp.json` config file:
+
+```json
+{
+  "mcpServers": {
+    "custom-chrome-mcp": {
+      "command": "npx",
+      "args": ["-y", "@eddym06/custom-chrome-mcp", "--port=9222"]
+    }
+  }
+}
+```
+
+## 🌍 Platform Support
+
+- ✅ **Windows** - Full support with robocopy-based Shadow Profile
+- ✅ **macOS** - Full support with rsync-based Shadow Profile  
+- ✅ **Linux** - Full support with rsync-based Shadow Profile
+
+## ✨ Características Principales
+
+### 🔌 Conexión a Chrome Existente
+- **Conecta a tu Chrome ya abierto** con `--remote-debugging-port=9222`
+- **Usa tus sesiones activas** (Google, Facebook, etc.)
+- **Sin detección de automatización** porque usas tu navegador real
+- **Mantén tus extensiones y configuración**
+
+### 🛡️ Anti-Detección Avanzada
+- Oculta `navigator.webdriver`
+- Spoof de plugins y permisos
+- User-Agent personalizable
+- Timezone y geolocalización configurable
+- Scripts anti-detección automáticos
+
+### 🔒 Shadow Profile System
+- **Bypasses Chrome's Default profile debugging restriction**
+- Platform-specific cloning (robocopy on Windows, rsync on Unix)
+- Automatic encryption key preservation
+- Skips cache folders for fast copying
+
+### ⚙️ Gestión Completa de Service Workers
+- Listar todos los Service Workers registrados
+- Inspeccionar, actualizar y desregistrar workers
+- Iniciar/detener Service Workers
+- Gestión de caché de Service Workers
+- Skip waiting y control total
+
+### 🍪 Gestión de Sesiones
+- Exportar/importar sesiones completas
+- Gestión de cookies (get, set, delete)
+- localStorage y sessionStorage
+- Persistencia de sesiones entre ejecuciones
+
+### 📸 Captura Avanzada
+- Screenshots (fullpage, áreas específicas)
+- Exportar a PDF
+- Obtener HTML completo
+- Métricas de página
+- Árbol de accesibilidad
+
+### 🎯 Automatización Inteligente
+- Delays human-like automáticos
+- Wait for selectors
+- Navegación completa (back, forward, reload)
+- Multi-tab management
+- Ejecución de JavaScript custom
+
+## 📦 Instalación
+
+### Desde GitHub Packages
+
+1. Crea un archivo `.npmrc` en tu proyecto:
+```bash
+//npm.pkg.github.com/:_authToken=YOUR_GITHUB_TOKEN
+@eddym06:registry=https://npm.pkg.github.com
+```
+
+2. Instala el paquete:
+```bash
+npm install @eddym06/custom-chrome-mcp
+```
+
+### Desde el código fuente
+```bash
+git clone https://github.com/Eddym06/devTools-Advance-mcp.git
+cd custom-chrome-mcp
+npm install
+npm run build
+```
+npm install -g custom-chrome-mcp
+```
+
+### Desarrollo local
+```bash
+cd custom-chrome-mcp
+npm install
+npm run build
+```
+
+## 🚀 Uso Rápido
+
+### 1. Lanza Chrome con debugging habilitado
+
+**Windows:**
+```powershell
+start chrome --remote-debugging-port=9222
+```
+
+**macOS:**
+```bash
+/Applications/Google\ Chrome.app/Contents/MacOS/Google\ Chrome --remote-debugging-port=9222 &
+```
+
+**Linux:**
+```bash
+google-chrome --remote-debugging-port=9222 &
+```
+
+### 2. Configura el MCP en VS Code
+
+Agrega en tu `mcp.json` o configuración de Cline/Claude:
+
+```json
+{
+  "mcpServers": {
+    "custom-chrome-mcp": {
+      "command": "npx",
+      "args": ["custom-chrome-mcp", "--port=9222"]
+    }
+  }
+}
+```
+
+### 3. ¡Empieza a usar!
+
+El MCP se conectará automáticamente a tu Chrome y tendrás acceso a 44 herramientas organizadas en 6 categorías.
+
+## 🛠️ Herramientas Disponibles
+
+### Navegación & Tabs (8 herramientas)
+- `navigate` - Navegar a URL
+- `go_back` / `go_forward` - Historial
+- `reload` - Recargar página
+- `list_tabs` - Listar pestañas
+- `create_tab` - Crear pestaña
+- `close_tab` - Cerrar pestaña
+- `switch_tab` - Cambiar de pestaña
+- `get_url` - Obtener URL actual
+
+### Interacción con Página (8 herramientas)
+- `click` - Hacer click en elemento
+- `type` - Escribir texto
+- `get_text` - Obtener texto
+- `get_attribute` - Obtener atributo
+- `execute_script` - Ejecutar JavaScript
+- `scroll` - Hacer scroll
+- `wait_for_selector` - Esperar elemento
+- `select_option` - Seleccionar opción
+
+### Anti-Detección (5 herramientas)
+- `enable_stealth_mode` - Activar modo stealth
+- `set_user_agent` - Cambiar user agent
+- `set_viewport` - Configurar viewport
+- `set_geolocation` - Configurar ubicación
+- `set_timezone` - Configurar zona horaria
+
+### Service Workers (9 herramientas)
+- `list_service_workers` - Listar workers
+- `get_service_worker` - Obtener detalles
+- `unregister_service_worker` - Desregistrar
+- `update_service_worker` - Actualizar
+- `start_service_worker` - Iniciar
+- `stop_service_worker` - Detener
+- `inspect_service_worker` - Inspeccionar
+- `skip_waiting` - Skip waiting
+- `get_sw_caches` - Obtener cachés
+
+### Captura (5 herramientas)
+- `screenshot` - Captura de pantalla
+- `get_html` - Obtener HTML
+- `print_to_pdf` - Exportar a PDF
+- `get_page_metrics` - Métricas de página
+- `get_accessibility_tree` - Árbol a11y
+
+### Sesiones & Cookies (9 herramientas)
+- `get_cookies` - Obtener cookies
+- `set_cookie` - Establecer cookie
+- `delete_cookie` - Eliminar cookie
+- `clear_cookies` - Limpiar cookies
+- `get_local_storage` - Obtener localStorage
+- `set_local_storage` - Establecer item
+- `clear_local_storage` - Limpiar storage
+- `export_session` - Exportar sesión
+- `import_session` - Importar sesión
+
+## 💡 Ejemplos de Uso
+
+### Ejemplo 1: Navegar y hacer screenshot
+```typescript
+// Navegar a una URL
+await mcp.call('navigate', { url: 'https://example.com' });
+
+// Esperar que cargue un elemento
+await mcp.call('wait_for_selector', { selector: '#content' });
+
+// Tomar screenshot full page
+await mcp.call('screenshot', { fullPage: true, format: 'png' });
+```
+
+### Ejemplo 2: Activar modo stealth y navegar
+```typescript
+// Activar modo stealth
+await mcp.call('enable_stealth_mode', {});
+
+// Navegar a Google
+await mcp.call('navigate', { url: 'https://google.com' });
+
+// Escribir en el buscador
+await mcp.call('type', { 
+  selector: 'input[name="q"]', 
+  text: 'model context protocol' 
+});
+
+// Hacer click en buscar
+await mcp.call('click', { selector: 'input[type="submit"]' });
+```
+
+### Ejemplo 3: Exportar sesión
+```typescript
+// Exportar sesión actual (cookies, localStorage, etc.)
+const result = await mcp.call('export_session', {});
+console.log(result.session);
+
+// Guardar en archivo
+fs.writeFileSync('session.json', JSON.stringify(result.session));
+
+// Importar en otra sesión
+const sessionData = fs.readFileSync('session.json', 'utf8');
+await mcp.call('import_session', { sessionData });
+```
+
+### Ejemplo 4: Gestionar Service Workers
+```typescript
+// Listar todos los service workers
+const workers = await mcp.call('list_service_workers', {});
+console.log(workers.workers);
+
+// Actualizar un service worker específico
+await mcp.call('update_service_worker', { 
+  scopeURL: 'https://example.com/' 
+});
+
+// Ver cachés
+const caches = await mcp.call('get_sw_caches', {});
+console.log(caches.caches);
+```
+
+## 🔧 Configuración Avanzada
+
+### Puerto personalizado
+```json
+{
+  "custom-chrome-mcp": {
+    "command": "npx",
+    "args": ["custom-chrome-mcp", "--port=9333"]
+  }
+}
+```
+
+### Variables de entorno
+Puedes configurar:
+- `CHROME_PORT` - Puerto de debugging (default: 9222)
+
+## 🎯 Ventajas sobre otros MCPs
+
+| Característica | Custom Chrome MCP | chrome-devtools-mcp | playwright-mcp |
+|----------------|-------------------|---------------------|----------------|
+| Conecta a Chrome existente | ✅ | ❌ | ❌ |
+| Usa sesiones reales | ✅ | ❌ | ❌ |
+| Anti-detección | ✅ | ❌ | ⚠️ |
+| Service Workers | ✅ | ⚠️ | ⚠️ |
+| Exportar/importar sesiones | ✅ | ❌ | ❌ |
+| Delays human-like | ✅ | ❌ | ⚠️ |
+| Multi-tab | ✅ | ✅ | ✅ |
+| Screenshots | ✅ | ✅ | ✅ |
+
+## 🐛 Troubleshooting
+
+### Error: Failed to connect to Chrome
+**Solución:** Asegúrate de que Chrome está corriendo con `--remote-debugging-port=9222`
+
+```powershell
+# Verifica que el puerto está abierto
+netstat -an | findstr 9222
+```
+
+### Chrome detecta automatización
+**Solución:** Usa `enable_stealth_mode` antes de navegar a sitios sensibles
+
+```typescript
+await mcp.call('enable_stealth_mode', {});
+```
+
+### Service Workers no aparecen
+**Solución:** Los Service Workers solo funcionan con HTTPS o localhost. Usa un servidor local:
+
+```bash
+python -m http.server 8000
+# Luego navega a http://localhost:8000
+```
+
+## 📝 Desarrollo
+
+### Estructura del proyecto
+```
+custom-chrome-mcp/
+├── src/
+│   ├── index.ts              # Servidor MCP principal
+│   ├── chrome-connector.ts   # Conexión a Chrome
+│   ├── tools/
+│   │   ├── navigation.ts     # Navegación
+│   │   ├── interaction.ts    # Interacción
+│   │   ├── anti-detection.ts # Anti-detección
+│   │   ├── service-worker.ts # Service Workers
+│   │   ├── capture.ts        # Capturas
+│   │   └── session.ts        # Sesiones
+│   ├── utils/
+│   │   └── helpers.ts        # Utilidades
+│   └── types/
+│       └── index.ts          # Tipos TypeScript
+├── package.json
+└── tsconfig.json
+```
+
+### Comandos
+```bash
+npm run build    # Compilar TypeScript
+npm run dev      # Modo desarrollo (watch)
+npm run lint     # Lint código
+npm run format   # Formatear código
+```
+
+### Añadir nuevas herramientas
+
+1. Crea un nuevo archivo en `src/tools/`
+2. Define tus herramientas usando el patrón:
+
+```typescript
+export function createMyTools(connector: ChromeConnector) {
+  return [
+    {
+      name: 'my_tool',
+      description: 'Descripción de la herramienta',
+      inputSchema: z.object({
+        param: z.string().describe('Parámetro')
+      }),
+      handler: async ({ param }: any) => {
+        // Implementación
+        return { success: true };
+      }
+    }
+  ];
+}
+```
+
+3. Importa y añade en [index.ts](src/index.ts)
+
+## 📄 Licencia
+
+MIT © 2026 Eddy M
+
+## 🤝 Contribuciones
+
+¡Las contribuciones son bienvenidas! Por favor:
+
+1. Fork el proyecto
+2. Crea una rama para tu feature (`git checkout -b feature/amazing-feature`)
+3. Commit tus cambios (`git commit -m 'Add amazing feature'`)
+4. Push a la rama (`git push origin feature/amazing-feature`)
+5. Abre un Pull Request
+
+## 🙏 Agradecimientos
+
+- [Model Context Protocol](https://modelcontextprotocol.io/) - El protocolo que hace esto posible
+- [chrome-remote-interface](https://github.com/cyrus-and/chrome-remote-interface) - Cliente CDP para Node.js
+- La comunidad de Chrome DevTools
+
+## 📧 Soporte
+
+Si encuentras algún problema o tienes preguntas:
+- Abre un issue en GitHub
+- Consulta la documentación de MCP
+- Revisa los ejemplos en este README
+
+---
+
+**Hecho con ❤️ para automatizar Chrome de forma inteligente**