Traggo

Todo lo que necesitas para usar traggo con tu LLM favorito.

Documentación

Servidor MCP de Traggo

Un servidor MCP que permite a los asistentes de IA registrar tiempo en Traggo. Actúa como proxy de las llamadas de herramientas MCP hacia la API GraphQL de una instancia de Traggo, e incluye una pequeña interfaz web para obtener el token de acceso con el que te autenticas.

Cómo funciona

El servidor tiene dos superficies:

Inicio de sesión web (/login) — inicias sesión con tu nombre de usuario y contraseña de Traggo y obtienes un token de dispositivo de Traggo. Es una capa delgada sobre la mutación GraphQL login de Traggo; el token se muestra en pantalla para que lo copies.
Endpoint MCP (/mcp) — tu cliente MCP se conecta aquí y envía el token como cabecera Authorization: Bearer <token>. Cada llamada de herramienta se traduce en una solicitud GraphQL de Traggo (enviada upstream como Authorization: traggo <token>, el esquema que Traggo espera).

El servidor no tiene estado: no almacena nada. El token de Traggo es todo el estado de autenticación.

            ┌─────────────┐   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

Herramientas

Herramienta	Descripción
`start_timer`	Iniciar un temporizador en ejecución (intervalo de tiempo abierto) con etiquetas y una nota. El inicio por defecto es ahora.
`stop_timer`	Detener un temporizador en ejecución por id. El fin por defecto es ahora.
`add_timespan`	Registrar un intervalo de tiempo completado con inicio/fin explícitos, etiquetas y una nota.
`update_timespan`	Editar el inicio, fin, etiquetas y nota de un intervalo de tiempo por id.
`remove_timespan`	Eliminar un intervalo de tiempo por id.
`list_timers`	Listar temporizadores en ejecución (para encontrar un id que detener).
`list_timespans`	Listar intervalos de tiempo registrados, opcionalmente dentro de un rango de tiempo RFC3339 (para encontrar un id que editar).
`list_tags`	Listar todas las definiciones de etiquetas (clave, color, recuento de uso).
`create_tag`	Crear una definición de etiqueta (clave + color hexadecimal).
`update_tag`	Cambiar el color de una etiqueta y opcionalmente renombrarla.
`remove_tag`	Eliminar una definición de etiqueta por clave.
`ping_auth`	Diagnóstico: devuelve el token para verificar la conexión de autenticación.

Las etiquetas son pares clave/valor (p. ej. {"key": "project", "value": "traggo"}). Los tiempos son RFC3339 (p. ej. 2026-06-28T09:00:00Z).

Ejecución

El servidor necesita una variable de entorno: TRAGGO_URL, la URL base de tu instancia de Traggo (sin barra final).

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

Escucha en :8080. Abre http://localhost:8080/login para obtener un token y luego apunta tu cliente MCP a http://localhost:8080/mcp.

Conexión de un cliente MCP

Usa un transporte MCP HTTP transmisible apuntando a /mcp, con el token como credencial de portador. Por ejemplo, en un cliente que admita servidores MCP HTTP:

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

Desarrollo

Requisitos previos

Go 1.26+
templ — go install github.com/a-h/templ/cmd/templ@latest (plantillas HTML)
Bun — ejecuta el CLI de Tailwind mediante bunx
air — go install github.com/air-verse/air@latest (recarga en caliente, opcional)
Dagger — solo necesario para compilar/publicar la imagen del contenedor

Bucle de desarrollo con recarga en caliente

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

air (configurado en .air.toml) regenera plantillas y CSS, recompila y sirve con recarga en vivo en http://localhost:8090 (haciendo proxy de la aplicación en :8080).

Compilación manual de recursos

Si no usas air:

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

Estructura del proyecto

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

Compilación y publicación de la imagen

La imagen del contenedor se compila con Dagger — una compilación de múltiples etapas (compilación de Go en golang:1.26, tiempo de ejecución en wolfi-base) que publica en un registro de contenedores. El registro, las credenciales y el nombre de la imagen son 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 por defecto es . y --image por defecto es traggo-mcp:latest. La función devuelve la referencia de la imagen publicada.

Contribuciones

Las contribuciones son bienvenidas. Para empezar:

Haz un fork y clona el repositorio.
Instala los requisitos previos anteriores y ejecuta air (o los pasos de compilación manual) contra una instancia de Traggo que controles.
Haz tu cambio. Si tocas un archivo .templ, ejecuta templ generate. Si agregas o cambias una dependencia, ejecuta go mod tidy.
Asegúrate de que go build ./... y go vet ./... pasen.
Abre una solicitud de extracción describiendo el cambio.

Al agregar una nueva herramienta, el patrón es:

Define los tipos de entrada/salida en internal/traggo/types.go (usa etiquetas de estructura jsonschema para que el esquema MCP sea descriptivo).
Agrega el método de operación a internal/traggo/service.go (pasa por el helper compartido execute para autenticación y manejo de errores).
Registra la herramienta en internal/mcp/server.go.

El esquema GraphQL de Traggo es la fuente de verdad para las operaciones y nombres de campos disponibles.