Applescript MCP

🚀 Guide to Interacting with macOS Applications Using AppleScript

This project aims to demonstrate how to interact with the macOS system and applications through AppleScript. This document details all aspects of the project, including usage methods, implementation details, and the development process.

🚀 Quick Start

This guide provides a comprehensive overview of using AppleScript to interact with macOS applications. It covers basic and advanced features, implementation details, development guidelines, and more.

✨ Features

Basic Features

Calendar Operations

• Add a Calendar Event

tell application "Calendar"
    add event "Event Name" at date (current date)
end tell

• Query Calendar Events

tell application "Calendar"
    get every event of calendar "Work"
end tell

System Preferences

• Adjust Screen Brightness

tell application "System Preferences"
    set the brightness of display to 0.8
end tell

• Manage Network Connections

tell application "Network"
    connect using interface "Wi-Fi" with name "MyNetwork" and password "password123"
end tell

File Operations

• Copy a File

tell application "Finder"
    duplicate the item "/Users/Shared/test.txt" to folder "/Users/user/Desktop"
end tell

• Create a New Folder

tell application "Finder"
    make new folder at "/Users/user/Documents" named "New Folder"
end tell

Advanced Features

Cross-Application Interaction

• Open a Link in Safari

tell application "Safari"
    open location "https://modelcontextprotocol.io"
end tell

• Transfer a File from Finder to Another Application

tell application "Finder" to get the selection
tell application "TextEdit" to open the result

🔧 Technical Details

Technical Architecture

• Script Engine: Based on AppleScript language processing.
• Execution Environment: Use the osascript command to run scripts in the terminal.
• Communication Protocol: Follows the Model Context Protocol (MCP).

Execution Flow

1. Receive an MCP request.
2. Parse the request parameters.
3. Generate the corresponding AppleScript code.
4. Execute the script using osascript.
5. Process and return the execution result.

📚 Documentation

Development Guide

Environment Configuration

# Install dependencies
npm install

# Build the server
npm run build

# Start the MCP inspection tool
npx @modelcontextprotocol/inspector node specified_path/index.js parameters...

New Feature Development

Create a New Category File

Create a new TypeScript file in the src/categories directory:

import { ScriptCategory } from "../types/index.js";

export const newCategory: ScriptCategory = {
  name: "New Category Name",
  scripts: [
    {
      name: "Script 1",
      description: "Script function description",
      execute: (params) => {
        // Script execution logic
        return result;
      }
    }
  ]
};

Add Specific Implementations

Add specific script definitions to the scripts array. Each script includes a name, description, and execution function.

Advanced Topics

Dynamic Script Generation

You can dynamically generate AppleScript code based on input parameters. For example:

generateScript(params: any): string {
    let script = '';
    if (params.action === 'openUrl') {
        script = `tell application "Safari" to open location "${params.url}"`;
    }
    return script;
}

Complex Data Processing

Perform complex data processing before and after script execution. For example:

processData(data: any): any {
    // Data cleaning logic
    const cleanedData = data.map(item => ({
        id: item.id,
        name: item.name.toUpperCase()
    }));
    
    return cleanedData;
}

Debugging Techniques

Use the MCP Inspection Tool

Monitor and debug the script execution process using the modelcontextprotocol/inspector tool.

Logging Setup

Add log output to your code:

import { Logger } from '../utils/logger';

// Initialize the logger
const logger = new Logger('script-executor');

// Add a log
logger.info('Starting script execution');
try {
    // Script execution logic
} catch (error) {
    logger.error('Script execution failed', error);
}

📄 License

This project is licensed under the MIT License. The full text of the license is as follows:

MIT License

Copyright © Year Author Name.

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

Through the above guide, you can gain an in-depth understanding of how to use AppleScript to interact with macOS applications and develop and expand related functions as needed.