Controle de Tempo

Código Aberto — O GitScrum MCP Server é código aberto sob a licença MIT. Disponível no npm e no GitHub. Servidor Model Context Protocol para GitScrum — Claude, GitHub Copilot, Cursor e qualquer cliente compatível com MCP têm acesso operacional completo à sua stack de gerenciamento de projetos.

A ferramenta time fornece 9 ações para gerenciamento de cronômetros em tempo real, registro de entradas de tempo e analytics de produtividade. Seja rastreando horas faturáveis para trabalho de clientes, medindo produtividade da equipe ou gerando relatórios de tempo para faturamento, a ferramenta de controle de tempo dá ao seu assistente de IA controle total sobre o sistema de time tracking do GitScrum.

A ferramenta suporta dois fluxos de trabalho principais: cronômetros em tempo real (iniciar/parar enquanto trabalha) e registros de tempo (visualizar entradas registradas). Para analytics, a ferramenta fornece cinco ações de relatório que cobrem produtividade individual, desempenho da equipe e detalhamentos cronológicos.

Visão Geral das Ações

Fluxo de Trabalho do Cronômetro

O fluxo principal do cronômetro segue uma sequência simples: verificar cronômetros ativos → iniciar novo cronômetro → trabalhar → parar o cronômetro. O servidor MCP garante que apenas um cronômetro pode rodar por vez por usuário.

Verificando Cronômetros Ativos

Antes de iniciar um novo cronômetro, o assistente de IA deve verificar se um cronômetro já está em execução. A ação active retorna os detalhes do cronômetro atual se existir, ou { active: false } se nenhum cronômetro estiver rodando.

O parâmetro company_slug é resolvido automaticamente se omitido — o servidor usa seu primeiro workspace acessível.

Você:  "Quais cronômetros estão rodando?"
IA:    Chama time action=active → retorna detalhes do cronômetro atual ou "sem cronômetro ativo"

Você:  "Estou rastreando tempo em algo?"
IA:    Chama time action=active → informa se um cronômetro está rodando e em qual tarefa

Iniciando um Cronômetro

A ação start inicia um cronômetro em uma tarefa específica. Você precisa do UUID da tarefa, que o assistente de IA pode obter da ferramenta task (usando ações como my, today, filter ou by_code).

O servidor MCP retorna o objeto do cronômetro com um timetrackingid que você precisa para a ação stop. O assistente de IA mantém este ID no contexto da conversa para quando você estiver pronto para parar.

Você:  "Iniciar um cronômetro na tarefa GS-123"
IA:    Busca tarefa por código → chama time action=start com task_uuid
      → "Cronômetro iniciado em 'Corrigir validação de login'"

Você:  "Rastrear tempo na tarefa de migração da API"
IA:    Encontra a tarefa → chama time action=start
      → "Cronômetro iniciado em 'Migração da API v3'"

Você:  "Começar a rastrear tempo na minha tarefa atual"
IA:    Verifica task action=today → escolhe a tarefa mais relevante → inicia cronômetro

Parando um Cronômetro

A ação stop encerra o cronômetro em execução. Ela requer o timetrackingid, que o assistente de IA obtém da resposta da ação active.

Você:  "Parar meu cronômetro"
IA:    Chama time action=active → obtém time_tracking_id
      → chama time action=stop → "Cronômetro parado. 1h 23min registrados em 'Corrigir validação de login'"

Você:  "Terminei de trabalhar por agora"
IA:    Verifica se há cronômetro ativo → para se estiver rodando

Exemplo de Fluxo do Cronômetro

Aqui está uma sessão completa de cronômetro como uma conversa natural:

Você:  "Em que estou rastreando tempo?"
IA:    Chama time action=active → "Sem cronômetro ativo"

Você:  "Iniciar um cronômetro na tarefa de correção de login"
IA:    Encontra tarefa → chama time action=start → "Cronômetro iniciado em 'Corrigir validação de login'"

[... você trabalha por 2 horas ...]

Você:  "Parar o cronômetro"
IA:    Chama time action=active → obtém ID → chama time action=stop
      → "Cronômetro parado. 2h 04min registrados"

Registros de Tempo

A ação logs retorna entradas de tempo registradas para um projeto específico. Cada entrada inclui a tarefa, usuário, duração, data e descrição opcional. Esta é a trilha de auditoria de todo o tempo rastreado dentro do projeto.

Parâmetros

Você:  "Mostrar registros de tempo do projeto Backend"
IA:    Chama time action=logs → retorna lista de entradas de tempo com tarefa, usuário e duração

Você:  "Quanto tempo foi registrado no projeto Backend esta semana?"
IA:    Chama time action=logs → IA soma entradas da semana atual

Você:  "Quem registrou mais tempo no projeto Mobile App?"
IA:    Chama time action=logs → IA agrupa por usuário e soma durações

Analytics e Relatórios

A ferramenta de tempo fornece cinco ações de analytics que agregam dados de tempo para diferentes propósitos. Todas compartilham uma estrutura de parâmetros comum.

Parâmetros Comuns

Períodos Disponíveis

Analytics

A ação analytics retorna um resumo dos dados de controle de tempo — total de horas, média diária de horas, distribuição por projeto e dados de tendência. Este é o dashboard de visão geral para controle de tempo.

Você:  "Mostrar meus analytics de controle de tempo deste mês"
IA:    Chama time action=analytics com period="this-month"
      → retorna total de horas, médias diárias, divisão por projeto

Você:  "Quanto tempo rastreei na semana passada?"
IA:    Chama time action=analytics com period="last-7-days"
      → retorna total de horas e distribuição diária

Equipe

A ação team retorna dados de controle de tempo agregados por membro da equipe. Isso mostra quem está rastreando tempo, quanto cada pessoa rastreou e em quais projetos. Gerentes usam isso para avaliação de carga de trabalho e planejamento de capacidade.

Você:  "Mostrar controle de tempo da equipe desta semana"
IA:    Chama time action=team com period="last-7-days"
      → retorna horas por membro, divisão por projeto

Você:  "Quem rastreou mais horas este mês?"
IA:    Chama time action=team com period="this-month"
      → IA identifica o maior contribuidor

Relatórios

A ação reports gera relatórios detalhados de tempo adequados para faturamento. Ela suporta diferentes tipos de relatório e cálculos opcionais de taxa por hora.

Você:  "Gerar um relatório de tempo para o projeto Backend deste mês"
IA:    Chama time action=reports com project_slug, period="this-month"
      → retorna relatório detalhado de tempo com divisão por tarefa

Você:  "Mostrar as horas faturáveis da Acme Corp a R$150/hora"
IA:    Chama time action=reports com hourly_rate=150
      → retorna relatório com custos calculados

Você:  "Criar um relatório de tempo pronto para fatura do mês passado"
IA:    Chama time action=reports com period="last-month"
      → retorna relatório detalhado com datas, tarefas, durações e totais

Produtividade

A ação productivity mede padrões de controle de tempo e métricas de eficiência — tempo de foco, frequência de troca de contexto, horas produtivas por horário do dia e pontuações de consistência. Isso ajuda contribuidores individuais e gerentes a entender padrões de trabalho.

Você:  "Mostrar minhas métricas de produtividade desta semana"
IA:    Chama time action=productivity com period="last-7-days"
      → retorna tempo de foco, horas produtivas, dados de consistência

Você:  "Qual foi a produtividade da equipe no mês passado?"
IA:    Chama time action=productivity com period="last-month"
      → retorna tendências de produtividade da equipe

Linha do Tempo

A ação timeline retorna uma visualização cronológica de entradas de tempo — uma divisão dia a dia, hora a hora do que foi rastreado e quando. Isso é útil para revisar como o tempo foi gasto ao longo de um dia ou semana.

Você:  "Mostrar minha linha do tempo de tempo de hoje"
IA:    Chama time action=timeline com period="today"
      → retorna lista cronológica de blocos de tempo rastreados

Você:  "No que trabalhei ontem?"
IA:    Chama time action=timeline com period="yesterday"
      → retorna entradas de tempo ordenadas com detalhes das tarefas

Workflow de Faturamento

Para equipes rastreando horas faturáveis, a ferramenta de tempo se integra com as capacidades de faturamento do GitScrum. Aqui está um workflow típico de faturamento:

1. Rastrear tempo ao longo do período

Membros da equipe usam cronômetros ou entradas manuais para rastrear tempo em tarefas de clientes.

Você:  "Iniciar um cronômetro na tarefa de integração da API da Acme Corp"
IA:    Inicia cronômetro → você trabalha → para quando terminar

2. Revisar tempo no final do período

Verifique o tempo acumulado antes de gerar faturas.

Você:  "Mostrar todo o tempo rastreado no projeto Backend deste mês"
IA:    Chama time action=logs → retorna lista detalhada de entradas

Você:  "Qual é o total de horas faturáveis deste mês?"
IA:    Chama time action=reports com period="this-month" → retorna totais

3. Gerar relatório de faturamento

Crie um relatório com taxas por hora para faturamento.

Você:  "Gerar um relatório de faturamento a R$150/hora do mês passado"
IA:    Chama time action=reports com hourly_rate=150, period="last-month"
      → retorna relatório com cálculos de horas × taxa

4. Analisar capacidade da equipe

Revise a utilização da equipe para planejamento futuro.

Você:  "Como o tempo da equipe está distribuído entre projetos?"
IA:    Chama time action=team com period="this-month"
      → retorna divisão por membro e por projeto

Integração com Tarefas

O controle de tempo é fortemente acoplado com tarefas. Cada cronômetro e entrada manual está vinculado a uma tarefa específica. Isso significa que seu assistente de IA pode:

• Iniciar cronômetros a partir do contexto de tarefas. Ao revisar sua lista de tarefas, diga ao assistente de IA em qual tarefa rastrear tempo. Ele resolve o UUID da tarefa automaticamente.

• Visualizar dados de tempo dos detalhes da tarefa. Quando você obtém detalhes da tarefa com task action=get, a resposta inclui dados de controle de tempo — tempo total registrado, cronômetros ativos e entradas de tempo.

• Correlacionar tempo com progresso do sprint. Combine sprint action=stats com analytics de tempo para entender quanto esforço cada sprint consumiu.

Você:  "Quanto tempo gastamos no Sprint 14?"
IA:    Obtém tarefas do sprint → cruza referências com registros de tempo → reporta total de horas

Você:  "Começar a rastrear a próxima tarefa da minha lista"
IA:    Chama task action=today → escolhe a tarefa de maior prioridade → inicia cronômetro

Análise Baseada em Períodos

Todas as ações de analytics suportam o parâmetro period para filtragem consistente de janela de tempo. Quando omitido, a maioria das ações usa o padrão do escopo atual (todo o tempo ou período atual, dependendo do endpoint).

Para relatórios recorrentes, você pode estabelecer um padrão com seu assistente de IA:

Você:  "Toda segunda-feira, mostrar o relatório de tempo da semana passada"
IA:    Chama time action=reports com period="last-7-days" → resumo semanal

Você:  "Revisão de tempo de final de mês"
IA:    Chama time action=analytics + team + productivity com period="this-month"
      → análise mensal abrangente

Resolução Automática de Contexto

A ferramenta de tempo suporta resolução automática de contexto para companyslug. Se você não especificar um workspace, o servidor MCP usa seu primeiro workspace acessível. Para projectslug, o servidor pode resolver automaticamente a partir do contexto da conversa se estabelecido anteriormente.

A ação start requer apenas task_uuid — o servidor determina o workspace e projeto a partir da própria tarefa. Isso significa que você pode ir da navegação de tarefas ao controle de tempo em uma única etapa sem re-especificar nenhum contexto.

Próximos Passos

• Tarefas: Gerencie as tarefas nas quais você rastreia tempo.
• Sprints: Planeje sprints e correlacione tempo com progresso do sprint.
• Projetos: Configure projetos e revise membros da equipe.
• Início Rápido: Configure o servidor MCP se ainda não o fez.