applescript-mcp

Instructions

Implementation Reference

• src/categories/system.ts:31-36 (handler)

  Core handler implementation: AppleScript code that retrieves the name of the currently frontmost application using System Events.

  {
    name: "get_frontmost_app",
    description: "Get the name of the frontmost application",
    script:
      'tell application "System Events" to get name of first process whose frontmost is true',
  },

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

  Tool registration in listTools handler: constructs tool name as 'system_get_frontmost_app' from category 'system' and script 'get_frontmost_app'.

  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:2-25 (registration)

  Imports and registers the 'system' category containing the 'get_frontmost_app' script definition.

  import { systemCategory } from "./categories/system.js";
  import { calendarCategory } from "./categories/calendar.js";
  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);

• src/framework.ts:176-214 (helper)

  Helper function that executes the AppleScript via osascript, used for all tools including system_get_frontmost_app.

  private async executeScript(script: string): Promise<string> {
    // Log script execution (truncate long scripts for readability)
    const scriptPreview = script.length > 100 ? script.substring(0, 100) + "..." : script;
    this.log("debug", "Executing AppleScript", { scriptPreview });
    
    try {
      const startTime = Date.now();
      const { stdout } = await execAsync(
        `osascript -e '${script.replace(/'/g, "'\"'\"'")}'`,
      );
      const executionTime = Date.now() - startTime;
      
      this.log("debug", "AppleScript executed successfully", { 
        executionTimeMs: executionTime,
        outputLength: stdout.length
      });
      
      return stdout.trim();
    } catch (error) {
      // Properly type check the error object
      let errorMessage = "Unknown error occurred";
      if (error && typeof error === "object") {
        if ("message" in error && typeof error.message === "string") {
          errorMessage = error.message;
        } else if (error instanceof Error) {
          errorMessage = error.message;
        }
      } else if (typeof error === "string") {
        errorMessage = error;
      }
      
      this.log("error", "AppleScript execution failed", { 
        error: errorMessage,
        scriptPreview
      });
      
      throw new Error(`AppleScript execution failed: ${errorMessage}`);
    }
  }

• src/framework.ts:234-294 (handler)

  MCP CallTool request handler: parses 'system_get_frontmost_app', locates script, executes it, and returns result.

  // Handle tool execution
  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);
      
      this.log("info", "Tool execution completed successfully", { 
        tool: toolName,
        resultLength: result.length
      });
  
      return {
        content: [
          {
            type: "text",
            text: result,
          },
        ],
      };