macOS Automator MCP Server

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引擎）。
• macOS。
• 关键权限设置：
  • 运行此 MCP 服务器的应用程序（例如，终端、您的 Node.js 应用程序）需要在运行该服务器的 macOS 计算机上获得明确的用户权限。
  • **自动化权限：**控制其他应用程序（Finder、Safari、Mail 等）。
    • 前往：系统设置>隐私和安全>自动化。
    • 在列表中找到运行服务器的应用程序（例如终端）。
    • 确保它需要控制的所有应用程序的复选框都已勾选。
    • 查看示例： docs/automation-permissions-example.png （占位符图像）。
  • **可访问性权限：**通过“系统事件”进行 UI 脚本编写（例如，模拟点击、击键）。
    • 前往：系统设置 > 隐私和安全 > 辅助功能。
    • 将运行服务器的应用程序（例如终端）添加到列表中并确保勾选其复选框。
  • 即使已预先授权，首次尝试控制新应用程序或使用辅助功能仍可能触发 macOS 确认提示。服务器本身无法授予这些权限。

安装和使用

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

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

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

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

1. 克隆存储库：
   git clone https://github.com/steipete/macos-automator-mcp.git cd macos-automator-mcp npm install # Ensure dependencies are installed
2. **配置您的 MCP 客户端：**更新您的 MCP 客户端的配置以指向克隆存储库中的start.sh脚本的绝对路径。mcp.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脚本旨在确保您始终通过 tsx 从src/运行最新的 TypeScript 代码，尤其是在修改为在执行前删除所有已编译的dist/server.js文件（例如，添加rm -f dist/server.js ）的tsx 。这对于开发环境非常理想，可以防止构建过时导致的问题。对于生产部署（例如，发布到 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等占位符），则使用 kb_script_id 。请从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（ -sh ）使用人类可读的格式，对 JXA 使用直接输出（无-s标志）。
  • 'human_readable' ：强制-sh （人类可读的输出，主要用于 AppleScript）。
  • 'structured_error' ：强制-ss （结构化错误报告，主要用于 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 使用知识库脚本：
  { "toolName": "execute_script", "input": { "kb_script_id": "safari_get_active_tab_url", "timeout_seconds": 10 } }
• 通过 ID 和input_data使用知识库脚本：
  { "toolName": "execute_script", "input": { "kb_script_id": "finder_create_folder_at_path", "input_data": { "folder_name": "New MCP Folder", "parent_path": "~/Desktop" } } }

响应格式：

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

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

响应示例（成功）：

响应示例（错误）：

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" } }
  • 获取邮件中未读邮件的主题： { "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是运行 MCP 服务器的用户可以访问的绝对 POSIX 路径。
• **输出/JXA 错误问题：**对于 JXA 脚本，尤其是使用 Objective-C 桥接的脚本，请确保将output_format_mode设置为'direct'或'auto' （默认）。在 JXA 中使用 AppleScript 特定的格式化标志（例如human_readable可能会导致错误。如果 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或类似程序运行时）：
    KB_PARSING=eager ./start.sh
  • 示例（通过支持env的 MCP 运行器进行配置时，例如mcp-agentify ）：
    { "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（来自 frontmatter 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文件。