clokio-mcp 0.25.0 → 0.26.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 120 tools to 33. Optional groups are `tasks`,
+task-focused session drops from 121 tools to 34. 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,12 +76,12 @@ through it.
 
 ## Tools
 
-120 tools across seven areas. Read-only tools carry the MCP `readOnlyHint`; writes
+121 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`; names the ticket a task was opened from), 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, read images pasted into descriptions and comments, activity (with organisations, paged), list/add/remove dependencies, set custom field |
+| **Tasks** | list (with `compact` / `sort` / `updated_since` / `recurring`), 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), delete, bulk update (status, priority, due date, 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, 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; with the tickets toolset, also the acting employee's open tickets), create, set status |
@@ -117,7 +117,8 @@ are marked mutating (deletes are `destructive`).
   `recurrence.armed` on a task says whether the series is live, a copy names
   its template as `recurrence.spawned_from`, and `series_of` on the list tool
   returns every occurrence of one series.
-- An API key sees **public custom fields only**.
+- An API key sees **public custom fields only**. A dropdown or multi-select
+  value may be the option's value or its label as shown on screen.
 
 ## Logging time
 

package/dist/tools/tasks.js

@@ -7,6 +7,22 @@ import { asAttachmentArray, downloadAttachment, downloadTaskMedia, inlineMediaRo
 const employeeCode = z
     .string()
     .regex(/^[A-Za-z0-9_-]{1,50}$/, 'employee_code must be 1-50 chars of letters, digits, _ or -');
+/**
+ * One custom field value as the API takes it: text / number / date string,
+ * true / false for a checkbox, an option's value OR label for a dropdown, a
+ * list of them for a multi-select, null to clear. The server validates it
+ * against the field's type (backend task #5874 part 2).
+ */
+const customFieldValue = z
+    .union([z.string(), z.number(), z.boolean(), z.array(z.string()), z.null()])
+    .describe('The value; a dropdown option by its value or its label; null clears');
+/** field_key -> value, at least one and at most 50 fields (the server's cap). */
+const customFieldsMap = z
+    .record(z.string().min(1).max(50), customFieldValue)
+    .refine((m) => Object.keys(m).length >= 1 && Object.keys(m).length <= 50, {
+    message: 'custom_fields must name 1-50 fields',
+})
+    .describe('Object of field_key -> value, e.g. {"stage": "In build", "client_po": "PO-1"}');
 /**
  * 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
@@ -178,6 +194,45 @@ const RECURRENCE_MODEL_NOTE = 'RECURRING TASKS: pass `recurrence` to make this t
     'the template (title, description, assignees, labels, priority, estimate) early on each matching day, ' +
     'due that day, independent of whether earlier copies were closed. A multi-period cadence ' +
     '(every: N > 1) counts whole periods from the task\'s DUE DATE, so set one.';
+/**
+ * A label name as the API takes it: the task_labels column is 50 characters
+ * (the backend validates max:50 on every label field since 0.26.0's backend,
+ * task #5874).
+ */
+const labelName = z.string().min(1).max(50);
+/** One names field on update / bulk: up to 50 names (the API's cap). */
+const labelNames = z.array(labelName).max(50).optional();
+/** How labels work on clokio_update_task, said once. */
+const LABELS_ON_UPDATE_NOTE = 'LABELS: `label_names` REPLACES the task\'s whole label set (an empty list removes every label). ' +
+    '`add_label_names` / `remove_label_names` change it instead, keeping the rest. Do not combine ' +
+    '`label_names` with either of them, and do not put one label in both (spellings the organisation treats as ' +
+    'one label count; the server refuses it). An empty list is not a change. A name that does not exist in ' +
+    'your organisation is CREATED (as on clokio_create_task; check clokio_list_task_labels first to reuse ' +
+    'an existing spelling), names match case-insensitively, a remove never creates, and adding a label the ' +
+    'task already carries or removing one it does not carry changes nothing. Up to 50 names per field, ' +
+    '50 characters each. Each change is written to the task\'s activity log, credited like any other edit.';
+/** A diff list that names something; an empty list is not a change (the API ignores it too). */
+export function hasNames(list) {
+    return Array.isArray(list) && list.length > 0;
+}
+/**
+ * Refuse before any request what the API would refuse anyway: replace with a
+ * non-empty diff (update only), and the same name (trimmed, case-folded) in
+ * both diff lists, which the API refuses before any lookup. Accent variants
+ * of an existing label ("Café" / "Cafe") are judged by the API on the
+ * resolved labels, in its own sentence.
+ */
+export function refuseLabelConflicts(args, allowReplace) {
+    if (allowReplace && args.label_names !== undefined && (hasNames(args.add_label_names) || hasNames(args.remove_label_names))) {
+        throw new Error('Pass either label_names (replaces every label) or add_label_names / remove_label_names (a change), not both.');
+    }
+    const fold = (n) => n.trim().toLowerCase();
+    const adding = new Set((args.add_label_names ?? []).map(fold));
+    const both = [...new Set((args.remove_label_names ?? []).filter((n) => adding.has(fold(n))).map((n) => n.trim()))];
+    if (both.length > 0) {
+        throw new Error(`These labels are in both add_label_names and remove_label_names: ${both.join(', ')}. Send each label in one of them.`);
+    }
+}
 /** Task-management tools: the core of the Clokio API surface. */
 /** #5: what clokio_set_task_assignees answers - the id, the link and the people, never the whole task. */
 export function compactAssignees(taskId, t, baseUrl = 'https://app.clokio.io') {
@@ -391,7 +446,7 @@ export function registerTaskTools(server, config) {
                 .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))
+                .array(labelName)
                 .max(20)
                 .optional()
                 .describe('Label names. A name that does not exist yet is CREATED - check clokio_list_task_labels first'),
@@ -450,7 +505,12 @@ export function registerTaskTools(server, config) {
             '\n\nManage an existing series here: `recurrence` (an object) sets or retunes the rule and switches ' +
             'the series ON; `recurrence: null` STOPS it (future copies stop; already-spawned copies are ordinary ' +
             'tasks and stay). To PAUSE while keeping the rule stored, pass `recurrence_active: false`, and ' +
-            '`recurrence_active: true` to resume.',
+            '`recurrence_active: true` to resume.\n\n' +
+            LABELS_ON_UPDATE_NOTE +
+            '\n\n' +
+            '`custom_fields` (object field_key -> value) sets several custom fields in the same call, with the ' +
+            'rules of clokio_set_task_custom_field (option labels accepted, null clears). Every field is checked ' +
+            'before anything is written: one bad field refuses the whole update and nothing changes.',
         schema: {
             id: z.number().int(),
             title: z.string().max(255).optional(),
@@ -470,6 +530,10 @@ export function registerTaskTools(server, config) {
                 .boolean()
                 .optional()
                 .describe('Pause (false) / resume (true) the series without touching its stored rule'),
+            label_names: labelNames.describe('REPLACES every label on the task with exactly these names ([] removes them all). A missing name is CREATED. Cannot be combined with add_label_names / remove_label_names'),
+            add_label_names: labelNames.describe('Labels to ADD, keeping the others. A missing name is CREATED; one the task already carries changes nothing'),
+            remove_label_names: labelNames.describe('Labels to REMOVE, keeping the others. A name the task does not carry, or that does not exist, changes nothing (never created)'),
+            custom_fields: customFieldsMap.optional(),
         },
         handler: (args, cfg) => {
             // Only keys the caller actually supplied may go in the body: PATCH
@@ -486,10 +550,18 @@ export function registerTaskTools(server, config) {
                 'estimated_hours',
                 'project_id',
                 'actor_employee_code',
+                'label_names',
+                'custom_fields',
             ]) {
                 if (args[key] !== undefined)
                     body[key] = args[key];
             }
+            refuseLabelConflicts(args, true);
+            // An empty add/remove list is not a change: it is not sent.
+            if (hasNames(args.add_label_names))
+                body.add_label_names = args.add_label_names;
+            if (hasNames(args.remove_label_names))
+                body.remove_label_names = args.remove_label_names;
             if (typeof body.description === 'string')
                 body.description = markdownToHtml(body.description);
             // Series management maps onto the API's two columns. `recurrence`
@@ -510,6 +582,12 @@ export function registerTaskTools(server, config) {
             else if (args.recurrence_active !== undefined) {
                 body.is_recurring = args.recurrence_active;
             }
+            // Nothing to change (only empty add/remove lists, or no field at all):
+            // refused here, as the bulk tool refuses, instead of a request that
+            // changes nothing.
+            if (Object.keys(body).filter((k) => k !== 'actor_employee_code').length === 0) {
+                throw new Error('Nothing to change: give at least one field (an empty add_label_names / remove_label_names list is not a change).');
+            }
             // Credit the update to CLOKIO_DEFAULT_ACTOR when the caller named no
             // actor. The API otherwise falls back to the key's issuer on its own,
             // so this only overrides for a shared/service key. An explicit
@@ -858,34 +936,84 @@ export function registerTaskTools(server, config) {
     registerTool(server, config, {
         name: 'clokio_set_task_custom_field',
         mutates: true,
-        description: 'Set one custom field value on a task, identified by field_key (never field_id). An API key sees ' +
-            'PUBLIC fields only.',
+        description: 'Set one custom field value on a task, identified by field_key (never field_id); list a project\'s ' +
+            'keys with clokio_get_project_custom_fields. An API key sees PUBLIC fields only. A dropdown or ' +
+            'multi-select value may be the option\'s stored value OR its label as shown on screen (value first, ' +
+            'then the exact label, then the label ignoring case and surrounding spaces). A label two options ' +
+            'share is refused asking for the value; an unknown one is refused listing the options. null clears ' +
+            'the value. To set several fields on one task use custom_fields on clokio_update_task; on many tasks, ' +
+            'clokio_bulk_set_task_custom_field.',
         schema: {
             id: z.number().int(),
             field_key: z.string(),
-            value: z.union([z.string(), z.number(), z.boolean(), z.array(z.string())]),
+            value: customFieldValue,
+            actor_employee_code: employeeCode.optional().describe('Who to credit in the activity log; omit to use the key issuer / CLOKIO_DEFAULT_ACTOR'),
+        },
+        handler: (args, cfg) => {
+            const body = { field_key: args.field_key, value: args.value };
+            const actor = args.actor_employee_code ?? cfg.defaultActor;
+            if (actor)
+                body.actor_employee_code = actor;
+            return request(cfg, `/tasks/${args.id}/custom-fields`, { method: 'PATCH', body });
+        },
+    });
+    registerTool(server, config, {
+        name: 'clokio_bulk_set_task_custom_field',
+        mutates: true,
+        description: 'Set the same custom field value(s) on up to 200 tasks at once: custom_fields is an object of ' +
+            'field_key -> value (one or more fields; option labels accepted as on clokio_set_task_custom_field; ' +
+            'null clears). Fields are defined PER PROJECT, so each task is judged against its own project. ' +
+            'Partial success is normal: the result is {updated, not_found, field_not_on_project, invalid_value, ' +
+            'moved, errors}. not_found = ids not in your org; field_not_on_project = the task\'s project has no such ' +
+            'field (or only a private one); invalid_value = a value refused for that project\'s field; moved = ' +
+            'the task moved to another project while the request ran, nothing written: retry those ids; errors ' +
+            'says why per task id and field key. Per task it is all or nothing. Attribution follows the key ' +
+            'issuer unless actor_employee_code is set.',
+        schema: {
+            ids: z.array(z.number().int()).min(1).max(200),
+            custom_fields: customFieldsMap,
+            actor_employee_code: employeeCode.optional().describe('Who to credit; omit to use the key issuer'),
+        },
+        handler: (args, cfg) => {
+            const body = { ids: args.ids, custom_fields: args.custom_fields };
+            const actor = args.actor_employee_code ?? cfg.defaultActor;
+            if (actor)
+                body.actor_employee_code = actor;
+            return request(cfg, '/tasks/bulk/custom-fields', { method: 'PATCH', body });
         },
-        handler: (args, cfg) => request(cfg, `/tasks/${args.id}/custom-fields`, {
-            method: 'PATCH',
-            body: { field_key: args.field_key, value: args.value },
-        }),
     });
     registerTool(server, config, {
         name: 'clokio_bulk_update_tasks',
         mutates: true,
-        description: 'Apply ONE change (any of status, priority, due_date) to up to 200 tasks at once - for cleaning up a ' +
-            'board without a call per task. Partial success is normal: the result is {updated, not_found, ' +
-            'invalid_status}. not_found lists ids that do not exist in your org (skipped, not fatal); ' +
-            'invalid_status lists tasks whose board does not have the given status slug. Give at least one of ' +
-            'status/priority/due_date. Attribution follows the key issuer unless actor_employee_code is set.',
+        description: 'Apply ONE change (any of status, priority, due_date, add_label_names, remove_label_names) to up to 200 ' +
+            'tasks at once - for cleaning up a board without a call per task. Partial success is normal: the result ' +
+            'is {updated, not_found, invalid_status}. not_found lists ids that do not exist in your org (skipped, not ' +
+            'fatal); invalid_status lists tasks whose board does not have the given status slug (such a task is ' +
+            'skipped whole, its labels included). Give at least one of status/priority/due_date/add_label_names/' +
+            'remove_label_names (an empty list does not count). Labels are a change only: add_label_names adds (a missing name is CREATED once in ' +
+            'your organisation), remove_label_names removes (never creates); a label a task already carries, or one ' +
+            'it does not carry, changes nothing for that task. To REPLACE a task\'s whole label set use ' +
+            'clokio_update_task with label_names. With labels, the result also has labels_failed: ids whose label change ' +
+            'could not be written after their other changes were saved (normally empty; send the labels again). ' +
+            'Attribution follows the key issuer unless actor_employee_code is set.',
         schema: {
             ids: z.array(z.number().int()).min(1).max(200),
             status: z.string().optional().describe('Status slug - validated per task against its own board'),
             priority: z.enum(['low', 'medium', 'high', 'urgent']).optional(),
             due_date: z.string().nullable().optional().describe('YYYY-MM-DD, or null to clear'),
             actor_employee_code: employeeCode.optional().describe('Who to credit; omit to use the key issuer'),
+            add_label_names: labelNames.describe('Labels to ADD to every task. A missing name is CREATED once in your organisation'),
+            remove_label_names: labelNames.describe('Labels to REMOVE from every task. An unknown name changes nothing (never created)'),
         },
         handler: (args, cfg) => {
+            if (args.status === undefined &&
+                args.priority === undefined &&
+                args.due_date === undefined &&
+                !hasNames(args.add_label_names) &&
+                !hasNames(args.remove_label_names)) {
+                throw new Error('Give at least one of: status, priority, due_date, add_label_names, remove_label_names.');
+            }
+            refuseLabelConflicts(args, false);
             const body = { ids: args.ids };
             if (args.status !== undefined)
                 body.status = args.status;
@@ -893,6 +1021,10 @@ export function registerTaskTools(server, config) {
                 body.priority = args.priority;
             if (args.due_date !== undefined)
                 body.due_date = args.due_date;
+            if (hasNames(args.add_label_names))
+                body.add_label_names = args.add_label_names;
+            if (hasNames(args.remove_label_names))
+                body.remove_label_names = args.remove_label_names;
             body.actor_employee_code = args.actor_employee_code ?? cfg.defaultActor;
             return request(cfg, '/tasks/bulk', { method: 'PATCH', body });
         },

package/package.json

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