clokio-mcp 0.27.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 127 tools to 40. Optional groups are `tasks`,
+task-focused session drops from 129 tools to 42. Optional groups are `tasks`,
 `employees`, `attendance` (which includes leave, time entries and logging time), `docs` and
 `tickets`;
 combine them with commas. If your key cannot open documents (no acts-as
@@ -76,13 +76,13 @@ through it.
 
 ## Tools
 
-127 tools across seven areas. Read-only tools carry the MCP `readOnlyHint`; writes
+129 tools across seven areas. Read-only tools carry the MCP `readOnlyHint`; writes
 are marked mutating (deletes are `destructive`).
 
 | Area | Tools |
 |------|-------|
-| **Tasks** | list (with `compact` / `sort` / `updated_since` / `updated_before` / `recurring`, no due date, no assignee, a custom field value, title-only search), a project's task summary (counts by status / priority / label / assignee, overdue and stale lists, per option of a release dropdown: `clokio_get_project_task_summary`), a project's activity log (`clokio_list_project_activity`), get (with `comments_limit`; names the ticket a task was opened from), create, update (incl. recurring series: set a rule, pause/resume, stop; labels: replace, add, remove; parent task; assignees in the same call), delete, bulk update (status, priority, due date, estimate, add / remove labels), set assignees (a shared board's client people as `{employee_code, organization_id}`), list a board's people, list/add/edit comments, list attachments (with `is_latest` + `latest_only`), upload, download one (save to disk, or read PDF text / ZIP entries / images / text inline), download all to a folder, read images pasted into descriptions and comments, activity (with organisations, paged), list/add/remove dependencies, set custom field (an option by value or label), set custom fields on many tasks (`clokio_bulk_set_task_custom_field`, partial success); `clokio_update_task` takes `custom_fields` too |
-| **Projects & clients** | list projects, project statuses (and create / edit them), project custom fields (and create / edit them, e.g. a release dropdown), project contacts, get client, add client contact |
+| **Tasks** | list (with `compact` / `fields` / `sort` / `updated_since` / `updated_before` / `recurring`, no due date, no assignee, a custom field value, title-only search), a project's task summary (counts by status / priority / label / assignee, overdue and stale lists, per option of a release dropdown: `clokio_get_project_task_summary`), a project's activity log (`clokio_list_project_activity`), get (with `comments_limit`; names the ticket a task was opened from), create, update (incl. recurring series: set a rule, pause/resume, stop; labels: replace, add, remove; parent task; assignees in the same call), delete, bulk update (status, priority, due date, estimate, add / remove labels), set assignees (a shared board's client people as `{employee_code, organization_id}`), list a board's people, list/add/edit comments, list attachments (with `is_latest` + `latest_only`), upload, download one (save to disk, or read PDF text / ZIP entries / images / text inline), download all to a folder, read images pasted into descriptions and comments, activity (with organisations, paged), list/add/remove dependencies, set custom field (an option by value or label), set custom fields on many tasks (`clokio_bulk_set_task_custom_field`, partial success); `clokio_update_task` takes `custom_fields` too |
+| **Projects & clients** | list projects, project statuses (and create / edit / delete them; a status in use moves its tasks to `move_to`), project custom fields (and create / edit / delete them, e.g. a release dropdown; a delete removes the stored values too), project contacts, get client, add client contact |
 | **Reference** | task statuses, task labels, locations, list webhooks (read-only), whoami |
 | **Employees** | list (name search), lookup by PIN, task-stats, inbox (mentions, new assignments, others' status changes; with the tickets toolset, also the acting employee's open tickets), create, set status |
 | **Attendance** | daily, range, per-employee, monthly summary, clock in/out, break start/end, time entries (local times in the person's zone; edit / delete your own), leaves (with `days`, half days counted 0.5), days of leave taken per type and year (`clokio_get_leave_days_taken`; the old name `clokio_get_leave_balances` still works; Clokio tracks no quota or remaining balance; leave and time-entry lists take `employee_code` and at most 92 days per call), **log time on a task**, start / stop / read the timer (see [Logging time](#logging-time)) |

package/dist/tools/projects.js

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

package/dist/tools/tasks.js

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

package/package.json

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