OmniFocus

Um servidor MCP profissional para OmniFocus com cache inteligente e análises para gerenciar tarefas e projetos.

GitHub
15
Experimente este MCPPatrocinado

Documentação

Protocolo de Contexto do Modelo para OmniFocus (incluindo recursos avançados)

Aviso: desculpe a rigidez da documentação e a linguagem dos commits; o projeto é totalmente codificado via Claude Code, então muitas mensagens são tão divertidas quanto um relatório contábil (com ênfase aleatória de um vendedor de carros aqui e ali).

Um servidor profissional de Protocolo de Contexto do Modelo (MCP) para OmniFocus que fornece recursos avançados de gerenciamento de tarefas com cache inteligente e análises. Construído com TypeScript e total respeito à API oficial OmniAutomation do OmniFocus.

Recursos

Capacidades Principais

  • Cache Inteligente: sistema de cache baseado em TTL para desempenho ideal
  • Segurança de Tipos: suporte completo a TypeScript com tipos abrangentes
  • Somente API Oficial: usa apenas scripts OmniAutomation (sem invasão de banco de dados)
  • Alto Desempenho: lida com mais de 1000 tarefas com eficiência usando cache inteligente

Ferramentas Disponíveis

Operações de Tarefas (Leitura)

  • list_tasks - Filtragem avançada de tarefas com cache inteligente
    • Filtrar por: status de conclusão, sinalizadores, projeto, tags, datas, termos de pesquisa
    • Suporta filtragem de caixa de entrada e verificações de disponibilidade
    • Suporta até 1000 tarefas com metadados de paginação adequados
    • Resultados armazenados em cache por 30 segundos para consultas repetidas extremamente rápidas
  • get_task_count - Obter contagem de tarefas que correspondem aos filtros sem dados
    • Mesmas opções de filtragem do list_tasks
    • Retorna apenas a contagem para desempenho

Operações de Tarefas (Escrita)

  • create_task - Criar novas tarefas na caixa de entrada
    • Definir nome, nota, status de sinalização, datas de vencimento/adiamento
    • Atribuição de tags limitada a tags existentes
    • Retorna ID temporário (limitação do JXA)
  • update_task - Atualizar tarefas existentes
    • Modificar nome, nota, status de sinalização, datas
    • Gerenciamento limitado de tags devido ao JXA
  • complete_task - Marcar tarefas como concluídas
  • delete_task - Remover tarefas

Operações de Projetos

  • list_projects - Listar e filtrar projetos com cache
    • Filtrar por: status (ativo, em espera, arquivado, concluído), sinalizadores, pasta
    • Resultados armazenados em cache por 5 minutos
  • create_project - Criar novos projetos com suporte a pastas
    • Cria pastas automaticamente se não existirem
    • Definir nome, nota, datas, sinalizadores e pasta pai
  • update_project - Atualizar propriedades do projeto
    • Alterar nome, nota, status, datas, sinalizadores
    • Movimentação de pastas suportada com limitações (restrição do JXA)
  • complete_project - Marcar projetos como concluídos
  • delete_project - Remover projetos do OmniFocus

Em Breve

  • Ferramentas de análise (estatísticas de produtividade, rastreamento de velocidade, análise de atrasos)
  • Gerenciamento de tags
  • Operações em lote
  • Pesquisa inteligente com linguagem natural
  • Análise de tarefas recorrentes

Instalação e Permissões

Pré-requisitos

  1. OmniFocus 3 ou posterior instalado no macOS
  2. Node.js 18+ instalado
  3. Permissão para acessar o OmniFocus via automação (consulte o Guia de Permissões)

Etapas de Instalação

# 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

Concessão de Permissões

Na primeira vez que você usar o servidor MCP, o macOS solicitará permissão para acessar o OmniFocus. Consulte o Guia de Permissões para instruções detalhadas.

Configuração

Configuração do Claude Desktop

Adicione ao seu arquivo de configuração do 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"
      }
    }
  }
}

Variáveis de Ambiente

  • LOG_LEVEL - Define o nível de registro: error, warn, info, debug (padrão: info)

Exemplos de Uso

Listar Todas as Tarefas Incompletas

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

Criar uma Nova Tarefa com Atribuição de Projeto

// 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 uma Tarefa Entre Projetos

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

Encontrar Tarefas Atrasadas

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

Listar Projetos Ativos

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

Criar um Projeto com Pasta

{
  "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
  }
}

Atualizar Projeto (Incluindo Pasta)

// 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"
    }
  }
}

Solução de Problemas

Erros de "Projeto não encontrado" com IDs Numéricos

Se você vir erros como Project with ID '547' not found seguidos de um aviso de bug do Claude Desktop:

  1. Use list_projects para obter o ID completo correto do projeto:

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

  2. Copie o ID alfanumérico completo (por exemplo, "az5Ieo4ip7K") dos resultados

  3. Use nomes de projetos como alternativa:

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

    Em seguida, atribua manualmente no OmniFocus, ou use nomes de projetos nos filtros de pesquisa.

Falhas na Atualização de Tarefas

  • Sempre obtenha IDs de tarefas de list_tasks em vez de adivinhar
  • Use list_projects para verificar IDs de projetos antes da atribuição
  • Verifique se as tarefas existem e não estão na lixeira

Arquitetura

Estratégia de Cache

O servidor implementa cache inteligente com diferentes TTLs para diferentes tipos de dados:

  • Tarefas: 30 segundos (mudam com frequência)
  • Projetos: 5 minutos (menos voláteis)
  • Análises: 1 hora (cálculos caros)
  • Tags: 10 minutos (relativamente estáveis)

O cache é invalidado automaticamente em operações de escrita.

Integração OmniAutomation

Todas as interações com o OmniFocus usam JavaScript para Automação (JXA) através do OmniAutomation:

  • Scripts são encapsulados para tratamento de erros
  • Parâmetros são escapados com segurança
  • Resultados são tipados e validados
  • Operações em lote são suportadas

Tratamento de Erros

O servidor fornece mensagens de erro detalhadas com:

  • Tipos de erro específicos (NotFound, Permission, execução de script)
  • Informações contextuais para depuração
  • Degradação graciosa quando possível

Desenvolvimento

Pré-requisitos

  • Node.js 18+
  • OmniFocus 3+ (Pro recomendado)
  • macOS (necessário 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

Estrutura do Projeto

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

Desempenho

  • Lida com mais de 1000 tarefas com tempos de resposta abaixo de um segundo
  • Cache inteligente reduz chamadas à API do OmniFocus em mais de 80%
  • Execução concorrente de scripts para operações em lote
  • Eficiente em memória com limpeza automática de cache

Segurança

  • Sem acesso direto ao banco de dados
  • Parâmetros são sanitizados antes da execução do script
  • Operações somente leitura por padrão
  • Nenhum dado sensível é registrado

Contribuindo

  1. Faça um fork do repositório
  2. Crie um branch de recurso
  3. Adicione testes para novas funcionalidades
  4. Garanta que todos os testes passem
  5. Envie um pull request

Melhorias Futuras

Recomendações de Alta Prioridade

  1. Corrigir Suíte de Testes Unitários: Vários testes unitários estão falhando devido a suposições incorretas sobre o código. Áreas prioritárias:

    • Atualizar expectativas de teste para corresponder aos formatos reais de resposta da API
    • Alinhar objetos mock com interfaces reais de implementação
    • Remover testes que verificam comportamento incorreto (por exemplo, esperar que primaryKey seja um método quando é uma propriedade)

  2. Adicionar Configuração ESLint: O projeto está sem um arquivo de configuração ESLint, o que impede a execução do linting. Crie um eslint.config.js que suporte TypeScript e siga os padrões de codificação do projeto.

  3. Melhorar Recuperação de Erros: Embora o fallback do esquema de URL para erros de permissão negada seja um bom começo, considere:

    • Implementar lógica de nova tentativa com backoff exponencial
    • Adicionar mensagens de erro amigáveis que sugiram soluções
    • Criar uma ferramenta de diagnóstico para ajudar usuários a solucionar problemas de permissão

Licença

Licença MIT - consulte o arquivo LICENSE para detalhes

Testes

Testes de Ponta a Ponta com Claude Desktop

Para testar o sistema de permissões com o Claude Desktop:

  1. Revogar Permissões (para testar o tratamento de erros):

    • Abra Ajustes do Sistema → Privacidade e Segurança → Automação
    • Encontre "Claude" (ou "Electron" se o Claude não estiver listado)
    • Desmarque a caixa ao lado de "OmniFocus"

  2. Teste no Claude Desktop:

    • Pergunte ao Claude: "Você pode listar minhas tarefas do OmniFocus?"
    • Você deve ver uma mensagem de erro útil com instruções para conceder permissões

  3. Conceder Permissões:

    • Clique em "OK" quando a caixa de diálogo de permissão aparecer
    • Ou habilite manualmente em Ajustes do Sistema conforme instruído

  4. Verificar Sucesso:

    • Pergunte ao Claude novamente para listar suas tarefas
    • As tarefas devem agora ser exibidas corretamente

Testes Durante o Desenvolvimento

# 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

Bug de Análise de ID do Claude Desktop

PROBLEMA CRÍTICO: O Claude Desktop tem um bug confirmado onde extrai partes numéricas de IDs alfanuméricos de projetos ao chamar ferramentas MCP.

Exemplo: Quando você fornece o ID do projeto "az5Ieo4ip7K", o Claude Desktop pode passar apenas "547" para a ferramenta, causando erros de "Projeto não encontrado".

Sintomas:

  • Atualizações de tarefas falham com erros de "Projeto não encontrado"
  • Mensagens de erro mostram IDs numéricos (como "547") em vez de IDs alfanuméricos completos
  • Ocorre mesmo quando IDs completos de projetos são fornecidos nos prompts

Mitigação:

  • Nossas mensagens de erro agora detectam esse padrão e fornecem orientação útil
  • Descrições de ferramentas alertam sobre o uso de IDs alfanuméricos completos
  • Considere usar nomes de projetos em vez de IDs quando esse bug afetar seu fluxo de trabalho

Problemas Relacionados: Isso faz parte de bugs mais amplos de processamento de parâmetros do Claude Desktop documentados em issues do GitHub, incluindo falhas de conversão de tipos e erros de análise JSON.

Requisito de Módulos ES

Este projeto usa módulos ES (ESM) com extensões .js em declarações de importação, o que pode parecer incomum para projetos TypeScript. Isso é necessário porque:

  1. O SDK MCP (@modelcontextprotocol/sdk) é atualmente somente ESM
  2. Existem problemas conhecidos de compatibilidade com CommonJS (consulte GitHub issue #217)

Migração Futura: Quando o SDK MCP adicionar suporte adequado a CommonJS, este projeto deve migrar para TypeScript/CommonJS padrão para remover a necessidade de extensões .js nos imports.

Agradecimentos

Construído com: