金大哥 - mcp-safari-screenshot MCP 详情

article

README

🚀 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。
权限要求：终端需要辅助功能权限（系统设置 → 安全与隐私 → 隐私 → 辅助功能）。

选项

| 属性 | 详情 | |------|------| | url | 要捕获的 URL，必填项 | | outputPath | 截图保存的位置，默认值为 ./screenshots/[hostname]-[timestamp].png | | width | 窗口宽度（以像素为单位），默认值为 1024 | | height | 窗口高度（以像素为单位），默认值为 768 | | waitTime | 等待页面加载的秒数，默认值为 3 | | zoomLevel | 页面缩放级别（1 = 100%），默认值为 1 |

常见视口大小

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

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

工作原理

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

示例

测试发现

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

期望的响应：

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

执行截图

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

期望的结果：

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

故障排除

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

检查终端是否有辅助功能权限。
确保 Safari 不处于隐私浏览模式。
确保工作目录可写。
检查 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

期望的响应：

发现将返回 capabilities。
执行将：
- 将进度日志记录到 stderr。
- 将结果 JSON 返回到 stdout。
- 将截图保存到 ./screenshots/。

🔧 技术细节

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

📄 许可证

本项目采用 MIT 许可证。

mcp-safari-screenshot