Traggo

Tudo o que você precisa para usar o traggo com seu LLM favorito.

Documentação

Servidor MCP Traggo

Um servidor MCP que permite que assistentes de IA registrem tempo no Traggo. Ele faz proxy de chamadas de ferramentas MCP para a API GraphQL de uma instância Traggo e inclui uma pequena interface web para obter o token de acesso com o qual você se autentica.

Como funciona

O servidor tem duas superfícies:

Login web (/login) — você faz login com seu nome de usuário e senha do Traggo e recebe um token de dispositivo do Traggo. Este é um wrapper fino sobre a mutação GraphQL login do Traggo; o token é exibido na tela para você copiar.
Endpoint MCP (/mcp) — seu cliente MCP se conecta aqui e envia o token como um cabeçalho Authorization: Bearer <token>. Cada chamada de ferramenta é traduzida em uma solicitação GraphQL do Traggo (enviada upstream como Authorization: traggo <token>, o esquema que o Traggo espera).

O servidor é sem estado — ele não armazena nada. O token do Traggo é todo o estado de autenticação.

            ┌─────────────┐   Bearer <token>   ┌──────────────┐   traggo <token>   ┌────────────┐
 MCP client │  POST /mcp  │ ─────────────────► │ traggo-mcp   │ ─────────────────► │   Traggo   │
            └─────────────┘                    │ (this server)│   GraphQL          │  instance  │
                                               └──────────────┘                    └────────────┘
   browser  ── GET/POST /login ──────────────► returns a device token to copy

Ferramentas

Ferramenta	Descrição
`start_timer`	Inicia um timer em execução (período de tempo aberto) com tags e uma nota. O início padrão é agora.
`stop_timer`	Para um timer em execução pelo id. O fim padrão é agora.
`add_timespan`	Registra um período de tempo concluído com início/fim explícitos, tags e uma nota.
`update_timespan`	Edita o início, fim, tags e nota de um período de tempo pelo id.
`remove_timespan`	Exclui um período de tempo pelo id.
`list_timers`	Lista timers atualmente em execução (para encontrar um id para parar).
`list_timespans`	Lista períodos de tempo registrados, opcionalmente dentro de um intervalo de tempo RFC3339 (para encontrar um id para editar).
`list_tags`	Lista todas as definições de tags (chave, cor, contagem de uso).
`create_tag`	Cria uma definição de tag (chave + cor hexadecimal).
`update_tag`	Altera a cor de uma tag e opcionalmente a renomeia.
`remove_tag`	Exclui uma definição de tag pela chave.
`ping_auth`	Diagnóstico — ecoa o token para verificar a configuração de autenticação.

Tags são pares chave/valor (ex.: {"key": "project", "value": "traggo"}). Horários são RFC3339 (ex.: 2026-06-28T09:00:00Z).

Execução

O servidor precisa de uma variável de ambiente: TRAGGO_URL, a URL base da sua instância Traggo (sem barra final).

export TRAGGO_URL=https://traggo.example.com
go run ./cmd/server

Ele escuta em :8080. Abra http://localhost:8080/login para obter um token e, em seguida, aponte seu cliente MCP para http://localhost:8080/mcp.

Conectando um cliente MCP

Use um transporte MCP HTTP streamable apontado para /mcp, com o token como credencial bearer. Por exemplo, em um cliente que suporta servidores MCP HTTP:

{
  "mcpServers": {
    "traggo": {
      "url": "http://localhost:8080/mcp",
      "headers": { "Authorization": "Bearer <your-traggo-token>" }
    }
  }
}

Desenvolvimento

Pré-requisitos

Go 1.26+
templ — go install github.com/a-h/templ/cmd/templ@latest (templating HTML)
Bun — executa o CLI Tailwind via bunx
air — go install github.com/air-verse/air@latest (hot reload, opcional)
Dagger — necessário apenas para compilar/publicar a imagem do contêiner

Loop de desenvolvimento com hot-reload

export TRAGGO_URL=https://traggo.example.com
air

air (configurado em .air.toml) regenera templates e CSS, recompila e serve com recarga ao vivo em http://localhost:8090 (fazendo proxy do aplicativo em :8080).

Compilando assets manualmente

Se você não estiver usando air:

templ generate                                          # .templ → _templ.go
bunx @tailwindcss/cli -i ./app.css -o assets/output.css # build CSS
go run ./cmd/server

Estrutura do projeto

cmd/server/        Entry point: route wiring, starts the HTTP server
internal/
  auth/            Web login flow → Traggo device token
  mcp/             MCP server: tool registration + bearer-token middleware
  traggo/          GraphQL client for the Traggo API (all timer/timespan/tag ops)
views/             templ components and pages for the web UI
assets/            Static files (generated CSS, images)
.dagger/           Dagger module for building & publishing the container image

Compilando e publicando a imagem

A imagem do contêiner é compilada com Dagger — uma compilação em vários estágios (compilação Go em golang:1.26, runtime em wolfi-base) que publica em um registro de contêineres. Registro, credenciais e nome da imagem são todos parâmetros:

dagger call build \
  --source . \
  --registry registry.example.com \
  --username you@example.com \
  --registry-password env:REGISTRY_PASSWORD \
  --image traggo-mcp:latest

--source tem como padrão . e --image tem como padrão traggo-mcp:latest. A função retorna a referência da imagem publicada.

Contribuindo

Contribuições são bem-vindas. Para começar:

Faça um fork e clone o repositório.
Instale os pré-requisitos acima e execute air (ou as etapas de compilação manual) contra uma instância Traggo que você controla.
Faça sua alteração. Se você tocar em um arquivo .templ, execute templ generate. Se você adicionar ou alterar uma dependência, execute go mod tidy.
Certifique-se de que go build ./... e go vet ./... passem.
Abra um pull request descrevendo a alteração.

Ao adicionar uma nova ferramenta, o padrão é:

Defina os tipos de entrada/saída em internal/traggo/types.go (use tags de struct jsonschema para que o esquema MCP seja descritivo).
Adicione o método de operação a internal/traggo/service.go (ele passa pelo helper compartilhado execute para autenticação e tratamento de erros).
Registre a ferramenta em internal/mcp/server.go.

O esquema GraphQL do Traggo é a fonte da verdade para operações e nomes de campos disponíveis.