# 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):

```json
{
  "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`