applescript-mcp

Instructions

Implementation Reference

• src/categories/system.ts:37-60 (handler)

  Handler implementation for the 'system_launch_app' tool. This defines the AppleScript template that launches or activates the specified application by name, handling errors.

  {
    name: "launch_app",
    description: "Launch an application",
    schema: {
      type: "object",
      properties: {
        name: {
          type: "string",
          description: "Application name",
        },
      },
      required: ["name"],
    },
    script: (args) => `
          try
            tell application "${args.name}"
              activate
            end tell
            return "Application ${args.name} launched successfully"
          on error errMsg
            return "Failed to launch application: " & errMsg
          end try
        `,
  },

• src/categories/system.ts:40-49 (schema)

  Input schema for 'system_launch_app' tool, requiring the application 'name' as a string.

  schema: {
    type: "object",
    properties: {
      name: {
        type: "string",
        description: "Application name",
      },
    },
    required: ["name"],
  },

• src/index.ts:25-25 (registration)

  Registration of the 'system' category, which includes the 'launch_app' script that becomes the 'system_launch_app' tool.

  server.addCategory(systemCategory);

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

  Tool registration in listTools handler, constructing tool name as 'category_script' e.g. 'system_launch_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/framework.ts:235-281 (handler)

  Core execution handler for all tools including 'system_launch_app'. Parses tool name by splitting on '_', retrieves category/script, generates script content, and executes it 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);