Amazing Marvin AI Assistant

🚀 Integração do Assistente de IA do Amazing Marvin

Conecte seu sistema de produtividade Amazing Marvin com assistentes de IA para um gerenciamento de tarefas mais inteligente

📋 Sumário

• O que é isso?
• Início Rápido (2 minutos)
• O que você pode fazer com isso?
• Instalação
• Configuração
• Exemplos de Uso
• Solução de Problemas
• Perguntas Frequentes
• Desenvolvimento
• Privacidade e Segurança

🎯 O que é isso?

Isso conecta seu sistema de produtividade Amazing Marvin com assistentes de IA como Claude, Cursor e outros. Em vez de copiar manualmente suas tarefas e projetos para o chat, seu assistente de IA pode ver e ajudar com seus dados reais do Amazing Marvin.

✨ Principais Benefícios

• 🔄 Mantenha-se sincronizado - Seu assistente de IA sempre vê suas tarefas, projetos e metas atuais
• 📋 Ajuda inteligente - Receba conselhos personalizados com base na sua carga de trabalho e prioridades reais
• ⚡ Economize tempo - Chega de copiar e colar listas de tarefas ou explicar seus projetos
• 🎯 Melhor foco - A IA ajuda você a identificar o que é mais importante agora
• 🔒 Privado - Seus dados ficam entre o Amazing Marvin e seu assistente de IA

⚡ Início Rápido (2 minutos)

Passo 1: Obtenha sua chave de API do Amazing Marvin

1. Abra o Amazing Marvin → Configurações → API (navegar aqui pode ser mais fácil no celular)
2. Ative a API e copie seu token
3. Guarde-o em local seguro! 🔑

Passo 2: Instale

Caminho fácil (Smithery):

npx -y @smithery/cli mcp add @bgheneti/amazing-marvin-mcp --client claude

Cole a chave da API quando solicitado

Alternativa (pip):

pip install amazing-marvin-mcp

Depois adicione à configuração do seu cliente de IA (veja o guia de instalação)

Passo 3: Verifique se está funcionando

Pergunte à sua IA: "Quais tarefas tenho hoje?"

🎉 Pronto! Sua IA agora pode ver seus dados do Amazing Marvin.

💡 O que você pode fazer com isso?

Uma vez conectado, seu assistente de IA se torna seu coach pessoal de produtividade com acesso aos seus dados reais do Amazing Marvin:

📅 Ajuda no Planejamento Diário

"No que devo focar hoje?" - Receba recomendações personalizadas com base nos seus prazos e prioridades reais

"Estou me sentindo sobrecarregado - o que é mais importante?" - A IA ajuda você a filtrar o ruído e identificar o que realmente importa

🎯 Insights de Projetos

"Como está indo meu projeto de reforma do site?" - Veja o progresso, tarefas concluídas e o que falta fazer

"Mostre-me tudo relacionado ao trabalho com clientes esta semana" - Obtenha visualizações organizadas das suas tarefas por projeto ou categoria

📊 Acompanhamento de Progresso

"O que eu realizei esta semana?" - Revise seus padrões de produtividade e celebre conquistas

"Em quais dias sou mais produtivo?" - Entenda seus padrões para planejar melhor

⏰ Agendamento Inteligente

"O que está atrasado e precisa de atenção?" - Nunca perca o controle de prazos importantes

"Ajude-me a planejar amanhã com base no que tenho agendado" - Obtenha planos diários realistas que funcionam

⏱️ Controle de Tempo

"Comece a registrar o tempo nesta tarefa" - Gerencie o controle de tempo diretamente do chat com a IA

"No que tenho trabalhado hoje?" - Revise sua alocação de tempo e foco

Por que isso é melhor que conselhos genéricos de produtividade: Sua IA vê suas tarefas, prazos e progresso reais - então a ajuda que você recebe é personalizada para sua situação real, não dicas genéricas.

Observação: Isso cobre a maioria dos recursos do Amazing Marvin, embora algumas personalizações avançadas e estratégias tenham acesso limitado à API.

📦 Instalação

Opção 1: Smithery (Mais Fácil)

npx -y @smithery/cli install @bgheneti/amazing-marvin-mcp --client claude

Visite o Registro Smithery para outros clientes.

Opção 2: Pip + Configuração Manual

Por que escolher esta opção:

• ✅ Funciona com qualquer cliente de IA compatível com MCP
• ✅ Fácil de atualizar: basta pip install --upgrade amazing-marvin-mcp

Pré-requisitos

• ✅ Python 3.10+
• ✅ Claude Desktop, Cursor, Windsurf, VS Code ou outro cliente MCP
• ✅ Conta Amazing Marvin com acesso à API

Instalação

# Install from PyPI (recommended)
pip install amazing-marvin-mcp

📱 Configuração do Cliente

{
  "mcpServers": {
    "amazing-marvin": {
      "command": "python",
      "args": ["-m", "amazing_marvin_mcp"],
      "env": {
        "AMAZING_MARVIN_API_KEY": "your-api-key-here"
      }
    }
  }
}

{
  "mcpServers": {
    "amazing-marvin": {
      "command": "python",
      "args": ["-m", "amazing_marvin_mcp"],
      "env": {
        "AMAZING_MARVIN_API_KEY": "your-api-key-here"
      }
    }
  }
}

{
  "mcpServers": {
    "amazing-marvin": {
      "command": "python",
      "args": ["-m", "amazing_marvin_mcp"],
      "env": {
        "AMAZING_MARVIN_API_KEY": "your-api-key-here"
      }
    }
  }
}

{
  "mcpServers": {
    "amazing-marvin": {
      "command": "python",
      "args": ["-m", "amazing_marvin_mcp"],
      "env": {
        "AMAZING_MARVIN_API_KEY": "your-api-key-here"
      }
    }
  }
}

💡 Exemplos de Uso

O MCP fornece ferramentas específicas que sua IA pode usar. Basta pedir à sua IA para ajudar com tarefas de produtividade e ela usará as ferramentas apropriadas:

📁 Como ela entende sua configuração

Seu assistente de IA entende automaticamente sua estrutura do Amazing Marvin:

• Projetos de Trabalho e Pessoais - Mantém suas tarefas profissionais e pessoais organizadas
• Categorias e rótulos - Sabe como você organizou seu sistema de produtividade
• Datas de vencimento e prioridades - Entende o que é urgente vs. importante
• Concluídas vs. pendentes - Acompanha seu progresso e ritmo

Não precisa explicar seu sistema - sua IA simplesmente entende!

🔧 Solução de Problemas

❌ Problemas Comuns

❓ Perguntas Frequentes

👨‍💻 Desenvolvimento

🛠️ Configuração

git clone https://github.com/bgheneti/Amazing-Marvin-MCP.git
cd Amazing-Marvin-MCP
pip install -e ".[dev]"
pre-commit install

🔑 Defina sua chave de API

Opção A: Variável de ambiente

export AMAZING_MARVIN_API_KEY="your-api-key-here"

Opção B: Crie um arquivo .env

AMAZING_MARVIN_API_KEY=your-api-key-here

🧪 Testes

pytest tests/ -v

⚠️ Observação: Os testes criam itens temporários na sua conta Amazing Marvin com prefixos [TEST]. Eles podem precisar de limpeza manual devido a limitações da API.

📋 Qualidade do Código

# Run all checks
pre-commit run --all-files

# Individual tools
ruff check .          # Linting
ruff format .         # Formatting
mypy .               # Type checking
pytest tests/        # Tests

🔄 Ferramentas Disponíveis

O MCP fornece 28 ferramentas abrangentes para assistentes de IA: 📖 Operações de Leitura:

• get_daily_productivity_overview() - PRIMÁRIA visão diária abrangente (tarefas de hoje, atrasadas, concluídas, insights de planejamento)
• get_tasks() - Apenas itens agendados para hoje
• get_projects() - Todos os projetos
• get_categories() - Todas as categorias
• get_due_items() - Apenas itens atrasados/vencidos
• get_child_tasks( parent_id: str, recursive: bool = False ) - Subtarefas de uma tarefa/projeto pai
• get_all_tasks( label: str = None ) - Encontra todas as tarefas com filtro opcional por etiqueta (busca abrangente)
• get_labels() - Etiquetas de tarefas
• get_goals() - Metas e objetivos
• get_account_info() - Detalhes da conta
• get_completed_tasks() - Itens concluídos com categorização por data (padrão: últimos 7 dias)
• get_completed_tasks_for_date( date: str ) - Itens concluídos para data específica (formato YYYY-MM-DD)
• get_productivity_summary_for_time_range( days: int = 7, start_date: str = None, end_date: str = None ) - Análises flexíveis de produtividade
• get_currently_tracked_item() - Controle de tempo ativo

✏️ Operações de Escrita:

• create_task( title: str, project_id: str = None, category_id: str = None, due_date: str = None, note: str = None ) - Criar novas tarefas
• mark_task_done( item_id: str, timezone_offset: int = 0 ) - Concluir tarefas
• create_project( title: str, project_type: str = "project" ) - Criar novos projetos
• start_time_tracking( task_id: str ) - Iniciar controle de tempo
• stop_time_tracking( task_id: str ) - Encerrar controle de tempo
• batch_mark_done( task_ids: list[str] ) - Concluir múltiplas tarefas
• batch_create_tasks( task_list: list[str], project_id: str = None, category_id: str = None ) - Criar múltiplas tarefas
• claim_reward_points( points: int, item_id: str, date: str ) - Resgatar pontos de kudos
• get_kudos_info() - Obter informações do sistema de recompensas e kudos

🔧 Operações de Utilidade:

• test_api_connection() - Verificar conectividade da API
• get_project_overview( project_id: str ) - Análises do projeto
• get_daily_focus() - Prioridades diárias
• get_productivity_summary() - Métricas de desempenho
• time_tracking_summary() - Análises de tempo
• quick_daily_planning() - Assistência de planejamento
• create_project_with_tasks( project_title: str, task_titles: list[str], project_type: str = "project" ) - Configuração de projeto
• get_time_tracks( task_ids: list[str] ) - Histórico de controle de tempo

🤝 Contribuindo

🚀 Publicando Novas Versões

Este projeto usa publicação automatizada no PyPI via GitHub Actions.

Para mantenedores:

# Make your changes and test them
pytest tests/ -v
ruff check src/
mypy src/amazing_marvin_mcp/

# Use the release script to bump version and create tag
python scripts/release.py patch   # for bug fixes
python scripts/release.py minor   # for new features
python scripts/release.py major   # for breaking changes

# Push to trigger CI and PyPI publish
git push origin main
git push origin v1.x.x

O fluxo de trabalho:

1. ✅ Testes executados em Python 3.8-3.12
2. ✅ Linting e verificação de tipos passam
3. 📦 O pacote é construído e verificado
4. 🚀 Publicado no PyPI automaticamente em tags de versão

🔧 Configuração de Desenvolvimento Local

git clone https://github.com/bgheneti/Amazing-Marvin-MCP.git
cd Amazing-Marvin-MCP
pip install -e ".[dev]"
pre-commit install

🧪 Testes

Você também pode publicar manualmente no Test PyPI executando o fluxo de trabalho manualmente no GitHub.

🔒 Privacidade e Segurança

🛡️ Proteção dos Seus Dados

• Processamento Local: O MCP é executado inteiramente na sua máquina
• Conexão Direta: Os dados vão diretamente do Amazing Marvin para sua IA
• Sem Armazenamento em Nuvem: Nada é armazenado em servidores externos
• Segurança da Chave de API: Armazene sua chave com segurança usando variáveis de ambiente

🔐 Melhores Práticas

• ✅ Use variáveis de ambiente para chaves de API (não arquivos de configuração)
• ✅ Não compartilhe sua chave de API em capturas de tela ou logs
• ✅ Mantenha sua chave de API segura e trate-a como uma senha

⚖️ Desempenho e Limitações

O que esperar:

• Seu assistente de IA busca dados atualizados do Amazing Marvin quando você faz perguntas
• Dados históricos são armazenados em cache brevemente para evitar solicitações repetidas
• O tempo de resposta depende da sua conexão com a internet para o Amazing Marvin
• Solicitações muito frequentes podem ocasionalmente atingir limites de taxa (basta aguardar um momento)

Detalhes técnicos:

• Os dados são buscados em tempo real para precisão
• Alguns dados são armazenados em cache por 10 minutos para melhorar a velocidade
• Operações em lote funcionam eficientemente para múltiplas tarefas
• Todos os recursos principais do Amazing Marvin são suportados

📄 Licença

Licença MIT - veja LICENSE para detalhes.