clokio-mcp 0.20.0 → 0.21.0

package/README.md

@@ -64,7 +64,7 @@ acting. An explicit code on a tool call always takes precedence.
 Optional: set `CLOKIO_TOOLSETS` to register only the tool groups you need, e.g.
 `CLOKIO_TOOLSETS=tasks`. This cuts the per-session tool-list cost - a
 task-focused session drops from 98 tools to 32. Optional groups are `tasks`,
-`employees`, `attendance` (which includes leave and time entries), `docs` and
+`employees`, `attendance` (which includes leave, time entries and logging time), `docs` and
 `tickets`;
 combine them with commas. If your key cannot open documents (no acts-as
 employee and no explicit docs scopes), leaving `docs` out saves 33 tools it
@@ -74,7 +74,7 @@ through it.
 
 ## Tools
 
-98 tools across seven areas. Read-only tools carry the MCP `readOnlyHint`; writes
+102 tools across seven areas. Read-only tools carry the MCP `readOnlyHint`; writes
 are marked mutating (deletes are `destructive`).
 
 | Area | Tools |
@@ -83,7 +83,7 @@ are marked mutating (deletes are `destructive`).
 | **Projects & clients** | list projects, project statuses, project custom fields, project contacts, get client, add client contact |
 | **Reference** | task statuses, task labels, locations, list webhooks (read-only), whoami |
 | **Employees** | list (name search), lookup by PIN, task-stats, inbox (mentions, new assignments, others' status changes), create, set status |
-| **Attendance** | daily, range, per-employee, monthly summary, clock in/out, break start/end, time entries, leaves, leave balances |
+| **Attendance** | daily, range, per-employee, monthly summary, clock in/out, break start/end, time entries, leaves, leave balances, **log time on a task**, start / stop / read the timer (see [Logging time](#logging-time)) |
 | **Documents** (see [Documents](#documents) for who a key acts as) | list, tree, search, get (Markdown / HTML / JSON), create, replace content, update meta, move, archive, restore, delete, templates + create from template, members (by `employee_code`) and teams (list/add/update/remove, shareable teams), public share link, comments (list/add/resolve/reopen), versions (list/get/restore), attachments (list/upload/download) |
 | **Tickets** (see [Tickets](#tickets)) | list (filters + cursor), get (with its newest messages; internal notes labelled, everything the customer wrote wrapped as untrusted), more messages, **reply to the customer** (fresh `Idempotency-Key` per call, `destructive`), internal note (with mentions), update state / assignee, add / remove one label, contacts list / get / update, inboxes, ticket labels, saved replies |
 
@@ -117,6 +117,28 @@ are marked mutating (deletes are `destructive`).
   returns every occurrence of one series.
 - An API key sees **public custom fields only**.
 
+## Logging time
+
+`clokio_log_time`, `clokio_start_timer`, `clokio_stop_timer` and
+`clokio_get_active_timer` (0.21.0) call `/api/v1/time-entries` and
+`/api/v1/timer/*`. The time is **always the key's acting person's** (its
+"acts as" employee, else the person who issued it); no tool takes an
+employee and the server refuses one.
+
+- **Scopes:** `time_entries:write` for the three writes, `time_entries:read`
+  for the running timer. `time_entries:write` must be ticked on the key
+  explicitly: full access (`*`) never grants it.
+- `clokio_log_time` takes `task_id` and EITHER `date` + `start` + `end`,
+  `date` + `start` + `duration_minutes`, or `duration_minutes` alone (the
+  entry then ends now). Times are local to that person. At most 12 hours per
+  entry; nothing may start or end more than 10 minutes in the future; an
+  overlap with another time entry of the same person (their running timer and
+  an overnight entry from the day before included) is refused.
+- `clokio_start_timer` is refused while a timer runs; `force: true` stops it
+  and starts the new one. `clokio_stop_timer` is refused when nothing runs.
+- The task must be visible to that person, on an active project of your
+  organisation; a board another organisation shared with you is refused.
+
 ## Documents
 
 The Docs tools call `/api/v1/docs...` with the same `CLOKIO_API_KEY` as

package/dist/tools/attendance.js

@@ -183,6 +183,89 @@ export function registerAttendanceTools(server, config) {
             },
         }),
     });
+    // Logging time (backend task #5775). The time is ALWAYS the key's acting
+    // person's: none of these tools takes an employee, and the server refuses
+    // one in the body. Scope time_entries:write is explicit-only ("*" never
+    // grants it).
+    const actingPerson = "The time is ALWAYS recorded for the API key's ACTING person (its \"acts as\" employee, else the person who issued it), " +
+        'never for anyone else; there is no way to log time for another employee. ' +
+        'Needs the time_entries:write scope, ticked explicitly on the key: full access ("*") does NOT grant it.';
+    const taskRule = 'The task must be one that person can view in your organisation, on an active project; a board another organisation ' +
+        'shared with you is refused (404).';
+    registerTool(server, config, {
+        name: 'clokio_log_time',
+        description: 'Log a finished time entry on a task. ' + actingPerson + ' ' +
+            'Times are local to that person (their location timezone, else UTC). Give EITHER date + start + end ' +
+            '(an end at or before start runs past midnight), OR date + start + duration_minutes, OR duration_minutes alone ' +
+            '(the entry then ENDS NOW and started that many minutes ago; date must be today or omitted). ' +
+            'At most 12 hours (720 minutes) per entry; nothing may start or end more than 10 minutes in the future; ' +
+            'an entry overlapping another time entry of the same person (including their running timer, and an overnight entry from the day before) is refused. ' +
+            'A duration counts real minutes across a DST change. ' + taskRule + ' ' +
+            "The project's billable flag is inherited and the description defaults to the task title.",
+        schema: {
+            task_id: z.number().int().positive(),
+            date: z.string().regex(/^\d{4}-\d{2}-\d{2}$/, 'date must be YYYY-MM-DD').optional()
+                .describe('YYYY-MM-DD, the day the entry STARTS. Required with start'),
+            start: z.string().regex(/^\d{2}:\d{2}$/, 'start must be HH:MM').optional().describe('HH:MM, local time'),
+            end: z.string().regex(/^\d{2}:\d{2}$/, 'end must be HH:MM').optional()
+                .describe('HH:MM, local time. Give end OR duration_minutes, not both'),
+            duration_minutes: z.number().int().min(1).max(720).optional(),
+            description: z.string().max(255).optional(),
+        },
+        mutates: true,
+        handler: (args, cfg) => {
+            if ((args.end === undefined) === (args.duration_minutes === undefined)) {
+                throw new Error('Give exactly one of end or duration_minutes.');
+            }
+            if (args.start !== undefined && args.date === undefined) {
+                throw new Error('date is required with start.');
+            }
+            if (args.end !== undefined && args.start === undefined) {
+                throw new Error('start is required with end.');
+            }
+            return request(cfg, '/time-entries', {
+                method: 'POST',
+                body: {
+                    task_id: args.task_id,
+                    date: args.date,
+                    start: args.start,
+                    end: args.end,
+                    duration_minutes: args.duration_minutes,
+                    description: args.description,
+                },
+            });
+        },
+    });
+    registerTool(server, config, {
+        name: 'clokio_start_timer',
+        description: "Start a running timer on a task. " + actingPerson + ' ' + taskRule + ' ' +
+            'If a timer is already running the call is refused (409) and the running entry is returned; ' +
+            'pass force: true to stop that timer and start this one. The description defaults to the task title.',
+        schema: {
+            task_id: z.number().int().positive(),
+            description: z.string().max(255).optional(),
+            force: z.boolean().optional().describe('Stop a running timer first instead of being refused'),
+        },
+        mutates: true,
+        handler: (args, cfg) => request(cfg, '/timer/start', {
+            method: 'POST',
+            body: { task_id: args.task_id, description: args.description, force: args.force },
+        }),
+    });
+    registerTool(server, config, {
+        name: 'clokio_stop_timer',
+        description: "Stop the running timer of the API key's ACTING person (never anyone else's) and return the entry with its hours. " +
+            'Refused (409) when nothing is running. Needs time_entries:write (not granted by "*").',
+        schema: {},
+        mutates: true,
+        handler: (_args, cfg) => request(cfg, '/timer/stop', { method: 'POST' }),
+    });
+    registerTool(server, config, {
+        name: 'clokio_get_active_timer',
+        description: "The running timer of the API key's ACTING person, or entry: null when none runs. Needs time_entries:read.",
+        schema: {},
+        handler: (_args, cfg) => request(cfg, '/timer/active'),
+    });
     registerTool(server, config, {
         name: 'clokio_list_leaves',
         description: 'Leave requests in a date range. from and to are both REQUIRED (YYYY-MM-DD, to >= from). ' +

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "clokio-mcp",
-  "version": "0.20.0",
+  "version": "0.21.0",
   "description": "Model Context Protocol (MCP) server for Clokio - manage tasks, projects, clients, employees, attendance and documents from Claude and any MCP client.",
   "type": "module",
   "bin": {