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);