JinDaGe - mcp-safari-server MCP Details

article

README

🚀 MCP Safari Server

MCP Safari Server 是一个基于模型上下文协议（MCP）的服务器，可对 macOS 系统上的 Safari 浏览器进行编程式控制。它非常适合用于网页自动化、测试以及与 Claude 等 AI 助手协作进行调试工作。

🚀 快速开始

安装

安装依赖：

cd mcp-safari-server
npm install

构建服务器：

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 可以使用以下工具进行操作：

执行脚本

在当前页面执行 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 以便立即修复。具体工作流程如下：

开发网页应用。
Safari MCP 监控 JavaScript 错误。
当错误发生时，自动将其发送到 Claude Code。
Claude 可以分析错误并提供修复建议或直接实施修复。

错误监控原理

启动错误监控后，服务器会执行以下操作：

向 Safari 页面注入 JavaScript 代码，以捕获以下错误：
- 未处理的错误（window.onerror）。
- 未处理的 Promise 拒绝。
- console.error 调用。
按照指定的间隔（默认每 2 秒）检查是否有新的错误。
如果发现错误且 Claude Code 处于激活状态，会发送包含以下信息的通知：
- 错误类型和消息。
- 文件位置和行/列号。
- 堆栈跟踪信息。
- 当前页面的 URL。
- 时间戳。
Claude Code 接收通知并提示你修复错误。

示例工作流程

启动开发服务器。
使用 navigate 工具在 Safari 中打开你的应用。
使用 start_error_monitoring 启动错误监控。
在与应用进行交互时，任何 JavaScript 错误都会被捕获。
Claude Code 会收到错误通知并帮助你修复错误。
完成后，使用 stop_error_monitoring 停止监控。

🔧 技术细节

系统要求

macOS 系统（使用 AppleScript 控制 Safari）。
Safari 浏览器。
Node.js 16 及以上版本。

安全注意事项

此服务器通过执行 AppleScript 命令来控制 Safari。请仅在受信任的环境中使用，并谨慎执行 JavaScript 代码。

故障排除

Safari 自动化权限：你可能需要在“系统偏好设置”>“安全性与隐私”>“隐私”>“自动化”中授予终端或 IDE 控制 Safari 的权限。
脚本执行错误：请确保 Safari 已安装且未被任何安全软件阻止。
控制台日志捕获：控制台日志捕获功能会向页面注入脚本。一些具有严格内容安全策略的页面可能会阻止此操作。

mcp-safari-server