clokio-mcp 0.19.0 → 0.21.0

package/README.md

@@ -63,8 +63,8 @@ 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 97 tools to 31. Optional groups are `tasks`,
-`employees`, `attendance` (which includes leave and time entries), `docs` and
+task-focused session drops from 98 tools to 32. Optional groups are `tasks`,
+`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,16 +74,16 @@ through it.
 
 ## Tools
 
-97 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 |
 |------|-------|
-| **Tasks** | list (with `compact` / `sort` / `updated_since` / `recurring`), get (with `comments_limit`), create, update (incl. recurring series: set a rule, pause/resume, stop), delete, bulk update, set assignees, list/add/edit comments, list attachments (with `is_latest` + `latest_only`), upload, download one (save to disk, or read PDF text / ZIP entries / images / text inline), download all to a folder, activity, list/add/remove dependencies, set custom field |
+| **Tasks** | list (with `compact` / `sort` / `updated_since` / `recurring`), get (with `comments_limit`), create, update (incl. recurring series: set a rule, pause/resume, stop), delete, bulk update, set assignees (a shared board's client people as `{employee_code, organization_id}`), list a board's people, list/add/edit comments, list attachments (with `is_latest` + `latest_only`), upload, download one (save to disk, or read PDF text / ZIP entries / images / text inline), download all to a folder, activity, list/add/remove dependencies, set custom field |
 | **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 |
 
@@ -92,6 +92,11 @@ are marked mutating (deletes are `destructive`).
 - **People are identified by `employee_code`** (e.g. `00080`), not internal ids.
   Use `clokio_list_employees` (with `search`) to resolve a name to a code, or
   `clokio_lookup_employee_by_pin` for a kiosk PIN.
+- **Shared boards.** On a project shared with a client organisation, its
+  people appear on your tasks with `external: true` and `organization {id,
+  name}`. List them with `clokio_list_project_people` and assign them as
+  `{employee_code, organization_id}`: an employee code is unique only within
+  one organisation, so a bare code always means yours.
 - **Attribution is automatic.** An unnamed write is credited to the key's
   issuer (see `clokio_whoami`), so you rarely set an author. Pass
   `created_by_employee_code` / `author_employee_code` only to credit someone
@@ -112,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/dist/tools/employees.js

@@ -18,6 +18,8 @@ export function registerEmployeeTools(server, config) {
             'wants for assignees, comment authors and task creators. Pass `search` with a name (or part of one) ' +
             'rather than listing everyone and matching yourself. Combine with status=active to skip people who have ' +
             'left. email is returned only if the key holds the employees:pii scope. ' +
+            "It lists the key's OWN organisation only: people of a client organisation on a shared board are not " +
+            'here - get them, with their organization.id, from clokio_list_project_people. ' +
             'Paginated: the response is {data, meta}, the people under data.',
         schema: {
             search: z.string().max(120).optional().describe('Free text over name and employee_code'),

package/dist/tools/tasks.js

@@ -7,6 +7,29 @@ import { asAttachmentArray, downloadAttachment, safeAttachmentName, stampIsLates
 const employeeCode = z
     .string()
     .regex(/^[A-Za-z0-9_-]{1,50}$/, 'employee_code must be 1-50 chars of letters, digits, _ or -');
+/**
+ * One assignee (Clokio Public API, spec 2026-10-16). A STRING is an
+ * employee_code of the key's OWN organisation. On a board shared with a
+ * client organisation, a person of THAT organisation is
+ * {employee_code, organization_id}: codes are unique per organisation only,
+ * so a bare code can never name them and may collide with one of yours.
+ * organization_id is the numeric organization.id clokio_list_project_people
+ * reports, never an organisation login code. .strict(): an extra key is a
+ * mistake the server would refuse, so it is refused here first.
+ */
+export const assigneeReference = z.union([
+    employeeCode,
+    z
+        .object({
+        employee_code: employeeCode,
+        organization_id: z.number().int().positive(),
+    })
+        .strict(),
+]);
+const SHARED_BOARD_NOTE = 'On a project SHARED with a client organisation, call clokio_list_project_people first: a person whose ' +
+    '`external` is true is assigned as {employee_code, organization_id} (organization.id from that tool), never ' +
+    'by a bare code - a bare code always means YOUR organisation and can collide with theirs. Bare string codes ' +
+    'for your own staff work exactly as before, and the two forms can be mixed in one list.';
 /**
  * Recurrence, as a structured object the agent fills, serialized here into
  * the rule string the Clokio scheduler executes (`daily`, `weekly:sun,wed`,
@@ -176,7 +199,9 @@ export function registerTaskTools(server, config) {
                 .boolean()
                 .optional()
                 .describe('STRONGLY PREFERRED when scanning. Returns a slim row - id, title, status, priority, ' +
-                'due_date, parent_id, project_id, assignee_codes (employee_code strings), labels (names) ' +
+                'due_date, parent_id, project_id, assignee_codes (employee_code strings of YOUR organisation), ' +
+                'external_assignees ([{employee_code, organization_id}] for a client organisation\'s people on a ' +
+                'shared board, [] when none; organization_id null when that organisation is hidden), labels (names) ' +
                 'and updated_at - dropping the HTML description and flattening the nested project/assignee ' +
                 'objects to ids. Resolve a project_id with clokio_list_projects, and fetch the one task you ' +
                 'actually need in full with clokio_get_task (its URL is /tasks/{id}/view).'),
@@ -227,7 +252,10 @@ export function registerTaskTools(server, config) {
         name: 'clokio_get_task',
         description: 'Get one task by id, with its full detail (assignees, labels, status, custom fields, task_url) and ' +
             'its comments. A long-running task can carry dozens of comments: pass comments_limit to keep only the ' +
-            'newest few, or 0 for none. comments_count always reports the real total.',
+            'newest few, or 0 for none. comments_count always reports the real total. Every person in it ' +
+            '(created_by, assignees, comment authors, uploaders) carries organization {id, name} and external: ' +
+            'an employee_code is unique only within one organisation, so pair it with organization.id when ' +
+            'external is true (organization is null when that organisation is hidden from you).',
         schema: {
             id: z.number().int(),
             comments_limit: z
@@ -248,7 +276,9 @@ export function registerTaskTools(server, config) {
             'automatically (whoami shows who that is). Set it only to credit someone OTHER than the key owner. ' +
             'Pass parent_task_id to create it as a SUBTASK of that task ' +
             '(same project, and the parent must not itself be a subtask - one level deep only).\n\n' +
-            RECURRENCE_MODEL_NOTE,
+            RECURRENCE_MODEL_NOTE +
+            '\n\n' +
+            SHARED_BOARD_NOTE,
         schema: {
             project_id: z.number().int(),
             title: z.string().max(255),
@@ -259,7 +289,11 @@ export function registerTaskTools(server, config) {
             start_date: z.string().optional().describe('YYYY-MM-DD'),
             estimated_hours: z.number().min(0).max(9999.99).optional(),
             parent_task_id: z.number().int().optional().describe('Makes this a subtask of that task'),
-            assignee_employee_codes: z.array(employeeCode).max(50).optional(),
+            assignee_employee_codes: z
+                .array(assigneeReference)
+                .max(50)
+                .optional()
+                .describe('Each a code of your organisation, or {employee_code, organization_id} for a client\'s person on a shared board'),
             label_names: z
                 .array(z.string().max(100))
                 .max(20)
@@ -401,10 +435,16 @@ export function registerTaskTools(server, config) {
         name: 'clokio_set_task_assignees',
         mutates: true,
         description: "Change a task's assignees. mode is REQUIRED: \"add\" appends, \"replace\" overwrites the whole list, " +
-            '"remove" takes those people off. People are named by employee_code (e.g. "00080").',
+            '"remove" takes those people off. People are named by employee_code (e.g. "00080"). Adding someone ' +
+            'already assigned leaves the assignee list and the activity log unchanged. Assigning through the API sends the assignee no notification.\n\n' +
+            SHARED_BOARD_NOTE,
         schema: {
             id: z.number().int(),
-            employee_codes: z.array(employeeCode).min(1).max(50),
+            employee_codes: z
+                .array(assigneeReference)
+                .min(1)
+                .max(50)
+                .describe('Each a code of your organisation, or {employee_code, organization_id} for a client\'s person on a shared board'),
             mode: z.enum(['add', 'replace', 'remove']).describe('Required'),
         },
         handler: (args, cfg) => request(cfg, `/tasks/${args.id}/assignees`, {
@@ -412,6 +452,18 @@ export function registerTaskTools(server, config) {
             body: { employee_codes: args.employee_codes, mode: args.mode },
         }),
     });
+    registerTool(server, config, {
+        name: 'clokio_list_project_people',
+        description: "Who is on a project's board: its members and, on a board shared with a client organisation, the client's " +
+            'nominated people and admins (active people only; coding agents are left out). Each row: employee_code, ' +
+            'name, organization {id, name}, external. Your organisation comes first. Call this BEFORE assigning on a ' +
+            'shared board: an external person is assigned as {employee_code, organization_id} (organization.id from ' +
+            'here). Your own staff who are not board members are still assignable by bare employee_code ' +
+            '(clokio_list_employees). email appears on your own rows only, and only with the employees:pii scope. ' +
+            'Needs the employees:read scope.',
+        schema: { project_id: z.number().int() },
+        handler: (args, cfg) => request(cfg, `/projects/${args.project_id}/people`),
+    });
     registerTool(server, config, {
         name: 'clokio_list_task_comments',
         description: 'List the comments on a task.',

package/package.json

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