macOS Automator MCP Server

Überblick

Dieses Projekt stellt einen Model Context Protocol (MCP)-Server, macos_automator , bereit, der die Ausführung von AppleScript- und JavaScript for Automation (JXA)-Skripten unter macOS ermöglicht. Es verfügt über eine Wissensdatenbank mit vordefinierten Skripten, die über die ID zugänglich sind, und unterstützt Inline-Skripte, Skriptdateien und Argumentübergabe. Die Wissensdatenbank wird bei der ersten Verwendung verzögert geladen, um einen schnellen Serverstart zu gewährleisten.

Vorteile

• Führen Sie AppleScript/JXA-Skripte remote über MCP aus.

• Nutzen Sie eine umfangreiche, erweiterbare Wissensdatenbank mit häufigen macOS-Automatisierungsaufgaben.

• Steuern Sie macOS-Anwendungen und Systemfunktionen programmgesteuert.

• Integrieren Sie die macOS-Automatisierung in größere KI-gesteuerte Workflows.

Voraussetzungen

• Node.js (Version >=18.0.0 empfohlen, siehe package.json -Engines).

• macOS.

• EINRICHTUNG WICHTIGER BERECHTIGUNGEN:

  • Die Anwendung, die DIESEN MCP-Server ausführt (z. B. Terminal, Ihre Node.js-Anwendung), erfordert explizite Benutzerberechtigungen auf dem macOS-Computer, auf dem der Server ausgeführt wird.

  • Automatisierungsberechtigungen: Zur Steuerung anderer Anwendungen (Finder, Safari, Mail usw.).

    • Gehen Sie zu: Systemeinstellungen > Datenschutz und Sicherheit > Automatisierung.

    • Suchen Sie in der Liste nach der Anwendung, die den Server ausführt (z. B. Terminal).

    • Stellen Sie sicher, dass für alle zu steuernden Anwendungen Kontrollkästchen aktiviert sind.

    • Siehe Beispiel: docs/automation-permissions-example.png (Platzhalterbild).

  • Zugriffsberechtigungen: Für UI-Skripting über „Systemereignisse“ (z. B. Simulation von Klicks, Tastenanschlägen).

    • Gehen Sie zu: Systemeinstellungen > Datenschutz und Sicherheit > Eingabehilfen.

    • Fügen Sie der Liste die Anwendung hinzu, die den Server ausführt (z. B. Terminal), und stellen Sie sicher, dass das entsprechende Kontrollkästchen aktiviert ist.

  • Beim erstmaligen Versuch, eine neue Anwendung zu steuern oder Bedienungshilfen zu verwenden, kann trotz vorheriger Autorisierung eine Bestätigungsaufforderung von macOS ausgelöst werden. Der Server selbst kann diese Berechtigungen nicht erteilen.

Installation und Verwendung

Der Server wird primär über npx ausgeführt. Dadurch wird sichergestellt, dass Sie die neueste Version verwenden, ohne eine globale Installation durchführen zu müssen.

Fügen Sie mcp.json Ihres MCP-Clients die folgende Konfiguration hinzu (oder eine gleichwertige Konfiguration):

Lokale Ausführung (für Entwicklung oder direkte Verwendung)

Alternativ können Sie für die Entwicklung oder wenn Sie den Server lieber direkt aus einem geklonten Repository ausführen möchten, das bereitgestellte Skript start.sh verwenden. Dies ist nützlich, wenn Sie lokale Änderungen vornehmen oder eine bestimmte Version ausführen möchten.

1. Klonen Sie das Repository:

   git clone https://github.com/steipete/macos-automator-mcp.git cd macos-automator-mcp npm install # Ensure dependencies are installed

2. Konfigurieren Sie Ihren MCP-Client: Aktualisieren Sie die Konfiguration Ihres MCP-Clients, sodass sie auf den absoluten Pfad des Skripts start.sh in Ihrem geklonten Repository verweist.

   Beispiel für mcp.json Konfigurationsausschnitt:

   { "mcpServers": { "macos_automator_local": { "command": "/absolute/path/to/your/cloned/macos-automator-mcp/start.sh", "env": { "LOG_LEVEL": "DEBUG" } } } }

   Wichtig: Ersetzen Sie /absolute/path/to/your/cloned/macos-automator-mcp/start.sh durch den richtigen absoluten Pfad auf Ihrem System.

   Das Skript start.sh verwendet automatisch tsx , um den TypeScript-Quellcode direkt auszuführen, falls keine kompilierte Version gefunden wird, oder führt die kompilierte Version aus dist/ falls verfügbar. Die Umgebungsvariable LOG_LEVEL wird dabei berücksichtigt.

   Hinweis für Entwickler: Das Skript start.sh , insbesondere wenn es so modifiziert wurde, dass es vor der Ausführung bereits kompilierte dist/server.js entfernt (z. B. durch Hinzufügen von rm -f dist/server.js ), soll sicherstellen, dass Sie immer den neuesten TypeScript-Code aus dem Verzeichnis src/ über tsx ausführen. Dies ist ideal für die Entwicklung, um Probleme mit veralteten Builds zu vermeiden. Für die Produktionsbereitstellung (z. B. bei der Veröffentlichung in npm) würde ein Build-Prozess typischerweise eine definitive dist/server.js erstellen, die dann als Einstiegspunkt für das veröffentlichte Paket dient.

Mitgelieferte Werkzeuge

1. execute_script

Führt ein AppleScript- oder JavaScript for Automation (JXA)-Skript unter macOS aus. Skripte können als Inline-Inhalt ( script_content ), als absoluter Dateipfad ( script_path ) oder durch Referenzieren eines Skripts aus der integrierten Wissensdatenbank mithilfe der eindeutigen kb_script_id bereitgestellt werden.

Skriptquellen (schließen sich gegenseitig aus):

• script_content (Zeichenfolge): Roher Skriptcode.

• script_path (Zeichenfolge): Absoluter POSIX-Pfad zu einer Skriptdatei (z. B. .applescript , .scpt , .js ).

• kb_script_id (Zeichenfolge): Die ID eines vordefinierten Skripts aus der Wissensdatenbank des Servers. Verwenden Sie das Tool get_scripting_tips , um verfügbare Skript-IDs und deren Funktionen zu ermitteln.

Sprachspezifikation:

• language (Aufzählung: „Applescript“ | „Javascript“, optional): Geben Sie die Sprache an.

  • Bei Verwendung von kb_script_id wird die Sprache aus dem Wissensdatenbankskript abgeleitet.

  • Wenn die Verwendung script_content oder script_path und language weggelassen wird, wird standardmäßig „Applescript“ verwendet.

Übergeben von Eingaben an Skripte:

• arguments (Array von Zeichenfolgen, optional):

  • Für script_path : Wird als Standardargument an den Skript-Handler on run argv (AppleScript) oder run(argv) (JXA) übergeben.

  • Für kb_script_id : Wird verwendet, wenn das vordefinierte Skript positionelle String-Argumente akzeptiert (z. B. Platzhalter wie --MCP_ARG_1 , --MCP_ARG_2 ersetzt). Überprüfen Sie den argumentsPrompt des Skripts in get_scripting_tips .

• input_data (JSON-Objekt, optional):

  • In erster Linie für kb_script_id -Skripte, die benannte, strukturierte Eingaben akzeptieren.

  • Werte aus diesem Objekt ersetzen Platzhalter im Skript (z. B. --MCP_INPUT:yourKeyName ). Siehe argumentsPrompt von get_scripting_tips .

  • Werte (Zeichenfolgen, Zahlen, Boolesche Werte, einfache Arrays/Objekte) werden in ihre AppleScript-Literaläquivalente konvertiert.

Weitere Optionen:

• timeout_seconds (Ganzzahl, optional, Standard: 60): Maximale Ausführungszeit.

• output_format_mode (Aufzählung, optional, Standard: „auto“): Steuert die Formatierungsflags osascript Ausgabe.

  • 'auto' : (Standard) Verwendet für AppleScript eine menschenlesbare Version ( -sh ) und für JXA eine direkte Ausgabe (keine -s Flags).

  • 'human_readable' : Erzwingt -sh (menschenlesbare Ausgabe, hauptsächlich für AppleScript).

  • 'structured_error' : Erzwingt -ss (strukturierte Fehlerberichterstattung, hauptsächlich für AppleScript).

  • 'structured_output_and_error' : Erzwingt -s ss (strukturierte Ausgabe für Hauptergebnis und Fehler, hauptsächlich für AppleScript).

  • 'direct' : Es werden keine -s Flags verwendet (empfohlen für JXA, auch das Verhalten für JXA im auto -Modus).

• include_executed_script_in_output (Boolesch, optional, Standard: false): Wenn „true“, enthält die Ausgabe den vollständigen Skriptinhalt (nach etwaigen Platzhalterersetzungen für Wissensdatenbankskripte) oder den ausgeführten Skriptpfad. Dieser wird als zusätzlicher Textteil an das Ausgabeinhaltsarray angehängt.

• include_substitution_logs (Boolesch, optional, Standard: false): Wenn „true“, werden detaillierte Protokolle der in Wissensdatenbankskripten durchgeführten Platzhalterersetzungen in die Ausgabe aufgenommen. Dies ist nützlich, um die Verarbeitung und Einfügung input_data und arguments in das Skript zu debuggen. Die Protokolle werden bei Erfolg der Skriptausgabe vorangestellt oder bei einem Fehler an die Fehlermeldung angehängt.

• report_execution_time (boolesch, optional, Standard: false): Wenn true , wird eine zusätzliche Nachricht mit der formatierten Skriptausführungszeit in das Antwortinhaltsarray aufgenommen.

SICHERHEITSWARNUNG UND MACOS-BERECHTIGUNGEN: (Dieselben kritischen Warnungen wie zuvor zur willkürlichen Skriptausführung und zu den Berechtigungen für die Automatisierung/Zugänglichkeit von macOS).

Beispiele:

• (Vorhandene Beispiele für Inline-/Dateipfade bleiben relevant)

• Verwenden des Knowledge Base-Skripts nach ID:

  { "toolName": "execute_script", "input": { "kb_script_id": "safari_get_active_tab_url", "timeout_seconds": 10 } }

• Verwenden des Knowledge Base-Skripts nach ID mit

  { "toolName": "execute_script", "input": { "kb_script_id": "finder_create_folder_at_path", "input_data": { "folder_name": "New MCP Folder", "parent_path": "~/Desktop" } } }

Antwortformat:

Das Tool execute_script gibt eine Antwort im folgenden Format zurück:

• content : Ein Array von Textinhaltselementen, die die Skriptausgabe enthalten

• isError : (Boolesch, optional) Wird auf true gesetzt, wenn bei der Skriptausführung ein Fehler aufgetreten ist. Dieses Flag wird gesetzt, wenn:

  • Die Skriptausgabe (stdout) beginnt mit „Error“ (ohne Berücksichtigung der Groß- und Kleinschreibung).

  • Dadurch können Clients leicht feststellen, ob die Ausführung fehlgeschlagen ist, ohne den Ausgabetext zu analysieren.

Beispielantwort (Erfolg):

Beispielantwort (Fehler):

2. get_scripting_tips

Ruft AppleScript/JXA-Tipps, Beispiele und Details zu ausführbaren Skripten aus der Wissensdatenbank des Servers ab. Nützlich, um verfügbare Skripte, ihre Funktionen und ihre Verwendung mit execute_script (insbesondere kb_script_id ) zu entdecken.

Argumente:

• list_categories (Boolesch, optional, Standard: false): Wenn „true“, wird nur die Liste der verfügbaren Wissensdatenbankkategorien und deren Beschreibungen zurückgegeben. Überschreibt andere Parameter.

• category (Zeichenfolge, optional): Filtert Tipps nach einer bestimmten Kategorie-ID (z. B. „Finder“, „Safari“).

• search_term (Zeichenfolge, optional): Sucht nach einem Schlüsselwort in Tipptiteln, Beschreibungen, Skriptinhalten, Schlüsselwörtern oder IDs.

• refresh_database (Boolesch, optional, Standard: false): Wenn „true“, wird vor der Verarbeitung der Anfrage ein Neuladen der gesamten Wissensdatenbank von der Festplatte erzwungen. Dies ist während der Entwicklung nützlich, wenn Sie Wissensdatenbankdateien aktiv ändern und sicherstellen möchten, dass die neuesten Versionen verwendet werden, ohne den Server neu zu starten.

• limit (Ganzzahl, optional, Standard: 10): Maximale Anzahl der zurückzugebenden Ergebnisse.

Ausgabe:

• Gibt eine in Markdown formatierte Zeichenfolge zurück, die die angeforderten Tipps enthält, einschließlich Titel, Beschreibung, Skriptinhalt, Sprache, ausführbarer ID (falls zutreffend), Argumentaufforderungen und Hinweisen.

Anwendungsbeispiel:

• Alle Kategorien auflisten: { "toolName": "get_scripting_tips", "input": { "list_categories": true } }

• Holen Sie sich Tipps für die Kategorie „Safari“: { "toolName": "get_scripting_tips", "input": { "category": "safari" } }

• Suche nach Tipps zum Thema "Zwischenablage": { "toolName": "get_scripting_tips", "input": { "search_term": "clipboard" } }

Wichtige Anwendungsfälle und Beispiele

• Anwendungskontrolle:

  • Holen Sie sich die aktuelle URL von Safari: { "input": { "script_content": "tell application \"Safari\" to get URL of front document" } }

  • Betreff ungelesener E-Mails in Mail abrufen: { "input": { "script_content": "tell application \"Mail\" to get subject of messages of inbox whose read status is false" } }

• Dateisystemoperationen:

  • Dateien auf dem Desktop auflisten: { "input": { "script_content": "tell application \"Finder\" to get name of every item of desktop" } }

  • Neuen Ordner erstellen: { "input": { "script_content": "tell application \"Finder\" to make new folder at desktop with properties {name:\"My New Folder\"}" } }

• Systeminteraktionen:

  • Zeigen Sie eine Systembenachrichtigung an: { "input": { "script_content": "display notification \"Important Update!\" with title \"System Alert\"" } }

  • Systemlautstärke einstellen: { "input": { "script_content": "set volume output volume 50" } } (0-100)

  • Aktuellen Inhalt der Zwischenablage abrufen: { "input": { "script_content": "the clipboard" } }

Fehlerbehebung

• Berechtigungsfehler: Wenn Skripte keine Apps steuern oder UI-Aktionen ausführen können, überprüfen Sie die Automatisierungs- und Zugriffsberechtigungen in den Systemeinstellungen für die Anwendung, die den MCP-Server ausführt (z. B. Terminal).

• Skriptsyntaxfehler: osascript Fehler werden in der stderr oder in einer Fehlermeldung zurückgegeben. Testen Sie komplexe Skripte zunächst lokal mit dem Skripteditor (für AppleScript) oder einem JXA-Runner.

• Timeouts: Wenn ein Skript länger als timeout_seconds (Standard: 60 Sekunden) benötigt, wird es beendet. Erhöhen Sie das Timeout für Skripte mit langer Laufzeit.

• Datei nicht gefunden: Stellen Sie sicher, dass script_path ein absoluter POSIX-Pfad ist, auf den der Benutzer, der den MCP-Server ausführt, zugreifen kann.

• Fehlerhafte Ausgabe/JXA-Probleme: Stellen Sie bei JXA-Skripten, insbesondere solchen mit Objective-C-Bridging, sicher, dass output_format_mode auf 'direct' oder 'auto' (Standard) eingestellt ist. Die Verwendung von AppleScript-spezifischen Formatierungsflags wie human_readable mit JXA kann zu Fehlern führen. Wenn die AppleScript-Ausgabe nicht korrekt analysiert wird, versuchen Sie structured_output_and_error oder structured_error .

Konfiguration über Umgebungsvariablen

• LOG_LEVEL : Legen Sie die Protokollierungsebene für den Server fest.

  • Werte: DEBUG , INFO , WARN , ERROR

  • Beispiel: LOG_LEVEL=DEBUG npx @steipete/macos-automator-mcp@latest

• KB_PARSING : Steuert, wann die Wissensdatenbank (Skripttipps) analysiert wird.

  • Werte:

    • lazy (Standard): Die Wissensdatenbank wird bei der ersten Anfrage an get_scripting_tips oder bei Verwendung einer kb_script_id in execute_script analysiert. Dies ermöglicht einen schnelleren Serverstart.

    • eager : Die Wissensdatenbank wird beim Serverstart analysiert. Dies kann die Startzeit etwas verlängern, stellt aber sicher, dass die Wissensdatenbank sofort verfügbar ist und etwaige Analysefehler frühzeitig erkannt werden.

  • Beispiel (bei Ausführung über start.sh oder ähnliches):

    KB_PARSING=eager ./start.sh

  • Beispiel (bei der Konfiguration über einen MCP-Runner, der env unterstützt, wie z. B. mcp-agentify ):

    { "env": { "LOG_LEVEL": "INFO", "KB_PARSING": "eager" } }

Für Entwickler

Ausführliche Anweisungen zur lokalen Entwicklung, zur Projektstruktur (einschließlich der knowledge_base ) und zu Beitragsrichtlinien finden Sie unter DEVELOPMENT.md .

Entwicklung

Einzelheiten zur Projektstruktur, zum Erstellen und Testen finden Sie in DEVELOPMENT.md .

Lokale Wissensdatenbank

Sie können die integrierte Wissensdatenbank mit Ihren eigenen lokalen Tipps und freigegebenen Handlern ergänzen. Erstellen Sie eine Verzeichnisstruktur, die mit der knowledge_base in diesem Repository (oder einer Teilmenge davon) identisch ist.

Standardmäßig sucht die Anwendung unter ~/.macos-automator/knowledge_base nach dieser lokalen Wissensdatenbank. Sie können diesen Pfad anpassen, indem Sie die Umgebungsvariable LOCAL_KB_PATH festlegen.

Beispiel:

Angenommen, Sie haben eine lokale Wissensdatenbank unter /Users/yourname/my-custom-kb . Legen Sie die Umgebungsvariable fest: export LOCAL_KB_PATH=/Users/yourname/my-custom-kb

Oder, wenn Sie das Validierungsskript ausführen, können Sie das Argument --local-kb-path verwenden: npm run validate:kb -- --local-kb-path /Users/yourname/my-custom-kb

Struktur und Überschreibungen:

• Ihre lokale Wissensdatenbank sollte die Kategoriestruktur der knowledge_base widerspiegeln (z. B. 01_applescript_core , 05_web_browsers/safari usw.).

• Sie können neue .md Tippdateien oder _shared_handlers (z. B. .applescript oder .js Dateien) hinzufügen.

• Wenn eine Tipp-ID (entweder aus der Frontmatter id: oder aus dem Dateinamen/Pfad generiert) in Ihrer lokalen Wissensdatenbank mit einer ID in der eingebetteten Wissensdatenbank übereinstimmt, überschreibt Ihre lokale Version die eingebettete.

• In ähnlicher Weise überschreiben gemeinsam genutzte Handler mit demselben Namen und derselben Sprache (z. B. my_utility.applescript ) in Ihrem lokalen _shared_handlers Verzeichnis alle eingebetteten Handler mit demselben Namen und derselben Sprache innerhalb derselben Kategorie (oder global, wenn Sie sie im Stammverzeichnis der _shared_handlers Ihrer lokalen KB platzieren).

• Kategoriebeschreibungen aus _category_info.md in Ihrer lokalen KB können auch diejenigen aus der eingebetteten KB für dieselbe Kategorie überschreiben.

Dies ermöglicht die Personalisierung und Erweiterung der verfügbaren Automatisierungsskripte und Tipps, ohne die Kernanwendungsdateien zu ändern.

Beitragen

Beiträge sind willkommen! Bitte senden Sie Probleme und Pull Requests an das GitHub-Repository .

Automatisierungsfunktionen

Dieser Server bietet leistungsstarke macOS-Automatisierungsfunktionen über AppleScript und JavaScript for Automation (JXA). Hier sind einige der nützlichsten Beispiele:

Terminalautomatisierung

• Führen Sie Befehle in neuen Terminal-Registerkarten aus:

  { "input": { "kb_script_id": "terminal_app_run_command_new_tab", "input_data": { "command": "ls -la" } } }

• Führen Sie Befehle mit sudo aus und geben Sie das Passwort sicher ein

• Erfassen Sie die Befehlsausgabe zur Verarbeitung

Browsersteuerung

• Chrome/Safari-Automatisierung:

  { "input": { "kb_script_id": "chrome_open_url_new_tab_profile", "input_data": { "url": "https://example.com", "profile_name": "Default" } } }
  { "input": { "kb_script_id": "safari_get_front_tab_url" } }

• Führen Sie JavaScript im Browserkontext aus:

  { "input": { "kb_script_id": "chrome_execute_javascript", "input_data": { "javascript_code": "document.title" } } }

• Seiteninhalte extrahieren, Formulare bearbeiten und Workflows automatisieren

• Screenshots von Webseiten machen

Systeminteraktion

• Systemeinstellungen umschalten (Dunkelmodus, Lautstärke, Netzwerk):

  { "input": { "kb_script_id": "systemsettings_toggle_dark_mode_ui" } }

• Inhalt der Zwischenablage abrufen/festlegen:

  { "input": { "kb_script_id": "system_clipboard_get_file_paths" } }

• Öffnen/Steuern von Systemdialogen und Warnungen

• Erstellen und Verwalten von Systembenachrichtigungen

Dateioperationen

• Dateien/Ordner erstellen, verschieben und bearbeiten:

  { "input": { "kb_script_id": "finder_create_new_folder_desktop", "input_data": { "folder_name": "My Project" } } }

• Textdateien lesen und schreiben:

  { "input": { "kb_script_id": "fileops_read_text_file", "input_data": { "file_path": "~/Documents/notes.txt" } } }

• Auflisten und Filtern von Dateien in Verzeichnissen

• Abrufen von Dateimetadaten und -eigenschaften

Anwendungsintegration

• Kalender-/Erinnerungsverwaltung:

  { "input": { "kb_script_id": "calendar_create_event", "input_data": { "title": "Meeting", "start_date": "2023-06-01 10:00", "end_date": "2023-06-01 11:00" } } }

• E-Mail-Automatisierung mit Mail.app:

  { "input": { "kb_script_id": "mail_send_email_direct", "input_data": { "recipient": "user@example.com", "subject": "Hello", "body_content": "Message content" } } }

• Musikwiedergabe steuern:

  { "input": { "kb_script_id": "music_playback_controls", "input_data": { "action": "play" } } }

• Arbeiten Sie mit kreativen Apps (Keynote, Pages, Numbers)

Verwenden Sie das Tool get_scripting_tips , um alle verfügbaren Automatisierungsfunktionen nach Kategorien geordnet zu erkunden.

Lizenz

Dieses Projekt ist unter der MIT-Lizenz lizenziert. Weitere Informationen finden Sie in der Datei LICENSE .