Peekaboo

🚀 Peekaboo MCP：極速截屏，宛如超自然現象

Peekaboo MCP 是一款超自然的 macOS 實用工具，它能像幽靈一樣迅速捕捉屏幕快照，並藉助超自然的 AI 視覺洞察窗口內容。有了它，你的 AI 助手將擁有真正的視覺能力，輕鬆應對各種與視覺相關的任務。

🚀 快速開始

召喚 Peekaboo 的儀式要求

• macOS 14.0+（Sonoma 或更高版本）
• Node.js 20.0+

快速召喚儀式

將 Peekaboo 召喚到你的 Agent 領域：

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

4. 重啟 Claude Desktop

完成以上步驟，Peekaboo 就會從數字世界中現身，準備好為你的屏幕服務！

✨ 主要特性

為何你的 AI 需要視覺能力

• 🐛 漏洞排查：讓 AI 真正看到佈局問題，提高排查效率。
• 📸 即時分析：一鍵截圖並提問，實現快速分析。
• 🎨 設計評審：藉助視覺證據，讓 AI 對 CSS 問題進行評估。
• 📊 數據分析：AI 能夠解讀圖表中的數據。
• 🖼️ UI 測試：確保應用在不同設備上顯示正常，避免“在我機器上正常”的問題。
• 📱 多屏幕魔法：隨時捕捉任何窗口、任何應用的畫面。
• 🤖 自動化魔法：讓 AI 看到你所看到的，然後修復問題。

Peekaboo 就像是為你的編碼助手配備的超自然隱形眼鏡，從此無需再反覆解釋“提交”按鈕的位置！

📦 安裝指南

召喚 Ollama - 本地視覺預言家

Ollama 提供了強大的本地 AI 能力，無需將數據上傳到雲端即可分析截圖。以下是召喚 Ollama 的步驟：

📦 安裝 Ollama

macOS（通過 Homebrew）：

brew install ollama

訪問 ollama.ai 並下載 macOS 應用。

啟動 Ollama 守護進程：

ollama serve

守護進程默認運行在 http://localhost:11434。

🎭 下載視覺模型

對於性能強大的機器，推薦使用 LLaVA（大型語言和視覺助手）模型：

# 下載最新的 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

將 Ollama 添加到你的 Claude Desktop 配置中：

{
  "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. 👁️ 全視之眼權限

執行權限儀式：

1. 打開 系統偏好設置 → 安全性與隱私 → 隱私
2. 從左側邊欄選擇 屏幕錄製
3. 點擊 鎖圖標 並輸入密碼
4. 點擊 + 並添加你的終端應用程序或 MCP 客戶端
5. 重啟應用程序

已知可使用 Peekaboo 的應用程序：

• Terminal.app：/Applications/Utilities/Terminal.app
• Claude Desktop：/Applications/Claude.app
• VS Code：/Applications/Visual Studio Code.app

2. 🪄 窗口低語者權限（可選）

若要對窗口發送命令並使其響應：

1. 打開 系統偏好設置 → 安全性與隱私 → 隱私
2. 從左側邊欄選擇 輔助功能
3. 添加你的終端/MCP 客戶端應用程序

驗證 Peekaboo 是否成功啟動

# 直接與 Swift 程序交互
./peekaboo --help

# 檢查服務器狀態
./peekaboo list server_status --json-output

# 進行截圖（需要權限）
./peekaboo image --mode screen --format png

# 啟動 Peekaboo 進行測試
peekaboo-mcp

預期輸出：

{
  "success": true,
  "data": {
    "swift_cli_available": true,
    "permissions": {
      "screen_recording": true
    },
    "system_info": {
      "macos_version": "14.0"
    }
  }
}

💻 使用示例

基礎用法

1. 🖼️ image - 捕捉幽靈般的視覺畫面

捕捉整個主屏幕並保存：

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

Peekaboo 會返回保存文件的詳細信息。

捕捉 Finder 的活動窗口並以 Base64 格式返回數據：

{
  "tool_name": "image",
  "arguments": {
    "app": "Finder",
    "mode": "window",
    "return_data": true,
    "format": "jpg"
  }
}

Peekaboo 會直接返回圖像數據，同時提供圖像可能保存位置的信息。

捕捉“Google Chrome”的所有窗口並將其置於前臺：

{
  "tool_name": "image",
  "arguments": {
    "app": "Google Chrome",
    "mode": "multi",
    "capture_focus": "foreground",
    "path": "~/Desktop/ChromeWindows/" // 文件將在此處命名並保存
  }
}

2. 👁️ list - 揭示隱藏的幽靈

列出所有正在運行的應用程序：

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

Peekaboo 會顯示所有活動應用程序的列表、它們的 PID 等信息。

列出“Preview”應用的所有窗口，包括其邊界和 ID：

{
  "tool_name": "list",
  "arguments": {
    "item_type": "application_windows",
    "app": "Preview",
    "include_window_details": ["bounds", "ids"]
  }
}

獲取服務器的當前狀態：

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

3. 🔮 analyze - 解讀捕捉到的精髓

使用自動配置的 AI 提供商對圖像提出問題：

{
  "tool_name": "analyze",
  "arguments": {
    "image_path": "~/Desktop/myscreen.png",
    "question": "左上角象限中可見的主要顏色是什麼？"
  }
}

Peekaboo 會諮詢其 AI 助手並返回分析結果。

強制使用 Ollama 特定模型進行分析：

{
  "tool_name": "analyze",
  "arguments": {
    "image_path": "~/Desktop/some_diagram.jpg",
    "question": "解釋這個圖表。",
    "provider_config": {
      "type": "ollama",
      "model": "llava:13b-v1.6"
    }
  }
}

高級用法

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

📚 詳細文檔

替代召喚儀式

🧪 從源代碼構建

如果你想從源代碼構建 Peekaboo，可以按照以下步驟操作：

# 克隆倉庫
git clone https://github.com/steipete/peekaboo.git
cd peekaboo

# 安裝依賴
npm install

# 構建 TypeScript 項目
npm run build

# 構建 Swift CLI
cd peekaboo-cli
swift build -c release

# 複製可執行文件
cp .build/release/peekaboo ../peekaboo

# 返回項目根目錄
cd ..

# 可選：全局安裝
npm link

然後將 Peekaboo 綁定到 Claude Desktop（或其他 MCP 客戶端）：

示例 MCP 客戶端配置（使用本地構建）： 如果你運行了 npm link 並且 peekaboo-mcp 已在你的 PATH 中：

{
  "mcpServers": {
    "peekaboo_local": {
      "command": "peekaboo-mcp",
      "args": [],
      "env": {
        "PEEKABOO_LOG_LEVEL": "debug",
        "PEEKABOO_CONSOLE_LOGGING": "true"
      }
    }
  }
}

或者直接使用 node 運行：

{
  "mcpServers": {
    "peekaboo_local_node": {
      "command": "node",
      "args": [
        "/Users/steipete/Projects/Peekaboo/dist/index.js"
      ],
      "env": {
        "PEEKABOO_LOG_LEVEL": "debug",
        "PEEKABOO_CONSOLE_LOGGING": "true"
      }
    }
  }
}

請將 /Users/steipete/Projects/Peekaboo/dist/index.js 替換為你克隆項目中 dist/index.js 的實際絕對路徑。同時，使用這些本地配置時，請確保在 MCP 客戶端的服務器列表中使用不同的鍵（如 "peekaboo_local" 或 "peekaboo_local_node"），以避免與基於 npx 的 "peekaboo" 服務器配置衝突。

🍎 古老的 AppleScript 儀式

如果你想使用簡單的方式進行截圖，可以運行古老的 AppleScript：

# 直接運行 AppleScript
osascript peekaboo.scpt

這種方式僅提供簡單的截圖功能，不包含 MCP 集成或 AI 分析功能。

其他 MCP 客戶端的手動配置

對於除 Claude Desktop 之外的 MCP 客戶端，可以使用以下配置：

{
  "server": {
    "command": "node",
    "args": ["/path/to/peekaboo/dist/index.js"],
    "env": {
      "PEEKABOO_AI_PROVIDERS": "ollama/llava,openai/gpt-4o"
    }
  }
}

可用工具（通過 MCP 服務器）

Peekaboo 在作為 MCP 服務器運行時，通過以下工具提供其功能：

• image：捕捉 macOS 屏幕內容。

  • 可以針對整個屏幕、特定應用程序窗口或應用的所有窗口進行捕捉。
  • 支持多種格式和捕捉模式（前臺/後臺）。
  • 新增功能：可以選擇提供 question 和 provider_config 來立即分析捕捉的圖像，返回分析結果和圖像詳細信息。如果提出問題，圖像文件將是臨時的，分析完成後將被刪除，除非指定了 path。如果提出問題，圖像數據（Base64）將不會返回。
  • 完整的輸入/輸出模式請參閱 docs/spec.md。

• analyze：使用配置的 AI 模型分析現有圖像文件。

  • 需要圖像路徑和問題。
  • 使用通過 PEEKABOO_AI_PROVIDERS 和 provider_config 輸入配置的 AI 提供商。
  • 完整的輸入/輸出模式請參閱 docs/spec.md。

• list：列出系統項目，如正在運行的應用程序、特定應用的窗口或服務器狀態。

  • 完整的輸入/輸出模式請參閱 docs/spec.md。

🔧 技術細節

超自然能力

🖼️ 空靈視覺捕捉

• 多屏幕捕捉：分別捕捉每個屏幕的畫面。
• 精準定位：通過模糊匹配功能，準確捕捉指定應用或窗口的畫面。
• 多種格式支持：支持 PNG、JPEG、WebP、HEIF 等多種圖像格式。
• 智能命名：根據時間和描述自動生成文件名。
• 權限檢測：自動驗證所需的權限。

👻 精靈管理

• 全面的應用列表：提供所有正在運行的應用程序的詳細信息。
• 窗口信息查詢：可以查詢每個應用程序的窗口信息和元數據。
• 模糊匹配：通過部分名稱、應用 ID 或進程號查找應用程序。
• 狀態監控：實時監控應用程序的活動狀態和窗口數量。

🧿 神諭集成

• 多神諭支持：目前支持 Ollama（通過直接 API 調用）和 OpenAI（通過其官方 Node.js SDK），未來計劃支持 Anthropic 等其他神諭。
• 圖像分析：可以使用自然語言對捕捉的圖像進行查詢和分析。
• 可配置性：通過環境變量選擇不同的 AI 提供商。

架構概述

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

技術實現細節

📜 結構化輸出

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

🌌 協議集成

Node.js 服務器在 MCP 的 JSON-RPC 協議和 Swift CLI 的 JSON 輸出之間進行轉換，提供以下功能：

• 模式驗證：使用 Zod 進行輸入驗證。
• 錯誤處理：使用適當的 MCP 錯誤代碼處理錯誤。
• 日誌記錄：使用 Pino 日誌記錄器進行日誌記錄。
• 類型安全：整個 TypeScript 代碼庫具有類型安全性。

🚪 權限管理

Peekaboo 尊重 macOS 的安全機制，在進行截圖操作前會檢查屏幕錄製權限，並在權限缺失時提供清晰的錯誤信息，引導用戶授予所需權限。

📄 許可證

本項目採用 MIT 許可證，詳細信息請參閱 LICENSE 文件。

🧛 加入社區

如果你想為 Peekaboo 項目做出貢獻，可以按照以下步驟操作：

1. Fork 倉庫
2. 創建功能分支 (git checkout -b feature/amazing-feature)
3. 提交更改 (git commit -m 'Add amazing feature')
4. 推送至分支 (git push origin feature/amazing-feature)
5. 打開 Pull Request

🎃 Peekaboo 等待你的命令！這個神秘的工具將 macOS 的隱藏 API 與 Node.js 的強大功能相結合，讓你擁有捕捉屏幕和解讀其中奧秘的能力。祝你使用愉快！👻