applescript-mcp

Instructions

Implementation Reference

• src/categories/system.ts:61-89 (handler)

  Core implementation of the 'quit_app' script in the 'system' category. This defines the input schema, generates the AppleScript code based on arguments, and handles the quit logic. Tool name becomes 'system_quit_app' via category prefixing.

  {
    name: "quit_app",
    description: "Quit an application",
    schema: {
      type: "object",
      properties: {
        name: {
          type: "string",
          description: "Application name",
        },
        force: {
          type: "boolean",
          description: "Force quit if true",
          default: false,
        },
      },
      required: ["name"],
    },
    script: (args) => `
          try
            tell application "${args.name}"
              ${args.force ? "quit saving no" : "quit"}
            end tell
            return "Application ${args.name} quit successfully"
          on error errMsg
            return "Failed to quit application: " & errMsg
          end try
        `,
  },

• src/categories/system.ts:64-78 (schema)

  Input schema for the quit_app tool, specifying the application name (required) and optional force flag.

  schema: {
    type: "object",
    properties: {
      name: {
        type: "string",
        description: "Application name",
      },
      force: {
        type: "boolean",
        description: "Force quit if true",
        default: false,
      },
    },
    required: ["name"],
  },

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

  Registers the MCP tool 'system_quit_app' by constructing tool names as '{category}_{script}' (e.g., system_quit_app) and listing them with descriptions and schemas.

  // List available tools
  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:243-247 (helper)

  Helper logic to parse tool name 'system_quit_app' into category 'system' and script 'quit_app' during tool execution.

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

  Imports the system category (containing quit_app) and registers it with the framework server.

  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);