MCP Safari Screenshot

🚀 Safari 截圖工具

這是一個基於 Node.js 的 MCP 服務器，專門用於在 macOS 系統上藉助 Safari 瀏覽器進行截圖捕獲。它能滿足多種截圖需求，為用戶提供便捷、高質量的截圖體驗。

🚀 快速開始

需求

• macOS 系統
• Safari 瀏覽器
• Node.js 版本需 >= 14.0.0
• 終端需要輔助功能權限（可通過系統設置 → 安全與隱私 → 隱私 → 輔助功能進行設置）

安裝

npm install safari-screenshot

✨ 主要特性

• 靈活的窗口尺寸：可捕獲特定大小窗口的截圖，滿足不同場景需求。
• 多樣的縮放級別：支持不同的縮放級別，適應各種頁面顯示。
• 可配置的等待時間：能自定義頁面加載等待時間，確保完整捕獲頁面內容。
• 自動清理：捕獲截圖後自動清理，保持系統整潔。
• 高質量截圖：具備原生 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, // 全高清寬度
	height: 1080, // 全高清高度
	waitTime: 5, // 等待更長時間以捕獲 HD 內容
	zoomLevel: 0.8, // 略微縮小
});

📚 詳細文檔

選項說明

常見視口大小

該模塊針對以下常見視口大小進行了測試：

• 臺式機：1920×1080（全高清）
• 筆記本電腦：1366×768
• 平板電腦：1024×768
• 手機：375×667

🔧 技術細節

工作原理

1. 發現功能

   • MCP 服務器向 Cursor 代理報告其 capabilities。
   • 返回支持的工具和參數。

2. 執行截圖

   • 當收到帶有 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 返回結果。

本地測試

可以直接測試 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/

⚙️ 故障排除

如果遇到問題：

1. 檢查終端是否有輔助功能權限
2. 確保 Safari 不處於隱私瀏覽模式
3. 確保工作目錄可寫
4. 檢查 Cursor 控臺中的錯誤消息

📄 許可證

本項目採用 MIT 許可證。