clokio-mcp 0.25.0 → 0.27.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 127 tools to 40. 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
 
-120 tools across seven areas. Read-only tools carry the MCP `readOnlyHint`; writes
+127 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 |
-| **Projects & clients** | list projects, project statuses, project custom fields, project contacts, get client, add client contact |
+| **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 |
 | **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)) |
@@ -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/projects.js

@@ -2,6 +2,7 @@ import { z } from 'zod';
 import { request } from '../client.js';
 import { registerTool } from './helpers.js';
 import { VERSION } from '../version.js';
+import { FIELD_KEY_PATTERN } from './tasks.js';
 /** Projects, clients, and the board-configuration + reference lookups. */
 export function registerProjectTools(server, config) {
     registerTool(server, config, {
@@ -29,6 +30,160 @@ export function registerProjectTools(server, config) {
         schema: { project_id: z.number().int() },
         handler: (args, cfg) => request(cfg, `/projects/${args.project_id}/custom-fields`),
     });
+    // ── 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.
+    const fieldOptions = z
+        .array(z.object({
+        value: z.string().min(1).max(100).describe('The stored value tasks hold; keep it stable'),
+        label: z.string().max(100).optional().describe('What people see; defaults to the value'),
+        color: z
+            .string()
+            .regex(/^#[0-9a-fA-F]{6}$/, 'color must be #rrggbb')
+            .optional(),
+    }))
+        .min(1)
+        .max(200);
+    const fieldType = z.enum(['text', 'number', 'date', 'dropdown', 'checkbox', 'multi_select', 'url', 'email']);
+    const actorCode = z
+        .string()
+        .regex(/^[A-Za-z0-9_-]{1,50}$/, 'employee_code: letters, digits, _ or -')
+        .optional()
+        .describe('Checked by the server (an unknown code is refused); a configuration edit writes no activity row');
+    const statusColor = z
+        .string()
+        .regex(/^#[0-9a-fA-F]{6}$/, 'color must be #rrggbb')
+        .nullable()
+        .optional();
+    registerTool(server, config, {
+        name: 'clokio_create_project_custom_field',
+        mutates: true,
+        description: 'Create a custom field on a project (the board\'s columns). type is one of text, number, date, dropdown, ' +
+            'checkbox, multi_select, url, email. A dropdown or multi_select NEEDS options ({value, label?, color?}; ' +
+            'the label defaults to the value); every other type takes none. The field key is generated from the ' +
+            'name and never changes (it is what clokio_set_task_custom_field and the list filters take). An API ' +
+            'key creates PUBLIC fields only. A release or sprint is a dropdown field: create it once, add an ' +
+            'option per release with clokio_update_project_custom_field, set it on tasks with ' +
+            'clokio_bulk_set_task_custom_field, read it with clokio_get_project_task_summary group_by_custom_field. ' +
+            'Needs the projects:write scope.',
+        schema: {
+            project_id: z.number().int(),
+            name: z.string().min(1).max(50),
+            type: fieldType,
+            options: fieldOptions.optional(),
+            is_required: z.boolean().optional(),
+            actor_employee_code: actorCode,
+        },
+        handler: (args, cfg) => {
+            const optioned = args.type === 'dropdown' || args.type === 'multi_select';
+            if (optioned && args.options === undefined) {
+                throw new Error(`A ${args.type} field needs options: give at least one {value, label}.`);
+            }
+            if (!optioned && args.options !== undefined) {
+                throw new Error(`A ${args.type} field takes no options; only dropdown and multi_select do.`);
+            }
+            const body = { name: args.name, type: args.type };
+            if (args.options !== undefined)
+                body.options = args.options;
+            if (args.is_required !== undefined)
+                body.is_required = args.is_required;
+            const actor = args.actor_employee_code ?? cfg.defaultActor;
+            if (actor)
+                body.actor_employee_code = actor;
+            return request(cfg, `/projects/${args.project_id}/custom-fields`, { method: 'POST', body });
+        },
+    });
+    registerTool(server, config, {
+        name: 'clokio_update_project_custom_field',
+        mutates: true,
+        description: 'Edit a project custom field by its field_key: rename it (the key stays), change its type, flip ' +
+            'is_required, or replace its options with the WHOLE new list. To add a release, read the field with ' +
+            'clokio_get_project_custom_fields and send every option plus the new one; renaming a label or ' +
+            'reordering is free (tasks store the value). Removing an option tasks still hold is refused naming ' +
+            'it; so is a type change that would leave stored answers unreadable. 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 -'),
+            name: z.string().min(1).max(50).optional(),
+            type: fieldType.optional(),
+            options: fieldOptions.optional(),
+            is_required: z.boolean().optional(),
+            actor_employee_code: actorCode,
+        },
+        handler: (args, cfg) => {
+            const body = {};
+            for (const key of ['name', 'type', 'options', 'is_required']) {
+                if (args[key] !== undefined)
+                    body[key] = args[key];
+            }
+            if (Object.keys(body).length === 0) {
+                throw new Error('Nothing to change: give at least one of name, type, options, is_required.');
+            }
+            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: 'PATCH', body });
+        },
+    });
+    registerTool(server, config, {
+        name: 'clokio_create_project_status',
+        mutates: true,
+        description: 'Add a status (a board column) to a project. The name must be new in the project (compared ignoring ' +
+            'case); the slug is generated from it and never changes. A new status is always ACTIVE: a project has ' +
+            'exactly one completed status, which always stays the last column. position (0-based) places it. A ' +
+            'project still using the organisation\'s statuses gets its own copy first, so no other project ' +
+            'changes. Needs the projects:write scope.',
+        schema: {
+            project_id: z.number().int(),
+            name: z.string().min(1).max(50),
+            color: statusColor.describe('#rrggbb'),
+            position: z.number().int().min(0).max(200).optional().describe('0-based place on the board'),
+            actor_employee_code: actorCode,
+        },
+        handler: (args, cfg) => {
+            const body = { name: args.name };
+            if (args.color !== undefined)
+                body.color = args.color;
+            if (args.position !== undefined)
+                body.position = args.position;
+            const actor = args.actor_employee_code ?? cfg.defaultActor;
+            if (actor)
+                body.actor_employee_code = actor;
+            return request(cfg, `/projects/${args.project_id}/statuses`, { method: 'POST', body });
+        },
+    });
+    registerTool(server, config, {
+        name: 'clokio_update_project_status',
+        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.',
+        schema: {
+            project_id: z.number().int(),
+            slug: z.string().regex(/^[A-Za-z0-9_-]{1,100}$/, 'slug: letters, digits, _ or -'),
+            name: z.string().min(1).max(50).optional(),
+            color: statusColor.describe('#rrggbb, or null for the default colour'),
+            category: z.enum(['active', 'done']).optional(),
+            position: z.number().int().min(0).max(200).optional().describe('0-based place on the board'),
+            actor_employee_code: actorCode,
+        },
+        handler: (args, cfg) => {
+            const body = {};
+            for (const key of ['name', 'color', 'category', 'position']) {
+                if (args[key] !== undefined)
+                    body[key] = args[key];
+            }
+            if (Object.keys(body).length === 0) {
+                throw new Error('Nothing to change: give at least one of name, color, category, position.');
+            }
+            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: 'PATCH', body });
+        },
+    });
     registerTool(server, config, {
         name: 'clokio_get_project_contacts',
         description: "The contacts for a project's client.",

package/dist/tools/tasks.js

@@ -7,6 +7,32 @@ 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 -');
+/**
+ * A custom field's field_key, by the backend's own rule: the route
+ * `->where('fieldKey', '[A-Za-z0-9_-]{1,50}')` and the 50-char `key` column
+ * (keys are generated with Str::slug). Every field_key input uses it, so a
+ * key such as `a]b` or `x&y` never reaches a query string or a path.
+ */
+export const FIELD_KEY_PATTERN = /^[A-Za-z0-9_-]{1,50}$/;
+const fieldKey = z.string().regex(FIELD_KEY_PATTERN, 'field_key must be 1-50 chars of letters, digits, _ or -');
+/** THE estimated_hours ceiling of every Public API write (create, update, bulk): the backend's ESTIMATED_HOURS_MAX. */
+export const ESTIMATED_HOURS_MAX = 9999.99;
+/**
+ * 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(fieldKey, 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 +204,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') {
@@ -224,6 +289,32 @@ export function renderActivity(res) {
         `Page ${meta.current_page ?? '-'} of ${meta.last_page ?? '-'} (total ${meta.total ?? '-'}); pass page to continue.`,
     ].join('\n');
 }
+/**
+ * 0.27.0 (backend #5874 part 4): a project's activity feed, one change per
+ * line like renderActivity, each naming its task, then the keyset cursor to
+ * continue with. Values are flattened the same way, so a value cannot print
+ * something that looks like further lines.
+ */
+export function renderProjectActivity(res) {
+    const rows = Array.isArray(res) ? res : (res?.data ?? []);
+    const meta = res?.meta ?? {};
+    const flat = (v) => String(v).replace(/\s+/g, ' ').trim();
+    const value = (v) => {
+        if (v === null || v === undefined)
+            return '-';
+        const f = flat(typeof v === 'object' ? JSON.stringify(v) : v);
+        return f === '' ? '-' : f;
+    };
+    const task = (t) => t ? `task #${flat(t.id)}${t.title ? ` "${flat(t.title)}"` : ''}${t.deleted ? ' (deleted)' : ''}` : 'task -';
+    const line = (a) => `[${flat(a.created_at)}] ${task(a.task)} - ${flat(activityActor(a.employee))}: ${flat(a.action)}${a.field ? ` ${flat(a.field)}` : ''}` +
+        (a.old_value != null || a.new_value != null ? ` (${value(a.old_value)} -> ${value(a.new_value)})` : '');
+    return [
+        ...(rows.length ? rows.map(line) : ['No activity.']),
+        meta.next_cursor
+            ? `More: pass cursor="${flat(meta.next_cursor)}" (with the same filters) for the next page.`
+            : 'End of the log for these filters.',
+    ].join('\n');
+}
 /**
  * #4 (0.23.0): the ticket a task was opened from, as `linked_ticket:
  * "ticket #<id> <url>"` first in the answer, replacing the raw `ticket`
@@ -239,6 +330,39 @@ export function withLinkedTicket(task) {
     }
     return rest;
 }
+/**
+ * The list filters of backend task #5874 part 3, turned into GET /tasks query
+ * keys: `custom_field` (an object) becomes custom_field[<field_key>]=<value>,
+ * a boolean checkbox value 1 / 0. The contradictions the server refuses with a
+ * 422 are refused here first, in the same words, so no request is spent on
+ * them.
+ */
+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.');
+    }
+    if (args.no_assignee === true && args.assignee_employee_code !== undefined) {
+        throw new Error('no_assignee=true cannot be combined with assignee_employee_code: a task with no assignee is held by nobody. Drop one of them.');
+    }
+    const out = {
+        no_due_date: args.no_due_date === undefined ? undefined : args.no_due_date ? 1 : 0,
+        no_assignee: args.no_assignee === undefined ? undefined : args.no_assignee ? 1 : 0,
+        search_in: args.search_in,
+        updated_before: args.updated_before,
+    };
+    if (args.custom_field !== undefined) {
+        if (args.project_id === undefined) {
+            throw new Error('custom_field filters need project_id: custom fields belong to one project. Add project_id; clokio_get_project_custom_fields lists its field keys.');
+        }
+        for (const [key, value] of Object.entries(args.custom_field)) {
+            if (!FIELD_KEY_PATTERN.test(key)) {
+                throw new Error(`custom_field key "${key}" is not a field_key: 1-50 chars of letters, digits, _ or -.`);
+            }
+            out[`custom_field[${key}]`] = typeof value === 'boolean' ? (value ? 1 : 0) : value;
+        }
+    }
+    return out;
+}
 export function registerTaskTools(server, config) {
     registerTool(server, config, {
         name: 'clokio_list_tasks',
@@ -246,14 +370,44 @@ export function registerTaskTools(server, config) {
             'your own code. An UNKNOWN query parameter is a 422 naming it, so use exactly these names. Paginate ' +
             'with page, or crawl with cursor (preferred past one page). Every task carries a task_url.\n\n' +
             'The response is {data, meta}. meta carries total, per_page, current_page and next_cursor - read ' +
-            'next_cursor and pass it back as `cursor` for the following page; it is null on the last one.',
+            'next_cursor and pass it back as `cursor` for the following page; it is null on the last one. ' +
+            'For counts rather than rows (how many open tasks per status, label or person, what is overdue or ' +
+            'stale on one board), use clokio_get_project_task_summary instead of paging.',
         schema: {
             project_id: z.number().int().optional(),
             status: z.string().optional().describe('Status slug, e.g. "in_progress"'),
             priority: z.enum(['low', 'medium', 'high', 'urgent']).optional(),
             assignee_employee_code: employeeCode.optional().describe('employee_code, e.g. "00080"'),
             label: z.string().optional(),
-            search: z.string().optional().describe('Free text over title and description'),
+            search: z.string().optional().describe('Free text over title and description (see search_in)'),
+            search_in: z
+                .enum(['title', 'all'])
+                .optional()
+                .describe('Where `search` looks: "title" only, or "all" = title and description (the default)'),
+            no_due_date: z
+                .boolean()
+                .optional()
+                .describe('true = only tasks with NO due date; false = only tasks that have one; omit for no filter. ' +
+                'Cannot be combined with due_before / due_after when true.'),
+            no_assignee: z
+                .boolean()
+                .optional()
+                .describe('true = only tasks nobody is assigned to; false = only tasks somebody holds; omit for no filter. ' +
+                'A client person on a shared board, or a departed employee, still counts as holding a task. ' +
+                'Cannot be combined with assignee_employee_code when true.'),
+            custom_field: z
+                .record(fieldKey, z.union([z.string().min(1).max(500), z.number(), z.boolean()]))
+                .refine((m) => Object.keys(m).length >= 1 && Object.keys(m).length <= 20, {
+                message: 'custom_field must name 1-20 fields',
+            })
+                .optional()
+                .describe('Match custom field values: an object of field_key -> value, e.g. {"stage": "In build", "escalated": true}. ' +
+                'Several fields are ANDed. REQUIRES project_id (fields belong to one project); the keys are the ' +
+                'field_key values clokio_get_project_custom_fields lists, and a key that is not a public field of ' +
+                'that project is refused naming it. Per type: dropdown = the option value or its label (a label ' +
+                'two options share is refused asking for the value); multi-select = the task\'s list CONTAINS that ' +
+                'option; checkbox = true (ticked) or false (not ticked, an unanswered checkbox included); text, ' +
+                'url and email = exact match, ignoring case; number and date (YYYY-MM-DD) = exact.'),
             open: z.boolean().optional().describe('true = only tasks whose status is not a "done" one'),
             recurring: z
                 .boolean()
@@ -283,6 +437,11 @@ export function registerTaskTools(server, config) {
                 .string()
                 .optional()
                 .describe('ISO-8601. Incremental sync: only tasks changed at or after this instant'),
+            updated_before: z
+                .string()
+                .optional()
+                .describe('YYYY-MM-DD or ISO-8601, organization timezone. Only tasks last updated BEFORE this (exclusive); ' +
+                'the other half of updated_since'),
             include_comments: z.boolean().optional(),
             per_page: z.number().int().min(1).max(100).optional(),
             page: z.number().int().optional(),
@@ -316,6 +475,7 @@ export function registerTaskTools(server, config) {
         },
         handler: (args, cfg) => request(cfg, '/tasks', {
             query: {
+                ...listFilterQuery(args),
                 project_id: args.project_id,
                 status: args.status,
                 priority: args.priority,
@@ -340,6 +500,83 @@ export function registerTaskTools(server, config) {
             },
         }),
     });
+    registerTool(server, config, {
+        name: 'clokio_get_project_task_summary',
+        description: "One project's task numbers in one call, counted by the server: tasks by status (the project's own " +
+            'statuses, each with is_open), by priority (low / medium / high / urgent / none), by label name and by ' +
+            'assignee, plus unassigned and no_due_date counts; and two short lists of compact task rows: overdue ' +
+            "(open tasks due before today in the organisation's time zone, oldest due first) and stale (open tasks " +
+            'not updated for stale_days, least recently updated first), each at most 50 rows with a total. ' +
+            'OPEN tasks only unless include_closed is true. Subtasks count as tasks of their own unless top_level ' +
+            'is true. A task held by several people is counted for EACH of them in by_assignee, so those numbers ' +
+            'can sum above total. The answer carries a definitions block naming the rule behind every number, and ' +
+            'echoes stale_days. Use this for "how is project X doing" questions; use clokio_list_tasks for the rows ' +
+            'themselves. Needs tasks:read.',
+        schema: {
+            project_id: z.number().int(),
+            include_closed: z
+                .boolean()
+                .optional()
+                .describe('true also counts closed tasks (status category done). overdue and stale stay open tasks'),
+            top_level: z
+                .boolean()
+                .optional()
+                .describe('true counts top-level tasks only (subtasks excluded), overdue and stale included'),
+            stale_days: z
+                .number()
+                .int()
+                .min(1)
+                .max(365)
+                .optional()
+                .describe('Days without an update (updated_at) that make an open task stale. Default 14, range 1-365'),
+            group_by_custom_field: fieldKey
+                .optional()
+                .describe('The field_key of a PUBLIC dropdown or multi-select field of this project (clokio_get_project_custom_fields). ' +
+                'Adds by_custom_field: tasks per option (value and label) with open / closed / total, plus none for tasks ' +
+                'with no answer; a multi-select task counts under each option it holds. This answers "what is in each ' +
+                'release / sprint". Any other field type, a private field or an unknown key is refused (422).'),
+        },
+        handler: (args, cfg) => request(cfg, `/projects/${args.project_id}/task-summary`, {
+            query: {
+                include_closed: args.include_closed === undefined ? undefined : args.include_closed ? 1 : 0,
+                top_level: args.top_level === undefined ? undefined : args.top_level ? 1 : 0,
+                stale_days: args.stale_days,
+                group_by_custom_field: args.group_by_custom_field,
+            },
+        }),
+    });
+    registerTool(server, config, {
+        name: 'clokio_list_project_activity',
+        description: "One project's activity log, newest first: every change on every task of the board (deleted tasks " +
+            'included), one line per change naming the task, who acted (name, code, organisation) and what changed. ' +
+            "since / until narrow it (a plain date or time is read in the organisation's time zone; until is " +
+            'exclusive), action limits it to some actions (e.g. ["status_changed", "assigned"]). Pages of per_page ' +
+            '(1-100, default 25); the answer ends with the cursor to pass back for the next page, with the same ' +
+            "filters. Only PUBLIC custom fields' history appears, and internal comments never do. Use " +
+            'clokio_get_task_activity for one task. Needs tasks:read.',
+        schema: {
+            project_id: z.number().int(),
+            since: z.string().optional().describe('YYYY-MM-DD or ISO-8601: rows at or after this instant'),
+            until: z.string().optional().describe('YYYY-MM-DD or ISO-8601: rows before this instant (exclusive)'),
+            action: z
+                .array(z.string().min(1).max(60))
+                .min(1)
+                .max(30)
+                .optional()
+                .describe('Only these actions, e.g. ["status_changed", "assigned", "custom_field_changed"]'),
+            cursor: z.string().max(500).optional().describe('The cursor the previous page ended with'),
+            per_page: z.number().int().min(1).max(100).optional(),
+        },
+        handler: async (args, cfg) => renderProjectActivity(await request(cfg, `/projects/${args.project_id}/activities`, {
+            query: {
+                since: args.since,
+                until: args.until,
+                action: args.action,
+                cursor: args.cursor,
+                per_page: args.per_page,
+            },
+        })),
+    });
     registerTool(server, config, {
         name: 'clokio_get_task',
         description: 'Get one task by id, with its full detail (assignees, labels, status, custom fields, task_url) and ' +
@@ -383,7 +620,7 @@ export function registerTaskTools(server, config) {
             status: z.string().optional().describe("Status slug valid for THIS project's board"),
             due_date: z.string().optional().describe('YYYY-MM-DD'),
             start_date: z.string().optional().describe('YYYY-MM-DD'),
-            estimated_hours: z.number().min(0).max(9999.99).optional(),
+            estimated_hours: z.number().min(0).max(ESTIMATED_HOURS_MAX).optional(),
             parent_task_id: z.number().int().optional().describe('Makes this a subtask of that task'),
             assignee_employee_codes: z
                 .array(assigneeReference)
@@ -391,7 +628,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 +687,19 @@ 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.\n\n' +
+            '`parent_task_id` makes the task a subtask of another task on the SAME project (null makes it ' +
+            'top-level again). Subtasks go one level deep: a subtask cannot be a parent, a task that has subtasks ' +
+            'cannot become one, and a task cannot be its own parent.\n\n' +
+            '`assignee_employee_codes` (with `assignee_mode`: replace by default, add, remove) changes the ' +
+            'assignees in the same call, with exactly the rules of clokio_set_task_assignees (a client\'s person ' +
+            'as {employee_code, organization_id}; assigning makes the person a watcher). A refused person refuses ' +
+            'the WHOLE update: nothing in the call is written.',
         schema: {
             id: z.number().int(),
             title: z.string().max(255).optional(),
@@ -459,8 +708,15 @@ export function registerTaskTools(server, config) {
             status: z.string().optional().describe("Status slug valid for this task's board"),
             due_date: z.string().nullable().optional().describe('YYYY-MM-DD, or null to clear'),
             start_date: z.string().nullable().optional().describe('YYYY-MM-DD, or null to clear'),
-            estimated_hours: z.number().min(0).max(9999.99).nullable().optional(),
-            project_id: z.number().int().optional().describe('Move the task to another project'),
+            estimated_hours: z.number().min(0).max(ESTIMATED_HOURS_MAX).nullable().optional(),
+            project_id: z
+                .number()
+                .int()
+                .optional()
+                .describe('Move the task to another project. Its subtasks move with it, and a status the new board lacks becomes ' +
+                'that board\'s default. A SUBTASK moves only when the same call sends parent_task_id: null (it ' +
+                'becomes a top-level task there) or the id of a task on the new project (it moves under it); ' +
+                'otherwise the server refuses it.'),
             actor_employee_code: employeeCode.optional().describe('Who to credit in the activity log; omit to use the key issuer / CLOKIO_DEFAULT_ACTOR'),
             recurrence: recurrenceInput
                 .nullable()
@@ -470,6 +726,27 @@ 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(),
+            parent_task_id: z
+                .number()
+                .int()
+                .min(1)
+                .nullable()
+                .optional()
+                .describe('Hang the task under this task (same project, one level deep), or null to make it top-level'),
+            assignee_employee_codes: z
+                .array(assigneeReference)
+                .min(1)
+                .max(50)
+                .optional()
+                .describe('Assignees, as on clokio_set_task_assignees: a code of your organisation, or {employee_code, organization_id} for a client\'s person'),
+            assignee_mode: z
+                .enum(['replace', 'add', 'remove'])
+                .optional()
+                .describe('How assignee_employee_codes applies: replace (default) overwrites, add appends, remove takes off'),
         },
         handler: (args, cfg) => {
             // Only keys the caller actually supplied may go in the body: PATCH
@@ -486,10 +763,24 @@ export function registerTaskTools(server, config) {
                 'estimated_hours',
                 'project_id',
                 'actor_employee_code',
+                'label_names',
+                'custom_fields',
+                'parent_task_id',
+                'assignee_employee_codes',
+                'assignee_mode',
             ]) {
                 if (args[key] !== undefined)
                     body[key] = args[key];
             }
+            if (args.assignee_mode !== undefined && args.assignee_employee_codes === undefined) {
+                throw new Error('assignee_mode needs assignee_employee_codes.');
+            }
+            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 +801,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
@@ -544,11 +841,15 @@ export function registerTaskTools(server, config) {
                 .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'),
+            actor_employee_code: employeeCode.optional().describe('Who to credit in the activity log; omit to use the key issuer / CLOKIO_DEFAULT_ACTOR'),
+        },
+        handler: async (args, cfg) => {
+            const body = { employee_codes: args.employee_codes, mode: args.mode };
+            const actor = args.actor_employee_code ?? cfg.defaultActor;
+            if (actor)
+                body.actor_employee_code = actor;
+            return compactAssignees(args.id, await request(cfg, `/tasks/${args.id}/assignees`, { method: 'PATCH', body }), cfg.baseUrl);
         },
-        handler: async (args, cfg) => compactAssignees(args.id, await request(cfg, `/tasks/${args.id}/assignees`, {
-            method: 'PATCH',
-            body: { employee_codes: args.employee_codes, mode: args.mode },
-        }), cfg.baseUrl),
     });
     registerTool(server, config, {
         name: 'clokio_list_project_people',
@@ -858,34 +1159,87 @@ 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())]),
+            field_key: fieldKey,
+            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, estimated_hours, 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). estimated_hours (0-9999.99, null clears) sets one estimate on every ' +
+            'task; a task already holding it changes nothing. Give at least one of status/priority/due_date/estimated_hours/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'),
+            estimated_hours: z.number().min(0).max(ESTIMATED_HOURS_MAX).nullable().optional().describe('Hours, 0-9999.99, set on every task; null clears'),
             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 &&
+                args.estimated_hours === undefined &&
+                !hasNames(args.add_label_names) &&
+                !hasNames(args.remove_label_names)) {
+                throw new Error('Give at least one of: status, priority, due_date, estimated_hours, add_label_names, remove_label_names.');
+            }
+            refuseLabelConflicts(args, false);
             const body = { ids: args.ids };
             if (args.status !== undefined)
                 body.status = args.status;
@@ -893,6 +1247,12 @@ export function registerTaskTools(server, config) {
                 body.priority = args.priority;
             if (args.due_date !== undefined)
                 body.due_date = args.due_date;
+            if (args.estimated_hours !== undefined)
+                body.estimated_hours = args.estimated_hours;
+            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.27.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": {