Vibradores Ojos

Un servidor MCP que permite a los LLM "ver" lo que sucede en juegos y aplicaciones basados en navegador a través de visualización de lienzo vectorizado e información de depuración.

Vibe-Eyes utiliza una arquitectura cliente-servidor donde un cliente de navegador liviano captura el contenido del lienzo y la información de depuración, lo envía a un servidor Node.js a través de WebSockets, que luego vectoriza las imágenes en representaciones SVG compactas y las pone a disposición de los LLM a través del Protocolo de contexto de modelo (MCP).

flowchart LR
    A["Browser Game/App<br/>(Canvas + JavaScript)"] -->|"Captures"| B["Vibe-Eyes Client<br/>(vibe-eyes-client)"]
    B -->|"WebSocket<br/>(CORS-free)"| C["Socket.IO Server"]
    
    subgraph server["Vibe-Eyes Server (mcp.js)"]
        C -->|"Process"| D["Vectorization<br/>(vectorizer.js)"]
        C -->|"Store"| E["Debug Data<br/>(logs, errors, exceptions)"]
        D -->|"Rough SVG"| F["MCP Tool: getGameDebug()"]
        E --> F
    end
    
    F -->|"SVG + Debug Info"| G["Claude/LLM<br/>(MCP Client)"]
    G -->|"Debugging<br/>Assistance"| A
    
    classDef default color:#000,font-weight:bold
    classDef edgeLabel color:#333,font-size:12px
    
    style A fill:#c0e0ff,stroke:#000,stroke-width:2px
    style B fill:#ffe0a0,stroke:#000,stroke-width:2px
    style C fill:#a0d0ff,stroke:#000,stroke-width:2px
    style D fill:#b0e0a0,stroke:#000,stroke-width:2px
    style E fill:#ffb0b0,stroke:#000,stroke-width:2px
    style F fill:#d0b0ff,stroke:#000,stroke-width:2px
    style G fill:#ffb0d0,stroke:#000,stroke-width:2px
    style server fill:#f0f0f0,stroke:#666,stroke-width:1px,stroke-dasharray: 5 5,color:#000

Nota: Este proyecto es experimental y está diseñado para mejorar las sesiones de "codificación de vibraciones" con LLM al brindar contexto visual e información de depuración enriquecida.

Explicación en vídeo

Related MCP server: image-tiler-mcp-server

Capacidades clave

• Captura y vectoriza elementos del lienzo de los juegos de navegador.

• Recopila registros y errores de la consola en tiempo real

• Captura excepciones no controladas con seguimientos de pila completos

• Hace que la información visual y de depuración esté disponible para los LLM a través de MCP

• Crea una experiencia de depuración perfecta para los desarrolladores que trabajan con LLM

Cómo funciona

1. Un cliente liviano se ejecuta en el juego/aplicación del navegador.

2. El cliente captura instantáneas del lienzo, registros/errores de la consola y excepciones no controladas.

3. Los datos se envían al servidor Vibe-Eyes a través de WebSocket (evitando problemas de CORS)

4. El servidor vectoriza las imágenes del lienzo y las almacena con la información de depuración

5. Los LLM se conectan a través del Protocolo de Contexto de Modelo para acceder a los datos más recientes

6. Los LLM pueden "ver" lo que está sucediendo y ayudar a depurar problemas con contexto completo

Componentes

1. Servidor MCP Vibe-Eyes ( mcp.js )

El servidor central que:

• Recibe instantáneas del lienzo a través de Socket.IO

• Vectoriza imágenes para compactar la representación SVG (aproximación aproximada)

• Almacena información de depuración (registros, errores, excepciones, tiempos)

• Expone los datos a través del Protocolo de Contexto de Modelo (MCP)

• Proporciona puntos finales HTTP para acceso directo

• Procesa imágenes secuencialmente para administrar recursos

2. Cliente del navegador

El cliente del navegador está disponible en el repositorio vibe-eyes-client .

Una integración de navegador liviana que:

• Encuentra elementos del lienzo en la página.

• Captura el contenido del lienzo como URL de datos

• Intercepta registros y errores de la consola

• Detecta excepciones globales no controladas con seguimientos de pila

• Envía datos al servidor Vibe-Eyes a través de WebSockets

• Minimiza el impacto en el rendimiento de los juegos.

• Admite la inicialización explícita para controlar cuándo comienza la captura

3. Motor de vectorización ( vectorizer.js )

Una biblioteca de vectorización SVG de alta calidad que:

• Convierte imágenes rasterizadas en archivos SVG vectoriales

• Optimiza los SVG para mejorar el tamaño y la claridad

• Conserva la información visual mientras reduce el tamaño de los datos

Empezando

Instalación

# Clone the repository
git clone https://github.com/monteslu/vibe-eyes.git
cd vibe-eyes

# Install dependencies
npm install

Uso con agentes LLM

Registre el servidor MCP con su agente de IA:

# For Claude Code
claude mcp add

Esto le permite a Claude utilizar las capacidades de Vibe-Eyes a través de MCP.

Integración con juegos/aplicaciones

Agregue el cliente a su aplicación de navegador incluyendo los scripts necesarios:

<!-- Include Socket.IO client -->
<script src="https://cdn.socket.io/4.7.4/socket.io.min.js"></script>

<!-- Include Vibe-Eyes client -->
<script src="https://cdn.jsdelivr.net/npm/vibe-eyes-client/dist/index.min.js"></script>

<!-- Initialize the client -->
<script>
  // Import the initialization function if using as module
  // import { initializeVibeEyes } from 'vibe-eyes-client';
  
  // Initialize with configuration
  const vibeEyes = initializeVibeEyes({
    // WebSocket URL to the Vibe-Eyes server
    serverUrl: 'ws://localhost:8869',
    // Capture interval in milliseconds
    captureDelay: 1000,
    // Start capturing automatically after connection
    autoCapture: true
  });
</script>

Uso con Claude u otros LLM

El servidor MCP expone una herramienta para que los LLM accedan a la información visual y de depuración más reciente a través del Protocolo de contexto de modelo (MCP):

getGameDebug({ includeSvg: true/false })

El Máster recibirá:

• Registros y errores recientes de la consola de la aplicación

• Excepciones no controladas con seguimiento de pila completo (si se produjeron)

• Aproximación SVG vectorizada del lienzo (si includeSvg es verdadero)

• Información de tiempo y correlación para conectar el estado visual con los registros

Esto permite al LLM “ver” lo que está sucediendo en la aplicación y brindar una mejor asistencia.

Ejemplo de configuración de MCP (para Claude Code)

Para acceder a Vibe-Eyes de Claude:

{
  "name": "vibe-eyes",
  "url": "http://localhost:8869",
  "tools": [
    {
      "name": "getGameDebug",
      "description": "Retrieves the most recent canvas visualization and debug information from a browser game or application"
    }
  ]
}

Cómo Vibe-Eyes ayuda con la codificación de vibraciones

Las sesiones tradicionales de "codificación de vibraciones" requieren que los desarrolladores tomen capturas de pantalla manualmente y describan lo que sucede en su aplicación. Vibe-Eyes automatiza este proceso mediante:

1. Proporcionar contexto visual : los LLM pueden ver el estado visual real del juego/aplicación

2. Correlación de problemas visuales y de código : los registros de la consola se emparejan con el estado visual

3. Reducción del trabajo manual : no es necesario capturar ni cargar capturas de pantalla manualmente

4. Habilitación de la depuración en tiempo real : los LLM pueden observar los cambios a medida que ocurren

5. Optimización de la transferencia de datos : la representación vectorial es más compacta que las capturas de pantalla

Consideraciones de rendimiento

• El cliente del navegador está diseñado para minimizar el impacto en el rendimiento de la aplicación.

• La creación de URL de datos de lienzo puede consumir muchos recursos de la CPU, por lo que la frecuencia de captura es configurable

• El transporte WebSocket evita los problemas CORS comunes en configuraciones entre dominios

• El servidor procesa las imágenes secuencialmente para evitar la sobrecarga.

• La vectorización SVG equilibra la precisión visual con la optimización del tamaño

Acceso directo a SVG

Para aplicaciones que quieran reutilizar la salida SVG vectorizada:

1. Respuesta de WebSocket : el servidor incluye el SVG directamente en las respuestas de WebSocket:

   socket.on('debugCapture', (data, callback) => {
     // Capture and process...
     callback({
       success: true,
       id: "capture_123",
       svg: "<svg>...</svg>",  // Vectorized SVG 
       stats: { /* stats data */ }
     });
   });

2. Punto final HTTP : acceda a la última captura a través del punto final /latest :

   fetch('http://localhost:8869/latest')
     .then(res => res.json())
     .then(data => {
       const svg = data.vectorized?.svg;
       // Use the SVG...
     });

Referencia de API

Cliente de navegador

// Initialize the client
const vibeEyes = initializeVibeEyes({
  serverUrl: 'ws://localhost:8869',
  captureDelay: 1000, // ms between captures
  maxLogs: 10,        // Max console.log entries to store
  maxErrors: 10,      // Max console.error entries to store
  autoCapture: true   // Start capturing automatically
});

// Manual control
vibeEyes.startCaptureLoop(); // Start auto-capturing
vibeEyes.stopCaptureLoop();  // Stop auto-capturing
vibeEyes.captureAndSend();   // Trigger one capture immediately

// The server responds with:
// {
//   success: true,
//   id: "capture_1234567890",
//   processedAt: 1616161616161,
//   svg: "<svg>...</svg>",  // The vectorized SVG for direct use
//   stats: {
//     vectorizeTime: 120,
//     optimizeTime: 30,
//     originalSize: 50000,
//     finalSize: 15000,
//     sizeReduction: 70
//   }
// }

Herramienta MCP

// MCP tool available to LLMs
getGameDebug({
  includeSvg: true  // Whether to include SVG visualization
})

// Returns
{
  success: true,
  capture: {
    id: "capture_123456789",
    timestamp: 1616161616161,
    console_logs: [
      { timestamp: 1616161616000, data: ["Player position:", {x: 10, y: 20}] },
      // ...more logs
    ],
    console_errors: [
      // Any errors captured
    ],
    unhandled_exception: {
      timestamp: 1616161616100,
      message: "Uncaught SyntaxError: Unexpected token ';'",
      stack: "SyntaxError: Unexpected token ';'\n    at game.js:42:10\n...",
      type: "SyntaxError",
      source: "game.js",
      line: 42,
      column: 10
    },
    vectorized: {
      svg: "<svg>...</svg>",  // Only if includeSvg is true (rough approximation)
      imageType: "png",
      stats: {
        vectorizeTime: 120,
        optimizeTime: 30,
        originalSize: 50000,
        finalSize: 15000,
        sizeReduction: 70
      }
    }
  }
}

CLI del vectorizador independiente

El proyecto también incluye una herramienta CLI independiente para vectorizar archivos individuales:

# Install CLI globally
npm install -g vibe-eyes

# Use the CLI
vibe-eyes-vectorize input.png output.svg

# With options
vibe-eyes-vectorize photo.jpg --color-precision 10 --max-iterations 100

Licencia

ISC