MCP Safari Screenshot

🚀 Safari 截图工具

这是一个 Node.js MCP 服务器，专门用于在 macOS 系统上借助 Safari 浏览器捕获网页截图。它能满足不同场景下的截图需求，为用户提供便捷的截图服务。

🚀 快速开始

该工具使用简单，只需按照以下步骤操作，就能轻松在 macOS 上使用 Safari 进行截图。

✨ 主要特性

• 灵活的窗口大小：可捕获特定大小窗口的截图，满足不同尺寸设备的展示需求。
• 多样的缩放级别：支持不同的缩放级别，方便查看不同比例的页面内容。
• 可配置等待时间：页面加载等待时间可配置，确保能完整捕获页面内容。
• 自动清理机制：捕获截图后会自动清理，保持系统整洁。
• 高质量截图：提供原生 macOS 截图质量，保证图片清晰。

📦 安装指南

在满足需求的环境下，使用以下命令进行安装：

npm install safari-screenshot

💻 使用示例

基础用法

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, // 等待更长时间以捕获 HD 内容
	zoomLevel: 0.8, // 略微缩小
});

📚 详细文档

需求

• 系统环境：macOS 系统。
• 浏览器：Safari 浏览器。
• Node.js 版本：Node.js >= 14.0.0。
• 权限要求：终端需要辅助功能权限（系统设置 → 安全与隐私 → 隐私 → 辅助功能）。

选项

常见视口大小

该模块针对以下常见视口大小进行了测试：

• 台式机：1920×1080（全高清）
• 笔记本电脑：1366×768
• 平板电脑：1024×768
• 手机：375×667

工作原理

1. 发现功能
   • MCP 服务器向 Cursor 代理报告其 capabilities。
   • 返回支持的工具和参数。
2. 执行截图
   • 当收到带有 take_screenshot 类型的请求时，MCP 服务器执行以下步骤：
     • 打开 Safari 并设置必要的偏好。
     • 使用 seleniumWebDriver 控制 Safari 浏览器。
     • 等待页面加载（可配置）。
     • 捕获截图并保存到指定位置。

示例

1. 测试发现

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

期望的响应：

{
    "type": "capabilities",
    "tools": [
        {
            "name": "take_screenshot",
            "parameters": ["url", "outputPath", "waitTime", "zoomLevel"]
        }
    ]
}

2. 执行截图

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

期望的结果：

• 截图保存到 ./screenshots/ 目录。
• 通过 requestId 返回结果。

故障排除

如果遇到问题，可按以下步骤排查：

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

本地测试

可以直接测试 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. 发现将返回 capabilities。
2. 执行将：
   • 将进度日志记录到 stderr。
   • 将结果 JSON 返回到 stdout。
   • 将截图保存到 ./screenshots/。

🔧 技术细节

该工具基于 Node.js 构建 MCP 服务器，利用 seleniumWebDriver 控制 Safari 浏览器进行截图操作。MCP 服务器通过与 Cursor 代理交互，实现功能发现和截图执行。在执行截图时，会根据用户配置的参数，打开指定 URL 的页面，等待页面加载完成后进行截图并保存。

📄 许可证

本项目采用 MIT 许可证。