Tickspot

Plugin para Claude Code que conecta tu cuenta de Tickspot con tu Google Calendar para registrar horas de trabajo con un solo comando.

En lugar de abrir Tickspot manualmente, escribes en Claude:

/log-today

Claude revisa tus eventos del día en Google Calendar, los asocia automáticamente a los proyectos y tareas correctas en Tickspot, te muestra un resumen para confirmar, y crea todas las entradas de golpe.

---

Comandos disponibles

Comando	Lo que hace
/tick-setup	Conecta tus credenciales de Tickspot y Google Calendar (solo la primera vez)
/log-today	Registra las horas del día de hoy usando tu calendario
/log-week	Registra toda la semana en batch
/check-gaps	Detecta días con horas faltantes o incompletas

También puedes activarlos de forma conversacional — no es necesario recordar los comandos exactos:

"Tengo que llenar el tick de esta semana"

"¿Qué me falta registrar?"

"Llena mis horas del lunes"

"Log my hours for today"

---

Requisitos

Antes de instalar, verifica que tienes:

• Claude Code — la CLI de Claude. Descárgala en claude.ai/download o instálala con npm install -g @anthropic-ai/claude-code.

• Node.js 18 o superior — el motor del plugin. Verifica con node --version. Si no lo tienes o es muy viejo, descárgalo en nodejs.org (elige "LTS").

• Cuenta en Tickspot — necesitas tener acceso a la cuenta del equipo.

---

Instalación

Solo necesitas dos comandos. Ábrelos en tu terminal:

1. Agrega el repositorio de plugins del equipo:

claude plugin marketplace add epa-datos/tick-mcp

2. Instala el plugin:

claude plugin install tick-claude

Listo. El plugin ya está instalado. Ahora falta configurar tus credenciales.

---

Configuración inicial — /tick-setup

La primera vez que uses el plugin, ejecuta este comando en Claude:

/tick-setup

Claude te guiará paso a paso:

1. Te pedirá tu API Token de Tickspot. Para encontrarlo: entra a epa-digital39.tickspot.com → haz clic en tu nombre (esquina superior derecha) → Edit Profile → copia el token de la sección API Token.

2. Te pedirá tu correo @epa.digital.

3. Resolverá tu User ID automáticamente — consultará la API de Tickspot y encontrará tu cuenta sin que tengas que buscar nada.

4. Escribirá las variables de entorno en tu shell — sin que tengas que editar archivos manualmente.

5. Conectará tu Google Calendar — se abrirá una ventana del navegador pidiendo autorización de Google. Acéptala y regresa a Claude. Si prefieres no conectarlo, el plugin igualmente funciona y te pedirá tus actividades de forma manual.

Al terminar verás algo como:

Setup completado:
✅ Tickspot — User ID 281096 ([email protected])
✅ Google Calendar — 3 calendarios conectados

Listo para usar. Prueba con /log-today

Si en algún momento necesitas reconectar Google Calendar o cambiar tus credenciales, vuelve a correr /tick-setup.

---

Uso diario

Registrar el día de hoy — /log-today

/log-today

Claude hará lo siguiente sin que tengas que pedirle nada más:

1. Verifica si hoy es festivo en México.
2. Revisa si ya tienes horas registradas para hoy.
3. Lee tus eventos de Google Calendar del día.
4. Asocia cada evento al proyecto y tarea correcta en Tickspot.
5. Te muestra una tabla con las entradas propuestas:

Entradas propuestas para hoy (martes 29 abr):

  #  Proyecto                      Tarea              Horas  Notas
  1  [Datos_Medicion] Analytics    Office Hours        1.5
  2  [SteveMadden_Medicion]        Revisión propuesta  3.0   Nueva GA4
  3  [EPA_DesignSystem] Interno    Dudas / Soporte     1.0

  Total: 5.5h  (faltan 2.5h para completar el día)

¿Creo estas entradas? (sí / modificar / cancelar)

6. Con tu confirmación, crea todas las entradas de una sola vez.

Si ese día no tienes eventos en el calendario, Claude simplemente te pregunta: "¿Qué hiciste hoy?" y acepta cualquier formato de respuesta.

---

Registrar la semana completa — /log-week

/log-week

Hace lo mismo que /log-today pero para todos los días laborables de la semana actual (lunes a hoy). Detecta automáticamente festivos, días ya completos (8h+), y te pregunta una sola vez si hubo días que no trabajaste.

Para la semana pasada:

/log-week semana pasada

---

Ver días con horas faltantes — /check-gaps

/check-gaps

Revisa tu registro de la semana actual y te muestra qué días están completos, incompletos o vacíos:

Reporte de horas — Semana del 28 abr al 2 may

  Lun 28  ✓  8.5h
  Mar 29  ✓  8.0h
  Mié 30  —  [Festivo: Día del Trabajo]
  Jue 1   ⚠  5.0h  ← faltan 3h
  Vie 2   ✗  0.0h  ← vacío

  Total registrado: 21.5h de 32h esperadas
  Días pendientes: 2 (jueves parcial + viernes)

¿Quieres que te ayude a llenar los días pendientes ahora?

Acepta también rangos como semana pasada, este mes, o fechas específicas.

---

Integración con Google Calendar

El plugin lee tu calendario para proponer entradas automáticamente. Así es como funciona el mapeo:

• Identifica el cliente o proyecto por el nombre del evento (por ejemplo, un evento llamado "Weekly Steve Madden" lo asocia al proyecto [SteveMadden_Medicion]).
• Infiere el tipo de tarea según el nombre: juntas se registran como Office Hours, revisiones como Revisión, trabajo técnico como la tarea más específica disponible.
• Si un evento es ambiguo entre dos proyectos posibles, pregunta antes de decidir.
• Los eventos personales o de bloqueo (fuera de horario laboral, sin título de cliente) los omite o te pregunta qué hacer con ellos.

El plugin conoce los patrones de naming del equipo EPA Digital — no necesitas escribir los nombres exactos de los proyectos.

---

Solución de problemas

Los comandos /log-today, /log-week, etc. no aparecen

1. Verifica que el plugin está instalado: claude plugin list
2. Si no aparece tick-claude, vuelve a ejecutar la instalación:

   claude plugin marketplace add epa-datos/tick-mcp
   claude plugin install tick-claude
   

3. Reinicia Claude Code (cierra y vuelve a abrir).

Error al conectar con Tickspot

• Vuelve a correr /tick-setup para renovar tu token.
• Verifica que tu token sea el correcto: entra a tu perfil de Tickspot → Edit Profile → sección API Token.

Google Calendar no se conecta o no encuentra eventos

• Vuelve a correr /tick-setup — Claude intentará reconectar el calendario.
• Si el navegador no abrió la ventana de autorización de Google, prueba correrlo en una terminal nueva.
• El plugin funciona sin Calendar — si no está conectado, Claude te pedirá tus actividades manualmente.

"No se encontraron proyectos" o proyectos desactualizados

El plugin guarda en caché los proyectos y tareas para responder más rápido. Si en Tickspot se crearon proyectos nuevos recientemente, dile a Claude:

"Refresca el caché de Tickspot"

---

Para desarrolladores

Estructura del repositorio

tick-mcp/
├── src/                    # Código fuente del servidor MCP
│   ├── index.ts            # Punto de entrada
│   ├── api/                # Cliente HTTP + autenticación
│   ├── cache/              # Caché híbrida TTL + ETag
│   ├── tools/              # Herramientas expuestas a Claude
│   └── schemas/            # Validación Zod
├── plugin-build/           # Fuente del plugin (comandos, skills, config)
│   ├── commands/           # Definiciones de /log-today, /log-week, etc.
│   ├── skills/log-hours/   # Skill principal con reglas de mapeo
│   └── team-config.json    # Config del equipo (suscripción, zona horaria)
├── dist/                   # Servidor compilado
└── tick-claude.plugin      # Archivo del plugin listo para distribuir

Compilar el servidor

npm install
npm run build        # TypeScript → JavaScript
npm run dev          # Modo watch
npm run inspector    # MCP Inspector para pruebas locales

Publicar una nueva versión del plugin

El archivo tick-claude.plugin es un ZIP que contiene el servidor compilado y los archivos del plugin. Para generar uno nuevo después de cambios:

npm run build
# luego empaquetar plugin-build/ + dist/index.cjs → tick-claude.plugin

Caché del servidor

• Proyectos y clientes: TTL de 30 días + validación ETag
• Tareas: TTL de 7 días + validación ETag
• Entradas de tiempo: sin caché (cambian frecuentemente)

---

Licencia

MIT — Construido con Model Context Protocol de Anthropic.