feat: add macos-automator MCP for AppleScript automation#89
feat: add macos-automator MCP for AppleScript automation#89marcusquinn merged 2 commits intomainfrom
Conversation
- Add macos-automator MCP server (steipete/macos-automator-mcp) - Create @mac subagent to enable MCP tools on demand - MCP disabled globally, enabled via @mac subagent for context efficiency - Add tools/automation/ folder with mac.md and macos-automator.md docs - Update AGENTS.md with automation subagent references - macOS-only (platform check in generate-opencode-agents.sh) Tools available via @mac: - execute_script: Run AppleScript or JXA code - get_scripting_tips: Search 200+ pre-built automation scripts - accessibility_query: Query and interact with UI elements
|
Note Other AI code review bot(s) detectedCodeRabbit has detected other AI code review bot(s) in this pull request and will avoid duplicating their findings in the review comments. This may lead to a less comprehensive review. WalkthroughAdds macOS automation support: Darwin-gated macos-automator MCP server registration and macOS-specific tool bindings, plus user-facing documentation (quick-start and full reference). Changes are configuration and docs-only; runtime behavior applies only on macOS. Changes
Sequence Diagram(s)sequenceDiagram
autonumber
Actor Developer
Developer->>Generator Script: run generate-opencode-agents.sh
Generator Script->>Platform Check: platform.system() == 'Darwin'?
alt Darwin (macOS)
Generator Script->>MCP Registry: add macos-automator MCP entry (`@steipete/`...)
Generator Script->>Tools Catalog: register macos-automator_* (disabled globally)
Generator Script->>Subagent Logic: when subagent == macos-automator/mac -> enable macos-automator_* and webfetch permissions
else Non-Darwin
Generator Script-->>Tools Catalog: skip macOS-specific entries
end
Developer->>Agent Runtime: start agent with `@mac` subagent
Agent Runtime->>MCP Server: invoke macos-automator tools (execute_script, accessibility_query, etc.)
MCP Server->>macOS (OS APIs): perform automation actions (AppleScript/JXA, Accessibility)
macOS->>MCP Server: return results
MCP Server->>Agent Runtime: deliver tool outputs
Estimated code review effort🎯 3 (Moderate) | ⏱️ ~20 minutes Possibly related PRs
Poem
🚥 Pre-merge checks | ✅ 3✅ Passed checks (3 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing touches
📜 Recent review detailsConfiguration used: Path: .coderabbit.yaml Review profile: CHILL Plan: Pro 📒 Files selected for processing (2)
🚧 Files skipped from review as they are similar to previous changes (1)
🧰 Additional context used📓 Path-based instructions (1).agent/scripts/*.sh⚙️ CodeRabbit configuration file
Files:
⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (1)
🔇 Additional comments (3)
✏️ Tip: You can disable this entire section by setting Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
Summary of ChangesHello @marcusquinn, I'm Gemini Code Assist1! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed! This pull request significantly enhances the system's capabilities by integrating native macOS automation. It introduces a new subagent, @mac, which acts as a gateway to powerful AppleScript and JXA functionalities, allowing for direct control and interaction with macOS applications and UI elements. This enables users to automate complex workflows and system tasks directly through the platform, while maintaining a secure and efficient approach by only activating these tools when explicitly requested. Highlights
Using Gemini Code AssistThe full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips. Invoking Gemini You can request assistance from Gemini at any point by creating a comment using either
Customization To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a Limitations & Feedback Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with 👍 and 👎 on @gemini-code-assist comments. If you're interested in giving your feedback about your experience with Gemini Code Assist for Github and other Google products, sign up here. You can also get AI-powered code generation, chat, as well as code reviews directly in the IDE at no cost with the Gemini Code Assist IDE Extension. Footnotes
|
🔍 Code Quality Report�[0;35m[MONITOR]�[0m Code Review Monitoring Report �[0;34m[INFO]�[0m Latest Quality Status: �[0;34m[INFO]�[0m Recent monitoring activity: 📈 Current Quality Metrics
Generated on: Wed Jan 14 15:55:29 UTC 2026 Generated by AI DevOps Framework Code Review Monitoring |
![gemini-code-assist[bot]](https://avatars.githubusercontent.com/in/956858?s=60&v=4){kind=small}
There was a problem hiding this comment.
Code Review
This pull request introduces a new macos-automator MCP for AppleScript and JXA automation on macOS, along with a @mac subagent to use it. The changes include adding documentation, updating agent lists, and modifying the agent generation script to configure the new MCP for macOS users. My review focuses on ensuring the stability of the new integration and maintaining code quality. I've identified a significant issue with using @latest for the npm package dependency, which could lead to instability, and recommend pinning it to a specific version. I also have a few suggestions to improve code style in the generation script and consistency in the documentation.
| if 'macos-automator' not in config['mcp']: | ||
| config['mcp']['macos-automator'] = { | ||
| "type": "local", | ||
| "command": ["npx", "-y", "@steipete/macos-automator-mcp@latest"], |
There was a problem hiding this comment.
Using @latest for npm packages in an automated script can introduce breaking changes unexpectedly, leading to instability. It is a strong best practice to pin dependencies to a specific version to ensure reproducible and stable environments. The latest version appears to be 0.2.0. Please replace @latest with a specific, known-good version of the package.
| "command": ["npx", "-y", "@steipete/macos-automator-mcp@latest"], | |
| "command": ["npx", "-y", "@steipete/macos-automator-mcp@0.2.0"], |
|
|
||
| # macOS Automator MCP - AppleScript and JXA automation (macOS only) | ||
| # Docs: https://github.com/steipete/macos-automator-mcp | ||
| import platform |
There was a problem hiding this comment.
According to Python's PEP 8 style guide, all imports should be at the top of the script. Placing import platform in the middle of the logic makes the code harder to read and maintain, as dependencies are not declared in one place. Please move this import to the top of the Python script block.
| ## Quick Reference | ||
|
|
||
| - **Purpose**: Execute AppleScript and JXA (JavaScript for Automation) on macOS | ||
| - **Install**: `npm install -g @steipete/macos-automator-mcp@latest` |
There was a problem hiding this comment.
While using @latest can be convenient for users to get the newest version, it can also lead to unexpected issues if a new release has breaking changes. For documentation, it's safer to recommend a specific version to ensure users have a stable starting point. They can always choose to use a newer version consciously. This feedback applies to other installation commands in this file as well.
| - **Install**: `npm install -g @steipete/macos-automator-mcp@latest` | |
| - **Install**: `npm install -g @steipete/macos-automator-mcp@0.2.0` |
| ```json | ||
| "macos-automator": { | ||
| "type": "local", | ||
| "command": ["npx", "-y", "@steipete/macos-automator-mcp@latest"], |
There was a problem hiding this comment.
In configuration examples, it's particularly important to use a specific version instead of @latest to promote stability and reproducibility for users who copy-paste this code. Please update this and other configuration examples in this file to use a specific version (e.g., 0.2.0).
| "command": ["npx", "-y", "@steipete/macos-automator-mcp@latest"], | |
| "command": ["npx", "-y", "@steipete/macos-automator-mcp@0.2.0"], |
🤖 Augment PR SummarySummary: Adds optional macOS automation support (AppleScript/JXA + accessibility) via the Changes:
Technical Notes: The generator gates MCP server config behind 🤖 Was this summary useful? React with 👍 or 👎 |
![augmentcode[bot]](https://avatars.githubusercontent.com/in/1027498?s=60&v=4){kind=small}
| "type": "local", | ||
| "command": ["npx", "-y", "@steipete/macos-automator-mcp@latest"], | ||
| "enabled": True | ||
| } |
There was a problem hiding this comment.
The PR description mentions MCP being “disabled globally”, but this sets the MCP server itself to "enabled": True (which may start it by default on macOS and trigger permission prompts). Consider aligning the config behavior with the docs/expectation so “disabled globally” is unambiguous.
🤖 Was this useful? React with 👍 or 👎
| shadcn) | ||
| extra_tools=$' shadcn_*: true\n write: true\n edit: true' | ||
| ;; | ||
| macos-automator|mac) |
There was a problem hiding this comment.
This macos-automator|mac branch enables macos-automator_* tools unconditionally, but the MCP server config is only added on Darwin earlier; on non-macOS this could generate subagents that reference tools that don’t exist. Consider gating this extra-tools injection to macOS as well to avoid broken subagent tool configs on other platforms.
🤖 Was this useful? React with 👍 or 👎
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 2
🤖 Fix all issues with AI agents
In @.agent/tools/automation/macos-automator.md:
- Around line 266-282: Remove the JavaScript-style comments and ensure each
example is a valid, standalone JSON code block; replace the inline comments
before the first object with a proper fenced code block containing only the JSON
object that has "script_content" and "language", and for the two KB examples
create separate fenced JSON blocks each containing only the single object with
"kb_script_id": "safari_get_active_tab_url" and "kb_script_id":
"systemsettings_toggle_dark_mode_ui" respectively, and add any human-readable
captions outside the fences (not as // comments).
🧹 Nitpick comments (2)
.agent/tools/automation/mac.md (1)
91-93: Minor: Documentation path reference format.The reference uses a relative path without the leading
./or@prefix. Consider whether this should match the pattern used elsewhere in the framework for subagent references.See `tools/automation/macos-automator.md` for complete setup and configuration.This format is acceptable but verify it aligns with how other subagents reference their full documentation.
.agent/scripts/generate-opencode-agents.sh (1)
474-474: Consider: Import statement placement.The
import platformis placed inline within the conditional block at line 474. While this works, Python best practice typically places imports at the top of the script. However, since this is embedded in a heredoc andimport shutilalready appears at line 411, this pattern is consistent with the existing code structure.If you want to consolidate imports for clarity:
import shutil +import platform bun_path = shutil.which('bun')Then remove the inline import at line 474. This is purely a style preference and not required.
📜 Review details
Configuration used: Path: .coderabbit.yaml
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (4)
.agent/AGENTS.md.agent/scripts/generate-opencode-agents.sh.agent/tools/automation/mac.md.agent/tools/automation/macos-automator.md
🧰 Additional context used
📓 Path-based instructions (1)
.agent/scripts/*.sh
⚙️ CodeRabbit configuration file
.agent/scripts/*.sh: Automation scripts - focus on:
- Reliability and robustness
- Clear logging and feedback
- Proper exit codes
- Error recovery mechanisms
Files:
.agent/scripts/generate-opencode-agents.sh
🧠 Learnings (9)
📚 Learning: 2025-11-29T04:34:42.033Z
Learnt from: CR
Repo: marcusquinn/aidevops PR: 0
File: AGENT.md:0-0
Timestamp: 2025-11-29T04:34:42.033Z
Learning: Reference AGENTS.md (authoritative) instead of AGENT.md for AI assistant guidance
Applied to files:
.agent/tools/automation/macos-automator.md.agent/tools/automation/mac.md.agent/AGENTS.md
📚 Learning: 2025-11-29T04:34:30.742Z
Learnt from: CR
Repo: marcusquinn/aidevops PR: 0
File: GEMINI.md:0-0
Timestamp: 2025-11-29T04:34:30.742Z
Learning: Reference AGENTS.md for authoritative AI assistant guidance instead of GEMINI.md
Applied to files:
.agent/tools/automation/mac.md.agent/AGENTS.md
📚 Learning: 2026-01-06T15:57:56.027Z
Learnt from: CR
Repo: marcusquinn/aidevops PR: 0
File: AGENTS.md:0-0
Timestamp: 2026-01-06T15:57:56.027Z
Learning: Applies to **/AGENTS.md : Limit root AGENTS.md to ~50-100 max instructions with universal applicability to >80% of tasks
Applied to files:
.agent/tools/automation/mac.md.agent/AGENTS.md
📚 Learning: 2025-11-29T04:34:27.158Z
Learnt from: CR
Repo: marcusquinn/aidevops PR: 0
File: CLAUDE.md:0-0
Timestamp: 2025-11-29T04:34:27.158Z
Learning: All instructions, documentation, and operational guidance should be maintained in AGENTS.md as the single source of truth
Applied to files:
.agent/tools/automation/mac.md.agent/AGENTS.md
📚 Learning: 2025-11-29T04:34:30.742Z
Learnt from: CR
Repo: marcusquinn/aidevops PR: 0
File: GEMINI.md:0-0
Timestamp: 2025-11-29T04:34:30.742Z
Learning: Maintain all instructions, documentation, and operational guidance in AGENTS.md as the single source of truth
Applied to files:
.agent/tools/automation/mac.md.agent/AGENTS.md
📚 Learning: 2026-01-06T15:57:56.027Z
Learnt from: CR
Repo: marcusquinn/aidevops PR: 0
File: AGENTS.md:0-0
Timestamp: 2026-01-06T15:57:56.027Z
Learning: Applies to **/AGENTS.md : Use progressive disclosure in AGENTS.md with pointers to subagents rather than inline content
Applied to files:
.agent/AGENTS.md
📚 Learning: 2025-11-29T04:34:42.033Z
Learnt from: CR
Repo: marcusquinn/aidevops PR: 0
File: AGENT.md:0-0
Timestamp: 2025-11-29T04:34:42.033Z
Learning: Maintain all AI assistant instructions, documentation, and operational guidance in AGENTS.md as the single source of truth
Applied to files:
.agent/AGENTS.md
📚 Learning: 2025-12-22T01:24:53.937Z
Learnt from: CR
Repo: marcusquinn/aidevops PR: 0
File: templates/home/AGENTS.md:0-0
Timestamp: 2025-12-22T01:24:53.937Z
Learning: Follow all security protocols and working directory specifications defined in ~/Git/aidevops/AGENTS.md
Applied to files:
.agent/AGENTS.md
📚 Learning: 2025-12-22T01:24:53.937Z
Learnt from: CR
Repo: marcusquinn/aidevops PR: 0
File: templates/home/AGENTS.md:0-0
Timestamp: 2025-12-22T01:24:53.937Z
Learning: Reference the authoritative repository at ~/Git/aidevops/ for all detailed AI assistant instructions and configurations
Applied to files:
.agent/AGENTS.md
⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (1)
- GitHub Check: Codacy Static Code Analysis
🔇 Additional comments (7)
.agent/tools/automation/macos-automator.md (2)
1-13: LGTM! Well-structured frontmatter.The tool permissions correctly enable
macos-automator_*: truewhile keeping write/edit disabled for a read-focused automation subagent. Thebash: truepermission appropriately supports script execution verification.
469-470: Documentation links verified and valid.Both referenced documentation files exist at the correct relative paths:
../browser/stagehand.mdresolves to.agent/tools/browser/stagehand.md✓../browser/playwright.mdresolves to.agent/tools/browser/playwright.md✓No action required.
.agent/tools/automation/mac.md (1)
1-13: LGTM! Consistent frontmatter with parent documentation.Tool permissions correctly mirror the full
macos-automator.mdconfiguration, maintaining consistency across the subagent ecosystem..agent/scripts/generate-opencode-agents.sh (2)
472-486: LGTM! Clean Darwin-gated MCP configuration.The implementation follows established patterns in this script:
- Platform check using
platform.system() == 'Darwin'is idiomatic Python- Idempotent check (
if 'macos-automator' not in config['mcp']) prevents duplicate entries- Logging feedback via
print()statements matches existing MCP additions- Both MCP server and tools configurations are handled together
This maintains the A-grade quality standard.
542-544: LGTM! Correct case pattern for subagent tool binding.The
macos-automator|macpattern correctly enables both naming conventions, and the tool permissions (macos-automator_*andwebfetch) align with the documentation frontmatter..agent/AGENTS.md (2)
395-395: LGTM! Appropriate subagent folder documentation.The new
tools/automation/entry correctly describes macOS automation capabilities and lists bothmacandmacos-automatoras key subagents, maintaining consistency with the new documentation files.
487-487: LGTM! Progressive disclosure entry added.The task domain mapping correctly guides users to
tools/automation/mac.mdfor macOS automation needs, with appropriate feature keywords (AppleScript, JXA, app control). This follows the progressive disclosure pattern established in the framework learnings.
✏️ Tip: You can disable this entire section by setting review_details to false in your review settings.
- Pin macos-automator-mcp to v0.2.0 instead of @latest for stability - Move 'import platform' to top of Python block with other imports - Fix invalid JSON comments in documentation examples - Gate subagent tool injection to macOS only (uname check) - Update all config examples to use pinned version
|
🔍 Code Quality Report�[0;35m[MONITOR]�[0m Code Review Monitoring Report �[0;34m[INFO]�[0m Latest Quality Status: �[0;34m[INFO]�[0m Recent monitoring activity: 📈 Current Quality Metrics
Generated on: Wed Jan 14 16:00:58 UTC 2026 Generated by AI DevOps Framework Code Review Monitoring |
1 participant
Summary
@macsubagent to enable MCP tools on demand (context-efficient pattern)@macsubagent invocationChanges
New Files
.agent/tools/automation/mac.md-@macsubagent documentation.agent/tools/automation/macos-automator.md- Full MCP setup guideModified Files
.agent/AGENTS.md- Addedtools/automation/to subagent folders table.agent/scripts/generate-opencode-agents.sh- Added macos-automator MCP config (macOS-only)MCP Tools Available via @mac
execute_scriptget_scripting_tipsaccessibility_queryUsage
Requirements
Testing
./setup.shdeploys successfully@macsubagent generated withmacos-automator_*: trueSummary by CodeRabbit
New Features
Documentation
✏️ Tip: You can customize this high-level summary in your review settings.