macOS Automator MCP 服务器

概述

此项目提供了一个模型上下文协议（MCP）服务器 macos_automator，允许在 macOS 上执行 AppleScript 和 JavaScript for Automation (JXA) 脚本。它包含一个可通过 ID 访问的预定义脚本知识库，并支持内联脚本、脚本文件和参数传递。
知识库在首次使用时懒加载，以实现快速启动服务器。

优点

• 通过 MCP 远程执行 AppleScript/JXA 脚本。
• 利用丰富且可扩展的常见 macOS 自动化任务知识库。
• 以编程方式控制 macOS 应用程序和系统功能。
• 将 macOS 自动化集成到更大的 AI 驱动工作流中。

前提条件

• Node.js（建议版本 >=18.0.0，请参阅 package.json 中的 engines）。
• macOS。
• 关键权限设置：
  • 运行此 MCP 服务器的应用程序（例如终端、您的 Node.js 应用程序）需要在运行服务器的 macOS 机器上获得用户的显式权限。
  • 自动化权限： 用于控制其他应用程序（Finder、Safari、Mail 等）。
    • 前往：系统设置 > 隐私与安全性 > 自动化。
    • 在列表中找到运行服务器的应用程序（例如终端）。
    • 确保它对所有需要控制的应用程序都勾选了复选框。
    • 参见示例：docs/automation-permissions-example.png（占位符图像）。
  • 辅助功能权限： 用于通过“系统事件”进行 UI 脚本编写（例如模拟点击、按键）。
    • 前往：系统设置 > 隐私与安全性 > 辅助功能。
    • 将运行服务器的应用程序（例如终端）添加到列表中，并确保其复选框已勾选。
  • 即使预先授权，首次尝试控制新应用程序或使用辅助功能特性时仍可能触发 macOS 的确认提示。服务器本身无法授予这些权限。

安装与使用

运行此服务器的主要方法是通过 npx。这可以确保您使用的是最新版本，而无需全局安装。

将以下配置添加到您的 MCP 客户端的 mcp.json（或等效配置）中：

json
{
"mcpServers": {
"macos_automator": {
"command": "npx",
"args": [
"-y",
"@steipete/macos-automator-mcp@latest"
]
}
}
}

本地运行（开发或直接使用）

或者，如果您希望进行开发或直接从克隆的仓库运行服务器，可以使用提供的 start.sh 脚本。这对于希望进行本地修改或运行特定版本的情况非常有用。

1. 克隆仓库：
   bash
   git clone https://github.com/steipete/macos-automator-mcp.git
   cd macos-automator-mcp
   npm install # 确保依赖项已安装

2. 配置您的 MCP 客户端：
   更新您的 MCP 客户端配置，使其指向克隆仓库中的 start.sh 脚本的绝对路径。

   示例 mcp.json 配置片段：
   json
   {
   "mcpServers": {
   "macos_automator_local": {
   "command": "/absolute/path/to/your/cloned/macos-automator-mcp/start.sh",
   "env": {
   "LOG_LEVEL": "DEBUG"
   }
   }
   }
   }

   重要： 请将 /absolute/path/to/your/cloned/macos-automator-mcp/start.sh 替换为您系统上的正确绝对路径。

   如果未找到编译版本，start.sh 脚本会自动使用 tsx 直接运行 TypeScript 源代码，或者如果可用则从 dist/ 运行编译版本。它尊重 LOG_LEVEL 环境变量。开发者注意事项： start.sh 脚本，特别是如果修改为在执行前删除任何预先存在的已编译的 dist/server.js（例如，通过添加 rm -f dist/server.js），旨在确保您始终通过 tsx 运行来自 src/ 目录的最新 TypeScript 代码。这对于开发来说是理想的，可以防止因旧构建而引发的问题。对于生产部署（例如发布到 npm 时），通常会有一个构建过程来创建最终的 dist/server.js，这将成为发布的包的入口点。

提供的工具

1. execute_script

在 macOS 上执行 AppleScript 或 JavaScript for Automation (JXA) 脚本。
脚本可以通过内联内容 (script_content)、绝对文件路径 (script_path) 或通过引用内置知识库中的脚本并使用其唯一的 kb_script_id 来提供。

脚本来源（互斥）：

• script_content (字符串)：原始脚本代码。
• script_path (字符串)：指向脚本文件的绝对 POSIX 路径（例如，.applescript、.scpt、.js）。
• kb_script_id (字符串)：来自服务器知识库的预定义脚本的 ID。使用 get_scripting_tips 工具来发现可用的脚本 ID 及其功能。

语言指定：

• language (枚举: applescript | javascript, 可选)：指定语言。
  • 如果使用 kb_script_id，则从知识库脚本中推断语言。
  • 如果使用 script_content 或 script_path 并且省略了 language，则默认为 applescript。

向脚本传递输入：

• arguments (字符串数组, 可选)：
  • 对于 script_path：作为标准参数传递给脚本的 on run argv (AppleScript) 或 run(argv) (JXA) 处理程序。
  • 对于 kb_script_id：如果预定义脚本设计为接受位置字符串参数（例如，替换占位符如 --MCP_ARG_1、--MCP_ARG_2）。请检查 get_scripting_tips 中的脚本 argumentsPrompt。
• input_data (JSON 对象, 可选)：
  • 主要用于设计为接受命名结构化输入的 kb_script_id 脚本。
  • 此对象中的值将替换脚本中的占位符（例如，--MCP_INPUT:yourKeyName）。参见 get_scripting_tips 中的 argumentsPrompt。
  • 值（字符串、数字、布尔值、简单数组/对象）被转换为其 AppleScript 字面量等价物。

其他选项：

• timeout_seconds (整数, 可选, 默认: 60)：最大执行时间。
• output_format_mode (枚举, 可选, 默认: auto)：控制 osascript 输出格式化标志。
  • auto：(默认) 对 AppleScript 使用易读格式 (-s h)，对 JXA 使用直接输出（无 -s 标志）。
  • human_readable：强制使用 -s h（易读输出，主要用于 AppleScript）。
  • structured_error：强制使用 -s s（结构化错误报告，主要用于 AppleScript）。
  • structured_output_and_error：强制使用 -s ss（主要结果和错误的结构化输出，主要用于 AppleScript）。
  • direct：不使用 -s 标志（推荐用于 JXA，在 auto 模式下也是 JXA 的行为）。
• include_executed_script_in_output (布尔值, 可选, 默认: false)：如果为 true，则输出将包含完整的脚本内容（对于知识库脚本，在进行任何占位符替换之后）或被执行的脚本路径。这将作为额外的文本部分附加到输出内容数组中。
• include_substitution_logs (布尔值, 可选, 默认: false)：如果为 true，则包括对知识库脚本执行的详细占位符替换日志。这对于调试 input_data 和 arguments 如何处理并插入脚本非常有用。这些日志在成功时会被前置到脚本输出中，或者在失败时被追加到错误消息中。- report_execution_time (布尔值，可选，默认：false)：如果为 true，则在响应内容数组中包含一个带有格式化脚本执行时间的附加消息。

安全警告和 macOS 权限：（与之前相同的关于任意脚本执行和 macOS 自动化/辅助功能权限的重要警告）。

示例：

• （内联/文件路径的现有示例仍然适用）

• 使用知识库脚本 ID：
  json
  {
  "toolName": "execute_script",
  "input": {
  "kb_script_id": "safari_get_active_tab_url",
  "timeout_seconds": 10
  }
  }

• 使用带有 input_data 的知识库脚本 ID：
  json
  {
  "toolName": "execute_script",
  "input": {
  "kb_script_id": "finder_create_folder_at_path",
  "input_data": {
  "folder_name": "New MCP Folder",
  "parent_path": "~/Desktop"
  }
  }
  }

响应格式：

execute_script 工具返回的响应格式如下：

typescript
{
content: Array<{
type: text ;
text: string;
}>;
isError?: boolean;
}

• content：一个包含脚本输出的文本内容项数组
• isError：（布尔值，可选）当脚本执行产生错误时设置为 true。此标志在以下情况下被设置：
  • 脚本输出（stdout）以 "Error" 开头（不区分大小写）
  • 这有助于客户端无需解析输出文本即可轻松确定执行是否失败

示例响应（成功）：
json
{
"content": [{
"type": "text",
"text": "Script executed successfully"
}]
}

示例响应（错误）：
json
{
"content": [{
"type": "text",
"text": "Error: Cannot find application Safari "
}],
"isError": true
}

2. get_scripting_tips

从服务器的知识库中检索 AppleScript/JXA 提示、示例和可运行脚本详情。对于发现可用脚本、它们的功能以及如何使用 execute_script（特别是 kb_script_id）非常有用。

参数：

• list_categories（布尔值，可选，默认：false）：如果为 true，则仅返回可用知识库类别的列表及其描述。覆盖其他参数。
• category（字符串，可选）：通过特定类别 ID（例如 "finder", "safari"）筛选提示。
• search_term（字符串，可选）：在提示标题、描述、脚本内容、关键字或 ID 中搜索关键词。
• refresh_database（布尔值，可选，默认：false）：如果为 true，在处理请求前强制重新加载整个知识库。如果您正在积极修改知识库文件并希望确保使用最新版本而无需重启服务器，这将非常有用。
• limit（整数，可选，默认：10）：要返回的最大结果数量。

输出：

• 返回一个 Markdown 格式的字符串，其中包含请求的提示，包括其标题、描述、脚本内容、语言、可运行 ID（如果适用）、参数提示和注释。

示例用法：

• 列出所有类别：
  { "toolName": "get_scripting_tips", "input": { "list_categories": true } }
• 获取 "safari" 类别的提示：
  { "toolName": "get_scripting_tips", "input": { "category": "safari" } }
• 搜索与 "clipboard" 相关的提示：
  { "toolName": "get_scripting_tips", "input": { "search_term": "clipboard" } }

主要使用场景及示例

• 应用程序控制：
  • 从 Safari 获取当前 URL：{ "input": { "script_content": "tell application \"Safari\" to get URL of front document" } }
  • 获取 Mail 中未读邮件的主题：{ "input": { "script_content": "tell application \"Mail\" to get subject of messages of inbox whose read status is false" } }
• 文件系统操作：- 列出桌面上的文件：{ "input": { "script_content": "tell application \"Finder\" to get name of every item of desktop" } }
• 创建新文件夹：{ "input": { "script_content": "tell application \"Finder\" to make new folder at desktop with properties {name:\"My New Folder\"}" } }
• 系统交互：
  • 显示系统通知：{ "input": { "script_content": "display notification \"Important Update!\" with title \"System Alert\"" } }
  • 设置系统音量：{ "input": { "script_content": "set volume output volume 50" } } (范围0-100)
  • 获取当前剪贴板内容：{ "input": { "script_content": "the clipboard" } }

故障排除

• 权限错误： 如果脚本无法控制应用程序或执行UI操作，请检查运行MCP服务器的应用程序（例如终端）在系统设置中的自动化和辅助功能权限。
• 脚本语法错误： osascript 错误将返回在 stderr 或错误消息中。首先使用脚本编辑器（针对AppleScript）或JXA运行器本地测试复杂脚本。
• 超时： 如果脚本执行时间超过 timeout_seconds（默认60秒），它将被终止。对于长时间运行的脚本，增加超时时间。
• 找不到文件： 确保 script_path 是一个绝对POSIX路径，并且可以被运行MCP服务器的用户访问。
• 输出不正确/JXA问题： 对于JXA脚本，特别是那些使用Objective-C桥接的脚本，确保 output_format_mode 设置为 direct 或 auto（默认）。使用特定于AppleScript的格式化标志（如 human_readable）与JXA可能会导致错误。如果AppleScript输出解析不正确，尝试使用 structured_output_and_error 或 structured_error。

通过环境变量配置

• LOG_LEVEL：设置服务器的日志级别。

  • 值：DEBUG, INFO, WARN, ERROR
  • 示例：LOG_LEVEL=DEBUG npx @steipete/macos-automator-mcp@latest

• KB_PARSING：控制知识库（脚本提示）何时被解析。

  • 值：

    • lazy（默认）：知识库在首次请求 get_scripting_tips 或在 execute_script 中使用 kb_script_id 时被解析。这允许更快的服务器启动。
    • eager：知识库在服务器启动时被解析。这可能会稍微增加启动时间，但确保知识库立即可用，并且任何解析错误都能及早捕获。

  • 示例（当通过 start.sh 或类似方式运行时）：
    bash
    KB_PARSING=eager ./start.sh

  • 示例（当通过支持 env 的MCP运行器配置时，比如 mcp-agentify）：
    json
    {
    "env": {
    "LOG_LEVEL": "INFO",
    "KB_PARSING": "eager"
    }
    }

开发者指南

有关本地开发、项目结构（包括 knowledge_base）以及贡献指南的详细说明，请参阅 DEVELOPMENT.md。

开发

有关项目结构、构建和测试的详细信息，请参见 DEVELOPMENT.md。

本地知识库

您可以使用自己的本地提示和共享处理器来补充内置的知识库。创建与该仓库中 knowledge_base 相同的目录结构（或其子集）。

默认情况下，应用程序会在 ~/.macos-automator/knowledge_base 查找此本地知识库。
您可以通过设置 LOCAL_KB_PATH 环境变量来自定义此路径。

示例：

假设您的本地知识库位于 /Users/yourname/my-custom-kb。
设置环境变量：
export LOCAL_KB_PATH=/Users/yourname/my-custom-kb

或者，如果您正在运行验证器脚本，可以使用 --local-kb-path 参数：
npm run validate:kb -- --local-kb-path /Users/yourname/my-custom-kb

结构和覆盖：* 你的本地知识库应该镜像主knowledge_base的类别结构（例如，01_applescript_core，05_web_browsers/safari等）。

• 你可以添加新的.md提示文件或_shared_handlers（例如，.applescript或.js文件）。
• 如果你的本地知识库中的提示ID（从前置元数据id:获取或从文件名/路径生成）与嵌入的知识库中的ID匹配，那么你的本地版本将覆盖嵌入版本。
• 类似地，在你的本地_shared_handlers目录中具有相同名称和语言（例如，my_utility.applescript）的共享处理器将覆盖同一类别内（或者如果你将它们放置在本地KB的_shared_handlers根目录下则全局）具有相同名称和语言的任何嵌入式处理器。
• 来自你本地KB中的_category_info.md的类别描述也可以覆盖嵌入KB中相同类别的描述。

这允许个性化和扩展可用的自动化脚本和提示，而无需修改核心应用程序文件。

贡献

欢迎贡献！请向GitHub仓库提交问题和拉取请求。

自动化功能

此服务器通过AppleScript和JavaScript for Automation (JXA) 提供强大的macOS自动化能力。以下是一些最实用的例子：

终端自动化

• 在新终端标签页中运行命令：

  { "input": { "kb_script_id": "terminal_app_run_command_new_tab", "input_data": { "command": "ls -la" } } }

• 使用sudo执行命令并安全提供密码

• 捕获命令输出以进行处理

浏览器控制

• Chrome/Safari自动化：

  { "input": { "kb_script_id": "chrome_open_url_new_tab_profile", "input_data": { "url": "https://example.com", "profile_name": "Default" } } }

  { "input": { "kb_script_id": "safari_get_front_tab_url" } }

• 在浏览器上下文中执行JavaScript：

  { "input": { "kb_script_id": "chrome_execute_javascript", "input_data": { "javascript_code": "document.title" } } }

• 提取页面内容、操作表单及自动化工作流程

• 对网页截图

系统交互

• 切换系统设置（暗模式、音量、网络）：

  { "input": { "kb_script_id": "systemsettings_toggle_dark_mode_ui" } }

• 获取/设置剪贴板内容：

  { "input": { "kb_script_id": "system_clipboard_get_file_paths" } }

• 打开/控制系统对话框和警告

• 创建和管理系统通知

文件操作

• 创建、移动和管理文件/文件夹：

  { "input": { "kb_script_id": "finder_create_new_folder_desktop", "input_data": { "folder_name": "My Project" } } }

• 读写文本文件：

  { "input": { "kb_script_id": "fileops_read_text_file", "input_data": { "file_path": "~/Documents/notes.txt" } } }

• 列出并过滤目录中的文件

• 获取文件元数据和属性

应用程序集成

• 日历/提醒事项管理：

  { "input": { "kb_script_id": "calendar_create_event", "input_data": { "title": "Meeting", "start_date": "2023-06-01 10:00", "end_date": "2023-06-01 11:00" } } }

• 使用Mail.app进行邮件自动化：

  { "input": { "kb_script_id": "mail_send_email_direct", "input_data": { "recipient": "user@example.com", "subject": "Hello", "body_content": "Message content" } } }

• 控制音乐播放：

  { "input": { "kb_script_id": "music_playback_controls", "input_data": { "action": "play" } } }

• 与创意应用（Keynote, Pages, Numbers）协作

使用get_scripting_tips工具探索按类别组织的所有可用自动化功能。

许可证

该项目根据MIT许可证发布。详情请参阅LICENSE文件。

请注意，翻译时仅对 alt 属性中的描述进行了中文转换，以保持链接和图片属性的完整性。其他部分如链接地址、图片尺寸等均未做改动。