FocusRelay

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

Planeje seu dia e mantenha o OmniFocus atualizado com IA

FocusRelay é um servidor MCP e CLI nativo em Swift, rápido, que ajuda assistentes de IA a ler e atualizar com segurança o OmniFocus usando APIs documentadas do OmniFocus.

Instalar com Homebrew · Veja o que ele pode fazer · Adicione uma estrela ao FocusRelay · Contribua

Pergunte sobre o trabalho já existente no OmniFocus, revise a resposta e faça alterações aprovadas sem precisar clicar em longas listas de tarefas.

Pergunte. Revise. Atualize.

O FocusRelay foi projetado para perguntas direcionadas e respostas compactas, para que o assistente não precise de todo o seu banco de dados do OmniFocus para solicitações rotineiras.

Experimente prompts como:

• "Ajude-me a processar minha caixa de entrada do OmniFocus em um pequeno lote."
• "Quantos itens sinalizados eu tenho?"
• "Mostre-me as três primeiras tarefas disponíveis na minha caixa de entrada."
• "Encontre minha tarefa chamada [nome da tarefa], sinalize-a e verifique a alteração."
• "Defina [nome da tarefa] como vencendo amanhã às 17h no meu fuso horário local e verifique a alteração."

Em clientes que expõem prompts de servidor MCP, selecione process_inbox. No OpenCode, execute /focusrelay:process_inbox para iniciar o fluxo de trabalho guiado. Agentes baseados em CLI podem recuperar exatamente as mesmas instruções com focusrelay workflow get process_inbox; use focusrelay workflow list para descobrir fluxos de trabalho disponíveis sem carregar o texto completo.

Esses fluxos de trabalho foram testados com vários modelos compatíveis com MCP no OpenCode. As atualizações visam IDs estáveis do OmniFocus e podem verificar o resultado salvo. Se os nomes estiverem duplicados, peça para ver os candidatos antes de alterar qualquer coisa.

A versão atual pode:

• guiar clientes MCP compatíveis e agentes baseados em CLI por um fluxo de trabalho de caixa de entrada limitado e com aprovação prévia;
• encontrar e contar tarefas usando datas, sinalizações, tags, projetos, disponibilidade, estado da caixa de entrada, conclusão, estimativas e pesquisa de texto;
• revisar projetos, pastas, tags, contagens de tarefas e trabalhos parados;
• atualizar nomes, notas, sinalizações, datas, estimativas, tags, configurações de projeto e intervalos de revisão;
• marcar projetos ativos e em espera como revisados usando o carimbo de data/hora de revisão nativo e a semântica de próxima revisão do OmniFocus;
• descartar, restaurar, concluir, reativar e mover tarefas existentes;
• concluir, reativar, alterar o status e mover projetos existentes;
• visualizar uma alteração proposta e verificar o resultado salvo.

A versão atual atualiza tarefas e projetos existentes. Criar ou excluir itens não é suportado; a criação é rastreada em #82 e #83.

Por que FocusRelay?

No branch de desenvolvimento, as perguntas do Forecast suportam um escopo parcial explícito apenas de tarefas. Ele inclui ações agendadas passadas/hoje, sinalizações e a tag Forecast configurada; não é o total nativo do Forecast e exclui eventos de calendário e preferências de visibilidade nativas. Isso requer o binário e a ponte de desenvolvimento correspondentes, não a versão atual do Homebrew.

Mantenha o assistente focado

O FocusRelay expõe nove ferramentas voltadas ao modelo: sete ferramentas de leitura mais edit_tasks e edit_projects para alterações suportadas. Combinar sete ferramentas de edição em duas reduziu o catálogo completo de 14 ferramentas para 9 e reduziu o uso de contexto em 7–13% em testes controlados de modelo, deixando mais espaço para o trabalho real do usuário. Diagnósticos internos permanecem no CLI, comandos de contagem evitam retornar longas listas de itens, e a seleção de campos mantém as respostas compactas.

Velocidade nativa Swift em escala de biblioteca real

O FocusRelay é compilado como Swift nativo e instalado com Homebrew, sem runtime Node.js ou Python no caminho da solicitação. Filtragem de passagem única e paginação com parada antecipada mantêm leituras focadas da caixa de entrada perto de um segundo em testes com escala de milhares de tarefas. O mesmo núcleo alimenta um CLI para consultas precisas e de baixo contexto.

Execute onde o OmniFocus entende seus dados

O servidor Swift despacha o trabalho para um plug-in de ponte leve que é executado dentro do contexto Omni Automation do OmniFocus. Ele usa APIs documentadas e status nativos, mantendo os resultados alinhados com o OmniFocus sem ler seu banco de dados privado.

Faça alterações que você pode verificar

As ferramentas de edição visam IDs estáveis e suportam visualização, resultados por item, campos de retorno compactos e verificação opcional. Uma falha ao salvar, atualizar ou verificar é relatada como falha—não sucesso.

O FocusRelay lida com o trabalho do OmniFocus em ordem, diz aos assistentes para aguardar cada atualização e relata sobrecarga claramente em vez de deixar as solicitações colidirem. Quando um cliente MCP se desconecta, seu processo FocusRelay sai limpo em vez de permanecer em segundo plano.

Veja as notas de versão mais recentes para as mudanças voltadas ao usuário e requisitos de atualização.

Privacidade e segurança

O FocusRelay é executado localmente no seu Mac. Seu servidor Swift se comunica no dispositivo com um plug-in de ponte que acessa o OmniFocus por meio de APIs documentadas. O FocusRelay não tem serviço de nuvem hospedado e não envia seus dados do OmniFocus para um serviço operado pela FocusRelay.

Seu cliente MCP e o modelo de IA escolhido podem transmitir entradas e resultados de ferramentas sob seus próprios termos de privacidade. Revise essas configurações antes de usar o FocusRelay com dados confidenciais.

Instale o servidor MCP do OmniFocus com Homebrew

Requisitos:

• macOS 26 ou posterior em Apple silicon;
• OmniFocus 4;
• Homebrew;
• um assistente compatível com MCP ou um agente de IA com capacidade de shell.

1. Instale e confie na fórmula

O Homebrew 6 exige confiança explícita para fórmulas de taps não oficiais. Confie apenas na fórmula FocusRelay e depois instale-a:

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

A confiança específica da fórmula autoriza o FocusRelay sem confiar em todas as fórmulas atuais ou futuras no tap. Consulte a documentação de Confiança de Tap do Homebrew para obter detalhes.

2. Execute a configuração guiada

Execute o comando de configuração instalado:

focusrelay setup

Ele encontra o plug-in incluído no Homebrew, verifica se a versão corresponde ao binário, detecta todas as pastas de plug-in do OmniFocus suportadas e visualiza a origem e os destinos antes de pedir permissão para copiar qualquer coisa. Plug-ins existentes permanecem no lugar até que sua substituição seja copiada com sucesso. Executar a configuração novamente relata cópias que já estão atualizadas.

A configuração também imprime o comando e os argumentos MCP neutros do cliente. Adicione --client claude-code, --client codex ou --client opencode para um exemplo de cliente conhecido; o FocusRelay imprime a configuração, mas não a edita.

Para automação, revise o mesmo plano primeiro e depois opte explicitamente:

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

Compilando a partir do código-fonte? Continue usando ./scripts/install-plugin.sh; é um ponto de entrada de desenvolvimento enxuto para esta mesma implementação de configuração Swift.

3. Reinicie o OmniFocus

Saia completamente do OmniFocus e reabra-o para que o plug-in atualizado seja carregado:

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

4. Verifique a prontidão e adicione o FocusRelay ao seu assistente de IA

O FocusRelay atualmente suporta clientes MCP baseados em terminal: Claude Code, OpenCode, Codex CLI e outros clientes iniciados a partir de um terminal. Aplicativos de desktop, como Claude Desktop e o aplicativo de desktop do ChatGPT, ainda não são suportados: o macOS restringe seu acesso aos dados do OmniFocus dos quais o FocusRelay depende. O suporte a aplicativos de desktop é rastreado em #196.

Configure um servidor MCP stdio local com:

• 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
    }
  }
}

Na primeira consulta, o OmniFocus pergunta se deseja permitir a automação. Escolha Executar Script. Se o prompt estiver oculto, traga o OmniFocus para a frente.

Após reiniciar o OmniFocus, verifique se o plug-in carregado corresponde ao binário:

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

Então pergunte:

Quantos itens sinalizados eu tenho no OmniFocus?

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

Use o FocusRelay como servidor MCP do OmniFocus ou CLI

O MCP permite que assistentes compatíveis descubram o FocusRelay e escolham a ação certa. O CLI é útil para scripts, depuração e agentes que já têm acesso ao shell.

Os exemplos abaixo visam a versão atual do Homebrew e a compilação do código-fonte.

# 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

Execute focusrelay --help para a lista de comandos. Para exemplos de escrita e regras de segurança, consulte Fluxos de Trabalho de Atualização Segura para CLI e MCP.

Compare o FocusRelay com outros servidores MCP do OmniFocus

O FocusRelay combina um servidor Swift nativo com um plug-in de ponte que executa dentro do OmniFocus. O Swift mantém o MCP rápido e compacto; a ponte obtém dados atualizados e aplica alterações por meio de APIs documentadas do OmniFocus.

✅ Disponível · 🟡 Próximo · 🟠 Backlog · ◇ Roadmap do projeto · — Não documentado atualmente

Esta comparação reflete a documentação pública de cada projeto em 15 de julho de 2026; "Não documentado" não é uma afirmação de que um recurso é impossível. Os outros READMEs públicos não descrevem um contrato equivalente de visualização por destino e verificação pós-salvamento.

A visualização resolve IDs e valida a alteração sem salvá-la. A verificação é executada após o OmniFocus salvar, lê os valores afetados de volta e relata uma incompatibilidade como falha. Esses são argumentos de ferramenta MCP, portanto, Codex, Claude Code, OpenCode e outros clientes MCP stdio padrão podem usá-los; se um modelo os escolhe sem ser solicitado depende do modelo e do cliente. Para alterações importantes, peça para "visualizar primeiro, depois aplicar com verificação."

Ajude a moldar o FocusRelay

Veja GitHub Issues para o trabalho planejado. Se o FocusRelay ganhar um lugar no seu fluxo de trabalho, adicione uma estrela ao repositório para que mais usuários do OmniFocus possam encontrá-lo. Quer ajudar? Escolha uma issue, proponha um caso de uso ou abra um pull request focado. Veja CONTRIBUTING.md para começar.

Solução de problemas

A ponte expira

1. Traga o OmniFocus para a frente e aceite o primeiro prompt Run Script.
2. Confirme que o FocusRelay Bridge está habilitado em Automation → Configure Plug-ins….
3. Execute focusrelay setup, saia completamente do OmniFocus e reabra-o.
4. Execute focusrelay setup --check-readiness.

Os resultados parecem desatualizados após uma atualização

O JavaScript do plugin é armazenado em cache pelo OmniFocus. Execute focusrelay setup, reinicie o OmniFocus completamente e verifique com focusrelay setup --check-readiness. Os catálogos de projetos e tags ficam em cache por cinco minutos; as consultas de tarefas estão sempre atualizadas.

As versões do plugin e do binário não correspondem

Atualizar a fórmula do Homebrew substitui o binário, mas deixa as cópias do plugin já instaladas para o OmniFocus intactas, então uma etapa 2 pulada pode deixar o plugin muitas versões atrás.

Execute a configuração guiada novamente, reinicie o OmniFocus e verifique a versão carregada:

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

A configuração verifica se cada cópia esperada—incluindo o local preferido do iCloud quando a sincronização de plug-ins está habilitada—está disponível antes de alterar arquivos, e preserva cada cópia existente até que sua substituição tenha sido copiada e verificada. Ela atualiza os destinos um de cada vez, então se um destino posterior falhar, um anterior pode já ter sido atualizado. Corrija o problema relatado e execute a configuração novamente antes de reiniciar o OmniFocus. Um resultado de prontidão saudável significa que o plug-in carregado, cada cópia instalada e o binário estão em concordância.

Um resultado baseado em tempo parece errado após viajar

Reinicie o cliente MCP e o OmniFocus para que o FocusRelay detecte o fuso horário atual do macOS.

Desenvolvimento

swift build
swift test

O FocusRelay usa Swift Testing do kit de ferramentas Swift. Alterações de consulta de produção devem seguir o contrato Omni Automation documentado.

Licença

O FocusRelay está disponível sob a Licença MIT.