{"_id":"@byteflowsivar/kimai-task-tracker-mcp","_rev":"2-a63ef2995aadb56b161b51df710d290e","name":"@byteflowsivar/kimai-task-tracker-mcp","dist-tags":{"latest":"0.1.2"},"versions":{"0.1.1":{"name":"@byteflowsivar/kimai-task-tracker-mcp","version":"0.1.1","keywords":["mcp","kimai","time-tracking","timesheet","task-management","model-context-protocol"],"license":"MIT","_id":"@byteflowsivar/kimai-task-tracker-mcp@0.1.1","maintainers":[{"name":"rex2002xp","email":"rex2002xp@gmail.com"}],"bin":{"kimai-task-tracker":"dist/index.js"},"dist":{"shasum":"32e38b136179d84cc3e4623d6a08a26bd7bcc38d","tarball":"https://registry.npmjs.org/@byteflowsivar/kimai-task-tracker-mcp/-/kimai-task-tracker-mcp-0.1.1.tgz","fileCount":27,"integrity":"sha512-4bK1kOsVb9SBSI9o0Wb15zjqXG5IBdswZYsVWhz8jA1+AHxnMGOvWLhO/4uyPbdMqiGf3qgazuLaa7gS/oYaQw==","signatures":[{"sig":"MEQCIE/llABbotNwwEzA2VV23hS7UZ1fv+t10uLqUBs6bFyNAiBe2FCgFWFGYO6nbAZGOMqm0v4iBa2GTzwGZ8zAtNAGlA==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":222847},"type":"module","engines":{"node":">=18"},"gitHead":"d54a3397ba4699bc26cc3d4195f0b418bf267fd2","scripts":{"dev":"tsx src/index.ts","test":"vitest run","build":"tsc -p tsconfig.build.json","types":"openapi-typescript openapi/openapi.json -o src/types.ts","release":"./release.sh","typecheck":"tsc --noEmit","prepublishOnly":"pnpm typecheck && pnpm test && pnpm build"},"_npmUser":{"name":"rex2002xp","email":"rex2002xp@gmail.com"},"_npmVersion":"11.13.0","description":"Servidor MCP para gestionar tareas de un proyecto Kimai y registrar el tiempo invertido","directories":{},"_nodeVersion":"24.15.0","dependencies":{"zod":"^4.4.3","dotenv":"^17.4.2","@modelcontextprotocol/sdk":"^1.12.1"},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"tsx":"^4.19.4","vitest":"^3.2.4","typescript":"^5.8.3","@types/node":"^22.15.30","openapi-typescript":"^7.6.1"},"_npmOperationalInternal":{"tmp":"tmp/kimai-task-tracker-mcp_0.1.1_1785756285798_0.6990213890907833","host":"s3://npm-registry-packages-npm-production"}},"0.1.2":{"name":"@byteflowsivar/kimai-task-tracker-mcp","version":"0.1.2","description":"Servidor MCP para gestionar tareas de un proyecto Kimai y registrar el tiempo invertido","type":"module","bin":{"kimai-task-tracker":"dist/index.js"},"publishConfig":{"access":"public"},"engines":{"node":">=18"},"keywords":["mcp","kimai","time-tracking","timesheet","task-management","model-context-protocol"],"license":"MIT","scripts":{"dev":"tsx src/index.ts","build":"tsc -p tsconfig.build.json","typecheck":"tsc --noEmit","types":"openapi-typescript openapi/openapi.json -o src/types.ts","test":"vitest run","prepublishOnly":"pnpm typecheck && pnpm test && pnpm build","release":"./release.sh"},"dependencies":{"@modelcontextprotocol/sdk":"^1.12.1","zod":"^4.4.3"},"devDependencies":{"@types/node":"^22.15.30","openapi-typescript":"^7.6.1","tsx":"^4.19.4","typescript":"^5.8.3","vitest":"^3.2.4"},"gitHead":"1bc75c510958dc4635145724a846b857922b323e","_id":"@byteflowsivar/kimai-task-tracker-mcp@0.1.2","_nodeVersion":"24.15.0","_npmVersion":"11.13.0","dist":{"integrity":"sha512-zqDsrIPvNG2PT/GK96cfMSPgJVjg7xapgZSHmVF7oun+rqvru059BNTXe0In+43JCXYYGLMorErhc2sEoCo3BQ==","shasum":"1f2649e09fe6c4c3437d1d201a70995b8829fab9","tarball":"https://registry.npmjs.org/@byteflowsivar/kimai-task-tracker-mcp/-/kimai-task-tracker-mcp-0.1.2.tgz","fileCount":27,"unpackedSize":222331,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIQDduDDS6No3zTJfmQGJm9cXVn4E2pXpGBsv3fJxJ7s5KgIgX4fyz4RnuK1Sz6BRjSBJREPPnt2COvKiWu/rJQ8VJxY="}]},"_npmUser":{"name":"rex2002xp","email":"rex2002xp@gmail.com"},"directories":{},"maintainers":[{"name":"rex2002xp","email":"rex2002xp@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/kimai-task-tracker-mcp_0.1.2_1785759449532_0.6212750761051944"},"_hasShrinkwrap":false}},"time":{"created":"2026-08-03T11:24:45.633Z","modified":"2026-08-03T12:17:29.856Z","0.1.1":"2026-08-03T11:24:45.930Z","0.1.2":"2026-08-03T12:17:29.670Z"},"license":"MIT","keywords":["mcp","kimai","time-tracking","timesheet","task-management","model-context-protocol"],"description":"Servidor MCP para gestionar tareas de un proyecto Kimai y registrar el tiempo invertido","maintainers":[{"name":"rex2002xp","email":"rex2002xp@gmail.com"}],"readme":"# kimai-task-tracker-mcp\n\nServidor 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.\n\nPublicado en npm como **`@byteflowsivar/kimai-task-tracker-mcp`**.\n\n## Requisitos\n\n- Node.js >= 18\n- Una instancia de Kimai con API habilitada y un token de API\n\n## Configuración\n\nEl 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.\n\n| Variable | Obligatoria | Descripción |\n|----------|-------------|-------------|\n| `KIMAI_URL` | sí | URL base de Kimai **sin** `/api`, p. ej. `https://kimai.ejemplo.com` |\n| `KIMAI_PROJECT_ID` | sí | ID del proyecto cuyas tareas gestiona el servidor (entero) |\n| `KIMAI_API_TOKEN` | sí | Token de API de Kimai (secret, nunca se loguea) |\n| `KIMAI_READ_ONLY` | no | `true` expone solo las tools de lectura |\n\n## Cómo obtener `KIMAI_PROJECT_ID`\n\n1. Abrí la app de Kimai y navegá al proyecto.\n2. La URL tiene la forma `https://kimai.ejemplo.com/en/<cliente>/<proyecto>/...`. El ID no aparece en la URL.\n3. 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`.\n\n## Instalación\n\n### Desde npm (producción)\n\n```bash\nnpm install -g @byteflowsivar/kimai-task-tracker-mcp\n```\n\n### Desde el repositorio (desarrollo)\n\n```bash\npnpm install\npnpm build\n```\n\n## Uso en desarrollo\n\n```bash\nKIMAI_URL=https://kimai.ejemplo.com \\\nKIMAI_PROJECT_ID=1 \\\nKIMAI_API_TOKEN=tu_token \\\npnpm dev\n```\n\n## Registro en un cliente MCP\n\nLa forma más simple es ejecutar el paquete con `npx`, que lo descarga automáticamente sin instalación global:\n\n```json\n{\n  \"mcpServers\": {\n    \"kimai-task-tracker\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@byteflowsivar/kimai-task-tracker-mcp\"],\n      \"env\": {\n        \"KIMAI_URL\": \"https://kimai.ejemplo.com\",\n        \"KIMAI_PROJECT_ID\": \"1\",\n        \"KIMAI_API_TOKEN\": \"tu_token\",\n        \"KIMAI_READ_ONLY\": \"false\"\n      }\n    }\n  }\n}\n```\n\nSi preferís instalarlo globalmente, el binario `kimai-task-tracker` queda disponible en el `PATH`:\n\n```json\n{\n  \"mcpServers\": {\n    \"kimai-task-tracker\": {\n      \"command\": \"kimai-task-tracker\",\n      \"env\": {\n        \"KIMAI_URL\": \"https://kimai.ejemplo.com\",\n        \"KIMAI_PROJECT_ID\": \"1\",\n        \"KIMAI_API_TOKEN\": \"tu_token\",\n        \"KIMAI_READ_ONLY\": \"false\"\n      }\n    }\n  }\n}\n```\n\nTambién podés apuntar `command` a `node` y `args` a la ruta del `dist/index.js` del paquete:\n\n```json\n{\n  \"mcpServers\": {\n    \"kimai-task-tracker\": {\n      \"command\": \"node\",\n      \"args\": [\"/ruta/al/paquete/dist/index.js\"],\n      \"env\": {\n        \"KIMAI_URL\": \"https://kimai.ejemplo.com\",\n        \"KIMAI_PROJECT_ID\": \"1\",\n        \"KIMAI_API_TOKEN\": \"tu_token\",\n        \"KIMAI_READ_ONLY\": \"false\"\n      }\n    }\n  }\n}\n```\n\n## Uso con opencode\n\nEl 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):\n\n```json\n{\n  \"$schema\": \"https://opencode.ai/config.json\",\n  \"mcp\": {\n    \"kimai-task-tracker\": {\n      \"type\": \"local\",\n      \"command\": [\"npx\", \"-y\", \"@byteflowsivar/kimai-task-tracker-mcp\"],\n      \"environment\": {\n        \"KIMAI_URL\": \"https://kimai.ejemplo.com\",\n        \"KIMAI_PROJECT_ID\": \"1\",\n        \"KIMAI_API_TOKEN\": \"tu_token\"\n      },\n      \"enabled\": true\n    }\n  }\n}\n```\n\n> ⚠️ **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).\n\nTras reiniciar opencode, el server `kimai-task-tracker` aparece con sus 10 tools; probá `list_tasks` para verificar la conexión.\n\n## Tools\n\n| Tool | Lectura/Escritura | Descripción |\n|------|-------------------|-------------|\n| `list_tasks` | lectura | Lista las tareas del proyecto con estado (`todo`, `in_progress`, `done`) y tiempo registrado. Filtros `estado` y `term`. |\n| `create_task` | escritura | Crea una tarea (`POST /api/activities`). El nombre se normaliza a `[TODO] ...`. |\n| `mark_task_done` | escritura | Renombra a `[DONE] ...`. Idempotente. |\n| `reopen_task` | escritura | Renombra a `[TODO] ...`. Idempotente. |\n| `start_task` | escritura | Inicia un timer. Rechaza si la tarea ya tiene un registro en curso. |\n| `stop_timesheet` | escritura | Detiene el registro activo (o uno específico con `timesheet_id`). |\n| `log_time` | escritura | Registra tiempo manual con `inicio`/`fin` explícitos. Valida `inicio < fin`. |\n| `get_task_time` | lectura | Registros de una tarea y su suma de duración. |\n| `get_project_summary` | lectura | Total del proyecto y desglose por tarea, con rango `desde`/`hasta` opcional. |\n| `list_tags` | lectura | Lista los tags existentes. |\n\nCon `KIMAI_READ_ONLY=true` solo se exponen las tools de lectura.\n\n## Desarrollo\n\n```bash\npnpm types        # regenera src/types.ts desde openapi/openapi.json\npnpm test         # corre vitest\npnpm typecheck    # typecheck de TypeScript strict\npnpm build        # compila a dist/ (sin tests)\n```\n\n## Publicación\n\nEl paquete se publica en npm bajo la org **`@byteflowsivar`**. Requiere:\n\n- Estar logueado en npm: `npm login`\n- Ser owner de la org `byteflowsivar`: `npm org ls byteflowsivar`\n\n### Paso a paso\n\n```bash\npnpm release patch   # 0.1.0 → 0.1.1\npnpm release minor   # 0.1.0 → 0.2.0\npnpm release major   # 0.1.0 → 1.0.0\n```\n\nEl script `release.sh` hace lo siguiente:\n\n1. **Bump de versión** con `npm version <tipo> --no-git-tag-version`.\n2. **Valida el tarball** con `npm pack --dry-run` (solo `dist/`, `README.md` y `package.json`; nunca `.env` ni `src/`).\n3. **Publica** con `npm publish`, que ejecuta automáticamente el `prepublishOnly` (`typecheck` → `test` → `build`). Si alguno falla, no se publica nada.\n4. **Verifica** la versión publicada con `npm view`.\n\n> 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.\n\n## Licencia\n\nMIT — ver [LICENSE](LICENSE).\n\n## Notas\n\n- Los tags solo se aceptan en el registro de tiempo (`start_task`/`log_time`), porque Kimai no soporta tags en activities.\n- Kimai responde `200` en `POST`/`PATCH` (no `201`). El cliente maneja errores `401`/`403`/`404`/`422` con el detalle de Kimai.\n","readmeFilename":"README.md"}