macOS Automator MCP Server

Servidor MCP de macOS Automator

Descripción general

Este proyecto proporciona un servidor de Protocolo de Contexto de Modelo (MCP), macos_automator , que permite la ejecución de scripts de AppleScript y JavaScript para Automatización (JXA) en macOS. Incluye una base de conocimiento de scripts predefinidos accesibles por ID y admite scripts en línea, archivos de script y paso de argumentos. La base de conocimiento se carga de forma diferida al primer uso para un inicio rápido del servidor.

Beneficios

• Ejecute scripts AppleScript/JXA de forma remota a través de MCP.
• Utilice una base de conocimiento rica y extensible de tareas comunes de automatización de macOS.
• Controle las aplicaciones macOS y las funciones del sistema mediante programación.
• Integre la automatización de macOS en flujos de trabajo más amplios impulsados por IA.

Prerrequisitos

• Node.js (versión >=18.0.0 recomendada, ver motores package.json ).
• macOS.
• CONFIGURACIÓN DE PERMISOS CRÍTICOS:
  • La aplicación que ejecuta ESTE servidor MCP (por ejemplo, Terminal, su aplicación Node.js) requiere permisos de usuario explícitos en la máquina macOS donde se ejecuta el servidor.
  • Permisos de automatización: Para controlar otras aplicaciones (Finder, Safari, Mail, etc.).
    • Vaya a: Configuración del sistema > Privacidad y seguridad > Automatización.
    • Busque la aplicación que ejecuta el servidor (por ejemplo, Terminal) en la lista.
    • Asegúrese de que tenga casillas de verificación marcadas para todas las aplicaciones que necesita controlar.
    • Ver ejemplo: docs/automation-permissions-example.png (imagen de marcador de posición).
  • Permisos de accesibilidad: para scripts de UI a través de "Eventos del sistema" (por ejemplo, simulación de clics, pulsaciones de teclas).
    • Vaya a: Configuración del sistema > Privacidad y seguridad > Accesibilidad.
    • Agregue la aplicación que ejecuta el servidor (por ejemplo, Terminal) a la lista y asegúrese de que su casilla de verificación esté marcada.
  • Los primeros intentos de controlar una nueva aplicación o usar funciones de accesibilidad podrían generar un mensaje de confirmación de macOS, incluso con autorización previa. El servidor no puede otorgar estos permisos.

Instalación y uso

La forma principal de ejecutar este servidor es mediante npx . Esto garantiza que se use la última versión sin necesidad de una instalación global.

Agregue la siguiente configuración al mcp.json de su cliente MCP (o configuración equivalente):

Ejecución local (para desarrollo o uso directo)

Como alternativa, para desarrollo o si prefiere ejecutar el servidor directamente desde un repositorio clonado, puede usar el script start.sh proporcionado. Esto resulta útil si desea realizar modificaciones locales o ejecutar una versión específica.

1. Clonar el repositorio:
   git clone https://github.com/steipete/macos-automator-mcp.git cd macos-automator-mcp npm install # Ensure dependencies are installed
2. Configure su cliente MCP: actualice la configuración de su cliente MCP para que apunte a la ruta absoluta del script start.sh dentro de su repositorio clonado.Ejemplo de fragmento de configuración mcp.json :
   { "mcpServers": { "macos_automator_local": { "command": "/absolute/path/to/your/cloned/macos-automator-mcp/start.sh", "env": { "LOG_LEVEL": "DEBUG" } } } }
   Importante: reemplace /absolute/path/to/your/cloned/macos-automator-mcp/start.sh con la ruta absoluta correcta en su sistema.El script start.sh usará automáticamente tsx para ejecutar el código fuente de TypeScript directamente si no se encuentra una versión compilada, o bien, ejecutará la versión compilada desde dist/ si está disponible. Respeta la variable de entorno LOG_LEVEL .Nota para desarrolladores: El script start.sh , especialmente si se modifica para eliminar cualquier dist/server.js compilado previamente antes de la ejecución (p. ej., añadiendo rm -f dist/server.js ), está diseñado para garantizar que siempre se ejecute el código TypeScript más reciente desde el directorio src/ mediante tsx . Esto es ideal para el desarrollo, ya que evita problemas con compilaciones obsoletas. Para la implementación en producción (p. ej., al publicar en npm), un proceso de compilación normalmente crearía un dist/server.js definitivo, que sería el punto de entrada para el paquete publicado.

Herramientas proporcionadas

1. execute_script

Ejecuta un script de AppleScript o JavaScript para Automatización (JXA) en macOS. Los scripts pueden proporcionarse como contenido en línea ( script_content ), una ruta de archivo absoluta ( script_path ) o haciendo referencia a un script de la base de conocimiento integrada mediante su kb_script_id único.

Fuentes de script (mutuamente excluyentes):

• script_content (cadena): código de script sin procesar.
• script_path (cadena): ruta POSIX absoluta a un archivo de script (por ejemplo, .applescript , .scpt , .js ).
• kb_script_id (cadena): El ID de un script predefinido de la base de conocimientos del servidor. Utilice la herramienta get_scripting_tips para descubrir los ID de script disponibles y sus funcionalidades.

Especificación del idioma:

• language (enum: 'applescript' | 'javascript', opcional): especifica el idioma.
  • Si se utiliza kb_script_id , el idioma se infiere del script de la base de conocimiento.
  • Si se utiliza script_content o script_path y se omite language , el valor predeterminado es 'applescript'.

Pasando entradas a scripts:

• arguments (matriz de cadenas, opcional):
  • Para script_path : se pasan como argumentos estándar al controlador on run argv (AppleScript) o run(argv) (JXA) del script durante su ejecución.
  • Para kb_script_id : Se usa si el script predefinido está diseñado para aceptar argumentos de cadena posicionales (p. ej., reemplaza marcadores de posición como --MCP_ARG_1 o --MCP_ARG_2 ). Consulte el argumentsPrompt del script en get_scripting_tips .
• input_data (objeto JSON, opcional):
  • Principalmente para scripts kb_script_id diseñados para aceptar entradas estructuradas y con nombre.
  • Los valores de este objeto reemplazan los marcadores de posición en el script (p. ej., --MCP_INPUT:yourKeyName ). Consulte argumentsPrompt de get_scripting_tips .
  • Los valores (cadenas, números, valores booleanos, matrices/objetos simples) se convierten en sus equivalentes literales de AppleScript.

Otras opciones:

• timeout_seconds (entero, opcional, predeterminado: 60): tiempo máximo de ejecución.
• output_format_mode (enum, opcional, predeterminado: 'auto'): controla los indicadores de formato de salida osascript .
  • 'auto' : (predeterminado) utiliza código legible para AppleScript ( -sh ) y salida directa (sin indicadores -s ) para JXA.
  • 'human_readable' : Fuerza -sh (salida legible por humanos, principalmente para AppleScript).
  • 'structured_error' : Fuerza -ss (informe de error estructurado, principalmente para AppleScript).
  • 'structured_output_and_error' : Fuerza -s ss (salida estructurada para el resultado principal y los errores, principalmente para AppleScript).
  • 'direct' : no se utilizan indicadores -s (recomendado para JXA, también el comportamiento para JXA en modo auto ).
• include_executed_script_in_output (booleano, opcional, valor predeterminado: false): Si es true, la salida incluirá el contenido completo del script (después de cualquier sustitución de marcadores de posición para scripts de la base de conocimiento) o la ruta del script ejecutado. Esto se añade como texto adicional en la matriz de contenido de salida.
• include_substitution_logs (booleano, opcional, valor predeterminado: false): Si es true, se incluyen en la salida registros detallados de las sustituciones de marcadores de posición realizadas en scripts de la base de conocimiento. Esto resulta útil para depurar el procesamiento e inserción de input_data y arguments en el script. Los registros se añaden al inicio de la salida del script en caso de éxito o al mensaje de error en caso de error.
• report_execution_time (booleano, opcional, predeterminado: falso): si es true , se incluirá un mensaje adicional con el tiempo de ejecución del script formateado en la matriz de contenido de respuesta.

ADVERTENCIA DE SEGURIDAD Y PERMISOS DE MACOS: (Las mismas advertencias críticas que antes sobre la ejecución de scripts arbitrarios y los permisos de Automatización/Accesibilidad de macOS).

Ejemplos:

• (Los ejemplos existentes de rutas en línea/archivo siguen siendo relevantes)
• Uso del script de base de conocimientos por ID:
  { "toolName": "execute_script", "input": { "kb_script_id": "safari_get_active_tab_url", "timeout_seconds": 10 } }
• Uso del script de base de conocimientos por ID con input_data :
  { "toolName": "execute_script", "input": { "kb_script_id": "finder_create_folder_at_path", "input_data": { "folder_name": "New MCP Folder", "parent_path": "~/Desktop" } } }

Formato de respuesta:

La herramienta execute_script devuelve una respuesta en el siguiente formato:

• content : una matriz de elementos de contenido de texto que contienen la salida del script
• isError : (booleano, opcional) Se establece como true cuando la ejecución del script produjo un error. Este indicador se establece cuando:
  • La salida del script (stdout) comienza con "Error" (sin distinguir entre mayúsculas y minúsculas)
  • Esto ayuda a los clientes a determinar fácilmente si la ejecución falló sin analizar el texto de salida.

Ejemplo de respuesta (éxito):

Ejemplo de respuesta (error):

2. get_scripting_tips

Recupera consejos, ejemplos y detalles de scripts ejecutables de AppleScript/JXA de la base de conocimientos del servidor. Resulta útil para descubrir los scripts disponibles, sus funcionalidades y cómo usarlos con execute_script (especialmente kb_script_id ).

Argumentos:

• list_categories (booleano, opcional, valor predeterminado: false): Si es true, devuelve solo la lista de categorías disponibles de la base de conocimiento y sus descripciones. Anula otros parámetros.
• category (cadena, opcional): filtra las sugerencias por un ID de categoría específico (por ejemplo, "buscador", "safari").
• search_term (cadena, opcional): busca una palabra clave dentro de títulos de sugerencias, descripciones, contenido de scripts, palabras clave o ID.
• refresh_database (booleano, opcional, valor predeterminado: false): Si es true, fuerza la recarga de toda la base de conocimiento desde el disco antes de procesar la solicitud. Esto es útil durante el desarrollo si se modifican activamente los archivos de la base de conocimiento y se desea garantizar que se utilicen las versiones más recientes sin reiniciar el servidor.
• limit (entero, opcional, predeterminado: 10): número máximo de resultados a devolver.

Producción:

• Devuelve una cadena con formato Markdown que contiene los consejos solicitados, incluido su título, descripción, contenido del script, idioma, ID ejecutable (si corresponde), indicaciones de argumentos y notas.

Ejemplo de uso:

• Listar todas las categorías: { "toolName": "get_scripting_tips", "input": { "list_categories": true } }
• Obtén consejos para la categoría "safari": { "toolName": "get_scripting_tips", "input": { "category": "safari" } }
• Buscar consejos relacionados con "clipboard": { "toolName": "get_scripting_tips", "input": { "search_term": "clipboard" } }

Casos de uso y ejemplos clave

• Control de aplicaciones:
  • Obtener la URL actual de Safari: { "input": { "script_content": "tell application \"Safari\" to get URL of front document" } }
  • Obtener los asuntos de los correos electrónicos no leídos en Mail: { "input": { "script_content": "tell application \"Mail\" to get subject of messages of inbox whose read status is false" } }
• Operaciones del sistema de archivos:
  • Lista de archivos en el escritorio: { "input": { "script_content": "tell application \"Finder\" to get name of every item of desktop" } }
  • Crear nueva carpeta: { "input": { "script_content": "tell application \"Finder\" to make new folder at desktop with properties {name:\"My New Folder\"}" } }
• Interacciones del sistema:
  • Mostrar una notificación del sistema: { "input": { "script_content": "display notification \"Important Update!\" with title \"System Alert\"" } }
  • Establecer el volumen del sistema: { "input": { "script_content": "set volume output volume 50" } } (0-100)
  • Obtener el contenido actual del portapapeles: { "input": { "script_content": "the clipboard" } }

Solución de problemas

• Errores de permisos: si los scripts no pueden controlar las aplicaciones o realizar acciones de la interfaz de usuario, verifique nuevamente los permisos de Automatización y Accesibilidad en la Configuración del sistema para la aplicación que ejecuta el servidor MCP (por ejemplo, Terminal).
• Errores de sintaxis de script: Los errores osascript se devolverán en el stderr o en un mensaje de error. Pruebe primero los scripts complejos localmente con el Editor de Scripts (para AppleScript) o un ejecutor JXA.
• Tiempos de espera: Si un script tarda más de timeout_seconds (predeterminado: 60 s), se finalizará. Aumente el tiempo de espera para scripts de larga duración.
• Archivo no encontrado: asegúrese de que script_path sea una ruta POSIX absoluta accesible para el usuario que ejecuta el servidor MCP.
• Problemas de salida incorrecta/JXA: Para scripts JXA, especialmente aquellos que usan puentes Objective-C, asegúrese de que output_format_mode esté configurado en 'direct' o 'auto' (predeterminado). El uso de indicadores de formato específicos de AppleScript, como human_readable , con JXA puede causar errores. Si la salida de AppleScript no se analiza correctamente, pruebe con structured_output_and_error o structured_error .

Configuración mediante variables de entorno

• LOG_LEVEL : establece el nivel de registro para el servidor.
  • Valores: DEBUG , INFO , WARN , ERROR
  • Ejemplo: LOG_LEVEL=DEBUG npx @steipete/macos-automator-mcp@latest
• KB_PARSING : controla cuándo se analiza la base de conocimientos (sugerencias de script).
  • Valores:
    • lazy (predeterminado): La base de conocimientos se analiza en la primera solicitud a get_scripting_tips o cuando se utiliza un kb_script_id en execute_script . Esto permite un inicio más rápido del servidor.
    • eager : La base de conocimientos se analiza al iniciar el servidor. Esto puede aumentar ligeramente el tiempo de inicio, pero garantiza que la base de conocimientos esté disponible de inmediato y que cualquier error de análisis se detecte a tiempo.
  • Ejemplo (cuando se ejecuta a través de start.sh o similar):
    KB_PARSING=eager ./start.sh
  • Ejemplo (al configurar a través de un ejecutor MCP que admite env , como mcp-agentify ):
    { "env": { "LOG_LEVEL": "INFO", "KB_PARSING": "eager" } }

Para desarrolladores

Para obtener instrucciones detalladas sobre el desarrollo local, la estructura del proyecto (incluida la knowledge_base ) y las pautas de contribución, consulte DEVELOPMENT.md .

Desarrollo

Consulte DEVELOPMENT.md para obtener detalles sobre la estructura, la construcción y las pruebas del proyecto.

Base de conocimientos locales

Puedes complementar la base de conocimientos integrada con tus propias sugerencias locales y controladores compartidos. Crea una estructura de directorios idéntica a la de knowledge_base en este repositorio (o un subconjunto de ella).

De forma predeterminada, la aplicación buscará esta base de conocimiento local en ~/.macos-automator/knowledge_base . Puede personalizar esta ruta configurando la variable de entorno LOCAL_KB_PATH .

Ejemplo:

Supongamos que tiene una base de conocimiento local en /Users/yourname/my-custom-kb . Establezca la variable de entorno: export LOCAL_KB_PATH=/Users/yourname/my-custom-kb

O bien, si está ejecutando el script de validación, puede usar el argumento --local-kb-path : npm run validate:kb -- --local-kb-path /Users/yourname/my-custom-kb

Estructura y anulaciones:

• Su base de conocimiento local debe reflejar la estructura de categorías de la knowledge_base principal (por ejemplo, 01_applescript_core , 05_web_browsers/safari , etc.).
• Puede agregar nuevos archivos de sugerencias .md o _shared_handlers (por ejemplo, archivos .applescript o .js ).
• Si un ID de sugerencia (ya sea del id: de frontmatter o generado a partir de nombre de archivo/ruta) en su base de conocimiento local coincide con un ID en la base de conocimiento incorporada, su versión local anulará la incorporada.
• De manera similar, los controladores compartidos con el mismo nombre e idioma (por ejemplo, my_utility.applescript ) en su directorio local _shared_handlers anularán cualquier controlador integrado con el mismo nombre e idioma dentro de la misma categoría (o globalmente si los coloca en la raíz de _shared_handlers de su base de conocimientos local).
• Las descripciones de categorías de _category_info.md en su base de conocimientos local también pueden anular aquellas de la base de conocimientos incorporada para la misma categoría.

Esto permite la personalización y ampliación de los scripts de automatización y sugerencias disponibles sin modificar los archivos principales de la aplicación.

Contribuyendo

¡Agradecemos sus contribuciones! Envíen sus problemas y solicitudes de incorporación de cambios al repositorio de GitHub .

Capacidades de automatización

Este servidor ofrece potentes funciones de automatización de macOS mediante AppleScript y JavaScript para Automatización (JXA). Estos son algunos de los ejemplos más útiles:

Automatización de terminales

• Ejecutar comandos en nuevas pestañas de Terminal:
  { "input": { "kb_script_id": "terminal_app_run_command_new_tab", "input_data": { "command": "ls -la" } } }
• Ejecute comandos con sudo y proporcione la contraseña de forma segura
• Capturar la salida del comando para su procesamiento

Control del navegador

• Automatización de 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" } }
• Ejecutar JavaScript en el contexto del navegador:
  { "input": { "kb_script_id": "chrome_execute_javascript", "input_data": { "javascript_code": "document.title" } } }
• Extraer contenido de páginas, manipular formularios y automatizar flujos de trabajo
• Tomar capturas de pantalla de páginas web

Interacción del sistema

• Alternar la configuración del sistema (modo oscuro, volumen, red):
  { "input": { "kb_script_id": "systemsettings_toggle_dark_mode_ui" } }
• Obtener/establecer el contenido del portapapeles:
  { "input": { "kb_script_id": "system_clipboard_get_file_paths" } }
• Abrir/controlar diálogos y alertas del sistema
• Crear y administrar notificaciones del sistema

Operaciones con archivos

• Crear, mover y manipular archivos/carpetas:
  { "input": { "kb_script_id": "finder_create_new_folder_desktop", "input_data": { "folder_name": "My Project" } } }
• Leer y escribir archivos de texto:
  { "input": { "kb_script_id": "fileops_read_text_file", "input_data": { "file_path": "~/Documents/notes.txt" } } }
• Listar y filtrar archivos en directorios
• Obtener metadatos y propiedades del archivo

Integración de aplicaciones

• Gestión de calendario/recordatorios:
  { "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" } } }
• Automatización del correo electrónico con Mail.app:
  { "input": { "kb_script_id": "mail_send_email_direct", "input_data": { "recipient": "user@example.com", "subject": "Hello", "body_content": "Message content" } } }
• Controlar la reproducción de música:
  { "input": { "kb_script_id": "music_playback_controls", "input_data": { "action": "play" } } }
• Trabajar con aplicaciones creativas (Keynote, Pages, Numbers)

Utilice la herramienta get_scripting_tips para explorar todas las capacidades de automatización disponibles organizadas por categoría.

Licencia

Este proyecto está licenciado bajo la Licencia MIT. Consulte el archivo de LICENCIA para más detalles.