Mukutu · Ekyte · ekyte-mcp + CLI muk-ekyte
Guia de uso do ekyte-mcp — a CLI muk-ekyte, o servidor MCP no Claude Code e o relatório de consumo de pacote de manutenção — além da verificação semanal de apontamento, que roda sozinha. Ao final, a skill de cronograma de projeto (§07) e uma comparação com o MCP oficial do Ekyte (§08).
Uma fonte de dados, duas formas de acessar — mesma lógica de negócio (src/hours.ts).
O ekyte-mcp (repo privado mktvirtual/mukutu-mono, pasta apps/ekyte-mcp) responde a uma pergunta: quem lançou e quem não lançou horas no Ekyte. Ele deriva o time automaticamente (quem tem apontamento nos últimos 30 dias), aplica a meta de horas por pessoa e um calendário de dias úteis, e devolve o semáforo 🔴🟡🟢.
Soma as horas de apontamentos Concluídos cujo dia de trabalho é a data avaliada, dentro do escopo. Então:
horas = 0 — não lançou nada.0 < horas < meta — lançou, mas abaixo da meta.horas ≥ meta — bateu ou passou.Meta: por pessoa, em config/thresholds.json. Hoje é 6h para todo o time (sem exceções). Ajustável por pessoa (ex.: meio-período → 4h) só editando esse arquivo, sem mexer 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"; fuso America/São Paulo.
muk-ekyteA superfície de terminal. Saída em tabela colorida quando é um terminal; JSON quando a saída é redirecionada (para jq, scripts, etc.).
# time todo, hoje — 🔴🟡🟢
muk-ekyte hours
# só quem está devendo horas (🔴 + 🟡)
muk-ekyte hours --status red,yellow
# escopo Mukutu — "muk" pega Mukutu* E o typo "Muktu | 3M"
muk-ekyte hours --workspace muk --status red,yellow
# um dia específico (a flag --date exige ISO AAAA-MM-DD), em JSON
muk-ekyte hours --date 2026-07-15 --format json | jq '.people'
# histórico de uma pessoa nos últimos 14 dias
muk-ekyte person "Kayo" --period 14--workspace muk. O substring muk casa tanto os ~35 workspaces Mukutu* (incluindo os "Mukutu - Cliente") quanto 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.ekyte-mcp no Claude CodeA superfície conversacional. Registrada no escopo user (vale em todos os projetos). É só perguntar em linguagem natural.
> quem não lançou horas hoje?
> status de horas do time em 15/07/2026
> histórico da Larissa nos últimos 14 dias
> quem está vermelho ou amarelo no escopo mukutu?Por baixo, o Claude chama uma destas ferramentas:
EKYTE_API_KEY do ambiente no momento em que o Claude Code é iniciado. Como a chave foi definida agora, reinicie o Claude Code para o MCP passar a devolver dados reais. A CLI já funciona em qualquer terminal novo.meta de frescor. Se o dado for provisório — dia de hoje ainda aberto, mês em andamento, ou dentro da janela de lançamento tardio (~4 dias) — vem um alert claro, que é sempre repassado a você. Assim dá pra saber na hora se o número é fechado ou parcial, sem depender de reinício. E as datas saem sempre em dd/mm/aaaa (a entrada aceita tanto dd/mm/aaaa quanto ISO).Uma pergunta diferente do semáforo diário: de cada projeto de manutenção, quanto do pacote mensal de horas já foi consumido no mês. Feito para relatório de cliente e diretoria.
O tool ekyte_maintenance_status responde, por projeto de manutenção: quantas horas foram lançadas no mês e se o pacote mensal (ex.: 8h, escrito no nome do projeto) já foi atingido. Enquanto o semáforo das seções anteriores é pessoa × dia, este é projeto × mês.
MWM Manutenção | 18314 - 8h → 8h/mês). Projeto sem Nh no nome vem como no_package.Status de cada projeto:
Em linguagem natural, pelo Claude Code:
> status das manutenções deste mês
> consumo de pacote da manutenção em 2026-06
> como está o pacote de manutenção do MWM?
> manutenções que estouraram o pacoteParâmetros do tool (todos opcionais):
AAAA-MM — mês a avaliar. Padrão: mês corrente (Brasília).manuten; ex.: manuten|sustenta|suporte.| Projeto | Pacote/mês | Consumido | % | Status |
|---|---|---|---|---|
| CRPMA Manutenção | 12h | 20,8h | 173% | over |
| Ancord Manutenção | 20h | 28,9h | 145% | over |
| Hirota Manutenção | 10h | 9,0h | 90% | ok |
| Master Expresso Manutenção | 8h | 0h | 0% | unused |
Exemplo real de julho/2026 (mês fechado), pelo método de soma direta. O retorno completo traz ainda remaining_hours, end_date, expired, um summary (contagem por status) e a coverage.
<Cliente> Manutenção” (então “[Ancord - Novo Site] - Ajustes de Manutenção” é site, não manutenção).expired. Vários projetos de manutenção têm data de término no passado mas continuam recebendo horas — renovação não atualizada no Ekyte (ou apontamento em projeto vencido). O campo expired: true marca esses casos: o pacote continua válido (a comparação de consumo vale), mas o registro precisa ser corrigido no Ekyte. Ex. real: Visagio terminou em 19/12/2025 e ainda recebeu horas em julho/2026./mcp e reconecte o ekyte-mcp (ou reinicie o Claude Code) para ele aparecer. No mês corrente os números são parciais — sobem até o fim do mês.Toda semana, medir quem ficou abaixo da meta entre os colaboradores Mukutu e avisar você. Critério = o semáforo (ver §01). Cobrança não sai daqui — o processo prepara e para; quem manda é você.
[d-1, d+4]: a quinta-feira de uma semana só fecha na segunda seguinte. Medir antes disso lê número que ainda vai mudar.O processo não mora mais aqui. Ele é um workflow versionado no repositório mkt_central, em workflows/02_operations/Z99_verificacao_apontamento/. Até 20/08/2026 era uma skill em claude-projects/ekyte/.claude/skills/, disparada por tarefa agendada — funcionava e entregava, mas aquela pasta não é git: mudar o limiar de 6h ou o roster não deixava rastro de quem mudou nem contra qual argumento.
Lê os dias já fechados da semana, monta o dashboard e manda o resumo para o espaço privado da Ana no Google Chat (webhook cifrado; e-mail foi descartado). Os rascunhos de cobrança ficam prontos e param ali.
Última manhã em que ainda dá para ver se alguma hora subiu depois da cobrança de sexta. Não manda mensagem nenhuma: o resultado entra na abertura do resumo da sexta seguinte.
Primeira execução real em 24/08/2026: zero. Dos 7 cobrados na semana de 17–20/08, nenhum lançou retroativo. A regra combinada é dois zeros seguidos e esta cadência é apagada em vez de seguir rodando às cegas — este foi o primeiro. A próxima medição é 31/08.
Quem deveria aparecer vem de references/roster_mukutu.md, escrito à mão. Derivar o roster de quem apontou nos últimos 30 dias — que é o que o ekyte-mcp faz para o semáforo — foi descartado aqui: esconde exatamente a pessoa que o processo procura. Ausência do Ekyte é zero, nunca omissão.
references/roster_mukutu.md, com as ausências marcadas nele mesmo.Fica registrado para não ser reproposto: publicar a lista nomeada no espaço do time (escolhido em 20/08 e revertido na primeira run, quando a mensagem real ficou pronta — mostrar um placar é diferente de expor quem não apontou na frente de todos); cobrar quem ficou abaixo de 6h em qualquer dia (medido: pegava 12 de 15 pessoas, três delas fechando a semana acima da meta — o caminho conhecido para o aviso virar ruído); cobrar só reincidente (deixaria a primeira falha passar em silêncio, e a janela de lançamento tardio fecha antes); e medir o efeito na sexta seguinte (leria sempre zero, porque a janela já fechou).
lastRunAt é sinal fraco (numa execução mudou, na outra não).Z99_, que é como o mkt_central marca o que ainda não provou cadência.O código foi trazido via git worktree (detached em origin/main) para …\manager-genesis\mukutu-mono-main, sem tocar no branch de trabalho feat/espelho-kv2-redesign.
~/.local/bin/muk-ekyte.cmd) e o MCP apontam por caminho absoluto para mukutu-mono-main. Se esse worktree for removido, as duas superfícies quebram. Para atualizar o código: git -C mukutu-mono-main fetch && git checkout origin/main e recompilar a CLI (pnpm run build:cli).O "hoje" usa o fuso America/São Paulo (Brasília). As ferramentas MCP (ekyte_*) aceitam datas em dd/mm/aaaa ou ISO AAAA-MM-DD na entrada (mês em mm/aaaa ou AAAA-MM) e sempre retornam dd/mm/aaaa (mês como MM/AAAA). A API do Ekyte é ISO; a conversão fica isolada em src/format.ts. A CLI muk-ekyte (binário já compilado) ainda usa ISO na flag --date e na saída JSON até ser recompilada com esta versão. Ex.: 15/07/2026 = 2026-07-15.
meta)Toda ferramenta de leitura retorna meta { generated_at, timezone, scope, up_to_date, alert }. Quando up_to_date é false (dia de hoje, mês corrente, data futura ou janela de lançamento tardio de ~4 dias), o alert explica por que o número é provisório — e esse aviso é sempre repassado ao usuário. O sinal viaja dentro da própria resposta, não depende de memória nem de reinício. Lógica em src/format.ts.
A EKYTE_API_KEY está guardada como variável de ambiente do usuário (registro HKCU) — fora de qualquer arquivo versionável e fora deste documento. O arquivo em texto puro original foi removido. Para rotacionar: gere nova chave em Ekyte › Minha Empresa › BI e redefina a variável de usuário.
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. Só apontamentos com status = 20 (Concluído) contam como "lançado".
O relatório de manutenção (§04) usa /v1.0/projects (nome com o pacote, datas, workspace) e /v1.0/time-trackings (as horas). O consumido é a soma direta dos apontamentos por workspace/projeto (regra puro × misto na §04) — igual à tela “Estatísticas de Apontamento” do Ekyte. Não usa mais o join ctcTaskId → task.projectId, que dependia de um snapshot de tarefas abertas e subestimava o consumo. Lógica em src/maintenance.ts.
Skill crono-proj. Monta o cronograma de um projeto de cliente e gera a imagem que o gestor envia — tabela de datas à esquerda, Gantt à direita, cor separando Mukutu de Cliente. O envio é manual: a skill termina no arquivo.
Onde mora: skills/crono-proj/ no mukutu-mono. Cores e fonte vêm do design system (packages/ui) na hora do render, nunca copiadas.
O Ekyte lançou um servidor MCP próprio (developers.ekyte.com/docs/mcp). O que é, e como se encaixa no que já temos.
Um servidor MCP remoto, hospedado pelo próprio Ekyte. Não se instala nada: aponta-se o cliente MCP para uma URL com um token pessoal e ganha-se acesso a 65 ferramentas que leem e escrevem dados do Ekyte.
# conexão — token no perfil: avatar › Meu Perfil › Integrações MCP
https://api.ekyte.com/mcp?token=SEU_TOKEN| MCP oficial (Ekyte) | Nosso ekyte-mcp | |
|---|---|---|
| Onde roda | remoto, hospedado pelo Ekyte | local (stdio no Claude Code + CLI); HTTP gated |
| Ferramentas | 65 | 6 |
| Leitura / escrita | lê e escreve (cria/edita/envia/upload) | só leitura (o fill_hours_plan é inerte) |
| Autenticação | token pessoal (ação logada como o usuário) | EKYTE_API_KEY de empresa (BI) |
| Foco | acesso amplo e cru ao Ekyte | estreito e opinativo: semáforo, manutenção, relatórios |
| Regra de negócio | nenhuma — devolve o dado bruto | meta/dias úteis, pacote, frescor, datas BR, atribuição puro×misto |
Os dois não competem. Nossas 6 ferramentas são uma camada de negócio em cima da API REST do Ekyte — o semáforo 🔴🟡🟢, o consumo de pacote, o frescor. O MCP oficial é a fonte crua. O encaixe natural é o oficial por baixo das nossas ferramentas, não no lugar delas.
ekyte_person_projects (horas por pessoa × projeto) ainda depende do join ctcTaskId → task.projectId, que passa por um snapshot de tarefas abertas e vira um piso (tarefas fechadas somem — cobertura de ~30% a 70% conforme o mês). O MCP oficial tem 17 ferramentas de Tarefas com filtros próprios: vale testar se resolvem tarefa → projeto de forma completa (inclusive fechadas). Se sim, o split por pessoa vira exato.deploy/ está gated) — e elimina a fragilidade do worktree (§06).?token=) e as ações ficam logadas como a pessoa dona do token — pior pra automação (rotação, desligamento) que a chave de empresa. (2) As ferramentas de escrita têm raio de dano grande; nossa postura read-only é mais segura pra rotina sem supervisão. Adotar escrita só atrás de confirmação explícita.ekyte-mcp como a camada opinativa (semáforo, manutenção, relatório de cliente/diretoria — lógica nossa). Pilotar as ferramentas de leitura do MCP oficial como fonte, mirando (a) fechar a lacuna do join que ainda resta no ekyte_person_projects e (b) o caminho de nuvem. Escrita fica pra depois, com confirmação.Obs.: o mono mukutu-mono tem outro MCP, o funnel-mcp ("verify-everything via typed tools" — Dagster/dbt/Postgres do funil/HubSpot). Mesma pegada de ferramentas tipadas, mas de dados de funil, não do Ekyte — não muda com o MCP oficial do Ekyte.
Documento vivo · atualizado em 24/08/2026 · inclui a skill de cronograma (§07) e a comparação com o MCP oficial do Ekyte (§08).