macOS Automator MCP Server

macOS Automator MCP-сервер

Обзор

Этот проект предоставляет сервер Model Context Protocol (MCP), macos_automator , который позволяет выполнять скрипты AppleScript и JavaScript for Automation (JXA) на macOS. Он содержит базу знаний предопределенных скриптов, доступных по идентификатору, и поддерживает встроенные скрипты, файлы скриптов и передачу аргументов. База знаний загружается лениво при первом использовании для быстрого запуска сервера.

Преимущества

• Удаленное выполнение скриптов AppleScript/JXA через MCP.
• Используйте обширную, расширяемую базу знаний по распространенным задачам автоматизации macOS.
• Управляйте приложениями и системными функциями macOS программным способом.
• Интегрируйте автоматизацию macOS в более крупные рабочие процессы на базе ИИ.

Предпосылки

• Node.js (рекомендуется версия >=18.0.0, см. движки package.json ).
• macOS.
• НАСТРОЙКА КРИТИЧЕСКИХ РАЗРЕШЕНИЙ:
  • Приложение, запускающее ЭТОТ сервер MCP (например, Терминал, ваше приложение Node.js), требует явных разрешений пользователя на компьютере macOS, где запущен сервер.
  • Разрешения автоматизации: для управления другими приложениями (Finder, Safari, Mail и т. д.).
    • Перейдите в: Настройки системы > Конфиденциальность и безопасность > Автоматизация.
    • Найдите в списке приложение, запускающее сервер (например, Терминал).
    • Убедитесь, что установлены флажки для всех приложений, которые необходимо контролировать.
    • См. пример: docs/automation-permissions-example.png (изображение-заполнитель).
  • Разрешения на доступ: для сценариев пользовательского интерфейса через «системные события» (например, имитация щелчков, нажатий клавиш).
    • Перейдите в раздел: Системные настройки > Конфиденциальность и безопасность > Специальные возможности.
    • Добавьте в список приложение, запускающее сервер (например, Терминал), и убедитесь, что его флажок отмечен.
  • Первые попытки управлять новым приложением или использовать функции доступности могут по-прежнему вызывать запрос подтверждения macOS, даже если они предварительно авторизованы. Сам сервер не может предоставить эти разрешения.

Установка и использование

Основной способ запустить этот сервер — через npx . Это гарантирует, что вы используете последнюю версию без необходимости глобальной установки.

Добавьте следующую конфигурацию в mcp.json вашего клиента MCP (или эквивалентную конфигурацию):

Запуск локально (для разработки или прямого использования)

В качестве альтернативы, для разработки или если вы предпочитаете запускать сервер напрямую из клонированного репозитория, вы можете использовать предоставленный скрипт start.sh . Это полезно, если вы хотите сделать локальные изменения или запустить определенную версию.

1. Клонируйте репозиторий:
   git clone https://github.com/steipete/macos-automator-mcp.git cd macos-automator-mcp npm install # Ensure dependencies are installed
2. Настройте клиент MCP: обновите конфигурацию клиента MCP, чтобы она указывала на абсолютный путь к скрипту start.sh в клонированном репозитории.Пример фрагмента конфигурации mcp.json :
   { "mcpServers": { "macos_automator_local": { "command": "/absolute/path/to/your/cloned/macos-automator-mcp/start.sh", "env": { "LOG_LEVEL": "DEBUG" } } } }
   Важно: замените /absolute/path/to/your/cloned/macos-automator-mcp/start.sh на правильный абсолютный путь в вашей системе.Скрипт start.sh автоматически использует tsx для прямого запуска исходного кода TypeScript, если скомпилированная версия не найдена, или запускает скомпилированную версию из dist/ если она доступна. Он учитывает переменную окружения LOG_LEVEL .Примечание для разработчиков: скрипт start.sh , особенно если он изменен для удаления любого ранее существующего скомпилированного dist/server.js перед выполнением (например, путем добавления rm -f dist/server.js ), предназначен для того, чтобы гарантировать, что вы всегда запускаете последний код TypeScript из каталога src/ через tsx . Это идеально подходит для разработки, чтобы предотвратить проблемы с устаревшими сборками. Для развертывания в продакшне (например, при публикации в npm) процесс сборки обычно создает окончательный dist/server.js , который затем становится точкой входа для опубликованного пакета.

Предоставляемые инструменты

1. execute_script

Выполняет скрипт AppleScript или JavaScript for Automation (JXA) на macOS. Скрипты могут быть предоставлены как встроенное содержимое ( script_content ), абсолютный путь к файлу ( script_path ) или путем ссылки на скрипт из встроенной базы знаний с использованием его уникального kb_script_id .

Источники скрипта (взаимоисключающие):

• script_content (строка): Необработанный код скрипта.
• script_path (строка): Абсолютный путь POSIX к файлу скрипта (например, .applescript , .scpt , .js ).
• kb_script_id (string): Идентификатор предопределенного скрипта из базы знаний сервера. Используйте инструмент get_scripting_tips для обнаружения доступных идентификаторов скриптов и их функций.

Спецификация языка:

• language (enum: 'applescript' | 'javascript', необязательно): укажите язык.
  • При использовании kb_script_id язык определяется из скрипта базы знаний.
  • Если используется script_content или script_path и language не указан, по умолчанию используется «applescript».

Передача входных данных в скрипты:

• arguments (массив строк, необязательно):
  • Для script_path : Передаются как стандартные аргументы on run argv (AppleScript) или run(argv) (JXA) скрипта при запуске.
  • Для kb_script_id : используется, если предопределенный скрипт предназначен для приема позиционных строковых аргументов (например, заменяет заполнители, такие как --MCP_ARG_1 , --MCP_ARG_2 ). Проверьте argumentsPrompt скрипта из get_scripting_tips .
• input_data (объект JSON, необязательно):
  • В первую очередь для скриптов kb_script_id , предназначенных для приема именованных структурированных входных данных.
  • Значения из этого объекта заменяют заполнители в скрипте (например, --MCP_INPUT:yourKeyName ). См. argumentsPrompt из get_scripting_tips .
  • Значения (строки, числа, логические значения, простые массивы/объекты) преобразуются в их литеральные эквиваленты AppleScript.

Другие варианты:

• timeout_seconds (целое число, необязательное, по умолчанию: 60): Максимальное время выполнения.
• output_format_mode (enum, необязательно, по умолчанию: 'auto'): управляет флагами форматирования вывода osascript .
  • 'auto' : (по умолчанию) использует понятный человеку формат для AppleScript ( -sh ) и прямой вывод (без флагов -s ) для JXA.
  • 'human_readable' : принудительно включает -sh (вывод, понятный человеку, в основном для AppleScript).
  • 'structured_error' : принудительно включает -ss (структурированные отчеты об ошибках, в основном для AppleScript).
  • 'structured_output_and_error' : принудительно устанавливает -s ss (структурированный вывод для основного результата и ошибок, в основном для AppleScript).
  • 'direct' : флаги -s не используются (рекомендуется для JXA, также поведение JXA в auto режиме).
• include_executed_script_in_output (boolean, необязательный, по умолчанию: false): Если true, вывод будет включать полное содержимое скрипта (после любых подстановок заполнителей для скриптов базы знаний) или путь к скрипту, который был выполнен. Это добавляется как дополнительная текстовая часть в массив выходного содержимого.
• include_substitution_logs (boolean, необязательно, по умолчанию: false): Если true, подробные журналы замен заполнителей, выполненных в скриптах базы знаний, включаются в вывод. Это полезно для отладки того, как input_data и arguments обрабатываются и вставляются в скрипт. Журналы добавляются в начало вывода скрипта при успешном выполнении или в конец сообщения об ошибке при неудаче.
• report_execution_time (boolean, необязательный, по умолчанию: false): Если true , в массив содержимого ответа будет включено дополнительное сообщение с отформатированным временем выполнения скрипта.

ПРЕДУПРЕЖДЕНИЕ О БЕЗОПАСНОСТИ И РАЗРЕШЕНИЯХ MACOS: (Те же критические предупреждения, что и раньше, о произвольном выполнении скриптов и разрешениях автоматизации/доступности macOS).

Примеры:

• (Существующие примеры для inline/file path остаются актуальными)
• Использование скрипта базы знаний по идентификатору:
  { "toolName": "execute_script", "input": { "kb_script_id": "safari_get_active_tab_url", "timeout_seconds": 10 } }
• Использование скрипта базы знаний по идентификатору с input_data :
  { "toolName": "execute_script", "input": { "kb_script_id": "finder_create_folder_at_path", "input_data": { "folder_name": "New MCP Folder", "parent_path": "~/Desktop" } } }

Формат ответа:

Инструмент execute_script возвращает ответ в следующем формате:

• content : Массив текстовых элементов содержимого, содержащий вывод скрипта.
• isError : (boolean, необязательно) Устанавливается в true , если выполнение скрипта привело к ошибке. Этот флаг устанавливается, когда:
  • Вывод скрипта (stdout) начинается с «Error» (без учета регистра)
  • Это помогает клиентам легко определить, произошло ли сбой выполнения, без анализа выходного текста.

Пример ответа (успех):

Пример ответа (ошибка):

2. get_scripting_tips

Извлекает советы, примеры и подробности запускаемого скрипта AppleScript/JXA из базы знаний сервера. Полезно для обнаружения доступных скриптов, их функций и того, как их использовать с execute_script (особенно kb_script_id ).

Аргументы:

• list_categories (boolean, Optional, default: false): Если true, возвращает только список доступных категорий базы знаний и их описания. Переопределяет другие параметры.
• category (строка, необязательно): Фильтрует советы по определенному идентификатору категории (например, «finder», «safari»).
• search_term (строка, необязательно): Поиск ключевого слова в заголовках советов, описаниях, содержимом сценария, ключевых словах или идентификаторах.
• refresh_database (boolean, Optional, Default: false): Если true, принудительно перезагрузит всю базу знаний с диска перед обработкой запроса. Это полезно во время разработки, если вы активно изменяете файлы базы знаний и хотите убедиться, что используются последние версии без перезапуска сервера.
• limit (целое число, необязательное, по умолчанию: 10): максимальное количество возвращаемых результатов.

Выход:

• Возвращает строку в формате Markdown, содержащую запрошенные подсказки, включая их заголовок, описание, содержимое скрипта, язык, идентификатор запуска (если применимо), подсказки аргументов и примечания.

Пример использования:

• Список всех категорий: { "toolName": "get_scripting_tips", "input": { "list_categories": true } }
• Получить советы для категории "safari": { "toolName": "get_scripting_tips", "input": { "category": "safari" } }
• Поиск советов, связанных с "clipboard": { "toolName": "get_scripting_tips", "input": { "search_term": "clipboard" } }

Основные варианты использования и примеры

• Контроль приложений:
  • Получить текущий URL из Safari: { "input": { "script_content": "tell application \"Safari\" to get URL of front document" } }
  • Получить темы непрочитанных писем в Mail: { "input": { "script_content": "tell application \"Mail\" to get subject of messages of inbox whose read status is false" } }
• Операции файловой системы:
  • Список файлов на рабочем столе: { "input": { "script_content": "tell application \"Finder\" to get name of every item of desktop" } }
  • Создать новую папку: { "input": { "script_content": "tell application \"Finder\" to make new folder at desktop with properties {name:\"My New Folder\"}" } }
• Системные взаимодействия:
  • Отобразить системное уведомление: { "input": { "script_content": "display notification \"Important Update!\" with title \"System Alert\"" } }
  • Установить громкость системы: { "input": { "script_content": "set volume output volume 50" } } (0-100)
  • Получить текущее содержимое буфера обмена: { "input": { "script_content": "the clipboard" } }

Поиск неисправностей

• Ошибки разрешений: если скрипты не могут управлять приложениями или выполнять действия пользовательского интерфейса, дважды проверьте разрешения автоматизации и специальных возможностей в системных настройках для приложения, запускающего сервер MCP (например, терминал).
• Ошибки синтаксиса скрипта: ошибки osascript будут возвращены в stderr или сообщение об ошибке. Сначала тестируйте сложные скрипты локально с помощью редактора скриптов (для AppleScript) или JXA runner.
• Тайм-ауты: Если выполнение скрипта занимает больше времени, чем timeout_seconds (по умолчанию 60 с), он будет завершен. Увеличьте тайм-аут для долго выполняющихся скриптов.
• Файл не найден: убедитесь, что script_path — это абсолютный путь POSIX, доступный пользователю, запустившему сервер MCP.
• Неправильные проблемы с выводом/JXA: для скриптов JXA, особенно использующих мост Objective-C, убедитесь, что output_format_mode установлен на 'direct' или 'auto' (по умолчанию). Использование флагов форматирования, специфичных для AppleScript, таких как human_readable с JXA, может привести к ошибкам. Если вывод AppleScript не обрабатывается правильно, попробуйте structured_output_and_error или structured_error .

Конфигурация через переменные среды

• LOG_LEVEL : Установите уровень ведения журнала для сервера.
  • Значения: DEBUG , INFO , WARN , ERROR
  • Пример: LOG_LEVEL=DEBUG npx @steipete/macos-automator-mcp@latest
• KB_PARSING : управляет тем, когда анализируется база знаний (подсказки скрипта).
  • Ценности:
    • lazy (по умолчанию): База знаний анализируется при первом запросе к get_scripting_tips или при использовании kb_script_id в execute_script . Это позволяет ускорить запуск сервера.
    • eager : База знаний анализируется при запуске сервера. Это может немного увеличить время запуска, но гарантирует немедленную доступность KB и раннее обнаружение любых ошибок анализа.
  • Пример (при запуске через start.sh или аналогичный):
    KB_PARSING=eager ./start.sh
  • Пример (при настройке через MCP Runner, поддерживающий env , например mcp-agentify ):
    { "env": { "LOG_LEVEL": "INFO", "KB_PARSING": "eager" } }

Для разработчиков

Подробные инструкции по локальному развитию, структуре проекта (включая базу knowledge_base ) и правила внесения вкладов см. на сайте DEVELOPMENT.md .

Разработка

Подробную информацию о структуре проекта, его создании и тестировании см. на сайте DEVELOPMENT.md.

Местная база знаний

Вы можете дополнить встроенную базу знаний собственными локальными советами и общими обработчиками. Создайте структуру каталогов, идентичную knowledge_base в этом репозитории (или его подмножестве).

По умолчанию приложение будет искать эту локальную базу знаний в ~/.macos-automator/knowledge_base . Вы можете настроить этот путь, установив переменную среды LOCAL_KB_PATH .

Пример:

Предположим, у вас есть локальная база знаний в /Users/yourname/my-custom-kb . Установите переменную среды: export LOCAL_KB_PATH=/Users/yourname/my-custom-kb

Или, если вы запускаете скрипт валидатора, вы можете использовать аргумент --local-kb-path : npm run validate:kb -- --local-kb-path /Users/yourname/my-custom-kb

Структура и переопределения:

• Ваша локальная база знаний должна отражать структуру категорий основной knowledge_base (например, 01_applescript_core , 05_web_browsers/safari и т. д.).
• Вы можете добавить новые файлы советов .md или _shared_handlers (например, файлы .applescript или .js ).
• Если идентификатор подсказки (либо из id: либо сгенерированный из имени файла/пути) в вашей локальной базе знаний совпадает с идентификатором во встроенной базе знаний, ваша локальная версия перезапишет встроенную.
• Аналогично общие обработчики с тем же именем и языком (например, my_utility.applescript ) в локальном каталоге _shared_handlers переопределят любые встроенные обработчики с тем же именем и языком в той же категории (или глобально, если вы поместите их в корень локального каталога _shared_handlers базы знаний).
• Описания категорий из _category_info.md в вашей локальной базе знаний также могут переопределять описания из встроенной базы знаний для той же категории.

Это позволяет персонализировать и расширять доступные сценарии автоматизации и советы без изменения основных файлов приложения.

Внося вклад

Вклады приветствуются! Пожалуйста, отправляйте проблемы и запросы на извлечение в репозиторий GitHub .

Возможности автоматизации

Этот сервер предоставляет мощные возможности автоматизации macOS через AppleScript и JavaScript для автоматизации (JXA). Вот некоторые из наиболее полезных примеров:

Автоматизация терминала

• Запуск команд на новых вкладках терминала:
  { "input": { "kb_script_id": "terminal_app_run_command_new_tab", "input_data": { "command": "ls -la" } } }
• Выполняйте команды с помощью sudo и безопасно указывайте пароль
• Захват вывода команды для обработки

Управление браузером

• Автоматизация Chrome/Safari:
  { "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" } }
• Выполнить JavaScript в контексте браузера:
  { "input": { "kb_script_id": "chrome_execute_javascript", "input_data": { "javascript_code": "document.title" } } }
• Извлекайте содержимое страниц, манипулируйте формами и автоматизируйте рабочие процессы
• Делайте снимки экрана веб-страниц

Взаимодействие системы

• Переключение настроек системы (темный режим, громкость, сеть):
  { "input": { "kb_script_id": "systemsettings_toggle_dark_mode_ui" } }
• Получить/установить содержимое буфера обмена:
  { "input": { "kb_script_id": "system_clipboard_get_file_paths" } }
• Открытие/управление системными диалогами и оповещениями
• Создание и управление системными уведомлениями

Операции с файлами

• Создание, перемещение и управление файлами/папками:
  { "input": { "kb_script_id": "finder_create_new_folder_desktop", "input_data": { "folder_name": "My Project" } } }
• Чтение и запись текстовых файлов:
  { "input": { "kb_script_id": "fileops_read_text_file", "input_data": { "file_path": "~/Documents/notes.txt" } } }
• Список и фильтрация файлов в каталогах
• Получить метаданные и свойства файла

Интеграция приложений

• Управление календарем/напоминаниями:
  { "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" } } }
• Автоматизация электронной почты с помощью Mail.app:
  { "input": { "kb_script_id": "mail_send_email_direct", "input_data": { "recipient": "user@example.com", "subject": "Hello", "body_content": "Message content" } } }
• Управление воспроизведением музыки:
  { "input": { "kb_script_id": "music_playback_controls", "input_data": { "action": "play" } } }
• Работа с креативными приложениями (Keynote, Pages, Numbers)

Используйте инструмент get_scripting_tips , чтобы изучить все доступные возможности автоматизации, упорядоченные по категориям.

Лицензия

Этот проект лицензирован по лицензии MIT. Подробности см. в файле LICENSE .