Things3

Gestiona tareas y proyectos en Things3 en macOS.

GitHub
74
Prueba este MCPPatrocinado

Documentación

MseeP.ai Security Assessment Badge

Servidor MCP para Things3

Un servidor MCP (Model Context Protocol) robusto que proporciona una integración completa con Things3, permitiéndote crear, gestionar y buscar tareas y proyectos a través del protocolo MCP. Incluye manejo de errores mejorado, codificación segura de URL e integración mejorada con AppleScript.

Características

  • ✅ Crear Proyectos: Crea nuevos proyectos en Things3 con soporte completo de metadatos
  • ✅ Crear Tareas: Crea nuevas tareas pendientes con propiedades detalladas, incluyendo listas de verificación, etiquetas y fechas
  • ✅ Ver Tareas: Lista tareas de la bandeja de entrada, la lista de hoy o todos los proyectos
  • ✅ Completar Tareas: Marca tareas como completadas buscando por su título
  • ✅ Funcionalidad de Búsqueda: Busca entre todas las tareas por título o contenido
  • ✅ Manejo Robusto de Errores: Validación integral y recuperación de errores
  • ✅ Codificación Segura de URL: Manejo adecuado de caracteres especiales y unicode
  • ✅ Integración con AppleScript: Enfoque seguro de concatenación de cadenas sin JSON

Instalación

Requisitos previos

  • macOS con Things3 instalado
  • Python 3.8+
  • Things3 en ejecución (para operaciones en tiempo real)

Instalar el Servidor

  1. Clona este repositorio:

    git clone <repository-url>
cd mcp-things3

  2. Instala usando pip:

    pip install -e .

  3. El servidor estará disponible como mcp-server-things3

Herramientas Disponibles

Operaciones de Visualización

view-inbox

Ver todas las tareas en la bandeja de entrada de Things3.

  • Parámetros: Ninguno
  • Devuelve: Lista de tareas de la bandeja de entrada con fechas de vencimiento e información de programación

view-projects

Ver todos los proyectos en Things3.

  • Parámetros: Ninguno
  • Devuelve: Lista de todos los proyectos con sus títulos

view-todos

Ver todas las tareas en la lista de hoy.

  • Parámetros: Ninguno
  • Devuelve: Lista de tareas de hoy con metadatos

Operaciones de Creación

create-things3-project

Crea un nuevo proyecto en Things3.

  • Requerido: title (cadena)
  • Opcional:
    • notes (cadena)
    • area (cadena)
    • when (cadena) - Fecha/hora de inicio
    • deadline (cadena) - Fecha de vencimiento
    • tags (matriz de cadenas)

Ejemplo:

{
  "title": "Website Redesign",
  "notes": "Complete overhaul of company website",
  "area": "Work",
  "deadline": "2024-03-15",
  "tags": ["urgent", "web-dev"]
}

create-things3-todo

Crea una nueva tarea en Things3.

  • Requerido: title (cadena)
  • Opcional:
    • notes (cadena)
    • when (cadena) - Fecha/hora de inicio
    • deadline (cadena) - Fecha de vencimiento
    • checklist (matriz de cadenas)
    • tags (matriz de cadenas)
    • list (cadena) - Proyecto o área al que asignar
    • heading (cadena) - Grupo bajo este encabezado

Ejemplo:

{
  "title": "Review design mockups",
  "notes": "Check the new homepage designs",
  "list": "Website Redesign", 
  "deadline": "2024-02-20",
  "tags": ["review"],
  "checklist": ["Check mobile responsiveness", "Verify brand guidelines", "Test accessibility"]
}

Operaciones de Gestión

complete-things3-todo

Marca una tarea como completada buscando por su título.

  • Requerido: title (cadena) - Título o título parcial para buscar
  • Devuelve: Mensaje de éxito/fracaso

Ejemplo:

{
  "title": "Review design"
}

search-things3-todos

Busca tareas por título o contenido.

  • Requerido: query (cadena) - Término de búsqueda
  • Devuelve: Lista de tareas coincidentes con estado y metadatos

Ejemplo:

{
  "query": "website"
}

Integración con Claude

Este servidor MCP está diseñado para funcionar perfectamente con Claude AI. Una vez configurado, puedes usar lenguaje natural para gestionar tus tareas de Things3:

  • "Crea un proyecto llamado 'Planificación Q1' con fecha límite el 31 de marzo"
  • "Añade una tarea para revisar el presupuesto con una lista de verificación de tareas"
  • "Muéstrame todas mis tareas para hoy"
  • "Marca la tarea 'Llamar al cliente' como completada"
  • "Busca todas las tareas relacionadas con el proyecto del sitio web"

Configuración

Configuración del Cliente MCP

Añade a tu configuración del cliente MCP (por ejemplo, configuración de Claude Desktop):

{
  "mcpServers": {
    "things3": {
      "command": "mcp-server-things3",
      "args": []
    }
  }
}

Configuración de Things3

  1. Asegúrate de que Things3 esté instalado y en ejecución
  2. Concede los permisos necesarios cuando se soliciten para el acceso a AppleScript
  3. El servidor validará la disponibilidad de Things3 antes de las operaciones

Arquitectura

Componentes

  • server.py: Implementación principal del servidor MCP con definiciones de herramientas y manejadores
  • applescript_handler.py: Integración robusta con AppleScript con análisis seguro de datos
  • Codificación de URL: Codificación adecuada de parámetros x-callback-url para caracteres especiales
  • Manejo de Errores: Validación integral y recuperación elegante de errores

Características de Seguridad

  • Saneamiento de Entradas: Todas las entradas del usuario están correctamente escapadas para AppleScript
  • Codificación de URL: Caracteres especiales y unicode manejados adecuadamente en URLs
  • Validación: Disponibilidad de Things3 verificada antes de las operaciones
  • Recuperación de Errores: Manejo elegante de errores de AppleScript y del sistema

Desarrollo

Ejecutar Pruebas

python test_things3.py

Depuración

El servidor incluye registro integral. Establece el nivel de registro para depuración:

export PYTHONPATH="."
python -c "
import logging
logging.basicConfig(level=logging.DEBUG)
from src.mcp_server_things3.server import main
import asyncio
asyncio.run(main())
"

Contribuir

  1. Haz un fork del repositorio
  2. Crea una rama de características
  3. Añade pruebas para la nueva funcionalidad
  4. Asegúrate de que todas las pruebas pasen
  5. Envía una solicitud de extracción

Solución de Problemas

Problemas Comunes

"Things3 no está disponible"

  • Asegúrate de que Things3 esté instalado y en ejecución
  • Concede permisos de AppleScript cuando se soliciten
  • Verifica que Things3 no esté en un modo de permisos restringidos

"Error al ejecutar AppleScript"

  • Verifica que la configuración de seguridad de macOS permita AppleScript
  • Asegúrate de que Things3 tenga los permisos de accesibilidad necesarios
  • Intenta reiniciar Things3

Problemas de codificación de URL con caracteres especiales

  • El servidor ahora maneja adecuadamente unicode y caracteres especiales
  • Si los problemas persisten, revisa los registros para errores específicos de construcción de URL

Notas de Rendimiento

  • Las operaciones de AppleScript pueden tener ligeros retrasos
  • Las listas de tareas grandes (más de 1000 elementos) pueden tardar más en buscarse
  • Considera usar búsquedas específicas en lugar de consultas amplias para un mejor rendimiento

Licencia

Licencia MIT - consulta el archivo LICENSE para más detalles.

Registro de Cambios

v0.1.0

  • Lanzamiento inicial con operaciones CRUD básicas
  • Manejo integral de errores y validación
  • Codificación segura de URL e integración con AppleScript
  • Funcionalidad de búsqueda y completado
  • Análisis robusto de datos sin concatenación de cadenas JSON