Vibe-Eyes

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

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

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

flowchart LR
    A["浏览器游戏/应用<br/>(Canvas + JavaScript)"] -->|"捕获"| B["Vibe-Eyes 客户端<br/>(vibe-eyes-client)"]
    B -->|"WebSocket<br/>(无 CORS)"| C["Socket.IO 服务器"]
    
    subgraph server["Vibe-Eyes 服务器 (mcp.js)"]
        C -->|"处理"| D["矢量化<br/>(vectorizer.js)"]
        C -->|"存储"| E["调试数据<br/>(日志、错误、异常)"]
        D -->|"粗略 SVG"| F["MCP 工具: getGameDebug()"]
        E --> F
    end
    
    F -->|"SVG + 调试信息"| G["Claude/LLM<br/>(MCP 客户端)"]
    G -->|"调试<br/>协助"| 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

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

视频说明

主要功能

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

工作原理

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

组件

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

核心服务器，它：

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

2. 浏览器客户端

浏览器客户端可在 vibe-eyes-client repository 中找到。

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

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

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

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

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

快速入门

安装

# 克隆存储库
git clone https://github.com/monteslu/vibe-eyes.git
cd vibe-eyes

# 安装依赖项
npm install

与 LLM 代理一起使用

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

# 对于 Claude Code
claude mcp add

这使 Claude 能够通过 MCP 使用 Vibe-Eyes 功能。

与游戏/应用程序集成

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

<!-- 包含 Socket.IO 客户端 -->
<script src="https://cdn.socket.io/4.7.4/socket.io.min.js"></script>

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

<!-- 初始化客户端 -->
<script>
  // 如果用作模块，则导入初始化函数
  // import { initializeVibeEyes } from 'vibe-eyes-client';
  
  // 使用配置初始化
  const vibeEyes = initializeVibeEyes({
    // Vibe-Eyes 服务器的 WebSocket URL
    serverUrl: 'ws://localhost:8869',
    // 捕获间隔（毫秒）
    captureDelay: 1000,
    // 连接后自动开始捕获
    autoCapture: true
  });
</script>

与 Claude 或其他 LLM 一起使用

MCP 服务器公开了一个工具，供 LLM 通过模型上下文协议 (MCP) 访问最新的视觉和调试信息：

getGameDebug({ includeSvg: true/false })

LLM 将收到：

• 来自应用程序的最新控制台日志和错误
• 具有完整堆栈跟踪的未处理异常（如果发生）
• 画布的矢量化 SVG 近似值（如果 includeSvg 为 true）
• 定时和关联信息，用于将视觉状态与日志连接起来

这允许 LLM “看到”应用程序中发生的事情并提供更好的帮助。

MCP 配置示例（对于 Claude Code）

要从 Claude 访问 Vibe-Eyes：

{
  "name": "vibe-eyes",
  "url": "http://localhost:8869",
  "tools": [
    {
      "name": "getGameDebug",
      "description": "从浏览器游戏或应用程序检索最新的画布可视化和调试信息"
    }
  ]
}

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 参考

浏览器客户端

// 初始化客户端
const vibeEyes = initializeVibeEyes({
  serverUrl: 'ws://localhost:8869',
  captureDelay: 1000, // 捕获之间的毫秒数
  maxLogs: 10,        // 要存储的最大 console.log 条目数
  maxErrors: 10,      // 要存储的最大 console.error 条目数
  autoCapture: true   // 自动开始捕获
});

// 手动控制
vibeEyes.startCaptureLoop(); // 开始自动捕获
vibeEyes.stopCaptureLoop();  // 停止自动捕获
vibeEyes.captureAndSend();   // 立即触发一次捕获

// 服务器响应：
// {
//   success: true,
//   id: "capture_1234567890",
//   processedAt: 1616161616161,
//   svg: "<svg>...</svg>",  // 用于直接使用的矢量化 SVG
//   stats: {
//     vectorizeTime: 120,
//     optimizeTime: 30,
//     originalSize: 50000,
//     finalSize: 15000,
//     sizeReduction: 70
//   }
// }

MCP 工具

// LLM 可用的 MCP 工具
getGameDebug({
  includeSvg: true  // 是否包含 SVG 可视化
})

// 返回
{
  success: true,
  capture: {
    id: "capture_123456789",
    timestamp: 1616161616161,
    console_logs: [
      { timestamp: 1616161616000, data: ["Player position:", {x: 10, y: 20}] },
      // ...更多日志
    ],
    console_errors: [
      // 捕获的任何错误
    ],
    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>",  // 仅当 includeSvg 为 true 时（粗略近似）
      imageType: "png",
      stats: {
        vectorizeTime: 120,
        optimizeTime: 30,
        originalSize: 50000,
        finalSize: 15000,
        sizeReduction: 70
      }
    }
  }
}

独立矢量化器 CLI

该项目还包括一个用于矢量化单个文件的独立 CLI 工具：

# 全局安装 CLI
npm install -g vibe-eyes

# 使用 CLI
vibe-eyes-vectorize input.png output.svg

# 使用选项
vibe-eyes-vectorize photo.jpg --color-precision 10 --max-iterations 100

许可证

ISC