OmniFocus

Un servidor MCP profesional para OmniFocus con caché inteligente y análisis para gestionar tareas y proyectos.

GitHub
15
Prueba este MCPPatrocinado

Documentación

Protocolo de Contexto de Modelo para OmniFocus (incl. funciones avanzadas)

Aviso: disculpa la rigidez de la documentación y el lenguaje de los commits; el proyecto está completamente codificado mediante Claude Code, por lo que muchos mensajes son tan divertidos como un informe contable (con énfasis aleatorio de vendedor de autos aquí y allá).

Un servidor profesional de Protocolo de Contexto de Modelo (MCP) para OmniFocus que proporciona capacidades avanzadas de gestión de tareas con caché inteligente y análisis. Construido con TypeScript y pleno respeto por la API oficial de OmniAutomation de OmniFocus.

Características

Capacidades Principales

  • Caché Inteligente: Sistema de caché basado en TTL para un rendimiento óptimo
  • Seguridad de Tipos: Soporte completo de TypeScript con tipos exhaustivos
  • Solo API Oficial: Utiliza únicamente scripts de OmniAutomation (sin manipulación de bases de datos)
  • Alto Rendimiento: Maneja más de 1000 tareas de manera eficiente con caché inteligente

Herramientas Disponibles

Operaciones de Tareas (Lectura)

  • list_tasks - Filtrado avanzado de tareas con caché inteligente
    • Filtrar por: estado de finalización, banderas, proyecto, etiquetas, fechas, términos de búsqueda
    • Soporta filtrado de bandeja de entrada y verificación de disponibilidad
    • Soporta hasta 1000 tareas con metadatos de paginación adecuados
    • Resultados almacenados en caché durante 30 segundos para consultas repetidas ultrarrápidas
  • get_task_count - Obtener el conteo de tareas que coinciden con los filtros sin datos
    • Mismas opciones de filtrado que list_tasks
    • Devuelve solo el conteo por rendimiento

Operaciones de Tareas (Escritura)

  • create_task - Crear nuevas tareas en la bandeja de entrada
    • Establecer nombre, nota, estado de bandera, fechas de vencimiento/posposición
    • Asignación de etiquetas limitada a etiquetas existentes
    • Devuelve ID temporal (limitación de JXA)
  • update_task - Actualizar tareas existentes
    • Modificar nombre, nota, estado de bandera, fechas
    • Gestión limitada de etiquetas debido a JXA
  • complete_task - Marcar tareas como completadas
  • delete_task - Eliminar tareas

Operaciones de Proyectos

  • list_projects - Listar y filtrar proyectos con caché
    • Filtrar por: estado (activo, en espera, abandonado, completado), banderas, carpeta
    • Resultados almacenados en caché durante 5 minutos
  • create_project - Crear nuevos proyectos con soporte de carpetas
    • Crea automáticamente carpetas si no existen
    • Establecer nombre, nota, fechas, banderas y carpeta principal
  • update_project - Actualizar propiedades de proyectos
    • Cambiar nombre, nota, estado, fechas, banderas
    • Movimiento de carpetas soportado con limitaciones (restricción de JXA)
  • complete_project - Marcar proyectos como completados
  • delete_project - Eliminar proyectos de OmniFocus

Próximamente

  • Herramientas de análisis (estadísticas de productividad, seguimiento de velocidad, análisis de vencidos)
  • Gestión de etiquetas
  • Operaciones masivas
  • Búsqueda inteligente con lenguaje natural
  • Análisis de tareas recurrentes

Instalación y Permisos

Requisitos Previos

  1. OmniFocus 3 o posterior instalado en macOS
  2. Node.js 18+ instalado
  3. Permiso para acceder a OmniFocus mediante automatización (ver Guía de Permisos)

Pasos de Instalación

# Clone the repository
git clone https://github.com/yourusername/omnifocus-cache-by-windsurf.git
cd omnifocus-cache-by-windsurf

# Install dependencies
npm install

# Build the project
npm run build

# Run the server
npm start

Otorgamiento de Permisos

La primera vez que uses el servidor MCP, macOS te pedirá que otorgues permiso para acceder a OmniFocus. Consulta la Guía de Permisos para instrucciones detalladas.

Configuración

Configuración de Claude Desktop

Agrega a tu archivo de configuración de Claude Desktop (~/Library/Application Support/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "omnifocus": {
      "command": "node",
      "args": ["/path/to/omnifocus-cache-by-windsurf/dist/index.js"],
      "env": {
        "LOG_LEVEL": "info"
      }
    }
  }
}

Variables de Entorno

  • LOG_LEVEL - Establece el nivel de registro: error, warn, info, debug (predeterminado: info)

Ejemplos de Uso

Listar Todas las Tareas Incompletas

{
  "tool": "list_tasks",
  "arguments": {
    "completed": false,
    "limit": 50
  }
}

Crear una Nueva Tarea con Asignación de Proyecto

// First, find the project ID
{
  "tool": "list_projects",
  "arguments": {
    "search": "Budget Planning"
  }
}
// Returns: { "projects": [{ "id": "jH8x2mKl9pQ", "name": "Budget Planning 2024", ... }] }

// Then create the task in that project
{
  "tool": "create_task",
  "arguments": {
    "name": "Review Q4 budget",
    "projectId": "jH8x2mKl9pQ",  // Use the ID from list_projects
    "dueDate": "2024-01-15T17:00:00Z",
    "flagged": true,
    "tags": ["finance", "urgent"],
    "estimatedMinutes": 30
  }
}

Mover una Tarea Entre Proyectos

// Move an existing task to a different project
{
  "tool": "update_task",
  "arguments": {
    "taskId": "abc123xyz",
    "projectId": "newProjectId"  // Or null to move to inbox
  }
}

Encontrar Tareas Vencidas

{
  "tool": "list_tasks",
  "arguments": {
    "completed": false,
    "dueBefore": "2024-01-01T00:00:00Z",
    "search": "budget"
  }
}

Listar Proyectos Activos

{
  "tool": "list_projects",
  "arguments": {
    "status": ["active"],
    "flagged": true
  }
}

Crear un Proyecto con Carpeta

{
  "tool": "create_project",
  "arguments": {
    "name": "New Website Launch",
    "note": "Complete redesign and launch",
    "folder": "Work Projects",  // Creates folder if it doesn't exist
    "dueDate": "2024-03-31T17:00:00Z",
    "flagged": true
  }
}

Actualizar Proyecto (Incluyendo Carpeta)

// First, get the project ID from list_projects
{
  "tool": "list_projects",
  "arguments": {
    "search": "Website Launch"
  }
}

// Then update using the project ID
{
  "tool": "update_project",
  "arguments": {
    "projectId": "jH8x2mKl9pQ",  // Use the ID from list_projects
    "updates": {
      "folder": "Archive",  // Note: Folder movement has JXA limitations
      "status": "onHold",
      "note": "Postponed until Q2"
    }
  }
}

Solución de Problemas

Errores de "Proyecto no encontrado" con IDs Numéricos

Si ves errores como Project with ID '547' not found seguidos de una advertencia de error de Claude Desktop:

  1. Usa list_projects para obtener el ID completo correcto del proyecto:

    {
  "tool": "list_projects",
  "arguments": {
    "search": "your project name"
  }
}

  2. Copia el ID alfanumérico completo (por ejemplo, "az5Ieo4ip7K") de los resultados

  3. Usa nombres de proyectos como alternativa:

    {
  "tool": "update_task", 
  "arguments": {
    "taskId": "your-task-id",
    "projectId": null  // Move to inbox first
  }
}

    Luego asigna manualmente en OmniFocus, o usa nombres de proyectos en los filtros de búsqueda.

Fallos en la Actualización de Tareas

  • Siempre obtén los IDs de tareas de list_tasks en lugar de adivinar
  • Usa list_projects para verificar los IDs de proyectos antes de la asignación
  • Verifica que las tareas existan y no estén en la papelera

Arquitectura

Estrategia de Caché

El servidor implementa caché inteligente con diferentes TTL para diferentes tipos de datos:

  • Tareas: 30 segundos (cambian con frecuencia)
  • Proyectos: 5 minutos (menos volátiles)
  • Análisis: 1 hora (cálculos costosos)
  • Etiquetas: 10 minutos (relativamente estables)

La caché se invalida automáticamente en operaciones de escritura.

Integración con OmniAutomation

Todas las interacciones con OmniFocus utilizan JavaScript para Automatización (JXA) a través de OmniAutomation:

  • Los scripts están envueltos para el manejo de errores
  • Los parámetros se escapan de manera segura
  • Los resultados están tipados y validados
  • Se soportan operaciones por lotes

Manejo de Errores

El servidor proporciona mensajes de error detallados con:

  • Tipos de error específicos (No encontrado, Permiso, Ejecución de script)
  • Información contextual para depuración
  • Degradación gradual cuando sea posible

Desarrollo

Requisitos Previos

  • Node.js 18+
  • OmniFocus 3+ (Pro recomendado)
  • macOS (requerido para OmniAutomation)

Scripts

npm run build    # Build TypeScript
npm run dev      # Watch mode
npm run test     # Run tests
npm run lint     # Lint code
npm run typecheck # Type checking

Estructura del Proyecto

src/
├── cache/          # Smart caching system
├── omnifocus/      # OmniAutomation integration
│   └── scripts/    # JXA script templates
├── tools/          # MCP tool implementations
├── utils/          # Logging and helpers
└── index.ts        # Server entry point

Rendimiento

  • Maneja más de 1000 tareas con tiempos de respuesta inferiores a un segundo
  • La caché inteligente reduce las llamadas a la API de OmniFocus en más del 80%
  • Ejecución concurrente de scripts para operaciones por lotes
  • Eficiente en memoria con limpieza automática de caché

Seguridad

  • Sin acceso directo a la base de datos
  • Los parámetros se sanitizan antes de la ejecución del script
  • Operaciones de solo lectura por defecto
  • No se registran datos sensibles

Contribuciones

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

Mejoras Futuras

Recomendaciones de Alta Prioridad

  1. Corregir el Conjunto de Pruebas Unitarias: Varias pruebas unitarias están fallando debido a suposiciones incorrectas sobre el código base. Áreas prioritarias:

    • Actualizar las expectativas de las pruebas para que coincidan con los formatos reales de respuesta de la API
    • Alinear los objetos simulados con las interfaces reales de implementación
    • Eliminar pruebas que verifican comportamiento incorrecto (por ejemplo, esperar que primaryKey sea un método cuando es una propiedad)

  2. Agregar Configuración de ESLint: Al proyecto le falta un archivo de configuración de ESLint, lo que impide que se ejecute el linting. Crea un eslint.config.js que soporte TypeScript y siga los estándares de codificación del proyecto.

  3. Mejorar la Recuperación de Errores: Si bien el respaldo del esquema de URL para errores de permiso denegado es un buen comienzo, considera:

    • Implementar lógica de reintento con retroceso exponencial
    • Agregar mensajes de error amigables que sugieran soluciones
    • Crear una herramienta de diagnóstico para ayudar a los usuarios a solucionar problemas de permisos

Licencia

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

Pruebas

Pruebas de Extremo a Extremo con Claude Desktop

Para probar el sistema de permisos con Claude Desktop:

  1. Revocar Permisos (para probar el manejo de errores):

    • Abre Configuración del Sistema → Privacidad y Seguridad → Automatización
    • Encuentra "Claude" (o "Electron" si Claude no está listado)
    • Desmarca la casilla junto a "OmniFocus"

  2. Probar en Claude Desktop:

    • Pregunta a Claude: "¿Puedes listar mis tareas de OmniFocus?"
    • Deberías ver un mensaje de error útil con instrucciones para otorgar permisos

  3. Otorgar Permisos:

    • Haz clic en "Aceptar" cuando aparezca el diálogo de permisos
    • O habilítalo manualmente en Configuración del Sistema como se indica

  4. Verificar el Éxito:

    • Pregunta nuevamente a Claude que liste tus tareas
    • Las tareas deberían mostrarse correctamente ahora

Pruebas Durante el Desarrollo

# Build and test the server
npm run build
npm test

# Test with MCP Inspector
npx @modelcontextprotocol/inspector dist/index.js

# Run integration tests
node tests/integration/test-as-claude-desktop.js

Notas Técnicas

Error de Análisis de IDs en Claude Desktop

PROBLEMA CRÍTICO: Claude Desktop tiene un error confirmado donde extrae porciones numéricas de IDs alfanuméricos de proyectos al llamar a herramientas MCP.

Ejemplo: Cuando proporcionas el ID de proyecto "az5Ieo4ip7K", Claude Desktop puede pasar solo "547" a la herramienta, causando errores de "Proyecto no encontrado".

Síntomas:

  • Las actualizaciones de tareas fallan con errores de "Proyecto no encontrado"
  • Los mensajes de error muestran IDs numéricos (como "547") en lugar de IDs alfanuméricos completos
  • Ocurre incluso cuando se proporcionan IDs completos de proyectos en las indicaciones

Mitigación:

  • Nuestros mensajes de error ahora detectan este patrón y proporcionan orientación útil
  • Las descripciones de las herramientas advierten sobre el uso de IDs alfanuméricos completos
  • Considera usar nombres de proyectos en lugar de IDs cuando este error afecte tu flujo de trabajo

Problemas Relacionados: Esto es parte de errores más amplios de procesamiento de parámetros de Claude Desktop documentados en problemas de GitHub, incluidos fallos de conversión de tipos y errores de análisis JSON.

Requisito de Módulos ES

Este proyecto utiliza módulos ES (ESM) con extensiones .js en las declaraciones de importación, lo que puede parecer inusual para proyectos TypeScript. Esto es necesario porque:

  1. El SDK de MCP (@modelcontextprotocol/sdk) actualmente es solo ESM
  2. Hay problemas conocidos de compatibilidad con CommonJS (ver Problema de GitHub #217)

Migración Futura: Una vez que el SDK de MCP agregue soporte adecuado para CommonJS, este proyecto debería migrar a TypeScript/CommonJS estándar para eliminar la necesidad de extensiones .js en las importaciones.

Agradecimientos

Construido con: