ekyte-mcp
ARQUIVADO 28/08/2026 — vive em
archive/2026-08_ekyte-mcp/; o MCP oficial do Ekyte tornou este obsoleto. Verarchive/2026-08_ekyte-mcp/WHY.md.
aliases: [“Ekyte MCP”, “ekyte-mcp”, “muk-ekyte”, “Monitoramento de Apontamentos”] type: resource cluster: tech-ia status: developing created: 2026-07-31 updated: 2026-07-31 tags: [tech, ia, mcp, ekyte, horas, gestao, mukutu, ferramentas]
Ekyte MCP / Ekyte MCP
Servidor MCP + CLI que responde quem lançou e quem não lançou horas no Ekyte, e quanto do pacote mensal de manutenção cada projeto já consumiu. Código canônico:
mukutu-mono/apps/ekyte-mcp(privado). Duas superfícies, uma mesma lógica de negócio (src/hours.ts). Fonte: mukutu-mono.
Números deste documento são ilustrativos
Consumo por projeto e nome de cliente são dado comercial e não entram no brain (este site é público). Os exemplos abaixo usam projetos fictícios; o dado real sai da ferramenta, na hora.
O que faz / What it does
Deriva o time automaticamente (quem tem apontamento nos últimos 30 dias — EKYTE_MCP_ROSTER_WINDOW_DAYS), aplica a meta de horas por pessoa e um calendário de dias úteis, e devolve o semáforo 🔴🟡🟢. / Answers who logged hours and who didn’t.
O semáforo: soma as horas de apontamentos Concluídos (status 20) cujo dia de trabalho é a data avaliada, dentro do escopo. Então:
- 🔴 vermelho —
horas = 0, não lançou nada. - 🟡 amarelo —
0 < horas < meta, lançou abaixo da meta. - 🟢 verde —
horas ≥ meta.
Meta: por pessoa, em config/thresholds.json — hoje 6h para todo o time, sem exceções. Ajustar alguém para meio-período (4h) é editar esse arquivo, sem tocar no código.
Anti-falso-alarme: janela de atraso de ~4 dias (lançamento tardio ainda conta no dia trabalhado); só dias úteis contam como “faltou” (src/workday.ts + config/holidays.json); fuso America/São_Paulo.
As duas superfícies / The two surfaces
CLI muk-ekyte — saída em tabela colorida no terminal, JSON quando redirecionada (para jq, scripts):
muk-ekyte hours # time todo, hoje — 🔴🟡🟢
muk-ekyte hours --status red,yellow # só quem está devendo horas
muk-ekyte hours --workspace muk --status red,yellow # escopo Mukutu
muk-ekyte hours --date 2026-07-15 --format json | jq '.people'
muk-ekyte person "Nome" --period 14 # histórico de 14 diasMCP ekyte-mcp no Claude Code — registrado no escopo user (vale em todos os projetos). Pergunta em linguagem natural: “quem não lançou horas hoje?”, “status de horas do time em 15/07/2026”, “quem está vermelho ou amarelo no escopo mukutu?”, “status das manutenções deste mês”.
As 6 ferramentas / The 6 tools
| Ferramenta | Pergunta que responde |
|---|---|
ekyte_hours_status(date?) | Time inteiro num dia: horas lançadas vs. meta, com semáforo. |
ekyte_missing(date?) | Só quem ficou abaixo da meta naquele dia (🔴 + 🟡). |
ekyte_person(name, period_days?) | Histórico dia a dia de uma pessoa numa janela recente. |
ekyte_maintenance_status(month?, workspace?, match?) | Por projeto de manutenção: horas do mês vs. o pacote mensal lido do nome do projeto. |
ekyte_person_projects(name, month?) | De uma pessoa: horas por projeto no mês, em 3 baldes transparentes (cliente / interno Mukutu / não-mapeado). |
ekyte_fill_hours_plan(entries) | Caminho de escrita (preencher horas) — inerte por design: devolve um plano, nunca escreve. |
O artefato de uso interno (“Ekyte · Monitoramento de Apontamentos”, 24/07/2026) documenta 5 dessas ferramentas —
ekyte_person_projectsentrou depois e está noorigin/main.
Escopo Mukutu / Mukutu scope
Use --workspace muk. O substring muk casa os ~35 workspaces Mukutu* (incluindo os “Mukutu - Cliente”) e o Muktu | 3M (typo, id 141790) — e nenhum outro workspace contém “muk”, então não há falso positivo. Verificado em 17/07/2026: 15 pessoas no escopo. Manutenção semanal: revarrer /workspaces da API e conferir se surgiu workspace Mukutu fora do padrão.
Manutenção: horas do mês vs. pacote / Maintenance packages
Pergunta diferente do semáforo diário: o semáforo é pessoa × dia, este é projeto × mês. Feito para relatório de cliente e diretoria.
- Pacote — lido do nome do projeto (
… - 8h→ 8h/mês, regex/(\d+)\s*h\b/). Projeto semNhno nome vem comono_package. - Consumido — soma das horas do mês pelo join
apontamento → tarefa → projeto(ctcTaskId → task.projectId). - Status —
over(estourou o pacote) ·ok(dentro) ·unused(0h no mês) ·no_package.
Exemplo de formato do retorno (projetos fictícios):
| Projeto | Pacote/mês | Consumido | % | Status |
|---|---|---|---|---|
| Cliente A · Manutenção | 8h | 5,0h | 63% | ok |
| Cliente B · Manutenção | 12h | 4,8h | 40% | ok |
| Cliente C · Manutenção | 20h | 24,2h | 121% | over |
| Cliente D · Manutenção | 8h | 0h | 0% | unused |
O retorno completo traz ainda remaining_hours, end_date, expired, summary (contagem por status) e coverage.
O consumido é um piso, não um teto
O Ekyte não liga o apontamento ao projeto diretamente, e /v1.0/tasks só expõe um snapshot de tarefas abertas/recentes — horas lançadas em tarefas já arquivadas podem não entrar. Por isso o retorno traz coverage.mapped_pct (quanto do mês foi atribuído a algum projeto). Manutenção mapeia bem (tarefas recentes); o não-mapeado é sobretudo trabalho interno e campanhas grandes.
Flag expired: vários projetos de manutenção têm data de término no passado e continuam recebendo horas — renovação não atualizada no Ekyte. O campo marca o caso sem somar nada silenciosamente: o pacote continua válido (a comparação de consumo vale), mas o registro precisa ser corrigido no Ekyte.
ekyte_person_projects nunca devolve um número só: o split cliente × interno é heurística sobre o título da tarefa e pode errar, então vem como balde sinalizado e jamais é somado ao total de cliente.
O frescor viaja dentro da resposta
Toda ferramenta de leitura retorna meta { generated_at, timezone, scope, up_to_date, alert }. Quando up_to_date = false (hoje ainda aberto, mês em andamento, data futura ou janela de lançamento tardio), o alert explica por que o número é provisório — e o aviso é sempre repassado a quem perguntou. O sinal não depende de memória nem de reinício: é a correção durável para “estou olhando dado parcial?”. Lógica em src/format.ts.
Datas: as ferramentas MCP aceitam dd/mm/aaaa ou ISO AAAA-MM-DD (mês mm/aaaa ou AAAA-MM) e sempre retornam dd/mm/aaaa. A CLI ainda usa ISO na flag --date e na saída JSON até ser recompilada.
Escrita de horas: inerte por design / Write path
ekyte_fill_hours_plan é a costura para preencher horas — a API REST do Ekyte é GET-only, então escrever de verdade significa dirigir a UI web via browser (pydoll). A v1 entrega a ferramenta deliberadamente inerte: valida e devolve {status: "plan_only", items, note}, sem abrir browser nem escrever, mesmo se pedirem. executePlan() em src/pydoll-fill.ts é a costura vazia — quando for implementada, tem de continuar suggest-confirm e nunca virar loop de escrita desassistida. Apontamento fabricado ou errado é risco real (cobrança errada, sinal de performance errado).
Fontes de dados / Data sources
Duas camadas, em ordem de prioridade: (1) SurrealDB Mukutu ek_mart_daily — ainda não implantada em produção; (2) API REST do Ekyte /v1.0/time-trackings — o caminho que roda hoje. src/surreal.ts degrada para [] em qualquer erro (nunca lança), então o MCP funciona pela API hoje e passa a usar o mart sozinho quando ele subir. O relatório de manutenção usa três endpoints read-only: /v1.0/projects, /v1.0/tasks e /v1.0/time-trackings.
Segurança da chave / Key handling
EKYTE_API_KEY fica como variável de ambiente do usuário (registro HKCU) — fora de arquivo versionável. Nunca commitar. Para rotacionar: gerar nova chave em Ekyte › Minha Empresa › BI e redefinir a variável. O servidor MCP herda a chave no momento em que o Claude Code inicia — mudou a chave ou o tool é novo, reinicie (ou /mcp e reconecte).
Plano de monitoramento diário / Daily monitoring plan
Status: aguardando validação. Todo dia útil, sinalizar quem está 🔴/🟡 no escopo Mukutu, avisar a gestão e depois notificar as próprias pessoas.
- Escopo —
--workspace muk(inclui o “3M”) + revisão semanal de workspaces novos. ✔ definido - Onde roda — começa local agendado (Agendador de Tarefas do Windows ou
/loopchamando a CLI). Próximas etapas anotadas: Claude Cowork (tarefa agendada, precisa registrar o MCP no Desktop) e nuvem via Routines (exige subir oekyte-mcpcomo servidor HTTP remoto). - Alerta — avaliar o último dia útil, não “hoje”: checar de manhã não mede nada (às 09h quase todo mundo está 🔴 só porque ainda não lançou). Foco em 🔴 e 🟡.
- Notificar as pessoas — canal Google Chat, começando em dry-run (só avisa a gestão) antes de acionar terceiros. Nunca virar loop de cobrança automática sem revisão. Liga a Ouvinte do Google Chat.
- Em aberto — confirmar meta de 6h/dia para todo o time ou cadastrar exceções (meio-período).
Por que importa para a Nova Mukutu / Why it matters
- Substitui a checagem manual na UI do Ekyte por uma pergunta em linguagem natural — é caso de uso direto de Automacoes de IA com dado interno real.
- O relatório de pacote de manutenção é insumo de cobrança e diretoria: mostra estouro de escopo mês a mês, o que liga a Modelo de Orçamento de Produto e ao diagnóstico de fluxo em Diagnóstico Kanban Mukutu.
- Padrão de projeto a copiar: caminho de escrita inerte + bloco de frescor obrigatório. Ver Como Criar Automacoes de IA.
Perguntas a responder / Questions to answer
- Meta única de 6h/dia ou exceções por contrato?
- Quando o
ek_mart_dailysobe no SurrealDB (tira a dependência da API REST)? - Vale expor
ekyte_maintenance_statuscomo relatório recorrente para os gestores de conta?
Relacionado / Related
- Ouvinte do Google Chat
- Skills da Equipe Mukutu
- Automacoes de IA
- Como Criar Automacoes de IA
- WezTerm
- mukutu-mono
Fontes / Sources
mukutu-mono/apps/ekyte-mcp/README.md+src/(origin/main, lido em 31/07/2026) — 6 tools registradas.- Artefato “Ekyte · Monitoramento de Apontamentos”, 24/07/2026 (documento vivo, 5 tools).