applescript-mcp

Instructions

Implementation Reference

• src/categories/mail.ts:13-71 (handler)

  Full tool definition including handler script (AppleScript template), schema, and internal urlEncode helper for mail_create_email (constructed as mail_create_email). The handler generates and executes AppleScript to create email via mailto URL.
  { name: "create_email", description: "Create a new email in Mail.app", schema: { type: "object", properties: { recipient: { type: "string", description: "Email recipient", }, subject: { type: "string", description: "Email subject", }, body: { type: "string", description: "Email body", }, }, required: ["recipient", "subject", "body"], }, script: (args) => ` set recipient to "${args.recipient}" set subject to "${args.subject}" set body to "${args.body}" -- URL encode subject and body set encodedSubject to my urlEncode(subject) set encodedBody to my urlEncode(body) -- Construct the mailto URL set mailtoURL to "mailto:" & recipient & "?subject=" & encodedSubject & "&body=" & encodedBody -- Use Apple Mail's 'mailto' command to create the email tell application "Mail" mailto mailtoURL activate end tell -- Handler to URL-encode text on urlEncode(theText) set theEncodedText to "" set theChars to every character of theText repeat with aChar in theChars set charCode to ASCII number aChar if charCode = 32 then set theEncodedText to theEncodedText & "%20" -- Space else if (charCode ≥ 48 and charCode ≤ 57) or (charCode ≥ 65 and charCode ≤ 90) or (charCode ≥ 97 and charCode ≤ 122) or charCode = 45 or charCode = 46 or charCode = 95 or charCode = 126 then -- Allowed characters: A-Z, a-z, 0-9, -, ., _, ~ set theEncodedText to theEncodedText & aChar else -- Convert to %HH format set hexCode to do shell script "printf '%02X' " & charCode set theEncodedText to theEncodedText & "%" & hexCode end if end repeat return theEncodedText end urlEncode `,
• src/categories/mail.ts:16-33 (schema)

  Input schema defining required recipient, subject, body for create_email tool.
  schema: { type: "object", properties: { recipient: { type: "string", description: "Email recipient", }, subject: { type: "string", description: "Email subject", }, body: { type: "string", description: "Email body", }, }, required: ["recipient", "subject", "body"], },
• src/framework.ts:221-232 (registration)

  Dynamic tool registration in listTools handler: constructs 'mail_create_email' from category 'mail' + script 'create_email'.
  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/framework.ts:235-331 (handler)

  Generic MCP tool call handler: resolves 'mail_create_email' to mail category + create_email script, generates AppleScript from template with args, executes via osascript.
  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, }, ], }; } catch (error) { if (error instanceof McpError) { this.log("error", "MCP error during tool execution", { tool: toolName, errorCode: error.code, errorMessage: error.message }); throw error; } 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", "Error during tool execution", { tool: toolName, errorMessage }); return { content: [ { type: "text", text: `Error: ${errorMessage}`, }, ], isError: true, }; } });
• src/index.ts:31-31 (registration)

  Registers the mail category (containing create_email) with the framework server.
  server.addCategory(mailCategory);