使用说明

macOS自动程序MCP🤖 - 您友好的邻居RoboScripter™

🎯 任务控制：自2024年以来教机器人点击按钮

欢迎来到自动化的未来，你的Mac最终会按照你的指示行事！这个模型上下文协议（MCP）服务器将你的人工智能助手变成一个真正了解AppleScript和JavaScript for Automation（JXA）的硅基实习生。

不再像穴居人那样复制粘贴脚本——让机器人来处理机器人的工作！我们的知识库包含200多个预编程的自动化序列，加载速度比你说“嘿Siri，你为什么不这样工作？”还要快

🚀 为什么让机器人运行你的Mac？

远程控制现实：通过MCP执行AppleScript/JXA脚本-这就像在Mac中有一个微型机器人！
电力知识库：200多种预制自动化配方。从“切换黑暗模式”到“从Safari中提取所有URL”，我们满足了您的机器人需求。
应用程序耳语器：以编程方式控制任何macOS应用程序。让Finder跳舞，Safari唱歌，终端。…好吧，终止一切。
AI工作流集成：将您的Mac连接到AI革命。你的法学硕士现在可以真正地做事，而不仅仅是谈论它们！

🔧 机器人要求（先决条件）

Node.js （版本>=18.0.0）-因为即使是机器人也需要运行时
macOS -抱歉，Windows用户，这是一个仅限苹果的聚会🍎
⚠️ 关键：自动化许可（Mac的信任问题）：
- 运行THIS MCP服务器的应用程序（例如终端、Node.js应用程序）需要在运行服务器的macOS机器上具有明确的用户权限。
- 自动化权限： 控制其他应用程序（Finder、Safari、Mail等）。
  - 转到：系统设置>隐私和安全>自动化。
  - 在列表中找到运行服务器的应用程序（例如终端）。
  - 确保它为需要控制的所有应用程序勾选了复选框。
  - 参见示例： docs/automation-permissions-example.png （占位符图像）。
- 可访问权限： 用于通过“系统事件”进行UI脚本编写（例如，模拟点击、按键）。
  - 转到：系统设置>隐私和安全>辅助功能。
  - 将运行服务器的应用程序（例如终端）添加到列表中，并确保其复选框已选中。
- 即使预先授权，首次尝试控制新应用程序或使用辅助功能仍可能触发macOS确认提示。服务器本身无法授予这些权限。

🏃‍♂️ 快速开始：释放机器人！

部署自动化军队的最简单方法是通过 npx无需安装，只需纯粹的机器人魔法！

将此添加到您的MCP客户端 mcp.json 并观看自动化开始：

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

🛠️ 机器人车间模式（本地开发）

想修补机器人的大脑吗？克隆仓库，成为一名机器人外科医生！

克隆存储库：

git clone https://github.com/steipete/macos-automator-mcp.git
cd macos-automator-mcp
npm install # Ensure dependencies are installed

配置您的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 脚本，特别是如果修改以删除任何预先存在的已编译脚本 dist/server.js 执行前（例如，通过添加 rm -f dist/server.js)，旨在确保您始终运行来自 src/ 目录通过 tsx。这对于开发来说是理想的，可以防止过时构建的问题。对于生产部署（例如，当发布到npm时），构建过程通常会创建一个明确的 dist/server.js 这将是已发布包的入口点。

🤖 机器人工具箱

1. `execute_script` -脚本启动器9000

你的机器人统治macOS的主要武器。给它输入AppleScript或JXA，然后观看魔术的发生！脚本可以作为内联内容提供(script_content)，绝对文件路径(script_path)，或通过使用其唯一性从内置知识库中引用脚本 kb_script_id.

脚本源（互斥）：

script_content （string）：原始脚本代码。
script_path （string）：脚本文件的绝对POSIX路径（例如。， .applescript, .scpt, .js).
kb_script_id （string）：服务器知识库中预定义脚本的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).检查脚本 argumentsPrompt 从 get_scripting_tips.
input_data （JSON对象，可选）：
- 主要用于 kb_script_id 用于接受命名的结构化输入的脚本。
- 来自该对象的值替换脚本中的占位符（例如。， --MCP_INPUT:yourKeyName).看 argumentsPrompt 从 get_scripting_tips.
- 值（字符串、数字、布尔值、简单数组/对象）被转换为其AppleScript文字等效值。

其他选项：

timeout_seconds （整数，可选，默认值：60）：最大执行时间。
output_format_mode （枚举，可选，默认值：“auto”）：控件 osascript 输出格式化标志。
- 'auto'：（默认）使用人类可读的AppleScript(-s h)，直接输出（否 -s 标志）用于JXA。
- 'human_readable'：部队 -s h （人类可读的输出，主要用于AppleScript）。
- 'structured_error'：部队 -s s （结构化错误报告，主要用于AppleScript）。
- 'structured_output_and_error'：部队 -s ss （主要结果和错误的结构化输出，主要用于AppleScript）。
- 'direct'：没有 -s 使用标志（建议用于JXA，也是JXA在 auto 模式）。
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: Array<{
    type: 'text';
    text: string;
  }>;
  isError?: boolean;
}

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

示例响应（成功）：

{
  "content": [{
    "type": "text",
    "text": "Script executed successfully"
  }]
}

示例响应（错误）：

{
  "content": [{
    "type": "text",
    "text": "Error: Cannot find application 'Safari'"
  }],
  "isError": true
}

2. `get_scripting_tips` -机器人百科全书

您的个人自动化图书管理员！搜索200多个预构建脚本的速度比谷歌“如何使用AppleScript”快。非常适合您的机器人需要灵感的时候。

论据：

list_categories （boolean，可选，默认值：false）：如果为true，则仅返回可用知识库类别及其描述的列表。覆盖其他参数。
category （字符串，可选）：按特定类别ID过滤提示（例如，“查找器”、“safari”）。
search_term （字符串，可选）：在提示标题、描述、脚本内容、关键字或ID中搜索关键字。
refresh_database （boolean，可选，默认值：false）：如果为true，则在处理请求之前强制从磁盘重新加载整个知识库。如果您正在积极修改知识库文件，并希望确保在不重新启动服务器的情况下使用最新版本，这在开发过程中非常有用。
limit （整数，可选，默认值：10）：返回的最大结果数。

输出：

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

示例用法：

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

3. `accessibility_query` -UI X射线视觉

赋予你的机器人超级英雄力量，在任何应用程序中查看并点击任何按钮！此工具使用可访问性框架深入macOS应用程序的灵魂。由神秘的 ax 二进制，这就像为用户界面提供X射线视觉。

这 ax 二进制，因此这个工具可以通过多种方式接受JSON命令输入：

直接JSON字符串参数： 如果 ax 如果使用不是有效文件路径的单个命令行参数调用，它将尝试将此参数解析为完整的JSON字符串。
文件路径参数： 如果 ax 如果使用一个有效文件路径的命令行参数调用，它将从该文件中读取完整的JSON命令。
标准输入： 如果 ax 如果调用时没有命令行参数，它将从标准输入中读取完整的JSON命令（可以是多行）。

该工具公开了完整的macOS可访问性API功能，允许对UI元素及其属性进行详细检查。它对于自动化与没有强大AppleScript支持的应用程序的交互或需要详细检查UI结构时特别有用。

输入参数：

command （枚举：“query”|“perform”，必填）：要执行的操作。
- query：检索有关UI元素的信息。
- perform：在UI元素上执行操作（如单击按钮）。
locator （object，必填）：查找目标元素的规范。
- app （字符串，必填）：要定位的应用程序，由捆绑包ID或显示名称指定（例如，“Safari”、“com.apple.Safari”）。
- role （string，必填）：目标元素的可访问性角色（例如“AXButton”、“AXStaticText”）。
- match （object，必填）：要匹配的属性的键值对。可以为空({})如果不需要。
- navigation_path_hint （字符串数组，可选）：在应用程序层次结构中导航的路径（例如。， ["window[1]", "toolbar[1]"]).
return_all_matches （布尔值，可选）：当 true，返回所有匹配的元素，而不仅仅是第一个匹配。默认值为 false.
attributes_to_query （字符串数组，可选）：查询匹配元素的特定属性。如果没有提供，将包括通用属性。示例： ["AXRole", "AXTitle", "AXValue"]
required_action_name （字符串，可选）：仅过滤支持特定操作的元素（例如，“AXPress”用于可点击元素）。
action_to_perform （字符串，可选，需要时 command="perform")：对匹配的元素执行的可访问性操作（例如，“AXPress”单击按钮）。
report_execution_time （boolean，可选）：如果为true，该工具将返回一条包含格式化脚本执行时间的附加消息。默认为false。
limit （整数，可选）：输出中返回的最大行数。默认值为500。如果输出超过此限制，则将被截断。
max_elements （整数，可选）：用于 return_all_matches: true 查询，这指定了UI元素的最大数量 ax 二进制文件将完全处理并返回的属性。如果省略，则使用内部默认值（例如200）。这有助于在查询具有大量匹配元素（如复杂网页上的众多文本字段）的UI时管理性能。这与 limit，它根据行截断最终的文本输出。
debug_logging （boolean，可选）：如果为true，则从底层启用详细的调试日志记录 ax 二元的。此诊断信息将包含在响应中，这有助于排除复杂的查询或意外行为。默认为false。
output_format （枚举：“smart”|“verbose”|“text_content”，可选，默认值：“smart”）：控制从 ax 二元的。
- 'smart'：（默认）优化可读性。省略具有空值或占位符值的属性。返回键值对。
- 'verbose'：最大细节。包括所有属性，甚至空/占位符。键值对。最适合调试元素属性。
- 'text_content'：文本提取非常紧凑。仅返回常见文本属性（例如AXValue、AXTitle）的连接文本值。没有归还钥匙。非常适合快速从元素中获取所有文本；这 attributes_to_query 此模式下忽略参数。

示例查询（注意：键名已更改为snake_case）：

在前面的Safari窗口中查找所有文本元素：

{
  "command": "query",
  "return_all_matches": true,
  "locator": {
    "app": "Safari",
    "role": "AXStaticText",
    "match": {},
    "navigation_path_hint": ["window[1]"]
  }
}

找到并单击具有特定标题的按钮：

{
  "command": "perform",
  "locator": {
    "app": "System Settings",
    "role": "AXButton",
    "match": {"AXTitle": "General"}
  },
  "action_to_perform": "AXPress"
}

获取有关聚焦UI元素的详细信息：

{
  "command": "query",
  "locator": {
    "app": "Mail",
    "role": "AXTextField",
    "match": {"AXFocused": "true"}
  },
  "attributes_to_query": ["AXRole", "AXTitle", "AXValue", "AXDescription", "AXHelp", "AXPosition", "AXSize"]
}

注：使用此工具需要运行此服务器的应用程序在macOS系统设置>隐私和安全>辅助功能中具有必要的辅助功能权限。

🎮 机器人游乐场：你的新机器人朋友可以做的很酷的事情

应用程序控制（教学应用程序谁是老板）：
- 从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:\"Robot's Secret Stash\"}" } }
系统交互（Mac Mind Control）：
- 显示系统通知： { "input": { "script_content": "display notification \"🤖 Beep boop! Task complete!\" with title \"Robot Report\"" } }
- 设置系统音量： { "input": { "script_content": "set volume output volume 50" } } (0-100)
- 获取当前剪贴板内容： { "input": { "script_content": "the clipboard" } }

🔧 当机器人反叛时（故障排除）

“拒绝访问”戏剧： 您的机器人缺少权限！检查系统设置>隐私和安全。把王国的钥匙交给你的航站楼。
脚本语法悲伤： 甚至机器人也会拼写错误。首先在脚本编辑器中测试脚本——这就像自动化的拼写检查。
超时发脾气： 有些任务需要时间。增加 timeout_seconds 如果你的机器人需要60秒以上才能完成任务。
找不到文件惨败： 机器人需要绝对路径，而不是相对路径。在机器人领域没有捷径！
JXA输出赔率： JavaScript机器人很挑剔。使用 output_format_mode: 'direct' 或让 'auto' 模式处理它。

🎛️ 机器人控制面板（配置）

使用这些环境变量微调机器人的行为：

**LOG_LEVEL**你的机器人应该有多健谈？
- DEBUG：机器人告诉你一切（TMI模式）
- INFO：正常的机器人聊天
- WARN：只有重要的东西
- ERROR：静音模式（机器人只在爆炸时说话）
- 例子： LOG_LEVEL=DEBUG npx @steipete/macos-automator-mcp@latest
KB_PARSING：机器人应该什么时候加载大脑？
- lazy （默认）：按需加载知识（快速启动，懒惰机器人）
- eager：启动时加载所有内容（启动速度较慢，即用型机器人）
- 例子： KB_PARSING=eager ./start.sh

👨‍🔬 欢迎机器人科学家！

想升级你的机器人吗？结账 Developpent.md 有关向您的自动化助手教授新技巧的完整技术手册。

🧠 教你的机器人新技巧（本地知识库）

你的机器人可以学习自定义技能！创建您自己的自动化配方，并观察您的机器人的发展。

默认情况下，应用程序将在以下位置查找此本地知识库 ~/.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匹配，您的本地版本将 以（权力）否决 嵌入式的。
类似地。， my_utility.applescript)在当地 _shared_handlers 目录将覆盖同一类别（或全局，如果您将它们放置在本地知识库的根目录）中具有相同名称和语言的任何嵌入式知识库 _shared_handlers).
类别描述来自 _category_info.md 在本地KB中，也可以覆盖同一类别的嵌入式KB中的那些。

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

🤝 加入机器人革命！

发现bug了吗？你有一个很酷的自动化想法吗？你的机器人军队需要你！向提交问题并拉取请求 GitHub存储库.

💪 机器人超级大国展示

以下是你的新硅伙伴可以开箱即用的东西：

🖥️ 终端Tamer

命令行魔法： 打开新标签，运行命令，捕获输出——你的机器人会说一口流利的bash！

{ "input": { "kb_script_id": "terminal_app_run_command_new_tab", "input_data": { "command": "echo '🤖 Hello World!'" } } }

🌐 浏览器机器人

Web自动化大师： 像木偶大师一样控制Chrome和Safari！
```
{ "input": { "kb_script_id": "safari_get_front_tab_url" } }
```
JavaScript注入： 让网页随着机器人的节奏跳舞
截图狙击手： 捕捉任何网页的速度都比你说“奶酪”快

⚙️ 系统魔法师

暗模式切换： 因为机器人有灵敏的光学传感器

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

剪贴板命令： 像专业人士一样复制、粘贴和操作
通知忍者： 发送实际被注意到的警报

📁 文件系统风水

文件夹创建器3000： 以机器人般的精准度组织您的数字生活

{ "input": { "kb_script_id": "finder_create_new_folder_desktop", "input_data": { "folder_name": "Robot Paradise" } } }

文本文件心灵感应： 读取和写入文件的速度比人类更快

📱 应用程序耳语器

日历指挥： 睡觉时安排会议
电子邮件自动机： 不动手指就发送电子邮件

音乐大师： 以编程方式DJ您的播放列表

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

🎯 专业提示： 使用 get_scripting_tips 发现所有200多种自动化食谱！

📜 法律事务（机器人权利）

这个项目是根据麻省理工学院许可证授权的，这意味着你的机器人可以自由漫游！请参阅许可证文件中的细则。

🤖 记得： 强大的自动化能力带来了巨大的责任。明智地使用你的机器人！