Safari 截图

一个使用 macOS 上的 Safari 进行截图的 Node.js MCP 服务器。

功能

• 捕获特定大小的窗口截图
• 支持不同的缩放级别
• 可配置的页面加载等待时间
• 截图后清理
• 原生 macOS 截图质量

使用方法

import { takeScreenshot } from './screenshot.js';

// Basic window screenshot
await takeScreenshot({
    url: 'https://www.apple.com',
    outputPath: './screenshot.png',
    width: 1024, // Optional: window width (default: 1024)
    height: 768, // Optional: window height (default: 768)
    waitTime: 3, // Optional: seconds to wait for load (default: 3)
    zoomLevel: 1, // Optional: page zoom level (default: 1)
});

// Responsive design testing
await takeScreenshot({
    url: 'https://www.apple.com',
    outputPath: './mobile.png',
    width: 375, // iPhone SE width
    height: 667, // iPhone SE height
    zoomLevel: 1,
});

// High-resolution capture
await takeScreenshot({
    url: 'https://www.apple.com',
    outputPath: './desktop-hd.png',
    width: 1920, // Full HD width
    height: 1080, // Full HD height
    waitTime: 5, // Wait longer for HD content
    zoomLevel: 0.8, // Zoom out slightly
});

要求

• macOS
• Safari
• Node.js >= 14.0.0
• 终端需要辅助功能权限（系统偏好设置 → 安全性与隐私 → 隐私 → 辅助功能）

安装

npm install safari-screenshot

选项

常见视口尺寸

该模块已测试以下常见视口尺寸：

• 桌面：1920×1080（全高清）
• 笔记本电脑：1366×768
• 平板横向：1024×768
• 平板纵向：768×1024
• 大屏手机：428×926（iPhone 12 Pro Max）
• 中屏手机：390×844（iPhone 12 Pro）
• 小屏手机：375×667（iPhone SE）

工作原理

1. 以指定的窗口大小打开 Safari
2. 加载 URL 并等待页面加载完成
3. 如果指定了缩放级别，则应用缩放级别
4. 使用原生 macOS 屏幕捕捉以获得完美像素的结果
5. 验证截图是否成功捕获
6. 清理 Safari 窗口

权限

此包需要系统事件权限才能工作：

1. 打开系统偏好设置 > 安全性与隐私 > 隐私 > 辅助功能
2. 将终端（或您的 IDE）添加到允许的应用程序列表中

与 Cursor 一起使用

在 Cursor 中设置

1. 打开 Cursor

2. 进入设置，选择“添加 MCP 服务器”

3. 在配置对话框中：

   • 名称：safari-screenshot
   • 类型：command
   • 命令：npx -y @rogerheykoop/mcp-safari-screenshot

   或者对于本地开发：

   • 命令：npx -y /path/to/mcp-safari-screenshot/server.js

示例命令

连接到 Cursor 中的服务器后，可以使用以下命令：

Take a screenshot of https://apple.com at desktop size

响应：将以 1920×1080 捕获

Capture https://apple.com on iPhone 12 Pro

响应：将以 390×844 捕获

Screenshot github.com at 50% zoom

响应：将以缩放级别 0.5 捕获

支持的参数

MCP 服务器理解这些概念：

• 设备名称（例如："iPhone"、"iPad"、"desktop"）
• 尺寸（例如："1024x768"）
• 缩放级别（例如："50% 缩放"、"2倍缩放"）
• 等待时间（例如："等待5秒"）

示例工作流

1. 响应式测试

   在 iPhone、iPad 和桌面设备上截取 apple.com 的屏幕截图
   

2. 缩放测试

   在 75% 缩放和 125% 缩放下截取 github.com 的屏幕截图
   

3. 自定义尺寸

   在 1440x900 分辨率下截取 example.com 的屏幕截图
   

提示

• 屏幕截图默认保存在 screenshots 目录中
• 设备名称会自动设置适当的尺寸
• 服务器负责清理 Safari 窗口
• 对于加载缓慢的页面，使用 "等待 X 秒"

故障排除

如果您遇到问题：

1. 检查终端是否具有辅助功能权限
2. 确认 Safari 不处于私密浏览模式
3. 确保工作目录可写
4. 检查 Cursor 控制台中的错误消息

许可证

MIT

本地测试

您可以直接测试 MCP 实现：

# Test discovery
echo '{"type":"discover"}' | npx -y ./server.js

# Test screenshot
echo '{"type":"execute","tool":"take_screenshot","input":"Take a screenshot of https://apple.com","requestId":"123"}' | npx -y ./server.js

预期响应：

1. Discover 将返回能力
2. Execute 将：
   • 将进度记录到 stderr
   • 将结果 JSON 返回到 stdout
   • 将屏幕截图保存到 ./screenshots/