applescript-mcp: Instructions file for Claude Code

CLAUDE.md

Project Overview

This is the AppleScript MCP (Model Context Protocol) Server - a dual-implementation MCP server that allows AI assistants to execute AppleScript on macOS systems. The server is available in both Node.js and Python implementations.

Key Capabilities:

• Execute AppleScript to interact with macOS applications (Notes, Calendar, Contacts, Messages, Mail, etc.)
• Search files using Spotlight/Finder
• Read/write file contents and execute shell commands
• Remote execution via SSH
• Docker support with host.docker.internal for Mac host access

Architecture

Dual Implementation

The project provides two parallel implementations:

1. Node.js (server.js): Primary implementation using @modelcontextprotocol/sdk
2. Python (src/applescript_mcp/server.py): Alternative implementation using Python MCP SDK

Both implementations provide identical functionality and should be kept in sync.

Core Components

server.js (Node.js)

• Main entry point: Implements MCP tool applescript_execute
• Execution modes:
  • Local: Uses /usr/bin/osascript to run AppleScript files
  • Remote: Uses SSH (node-ssh) to execute on remote Mac hosts
• Configuration via CLI args: --remoteHost, --remoteUser, --remotePassword
• Logging via custom Logger class (levels: ERROR, WARN, INFO, DEBUG)

Key Functions:

• executeAppleScript(code, timeout): Determines local vs remote execution
• executeLocalAppleScript(code, timeout): Executes on local machine
• executeRemoteAppleScript(code, timeout): Executes via SSH connection

Development Guidelines

Code Style

• Keep implementations simple and minimal (currently <100 LOC for core logic)
• Use proper error handling - return error messages rather than throwing
• Always clean up temporary files
• Log important operations at appropriate levels

When Making Changes

1. Maintain Dual Implementation Parity: If you modify the Node.js version, apply equivalent changes to the Python version and vice versa.