MCP Safari Server

🚀 MCP Safari Server

MCP Safari Server 是一個基於模型上下文協議（MCP）的服務器，可對 macOS 系統上的 Safari 瀏覽器進行編程式控制。它非常適合用於網頁自動化、測試以及與 Claude 等 AI 助手協作進行調試工作。

🚀 快速開始

安裝

1. 安裝依賴：

cd mcp-safari-server
npm install

2. 構建服務器：

npm run build

配置

將此服務器添加到你的 Claude 配置文件（.mcp.json 或 claude-code-config.json）中：

{
  "mcpServers": {
    "safari": {
      "command": "node",
      "args": ["/path/to/mcp-safari-server/dist/index.js"],
      "env": {}
    }
  }
}

或者在開發環境中使用：

{
  "mcpServers": {
    "safari": {
      "command": "npx",
      "args": ["tsx", "/path/to/mcp-safari-server/src/index.ts"],
      "env": {}
    }
  }
}

✨ 主要特性

• 導航功能：在 Safari 中打開指定的 URL。
• 執行 JavaScript 代碼：在當前頁面上下文中運行 JS 代碼。
• 獲取頁面信息：獲取當前頁面的 URL 和標題。
• 截圖功能：對當前的 Safari 窗口進行截圖。
• 控制檯日誌捕獲：捕獲並獲取 console.log、console.error 和 console.warn 消息。
• 頁面導航操作：刷新頁面、返回上一頁或前進到下一頁。
• 自動錯誤監控：監控 JavaScript 錯誤，並將其發送到 Claude Code 以便立即修復。
• 元素點擊：使用 CSS 選擇器點擊頁面上的元素。
• 文本輸入：在表單和輸入字段中填充文本。
• 滾動操作：滾動到特定元素或位置。
• 選項選擇：從下拉菜單中選擇選項。
• 元素文本提取：從頁面元素中提取文本內容。
• 元素等待：在與元素進行交互之前，等待元素出現。

📦 安裝指南

依賴安裝

進入項目目錄並安裝所需依賴：

cd mcp-safari-server
npm install

服務器構建

運行以下命令構建服務器：

npm run build

配置添加

將服務器配置添加到 Claude 配置文件中，可選擇生產環境或開發環境的配置。

💻 使用示例

基礎用法

配置完成後，Claude 可以使用以下工具進行操作：

導航

導航到指定 URL：

Use the safari navigate tool to open https://example.com

執行腳本

在當前頁面執行 JavaScript 代碼：

Use the safari execute_script tool to run: document.querySelector('h1').textContent

獲取頁面信息

獲取當前頁面的 URL 和標題：

Use the safari get_page_info tool to see the current URL and title

截圖

對當前 Safari 窗口進行截圖：

Use the safari take_screenshot tool to capture the current page

獲取控制檯日誌

獲取頁面的控制檯日誌：

Use the safari get_console_logs tool to see any console messages

刷新頁面

刷新當前頁面：

Use the safari refresh_page tool

歷史導航

返回上一頁或前進到下一頁：

Use the safari go_back tool to go to the previous page

開始錯誤監控

開始監控 JavaScript 錯誤並自動發送到 Claude Code：

Use the safari start_error_monitoring tool

選項：

• interval：檢查間隔（毫秒），默認值為 2000。
• autoSendToClaude：是否自動將錯誤發送到 Claude Code，默認值為 true。

停止錯誤監控

停止錯誤監控：

Use the safari stop_error_monitoring tool

點擊元素

點擊頁面上的元素：

Use the safari click_element tool with selector "#submit-button"
Use the safari click_element tool with selector "a.nav-link" and waitForNavigation true

輸入文本

在輸入字段中輸入文本：

Use the safari type_text tool with selector "#email" and text "user@example.com"
Use the safari type_text tool with selector "#password" and text "mypassword" and clearFirst false

滾動操作

滾動到特定元素或位置：

Use the safari scroll_to tool with selector "#footer"
Use the safari scroll_to tool with y 500 and behavior "smooth"

選擇選項

從下拉菜單中選擇選項：

Use the safari select_option tool with selector "#country" and value "US"
Use the safari select_option tool with selector "#size" and text "Large"
Use the safari select_option tool with selector "#priority" and index 2

獲取元素文本

獲取元素的文本內容：

Use the safari get_element_text tool with selector "h1"
Use the safari get_element_text tool with selector ".error-message"

等待元素出現

等待元素出現：

Use the safari wait_for_element tool with selector "#loading-complete"
Use the safari wait_for_element tool with selector ".modal" and timeout 5000

📚 詳細文檔

錯誤監控功能

Safari MCP 服務器可以自動監控網頁應用中的 JavaScript 錯誤，並將其發送到 Claude Code 以便立即修復。具體工作流程如下：

1. 開發網頁應用。
2. Safari MCP 監控 JavaScript 錯誤。
3. 當錯誤發生時，自動將其發送到 Claude Code。
4. Claude 可以分析錯誤並提供修復建議或直接實施修復。

錯誤監控原理

啟動錯誤監控後，服務器會執行以下操作：

1. 向 Safari 頁面注入 JavaScript 代碼，以捕獲以下錯誤：
   • 未處理的錯誤（window.onerror）。
   • 未處理的 Promise 拒絕。
   • console.error 調用。
2. 按照指定的間隔（默認每 2 秒）檢查是否有新的錯誤。
3. 如果發現錯誤且 Claude Code 處於激活狀態，會發送包含以下信息的通知：
   • 錯誤類型和消息。
   • 文件位置和行/列號。
   • 堆棧跟蹤信息。
   • 當前頁面的 URL。
   • 時間戳。
4. Claude Code 接收通知並提示你修復錯誤。

示例工作流程

1. 啟動開發服務器。
2. 使用 navigate 工具在 Safari 中打開你的應用。
3. 使用 start_error_monitoring 啟動錯誤監控。
4. 在與應用進行交互時，任何 JavaScript 錯誤都會被捕獲。
5. Claude Code 會收到錯誤通知並幫助你修復錯誤。
6. 完成後，使用 stop_error_monitoring 停止監控。

🔧 技術細節

系統要求

• macOS 系統（使用 AppleScript 控制 Safari）。
• Safari 瀏覽器。
• Node.js 16 及以上版本。

安全注意事項

此服務器通過執行 AppleScript 命令來控制 Safari。請僅在受信任的環境中使用，並謹慎執行 JavaScript 代碼。

故障排除

1. Safari 自動化權限：你可能需要在“系統偏好設置”>“安全性與隱私”>“隱私”>“自動化”中授予終端或 IDE 控制 Safari 的權限。
2. 腳本執行錯誤：請確保 Safari 已安裝且未被任何安全軟件阻止。
3. 控制檯日誌捕獲：控制檯日誌捕獲功能會向頁面注入腳本。一些具有嚴格內容安全策略的頁面可能會阻止此操作。