applescript-mcp

Instructions

Implementation Reference

• src/categories/calendar.ts:56-87 (handler)

  AppleScript implementation that lists all calendar events for today, executed as the 'calendar_list' tool.

  {
    name: "list",
    description: "List all events for today",
    script: `
    tell application "Calendar"
        set todayStart to (current date)
        set time of todayStart to 0
        set todayEnd to todayStart + 1 * days
        set eventList to {}
        repeat with calendarAccount in calendars
            set eventList to eventList & (every event of calendarAccount whose start date is greater than or equal to todayStart and start date is less than todayEnd)
        end repeat
        set output to ""
        repeat with anEvent in eventList
            set eventStartDate to start date of anEvent
            set eventEndDate to end date of anEvent
  
            -- Format the time parts
            set startHours to hours of eventStartDate
            set startMinutes to minutes of eventStartDate
            set endHours to hours of eventEndDate
            set endMinutes to minutes of eventEndDate
  
            set output to output & "Event: " & summary of anEvent & "\n"
            set output to output & "Start: " & startHours & ":" & text -2 thru -1 of ("0" & startMinutes) & "\n"
            set output to output & "End: " & endHours & ":" & text -2 thru -1 of ("0" & endMinutes) & "\n"
            set output to output & "-------------------\n"
        end repeat
        return output
    end tell
    `,
  },

• src/index.ts:26-26 (registration)

  Registers the calendar category with the MCP server framework, including the 'list' script which becomes the 'calendar_list' tool.

  server.addCategory(calendarCategory);

• src/framework.ts:222-232 (registration)

  MCP listTools handler constructs tool names like 'calendar_list' from category and script names.

    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:244-281 (handler)

  MCP callTool handler resolves 'calendar_list' to the calendar 'list' script, generates the AppleScript content, and executes it.

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