Blueprint MCP Server

oficial

Automatización del navegador mediante MCP para Chrome y Firefox

Documentación

Blueprint MCP

Controla tu navegador real con IA a través del Model Context Protocol

¿Qué es esto?

Un servidor MCP (Model Context Protocol) que permite a los asistentes de IA controlar tu navegador real (Chrome, Firefox u Opera) mediante una extensión del navegador. A diferencia de las herramientas de automatización sin interfaz gráfica, utiliza tu perfil de navegador real con todas tus sesiones iniciadas, cookies y extensiones intactas.

Perfecto para: Agentes de IA que necesitan interactuar con sitios donde ya has iniciado sesión, o que necesitan evitar la detección de bots.

¿Por qué usar esto en lugar de Playwright/Puppeteer?

Blueprint MCP	Playwright/Puppeteer
✅ Navegador real (no sin interfaz gráfica)	❌ Sin interfaz gráfica o nueva instancia del navegador
✅ Mantiene la sesión iniciada en todos tus sitios	❌ Debe volver a autenticarse en cada sesión
✅ Evita la detección de bots (usa huella digital real)	⚠️ A menudo detectado como navegador automatizado
✅ Funciona con tus extensiones de navegador existentes	❌ Sin soporte para extensiones
✅ Configuración cero: funciona nada más instalarlo	⚠️ Requiere instalación del navegador
✅ Soporte para Chrome, Firefox, Edge, Opera	✅ Soporte para Chrome, Firefox, Safari

Instalación

1. Instalar el servidor MCP

npm install -g @railsblueprint/blueprint-mcp

2. Instalar la extensión del navegador

Elige tu navegador:

Chrome / Edge / Opera

Chrome Web Store (funciona para todos los navegadores Chromium)
Manual: Descarga desde Releases, luego carga la extensión desempaquetada en chrome://extensions/ (Chrome), edge://extensions/ (Edge), o opera://extensions/ (Opera)

Firefox

Firefox Add-ons
Manual: Descarga desde Releases, luego carga en about:debugging#/runtime/this-firefox

3. Configurar tu cliente MCP

Claude Desktop (~/Library/Application Support/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "browser": {
      "command": "npx",
      "args": ["@railsblueprint/blueprint-mcp@latest"]
    }
  }
}

Claude Code (CLI impulsada por IA):

claude mcp add browser npx @railsblueprint/blueprint-mcp@latest

VS Code / Cursor (.vscode/settings.json):

{
  "mcp.servers": {
    "browser": {
      "command": "npx",
      "args": ["@railsblueprint/blueprint-mcp@latest"]
    }
  }
}

Inicio rápido

Inicia tu cliente MCP (Claude Desktop, Cursor, etc.)
Haz clic en el icono de la extensión Blueprint MCP en tu navegador
La extensión se conecta automáticamente al servidor MCP
¡Pide a tu asistente de IA que navegue!

Conversaciones de ejemplo:

You: "Go to GitHub and check my notifications"
AI: *navigates to github.com, clicks notifications, reads content*

You: "Fill out this form with my info"
AI: *reads form fields, fills them in, submits*

You: "Take a screenshot of this page"
AI: *captures screenshot and shows you*

Cómo funciona

┌─────────────────────────┐
│   AI Assistant          │
│   (Claude, GPT, etc)    │
└───────────┬─────────────┘
            │
            │ MCP Protocol
            ↓
┌─────────────────────────┐
│   MCP Client            │
│   (Claude Desktop, etc) │
└───────────┬─────────────┘
            │
            │ stdio/JSON-RPC
            ↓
┌─────────────────────────┐
│   blueprint-mcp         │
│   (this package)        │
└───────────┬─────────────┘
            │
            │ WebSocket (localhost:5555 or cloud relay)
            ↓
┌─────────────────────────┐
│   Browser Extension     │
└───────────┬─────────────┘
            │
            │ Browser Extension APIs
            ↓
┌─────────────────────────┐
│   Your Browser          │
│   (real profile)        │
└─────────────────────────┘

Gratis vs PRO

Nivel gratuito (por defecto)

✅ Conexión WebSocket local (puerto 5555)
✅ Instancia única del navegador
✅ Todas las funciones de automatización del navegador
✅ No requiere cuenta
❌ Limitado a la misma máquina

Nivel PRO

✅ Relé en la nube - conéctate desde cualquier lugar
✅ Múltiples navegadores - controla múltiples instancias del navegador
✅ Acceso compartido - múltiples clientes de IA pueden usar el mismo navegador
✅ Reconexión automática - mantiene la conexión a través de cambios de red
✅ Soporte prioritario

Actualizar a PRO

Herramientas disponibles

El servidor MCP proporciona estas herramientas a los asistentes de IA:

Gestión de conexión

enable - Activar la automatización del navegador (primer paso necesario)
disable - Desactivar la automatización del navegador
status - Verificar el estado de la conexión
auth - Iniciar sesión en la cuenta PRO (para funciones de relé en la nube)

Gestión de pestañas

browser_tabs - Listar, crear, adjuntar o cerrar pestañas del navegador

Navegación

browser_navigate - Navegar a una URL
browser_navigate_back - Retroceder en el historial

Contenido e inspección

browser_snapshot - Obtener contenido accesible de la página (recomendado para leer páginas)
browser_take_screenshot - Capturar captura de pantalla visual
browser_console_messages - Obtener registros de la consola del navegador
browser_network_requests - Potente herramienta de monitoreo y reproducción de red con múltiples acciones:
- Modo lista (por defecto): Resumen ligero con filtrado y paginación (por defecto: 20 solicitudes)
  - Filtros: urlPattern (subcadena), method (GET/POST), status (200/404), resourceType (xhr/fetch/script)
  - Paginación: limit (por defecto: 20), offset (por defecto: 0)
  - Ejemplo: action='list', urlPattern='api/users', method='GET', limit=10
- Modo detalles: Datos completos de solicitud/respuesta para una solicitud específica, incluyendo cabeceras y cuerpos
- Filtrado JSONPath: Consulta respuestas JSON grandes usando sintaxis JSONPath (ej., $.data.items[0])
- Modo reproducción: Vuelve a ejecutar solicitudes capturadas con cabeceras y autenticación originales
- Modo limpiar: Limpia el historial capturado para liberar memoria
- Ejemplo: action='details', requestId='12345.67', jsonPath='$.data.users[0]'
browser_extract_content - Extraer el contenido de la página como markdown

Interacción

browser_interact - Realizar múltiples acciones en secuencia (clic, escribir, pasar el cursor, esperar, etc.)
browser_click - Hacer clic en elementos
browser_type - Escribir texto en campos de entrada
browser_hover - Pasar el cursor sobre elementos
browser_select_option - Seleccionar opciones de menús desplegables
browser_fill_form - Rellenar múltiples campos de formulario a la vez
browser_press_key - Pulsar teclas del teclado
browser_drag - Arrastrar y soltar elementos

Avanzado

browser_evaluate - Ejecutar JavaScript en el contexto de la página
browser_handle_dialog - Manejar diálogos de alerta/confirmación/aviso
browser_file_upload - Subir archivos a través de campos de entrada de archivos
browser_window - Redimensionar, minimizar, maximizar la ventana del navegador
browser_pdf_save - Guardar la página actual como PDF
browser_performance_metrics - Obtener métricas de rendimiento
browser_verify_text_visible - Verificar que un texto está presente (para pruebas)
browser_verify_element_visible - Verificar que un elemento existe (para pruebas)

Gestión de extensiones

browser_list_extensions - Listar las extensiones del navegador instaladas
browser_reload_extensions - Recargar extensiones desempaquetadas (útil durante el desarrollo)

Desarrollo

Requisitos previos

Node.js 18+
Un navegador compatible (Chrome, Firefox, Edge u Opera)
npm o yarn

Configuración

# Clone the repository
git clone https://github.com/railsblueprint/blueprint-mcp.git
cd blueprint-mcp

# Install server dependencies
cd server
npm install
cd ..

# Install Chrome extension dependencies
cd extensions/chrome
npm install
cd ../..

Ejecución en desarrollo

Terminal 1: Iniciar el servidor MCP en modo depuración

cd server
node cli.js --debug

Terminal 2: Construir la extensión de Chrome

cd extensions/chrome
npm run build
# or for watch mode:
npm run dev

Nota: La extensión de Firefox no requiere un paso de construcción: utiliza JavaScript vainilla y se puede cargar directamente desde extensions/firefox/

Cargar la extensión en tu navegador:

Para navegadores Chromium (Chrome, Edge, Opera):

Abre chrome://extensions/ (Chrome), edge://extensions/ (Edge), o opera://extensions/ (Opera)
Habilita el "Modo desarrollador"
Haz clic en "Cargar extensión desempaquetada"
Selecciona la carpeta extensions/chrome/dist

Para Firefox:

Abre about:debugging#/runtime/this-firefox
Haz clic en "Cargar complemento temporal"
Selecciona cualquier archivo de la carpeta extensions/firefox

Estructura del proyecto

blueprint-mcp/
├── server/                     # MCP Server
│   ├── cli.js                  # Server entry point
│   ├── src/
│   │   ├── statefulBackend.js  # Connection state management
│   │   ├── unifiedBackend.js   # MCP tool implementations
│   │   ├── extensionServer.js  # WebSocket server for extension
│   │   ├── mcpConnection.js    # Proxy/relay connection handling
│   │   ├── transport.js        # Transport abstraction layer
│   │   ├── oauth.js            # OAuth2 client for PRO features
│   │   └── fileLogger.js       # Debug logging
│   └── tests/                  # Server test suites
├── extensions/                 # Browser Extensions
│   ├── chrome/                 # Chrome extension (TypeScript + Vite)
│   │   └── src/
│   │       ├── background.ts   # Extension service worker
│   │       ├── content-script.ts # Page content injection
│   │       └── utils/          # Utility functions
│   ├── firefox/                # Firefox extension (Vanilla JS)
│   │   └── src/
│   │       ├── background.js   # Service worker
│   │       └── content-script.js # Page injection
│   ├── shared/                 # Shared code between extensions
│   └── build-*.js              # Build scripts for each browser
├── docs/                       # Documentation
│   ├── testing/                # Test documentation
│   ├── architecture/           # Architecture docs
│   └── stores/                 # Browser store assets
└── releases/                   # Built extensions for distribution
    ├── chrome/
    ├── firefox/
    ├── edge/
    └── opera/

Pruebas

# Run tests
npm test

# Run with coverage
npm run test:coverage

Documentación:

Procedimientos de prueba manuales - Guía completa de pruebas manuales
Especificación de funciones - Documentación completa de funciones
Progreso de pruebas - Estado actual de la cobertura de pruebas

Configuración

El servidor funciona nada más instalarlo con valores predeterminados sensatos. Para configuración avanzada:

Variables de entorno

Crea un archivo .env en la raíz del proyecto:

# Authentication server (PRO features)
AUTH_BASE_URL=https://blueprint-mcp.railsblueprint.com

# Local WebSocket port (Free tier)
MCP_PORT=5555

# Debug mode
DEBUG=false

Opciones de línea de comandos

blueprint-mcp --debug              # Enable verbose logging
blueprint-mcp --port 8080          # Use custom WebSocket port (default: 5555)
blueprint-mcp --debug --port 8080  # Combine options

Nota: Si cambias el puerto, necesitarás actualizar la configuración de la extensión del navegador para que coincida.

Solución de problemas

La extensión no se conecta

Verifica que la extensión esté instalada y habilitada
Haz clic en el icono de la extensión: debería mostrar "Conectado"
Verifica que el servidor MCP esté en ejecución (busca el proceso en el puerto 5555)
Intenta recargar la extensión

"El puerto 5555 ya está en uso"

Otra instancia está en ejecución. Puedes:

Terminar el proceso existente:

lsof -ti:5555 | xargs kill -9

Usar un puerto diferente:

blueprint-mcp --port 8080

Las herramientas del navegador no funcionan

Asegúrate de haber llamado primero a enable
Verifica que te hayas adjuntado a una pestaña con browser_tabs
Verifica que la pestaña aún exista (no se haya cerrado)

Obtener ayuda

Contribuciones

¡Agradecemos las contribuciones! Consulta CONTRIBUTING.md para conocer las directrices.

Seguridad

Esta herramienta otorga a los asistentes de IA control sobre tu navegador. Por favor, revisa:

El servidor MCP solo acepta conexiones locales por defecto (localhost:5555)
Las conexiones del relé PRO se autentican mediante OAuth
La extensión requiere una acción explícita del usuario para conectarse
Todas las acciones del navegador pasan por el sistema de permisos del navegador

¿Encontraste un problema de seguridad? Por favor, envía un correo a [email protected] en lugar de presentar una incidencia pública.

Créditos

Este proyecto se inspiró originalmente en la implementación de Playwright MCP de Microsoft, pero se ha reescrito por completo para utilizar la automatización basada en extensiones del navegador en lugar de Playwright. La arquitectura, implementación y enfoque son fundamentalmente diferentes.

Diferencias clave:

Utiliza extensiones del navegador con el Protocolo DevTools (no Playwright)
Funciona con perfiles de navegador reales (no contextos aislados)
Comunicación basada en WebSocket (no retransmisión CDP)
Opción de relé en la nube para acceso remoto
Modelo de niveles Gratuito y PRO
Soporte para múltiples navegadores (Chrome, Firefox, Edge, Opera)

Agradecemos al equipo de Playwright por ser pioneros en la automatización del navegador a través de MCP.

Licencia

Licencia Apache 2.0 - consulta LICENSE

Creado con ❤️ por Rails Blueprint

Sitio web • GitHub • NPM