applescript-mcp

Instructions

Implementation Reference

• src/categories/finder.ts:89-105 (handler)

  Handler that generates AppleScript to open Quick Look preview for the given file path by selecting it in Finder and pressing spacebar.

  script: (args) => `
    try
      set filePath to POSIX file "${args.path}"
      tell application "Finder"
        activate
        select filePath
        tell application "System Events"
          -- Press Space to trigger Quick Look
          delay 0.5 -- Small delay to ensure Finder is ready
          key code 49 -- Space key
        end tell
      end tell
      return "Quick Look preview opened for ${args.path}"
    on error errMsg
      return "Failed to open Quick Look: " & errMsg
    end try
  `,

• src/categories/finder.ts:79-88 (schema)

  JSON Schema defining the input: object with required 'path' string.

  schema: {
    type: "object",
    properties: {
      path: {
        type: "string",
        description: "File path to preview",
      },
    },
    required: ["path"],
  },

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

  MCP 'listTools' request handler constructs tool name 'finder_quick_look_file' from category.finder + script.quick_look_file

    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:236-247 (registration)

  MCP 'callTool' request handler parses 'finder_quick_look_file' into category='finder' and script='quick_look_file'

  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

• src/index.ts:4-27 (registration)

  Imports and registers the 'finder' category containing the quick_look_file script into the MCP server.

  import { finderCategory } from "./categories/finder.js";
  import { clipboardCategory } from "./categories/clipboard.js";
  import { notificationsCategory } from "./categories/notifications.js";
  import { itermCategory } from "./categories/iterm.js";
  import { mailCategory } from "./categories/mail.js";
  import { pagesCategory } from "./categories/pages.js";
  import { shortcutsCategory } from "./categories/shortcuts.js";
  import { messagesCategory } from "./categories/messages.js";
  import { notesCategory } from "./categories/notes.js";
  
  const server = new AppleScriptFramework({
    name: "applescript-server",
    version: "1.0.4",
    debug: false,
  });
  
  // Log startup information using stderr (server isn't connected yet)
  console.error(`[INFO] Starting AppleScript MCP server - PID: ${process.pid}`);
  
  // Add all categories
  console.error("[INFO] Registering categories...");
  server.addCategory(systemCategory);
  server.addCategory(calendarCategory);
  server.addCategory(finderCategory);