Things 3

Gestiona tus tareas y proyectos en Things 3 en macOS.

GitHub

Documentación

Servidor MCP de Things 3 (Ruby)

Un servidor integral del Model Context Protocol (MCP) para la gestión de tareas de Things 3 en macOS. Este servidor proporciona gestión de tareas en lenguaje natural, filtrado avanzado, operaciones masivas, análisis y herramientas de mantenimiento mediante la integración con AppleScript.

Solo macOS: Este servidor MCP requiere macOS y Things 3 (que es exclusivo de macOS).

🏗️ Arquitectura

El código está organizado en clases enfocadas con una clara separación de responsabilidades:

  • Things3MCPServer - Implementación principal del servidor MCP
  • AppleScriptExecutor - Maneja la ejecución de AppleScript con gestión de errores
  • AppleScriptGenerator - Genera código AppleScript para operaciones de Things 3
  • Things3Client - Operaciones principales de tareas de Things 3 (CRUD)
  • DateParser - Análisis de fechas en lenguaje natural usando la gema Chronic
  • TaskFilter - Capacidades avanzadas de filtrado y búsqueda de tareas
  • BulkOperations - Operaciones masivas de tareas (crear, actualizar, mover, completar, importar)
  • ReportGenerator - Revisiones semanales, informes de proyectos y análisis

🚀 Características

Gestión Principal de Tareas

  • Operaciones CRUD: Crear, leer, actualizar, eliminar tareas
  • Fechas en Lenguaje Natural: "mañana", "el próximo viernes", "en 3 días", etc.
  • Organización Inteligente: Asignación de proyectos/áreas con creación automática
  • Búsqueda Avanzada: Filtrado multicriterio con soporte de expresiones regulares

Filtrado Avanzado

  • Filtros Complejos: Estado, proyectos, áreas, etiquetas, fechas, notas
  • Filtros Rápidos: Filtros predefinidos para escenarios comunes
  • Filtros Guardados: Almacena y reutiliza combinaciones de filtros complejas
  • Búsqueda de Texto: Búsqueda en nombres y contenido de notas con expresiones regulares

Operaciones Masivas

  • Creación Masiva: Crea múltiples tareas desde listas o plantillas
  • Actualizaciones Masivas: Actualiza tareas que coincidan con criterios específicos
  • Operaciones con Etiquetas: Añadir, eliminar, estandarizar etiquetas entre tareas
  • Importar/Exportar: Soporte de importación CSV, JSON y texto plano

Análisis e Informes

  • Revisiones Semanales: Generación integral de revisiones
  • Salud del Proyecto: Analiza el progreso y los cuellos de botella del proyecto
  • Perspectivas de Productividad: Patrones y tendencias de finalización
  • Herramientas de Planificación: Planificación de la próxima semana con programación basada en energía

Mantenimiento de Datos

  • Detección de Duplicados: Encuentra y fusiona tareas similares
  • Limpieza de Tareas Huérfanas: Organiza tareas sin proyectos/áreas
  • Estandarización de Etiquetas: Limpia la nomenclatura inconsistente de etiquetas
  • Salud del Sistema: Puntuación de organización y métricas de salud

📋 Requisitos

  • macOS: Requerido (Things 3 es solo para macOS)
  • Things 3: Debe estar instalado y en ejecución
  • Ruby: Versión 3.0.0 o superior
  • Dependencias: Gestionadas mediante Bundler

Nota: Este servidor MCP solo funciona en macOS ya que Things 3 es una aplicación exclusiva de macOS.

🔐 Configuración de Permisos de macOS

Este servidor MCP utiliza AppleScript para comunicarse con Things 3, lo que requiere permisos específicos de macOS:

1. Permisos de Accesibilidad

Cuando ejecutes el servidor MCP por primera vez, macOS solicitará permisos de accesibilidad:

  1. Preferencias del Sistema → Seguridad y Privacidad → Privacidad → Accesibilidad
  2. Haz clic en el candado para realizar cambios (introduce tu contraseña)
  3. Añade tu cliente MCP (por ejemplo, Claude Desktop, Cursor, Terminal)
  4. Activa la casilla para la aplicación

2. Permisos de AppleScript

El servidor también puede necesitar permisos de AppleScript:

  1. Preferencias del Sistema → Seguridad y Privacidad → Privacidad → Automatización
  2. Encuentra tu cliente MCP en la lista
  3. Activa "Things3" bajo tu aplicación cliente

3. Permisos de Terminal/Ruby (si se ejecuta directamente)

Si ejecutas el servidor directamente desde Terminal:

  1. Preferencias del Sistema → Seguridad y Privacidad → Privacidad → Accesibilidad
  2. Añade Terminal (o tu aplicación de terminal)
  3. Activa la casilla

💡 Consejo: Si recibes errores de "permiso denegado", reinicia tu cliente MCP después de otorgar los permisos.

🛠 Instalación

  1. Clona el repositorio:

    git clone https://github.com/mattsafaii/things3-mcp.git
cd things3-mcp

  2. Instala las dependencias:

    bundle install

  3. Ejecuta el servidor MCP:

    ./things3-mcp-server

  4. Configúralo en tu cliente MCP - Consulta Configuración del Cliente MCP a continuación

🔌 Configuración del Cliente MCP

Claude Desktop

  1. Encuentra tu archivo de configuración:

    • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

  2. Añade la configuración del servidor:

    {
  "mcpServers": {
    "things3": {
      "command": "/absolute/path/to/things3-mcp/things3-mcp-server",
      "args": []
    }
  }
}

  3. Reinicia Claude Desktop - El servidor aparecerá en tus herramientas disponibles

Cursor IDE

  1. Abre la Configuración de Cursor (Cmd + ,)

  2. Navega a Extensiones → MCP

  3. Añade la configuración del servidor:

    {
  "name": "Things3",
  "command": "/absolute/path/to/things3-mcp/things3-mcp-server",
  "args": []
}

VS Code (con Extensión MCP)

  1. Instala una extensión MCP desde el mercado de VS Code

  2. Abre la Configuración de VS Code (Cmd + ,)

  3. Busca "MCP" y añade el servidor:

    {
  "mcp.servers": [
    {
      "name": "things3",
      "command": "/absolute/path/to/things3-mcp/things3-mcp-server",
      "args": []
    }
  ]
}

Editor Zed

  1. Abre la configuración de Zed (Cmd + ,)

  2. Añade a tu settings.json:

    {
  "language_models": {
    "mcp_servers": {
      "things3": {
        "command": "/absolute/path/to/things3-mcp/things3-mcp-server",
        "args": []
      }
    }
  }
}

Continue (Extensión de VS Code)

  1. Abre la configuración de Continue (.continue/config.json en tu espacio de trabajo)

  2. Añade el servidor MCP:

    {
  "mcpServers": {
    "things3": {
      "command": "/absolute/path/to/things3-mcp/things3-mcp-server",
      "args": []
    }
  }
}

Cliente MCP Genérico

Para cualquier cliente MCP que soporte el estándar, usa:

{
  "name": "things3",
  "command": "/absolute/path/to/things3-mcp/things3-mcp-server",
  "args": [],
  "env": {
    "PATH": "/usr/local/bin:/usr/bin:/bin"
  }
}

Consejos de Configuración

  1. Usa rutas absolutas - Las rutas relativas pueden no funcionar en diferentes clientes
  2. Verifica los permisos - Asegúrate de que el ejecutable tenga los permisos adecuados (chmod +x)
  3. Prueba el servidor - Ejecuta ./things3-mcp-server manualmente para verificar que funciona
  4. Revisa los registros - La mayoría de los clientes MCP proporcionan registros para depurar problemas de conexión

Verificación de la Instalación

Una vez configurado, deberías ver estas herramientas disponibles en tu cliente MCP:

  • add_task, list_tasks, complete_task (operaciones principales)
  • weekly_review, project_status_report (análisis)
  • bulk_create_tasks, filter_tasks (características avanzadas)
  • Y más de 30 otras herramientas especializadas

Prueba con un comando simple:

"Add a task called 'Test MCP integration' to my Things 3"

Si tiene éxito, verás la tarea aparecer en Things 3 y recibirás un mensaje de confirmación.

Primera Ejecución: En el primer uso, macOS solicitará permisos (consulta Configuración de Permisos de macOS). Otorga los permisos y reinicia tu cliente MCP.

🎯 Herramientas Disponibles

33 herramientas integrales organizadas en categorías funcionales:

Operaciones Principales de Tareas

  • add_task - Crear nuevas tareas con metadatos completos
  • list_tasks - Listar tareas con opciones de filtrado
  • list_projects - Listar todos los proyectos y áreas
  • update_task - Modificar propiedades de tareas existentes
  • complete_task - Marcar tareas como completadas
  • delete_task - Eliminar tareas de Things 3
  • move_task - Mover tareas entre proyectos/áreas
  • search_tasks - Buscar nombres y contenido de tareas

Características Avanzadas

  • add_task_with_planning_notes - Crear tareas con metadatos de planificación
  • list_tasks_by_date_range - Filtrar tareas por rangos de fechas
  • snooze_task - Posponer tareas a fechas futuras
  • parse_date - Probar el análisis de fechas en lenguaje natural

Filtrado y Búsqueda

  • filter_tasks - Filtrado avanzado multicriterio
  • quick_filters - Filtros útiles predefinidos (huérfanas, vencidas, etc.)
  • saved_filters - Gestionar configuraciones de filtros reutilizables

Análisis e Informes

  • weekly_review - Generar revisiones semanales integrales
  • project_status_report - Analizar proyectos activos
  • productivity_insights - Rastrear patrones de productividad
  • next_week_planning - Planificar la próxima semana con niveles de energía
  • review_templates - Gestionar formatos de revisión consistentes

Operaciones Masivas

  • bulk_create_tasks - Crear múltiples tareas a la vez
  • bulk_update_tasks - Actualizar múltiples tareas coincidentes
  • bulk_move_tasks - Mover tareas entre proyectos
  • bulk_tag_operations - Gestión masiva de etiquetas
  • bulk_complete_tasks - Completar múltiples tareas
  • bulk_import_tasks - Importar desde formatos externos

Limpieza y Mantenimiento de Datos

  • cleanup_orphaned_tasks - Organizar tareas no asignadas
  • find_duplicate_tasks - Detectar y fusionar duplicados
  • standardize_tags - Limpiar la consistencia de nombres de etiquetas
  • cleanup_stale_tasks - Manejar tareas antiguas/abandonadas
  • analyze_project_health - Métricas de salud del proyecto
  • fix_broken_references - Reparar problemas de integridad de datos
  • organization_score - Evaluación general de la salud del sistema

Plantillas y Automatización

  • task_templates - Gestionar conjuntos de tareas reutilizables

🔧 Configuración

Almacenamiento de Filtros Guardados

Los filtros se guardan automáticamente en: ~/.things3_mcp_filters.json

Modo de Depuración

Activa el registro detallado estableciendo indicadores de depuración en los constructores de clases o mediante variables de entorno.

📖 Ejemplos de Uso

Gestión Básica de Tareas

# Add simple task
add_task({"name": "Buy groceries"})

# Add task with project and due date
add_task({
  "name": "Finish quarterly report", 
  "project": "Work",
  "due_date": "next Friday",
  "tags": ["urgent", "quarterly"]
})

Fechas en Lenguaje Natural

# Various supported formats
add_task({"name": "Team meeting", "due_date": "tomorrow at 2pm"})
add_task({"name": "Vacation planning", "due_date": "end of month"})
add_task({"name": "Project review", "start_date": "next Monday", "due_date": "in 2 weeks"})

Filtrado Avanzado

# Complex filter
filter_tasks({
  "status": ["open"],
  "project_names": ["Work", "Personal"],
  "tag_filter": {"has_tags": ["urgent"]},
  "date_filter": {"overdue": true}
})

# Quick filters
quick_filters({"filter_type": "orphaned_tasks"})

Flujo de Trabajo de Revisión Semanal

# Generate comprehensive review
weekly_review({
  "review_type": "last_week",
  "include_sections": ["completed", "overdue", "upcoming", "projects", "insights"]
})

# Project health check
project_status_report({"include_metrics": true})

# Plan next week
next_week_planning({"include_energy_levels": true})

Operaciones Masivas

# Create multiple tasks
bulk_create_tasks({
  "tasks": [
    {"name": "Research competitors", "project": "Website"},
    {"name": "Design mockups", "project": "Website", "due_date": "Friday"},
    {"name": "Write content", "project": "Website"}
  ]
})

# Standardize tags
standardize_tags({
  "apply": true,
  "rules": {"lowercase": true, "merge_similar": true}
})

🛡️ Manejo de Errores

  • Disponibilidad de Things 3: Valida que Things 3 esté en ejecución antes de las operaciones
  • Errores de AppleScript: Captura integral de errores con mensajes descriptivos
  • Análisis de Fechas: Manejo elegante de fechas ambiguas con indicadores de confianza
  • Validación de Entrada: Validación de parámetros con mensajes de error útiles
  • Protección de Tiempo de Espera: Tiempo de espera de 30 segundos en operaciones de AppleScript

📁 Estructura de Archivos

things3-mcp/
├── things3-mcp-server            # Executable script (root level)
├── lib/
│   ├── things3_mcp.rb            # Main entry point
│   └── things3_mcp/
│       ├── server.rb             # MCP server implementation
│       ├── client.rb             # Core Things 3 operations
│       ├── date_parser.rb        # Natural language date parsing
│       ├── task_filter.rb        # Advanced task filtering
│       ├── bulk_operations.rb    # Bulk task operations
│       ├── report_generator.rb   # Analytics and reports
│       └── applescript/
│           ├── executor.rb       # AppleScript execution engine
│           └── generator.rb      # AppleScript code generation
├── Gemfile                       # Ruby dependencies
├── Gemfile.lock                  # Locked dependency versions

└── README.md                     # This documentation

🔍 Solución de Problemas

Problemas Comunes

Things 3 No Está en Ejecución

Error: Things 3 is not available

Solución: Inicia la aplicación Things 3

Permiso Denegado de AppleScript

Error: AppleScript execution failed - permission denied

Soluciones:

  • Otorga permisos de Accesibilidad: Preferencias del Sistema → Seguridad y Privacidad → Privacidad → Accesibilidad
  • Otorga permisos de Automatización: Preferencias del Sistema → Seguridad y Privacidad → Privacidad → Automatización
  • Añade tu cliente MCP (Claude Desktop, Cursor, etc.) a ambas listas de permisos
  • Reinicia tu cliente MCP después de otorgar los permisos
  • Si se ejecuta directamente, añade Terminal a los permisos de Accesibilidad

Problemas de Análisis de Fechas

Error: Could not parse date: 'next Flursday'

Solución: Usa formatos compatibles como "el próximo viernes", "en 3 días" o "AAAA-MM-DD"

Tiempo de Espera de AppleScript

Error: AppleScript execution timeout

Solución: Reduce el tamaño de las operaciones masivas o verifica el rendimiento de Things 3

El Servidor MCP No Se Conecta

Error: MCP server failed to start

Soluciones:

  • Verifica que la ruta absoluta a things3-mcp-server sea correcta
  • Comprueba que el ejecutable tenga los permisos adecuados (chmod +x things3-mcp-server)
  • Prueba el servidor manualmente: ./things3-mcp-server
  • Revisa los registros del cliente MCP para mensajes de error detallados
  • Asegúrate de que Ruby y las dependencias estén instalados correctamente

Las Herramientas MCP No Aparecen

No Things3 tools available in client

Soluciones:

  • Reinicia tu cliente MCP después de los cambios de configuración
  • Verifica que la sintaxis de la configuración JSON sea válida
  • Comprueba que el nombre del servidor no entre en conflicto con otros servidores MCP
  • Busca errores de conexión en los registros del cliente

Modo de Depuración

Activa el registro detallado estableciendo debug: true en los constructores de clases para solucionar problemas.

🤝 Integración MCP

Este servidor implementa el Model Context Protocol y puede usarse con cualquier cliente compatible con MCP:

  • Claude Desktop - El cliente MCP más popular
  • Cursor IDE - Editor de código con IA con soporte MCP
  • VS Code - Con extensiones MCP
  • Editor Zed - Editor moderno con soporte MCP integrado
  • Continue - Extensión de VS Code para asistencia de codificación con IA
  • Aplicaciones Personalizadas - Cualquier herramienta que implemente el estándar MCP

Consulta la sección Configuración del Cliente MCP anterior para obtener instrucciones detalladas de configuración para cada cliente.

El servidor proporciona una interfaz de lenguaje natural para la gestión integral de tareas de Things 3 a través del protocolo MCP estandarizado, haciendo que tu gestión de tareas esté disponible para cualquier asistente de IA o herramienta de automatización que soporte MCP.

📄 Dependencias

  • mcp (~> 0.1.0) - Implementación del Model Context Protocol
  • chronic (~> 0.10.2) - Análisis de fechas en lenguaje natural
  • debug, rubocop (desarrollo)

📊 Salud del Sistema

El servidor incluye monitoreo de salud integrado a través de:

  • Puntuación de organización (0-100 en múltiples dimensiones)
  • Análisis de salud del proyecto
  • Detección de duplicados
  • Verificaciones de integridad de datos
  • Análisis de tendencias de productividad

El mantenimiento regular se puede automatizar a través de las herramientas de limpieza y análisis proporcionadas.