FocusRelay

FocusRelay — Servidor MCP y CLI rápido en Swift para OmniFocus en macOS

Planifica tu día y mantén OmniFocus al día con IA

FocusRelay es un servidor MCP y CLI rápido y nativo en Swift que ayuda a los asistentes de IA a leer y actualizar OmniFocus de forma segura mediante las APIs documentadas de OmniFocus.

Instalar con Homebrew · Ver lo que puede hacer · Destaca FocusRelay · Contribuir

Pregunta sobre el trabajo ya existente en OmniFocus, revisa la respuesta y realiza los cambios aprobados sin tener que hacer clic en largas listas de tareas.

Pregunta. Revisa. Actualiza.

FocusRelay está diseñado para preguntas específicas y respuestas compactas, de modo que el asistente no necesite toda tu base de datos de OmniFocus para solicitudes rutinarias.

Prueba indicaciones como:

• «Ayúdame a procesar mi bandeja de entrada de OmniFocus en un lote pequeño».
• «¿Cuántos elementos marcados tengo?»
• «Muéstrame las tres primeras tareas disponibles en mi bandeja de entrada».
• «Encuentra mi tarea llamada [nombre de la tarea], márcala y verifica el cambio».
• «Establece [nombre de la tarea] como pendiente para mañana a las 5 PM en mi zona horaria local y verifica el cambio».

En clientes que exponen indicaciones del servidor MCP, selecciona process_inbox. En OpenCode, ejecuta /focusrelay:process_inbox para iniciar el flujo de trabajo guiado. Los agentes basados en CLI pueden recuperar las mismas instrucciones con focusrelay workflow get process_inbox; usa focusrelay workflow list para descubrir los flujos de trabajo disponibles sin cargar su texto completo.

Estos flujos de trabajo se probaron con varios modelos compatibles con MCP en OpenCode. Las actualizaciones apuntan a IDs estables de OmniFocus y pueden verificar el resultado guardado. Si los nombres están duplicados, pide ver los candidatos antes de cambiar nada.

La versión actual puede:

• guiar a clientes MCP compatibles y agentes basados en CLI a través de un flujo de trabajo de bandeja de entrada acotado y con aprobación previa;
• encontrar y contar tareas usando fechas, marcadores, etiquetas, proyectos, disponibilidad, estado de la bandeja de entrada, finalización, estimaciones y búsqueda de texto;
• revisar proyectos, carpetas, etiquetas, recuentos de tareas y trabajo estancado;
• actualizar nombres, notas, marcadores, fechas, estimaciones, etiquetas, configuraciones de proyectos e intervalos de revisión;
• marcar proyectos activos y en espera como revisados usando la marca de tiempo de revisión nativa de OmniFocus y su semántica de próxima revisión;
• eliminar, restaurar, completar, reactivar y mover tareas existentes;
• completar, reactivar, cambiar el estado y mover proyectos existentes;
• previsualizar un cambio propuesto y verificar el resultado guardado.

La versión actual actualiza tareas y proyectos existentes. No se admite la creación o eliminación de elementos; la creación se sigue en #82 y #83.

¿Por qué FocusRelay?

En la rama de desarrollo, las preguntas de Forecast admiten un ámbito parcial explícito solo de tareas. Incluye acciones programadas pasadas/de hoy, marcadores y la etiqueta de Forecast configurada; no es el total nativo de Forecast y excluye eventos de calendario y preferencias de visibilidad nativas. Esto requiere el binario y el puente de desarrollo correspondientes, no la versión actual de Homebrew.

Mantén al asistente enfocado

FocusRelay expone nueve herramientas orientadas al modelo: siete herramientas de lectura más edit_tasks y edit_projects para cambios compatibles. Combinar siete herramientas de edición en dos redujo el catálogo completo de 14 herramientas a 9 y redujo el uso de contexto en un 7–13 % en pruebas controladas con modelos, dejando más espacio para el trabajo real del usuario. Los diagnósticos internos permanecen en la CLI, los comandos de recuento evitan devolver listas largas de elementos y la selección de campos mantiene las respuestas compactas.

Velocidad nativa de Swift a escala de biblioteca real

FocusRelay está compilado como Swift nativo e instalado con Homebrew, sin runtime de Node.js ni Python en la ruta de solicitud. El filtrado de una sola pasada y la paginación con detención temprana mantienen las lecturas enfocadas de la bandeja de entrada cerca de un segundo en pruebas a escala de miles de tareas. El mismo núcleo impulsa una CLI para consultas precisas y de bajo contexto.

Ejecútalo donde OmniFocus entiende sus datos

El servidor Swift envía el trabajo a un complemento puente ligero que se ejecuta dentro del contexto de Omni Automation de OmniFocus. Usa APIs documentadas y estados nativos, manteniendo los resultados alineados con OmniFocus sin leer su base de datos privada.

Haz cambios que puedas comprobar

Las herramientas de edición apuntan a IDs estables y admiten vistas previas, resultados por elemento, campos de retorno compactos y verificación opcional. Un guardado, actualización o verificación fallidos se informan como fallo, no como éxito.

FocusRelay gestiona el trabajo de OmniFocus en orden, indica a los asistentes que esperen cada actualización e informa de sobrecarga con claridad en lugar de dejar que las solicitudes colisionen. Cuando un cliente MCP se desconecta, su proceso de FocusRelay sale limpiamente en lugar de permanecer en segundo plano.

Consulta las notas de la última versión para conocer los cambios visibles para el usuario y los requisitos de actualización.

Privacidad y seguridad

FocusRelay se ejecuta localmente en tu Mac. Su servidor Swift se comunica en el dispositivo con un complemento puente que accede a OmniFocus mediante APIs documentadas. FocusRelay no tiene un servicio en la nube alojado y no envía tus datos de OmniFocus a un servicio operado por FocusRelay.

Tu cliente MCP y el modelo de IA elegido pueden transmitir entradas y resultados de herramientas bajo sus propios términos de privacidad. Revisa esos ajustes antes de usar FocusRelay con datos sensibles.

Instala el servidor MCP de OmniFocus con Homebrew

Requisitos:

• macOS 26 o posterior en Apple silicon;
• OmniFocus 4;
• Homebrew;
• un asistente compatible con MCP o un agente de IA con capacidad de shell.

1. Instala y confía en la fórmula

Homebrew 6 requiere confianza explícita para fórmulas de taps no oficiales. Confía solo en la fórmula de FocusRelay y luego instálala:

brew tap deverman/focus-relay
brew trust --formula deverman/focus-relay/focusrelay
brew install focusrelay

La confianza específica de la fórmula autoriza FocusRelay sin confiar en todas las fórmulas actuales o futuras del tap. Consulta la documentación de Tap Trust de Homebrew para más detalles.

2. Ejecuta la configuración guiada

Ejecuta el comando de configuración instalado:

focusrelay setup

Encuentra el complemento incluido con Homebrew, verifica que su versión coincida con el binario, detecta todas las carpetas de complementos de OmniFocus compatibles y muestra una vista previa del origen y los destinos antes de pedir permiso para copiar nada. Los complementos existentes permanecen en su lugar hasta que su reemplazo se haya copiado correctamente. Volver a ejecutar la configuración informa de las copias que ya están actualizadas.

La configuración también imprime el comando y los argumentos MCP neutrales para el cliente. Añade --client claude-code, --client codex o --client opencode para un ejemplo de cliente conocido; FocusRelay imprime la configuración pero no la edita.

Para automatización, revisa primero el mismo plan y luego opta explícitamente:

focusrelay setup --dry-run
focusrelay setup --non-interactive

¿Compilas desde el código fuente? Continúa usando ./scripts/install-plugin.sh; es un punto de entrada de desarrollo ligero para esta misma implementación de configuración en Swift.

3. Reinicia OmniFocus

Sal de OmniFocus por completo y vuelve a abrirlo para que se cargue el complemento actualizado:

osascript -e 'tell application "OmniFocus" to quit'
sleep 2
open -a "OmniFocus"

4. Comprueba la preparación y añade FocusRelay a tu asistente de IA

FocusRelay admite actualmente clientes MCP basados en terminal: Claude Code, OpenCode, Codex CLI y otros clientes lanzados desde una terminal. Las aplicaciones de escritorio como Claude Desktop y la aplicación de escritorio de ChatGPT aún no son compatibles: macOS restringe su acceso a los datos de OmniFocus de los que depende FocusRelay. El soporte para aplicaciones de escritorio se sigue en #196.

Configura un servidor MCP stdio local con:

• comando: /opt/homebrew/bin/focusrelay
• argumentos: serve

claude mcp add --scope user focusrelay -- /opt/homebrew/bin/focusrelay serve

claude mcp list

{
  "mcp": {
    "focusrelay": {
      "type": "local",
      "command": ["/opt/homebrew/bin/focusrelay", "serve"],
      "enabled": true
    }
  }
}

En la primera consulta, OmniFocus pregunta si se permite la automatización. Elige Run Script. Si la indicación está oculta, trae OmniFocus al frente.

Después de reiniciar OmniFocus, verifica que el complemento cargado coincida con el binario:

focusrelay setup --check-readiness
focusrelay list-tasks --fields id,name --limit 1

Luego pregunta:

¿Cuántos elementos marcados tengo en OmniFocus?

git clone https://github.com/deverman/FocusRelayMCP.git
cd FocusRelayMCP
swift build -c release
./scripts/install-plugin.sh

Usa FocusRelay como servidor MCP de OmniFocus o CLI

MCP permite que los asistentes compatibles descubran FocusRelay y elijan la acción correcta. La CLI es útil para scripts, depuración y agentes que ya tienen acceso al shell.

Los ejemplos a continuación apuntan a la versión actual de Homebrew y a la compilación desde el código fuente.

# Discover or retrieve the same workflows exposed as MCP prompts
focusrelay workflow list
focusrelay workflow get process_inbox

# Count without returning every matching task
focusrelay task-counts --flagged true

# Return only three task names
focusrelay list-tasks \
  --inbox-only true \
  --available-only true \
  --limit 3 \
  --fields name

# Preview a change without touching OmniFocus
focusrelay edit-tasks <task-id> \
  --operation update \
  --flagged true \
  --preview-only \
  --return-fields id,name,flagged

Ejecuta focusrelay --help para ver la lista de comandos. Para ejemplos de escritura y reglas de seguridad, consulta Safe Update Workflows for CLI and MCP.

Compara FocusRelay con otros servidores MCP de OmniFocus

FocusRelay combina un servidor Swift nativo con un complemento puente que se ejecuta dentro de OmniFocus. Swift mantiene MCP rápido y compacto; el puente obtiene datos frescos y aplica cambios mediante las APIs documentadas de OmniFocus.

✅ Disponible · 🟡 Próximamente · 🟠 Pendiente · ◇ Hoja de ruta del proyecto · — No documentado actualmente

Esta comparación refleja la documentación pública de cada proyecto al 15 de julio de 2026; «No documentado» no es una afirmación de que una función sea imposible. Los otros README públicos no describen un contrato equivalente de vista previa por destino y verificación posterior al guardado.

La vista previa resuelve IDs y valida el cambio sin guardarlo. La verificación se ejecuta después de que OmniFocus guarda, lee los valores afectados e informa de una discrepancia como fallo. Estos son argumentos de herramientas MCP, por lo que Codex, Claude Code, OpenCode y otros clientes MCP stdio estándar pueden usarlos; si un modelo los elige sin que se le pida depende del modelo y del cliente. Para cambios importantes, pídele que «previsualice primero y luego aplique con verificación».

Ayuda a dar forma a FocusRelay

Consulta GitHub Issues para ver el trabajo planificado. Si FocusRelay se gana un lugar en tu flujo de trabajo, destaca el repositorio para que más usuarios de OmniFocus puedan encontrarlo. ¿Quieres ayudar? Elige un issue, propón un caso de uso o abre un pull request enfocado. Consulta CONTRIBUTING.md para comenzar.

Solución de problemas

El puente se agota (timeout)

1. Trae OmniFocus al frente y acepta el primer mensaje de Run Script.
2. Confirma que FocusRelay Bridge está habilitado en Automation → Configure Plug-ins….
3. Ejecuta focusrelay setup, cierra OmniFocus por completo y vuelve a abrirlo.
4. Ejecuta focusrelay setup --check-readiness.

Los resultados parecen desactualizados después de una actualización

El JavaScript del plugin está en caché por OmniFocus. Ejecuta focusrelay setup, reinicia OmniFocus por completo y verifica con focusrelay setup --check-readiness. Los catálogos de proyectos y etiquetas se almacenan en caché durante cinco minutos; las consultas de tareas siempre están actualizadas.

Las versiones del plugin y del binario no coinciden

Actualizar la fórmula de Homebrew reemplaza el binario pero deja intactas las copias del plugin ya instaladas para OmniFocus, por lo que omitir el paso 2 puede dejar el plugin muchas versiones atrás.

Ejecuta nuevamente la configuración guiada, reinicia OmniFocus y verifica la versión cargada:

focusrelay setup
# Fully restart OmniFocus
focusrelay setup --check-readiness

La configuración verifica que cada copia esperada—incluida la ubicación preferida de iCloud cuando la sincronización de plugins está habilitada—esté disponible antes de cambiar archivos, y conserva cada copia existente hasta que su reemplazo haya sido copiado y verificado. Actualiza los destinos uno a la vez, por lo que si un destino posterior falla, uno anterior puede que ya haya sido actualizado. Corrige el problema reportado y vuelve a ejecutar la configuración antes de reiniciar OmniFocus. Un resultado de preparación saludable significa que el plugin cargado, cada copia instalada y el binario coinciden.

Un resultado basado en el tiempo parece incorrecto después de viajar

Reinicia el cliente MCP y OmniFocus para que FocusRelay detecte la zona horaria actual de macOS.

Desarrollo

swift build
swift test

FocusRelay usa Swift Testing del toolchain de Swift. Los cambios en consultas de producción deben seguir el contrato de Omni Automation documentado.

Licencia

FocusRelay está disponible bajo la Licencia MIT.