clokio-mcp 0.26.0 → 0.27.1

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 121 tools to 34. 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
 
-121 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` / `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 |
+| **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/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,225 @@ 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. 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'),
+        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. 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 -'),
+            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_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

@@ -7,6 +7,16 @@ 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
@@ -18,7 +28,7 @@ const customFieldValue = z
     .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)
+    .record(fieldKey, customFieldValue)
     .refine((m) => Object.keys(m).length >= 1 && Object.keys(m).length <= 50, {
     message: 'custom_fields must name 1-50 fields',
 })
@@ -279,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`
@@ -294,6 +330,58 @@ 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.
+ */
+/**
+ * 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.');
+    }
+    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',
@@ -301,14 +389,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()
@@ -338,6 +456,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(),
@@ -352,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',
@@ -371,6 +502,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,
@@ -392,9 +524,87 @@ 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(','),
             },
         }),
     });
+    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 ' +
@@ -438,7 +648,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)
@@ -510,7 +720,14 @@ export function registerTaskTools(server, config) {
             '\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.',
+            '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(),
@@ -519,8 +736,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()
@@ -534,6 +758,23 @@ export function registerTaskTools(server, config) {
             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
@@ -552,10 +793,16 @@ export function registerTaskTools(server, config) {
                 '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))
@@ -622,11 +869,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',
@@ -945,7 +1196,7 @@ export function registerTaskTools(server, config) {
             'clokio_bulk_set_task_custom_field.',
         schema: {
             id: z.number().int(),
-            field_key: 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'),
         },
@@ -985,11 +1236,12 @@ export function registerTaskTools(server, config) {
     registerTool(server, config, {
         name: 'clokio_bulk_update_tasks',
         mutates: true,
-        description: 'Apply ONE change (any of status, priority, due_date, add_label_names, remove_label_names) to up to 200 ' +
+        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). Give at least one of status/priority/due_date/add_label_names/' +
+            '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 ' +
@@ -1001,6 +1253,7 @@ export function registerTaskTools(server, config) {
             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)'),
@@ -1009,9 +1262,10 @@ export function registerTaskTools(server, config) {
             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, add_label_names, 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 };
@@ -1021,6 +1275,8 @@ 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))

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "clokio-mcp",
-  "version": "0.26.0",
+  "version": "0.27.1",
   "description": "Model Context Protocol (MCP) server for Clokio - manage tasks, projects, clients, employees, attendance and documents from Claude and any MCP client.",
   "type": "module",
   "bin": {