Peekaboo

🚀 Peekaboo MCP: 瞬間撮影、超常現象のような高速スクリーンショット

このアプリケーションは、macOSの画面を高速にキャプチャし、AIによる画像解析を行うことができるユーティリティです。開発者やエンジニアが、UIバグの特定やデザインレビューなどの作業を効率的に行うのに役立ちます。

このアプリケーションは、macOSの画面を高速にキャプチャし、AIによる画像解析を行うことができるユーティリティです。開発者やエンジニアが、UIバグの特定やデザインレビューなどの作業を効率的に行うのに役立ちます。

🚀 クイックスタート

AIアシスタントに画面を見せることができないので、UIバグの説明が難しいということはありませんか？Peekabooは、そんな問題を解決します！このユーティリティは、macOSの画面を高速にキャプチャし、AIによる画像解析を行うことができます。

インストール

1. 前提条件:

   • macOS 14.0以降
   • Node.js 20.0以降

2. Peekabooの起動: Claude Desktopの設定ファイルに以下の設定を追加します。

{
  "mcpServers": {
    "peekaboo": {
      "command": "npx",
      "args": [
        "-y",
        "@steipete/peekaboo-mcp@beta"
      ],
      "env": {
        "PEEKABOO_AI_PROVIDERS": "ollama/llava:latest"
      }
    }
  }
}

3. Claude Desktopの再起動: 設定を反映するために、Claude Desktopを再起動します。

使い方

Peekabooが起動したら、AIアシスタントが画面を見ることができるようになります。以下のようなコマンドを使って、画像のキャプチャや解析を行うことができます。

画像のキャプチャ

{
  "tool_name": "image",
  "arguments": {
    "mode": "screen",
    "path": "~/Desktop/myscreen.png",
    "format": "png"
  }
}

画像の解析

{
  "tool_name": "analyze",
  "arguments": {
    "image_path": "~/Desktop/myscreen.png",
    "question": "What is the main color visible in the top-left quadrant?"
  }
}

✨ 主な機能

• 高速なスクリーンショット: macOSの画面を高速にキャプチャすることができます。
• AIによる画像解析: キャプチャした画像をAIに解析させることができます。
• 多様なキャプチャモード: 画面全体、特定のアプリケーションのウィンドウ、またはアプリケーションのすべてのウィンドウをキャプチャすることができます。
• 多様なフォーマット: PNG、JPEG、WebP、HEIFなどのフォーマットで画像を保存することができます。
• 自動的な権限確認: 画面キャプチャに必要な権限を自動的に確認します。

📦 インストール

前提条件

• macOS 14.0以降
• Node.js 20.0以降

インストール手順

1. Claude Desktopの設定: Claude Desktopの設定ファイルに以下の設定を追加します。

{
  "mcpServers": {
    "peekaboo": {
      "command": "npx",
      "args": [
        "-y",
        "@steipete/peekaboo-mcp@beta"
      ],
      "env": {
        "PEEKABOO_AI_PROVIDERS": "ollama/llava:latest"
      }
    }
  }
}

2. Claude Desktopの再起動: 設定を反映するために、Claude Desktopを再起動します。

オプションの設定

環境変数の設定

Peekabooは、いくつかの環境変数を使って設定することができます。以下は、設定可能な環境変数の一覧です。

{
  "PEEKABOO_AI_PROVIDERS": "ollama/llava:latest,openai/gpt-4o",
  "PEEKABOO_LOG_LEVEL": "debug",
  "PEEKABOO_LOG_FILE": "~/Library/Logs/peekaboo-mcp-debug.log",
  "PEEKABOO_DEFAULT_SAVE_PATH": "~/Pictures/PeekabooCaptures",
  "PEEKABOO_CONSOLE_LOGGING": "true",
  "PEEKABOO_CLI_PATH": "/opt/custom/peekaboo"
}

環境変数の説明

Ollamaのインストール

Ollamaは、サクションをクラウドに送信せずに、ローカルで画像を解析することができる強力なAIを提供します。以下の手順で、Ollamaをインストールします。

macOS (Homebrew経由)

brew install ollama

Ollamaアプリのダウンロード

ollama.aiにアクセスし、macOS用のアプリをダウンロードします。

Ollamaデーモンの起動

ollama serve

ビジョンモデルのダウンロード

高性能マシン用

LLaVA (Large Language and Vision Assistant) は、推奨されるモデルです。

# 最新のLLaVAモデルをダウンロード (最良の品質を推奨)
ollama pull llava:latest

# 代替のLLaVAバージョン
ollama pull llava:7b-v1.6
ollama pull llava:13b-v1.6  # より大きく、より強力
ollama pull llava:34b-v1.6  # 最も大きく、最も強力 (大量のRAMが必要)

低性能マシン用

Qwen2-VLは、低いリソース要件で優れたパフォーマンスを提供します。

# Qwen2-VL 7Bモデルをダウンロード (品質とパフォーマンスのバランスが良い)
ollama pull qwen2-vl:7b

モデルサイズガイド

• qwen2-vl:7b - 約4GBのダウンロード、約6GBのRAMが必要 (軽量マシンに最適)
• llava:7b - 約4.5GBのダウンロード、約8GBのRAMが必要
• llava:13b - 約8GBのダウンロード、約16GBのRAMが必要
• llava:34b - 約20GBのダウンロード、約40GBのRAMが必要

PeekabooとOllamaの設定

Claude Desktopの設定ファイルにOllamaを追加します。

高性能マシン用

{
  "mcpServers": {
    "peekaboo": {
      "command": "npx",
      "args": [
        "-y",
        "@steipete/peekaboo-mcp@beta"
      ],
      "env": {
        "PEEKABOO_AI_PROVIDERS": "ollama/llava:latest"
      }
    }
  }
}

低性能マシン用 (Qwen2-VLを使用)

{
  "mcpServers": {
    "peekaboo": {
      "command": "npx",
      "args": [
        "-y",
        "@steipete/peekaboo-mcp@beta"
      ],
      "env": {
        "PEEKABOO_AI_PROVIDERS": "ollama/qwen2-vl:7b"
      }
    }
  }
}

複数のAIプロバイダ (Ollama + OpenAI)

{
  "env": {
    "PEEKABOO_AI_PROVIDERS": "ollama/llava:latest,openai/gpt-4o",
    "OPENAI_API_KEY": "your-api-key-here"
  }
}

Ollama統合のテスト

Ollamaの実行確認

# Ollamaが実行中であることを確認
curl http://localhost:11434/api/tags

# Peekabooで直接テスト (画像キャプチャのみ)
./peekaboo image --app Finder --path ~/Desktop/finder.png

# Peekabooで直接テスト (画像キャプチャと解析 - Peekabooが実行される環境でPEEKABOO_AI_PROVIDERSが設定されている必要があります)
# 注意: CLI自体は質問を受け取りません。これはMCPサーバの機能です。
# MCPサーバは: ./peekaboo image ... (画像を取得するため) を呼び出し、
# その後、MCPの 'image' ツールの入力に質問が含まれている場合、内部的にAIプロバイダを呼び出します。

権限の付与

Peekabooは、macOSの特定の権限を必要とします。以下の手順で、必要な権限を付与します。

画面キャプチャの権限

1. システム環境設定 → セキュリティとプライバシー → プライバシーを開きます。
2. 左側のサイドバーから画面録画を選択します。
3. ロックアイコンをクリックし、パスワードを入力します。
4. + をクリックし、ターミナルアプリケーションまたはMCPクライアントを追加します。
5. アプリケーションを再起動します。

アクセシビリティの権限 (オプション)

ウィンドウにコマンドを送信するためには、アクセシビリティの権限が必要です。

1. システム環境設定 → セキュリティとプライバシー → プライバシーを開きます。
2. 左側のサイドバーからアクセシビリティを選択します。
3. ターミナル/MCPクライアントアプリケーションを追加します。

Peekabooの起動確認

以下のコマンドを使って、Peekabooが正常に起動していることを確認します。

# Swift CLIのヘルプを表示
./peekaboo --help

# サーバの状態を確認
./peekaboo list server_status --json-output

# 画像のキャプチャ (権限が必要)
./peekaboo image --mode screen --format png

# テスト用のポータルを開く
peekaboo-mcp

💻 使用例

画像のキャプチャ

{
  "tool_name": "image",
  "arguments": {
    "mode": "screen",
    "path": "~/Desktop/myscreen.png",
    "format": "png"
  }
}

画像の解析

{
  "tool_name": "analyze",
  "arguments": {
    "image_path": "~/Desktop/myscreen.png",
    "question": "What is the main color visible in the top-left quadrant?"
  }
}

実行中のアプリケーションの一覧表示

{
  "tool_name": "list",
  "arguments": {
    "item_type": "running_applications"
  }
}

📚 ドキュメント

詳細な仕様

詳細な入出力スキーマについては、docs/spec.mdを参照してください。

トラブルシューティング

一般的な問題と解決策

デバッグモードの有効化

# デバッグモードで起動
PEEKABOO_LOG_LEVEL=debug peekaboo-mcp

# 権限の確認
./peekaboo list server_status --json-output

サポート

• 📚 ドキュメント
• 🐛 問題の報告
• 💬 ディスカッション

🔧 技術詳細

アーキテクチャ

Peekaboo/
├── src/                      # Node.js MCP Server (TypeScript)
│   ├── index.ts             # Main MCP server entry point
│   ├── tools/               # Individual tool implementations
│   │   ├── image.ts         # Screen capture tool
│   │   ├── analyze.ts       # AI analysis tool  
│   │   └── list.ts          # Application/window listing
│   ├── utils/               # Utility modules
│   │   ├── peekaboo-cli.ts   # Swift CLI integration
│   │   ├── ai-providers.ts  # AI provider management
│   │   └── server-status.ts # Server status utilities
│   └── types/               # Shared type definitions
├── peekaboo-cli/            # Native Swift CLI
│   └── Sources/peekaboo/    # Swift source files
│       ├── main.swift       # CLI entry point
│       ├── ImageCommand.swift    # Image capture implementation
│       ├── ListCommand.swift     # Application listing
│       ├── Models.swift          # Data structures
│       ├── ApplicationFinder.swift   # App discovery logic
│       ├── WindowManager.swift      # Window management
│       ├── PermissionsChecker.swift # macOS permissions
│       └── JSONOutput.swift        # JSON response formatting
├── package.json             # Node.js dependencies
├── tsconfig.json           # TypeScript configuration
└── README.md               # This file

JSON出力

Swift CLIを --json-output オプションで呼び出すと、構造化されたJSONが出力されます。

{
  "success": true,
  "data": {
    "applications": [
      {
        "app_name": "Safari",
        "bundle_id": "com.apple.Safari", 
        "pid": 1234,
        "is_active": true,
        "window_count": 2
      }
    ]
  },
  "debug_logs": ["Found 50 applications"]
}

MCPサーバの機能

• スキーマ検証: Zodを使用して、入力データの検証を行います。
• エラーハンドリング: 適切なMCPエラーコードを使用して、エラーをハンドリングします。
• ロギング: Pinoロガーを使用して、サーバのログを記録します。
• 型安全: TypeScriptを使用して、コードベース全体で型安全を保証します。

権限の管理

Peekabooは、macOSのセキュリティを尊重し、画面キャプチャ操作の前に画面録画の権限をチェックします。権限がない場合、エラーメッセージを表示し、ユーザーに必要な権限を付与するように誘導します。

📄 ライセンス

このプロジェクトは、MITライセンスの下でライセンスされています。詳細については、LICENSE ファイルを参照してください。

🧛 コントリビューション

1. リポジトリをフォークします。
2. 新しいフィーチャブランチを作成します (git checkout -b feature/amazing-feature)。
3. 変更をコミットします (git commit -m 'Add amazing feature')。
4. ブランチにプッシュします (git push origin feature/amazing-feature)。
5. プルリクエストを作成します。

🎃 Peekabooがあなたのコマンドを待っています！ このスペクトラルサーバは、macOSの禁断APIとNode.jsのエーテル領域の間のベールを越え、あなたに魂をキャプチャし、その秘密を解き明かす力を与えます。ハッピーハンティング！ 👻