AppleScript MCP

Ejecuta AppleScript en macOS

Documentación

Servidor MCP applescript-mcp

Un servidor de Protocolo de Model Context que permite a aplicaciones de LLM interactuar con macOS a través de AppleScript. Este servidor proporciona una interfaz estandarizada para que aplicaciones de IA controlen funciones del sistema, gestionen archivos, manejen notificaciones y más.

Características

🗓️ Gestión de calendario (eventos, recordatorios)
📋 Operaciones de portapapeles
🔍 Integración con Finder
🔔 Notificaciones del sistema
⚙️ Controles del sistema (volumen, modo oscuro, aplicaciones)
📟 Integración con terminal iTerm
📬 Correo (crear nuevo correo, listar correos, obtener correo)
🔄 Automatización de accesos directos
💬 Mensajes (listar chats, obtener mensajes, buscar mensajes, enviar un mensaje)
🗒️ Notas (crear notas con formato, listar notas, buscar notas)
📄 Pages (crear documentos)

Características Planificadas

🧭 Safari (abrir en Safari, guardar contenido de página, obtener página/pestaña seleccionada)
✅ Recordatorios (crear, obtener)

Requisitos Previos

macOS 10.15 o posterior
Node.js 18 o posterior

Categorías Disponibles

Calendario

Comando	Descripción	Parámetros
`add`	Crear evento de calendario	`title`, `startDate`, `endDate`, `calendar` (opcional)
`list`	Listar eventos de hoy	Ninguno

Ejemplos

// Create a new calendar event
Create a calendar event titled "Team Meeting" starting tomorrow at 2pm for 1 hour

// List today's events
What events do I have scheduled for today?

Portapapeles

Comando	Descripción	Parámetros
`set_clipboard`	Copiar al portapapeles	`content`
`get_clipboard`	Obtener contenido del portapapeles	Ninguno
`clear_clipboard`	Limpiar portapapeles	Ninguno

Ejemplos

// Copy text to clipboard
Copy "Remember to buy groceries" to my clipboard

// Get clipboard contents
What's currently in my clipboard?

// Clear clipboard
Clear my clipboard

Finder

Comando	Descripción	Parámetros
`get_selected_files`	Obtener archivos seleccionados	Ninguno
`search_files`	Buscar archivos	`query`, `location` (opcional)
`quick_look`	Vista previa de archivo	`path`

Ejemplos

// Get selected files in Finder
What files do I currently have selected in Finder?

// Search for files
Find all PDF files in my Documents folder

// Preview a file
Show me a preview of ~/Documents/report.pdf

Notificaciones

Nota: Enviar notificaciones requiere que habilites las notificaciones en Configuración del Sistema > Notificaciones > Editor de Scripts.

Comando	Descripción	Parámetros
`send_notification`	Mostrar notificación	`title`, `message`, `sound` (opcional)
`toggle_do_not_disturb`	Alternar modo No Molestar	Ninguno

Ejemplos

// Send a notification
Send me a notification with the title "Reminder" and message "Time to take a break"

// Toggle Do Not Disturb
Turn on Do Not Disturb mode

Sistema

Comando	Descripción	Parámetros
`volume`	Establecer volumen del sistema	`level` (0-100)
`get_frontmost_app`	Obtener aplicación activa	Ninguno
`launch_app`	Abrir aplicación	`name`
`quit_app`	Cerrar aplicación	`name`, `force` (opcional)
`toggle_dark_mode`	Alternar modo oscuro	Ninguno

Ejemplos

// Set system volume
Set my Mac's volume to 50%

// Get active application
What app am I currently using?

// Launch an application
Open Safari

// Quit an application
Close Spotify

// Toggle dark mode
Switch to dark mode

iTerm

Comando	Descripción	Parámetros
`paste_clipboard`	Pegar en iTerm	Ninguno
`run`	Ejecutar comando	`command`, `newWindow` (opcional)

Ejemplos

// Paste clipboard to iTerm
Paste my clipboard contents into iTerm

// Run a command in iTerm
Run "ls -la" in iTerm

// Run a command in a new iTerm window
Run "top" in a new iTerm window

Accesos Directos

Comando	Descripción	Parámetros
`run_shortcut`	Ejecutar un acceso directo	`name`, `input` (opcional)
`list_shortcuts`	Listar todos los accesos directos disponibles	`limit` (opcional)

Ejemplos

// List available shortcuts
List all my available shortcuts

// List with limit
Show me my top 5 shortcuts

// Run a shortcut
Run my "Daily Note in Bear" shortcut

// Run a shortcut with input
Run my "Add to-do" shortcut with input "Buy groceries"

Correo

Comando	Descripción	Parámetros
`create_email`	Crear un nuevo correo en Mail.app	`recipient`, `subject`, `body`
`list_emails`	Listar correos de un buzón	`mailbox` (opcional), `count` (opcional), `unreadOnly` (opcional)
`get_email`	Obtener un correo específico por búsqueda	`subject` (opcional), `sender` (opcional), `dateReceived` (opcional), `mailbox` (opcional), `account` (opcional), `unreadOnly` (opcional), `includeBody` (opcional)

Ejemplos

// Create a new email
Compose an email to john@example.com with subject "Meeting Tomorrow" and body "Hi John, Can we meet tomorrow at 2pm?"

// List emails
Show me my 10 most recent unread emails

// Get a specific email
Find the email from sarah@example.com about "Project Update"

Mensajes

Comando	Descripción	Parámetros
`list_chats`	Listar chats de iMessage y SMS disponibles	`includeParticipantDetails` (opcional, predeterminado: false)
`get_messages`	Obtener mensajes de la aplicación Mensajes	`limit` (opcional, predeterminado: 100)
`search_messages`	Buscar mensajes que contengan texto específico	`searchText`, `sender` (opcional), `chatId` (opcional), `limit` (opcional, predeterminado: 50), `daysBack` (opcional, predeterminado: 30)
`compose_message`	Abrir la aplicación Mensajes con mensaje prellenado o envío automático	`recipient` (requerido), `body` (opcional), `auto` (opcional, predeterminado: false)

Ejemplos

// List available chats
Show me my recent message conversations

// Get recent messages
Show me my last 20 messages

// Search messages
Find messages containing "dinner plans" from John in the last week

// Compose a message
Send a message to 555-123-4567 saying "I'll be there in 10 minutes"

Notas

Comando	Descripción	Parámetros
`create`	Crear una nota con formato similar a markdown	`title`, `content`, `format` (opcional con opciones de formato)
`createRawHtml`	Crear una nota con contenido HTML directo	`title`, `html`
`list`	Listar notas, opcionalmente de una carpeta específica	`folder` (opcional)
`get`	Obtener una nota específica por título	`title`, `folder` (opcional)
`search`	Buscar notas que contengan texto específico	`query`, `folder` (opcional), `limit` (opcional, predeterminado: 5), `includeBody` (opcional, predeterminado: true)

Ejemplos

// Create a new note with markdown formatting
Create a note titled "Meeting Minutes" with content "# Discussion Points\n- Project timeline\n- Budget review\n- Next steps" and format headings and lists

// Create a note with HTML
Create a note titled "Formatted Report" with HTML content "<h1>Quarterly Report</h1><p>Sales increased by <strong>15%</strong></p>"

// List notes
Show me all my notes in the "Work" folder

// Get a specific note
Show me my note titled "Shopping List"

// Search notes
Find notes containing "recipe" in my "Cooking" folder

Pages

Comando	Descripción	Parámetros
`create_document`	Crear un nuevo documento de Pages con texto plano	`content`

Ejemplos

// Create a new Pages document
Create a Pages document with the content "Project Proposal\n\nThis document outlines the scope and timeline for the upcoming project."

Arquitectura

El servidor applescript-mcp está construido usando TypeScript y sigue una arquitectura modular:

Componentes Principales

AppleScriptFramework (framework.ts): La clase principal del servidor que:
- Gestiona la comunicación del protocolo MCP
- Maneja el registro y ejecución de herramientas
- Proporciona funcionalidad de registro de eventos
- Ejecuta comandos de AppleScript
Categorías (src/categories/*.ts): Colecciones de scripts modulares organizadas por funcionalidad:
- Cada categoría contiene scripts relacionados (por ejemplo, calendario, sistema, notas)
- Las categorías se registran con el framework en index.ts
Tipos (src/types/index.ts): Interfaces de TypeScript que definen:
- ScriptDefinition: Estructura para scripts individuales
- ScriptCategory: Colección de scripts relacionados
- LogLevel: Niveles estándar de registro de eventos
- FrameworkOptions: Opciones de configuración

Flujo de Ejecución

El cliente envía una solicitud de herramienta a través del protocolo MCP
El servidor identifica la categoría y el script apropiados
Se genera el contenido del script (estático o dinámicamente mediante función)
AppleScript se ejecuta a través del comando osascript de macOS
Los resultados se devuelven al cliente

Sistema de Registro de Eventos

El framework incluye un sistema integral de registro de eventos que:

Registra tanto en stderr como en el protocolo de registro de MCP
Admite múltiples niveles de gravedad (depuración, información, advertencia, error, etc.)
Proporciona información detallada de ejecución para la resolución de problemas

Desarrollo

Configuración

# Install dependencies
npm install

# Build the server
npm run build

# Launch MCP Inspector
# See: https://modelcontextprotocol.io/docs/tools/inspector
npx @modelcontextprotocol/inspector node path/to/server/index.js args...

Agregar Nueva Funcionalidad

1. Crear Archivo de Categoría

Crear src/categories/newcategory.ts:

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

export const newCategory: ScriptCategory = {
  name: "category_name",
  description: "Category description",
  scripts: [
    // Scripts will go here
  ],
};

2. Agregar Scripts

{
  name: "script_name",
  description: "What the script does",
  schema: {
    type: "object",
    properties: {
      paramName: {
        type: "string",
        description: "Parameter description"
      }
    },
    required: ["paramName"]
  },
  script: (args) => `
    tell application "App"
      // AppleScript code using ${args.paramName}
    end tell
  `
}

3. Registrar Categoría

Actualizar src/index.ts:

import { newCategory } from "./categories/newcategory.js";
// ...
server.addCategory(newCategory);

Desarrollo Avanzado de Scripts

Para scripts más complejos, puedes:

Usar generación dinámica de scripts:

script: (args) => {
  // Process arguments and build script dynamically
  let scriptContent = `tell application "App"\n`;
  
  if (args.condition) {
    scriptContent += `  // Conditional logic\n`;
  }
  
  scriptContent += `end tell`;
  return scriptContent;
}

Procesar datos complejos:

// Example from Notes category
function generateNoteHtml(args: any): string {
  // Process markdown-like syntax into HTML
  let processedContent = content;
  
  if (format.headings) {
    processedContent = processedContent.replace(/^# (.+)$/gm, '<h1>$1</h1>');
    // ...
  }
  
  return processedContent;
}

Depuración

Usando MCP Inspector

El MCP Inspector proporciona una interfaz web para probar y depurar tu servidor:

npm run inspector

Registro de Eventos

Habilita el registro de depuración configurando la variable de entorno:

DEBUG=applescript-mcp* npm start

Configuración de ejemplo

Después de ejecutar npm run build, agrega lo siguiente a tu archivo mcp.json:

{
  "mcpServers": {
    "applescript-mcp-server": {
      "command": "node",
      "args": ["/path/to/applescript-mcp/dist/index.js"]
    }
  }
}

Problemas Comunes

Errores de Permisos: Verifica Preferencias del Sistema > Seguridad y Privacidad > Privacidad > Automatización
Fallos de Scripts: Prueba los scripts directamente en Editor de Scripts.app antes de la integración
Problemas de Comunicación: Verifica que los flujos stdio no estén siendo redirigidos
Acceso a Base de Datos: Algunas funciones (como Mensajes) requieren permiso de Acceso Completo al Disco

Recursos

Contribuciones

Haz un fork del repositorio
Crea una rama de funcionalidad
Realiza tus cambios
Envía a la rama
Crea una Solicitud de Extracción

Licencia

Licencia MIT - consulta LICENCIA para más detalles