mcp-compliant tool exposure for apple applications
Implements a Model Context Protocol server that discovers and exposes Apple application functionality as standardized MCP tools through a dual-mode initialization strategy. The server uses eager and lazy module loading to manage eight distinct Apple application integrations (Notes, Mail, Messages, Calendar, Contacts, Reminders, Maps, Web Search), allowing MCP-compatible clients like Claude Desktop and Cursor IDE to discover and invoke these tools through a unified interface without direct AppleScript knowledge.
Unique: Implements MCP server specification with dual-mode module loading (eager for core tools, lazy for heavy dependencies) and hybrid AppleScript/JXA execution strategy, enabling zero-configuration discovery of Apple application capabilities by MCP clients without requiring clients to understand AppleScript syntax or Apple automation internals.
vs alternatives: Provides native MCP protocol support for Apple ecosystem (vs. REST API wrappers or custom integrations), enabling seamless integration with Claude Desktop and other MCP clients without custom client-side code.
applescript and jxa-based application automation execution
Executes automation commands against macOS applications by translating MCP tool calls into AppleScript (via run-applescript) or JavaScript for Automation (JXA via @jxa/run library). The system uses a hybrid approach where some applications (Messages, Mail) use AppleScript for reliability, while others (Notes, Contacts, Reminders, Calendar, Maps) use JXA for better performance and modern JavaScript syntax support. Each tool invocation is wrapped with error handling and safe mode checks to prevent unintended application state changes.
Unique: Uses hybrid AppleScript/JXA execution strategy with application-specific selection (AppleScript for Messages/Mail reliability, JXA for Notes/Contacts/Calendar performance), combined with safe mode error handling that validates operations before execution and provides detailed error context from automation runtime failures.
vs alternatives: Provides direct native application control (vs. REST APIs or third-party services) with lower latency and no external service dependencies, while offering better error diagnostics than raw AppleScript through wrapped execution and structured error reporting.
safe mode error handling and operation validation
Implements a safety layer that validates automation operations before execution and provides detailed error context from AppleScript/JXA failures. Includes checks for invalid parameters (malformed email addresses, invalid dates), application state validation (checking if app is running), and graceful error recovery with diagnostic information. Errors include stack traces from automation runtime and suggestions for resolution, enabling developers to debug automation failures without direct AppleScript knowledge.
Unique: Wraps AppleScript/JXA execution with pre-flight validation and post-execution error parsing, providing structured error objects with diagnostic context and resolution suggestions rather than raw AppleScript error codes, enabling non-AppleScript developers to debug automation failures.
vs alternatives: Provides higher-level error handling (vs. raw AppleScript errors) with validation and diagnostics, making automation failures more debuggable and enabling graceful error recovery without requiring AppleScript expertise.
daisy-chaining multi-step automation workflows
Supports composition of multiple automation operations into single natural language requests through sequential tool invocation and data threading. Enables workflows like 'read notes, find contacts, send messages' where output from one operation feeds into the next without intermediate user interaction. The MCP server handles tool sequencing, data transformation between tools, and error propagation across the workflow. Allows AI clients to express complex multi-application workflows as single requests.
Unique: Enables natural language expression of multi-application workflows through MCP tool composition, where AI clients can invoke multiple tools sequentially with data threading between operations, allowing complex automation scenarios without explicit workflow definition or orchestration framework.
vs alternatives: Provides implicit workflow composition through AI reasoning (vs. explicit workflow definition languages like YAML or visual workflow builders), enabling natural language expression of complex automation while leveraging AI's ability to plan and sequence operations.
natural language to apple notes crud operations
Translates natural language requests into structured operations against Apple Notes through JXA automation. Supports listing all notes with metadata, searching notes by content or title, reading full note content with formatting, and creating new notes with specified content. The implementation uses @jxa/run to execute JavaScript directly in the Notes application context, providing access to note objects, folders, and metadata without requiring AppleScript syntax translation.
Unique: Implements JXA-based Notes access with full CRUD capability and metadata extraction (creation dates, folder structure), enabling AI agents to treat Notes as a queryable knowledge base while preserving note formatting and relationships through direct application object access rather than file system parsing.
vs alternatives: Provides real-time access to Notes application state (vs. file-based parsing of Notes database) with automatic sync and support for Notes-specific features like folders and metadata, while avoiding the complexity of parsing Apple's proprietary note storage format.
email send, receive, and search with scheduled delivery
Provides hybrid AppleScript/JXA-based email automation for Mail application, supporting message composition and sending, inbox/folder searching with query syntax, scheduled delivery (send at specific time), and message metadata retrieval. Uses AppleScript for reliability on send operations and JXA for search performance, with support for attachments, CC/BCC recipients, and HTML content. Integrates with Mail's native search indexing for fast query execution across large mailboxes.
Unique: Combines AppleScript for send reliability with JXA for search performance, and uniquely supports scheduled delivery by queuing messages in Mail's draft folder with timed send triggers, enabling AI agents to compose and schedule emails without user interaction while maintaining Mail's native reliability guarantees.
vs alternatives: Provides native Mail application control (vs. SMTP/IMAP libraries) with access to Mail's search indexing for fast queries, scheduled delivery without external services, and automatic handling of Mail's account configuration without requiring credential management.
message sending and conversation reading from messages app
Enables sending iMessage and SMS messages through Messages application via AppleScript automation, and reading conversation history from specific contacts or group chats. Supports both text messages and rich content (emojis, formatting), with access to message timestamps, sender information, and conversation metadata. Uses AppleScript for reliability and direct application control, with error handling for invalid phone numbers/email addresses and network failures.
Unique: Uses AppleScript to directly control Messages application for send operations with automatic protocol selection (iMessage vs SMS based on recipient type), and provides conversation history access with full metadata (timestamps, sender info) through direct application object introspection rather than file system parsing.
vs alternatives: Provides native Messages app control (vs. third-party messaging APIs) with automatic protocol selection and no external service dependencies, while supporting both iMessage and SMS through a unified interface without requiring separate carrier integrations.
calendar event search and creation with natural language dates
Implements JXA-based calendar automation supporting event search by date range or keyword, creation of new calendar events with attendees and reminders, and retrieval of event details (time, location, attendees, notes). Supports natural language date parsing (e.g., 'next Tuesday', 'in 2 weeks') through client-side interpretation, with automatic timezone handling and conflict detection. Events are created in the default calendar or specified calendar with full iCal property support.
Unique: Provides JXA-based calendar access with full event CRUD capability, automatic timezone handling, and conflict detection through direct Calendar application object access, enabling AI agents to reason about scheduling constraints and propose meeting times with awareness of existing calendar state.
vs alternatives: Offers native Calendar app integration (vs. CalDAV/iCal libraries) with automatic sync and support for Calendar-specific features like multiple calendars and attendee management, while avoiding the complexity of parsing iCal format and managing calendar subscriptions.
+4 more capabilities