macOS Automator MCP Server

macOS Automator MCP 서버

개요

이 프로젝트는 macOS에서 AppleScript 및 JavaScript for Automation(JXA) 스크립트를 실행할 수 있는 MCP(Model Context Protocol) 서버인 macos_automator 제공합니다. ID로 접근 가능한 미리 정의된 스크립트의 지식 기반을 제공하며, 인라인 스크립트, 스크립트 파일 및 인수 전달을 지원합니다. 지식 기반은 빠른 서버 시작을 위해 처음 사용 시 지연 로드됩니다.

이익

• MCP를 통해 원격으로 AppleScript/JXA 스크립트를 실행합니다.
• 일반적인 macOS 자동화 작업에 대한 풍부하고 확장 가능한 지식 기반을 활용하세요.
• macOS 애플리케이션과 시스템 기능을 프로그래밍 방식으로 제어합니다.
• macOS 자동화를 대규모 AI 기반 워크플로에 통합합니다.

필수 조건

• Node.js(버전 >=18.0.0 권장, package.json 엔진 참조).
• 맥OS.
• 중요 권한 설정:
  • 이 MCP 서버를 실행하는 애플리케이션(예: 터미널, Node.js 애플리케이션)에는 서버가 실행되는 macOS 컴퓨터에서 명시적인 사용자 권한이 필요합니다.
  • 자동화 권한: 다른 애플리케이션(Finder, Safari, 메일 등)을 제어합니다.
    • 시스템 설정 > 개인정보 보호 및 보안 > 자동화로 이동합니다.
    • 목록에서 서버를 실행하는 애플리케이션(예: 터미널)을 찾습니다.
    • 제어해야 하는 모든 애플리케이션에 대해 확인란이 선택되어 있는지 확인하세요.
    • 예를 들어 docs/automation-permissions-example.png (플레이스홀더 이미지)를 참조하세요.
  • 접근성 권한: "시스템 이벤트"를 통한 UI 스크립팅(예: 클릭, 키 입력 시뮬레이션)
    • 시스템 설정 > 개인정보 보호 및 보안 > 접근성으로 이동하세요.
    • 서버를 실행하는 애플리케이션(예: 터미널)을 목록에 추가하고 해당 확인란이 선택되어 있는지 확인하세요.
  • 새 애플리케이션을 제어하거나 접근성 기능을 처음 사용하려고 하면 사전 승인이 필요하더라도 macOS 확인 메시지가 표시될 수 있습니다. 서버 자체는 이러한 권한을 부여할 수 없습니다.

설치 및 사용

이 서버를 실행하는 기본 방법은 npx 사용하는 것입니다. 이렇게 하면 글로벌 설치 없이도 최신 버전을 사용할 수 있습니다.

MCP 클라이언트의 mcp.json (또는 동등한 구성)에 다음 구성을 추가합니다.

지엑스피1

로컬에서 실행(개발 또는 직접 사용)

개발 목적이거나 복제된 저장소에서 서버를 직접 실행하고 싶다면 제공된 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 클라이언트 구성: 복제된 저장소 내의 start.sh 스크립트의 절대 경로를 가리키도록 MCP 클라이언트 구성을 업데이트합니다.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 추가), tsx 를 통해 src/ 디렉터리의 최신 TypeScript 코드를 항상 실행하도록 설계되었습니다. 이는 오래된 빌드 문제를 방지하여 개발 환경에 이상적입니다. 프로덕션 배포(예: npm에 게시)의 경우, 빌드 프로세스는 일반적으로 최종 dist/server.js 파일을 생성하며, 이는 게시된 패키지의 진입점이 됩니다.

제공된 도구

1. execute_script

macOS에서 AppleScript 또는 JavaScript for Automation(JXA) 스크립트를 실행합니다. 스크립트는 인라인 콘텐츠( script_content ), 절대 파일 경로( script_path )로 제공되거나, 고유 kb_script_id 사용하여 내장된 지식 베이스의 스크립트를 참조하여 제공될 수 있습니다.

스크립트 소스(상호 배타적):

• script_content (문자열): 원시 스크립트 코드.
• script_path (문자열): 스크립트 파일에 대한 절대 POSIX 경로(예: .applescript , .scpt , .js ).
• kb_script_id (문자열): 서버 지식 베이스에서 미리 정의된 스크립트의 ID입니다. get_scripting_tips 도구를 사용하여 사용 가능한 스크립트 ID와 기능을 확인하세요.

언어 사양:

• 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 와 같은 플레이스홀더를 대체하는 경우) 사용됩니다. get_scripting_tips 에서 스크립트의 argumentsPrompt 확인하세요.
• input_data (JSON 객체, 선택 사항):
  • 주로 이름이 지정되고 구조화된 입력을 허용하도록 설계된 kb_script_id 스크립트용입니다.
  • 이 객체의 값은 스크립트의 플레이스홀더를 대체합니다(예: --MCP_INPUT:yourKeyName ). get_scripting_tips 의 argumentsPrompt 참조하세요.
  • 값(문자열, 숫자, 부울, 단순 배열/객체)은 AppleScript 리터럴 대응 값으로 변환됩니다.

기타 옵션:

• timeout_seconds (정수, 선택 사항, 기본값: 60): 최대 실행 시간.
• output_format_mode (enum, 선택 사항, 기본값: 'auto'): osascript 출력 형식 플래그를 제어합니다.
  • 'auto' : (기본값) AppleScript의 경우 사람이 읽을 수 있는 형식( -sh )을 사용하고 JXA의 경우 직접 출력( -s 플래그 없음)을 사용합니다.
  • 'human_readable' : -sh 강제로 실행합니다(주로 AppleScript의 경우 사람이 읽을 수 있는 출력).
  • 'structured_error' : -ss (구조적 오류 보고, 주로 AppleScript용)를 강제로 적용합니다.
  • 'structured_output_and_error' : -s ss (주로 AppleScript에 대한 주요 결과 및 오류에 대한 구조화된 출력)를 강제로 실행합니다.
  • 'direct' : -s 플래그를 사용하지 않습니다(JXA에 권장되며, auto 모드에서도 JXA의 동작입니다).
• include_executed_script_in_output (부울, 선택 사항, 기본값: false): true인 경우, 출력에 전체 스크립트 내용(지식 기반 스크립트에 대한 모든 대체 항목 이후) 또는 실행된 스크립트 경로가 포함됩니다. 이는 출력 내용 배열에 추가 텍스트 부분으로 추가됩니다.
• include_substitution_logs (부울, 선택 사항, 기본값: false): true인 경우, 지식 기반 스크립트에서 수행된 플레이스홀더 대체에 대한 자세한 로그가 출력에 포함됩니다. 이 설정은 input_data 와 arguments 처리되어 스크립트에 삽입되는 방식을 디버깅하는 데 유용합니다. 로그는 스크립트 출력이 성공하면 스크립트 출력 앞에 추가되고, 실패하면 오류 메시지 뒤에 추가됩니다.
• report_execution_time (부울, 선택 사항, 기본값: false): true 인 경우, 형식화된 스크립트 실행 시간이 포함된 추가 메시지가 응답 콘텐츠 배열에 포함됩니다.

보안 경고 및 macOS 권한: (임의 스크립트 실행 및 macOS 자동화/접근성 권한에 대한 이전과 동일한 중요 경고).

예:

• (인라인/파일 경로에 대한 기존 예는 여전히 관련성이 있음)
• ID로 지식 기반 스크립트 사용:
  { "toolName": "execute_script", "input": { "kb_script_id": "safari_get_active_tab_url", "timeout_seconds": 10 } }
• input_data 사용하여 ID로 지식 기반 스크립트 사용:
  { "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 : (부울, 선택 사항) 스크립트 실행 시 오류가 발생하면 true 로 설정됩니다. 이 플래그는 다음과 같은 경우에 설정됩니다.
  • 스크립트 출력(stdout)은 "Error"(대소문자 구분 없음)로 시작합니다.
  • 이를 통해 클라이언트는 출력 텍스트를 구문 분석하지 않고도 실행이 실패했는지 쉽게 확인할 수 있습니다.

응답 예시(성공):

응답 예시(오류):

2. get_scripting_tips

서버의 지식 기반에서 AppleScript/JXA 팁, 예제 및 실행 가능한 스크립트 세부 정보를 가져옵니다. 사용 가능한 스크립트, 해당 기능, 그리고 execute_script (특히 kb_script_id )를 사용하여 스크립트 사용 방법을 찾는 데 유용합니다.

인수:

• list_categories (부울, 선택 사항, 기본값: false): true인 경우, 사용 가능한 지식 기반 카테고리 목록과 해당 설명만 반환합니다. 다른 매개변수는 무시됩니다.
• category (문자열, 선택 사항): 특정 카테고리 ID(예: "finder", "safari")로 팁을 필터링합니다.
• search_term (문자열, 선택 사항): 팁 제목, 설명, 스크립트 내용, 키워드 또는 ID 내에서 키워드를 검색합니다.
• refresh_database (부울, 선택 사항, 기본값: false): true인 경우, 요청을 처리하기 전에 디스크에서 전체 지식 베이스를 강제로 다시 로드합니다. 개발 과정에서 지식 베이스 파일을 자주 수정하고 서버를 재시작하지 않고도 최신 버전을 사용하려는 경우 유용합니다.
• limit (정수, 선택 사항, 기본값: 10): 반환할 결과의 최대 개수.

산출:

• 요청된 팁, 즉 제목, 설명, 스크립트 내용, 언어, 실행 가능 ID(해당되는 경우), 인수 프롬프트 및 메모를 포함하는 마크다운 형식의 문자열을 반환합니다.

사용 예:

• 모든 카테고리 나열: { "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" } }

주요 사용 사례 및 예시

• 애플리케이션 제어:
  • Safari에서 현재 URL을 가져옵니다. { "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" } }

문제 해결

• 권한 오류: 스크립트가 앱을 제어하거나 UI 작업을 수행하지 못하는 경우, MCP 서버를 실행하는 애플리케이션(예: 터미널)의 시스템 설정에서 자동화 및 접근성 권한을 다시 한 번 확인하세요.
• 스크립트 구문 오류: osascript 오류는 stderr 또는 오류 메시지로 반환됩니다. 복잡한 스크립트는 먼저 스크립트 편집기(AppleScript용) 또는 JXA 실행기를 사용하여 로컬에서 테스트하세요.
• 시간 초과: 스크립트 실행 시간이 timeout_seconds (기본값 60초)보다 길어지면 스크립트가 종료됩니다. 장시간 실행되는 스크립트의 경우 시간 초과를 늘리세요.
• 파일을 찾을 수 없습니다. script_path MCP 서버를 실행하는 사용자가 액세스할 수 있는 절대 POSIX 경로인지 확인하세요.
• 잘못된 출력/JXA 문제: JXA 스크립트, 특히 Objective-C 브리징을 사용하는 스크립트의 경우, output_format_mode 가 'direct' 또는 'auto' (기본값)로 설정되어 있는지 확인하세요. JXA에서 human_readable 과 같은 AppleScript 전용 포맷팅 플래그를 사용하면 오류가 발생할 수 있습니다. 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 에 대한 첫 번째 요청 또는 execute_script 에 kb_script_id 사용될 때 지식 기반이 파싱됩니다. 이를 통해 서버 시작 속도가 향상됩니다.
    • eager : 지식 기반은 서버 시작 시 파싱됩니다. 이렇게 하면 시작 시간이 약간 길어질 수 있지만, 지식 기반을 즉시 사용할 수 있고 파싱 오류를 조기에 발견할 수 있습니다.
  • 예( start.sh 또는 유사한 명령어를 통해 실행할 경우):
    KB_PARSING=eager ./start.sh
  • 예( mcp-agentify 와 같이 env 지원하는 MCP 러너를 통해 구성하는 경우):
    { "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(프론트매터 id: 또는 파일 이름/경로에서 생성됨)가 내장된 지식 기반의 ID와 일치하는 경우, 로컬 버전이 내장된 버전을 재정의합니다 .
• 마찬가지로, 로컬 _shared_handlers 디렉토리에 있는 동일한 이름과 언어를 사용하는 공유 핸들러(예: my_utility.applescript )는 동일한 카테고리(또는 로컬 KB의 _shared_handlers 루트에 배치한 경우 전역적으로) 내에 있는 동일한 이름과 언어를 사용하는 모든 내장 핸들러를 재정의합니다.
• 로컬 KB의 _category_info.md 에 있는 카테고리 설명은 동일한 카테고리에 대한 내장 KB의 카테고리 설명을 재정의할 수도 있습니다.

이를 통해 핵심 애플리케이션 파일을 수정하지 않고도 사용 가능한 자동화 스크립트와 팁을 개인화하고 확장할 수 있습니다.

기여하다

기여를 환영합니다! 이슈와 풀 리퀘스트는 GitHub 저장소 에 제출해 주세요.

자동화 기능

이 서버는 AppleScript와 JavaScript for Automation(JXA)을 통해 강력한 macOS 자동화 기능을 제공합니다. 가장 유용한 몇 가지 예시는 다음과 같습니다.

터미널 자동화

• 새 터미널 탭에서 명령을 실행합니다.
  { "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 라이선스에 따라 라이선스가 부여됩니다. 자세한 내용은 라이선스 파일을 참조하세요.