Vibe-Eyes

一个MCP服务器，通过矢量化画布可视化和调试信息，使LLMs能够“看到”基于浏览器的游戏和应用程序中正在发生的事情。

<img src="./happy.jpg" width="50%" alt="Vibe-Eyes Logo">

Vibe-Eyes采用客户端-服务器架构，轻量级的浏览器客户端捕获画布内容和调试信息，通过WebSockets将其发送到Node.js服务器，然后将图像矢量化为紧凑的SVG表示，并通过模型上下文协议（MCP）提供给LLMs。

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

注意：此项目是实验性的，旨在通过提供视觉上下文和丰富的调试信息来增强与LLMs的“vibe编码”会话。

视频解释

主要功能

• 捕获并矢量化来自浏览器游戏的画布元素
• 实时收集控制台日志和错误
• 捕获带有完整堆栈跟踪的未处理异常
• 通过MCP使视觉和调试信息对LLMs可用
• 为使用LLMs工作的开发者创建无缝的调试体验

工作原理

1. 轻量级客户端在浏览器游戏/应用程序中运行
2. 客户端捕获画布快照、控制台日志/错误以及未处理的异常
3. 数据通过WebSocket发送至Vibe-Eyes服务器（避免CORS问题）
4. 服务器将画布图像矢量化，并与调试信息一起存储
5. LLMs通过模型上下文协议连接以访问最新数据
6. LLMs可以“看到”正在发生的情况，并利用完整的上下文帮助调试问题

组件

1. Vibe-Eyes MCP服务器 (mcp.js)

核心服务器：

• 通过Socket.IO接收画布快照
• 将图像矢量化为紧凑的SVG表示（粗略近似）
• 存储调试信息（日志、错误、异常、时间）
• 通过模型上下文协议（MCP）公开数据
• 提供HTTP端点以直接访问
• 顺序处理图像以管理资源

2. 浏览器客户端

浏览器客户端可在vibe-eyes-client仓库获取。

一种轻量级的浏览器集成，它：

• 在页面中查找画布元素
• 作为data URLs捕获画布内容
• 拦截控制台日志和错误
• 捕获带有堆栈跟踪的全局未处理异常
• 通过WebSockets将数据发送到Vibe-Eyes服务器
• 最小化对游戏性能的影响
• 支持显式初始化以控制何时开始捕获

3. 矢量化引擎 (vectorizer.js)

高质量的SVG矢量化库，它：

• 将光栅图像转换为矢量SVG
• 优化SVG大小和清晰度
• 在减少数据大小的同时保留视觉信息

开始使用

安装

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

# Install dependencies
npm install

与LLM代理一起使用

将MCP服务器注册到您的AI代理：

# For Claude Code
claude mcp add

这使得Claude可以通过MCP使用Vibe-Eyes的功能。

与游戏/应用程序集成

将下面的英文 markdown 内容翻译成中文，保持 markdown 格式输出，原样保留全部代码块和链接内容:

通过包含所需的脚本来将客户端添加到您的浏览器应用程序中：

<!-- 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>

与 Claude 或其他 LLM 一起使用

MCP 服务器通过 Model Context Protocol (MCP) 提供了一个工具，让 LLM 能够访问最新的视觉和调试信息：

getGameDebug({ includeSvg: true/false })

LLM 将会收到：

• 应用程序的最新控制台日志和错误
• 未处理的异常及其完整的堆栈跟踪（如果发生）
• 画布的矢量化 SVG 近似图（如果 includeSvg 为 true）
• 用于将视觉状态与日志关联的时间和相关性信息

这使得 LLM 能够“看到”应用程序中正在发生的事情，并提供更好的帮助。

示例 MCP 配置（针对 Claude 代码）

要从 Claude 访问 Vibe-Eyes：

{
  "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"
    }
  ]
}

Vibe-Eyes 如何帮助“氛围编码”

传统的“氛围编码”会话要求开发人员手动截取屏幕截图并描述其应用程序中正在发生的情况。Vibe-Eyes 通过以下方式自动化了这一过程：

1. 提供视觉上下文：LLM 可以看到游戏/应用程序的实际视觉状态
2. 关联视觉和代码问题：控制台日志与视觉状态配对
3. 减少手动工作：无需手动捕获和上传屏幕截图
4. 启用实时调试：LLM 可以观察到即时的变化
5. 优化数据传输：矢量表示比屏幕截图更紧凑

性能考虑

• 浏览器客户端旨在尽量减少对应用程序性能的影响
• 创建画布数据 URL 可能会消耗大量 CPU，因此可以配置捕获频率
• WebSocket 传输避免了跨域设置中常见的 CORS 问题
• 服务器按顺序处理图像以防止过载
• SVG 矢量化在视觉准确性和大小优化之间取得平衡

直接访问 SVG

对于希望重用矢量化 SVG 输出的应用程序：

1. WebSocket 响应：服务器直接在 WebSocket 响应中包含 SVG：

   socket.on('debugCapture', (data, callback) => {
     // 捕获和处理...
     callback({
       success: true,
       id: "capture_123",
       svg: "<svg>...</svg>",  // 矢量化 SVG 
       stats: { /* 统计数据 */ }
     });
   });
   

2. HTTP 端点：通过 /latest 端点访问最新的捕获：

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

API 参考

浏览器客户端

// 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
//   }
// }

MCP 工具

// MCP tool available t…