Peekaboo

开发

🚀 Peekaboo MCP：极速截图，宛如超自然体验

Peekaboo MCP 是一款 macOS 实用工具，它能像幽灵般迅速捕捉屏幕快照，并借助超自然的 AI 视觉洞察窗口内容。它赋予 AI 助手真正的视觉能力，让它们能像人类一样“看到”你所描述的内容，从而在 bug 排查、设计审查、数据可视化分析等场景中发挥重要作用。

🚀 快速开始

需求

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

重启 Claude Desktop

完成以上步骤后，Peekaboo 就会从数字世界中“现身”，准备好为你服务啦！👻

✨ 主要特性

为 AI 赋予视觉能力

🐛 精准定位 Bug：让 AI 能直观看到布局问题，快速定位 bug。
📸 即时分析：一键截图并提出问题，AI 即刻分析。
🎨 设计审查：AI 依据可视化证据评估你的 CSS 设计。
📊 数据洞察：AI 能解读图表数据，提供深入分析。
🖼️ UI 测试：确保应用在不同设备上显示正常，避免“在我电脑上正常”的问题。
📱 多屏捕获：随时捕获任意窗口、应用的屏幕内容。
🤖 自动化操作：让 AI 看到你所看到的，自动修复问题。

超自然的视觉捕获能力

多屏独立捕获：分别捕获每个显示屏的内容。
精准窗口定位：通过模糊匹配精准定位应用或窗口。
多种格式支持：支持 PNG、JPEG、WebP、HEIF 等多种图像格式。
智能命名规则：提供临时文件名和描述性命名。
权限自动检测：自动验证屏幕录制权限。

强大的管理功能

应用全面统计：列出所有运行的应用程序及其详细信息。
窗口精准查询：查询每个应用的窗口信息和元数据。
灵活匹配方式：通过部分名称、Bundle ID 或进程 ID 匹配应用。
状态实时监控：监控应用的活动状态和窗口数量。

广泛的 AI 集成

多 AI 支持：支持 Ollama 和 OpenAI，未来计划支持 Anthropic 等更多 AI 服务。
图像智能分析：通过自然语言查询分析捕获的图像内容。
灵活配置选项：通过环境变量选择 AI 提供商。

📦 安装指南

安装 Ollama

macOS（通过 Homebrew）

brew install ollama

你也可以访问 ollama.ai 下载 macOS 应用。

启动 Ollama 服务：

ollama serve

默认情况下，服务将在 http://localhost:11434 运行。

下载视觉模型

高性能设备推荐：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  # 最大、性能最强（需要大量内存）

低性能设备推荐：Qwen2-VL

# 下载 Qwen2-VL 7B 模型（性能与质量的平衡之选）
ollama pull qwen2-vl:7b

模型大小参考：

qwen2-vl:7b - 约 4GB 下载，约 6GB 内存要求（适合低配置设备）
llava:7b - 约 4.5GB 下载，约 8GB 内存要求
llava:13b - 约 8GB 下载，约 16GB 内存要求
llava:34b - 约 20GB 下载，约 40GB 内存要求

配置 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_AI_PROVIDERS 环境变量）
# 注意：CLI 本身不支持输入问题，这是 MCP 服务器的功能。
# MCP 服务器会先调用：./peekaboo image ... 获取图像
# 然后根据输入的问题调用 AI 提供商进行分析

授予必要权限

Peekaboo 需要以下 macOS 权限才能正常工作：

1. 屏幕录制权限

操作步骤：

打开 系统偏好设置 → 隐私与安全性 → 隐私。
选择左侧边栏的 屏幕录制。
点击 锁图标，输入密码解锁。
点击 + 号，添加你的终端应用或 MCP 客户端。
重启应用。

支持的应用：

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

2. 辅助功能权限（可选）

若要对窗口进行操作，需要授予此权限：

打开 系统偏好设置 → 隐私与安全性 → 隐私。
选择左侧边栏的 辅助功能。
添加你的终端或 MCP 客户端应用。

验证 Peekaboo 是否正常运行

# 查看 Peekaboo 帮助信息
./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"
}
}
}

💻 使用示例

🖼️ `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 会直接返回图像数据，方便 AI 分析，同时也会告知图像的保存位置（如果指定了路径）。

捕获 Google Chrome 的所有窗口并将其置于前台

{
"tool_name": "image",
"arguments": {
"app": "Google Chrome",
"mode": "multi",
"capture_focus": "foreground",
"path": "~/Desktop/ChromeWindows/"
}
}

👁️ `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"
}
}

🔮 `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_AI_PROVIDERS`	逗号分隔的 `provider_name/default_model_for_provider` 列表，指定可用的 AI 提供商和默认模型。例如：`"openai/gpt-4o,ollama/llava:7b"`。推荐使用 `ollama/llava:latest` 以获得最佳视觉分析效果。	`""`（无）
`PEEKABOO_LOG_LEVEL`	日志级别（trace, debug, info, warn, error, fatal）。	`info`
`PEEKABOO_LOG_FILE`	服务器日志文件路径。如果指定目录不可写，将使用系统临时目录。	`~/Library/Logs/peekaboo-mcp.log`
`PEEKABOO_DEFAULT_SAVE_PATH`	`image` 工具保存图像的默认绝对路径。如果 `image` 工具指定了 `path` 参数，则优先使用该参数。如果两者都未设置，Swift CLI 将使用临时目录。	（无，Swift CLI 使用临时路径）
`PEEKABOO_OLLAMA_BASE_URL`	Ollama API 服务器的基础 URL。仅当 Ollama 运行在非默认地址时需要设置。	`http://localhost:11434`
`PEEKABOO_CONSOLE_LOGGING`	是否在控制台输出日志（`"true"`/`"false"`）。	`"false"`
`PEEKABOO_CLI_PATH`	可选参数，指定 Swift `peekaboo` CLI 可执行文件的路径。	（使用捆绑的 CLI）

AI 提供商配置详解

PEEKABOO_AI_PROVIDERS 环境变量是配置 Peekaboo 分析功能的关键，它决定了 analyze 工具和 image 工具（当提供 question 参数时）使用的 AI 提供商和模型。格式为逗号分隔的 provider_name/model_identifier 字符串，例如： PEEKABOO_AI_PROVIDERS="ollama/llava:latest,openai/gpt-4o,anthropic/claude-3-haiku-20240307"

provider_name：目前支持 ollama（本地 Ollama 实例）和 openai，计划支持 anthropic。
model_identifier：指定提供商使用的具体模型，如 llava:latest、gpt-4o。

analyze 工具和 image 工具（当提供 question 参数时）会根据该配置尝试使用 AI 提供商。如果 provider_config 参数设置为 "auto"（analyze 工具默认，image 工具可选），Peekaboo 会按顺序尝试 PEEKABOO_AI_PROVIDERS 中的提供商，检查所需的 API 密钥（如 OPENAI_API_KEY）或服务可用性（如 Ollama 是否在 http://localhost:11434 或 PEEKABOO_OLLAMA_BASE_URL 指定的地址运行）。

你可以通过 analyze 或 image 工具的 provider_config 参数覆盖模型选择或指定特定的提供商。系统会验证其是否可用，如 API 密钥是否存在或服务是否运行。

其他安装方式

从源码安装

# 克隆仓库
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 客户端：

使用全局安装的配置示例：

{
"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 替换为你本地项目的实际路径。同时，使用本地配置时，请确保在 MCP 客户端的服务器列表中使用唯一的键（如 "peekaboo_local" 或 "peekaboo_local_node"），以避免与 npx 安装的 "peekaboo" 服务器冲突。

使用 AppleScript 进行简单截图

# 直接运行 AppleScript
osascript peekaboo.scpt

此方法仅提供简单的截图功能，不支持 MCP 集成和 AI 分析。

其他 MCP 客户端的手动配置

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

🔧 技术细节

架构设计

Peekaboo/
├── src/                      # Node.js MCP Server (TypeScript)
│   ├── index.ts             # 主 MCP 服务器入口
│   ├── tools/               # 工具实现
│   │   ├── image.ts         # 屏幕捕获工具
│   │   ├── analyze.ts       # AI 分析工具
│   │   └── list.ts          # 应用/窗口列表工具
│   ├── utils/               # 工具模块
│   │   ├── peekaboo-cli.ts   # Swift CLI 集成
│   │   ├── ai-providers.ts  # AI 提供商管理
│   │   └── server-status.ts # 服务器状态工具
│   └── types/               # 共享类型定义
├── peekaboo-cli/            # 原生 Swift CLI
│   └── Sources/peekaboo/    # Swift 源代码
│       ├── main.swift       # CLI 入口
│       ├── ImageCommand.swift    # 图像捕获实现
│       ├── ListCommand.swift     # 应用列表实现
│       ├── Models.swift          # 数据结构
│       ├── ApplicationFinder.swift   # 应用发现逻辑
│       ├── WindowManager.swift      # 窗口管理
│       ├── PermissionsChecker.swift # macOS 权限检查
│       └── JSONOutput.swift        # JSON 响应格式化
├── package.json             # Node.js 依赖
├── tsconfig.json           # TypeScript 配置
└── README.md               # 本文件

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

协议转换与集成

Node.js 服务器负责在 MCP 的 JSON-RPC 协议和 Swift CLI 的 JSON 输出之间进行转换，提供以下功能：

Schema 验证：使用 Zod 进行输入输出验证。
错误处理：使用 MCP 标准错误码处理错误。
日志记录：使用 Pino 记录日志。
类型安全：整个 TypeScript 代码库保证类型安全。

权限管理

Peekaboo 严格遵守 macOS 安全机制：

权限检查：在进行屏幕捕获操作前检查屏幕录制权限。
优雅降级：权限缺失时，功能会优雅降级。
错误提示：提供清晰的错误信息，引导用户授予所需权限。

📄 许可证

本项目采用 MIT 许可证，详细信息请参考 LICENSE 文件。

🧛 加入我们

如果你想为 Peekaboo 贡献代码，可以按照以下步骤操作：

Fork 本仓库。
创建新的功能分支 (git checkout -b feature/amazing-feature)。
提交你的更改 (git commit -m 'Add amazing feature')。
将分支推送到远程仓库 (git push origin feature/amazing-feature)。
提交 Pull Request。

📜 可用工具（通过 MCP 服务器）

Peekaboo 作为 MCP 服务器运行时，提供以下工具：

image：捕获 macOS 屏幕内容。
- 支持捕获整个屏幕、特定应用窗口或应用的所有窗口。
- 支持多种格式和捕获模式（前台/后台）。
- 新增功能：可选地提供 question 和 provider_config 参数，对捕获的图像进行即时分析，并返回分析结果和图像详细信息。如果提供了问题，图像文件将是临时的，分析完成后会删除，除非指定了 path 参数。提问时，不会返回图像数据（Base64）。
- 完整的输入输出 Schema 请参考 docs/spec.md。
analyze：使用配置好的 AI 模型分析现有图像文件。
- 需要提供图像路径和问题。
- 使用 PEEKABOO_AI_PROVIDERS 和 provider_config 配置的 AI 提供商。
- 完整的输入输出 Schema 请参考 docs/spec.md。
list：列出系统信息，如运行的应用程序、特定应用的窗口或服务器状态。
- 完整的输入输出 Schema 请参考 docs/spec.md。

🎃 Peekaboo 随时等待你的指令！它就像一座桥梁，连接 macOS 的隐藏 API 和 Node.js 的强大功能，让你能够轻松捕获屏幕内容并深入分析。祝你使用愉快！👻

0 条评论
分类：开发