horas-mcp

MCP server local para controle de horas por card/subtarefa do Jira — cronômetro, pausas, correções, relatórios e controle de apontamento pendente. 100% local (arquivo JSON), sem depender da API do Jira. Roda em Node 18+ e pode ser distribuído como um único arquivo.

Fluxo de uso (conversando com o agente)

Você diz	O que acontece
"começa a SUB-456"	inicia o cronômetro (para a anterior automaticamente)
"pausa" / "voltei"	pausa/retoma (almoço, reunião)
"terminei"	fecha a sessão e mostra tempo real + arredondado
"comecei a SUB-456 às 9h"	início retroativo
"trabalhei 1h30 ontem na SUB-457"	registro manual
"relatório de hoje / da semana"	tabela por card com pendências de apontamento
"apontei a SUB-456"	marca como apontada (some das pendências)

O apontamento oficial você lança no Jira manualmente — o relatório já mostra o valor arredondado no formato do worklog (2h 30m) e a nota da sessão para usar de comentário.

Build

npm install
npm run build     # dist/index.js (ESM, para desenvolvimento)
npm run bundle    # dist/horas.cjs — ARQUIVO ÚNICO, autocontido, Node 18+

Instalar na máquina da empresa (GitHub Copilot / VS Code)

Copie apenas dist/horas.cjs para a máquina (ex: C:\Users\voce\horas\horas.cjs) e registre no VS Code — Ctrl+Shift+P → "MCP: Open User Configuration" (ou .vscode/mcp.json do workspace):

{
  "servers": {
    "horas": {
      "type": "stdio",
      "command": "node",
      "args": ["C:/Users/voce/horas/horas.cjs"],
      "env": { "HORAS_BLOCO_MIN": "15", "HORAS_ARREDONDAR": "cima" }
    }
  }
}

Sem npm install, sem build — só Node 18+ e o arquivo. As tools aparecem no Copilot Chat em agent mode.

Alternativa com SQLite: leve node-22/dist/horas-sqlite.cjs (também arquivo único, requer Node 22.13+; dados em ~/.horas/horas.db). Escolha uma das duas — os dados não são compartilhados entre elas.

Instalar no Claude Code

claude mcp add --scope user horas -- node D:/Gabriel/Projetos/horas/dist/horas.cjs

Configuração (variáveis de ambiente)

Variável	Padrão	Descrição
HORAS_BLOCO_MIN	15	Tamanho do bloco de arredondamento em minutos (0 desliga)
HORAS_ARREDONDAR	cima	Modo: cima, proximo ou baixo
HORAS_SESSAO_MAX_HORAS	12	Sessão aberta além disso é tratada como timer esquecido
HORAS_DB	~/.horas/horas.json	Caminho do arquivo de dados (JSON, escrita atômica)

Tools expostas

iniciar_tarefa · pausar_tarefa · retomar_tarefa · parar_tarefa · status_atual · registrar_manual · editar_sessao · excluir_sessao · relatorio · marcar_apontado