applescript-mcp

Instructions

Implementation Reference

• src/categories/messages.ts:61-116 (handler)

  Core implementation of messages_get_messages tool. Defines the 'get_messages' script in messages category, including input schema (limit parameter) and AppleScript generator that directly queries the iMessage SQLite database at ~/Library/Messages/chat.db to retrieve recent messages with sender, text, date, and chat info.
  { name: "get_messages", description: "Get messages from the Messages app", schema: { type: "object", properties: { limit: { type: "number", description: "Maximum number of messages to retrieve", default: 100 } } }, script: (args) => ` on run -- Path to the Messages database set dbPath to (do shell script "echo ~/Library/Messages/chat.db") -- Create a temporary SQL file for our query set tempFile to (do shell script "mktemp /tmp/imessage_query.XXXXXX") -- Write SQL query to temp file do shell script "cat > " & quoted form of tempFile & " << 'EOF' SELECT datetime(message.date/1000000000 + strftime('%s', '2001-01-01'), 'unixepoch', 'localtime') as message_date, handle.id as sender, message.text as message_text, chat.display_name as chat_name FROM message LEFT JOIN handle ON message.handle_id = handle.ROWID LEFT JOIN chat_message_join ON message.ROWID = chat_message_join.message_id LEFT JOIN chat ON chat_message_join.chat_id = chat.ROWID ORDER BY message.date DESC LIMIT ${args.limit}; EOF" -- Execute the query set queryResult to do shell script "sqlite3 " & quoted form of dbPath & " < " & quoted form of tempFile -- Clean up temp file do shell script "rm " & quoted form of tempFile -- Process and display results set resultList to paragraphs of queryResult set messageData to {} repeat with messageLine in resultList set messageData to messageData & messageLine end repeat return messageData end run ` },
• src/framework.ts:221-232 (registration)

  Dynamic registration of all category scripts as MCP tools in ListToolsRequestSchema handler, constructing tool name as `${category.name}_${script.name}` (e.g. messages_get_messages from messages.get_messages).
  this.server.setRequestHandler(ListToolsRequestSchema, async () => ({ tools: this.categories.flatMap((category) => category.scripts.map((script) => ({ name: `${category.name}_${script.name}`, // Changed from dot to underscore description: `[${category.description}] ${script.description}`, inputSchema: script.schema || { type: "object", properties: {}, }, })), ), }));
• src/framework.ts:235-281 (handler)

  MCP CallToolRequestSchema execution handler for messages_get_messages. Parses tool name by splitting on '_', locates 'messages' category and 'get_messages' script, invokes script function with arguments to generate AppleScript, then executes via osascript.
  this.server.setRequestHandler(CallToolRequestSchema, async (request) => { const toolName = request.params.name; this.log("info", "Tool execution requested", { tool: toolName, hasArguments: !!request.params.arguments }); try { // Split on underscore instead of dot const [categoryName, ...scriptNameParts] = toolName.split("_"); const scriptName = scriptNameParts.join("_"); // Rejoin in case script name has underscores const category = this.categories.find((c) => c.name === categoryName); if (!category) { this.log("warning", "Category not found", { categoryName }); throw new McpError( ErrorCode.MethodNotFound, `Category not found: ${categoryName}`, ); } const script = category.scripts.find((s) => s.name === scriptName); if (!script) { this.log("warning", "Script not found", { categoryName, scriptName }); throw new McpError( ErrorCode.MethodNotFound, `Script not found: ${scriptName}`, ); } this.log("debug", "Generating script content", { categoryName, scriptName, isFunction: typeof script.script === "function" }); const scriptContent = typeof script.script === "function" ? script.script(request.params.arguments) : script.script; const result = await this.executeScript(scriptContent);
• src/index.ts:34-34 (registration)

  Registers the 'messages' ScriptCategory (containing get_messages script) with the AppleScriptFramework server, making messages_get_messages available as an MCP tool.
  server.addCategory(messagesCategory);