clokio-mcp 0.27.0 → 0.28.0

package/README.md

@@ -65,7 +65,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 127 tools to 40. Optional groups are `tasks`,
+task-focused session drops from 129 tools to 42. 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
@@ -76,13 +76,13 @@ through it.
 
 ## Tools
 
-127 tools across seven areas. Read-only tools carry the MCP `readOnlyHint`; writes
+129 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` / `updated_before` / `recurring`, no due date, no assignee, a custom field value, title-only search), a project's task summary (counts by status / priority / label / assignee, overdue and stale lists, per option of a release dropdown: `clokio_get_project_task_summary`), a project's activity log (`clokio_list_project_activity`), get (with `comments_limit`; names the ticket a task was opened from), create, update (incl. recurring series: set a rule, pause/resume, stop; labels: replace, add, remove; parent task; assignees in the same call), delete, bulk update (status, priority, due date, estimate, add / remove labels), 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, read images pasted into descriptions and comments, activity (with organisations, paged), list/add/remove dependencies, set custom field (an option by value or label), set custom fields on many tasks (`clokio_bulk_set_task_custom_field`, partial success); `clokio_update_task` takes `custom_fields` too |
-| **Projects & clients** | list projects, project statuses (and create / edit them), project custom fields (and create / edit them, e.g. a release dropdown), project contacts, get client, add client contact |
+| **Tasks** | list (with `compact` / `fields` / `sort` / `updated_since` / `updated_before` / `recurring`, no due date, no assignee, a custom field value, title-only search), a project's task summary (counts by status / priority / label / assignee, overdue and stale lists, per option of a release dropdown: `clokio_get_project_task_summary`), a project's activity log (`clokio_list_project_activity`), get (with `comments_limit`; names the ticket a task was opened from), create, update (incl. recurring series: set a rule, pause/resume, stop; labels: replace, add, remove; parent task; assignees in the same call), delete, bulk update (status, priority, due date, estimate, add / remove labels), 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, read images pasted into descriptions and comments, activity (with organisations, paged), list/add/remove dependencies, set custom field (an option by value or label), set custom fields on many tasks (`clokio_bulk_set_task_custom_field`, partial success); `clokio_update_task` takes `custom_fields` too |
+| **Projects & clients** | list projects, project statuses (and create / edit / delete them; a status in use moves its tasks to `move_to`), project custom fields (and create / edit / delete them, e.g. a release dropdown; a delete removes the stored values too), 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; with the tickets toolset, also the acting employee's open tickets), create, set status |
 | **Attendance** | daily, range, per-employee, monthly summary, clock in/out, break start/end, time entries (local times in the person's zone; edit / delete your own), leaves (with `days`, half days counted 0.5), days of leave taken per type and year (`clokio_get_leave_days_taken`; the old name `clokio_get_leave_balances` still works; Clokio tracks no quota or remaining balance; leave and time-entry lists take `employee_code` and at most 92 days per call), **log time on a task**, start / stop / read the timer (see [Logging time](#logging-time)) |

package/dist/tools/attendance.js

@@ -56,7 +56,10 @@ export function entryClock(e, opts = {}) {
  */
 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';
+    // An entry may be on a project with no task (task #5775): name the project then.
+    const task = e?.task
+        ? `task #${e.task.id} ${e.task.title}`
+        : e?.project?.name ? `no task, project ${e.project.name}` : 'no task';
     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)";
@@ -405,19 +408,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 +451,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,12 +463,16 @@ 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 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'),
         },
@@ -466,7 +481,7 @@ export function registerAttendanceTools(server, config) {
             try {
                 return withEntryLine(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 +517,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 +528,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'),

package/dist/tools/projects.js

@@ -32,7 +32,8 @@ export function registerProjectTools(server, config) {
     });
     // ── Board configuration writes (0.27.0, backend #5874 part 4) ──
     // projects:write. Every rule is the web editor's own copy on the server;
-    // nothing is judged here beyond the shapes. No delete in this version.
+    // nothing is judged here beyond the shapes. Delete since 0.27.1 (backend
+    // #5874 QA round 1), with the web's delete rules on the server.
     const fieldOptions = z
         .array(z.object({
         value: z.string().min(1).max(100).describe('The stored value tasks hold; keep it stable'),
@@ -158,8 +159,8 @@ export function registerProjectTools(server, config) {
         mutates: true,
         description: 'Edit a project status by its slug (clokio_get_project_statuses): rename (the slug stays), recolour, ' +
             'move (position, 0-based; the completed status stays last) or change category. A status cannot become ' +
-            'a second completed one, and the completed one cannot become active. Statuses cannot be deleted ' +
-            'through the API. Needs the projects:write scope.',
+            'a second completed one, and the completed one cannot become active. To remove a status use ' +
+            'clokio_delete_project_status. Needs the projects:write scope.',
         schema: {
             project_id: z.number().int(),
             slug: z.string().regex(/^[A-Za-z0-9_-]{1,100}$/, 'slug: letters, digits, _ or -'),
@@ -184,6 +185,70 @@ export function registerProjectTools(server, config) {
             return request(cfg, `/projects/${args.project_id}/statuses/${args.slug}`, { method: 'PATCH', body });
         },
     });
+    registerTool(server, config, {
+        name: 'clokio_delete_project_status',
+        mutates: 'destructive',
+        description: 'Delete a project status by its slug (clokio_get_project_statuses), with the web editor\'s rules. The ' +
+            'DEFAULT status (where new tasks start) and the COMPLETED status cannot be deleted. When tasks still use ' +
+            'the status, move_to is REQUIRED: another slug of the same project, of the SAME kind (an active status ' +
+            'for an active one); every task on the deleted status ' +
+            '(deleted tasks included) moves there in the same step, and each move is written to that task\'s ' +
+            'activity log, credited to the actor. Without move_to the server answers how many tasks use it and ' +
+            'deletes nothing. A project still using the organisation\'s statuses gets its own copy only when the ' +
+            'delete happens, so no other project changes. Needs the projects:write scope.',
+        schema: {
+            project_id: z.number().int(),
+            slug: z.string().regex(/^[A-Za-z0-9_-]{1,100}$/, 'slug: letters, digits, _ or -'),
+            move_to: z
+                .string()
+                .regex(/^[A-Za-z0-9_-]{1,100}$/, 'move_to: a status slug')
+                .optional()
+                .describe('Where the tasks on this status go: another slug of the same project. Required when any task uses it'),
+            actor_employee_code: actorCode,
+        },
+        handler: (args, cfg) => {
+            if (args.move_to !== undefined && args.move_to === args.slug) {
+                throw new Error('move_to must be another status, not the one being deleted.');
+            }
+            const body = {};
+            if (args.move_to !== undefined)
+                body.move_to = args.move_to;
+            const actor = args.actor_employee_code ?? cfg.defaultActor;
+            if (actor)
+                body.actor_employee_code = actor;
+            return request(cfg, `/projects/${args.project_id}/statuses/${args.slug}`, { method: 'DELETE', body });
+        },
+    });
+    registerTool(server, config, {
+        name: 'clokio_delete_project_custom_field',
+        mutates: 'destructive',
+        description: 'Delete a project custom field by its field_key, with the web editor\'s rule: the field is removed ' +
+            'TOGETHER WITH every value stored for it on every task, and this cannot be undone; there is no archive. ' +
+            'A field that holds any value needs confirm: true: without it the server answers how many tasks hold a ' +
+            'value and deletes nothing. A field with no values deletes without confirm. The answer says how many ' +
+            'tasks held a value (affected_task_count). Check usage first with clokio_list_tasks custom_field or ' +
+            'clokio_get_project_task_summary group_by_custom_field when that matters. A private field answers not ' +
+            'found. Needs the projects:write scope.',
+        schema: {
+            project_id: z.number().int(),
+            field_key: z.string().regex(FIELD_KEY_PATTERN, 'field_key: letters, digits, _ or -'),
+            confirm: z
+                .boolean()
+                .optional()
+                .describe('true = delete the field AND every value stored for it. Required when the field holds any value; ' +
+                'omit it first to learn how many tasks hold one'),
+            actor_employee_code: actorCode,
+        },
+        handler: (args, cfg) => {
+            const body = {};
+            if (args.confirm !== undefined)
+                body.confirm = args.confirm;
+            const actor = args.actor_employee_code ?? cfg.defaultActor;
+            if (actor)
+                body.actor_employee_code = actor;
+            return request(cfg, `/projects/${args.project_id}/custom-fields/${args.field_key}`, { method: 'DELETE', body });
+        },
+    });
     registerTool(server, config, {
         name: 'clokio_get_project_contacts',
         description: "The contacts for a project's client.",

package/dist/tools/tasks.js

@@ -337,6 +337,25 @@ export function withLinkedTicket(task) {
  * 422 are refused here first, in the same words, so no request is spent on
  * them.
  */
+/**
+ * The keys `fields` may name on GET /tasks (0.27.1, backend #5874 QA round 1):
+ * the compact row's keys plus custom_fields. The server's own list is
+ * PublicTaskResource::SELECTABLE_FIELDS; an unknown name is its 422.
+ */
+export const TASK_LIST_FIELDS = [
+    'id',
+    'title',
+    'status',
+    'priority',
+    'due_date',
+    'parent_id',
+    'project_id',
+    'assignee_codes',
+    'external_assignees',
+    'labels',
+    'updated_at',
+    'custom_fields',
+];
 export function listFilterQuery(args) {
     if (args.no_due_date === true && (args.due_before !== undefined || args.due_after !== undefined)) {
         throw new Error('no_due_date=true cannot be combined with due_before or due_after: a task with no due date is never due before or after anything. Drop one of them.');
@@ -456,6 +475,14 @@ export function registerTaskTools(server, config) {
                 '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).'),
+            fields: z
+                .array(z.enum(TASK_LIST_FIELDS))
+                .min(1)
+                .max(TASK_LIST_FIELDS.length)
+                .optional()
+                .describe('Return ONLY these keys per row, in this order (implies compact), e.g. ["id", "title", "status"]. ' +
+                'Allowed: ' + TASK_LIST_FIELDS.join(', ') + '. custom_fields is the full row\'s object of public ' +
+                'field values. The smallest scan there is.'),
             sort: z
                 .enum([
                 'due_date',
@@ -497,6 +524,7 @@ export function registerTaskTools(server, config) {
                 cursor: args.cursor,
                 sort: args.sort,
                 compact: args.compact === undefined ? undefined : args.compact ? 1 : 0,
+                fields: args.fields === undefined ? undefined : [...new Set(args.fields)].join(','),
             },
         }),
     });

package/package.json

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