applescript-mcp

Instructions

Implementation Reference

• src/categories/calendar.ts:38-54 (handler)

  Handler function that generates AppleScript to add a calendar event using provided title, startDate, endDate, and optional calendar.

  script: (args) => `
    tell application "Calendar"
      set theStartDate to current date
      set hours of theStartDate to ${args.startDate.slice(11, 13)}
      set minutes of theStartDate to ${args.startDate.slice(14, 16)}
      set seconds of theStartDate to ${args.startDate.slice(17, 19)}
  
      set theEndDate to theStartDate + (1 * hours)
      set hours of theEndDate to ${args.endDate.slice(11, 13)}
      set minutes of theEndDate to ${args.endDate.slice(14, 16)}
      set seconds of theEndDate to ${args.endDate.slice(17, 19)}
  
      tell calendar "${args.calendar || "Calendar"}"
        make new event with properties {summary:"${args.title}", start date:theStartDate, end date:theEndDate}
      end tell
    end tell
  `,

• src/categories/calendar.ts:15-37 (schema)

  JSON Schema defining input parameters for the calendar_add tool.

  schema: {
    type: "object",
    properties: {
      title: {
        type: "string",
        description: "Event title",
      },
      startDate: {
        type: "string",
        description: "Start date and time (YYYY-MM-DD HH:MM:SS)",
      },
      endDate: {
        type: "string",
        description: "End date and time (YYYY-MM-DD HH:MM:SS)",
      },
      calendar: {
        type: "string",
        description: "Calendar name (optional)",
        default: "Calendar",
      },
    },
    required: ["title", "startDate", "endDate"],
  },

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

  Registers all tools for listing, constructing tool names like 'calendar_add' from category 'calendar' and script 'add'.

  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/index.ts:26-26 (registration)

  Registers the calendar category containing the 'add' script into the MCP server.

  server.addCategory(calendarCategory);

• src/framework.ts:275-279 (handler)

  Core execution logic: invokes the script handler function (for calendar_add) with arguments to generate AppleScript, then executes it.

  const scriptContent =
    typeof script.script === "function"
      ? script.script(request.params.arguments)
      : script.script;