applescript-mcp

Instructions

Implementation Reference

• src/categories/iterm.ts:12-24 (handler)

  Core handler for 'iterm_paste_clipboard' tool: AppleScript that triggers copy to clipboard via System Events and pastes into current iTerm window session.

  {
    name: "paste_clipboard",
    description: "Paste clipboard content into iTerm",
    script: `
      tell application "System Events" to keystroke "c" using {command down}
      delay 0.1
      tell application "iTerm"
        set w to current window
        tell w's current session to write text (the clipboard)
        activate
      end tell
    `,
  },

• src/framework.ts:235-281 (handler)

  MCP tool execution handler: parses 'iterm_paste_clipboard' to locate iterm category and paste_clipboard script, generates AppleScript content, and executes it.

  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/framework.ts:221-232 (registration)

  Registers 'iterm_paste_clipboard' tool for MCP ListTools by constructing name as 'iterm_paste_clipboard' from category.script.

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

  Imports and registers the 'iterm' category (containing paste_clipboard script) with the framework, enabling the 'iterm_paste_clipboard' tool.

  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);
  server.addCategory(clipboardCategory);
  server.addCategory(notificationsCategory);
  server.addCategory(itermCategory);