Things 3

Gerencie suas tarefas e projetos no Things 3 no macOS.

GitHubExperimente este MCPPatrocinado

Documentação

Servidor MCP Things 3 (Ruby)

Um servidor abrangente do Model Context Protocol (MCP) para gerenciamento de tarefas no Things 3 para macOS. Este servidor fornece gerenciamento de tarefas em linguagem natural, filtragem avançada, operações em lote, análises e ferramentas de manutenção por meio da integração com AppleScript.

Somente macOS: Este servidor MCP requer macOS e Things 3 (que é exclusivo do macOS).

🏗️ Arquitetura

O código está organizado em classes focadas com clara separação de responsabilidades:

  • Things3MCPServer - Implementação principal do servidor MCP
  • AppleScriptExecutor - Executa AppleScript com tratamento de erros
  • AppleScriptGenerator - Gera código AppleScript para operações do Things 3
  • Things3Client - Operações principais de tarefas do Things 3 (CRUD)
  • DateParser - Análise de datas em linguagem natural usando a gem Chronic
  • TaskFilter - Filtragem avançada e recursos de busca de tarefas
  • BulkOperations - Operações em lote de tarefas (criar, atualizar, mover, concluir, importar)
  • ReportGenerator - Revisões semanais, relatórios de projetos e análises

🚀 Recursos

Gerenciamento Principal de Tarefas

  • Operações CRUD: Criar, ler, atualizar, excluir tarefas
  • Datas em Linguagem Natural: "amanhã", "próxima sexta-feira", "em 3 dias", etc.
  • Organização Inteligente: Atribuição de projeto/área com criação automática
  • Busca Avançada: Filtragem por múltiplos critérios com suporte a regex

Filtragem Avançada

  • Filtros Complexos: Status, projetos, áreas, tags, datas, notas
  • Filtros Rápidos: Filtros pré-configurados para cenários comuns
  • Filtros Salvos: Armazene e reutilize combinações complexas de filtros
  • Busca de Texto: Busca no nome e conteúdo das notas com regex

Operações em Lote

  • Criação em Massa: Crie múltiplas tarefas a partir de listas ou modelos
  • Atualizações em Lote: Atualize tarefas que correspondam a critérios específicos
  • Operações com Tags: Adicione, remova, padronize tags entre tarefas
  • Importação/Exportação: Suporte a importação de CSV, JSON e texto simples

Análises e Relatórios

  • Revisões Semanais: Geração abrangente de revisões
  • Saúde do Projeto: Analise o progresso e gargalos dos projetos
  • Insights de Produtividade: Padrões e tendências de conclusão
  • Ferramentas de Planejamento: Planejamento da próxima semana com agendamento baseado em energia

Manutenção de Dados

  • Detecção de Duplicatas: Encontre e mescle tarefas semelhantes
  • Limpeza de Tarefas Órfãs: Organize tarefas sem projetos/áreas
  • Padronização de Tags: Limpe nomes de tags inconsistentes
  • Saúde do Sistema: Pontuação de organização e métricas de saúde

📋 Requisitos

  • macOS: Obrigatório (Things 3 é exclusivo do macOS)
  • Things 3: Deve estar instalado e em execução
  • Ruby: Versão 3.0.0 ou superior
  • Dependências: Gerenciadas via Bundler

Nota: Este servidor MCP só funciona no macOS, pois o Things 3 é um aplicativo exclusivo do macOS.

🔐 Configuração de Permissões do macOS

Este servidor MCP usa AppleScript para se comunicar com o Things 3, o que requer permissões específicas do macOS:

1. Permissões de Acessibilidade

Ao executar o servidor MCP pela primeira vez, o macOS solicitará permissões de acessibilidade:

  1. Preferências do Sistema → Segurança e Privacidade → Privacidade → Acessibilidade
  2. Clique no cadeado para fazer alterações (digite sua senha)
  3. Adicione seu cliente MCP (ex.: Claude Desktop, Cursor, Terminal)
  4. Marque a caixa de seleção para o aplicativo

2. Permissões de AppleScript

O servidor também pode precisar de permissões de AppleScript:

  1. Preferências do Sistema → Segurança e Privacidade → Privacidade → Automação
  2. Encontre seu cliente MCP na lista
  3. Ative "Things3" sob seu aplicativo cliente

3. Permissões do Terminal/Ruby (se executado diretamente)

Se você executar o servidor diretamente do Terminal:

  1. Preferências do Sistema → Segurança e Privacidade → Privacidade → Acessibilidade
  2. Adicione o Terminal (ou seu aplicativo de terminal)
  3. Marque a caixa de seleção

💡 Dica: Se você receber erros de "permissão negada", reinicie seu cliente MCP após conceder as permissões.

🛠 Instalação

  1. Clone o repositório:

    git clone https://github.com/mattsafaii/things3-mcp.git
cd things3-mcp

  2. Instale as dependências:

    bundle install

  3. Execute o servidor MCP:

    ./things3-mcp-server

  4. Configure no seu cliente MCP - Veja Configuração do Cliente MCP abaixo

🔌 Configuração do Cliente MCP

Claude Desktop

  1. Encontre seu arquivo de configuração:

    • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

  2. Adicione a configuração do servidor:

    {
  "mcpServers": {
    "things3": {
      "command": "/absolute/path/to/things3-mcp/things3-mcp-server",
      "args": []
    }
  }
}

  3. Reinicie o Claude Desktop - O servidor aparecerá nas suas ferramentas disponíveis

Cursor IDE

  1. Abra as Configurações do Cursor (Cmd + ,)

  2. Navegue até Extensões → MCP

  3. Adicione a configuração do servidor:

    {
  "name": "Things3",
  "command": "/absolute/path/to/things3-mcp/things3-mcp-server",
  "args": []
}

VS Code (com Extensão MCP)

  1. Instale uma extensão MCP do marketplace do VS Code

  2. Abra as Configurações do VS Code (Cmd + ,)

  3. Pesquise por "MCP" e adicione o servidor:

    {
  "mcp.servers": [
    {
      "name": "things3",
      "command": "/absolute/path/to/things3-mcp/things3-mcp-server",
      "args": []
    }
  ]
}

Editor Zed

  1. Abra as configurações do Zed (Cmd + ,)

  2. Adicione ao seu settings.json:

    {
  "language_models": {
    "mcp_servers": {
      "things3": {
        "command": "/absolute/path/to/things3-mcp/things3-mcp-server",
        "args": []
      }
    }
  }
}

Continue (Extensão do VS Code)

  1. Abra a configuração do Continue (.continue/config.json no seu espaço de trabalho)

  2. Adicione o servidor MCP:

    {
  "mcpServers": {
    "things3": {
      "command": "/absolute/path/to/things3-mcp/things3-mcp-server",
      "args": []
    }
  }
}

Cliente MCP Genérico

Para qualquer cliente MCP que suporte o padrão, use:

{
  "name": "things3",
  "command": "/absolute/path/to/things3-mcp/things3-mcp-server",
  "args": [],
  "env": {
    "PATH": "/usr/local/bin:/usr/bin:/bin"
  }
}

Dicas de Configuração

  1. Use caminhos absolutos - Caminhos relativos podem não funcionar em diferentes clientes
  2. Verifique as permissões - Garanta que o executável tenha as permissões adequadas (chmod +x)
  3. Teste o servidor - Execute ./things3-mcp-server manualmente para verificar se funciona
  4. Verifique os logs - A maioria dos clientes MCP fornece logs para depuração de problemas de conexão

Verificando a Instalação

Após a configuração, você deve ver estas ferramentas disponíveis no seu cliente MCP:

  • add_task, list_tasks, complete_task (operações principais)
  • weekly_review, project_status_report (análises)
  • bulk_create_tasks, filter_tasks (recursos avançados)
  • E mais de 30 outras ferramentas especializadas

Teste com um comando simples:

"Add a task called 'Test MCP integration' to my Things 3"

Se for bem-sucedido, você verá a tarefa aparecer no Things 3 e receberá uma mensagem de confirmação.

Primeira Execução: No primeiro uso, o macOS solicitará permissões (veja Configuração de Permissões do macOS). Conceda as permissões e reinicie seu cliente MCP.

🎯 Ferramentas Disponíveis

33 ferramentas abrangentes organizadas em categorias funcionais:

Operações Principais de Tarefas

  • add_task - Crie novas tarefas com metadados completos
  • list_tasks - Liste tarefas com opções de filtragem
  • list_projects - Liste todos os projetos e áreas
  • update_task - Modifique propriedades de tarefas existentes
  • complete_task - Marque tarefas como concluídas
  • delete_task - Remova tarefas do Things 3
  • move_task - Mova tarefas entre projetos/áreas
  • search_tasks - Busque nomes e conteúdos de tarefas

Recursos Avançados

  • add_task_with_planning_notes - Crie tarefas com metadados de planejamento
  • list_tasks_by_date_range - Filtre tarefas por intervalos de datas
  • snooze_task - Adie tarefas para datas futuras
  • parse_date - Teste a análise de datas em linguagem natural

Filtragem e Busca

  • filter_tasks - Filtragem avançada por múltiplos critérios
  • quick_filters - Filtros úteis pré-configurados (órfãs, atrasadas, etc.)
  • saved_filters - Gerencie configurações de filtros reutilizáveis

Análises e Relatórios

  • weekly_review - Gere revisões semanais abrangentes
  • project_status_report - Analise projetos ativos
  • productivity_insights - Acompanhe padrões de produtividade
  • next_week_planning - Planeje a próxima semana com níveis de energia
  • review_templates - Gerencie formatos de revisão consistentes

Operações em Lote

  • bulk_create_tasks - Crie múltiplas tarefas de uma vez
  • bulk_update_tasks - Atualize múltiplas tarefas correspondentes
  • bulk_move_tasks - Mova tarefas entre projetos
  • bulk_tag_operations - Gerenciamento em massa de tags
  • bulk_complete_tasks - Conclua múltiplas tarefas
  • bulk_import_tasks - Importe de formatos externos

Limpeza e Manutenção de Dados

  • cleanup_orphaned_tasks - Organize tarefas não atribuídas
  • find_duplicate_tasks - Detecte e mescle duplicatas
  • standardize_tags - Limpe a consistência de nomes de tags
  • cleanup_stale_tasks - Lide com tarefas antigas/abandonadas
  • analyze_project_health - Métricas de saúde do projeto
  • fix_broken_references - Repare problemas de integridade de dados
  • organization_score - Avaliação geral da saúde do sistema

Modelos e Automação

  • task_templates - Gerencie conjuntos de tarefas reutilizáveis

🔧 Configuração

Armazenamento de Filtros Salvos

Os filtros são salvos automaticamente em: ~/.things3_mcp_filters.json

Modo de Depuração

Ative o registro detalhado definindo sinalizadores de depuração nos construtores de classe ou por meio de variáveis de ambiente.

📖 Exemplos de Uso

Gerenciamento Básico de Tarefas

# Add simple task
add_task({"name": "Buy groceries"})

# Add task with project and due date
add_task({
  "name": "Finish quarterly report", 
  "project": "Work",
  "due_date": "next Friday",
  "tags": ["urgent", "quarterly"]
})

Datas em Linguagem Natural

# Various supported formats
add_task({"name": "Team meeting", "due_date": "tomorrow at 2pm"})
add_task({"name": "Vacation planning", "due_date": "end of month"})
add_task({"name": "Project review", "start_date": "next Monday", "due_date": "in 2 weeks"})

Filtragem Avançada

# Complex filter
filter_tasks({
  "status": ["open"],
  "project_names": ["Work", "Personal"],
  "tag_filter": {"has_tags": ["urgent"]},
  "date_filter": {"overdue": true}
})

# Quick filters
quick_filters({"filter_type": "orphaned_tasks"})

Fluxo de Trabalho de Revisão Semanal

# Generate comprehensive review
weekly_review({
  "review_type": "last_week",
  "include_sections": ["completed", "overdue", "upcoming", "projects", "insights"]
})

# Project health check
project_status_report({"include_metrics": true})

# Plan next week
next_week_planning({"include_energy_levels": true})

Operações em Lote

# Create multiple tasks
bulk_create_tasks({
  "tasks": [
    {"name": "Research competitors", "project": "Website"},
    {"name": "Design mockups", "project": "Website", "due_date": "Friday"},
    {"name": "Write content", "project": "Website"}
  ]
})

# Standardize tags
standardize_tags({
  "apply": true,
  "rules": {"lowercase": true, "merge_similar": true}
})

🛡️ Tratamento de Erros

  • Disponibilidade do Things 3: Valida se o Things 3 está em execução antes das operações
  • Erros de AppleScript: Captura abrangente de erros com mensagens descritivas
  • Análise de Datas: Tratamento gracioso de datas ambíguas com indicadores de confiança
  • Validação de Entrada: Validação de parâmetros com mensagens de erro úteis
  • Proteção contra Timeout: Timeout de 30 segundos em operações AppleScript

📁 Estrutura de Arquivos

things3-mcp/
├── things3-mcp-server            # Executable script (root level)
├── lib/
│   ├── things3_mcp.rb            # Main entry point
│   └── things3_mcp/
│       ├── server.rb             # MCP server implementation
│       ├── client.rb             # Core Things 3 operations
│       ├── date_parser.rb        # Natural language date parsing
│       ├── task_filter.rb        # Advanced task filtering
│       ├── bulk_operations.rb    # Bulk task operations
│       ├── report_generator.rb   # Analytics and reports
│       └── applescript/
│           ├── executor.rb       # AppleScript execution engine
│           └── generator.rb      # AppleScript code generation
├── Gemfile                       # Ruby dependencies
├── Gemfile.lock                  # Locked dependency versions

└── README.md                     # This documentation

🔍 Solução de Problemas

Problemas Comuns

Things 3 Não Está em Execução

Error: Things 3 is not available

Solução: Inicie o aplicativo Things 3

Permissão de AppleScript Negada

Error: AppleScript execution failed - permission denied

Soluções:

  • Conceda permissões de Acessibilidade: Preferências do Sistema → Segurança e Privacidade → Privacidade → Acessibilidade
  • Conceda permissões de Automação: Preferências do Sistema → Segurança e Privacidade → Privacidade → Automação
  • Adicione seu cliente MCP (Claude Desktop, Cursor, etc.) a ambas as listas de permissões
  • Reinicie seu cliente MCP após conceder as permissões
  • Se executado diretamente, adicione o Terminal às permissões de Acessibilidade

Problemas com Análise de Datas

Error: Could not parse date: 'next Flursday'

Solução: Use formatos suportados como "próxima sexta-feira", "em 3 dias" ou "AAAA-MM-DD"

Timeout de AppleScript

Error: AppleScript execution timeout

Solução: Reduza o tamanho das operações em lote ou verifique o desempenho do Things 3

Servidor MCP Não Conectando

Error: MCP server failed to start

Soluções:

  • Verifique se o caminho absoluto para things3-mcp-server está correto
  • Verifique se o executável tem as permissões adequadas (chmod +x things3-mcp-server)
  • Teste o servidor manualmente: ./things3-mcp-server
  • Verifique os logs do cliente MCP para mensagens de erro detalhadas
  • Garanta que o Ruby e as dependências estejam instalados corretamente

Ferramentas MCP Não Aparecendo

No Things3 tools available in client

Soluções:

  • Reinicie seu cliente MCP após alterações de configuração
  • Verifique se a sintaxe da configuração JSON é válida
  • Verifique se o nome do servidor não conflita com outros servidores MCP
  • Procure por erros de conexão nos logs do cliente

Modo de Depuração

Ative o registro detalhado definindo debug: true nos construtores de classe para solução de problemas.

🤝 Integração MCP

Este servidor implementa o Model Context Protocol e pode ser usado com qualquer cliente compatível com MCP:

  • Claude Desktop - Cliente MCP mais popular
  • Cursor IDE - Editor de código com IA e suporte a MCP
  • VS Code - Com extensões MCP
  • Editor Zed - Editor moderno com suporte integrado a MCP
  • Continue - Extensão do VS Code para assistência de codificação com IA
  • Aplicativos Personalizados - Qualquer ferramenta que implemente o padrão MCP

Veja a seção Configuração do Cliente MCP acima para instruções detalhadas de configuração para cada cliente.

O servidor fornece uma interface em linguagem natural para o gerenciamento abrangente de tarefas do Things 3 por meio do protocolo MCP padronizado, tornando seu gerenciamento de tarefas disponível para qualquer assistente de IA ou ferramenta de automação que suporte MCP.

📄 Dependências

  • mcp (~> 0.1.0) - Implementação do Model Context Protocol
  • chronic (~> 0.10.2) - Análise de datas em linguagem natural
  • debug, rubocop (desenvolvimento)

📊 Saúde do Sistema

O servidor inclui monitoramento de saúde integrado por meio de:

  • Pontuação de organização (0-100 em múltiplas dimensões)
  • Análise de saúde do projeto
  • Detecção de duplicatas
  • Verificações de integridade de dados
  • Análise de tendências de produtividade

A manutenção regular pode ser automatizada por meio das ferramentas de limpeza e análise fornecidas.