# kimai-task-tracker-mcp

Servidor MCP (Model Context Protocol) para gestionar tareas de un proyecto Kimai y documentar el tiempo invertido. Una tarea es una **Activity** de Kimai; su estado se codifica en el nombre con la convención `[TODO]` / `[DONE]`, y "en curso" se infiere de un timesheet activo.

Publicado en npm como **`@byteflowsivar/kimai-task-tracker-mcp`**.

## Requisitos

- Node.js >= 18
- Una instancia de Kimai con API habilitada y un token de API

## Configuración

El servidor se configura con variables de entorno, que el cliente MCP debe inyectar (el server no lee `.env`). Faltan las requeridas, aborta con un mensaje claro.

| Variable | Obligatoria | Descripción |
|----------|-------------|-------------|
| `KIMAI_URL` | sí | URL base de Kimai **sin** `/api`, p. ej. `https://kimai.ejemplo.com` |
| `KIMAI_PROJECT_ID` | sí | ID del proyecto cuyas tareas gestiona el servidor (entero) |
| `KIMAI_API_TOKEN` | sí | Token de API de Kimai (secret, nunca se loguea) |
| `KIMAI_READ_ONLY` | no | `true` expone solo las tools de lectura |

## Cómo obtener `KIMAI_PROJECT_ID`

1. Abrí la app de Kimai y navegá al proyecto.
2. La URL tiene la forma `https://kimai.ejemplo.com/en/<cliente>/<proyecto>/...`. El ID no aparece en la URL.
3. Consultalo con la API: `GET https://kimai.ejemplo.com/api/projects` con el header `X-AUTH-USER`/`X-AUTH-TOKEN` (o `Authorization: Bearer <token>`), o desde `Administración > API`.

## Instalación

### Desde npm (producción)

```bash
npm install -g @byteflowsivar/kimai-task-tracker-mcp
```

### Desde el repositorio (desarrollo)

```bash
pnpm install
pnpm build
```

## Uso en desarrollo

```bash
KIMAI_URL=https://kimai.ejemplo.com \
KIMAI_PROJECT_ID=1 \
KIMAI_API_TOKEN=tu_token \
pnpm dev
```

## Registro en un cliente MCP

La forma más simple es ejecutar el paquete con `npx`, que lo descarga automáticamente sin instalación global:

```json
{
  "mcpServers": {
    "kimai-task-tracker": {
      "command": "npx",
      "args": ["-y", "@byteflowsivar/kimai-task-tracker-mcp"],
      "env": {
        "KIMAI_URL": "https://kimai.ejemplo.com",
        "KIMAI_PROJECT_ID": "1",
        "KIMAI_API_TOKEN": "tu_token",
        "KIMAI_READ_ONLY": "false"
      }
    }
  }
}
```

Si preferís instalarlo globalmente, el binario `kimai-task-tracker` queda disponible en el `PATH`:

```json
{
  "mcpServers": {
    "kimai-task-tracker": {
      "command": "kimai-task-tracker",
      "env": {
        "KIMAI_URL": "https://kimai.ejemplo.com",
        "KIMAI_PROJECT_ID": "1",
        "KIMAI_API_TOKEN": "tu_token",
        "KIMAI_READ_ONLY": "false"
      }
    }
  }
}
```

También podés apuntar `command` a `node` y `args` a la ruta del `dist/index.js` del paquete:

```json
{
  "mcpServers": {
    "kimai-task-tracker": {
      "command": "node",
      "args": ["/ruta/al/paquete/dist/index.js"],
      "env": {
        "KIMAI_URL": "https://kimai.ejemplo.com",
        "KIMAI_PROJECT_ID": "1",
        "KIMAI_API_TOKEN": "tu_token",
        "KIMAI_READ_ONLY": "false"
      }
    }
  }
}
```

## Uso con opencode

El repo incluye un `opencode.json` que registra el servidor MCP **solo para este proyecto**. Las variables van directamente en el bloque `environment` (así el usuario no necesita exportarlas ni tener el paquete instalado globalmente):

```json
{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "kimai-task-tracker": {
      "type": "local",
      "command": ["npx", "-y", "@byteflowsivar/kimai-task-tracker-mcp"],
      "environment": {
        "KIMAI_URL": "https://kimai.ejemplo.com",
        "KIMAI_PROJECT_ID": "1",
        "KIMAI_API_TOKEN": "tu_token"
      },
      "enabled": true
    }
  }
}
```

> ⚠️ **Seguridad**: `opencode.json` contiene el `KIMAI_API_TOKEN` real, así que está en `.gitignore` y no se commitea. Al clonar el repo, creá tu propio `opencode.json` con tus valores (podés copiar el bloque de arriba).

Tras reiniciar opencode, el server `kimai-task-tracker` aparece con sus 10 tools; probá `list_tasks` para verificar la conexión.

## Tools

| Tool | Lectura/Escritura | Descripción |
|------|-------------------|-------------|
| `list_tasks` | lectura | Lista las tareas del proyecto con estado (`todo`, `in_progress`, `done`) y tiempo registrado. Filtros `estado` y `term`. |
| `create_task` | escritura | Crea una tarea (`POST /api/activities`). El nombre se normaliza a `[TODO] ...`. |
| `mark_task_done` | escritura | Renombra a `[DONE] ...`. Idempotente. |
| `reopen_task` | escritura | Renombra a `[TODO] ...`. Idempotente. |
| `start_task` | escritura | Inicia un timer. Rechaza si la tarea ya tiene un registro en curso. |
| `stop_timesheet` | escritura | Detiene el registro activo (o uno específico con `timesheet_id`). |
| `log_time` | escritura | Registra tiempo manual con `inicio`/`fin` explícitos. Valida `inicio < fin`. |
| `get_task_time` | lectura | Registros de una tarea y su suma de duración. |
| `get_project_summary` | lectura | Total del proyecto y desglose por tarea, con rango `desde`/`hasta` opcional. |
| `list_tags` | lectura | Lista los tags existentes. |

Con `KIMAI_READ_ONLY=true` solo se exponen las tools de lectura.

## Desarrollo

```bash
pnpm types        # regenera src/types.ts desde openapi/openapi.json
pnpm test         # corre vitest
pnpm typecheck    # typecheck de TypeScript strict
pnpm build        # compila a dist/ (sin tests)
```

## Publicación

El paquete se publica en npm bajo la org **`@byteflowsivar`**. Requiere:

- Estar logueado en npm: `npm login`
- Ser owner de la org `byteflowsivar`: `npm org ls byteflowsivar`

### Paso a paso

```bash
pnpm release patch   # 0.1.0 → 0.1.1
pnpm release minor   # 0.1.0 → 0.2.0
pnpm release major   # 0.1.0 → 1.0.0
```

El script `release.sh` hace lo siguiente:

1. **Bump de versión** con `npm version <tipo> --no-git-tag-version`.
2. **Valida el tarball** con `npm pack --dry-run` (solo `dist/`, `README.md` y `package.json`; nunca `.env` ni `src/`).
3. **Publica** con `npm publish`, que ejecuta automáticamente el `prepublishOnly` (`typecheck` → `test` → `build`). Si alguno falla, no se publica nada.
4. **Verifica** la versión publicada con `npm view`.

> Nota: el script bumpea el `version` de `package.json` pero no crea un commit ni un tag de git. Creá el commit/tag después del release si lo querés versionar también en el repo.

## Licencia

MIT — ver [LICENSE](LICENSE).

## Notas

- Los tags solo se aceptan en el registro de tiempo (`start_task`/`log_time`), porque Kimai no soporta tags en activities.
- Kimai responde `200` en `POST`/`PATCH` (no `201`). El cliente maneja errores `401`/`403`/`404`/`422` con el detalle de Kimai.