clokio-mcp 0.5.3 → 0.13.0

package/README.md

@@ -24,7 +24,7 @@ permissions and the audit trail stay per-user.
 ```bash
 claude mcp add clokio \
   --env CLOKIO_API_KEY=clk_your_key_here \
-  -- npx -y clokio-mcp
+  -- npx -y clokio-mcp@latest
 ```
 
 ### Claude Desktop
@@ -36,7 +36,7 @@ Add to `claude_desktop_config.json`:
   "mcpServers": {
     "clokio": {
       "command": "npx",
-      "args": ["-y", "clokio-mcp"],
+      "args": ["-y", "clokio-mcp@latest"],
       "env": { "CLOKIO_API_KEY": "clk_your_key_here" }
     }
   }
@@ -45,32 +45,48 @@ Add to `claude_desktop_config.json`:
 
 ### Cursor / Cline / Zed / any MCP client
 
-Use the same command — `npx -y clokio-mcp` with `CLOKIO_API_KEY` in the env.
+Use the same command — `npx -y clokio-mcp@latest` with `CLOKIO_API_KEY` in the env.
 MCP is an open standard.
 
 Optional: set `CLOKIO_BASE_URL` to point at a different Clokio installation
 (defaults to `https://app.clokio.io`).
 
+Optional: set `CLOKIO_DEFAULT_ACTOR` to an `employee_code` (e.g. `00055`) to
+attribute tasks, comments and updates that name no author. You usually do not
+need it — an unnamed write is already credited to the person who issued the API
+key. Use it only for a **shared or service key** whose issuer is not the person
+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 48 tools to 26. Optional groups are `tasks`,
+`employees` and `attendance` (which includes leave and time entries); combine
+them with commas. The `projects` group (project/client lookups, task statuses
+and labels, and `whoami`) is always on, because the task tools resolve names
+through it.
+
 ## Tools
 
-36 tools across five areas. Read-only tools carry the MCP `readOnlyHint`; writes
+48 tools across five areas. Read-only tools carry the MCP `readOnlyHint`; writes
 are marked mutating (deletes are `destructive`).
 
 | Area | Tools |
 |------|-------|
-| **Tasks** | list, get, create, update, delete, set assignees, list/add comments, activity, list/add dependencies, set custom field |
+| **Tasks** | list (with `compact` / `sort` / `updated_since`), get (with `comments_limit`), create, update, delete, bulk update, set assignees, list/add/edit comments, list/upload/download attachments, activity, list/add/remove dependencies, set custom field |
 | **Projects & clients** | list projects, project statuses, project custom fields, project contacts, get client, add client contact |
-| **Reference** | task statuses, task labels, locations |
-| **Employees** | list, lookup, task-stats, create, set status |
-| **Attendance** | daily, range, per-employee, monthly summary, clock in/out, break start/end, time entries, balances |
+| **Reference** | task statuses, task labels, locations, list webhooks (read-only), whoami |
+| **Employees** | list (name search), lookup by PIN, task-stats, inbox, create, set status |
+| **Attendance** | daily, range, per-employee, monthly summary, clock in/out, break start/end, time entries, leaves, leave balances |
 
 ### Conventions
 
 - **People are identified by `employee_code`** (e.g. `00080`), not internal ids.
-  Use `clokio_lookup_employee` to resolve a name to a code.
-- **Attribute writes to a person** — pass `creator_employee_code` when creating a
-  task, `author_employee_code` when commenting, or the entry shows as the API key
-  owner ("External System").
+  Use `clokio_list_employees` (with `search`) to resolve a name to a code, or
+  `clokio_lookup_employee_by_pin` for a kiosk PIN.
+- **Attribution is automatic.** An unnamed write is credited to the key's
+  issuer (see `clokio_whoami`), so you rarely set an author. Pass
+  `created_by_employee_code` / `author_employee_code` only to credit someone
+  else, or set `CLOKIO_DEFAULT_ACTOR` for a shared key.
 - **Status slugs** come from `clokio_list_task_statuses` /
   `clokio_get_project_statuses`.
 - An API key sees **public custom fields only**.

package/dist/client.js

@@ -13,7 +13,13 @@ export function loadConfig() {
             'CLOKIO_API_KEY environment variable.');
     }
     const baseUrl = (process.env.CLOKIO_BASE_URL?.trim() || 'https://app.clokio.io').replace(/\/+$/, '');
-    return { baseUrl, apiKey };
+    const defaultActor = process.env.CLOKIO_DEFAULT_ACTOR?.trim() || undefined;
+    // Validate the same way the API constrains an employee_code, so a
+    // misconfigured value fails at startup rather than silently on every write.
+    if (defaultActor && !/^[A-Za-z0-9_-]{1,50}$/.test(defaultActor)) {
+        throw new Error('CLOKIO_DEFAULT_ACTOR must be an employee_code (1-50 chars of letters, digits, _ or -).');
+    }
+    return { baseUrl, apiKey, defaultActor };
 }
 /**
  * Encode ONE path segment supplied by a tool argument.
@@ -152,6 +158,74 @@ export async function requestRaw(config, path, fileName) {
         'The bytes are not included - they would be unreadable here and would cost a great deal of context. ' +
         'Ask the person to open the attachment in Clokio, or fetch this path yourself if you can handle binary.');
 }
+/**
+ * Upload a LOCAL FILE to a Clokio endpoint as multipart/form-data.
+ *
+ * The one write on this API that is not JSON. The tool gives a file PATH the
+ * model can already reach (it is running in a session with a filesystem), this
+ * reads it and sends it under the `file` field. Extra text fields (e.g.
+ * uploaded_by_employee_code) ride along.
+ *
+ * The same /api/v1 prefix guard and redirect: 'error' as request(), so the
+ * upload path is not a hole in either defence, and the key is sent as a header
+ * exactly as elsewhere - multipart does not change where the credential goes.
+ */
+export async function requestUpload(config, path, filePath, fields = {}) {
+    const { readFile } = await import('node:fs/promises');
+    const { basename } = await import('node:path');
+    const url = new URL(`${config.baseUrl}/api/v1${path.startsWith('/') ? path : `/${path}`}`);
+    const expectedPrefix = new URL(config.baseUrl).pathname.replace(/\/+$/, '') + '/api/v1/';
+    if (!url.pathname.startsWith(expectedPrefix)) {
+        throw new ClokioApiError(0, 'Refusing to send a request outside /api/v1.');
+    }
+    let bytes;
+    try {
+        bytes = await readFile(filePath);
+    }
+    catch (e) {
+        throw new ClokioApiError(0, `Could not read the file at ${filePath}: ${e.message}`);
+    }
+    const form = new FormData();
+    // A fresh Uint8Array view is a valid BlobPart; a Node Buffer is not, under
+    // strict lib types.
+    form.append('file', new Blob([new Uint8Array(bytes)]), basename(filePath));
+    for (const [key, value] of Object.entries(fields)) {
+        if (value !== undefined)
+            form.append(key, value);
+    }
+    let res;
+    try {
+        // Content-Type is set BY fetch from the FormData (with the boundary); do
+        // not set it by hand or the boundary is lost.
+        res = await fetch(url, {
+            method: 'POST',
+            headers: { 'X-API-Key': config.apiKey, Accept: 'application/json' },
+            body: form,
+            redirect: 'error',
+        });
+    }
+    catch (e) {
+        throw new ClokioApiError(0, `Network error reaching Clokio: ${e.message}`);
+    }
+    const text = await res.text();
+    let parsed;
+    try {
+        parsed = text ? JSON.parse(text) : undefined;
+    }
+    catch {
+        parsed = text;
+    }
+    if (!res.ok) {
+        const message = parsed && typeof parsed === 'object' && 'message' in parsed && typeof parsed.message === 'string'
+            ? parsed.message
+            : `Clokio API returned HTTP ${res.status}`;
+        throw new ClokioApiError(res.status, message, parsed);
+    }
+    if (parsed && typeof parsed === 'object' && 'data' in parsed) {
+        return parsed.data;
+    }
+    return parsed;
+}
 /** A Clokio API error, carrying the HTTP status and the server's message. */
 export class ClokioApiError extends Error {
     status;
@@ -234,9 +308,24 @@ export async function request(config, path, options = {}) {
             : `Clokio API returned HTTP ${res.status}`);
         throw new ClokioApiError(res.status, message, parsed);
     }
-    // Standard envelope: {status, message, data}. Unwrap `data` when present.
+    // Standard envelope: {status, message, data, meta?}. Unwrap `data`, but
+    // KEEP `meta` when the API sent one.
+    //
+    // Unwrapping both was a real defect: list endpoints return
+    // meta.next_cursor, meta.total and meta.last_page, and this threw all of it
+    // away. The tool descriptions told the model to page with a cursor while
+    // the value it needed had already been discarded - so a caller could not
+    // tell a full first page from the whole result set, and every crawl past
+    // page one was impossible. Reported 2026-09-26.
+    //
+    // `data` is returned bare when there is no meta, so single-object reads
+    // (get_task, whoami) keep the shape they have always had.
     if (parsed && typeof parsed === 'object' && 'data' in parsed) {
-        return parsed.data;
+        const envelope = parsed;
+        if (envelope.meta !== undefined && envelope.meta !== null) {
+            return { data: envelope.data, meta: envelope.meta };
+        }
+        return envelope.data;
     }
     return parsed;
 }

package/dist/index.js

@@ -10,31 +10,66 @@
  * Or register with: claude mcp add clokio -- npx -y clokio-mcp
  * (set CLOKIO_API_KEY, and optionally CLOKIO_BASE_URL, in the MCP env).
  */
-import { createRequire } from 'node:module';
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
 import { loadConfig } from './client.js';
+import { VERSION } from './version.js';
 import { registerTaskTools } from './tools/tasks.js';
 import { registerProjectTools } from './tools/projects.js';
 import { registerEmployeeTools } from './tools/employees.js';
 import { registerAttendanceTools } from './tools/attendance.js';
-// The version the MCP handshake announces is package.json's, read at runtime -
-// a literal here went stale on the first patch release (0.1.1 said 0.1.0).
-const { version } = createRequire(import.meta.url)('../package.json');
+/**
+ * The optional tool groups a session can turn OFF.
+ *
+ * tools/list is ~8k tokens with everything registered, and a task-focused
+ * session never touches the 13 attendance/leave/time tools or the 5 employee
+ * ones. Setting e.g. CLOKIO_TOOLSETS=tasks drops them, cutting the per-session
+ * cost.
+ *
+ * `projects` is NOT selectable: it holds whoami and the reference lookups
+ * (task statuses, labels, projects, locations) that the task tools depend on
+ * to resolve names to ids, so it is always registered. Naming a toolset that
+ * does not exist is refused at startup rather than silently ignored.
+ */
+const OPTIONAL_TOOLSETS = ['tasks', 'employees', 'attendance'];
+function selectedToolsets() {
+    const raw = process.env.CLOKIO_TOOLSETS?.trim();
+    if (!raw) {
+        // Default: everything.
+        return new Set(OPTIONAL_TOOLSETS);
+    }
+    const requested = raw
+        .split(',')
+        .map((s) => s.trim().toLowerCase())
+        .filter(Boolean);
+    const unknown = requested.filter((s) => !OPTIONAL_TOOLSETS.includes(s));
+    if (unknown.length) {
+        throw new Error(`CLOKIO_TOOLSETS names unknown toolset(s): ${unknown.join(', ')}. ` +
+            `Valid values are: ${OPTIONAL_TOOLSETS.join(', ')} (projects is always on).`);
+    }
+    return new Set(requested);
+}
 async function main() {
     const config = loadConfig();
+    const toolsets = selectedToolsets();
     const server = new McpServer({
         name: 'clokio-mcp',
-        version,
+        version: VERSION,
     });
-    registerTaskTools(server, config);
+    // Always on: whoami plus the reference lookups the task tools resolve
+    // names against.
     registerProjectTools(server, config);
-    registerEmployeeTools(server, config);
-    registerAttendanceTools(server, config);
+    if (toolsets.has('tasks'))
+        registerTaskTools(server, config);
+    if (toolsets.has('employees'))
+        registerEmployeeTools(server, config);
+    if (toolsets.has('attendance'))
+        registerAttendanceTools(server, config);
     const transport = new StdioServerTransport();
     await server.connect(transport);
     // stderr is safe for logs on stdio transport (stdout carries the protocol).
-    process.stderr.write(`clokio-mcp connected (base: ${config.baseUrl})\n`);
+    const active = ['projects', ...OPTIONAL_TOOLSETS.filter((t) => toolsets.has(t))].join(', ');
+    process.stderr.write(`clokio-mcp ${VERSION} connected (base: ${config.baseUrl}, toolsets: ${active})\n`);
 }
 main().catch((e) => {
     process.stderr.write(`clokio-mcp failed to start: ${e.message}\n`);

package/dist/tools/employees.js

@@ -17,7 +17,8 @@ export function registerEmployeeTools(server, config) {
         description: 'Find people. This is how you resolve a PERSON TO THEIR employee_code - the stable id every other tool ' +
             'wants for assignees, comment authors and task creators. Pass `search` with a name (or part of one) ' +
             'rather than listing everyone and matching yourself. Combine with status=active to skip people who have ' +
-            'left. email is returned only if the key holds the employees:pii scope.',
+            'left. email is returned only if the key holds the employees:pii scope. ' +
+            'Paginated: the response is {data, meta}, the people under data.',
         schema: {
             search: z.string().max(120).optional().describe('Free text over name and employee_code'),
             email: z.string().optional().describe('EXACT email match (not a substring search)'),
@@ -58,9 +59,30 @@ export function registerEmployeeTools(server, config) {
         schema: {
             employee_code: employeeCode,
             stale_days: z.number().int().min(1).max(365).optional(),
+            definitions: z
+                .boolean()
+                .optional()
+                .describe('false drops the definitions block once you know what the numbers mean'),
         },
         handler: (args, cfg) => request(cfg, `/employees/${seg(args.employee_code)}/task-stats`, {
-            query: { stale_days: args.stale_days },
+            query: {
+                stale_days: args.stale_days,
+                definitions: args.definitions === undefined ? undefined : args.definitions ? 1 : 0,
+            },
+        }),
+    });
+    registerTool(server, config, {
+        name: 'clokio_get_inbox',
+        description: 'What needs one person\'s attention: mentions_waiting (comments that @-mention them and that they have ' +
+            'NOT replied to yet) and newly_assigned (tasks assigned to them in the window). This is how you find ' +
+            'that someone asked a question, without scanning the board. `since` defaults to 14 days (max 90). ' +
+            'To answer for the KEY OWNER, pass their own employee_code (from clokio_whoami).',
+        schema: {
+            employee_code: employeeCode,
+            since: z.string().optional().describe('ISO-8601 or YYYY-MM-DD. Only items after this. Default 14 days ago'),
+        },
+        handler: (args, cfg) => request(cfg, `/employees/${seg(args.employee_code)}/inbox`, {
+            query: { since: args.since },
         }),
     });
     registerTool(server, config, {

package/dist/tools/projects.js

@@ -1,12 +1,13 @@
 import { z } from 'zod';
 import { request } from '../client.js';
 import { registerTool } from './helpers.js';
+import { VERSION } from '../version.js';
 /** Projects, clients, and the board-configuration + reference lookups. */
 export function registerProjectTools(server, config) {
     registerTool(server, config, {
         name: 'clokio_list_projects',
         description: 'List projects, optionally filtered by a search term (name / client) or status. Use this to resolve a ' +
-            'project NAME to the project_id every task tool needs.',
+            'project NAME to the project_id every task tool needs. Paginated: {data, meta}.',
         schema: {
             search: z.string().max(200).optional(),
             status: z.enum(['active', 'archived']).optional(),
@@ -65,7 +66,9 @@ export function registerProjectTools(server, config) {
     });
     registerTool(server, config, {
         name: 'clokio_list_task_labels',
-        description: 'List the available task labels (tags), with names and colors.',
+        description: 'List the available task labels (tags), with names and colors. There is no separate "create label" ' +
+            'call and none is needed: naming a label that does not exist yet in clokio_create_task\'s label_names ' +
+            'creates it. Check this list first so you reuse an existing label instead of creating a near-duplicate.',
         schema: {},
         handler: (_args, cfg) => request(cfg, '/task-labels'),
     });
@@ -75,6 +78,18 @@ export function registerProjectTools(server, config) {
         schema: {},
         handler: (_args, cfg) => request(cfg, '/locations'),
     });
+    registerTool(server, config, {
+        name: 'clokio_list_webhooks',
+        description: 'The organisation\'s webhooks with their delivery health (sent / succeeded / failed, last error), for ' +
+            'answering "why did a notification not arrive?". READ ONLY - webhooks are created in the Clokio ' +
+            'dashboard, never through the API. The destination URL is masked (a webhook URL carries a secret token).',
+        schema: {
+            active: z.boolean().optional().describe('Filter to active (true) or inactive (false) webhooks'),
+        },
+        handler: (args, cfg) => request(cfg, '/webhooks', {
+            query: { active: args.active === undefined ? undefined : args.active ? 1 : 0 },
+        }),
+    });
     registerTool(server, config, {
         name: 'clokio_whoami',
         description: 'Who this API key belongs to: the organisation (with its timezone - every date filter is evaluated in ' +
@@ -84,6 +99,17 @@ export function registerProjectTools(server, config) {
             'created_by_employee_code / author_employee_code on every write, so the work is attributed to a person ' +
             'instead of showing up as "External System" on a board the team reads. `issued_by` can be null.',
         schema: {},
-        handler: (_args, cfg) => request(cfg, '/me'),
+        // mcp_version is added CLIENT-side, from the running package, because the
+        // server cannot know which build is talking to it.
+        //
+        // It exists for one reason: `npx -y clokio-mcp` can serve a CACHED old
+        // build, and a session then reports bugs that were fixed releases ago
+        // against tools it does not actually have. That happened on 2026-09-26 -
+        // a session ran 0.1.2 while 0.5.3 was current, and the mismatch took a
+        // while to spot. Now the first call of a session states the version.
+        handler: async (_args, cfg) => {
+            const me = (await request(cfg, '/me'));
+            return { ...me, mcp_version: VERSION };
+        },
     });
 }

package/dist/tools/tasks.js

@@ -1,5 +1,5 @@
 import { z } from 'zod';
-import { request, requestRaw } from '../client.js';
+import { request, requestRaw, requestUpload } from '../client.js';
 import { registerTool } from './helpers.js';
 /** See employees.ts - the same stable-identifier rule applies to task filters. */
 const employeeCode = z
@@ -11,7 +11,9 @@ export function registerTaskTools(server, config) {
         name: 'clokio_list_tasks',
         description: 'List tasks across projects, with server-side filters so you do not page the whole board and count in ' +
             '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.',
+            '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.',
         schema: {
             project_id: z.number().int().optional(),
             status: z.string().optional().describe('Status slug, e.g. "in_progress"'),
@@ -41,6 +43,12 @@ export function registerTaskTools(server, config) {
             per_page: z.number().int().min(1).max(100).optional(),
             page: z.number().int().optional(),
             cursor: z.string().optional().describe('meta.next_cursor from a previous page; preferred over page'),
+            compact: z
+                .boolean()
+                .optional()
+                .describe('STRONGLY PREFERRED when scanning. Returns id, title, status, priority, due_date, project, ' +
+                'assignees, labels and updated_at only - dropping the HTML description, which is most of the ' +
+                'payload. Fetch the one task you actually need in full with clokio_get_task.'),
             sort: z
                 .enum([
                 'due_date',
@@ -78,21 +86,34 @@ export function registerTaskTools(server, config) {
                 page: args.page,
                 cursor: args.cursor,
                 sort: args.sort,
+                compact: args.compact === undefined ? undefined : args.compact ? 1 : 0,
             },
         }),
     });
     registerTool(server, config, {
         name: 'clokio_get_task',
-        description: 'Get one task by id, with its full detail (assignees, labels, status, custom fields, task_url).',
-        schema: { id: z.number().int() },
-        handler: (args, cfg) => request(cfg, `/tasks/${args.id}`),
+        description: 'Get one task by id, with its full detail (assignees, labels, status, custom fields, task_url) and ' +
+            'its comments. A long-running task can carry dozens of comments: pass comments_limit to keep only the ' +
+            'newest few, or 0 for none. comments_count always reports the real total.',
+        schema: {
+            id: z.number().int(),
+            comments_limit: z
+                .number()
+                .int()
+                .min(0)
+                .max(200)
+                .optional()
+                .describe('Newest N comments only (0 = none). Omitted returns every comment'),
+        },
+        handler: (args, cfg) => request(cfg, `/tasks/${args.id}`, { query: { comments_limit: args.comments_limit } }),
     });
     registerTool(server, config, {
         name: 'clokio_create_task',
         mutates: true,
         description: 'Create a task in a project. People are named by employee_code (e.g. "00080"), never internal ids. ' +
-            'ALWAYS set created_by_employee_code to attribute the task to a person - without it the task shows as ' +
-            'the API key owner ("External System"). Pass parent_task_id to create it as a SUBTASK of that task ' +
+            'You do NOT normally need created_by_employee_code: an unnamed task is attributed to the key\'s issuer ' +
+            'automatically (whoami shows who that is). Set it only to credit someone OTHER than the key owner. ' +
+            'Pass parent_task_id to create it as a SUBTASK of that task ' +
             '(same project, and the parent must not itself be a subtask - one level deep only).',
         schema: {
             project_id: z.number().int(),
@@ -105,8 +126,12 @@ export function registerTaskTools(server, config) {
             estimated_hours: z.number().min(0).max(9999.99).optional(),
             parent_task_id: z.number().int().optional().describe('Makes this a subtask of that task'),
             assignee_employee_codes: z.array(employeeCode).max(50).optional(),
-            label_names: z.array(z.string().max(100)).max(20).optional(),
-            created_by_employee_code: employeeCode.optional().describe('Attribute the task to this person'),
+            label_names: z
+                .array(z.string().max(100))
+                .max(20)
+                .optional()
+                .describe('Label names. A name that does not exist yet is CREATED - check clokio_list_task_labels first'),
+            created_by_employee_code: employeeCode.optional().describe('Credit someone OTHER than the key owner; omit to use the key issuer / CLOKIO_DEFAULT_ACTOR'),
         },
         handler: (args, cfg) => request(cfg, '/tasks', {
             method: 'POST',
@@ -122,7 +147,7 @@ export function registerTaskTools(server, config) {
                 parent_task_id: args.parent_task_id,
                 assignee_employee_codes: args.assignee_employee_codes,
                 label_names: args.label_names,
-                created_by_employee_code: args.created_by_employee_code,
+                created_by_employee_code: args.created_by_employee_code ?? cfg.defaultActor,
             },
         }),
     });
@@ -142,7 +167,7 @@ export function registerTaskTools(server, config) {
             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'),
-            actor_employee_code: employeeCode.optional().describe('Who to credit in the activity log'),
+            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) => {
             // Only keys the caller actually supplied may go in the body: PATCH
@@ -163,6 +188,13 @@ export function registerTaskTools(server, config) {
                 if (args[key] !== undefined)
                     body[key] = args[key];
             }
+            // 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
+            // actor_employee_code above already sits in body and is left untouched.
+            if (body.actor_employee_code === undefined && cfg.defaultActor) {
+                body.actor_employee_code = cfg.defaultActor;
+            }
             return request(cfg, `/tasks/${args.id}`, { method: 'PATCH', body });
         },
     });
@@ -197,25 +229,26 @@ export function registerTaskTools(server, config) {
     registerTool(server, config, {
         name: 'clokio_add_task_comment',
         mutates: true,
-        description: 'Add a comment to a task. Set author_employee_code to attribute it to a person; otherwise it shows as ' +
-            'the API key owner ("External System"). Use readable formatting (paragraphs, blank lines, bullet ' +
-            'lists); markdown TABLES are not rendered and post as raw text. Write in the language of the person ' +
-            'you are answering. ' +
+        description: 'Add a comment to a task. author_employee_code is usually unnecessary: an unnamed comment is attributed ' +
+            'to the key issuer automatically. Set it only to credit someone else. Use readable formatting ' +
+            '(paragraphs, blank lines, bullet lists); markdown TABLES are not rendered and post as raw text. Write ' +
+            'in the language of the person you are answering. ' +
             'TO MENTION SOMEONE, write @ followed by their full name exactly as clokio_list_employees spells it ' +
             '(for example "@Kiran Bahadur") in the body text - no markup needed. It becomes a real mention and ' +
-            'notifies them, but only if the comment has an author_employee_code; an unattributed comment notifies ' +
-            'nobody. A name that matches no one stays as plain text, so check the spelling first.',
+            'notifies them, but only if the comment has an author (its own field, the key issuer, or ' +
+            'CLOKIO_DEFAULT_ACTOR); a truly authorless comment notifies nobody. A name that matches no one stays ' +
+            'as plain text, so check the spelling first.',
         schema: {
             id: z.number().int(),
             body: z.string().max(65535),
-            author_employee_code: employeeCode.optional().describe('Attribute the comment to this person'),
+            author_employee_code: employeeCode.optional().describe('Credit someone OTHER than the key owner; omit to use the key issuer / CLOKIO_DEFAULT_ACTOR'),
             notify: z.boolean().optional().describe('Send notifications to watchers (default: the API decides)'),
         },
         handler: (args, cfg) => request(cfg, `/tasks/${args.id}/comments`, {
             method: 'POST',
             body: {
                 body: args.body,
-                author_employee_code: args.author_employee_code,
+                author_employee_code: args.author_employee_code ?? cfg.defaultActor,
                 notify: args.notify,
             },
         }),
@@ -236,7 +269,7 @@ export function registerTaskTools(server, config) {
         },
         handler: (args, cfg) => request(cfg, `/tasks/${args.id}/comments/${args.comment_id}`, {
             method: 'PATCH',
-            body: { body: args.body, author_employee_code: args.author_employee_code },
+            body: { body: args.body, author_employee_code: args.author_employee_code ?? cfg.defaultActor },
         }),
     });
     registerTool(server, config, {
@@ -263,6 +296,24 @@ export function registerTaskTools(server, config) {
         },
         handler: (args, cfg) => requestRaw(cfg, `/tasks/${args.id}/attachments/${args.attachment_id}`, args.file_name),
     });
+    registerTool(server, config, {
+        name: 'clokio_upload_task_attachment',
+        mutates: true,
+        description: 'Upload a LOCAL FILE to a task as an attachment - a screenshot, a log, a spreadsheet. Give the path to ' +
+            'a file on this machine; it is read and sent. Allowed types include images, PDF, Office docs, txt/csv/' +
+            'md/json, code diffs, zip and video, up to 200 MB. The uploader is the key issuer unless you set ' +
+            'uploaded_by_employee_code.',
+        schema: {
+            id: z.number().int().describe('The task id'),
+            file_path: z.string().describe('Path to a file on THIS machine'),
+            uploaded_by_employee_code: employeeCode
+                .optional()
+                .describe('Credit someone other than the key owner; omit to use the key issuer'),
+        },
+        handler: (args, cfg) => requestUpload(cfg, `/tasks/${args.id}/attachments`, args.file_path, {
+            uploaded_by_employee_code: args.uploaded_by_employee_code ?? cfg.defaultActor,
+        }),
+    });
     registerTool(server, config, {
         name: 'clokio_get_task_activity',
         description: 'Get the activity log (audit trail) for a task.',
@@ -315,4 +366,31 @@ export function registerTaskTools(server, config) {
             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.',
+        schema: {
+            ids: z.array(z.number().int()).min(1).max(200),
+            status: z.string().optional().describe('Status slug - validated per task against its own board'),
+            priority: z.enum(['low', 'medium', 'high', 'urgent']).optional(),
+            due_date: z.string().nullable().optional().describe('YYYY-MM-DD, or null to clear'),
+            actor_employee_code: employeeCode.optional().describe('Who to credit; omit to use the key issuer'),
+        },
+        handler: (args, cfg) => {
+            const body = { ids: args.ids };
+            if (args.status !== undefined)
+                body.status = args.status;
+            if (args.priority !== undefined)
+                body.priority = args.priority;
+            if (args.due_date !== undefined)
+                body.due_date = args.due_date;
+            body.actor_employee_code = args.actor_employee_code ?? cfg.defaultActor;
+            return request(cfg, '/tasks/bulk', { method: 'PATCH', body });
+        },
+    });
 }

package/dist/version.js

@@ -0,0 +1,15 @@
+import { createRequire } from 'node:module';
+/**
+ * This package's version, read from package.json at runtime.
+ *
+ * ONE source for it. A literal went stale on the first patch release (0.1.1
+ * announced itself as 0.1.0), and there are now two consumers that must not
+ * drift apart: the MCP handshake in index.ts, and clokio_whoami, which
+ * reports it so a session can tell WHICH build it is running.
+ *
+ * That second use is not cosmetic. `npx -y clokio-mcp` can serve a cached old
+ * build, and a session then reports bugs fixed releases ago against tools it
+ * does not have - which is exactly what happened on 2026-09-26, with 0.1.2
+ * running while 0.5.3 was current.
+ */
+export const VERSION = createRequire(import.meta.url)('../package.json').version;

package/package.json

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