Safari 截图

一个 Node.js MCP 服务器，用于使用 macOS 上的 Safari 浏览器捕获屏幕截图。

功能

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

用法

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

// 基本窗口截图
await takeScreenshot({
	url: 'https://www.apple.com',
	outputPath: './screenshot.png',
	width: 1024, // 可选：窗口宽度（默认：1024）
	height: 768, // 可选：窗口高度（默认：768）
	waitTime: 3, // 可选：页面加载等待秒数（默认：3）
	zoomLevel: 1, // 可选：页面缩放级别（默认：1）
});

// 响应式设计测试
await takeScreenshot({
	url: 'https://www.apple.com',
	outputPath: './mobile.png',
	width: 375, // iPhone SE 宽度
	height: 667, // iPhone SE 高度
	zoomLevel: 1,
});

// 高分辨率捕获
await takeScreenshot({
	url: 'https://www.apple.com',
	outputPath: './desktop-hd.png',
	width: 1920, // Full HD 宽度
	height: 1080, // Full HD 高度
	waitTime: 5, // 等待更长时间加载 HD 内容
	zoomLevel: 0.8, // 稍微缩小
});

要求

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

安装

npm install safari-screenshot

选项

选项	类型	默认值	描述
url	string	必需	要捕获的 URL
outputPath	string	自动	保存屏幕截图的位置（默认：./screenshots/[hostname]-[timestamp].png）
width	number	1024	窗口宽度，以像素为单位
height	number	768	窗口高度，以像素为单位
waitTime	number	3	页面加载等待秒数
zoomLevel	number	1	页面缩放级别（1 = 100%）

常用视口尺寸

该模块已使用以下常用视口尺寸进行测试：

• 桌面：1920×1080 (Full HD)
• 笔记本电脑：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

响应：将以 zoomLevel: 0.5 捕获

支持的参数

MCP 服务器理解以下概念：

• 设备名称（例如，“iPhone”、“iPad”、“desktop”）
• 尺寸（例如，“1024x768”）
• 缩放级别（例如，“50% zoom”、“2x zoom”）
• 等待时间（例如，“wait 5 seconds”）

示例工作流程

1. 响应式测试

   Take screenshots of apple.com on iPhone, iPad, and desktop
   

2. 缩放测试

   Capture github.com at 75% zoom and 125% zoom
   

3. 自定义尺寸

   Screenshot example.com at 1440x900
   

提示

• 屏幕截图默认保存到 screenshots 目录
• 设备名称自动设置适当的尺寸
• 服务器处理 Safari 浏览器窗口的清理
• 对于加载缓慢的页面，请使用“wait X seconds”

故障排除

如果遇到问题：

1. 检查终端是否具有辅助功能权限
2. 验证 Safari 浏览器是否未处于无痕浏览模式
3. 确保工作目录可写
4. 检查 Cursor 的控制台是否有错误消息

许可证

MIT

本地测试

您可以直接测试 MCP 实现：

# 测试发现
echo '{"type":"discover"}' | npx -y ./server.js

# 测试截图
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/