clokio-mcp 0.27.1 → 0.28.1

package/dist/tools/attendance.js

@@ -54,9 +54,20 @@ export function entryClock(e, opts = {}) {
  * The zone is the entry's `timezone` (local times) or UTC (an older server).
  * `zone: false` drops a local entry's zone, for a page whose header names it once.
  */
+/**
+ * What an entry is on, in words: its task, else its project (task #5775: an
+ * entry may be on a project with no task), else nothing. ONE copy for every
+ * line that names it (timeEntryLine, clokio_delete_time_entry), so they
+ * cannot drift (MCP QA 0.28.0).
+ */
+export function entryTarget(e) {
+    if (e?.task)
+        return `task #${e.task.id} ${e.task.title}`;
+    return e?.project?.name ? `no task, project ${e.project.name}` : 'no task';
+}
 export function timeEntryLine(e, opts = {}) {
     const id = e?.id === undefined || e?.id === null ? '(no id: server older than 2026-10-16)' : `#${e.id}`;
-    const task = e?.task ? `task #${e.task.id} ${e.task.title}` : 'no task';
+    const task = entryTarget(e);
     return `${id} ${e?.date ?? '-'} ${entryClock(e, opts)} ${e?.work_hour ?? 0}h | ${e?.employee_code ?? '-'} | ${task} | ${e?.description ?? ''}`;
 }
 const ZONE_NOTE = "the person's CURRENT location zone, which clokio_update_time_entry reads date/start/end in (after a location change it may differ from where the entry was logged)";
@@ -208,6 +219,21 @@ export function withShortEntryWarning(res) {
     return { ...res, warning };
 }
 /** #3: the line clokio_stop_timer adds when the stopped entry lasted under a minute, else null. */
+/**
+ * clokio_start_timer's answer: the entry line, and when force: true stopped a
+ * running timer (the server's `stopped_entry`, backend 2026-10-21), a
+ * "Stopped first" line naming it and, for one under a minute, the same
+ * warning clokio_stop_timer gives (MCP QA 0.28.0). An older server sends no
+ * stopped_entry and the answer is as before.
+ */
+export function withStoppedFirst(res) {
+    const out = withEntryLine(res);
+    const stopped = res?.stopped_entry;
+    if (!stopped || typeof stopped !== 'object' || out === null || typeof out !== 'object' || Array.isArray(out))
+        return out;
+    const warning = shortEntryWarning(stopped);
+    return { ...out, stopped_first: `Stopped first: ${timeEntryLine(stopped)}`, ...(warning ? { warning } : {}) };
+}
 export function shortEntryWarning(entry) {
     const a = Date.parse(entry?.check_in ?? '');
     const b = Date.parse(entry?.check_out ?? '');
@@ -405,19 +431,26 @@ export function registerAttendanceTools(server, config) {
         'Needs the time_entries:write scope: Full access includes it; a key with chosen permissions must list 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).';
+    const targetRule = 'WHAT THE TIME IS ON, like the web Timer page (both optional): task_id, project_id, both, or neither. ' +
+        'Neither = a personal entry with no project (not billable). project_id alone = on that project with no task. ' +
+        "Both = the task decides and project_id must be the task's own project (refused otherwise). " +
+        "A project must be an active project of your organisation (clokio_list_projects). Entries hold no client: to log time for a client, use one of the client's projects. " +
+        taskRule;
     registerTool(server, config, {
         name: 'clokio_log_time',
-        description: 'Log a finished time entry on a task. ' + actingPerson + ' ' +
+        description: 'Log a finished time entry, on a task, a project, or neither. ' + 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. " +
+            'A duration counts real minutes across a DST change. ' + targetRule + ' ' +
+            "The project's billable flag is inherited (no project: not billable) and the description defaults to the task title (empty without a task). " +
             ENTRY_LINE_NOTE,
         schema: {
-            task_id: z.number().int().positive(),
+            task_id: z.number().int().positive().optional().describe('Optional. The task the time is on'),
+            project_id: z.number().int().positive().optional()
+                .describe("Optional. A project of your organisation; with task_id it must be the task's project"),
             date: calendarDate('date').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'),
@@ -441,6 +474,7 @@ export function registerAttendanceTools(server, config) {
                 method: 'POST',
                 body: {
                     task_id: args.task_id,
+                    project_id: args.project_id,
                     date: args.date,
                     start: args.start,
                     end: args.end,
@@ -452,21 +486,26 @@ export function registerAttendanceTools(server, config) {
     });
     registerTool(server, config, {
         name: 'clokio_start_timer',
-        description: "Start a running timer on a task. " + actingPerson + ' ' + taskRule + ' ' +
+        description: 'Start a running timer on a task, a project, or neither (a personal timer). ' + actingPerson + ' ' + targetRule + ' ' +
             '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. ' +
+            'pass force: true to stop that timer and start this one (the answer then names the stopped entry under stopped_first, ' +
+            'with a warning when it lasted under a minute). The description defaults to the task title (empty without a task). ' +
+            'clokio_stop_timer stops any timer; the web Timer page asks for a project and a description before its own Stop, ' +
+            'so give a personal timer a description (and stop it here) if the person may stop it on the web. ' +
             ENTRY_LINE_NOTE,
         schema: {
-            task_id: z.number().int().positive(),
+            task_id: z.number().int().positive().optional().describe('Optional. The task the timer is on'),
+            project_id: z.number().int().positive().optional()
+                .describe("Optional. A project of your organisation; with task_id it must be the task's project"),
             description: z.string().max(255).optional(),
             force: z.boolean().optional().describe('Stop a running timer first instead of being refused'),
         },
         mutates: true,
         handler: async (args, cfg) => {
             try {
-                return withEntryLine(await request(cfg, '/timer/start', {
+                return withStoppedFirst(await request(cfg, '/timer/start', {
                     method: 'POST',
-                    body: { task_id: args.task_id, description: args.description, force: args.force },
+                    body: { task_id: args.task_id, project_id: args.project_id, description: args.description, force: args.force },
                 }));
             }
             catch (e) {
@@ -502,7 +541,10 @@ export function registerAttendanceTools(server, config) {
     registerTool(server, config, {
         name: 'clokio_update_time_entry',
         description: "Correct one of the time entries of the API key's ACTING person (another person's entry is \"Not found\"). " +
-            "Send only what changes: task_id (the entry moves to that task's project), description (null or empty resets it to the task title), " +
+            "Send only what changes: task_id (the entry moves to that task's project; null unlinks the task and keeps the project), " +
+            'project_id (an active project of your organisation, or null to clear it; billable follows the project). ' +
+            "On an entry that is on a task, project_id must be the task's own project: to move it elsewhere send task_id: null with it. " +
+            'description (null or empty resets it to the task title, empty without a task), ' +
             'and/or the time: date (YYYY-MM-DD), start, end (HH:MM, LOCAL to that person) or duration_minutes (alone it keeps the start and sets the length; start alone moves the entry and keeps its length). ' +
             'Parts you leave out keep their current values. The same checks as clokio_log_time: at most 12 hours, nothing in the future, ' +
             'no overlap with another entry of that person (their running timer included); an entry on an inactive project cannot change its time. ' +
@@ -510,7 +552,8 @@ export function registerAttendanceTools(server, config) {
             'Needs time_entries:write.',
         schema: {
             id: z.number().int().positive().describe('The entry id (clokio_list_time_entries)'),
-            task_id: z.number().int().positive().optional(),
+            task_id: z.number().int().positive().nullable().optional().describe('A task to link, or null to unlink the task'),
+            project_id: z.number().int().positive().nullable().optional().describe('A project of your organisation, or null to clear it'),
             date: calendarDate('date').optional(),
             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. Not with duration_minutes'),
@@ -539,8 +582,7 @@ export function registerAttendanceTools(server, config) {
         handler: async (args, cfg) => {
             const res = await request(cfg, `/time-entries/${seg(args.id)}`, { method: 'DELETE' });
             const e = res?.entry ?? {};
-            const task = e.task ? `task #${e.task.id} ${e.task.title}` : 'no task';
-            return `Deleted entry ${e.id ?? args.id}: ${e.date ?? '-'} ${entryClock(e)}, ${task}`;
+            return `Deleted entry ${e.id ?? args.id}: ${e.date ?? '-'} ${entryClock(e)}, ${entryTarget(e)}`;
         },
     });
     registerTool(server, config, {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "clokio-mcp",
-  "version": "0.27.1",
+  "version": "0.28.1",
   "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": {