suite-timesheet-mcp

Servidor MCP que deixa um assistente (Claude, GitHub Copilot, ou outro cliente MCP) ler e propor horas na Folha de Horas do Suite, através da extensão Suite Timesheet Importer.

• Nunca fala com o Suite. Quem lê e escreve é a extensão, no teu browser, com a tua sessão.

• Nunca escreve sem ti. Cada lançamento é uma proposta; só é escrito quando clicas Aplicar no painel ou aprovas a tool aplicar no teu cliente MCP.

• Nunca submete meses nem muda o mês aberto na página.

• Só local. Escuta apenas em 127.0.0.1, guarda tudo em memória, não tem telemetria.

Detalhes e forma de verificar cada afirmação: SECURITY.md.

Requisitos

• Node.js ≥ 20 (node -v).

• Chrome ou Edge com a extensão Suite Timesheet Importer instalada.

• A Folha de Horas do Suite aberta, com sessão válida.

Related MCP server: TrackingTime MCP

Instalação

1. Ligar a ponte na extensão

Nas Opções da extensão, liga Ligação ao servidor local (ponte MCP), clica em Guardar e aceita a permissão para http://127.0.0.1/*. Depois recarrega a Folha de Horas.

Este passo é manual e feito uma vez: sem ele a extensão nunca toca na rede local.

2. Registar o servidor no teu cliente MCP

Não é preciso clonar nada: o npx descarrega o pacote do npm e corre-o. @1 fixa a versão principal: recebes as correções 1.x, nunca uma versão incompatível. A primeira execução demora alguns segundos; as seguintes usam a cache.

Claude Code

claude mcp add --scope user suite-timesheet -- npx -y suite-timesheet-mcp@1

GitHub Copilot (VS Code)

code --add-mcp '{"name":"suite-timesheet","command":"npx","args":["-y","suite-timesheet-mcp@1"]}'

Depois recarrega a janela; as tools aparecem no modo Agent do Copilot.

Claude Desktop (inclui Cowork)

Em Definições → Programador → Editar configuração (~/Library/Application Support/Claude/claude_desktop_config.json no macOS, %APPDATA%\Claude\claude_desktop_config.json no Windows):

{
  "mcpServers": {
    "suite-timesheet": {
      "command": "npx",
      "args": ["-y", "suite-timesheet-mcp@1"]
    }
  }
}

Reinicia o Claude Desktop.

Outros clientes

O mesmo comando: npx -y suite-timesheet-mcp@1, por stdio. Atenção à chave do ficheiro de configuração: o VS Code usa servers, a maioria dos outros usa mcpServers.

Se o cliente não encontrar o npx (comum em apps abertas pelo Dock, que não herdam o PATH do terminal), usa o caminho absoluto dado por which npx. No Windows, usa "command": "cmd" com "args": ["/c", "npx", "-y", "…"].

3. Verificar

Pede ao assistente: "consulta o estado da ponte do Suite Timesheet". A tool estado deve responder com a ponte ligada e o mês visível na página. As Opções da extensão passam a mostrar "Claude ligado há N s" (o texto é o mesmo para qualquer cliente).

Instalação feita por um agente

Se estás a pedir a um agente para instalar isto, ele deve seguir esta ordem e parar no primeiro passo que falhe:

1. Confirmar node -v ≥ 20.

2. Correr o comando do passo 2 correspondente ao cliente em uso.

3. Pedir ao utilizador para fazer o passo 1 (Opções da extensão). O agente não o consegue fazer.

4. Pedir ao utilizador para recarregar o cliente MCP, se o cliente o exigir.

5. Chamar a tool estado. Sucesso = ponte ligada e mês visível. Qualquer ERR_*: ver Erros.

O agente não deve pôr a tool aplicar em aprovação automática.

Usar

Exemplos de pedidos:

• "Quantas horas tenho lançadas este mês no Suite?" → ler_mes

• "Que projetos tenho disponíveis?" → projetos

• "Lança 8 h no projeto X de segunda a sexta desta semana." → propor, depois aplicar

Lançar horas tem sempre duas fases:

1. propor calcula o plano, abre o painel da extensão com a pré-visualização e devolve-a ao assistente. Nada é escrito.

2. Confirmação, de uma de duas formas:

   • clicas Aplicar no painel, ou

   • dizes OK no chat e aprovas a chamada da tool aplicar no cliente MCP.

Por isso: mantém a aprovação manual da tool aplicar. Com ela em aprovação automática, qualquer proposta é escrita sem mais nenhuma confirmação. Linhas trancadas e propostas bloqueadas são sempre recusadas pela extensão.

Tools

Erros

Como funciona

cliente MCP ──stdio──▶ mcp.js ──HTTP──▶ serve.js ◀──long-poll── extensão ──▶ Suite
                                        127.0.0.1                    │
                                                              painel: Aplicar

1. O cliente MCP arranca o mcp.js. Se o serviço local (serve.js) não estiver a correr, o mcp.js arranca-o em segundo plano, em 127.0.0.1:18765.

2. A extensão, com a Folha de Horas aberta, faz long-poll ao serviço e publica o mês visível.

3. Cada tool enfileira um comando; a extensão executa-o no browser e devolve o resultado.

O protocolo entre o serviço e a extensão está em CONTRACT.md.

Configuração avançada

Variáveis de ambiente, no bloco env da configuração do cliente MCP:

Com o serviço gerido à mão, arranca-o antes de abrir a Folha de Horas, ou recarrega a página depois: a extensão só publica o contexto quando a página carrega ou muda de mês.

As tools aceitam timeout_s até 290 s (útil em resultado com lotes grandes). Se o cliente cortar a chamada antes disso, aumenta o timeout do cliente MCP (no Claude Code, 60 s por defeito).

Atualizar

As correções 1.x chegam ao reiniciar o cliente MCP (o npx volta a consultar o npm). Para uma versão principal nova, muda @1 no comando. O serviço local fica a correr entre sessões; para ele pegar na versão nova, termina-o uma vez (lsof -ti tcp:18765 | xargs kill) e o mcp.js arranca o novo.

Limitações

• Sem autenticação local: qualquer processo do teu utilizador consegue falar com o serviço. Páginas web não conseguem. Ver SECURITY.md.

• Tudo em memória: reiniciar o serviço esquece propostas e contexto (recarrega a Folha de Horas).

• Um mês de cada vez: o que está aberto na página.

Correr a partir de um clone

git clone https://github.com/williansaez/suite-timesheet-mcp.git
cd suite-timesheet-mcp
npm ci
node --test

Para usar a cópia local num cliente, troca o comando npx … por node /caminho/para/suite-timesheet-mcp/mcp.js. Também dá para instalar diretamente de uma tag do GitHub, sem npm: npx -y github:williansaez/suite-timesheet-mcp#v1.0.0 (precisa de git).

Licença

Código disponível para consulta, não open source. Podes instalar e usar o pacote sem alterações, para uso pessoal ou interno da tua organização. Não é permitido alterá-lo, redistribuí-lo nem publicar cópias ou forks. Os termos completos (em inglês, com tradução para português) estão em LICENSE.