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;
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了吗？你有一个很酷的自动化想法吗？你的机器人军队需要你！向提交问题并拉取请求 .
💪 机器人超级大国展示
以下是你的新硅伙伴可以开箱即用的东西：
🖥️ 终端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多种自动化食谱！
📜 法律事务（机器人权利）
这个项目是根据麻省理工学院许可证授权的，这意味着你的机器人可以自由漫游！请参阅 许可证 文件中的细则。
______________________________________________________________________
🤖 记得： 强大的自动化能力带来了巨大的责任。明智地使用你的机器人！