内容
# Safari 截图
一个用于在 macOS 上使用 Safari 捕获截图的 Node.js MCP Server。
## 特性
- 以特定尺寸捕获窗口截图
- 支持不同的缩放级别
- 可配置的页面加载等待时间
- 捕获后进行清理
- 原生 macOS 截图质量
## 使用方法
```javascript
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, // 全高清宽度
height: 1080, // 全高清高度
waitTime: 5, // 更长时间等待高清内容
zoomLevel: 0.8, // 略微缩小
});
```
## 需求
- macOS
- Safari
- Node.js >= 14.0.0
- 终端需要无障碍权限(系统偏好设置 → 安全性与隐私 → 隐私 → 无障碍)
## 安装
```bash
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(全高清)
- 笔记本: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. 将 Terminal(或您的 IDE)添加到允许的应用程序列表中
## 使用光标(Cursor)
### 在 Cursor 中设置
1. 打开 Cursor
2. 进入设置,选择“添加 MCP Server”
3. 在配置对话框中:
- 名称: `safari-screenshot`
- 类型: `command`
- 命令: `npx -y @rogerheykoop/mcp-safari-screenshot`
或者用于本地开发:
- 命令: `npx -y /path/to/mcp-safari-screenshot/server.js`
### 示例命令
连接到Cursor中的服务器后,您可以使用以下命令:
```
以桌面大小截取 https://apple.com 的屏幕截图
```
响应:将以 1920×1080 捕获
```
在 iPhone 12 Pro 上截取 https://apple.com
```
响应:将以 390×844 捕获
```
以 50% 缩放截取 github.com 的屏幕截图
```
响应:将以 zoomLevel: 0.5 捕获
### 支持的参数
MCP Server 理解以下概念:
- 设备名称(例如,“iPhone”,“iPad”,“desktop”)
- 尺寸(例如,“1024x768”)
- 缩放级别(例如,“50% zoom”,“2x zoom”)
- 等待时间(例如,“wait 5 seconds”)
### 示例工作流程
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实现:
```bash
```
# 测试发现
echo '{"type":"discover"}' | npx -y ./server.js
# 测试截图
```bash
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/