Vibe-Eyes

Vibe-Eyes

ベクトル化されたキャンバスの可視化とデバッグ情報を通じて、LLM がブラウザー上のゲームやアプリケーションで何が起きているかを「見られる」ようにする MCP サーバーです。

Vibe-Eyes はクライアント・サーバーアーキテクチャを採用しています。軽量なブラウザークライアントがキャンバスの内容とデバッグ情報を取得して WebSocket 経由で Node.js サーバーに送信し、サーバーが画像をコンパクトな SVG 表現にベクトル化して、Model Context Protocol（MCP）を通じて LLM が利用できるようにします。

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

注：このプロジェクトは実験的なもので、視覚的なコンテキストと詳細なデバッグ情報を提供することで、LLM を使った「バイブコーディング」セッションを強化するよう設計されています。

動画での解説

主な機能

• ブラウザーゲームのキャンバス要素を取得してベクトル化します
• コンソールログとエラーをリアルタイムで収集します
• スタックトレース全体を含めて、未処理の例外を捕捉します
• MCP を介して、視覚情報とデバッグ情報を LLM が利用できるようにします
• LLM と連携する開発者向けに、シームレスなデバッグ体験を実現します

仕組み

1. 軽量なクライアントがブラウザー上のゲーム／アプリケーションで動作します
2. クライアントがキャンバスのスナップショット、コンソールログ／エラー、未処理の例外を取得します
3. データは WebSocket 経由で Vibe-Eyes サーバーに送信されます（CORS の問題を回避します）
4. サーバーがキャンバス画像をベクトル化し、デバッグ情報とともに保存します
5. LLM は Model Context Protocol 経由で接続し、最新のデータにアクセスします
6. LLM は何が起きているかを「見て」、すべてのコンテキストを踏まえて問題のデバッグを支援できます

コンポーネント

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

中核となるサーバーで、以下の機能を備えています。

• Socket.IO 経由でキャンバスのスナップショットを受信します
• 画像をコンパクトな SVG 表現にベクトル化します（概算です）
• デバッグ情報（ログ、エラー、例外、タイミング）を保存します
• Model Context Protocol（MCP）経由でデータを公開します
• 直接アクセスできる HTTP エンドポイントを提供します
• リソースを管理するため、画像を順次処理します

2. ブラウザークライアント

ブラウザークライアントは、vibe-eyes-client リポジトリで利用できます。

以下の機能を備えた軽量なブラウザー連携機能です。

• ページ内のキャンバス要素を検出します
• キャンバスの内容をデータ URL として取得します
• コンソールログとエラーを横取りします
• スタックトレース付きで、グローバルな未処理の例外を捕捉します
• WebSocket 経由で Vibe-Eyes サーバーにデータを送信します
• ゲームへのパフォーマンス上の影響を最小限に抑えます
• 取得を開始するタイミングを制御できるよう、明示的な初期化をサポートします

3. ベクトル化エンジン (vectorizer.js)

高品質な SVG ベクトル化ライブラリで、以下の機能を備えています。

• ラスター画像をベクター SVG に変換します
• サイズと明瞭さを最適化した SVG を生成します
• データサイズを削減しながら、視覚情報を保持します

はじめに

インストール

Smithery 経由でのインストール

Smithery 経由で Claude Desktop に Vibe-Eyes を自動インストールするには、以下を実行します。

npx -y @smithery/cli install @monteslu/vibe-eyes --client claude

手動インストール

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

# Install dependencies
npm install

LLM エージェントでの使用

AI エージェントに MCP サーバーを登録します。

# For Claude Code
claude mcp add

これにより、Claude は MCP 経由で Vibe-Eyes の機能を利用できるようになります。

ゲーム／アプリケーションへの統合

必要なスクリプトを読み込んで、クライアントをブラウザーアプリケーションに追加します。

<script src="https://cdn.socket.io/4.7.4/socket.io.min.js"></script>


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


<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 サーバーは、LLM が Model Context Protocol（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": "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 レスポンス：サーバーは SVG を WebSocket レスポンスに直接含めます。

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

2. HTTP エンドポイント：/latest エンドポイントから最新のキャプチャにアクセスします。

   fetch('http://localhost:8869/latest')
     .then(res => res.json())
     .then(data => {
       const svg = data.vectorized?.svg;
       // Use the 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 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

このプロジェクトには、個別のファイルをベクトル化するスタンドアロンの CLI ツールも含まれています。

# 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

ライセンス

ISC