clokio-mcp 0.1.2 → 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.
@@ -41,6 +47,185 @@ export function seg(value) {
     }
     return encodeURIComponent(s);
 }
+/**
+ * Fetch an endpoint that returns a FILE rather than the JSON envelope.
+ *
+ * Only the attachment download does this today. Text comes back as text;
+ * anything binary is DESCRIBED rather than returned, because a model that
+ * asks for a 4 MB PNG cannot use the bytes and pouring them into the
+ * conversation as mojibake costs a fortune in tokens and tells it nothing.
+ * The description still answers the question the caller actually had - is
+ * there a file here, what kind, how big.
+ */
+export async function requestRaw(config, path, fileName) {
+    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 res;
+    try {
+        // `manual`, not 'error' and not 'follow'.
+        //
+        // The API streams small and renderable files, but 302s to a short-lived
+        // signed storage URL for anything over 8 MB. 'error' would report every
+        // large attachment as a bogus network failure. 'follow' is worse: Node
+        // re-sends request headers on a redirect, so X-API-Key would be handed
+        // to another origin, which is the leak the redirect: 'error' on the JSON
+        // path exists to prevent. So the redirect is followed HERE, by hand,
+        // with no credential attached - the signed URL needs none.
+        res = await fetch(url, {
+            headers: { 'X-API-Key': config.apiKey },
+            redirect: 'manual',
+        });
+        if (res.status >= 300 && res.status < 400) {
+            const location = res.headers.get('location');
+            if (!location) {
+                throw new ClokioApiError(0, 'Clokio redirected the download without a destination.');
+            }
+            // WHERE the redirect may point is constrained, even though the key does
+            // not travel with it.
+            //
+            // new URL() resolution is unrestricted: `file:///etc/passwd`, `data:...`
+            // and `http://169.254.169.254/...` all resolve to themselves rather than
+            // inheriting our origin. Node's fetch refuses most of those schemes on
+            // its own, but `data:` it happily resolves, and an http(s) target is a
+            // blind SSRF - this process would fetch an attacker-named URL and return
+            // up to 100k characters of the response into the model's context.
+            //
+            // Reaching that requires control of the API's own response, at which
+            // point the attacker could have put the same bytes in the attachment
+            // body - so it buys them nothing today. It is refused anyway because the
+            // check is free, and because "the API is trustworthy" is the assumption
+            // most likely to stop being true.
+            const target = new URL(location, url);
+            if (target.protocol !== 'https:' && target.protocol !== 'http:') {
+                throw new ClokioApiError(0, `Refusing to follow a download redirect to a ${target.protocol} URL.`);
+            }
+            // NO headers: the key must not cross to the storage origin.
+            res = await fetch(target, { redirect: 'error' });
+        }
+    }
+    catch (e) {
+        if (e instanceof ClokioApiError)
+            throw e;
+        throw new ClokioApiError(0, `Network error reaching Clokio: ${e.message}`);
+    }
+    if (!res.ok) {
+        const text = await res.text();
+        let message = `Clokio API returned HTTP ${res.status}`;
+        try {
+            const parsed = JSON.parse(text);
+            if (parsed && typeof parsed.message === 'string')
+                message = parsed.message;
+        }
+        catch {
+            /* a non-JSON error body is not more informative than the status */
+        }
+        throw new ClokioApiError(res.status, message);
+    }
+    const type = res.headers.get('content-type') ?? 'application/octet-stream';
+    const buffer = Buffer.from(await res.arrayBuffer());
+    // CONTENT-TYPE IS NOT ENOUGH. The API deliberately re-labels html, json,
+    // js, svg and xml attachments as application/octet-stream so a browser
+    // cannot render them from our origin - an XSS defence. Trusting the header
+    // alone would report a JSON report an agent attached as unreadable binary,
+    // so the file EXTENSION gets a say too.
+    const extension = (fileName ?? '').toLowerCase().match(/\.([a-z0-9]+)$/)?.[1] ?? '';
+    const TEXT_EXTENSIONS = new Set([
+        'txt', 'md', 'markdown', 'csv', 'tsv', 'json', 'xml', 'yaml', 'yml',
+        'html', 'htm', 'log', 'diff', 'patch', 'sql', 'js', 'ts', 'css', 'svg',
+    ]);
+    const isText = type.startsWith('text/') ||
+        /\b(json|xml|csv|yaml|javascript|markdown)\b/.test(type) ||
+        TEXT_EXTENSIONS.has(extension);
+    const kb = (buffer.byteLength / 1024).toFixed(1);
+    if (isText) {
+        // A CAP ON TEXT TOO. Attachments go up to 200 MB and .csv/.log are
+        // allowed, so "it is text" does not make it safe to paste: a 40 MB CSV
+        // would be dumped whole into the conversation. Truncate and SAY SO, so
+        // the reader never mistakes a prefix for the entire file.
+        const LIMIT = 100_000;
+        const text = buffer.toString('utf8');
+        if (text.length <= LIMIT) {
+            return text;
+        }
+        return (`[truncated: showing the first ${LIMIT.toLocaleString()} characters of ${kb} KB]\n\n` +
+            text.slice(0, LIMIT) +
+            `\n\n[...truncated. ${(text.length - LIMIT).toLocaleString()} more characters not shown.]`);
+    }
+    return (`[binary file: ${type}, ${kb} KB]\n\n` +
+        '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;
@@ -123,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/attendance.js

@@ -5,42 +5,79 @@ import { registerTool } from './helpers.js';
 const employeeCode = z
     .string()
     .regex(/^[A-Za-z0-9_-]{1,50}$/, 'employee_code must be 1-50 chars of letters, digits, _ or -');
-/** Attendance reads + clock/break writes, plus time entries and balances. */
+/** The four clock/break writes share these three optional arguments. */
+const pinArg = z
+    .string()
+    .regex(/^\d{4,6}$/, 'pin must be 4 to 6 digits')
+    .optional()
+    .describe("The employee's PIN, when the organization requires one");
+const timestampArg = z
+    .string()
+    .optional()
+    .describe("'YYYY-MM-DD HH:MM:SS'. Clamped to +/-10 minutes of server time; omit for now");
+const noteArg = z.string().max(500).optional();
+/** Attendance reads + clock/break writes, plus time entries and leave. */
 export function registerAttendanceTools(server, config) {
     registerTool(server, config, {
         name: 'clokio_attendance_daily',
-        description: 'Attendance for a single date (YYYY-MM-DD, defaults to today).',
-        schema: { date: z.string().optional().describe('YYYY-MM-DD') },
-        handler: (args, cfg) => request(cfg, '/attendance/daily', { query: { date: args.date } }),
+        description: 'Attendance for ONE date. The date is REQUIRED - there is no "today" default, so pass today\'s date ' +
+            'explicitly when that is what you want. Optionally scope to one employee.',
+        schema: {
+            date: z.string().describe('YYYY-MM-DD, required'),
+            employee_code: employeeCode.optional(),
+        },
+        handler: (args, cfg) => request(cfg, '/attendance/daily', { query: { date: args.date, employee_code: args.employee_code } }),
     });
     registerTool(server, config, {
         name: 'clokio_attendance_range',
-        description: 'Attendance for a date range (max 31 days).',
+        description: 'Attendance across a date range (max 31 days). Both dates are required.',
         schema: {
-            start_date: z.string().describe('YYYY-MM-DD'),
-            end_date: z.string().describe('YYYY-MM-DD'),
+            date_from: z.string().describe('YYYY-MM-DD, required'),
+            date_to: z.string().describe('YYYY-MM-DD, required, on or after date_from'),
+            employee_code: employeeCode.optional(),
         },
-        handler: (args, cfg) => request(cfg, '/attendance/range', { query: { start_date: args.start_date, end_date: args.end_date } }),
+        handler: (args, cfg) => request(cfg, '/attendance/range', {
+            query: { date_from: args.date_from, date_to: args.date_to, employee_code: args.employee_code },
+        }),
     });
     registerTool(server, config, {
         name: 'clokio_attendance_for_employee',
-        description: "One employee's attendance. Optionally scope to a date range.",
+        description: "One employee's attendance, optionally narrowed to a calendar month. month and year are NUMBERS " +
+            '(month 1-12), not a YYYY-MM string.',
         schema: {
             employee_code: employeeCode,
-            start_date: z.string().optional().describe('YYYY-MM-DD'),
-            end_date: z.string().optional().describe('YYYY-MM-DD'),
+            month: z.number().int().min(1).max(12).optional(),
+            year: z.number().int().min(1900).max(2100).optional(),
         },
         handler: (args, cfg) => request(cfg, `/attendance/employee/${seg(args.employee_code)}`, {
-            query: { start_date: args.start_date, end_date: args.end_date },
+            query: { month: args.month, year: args.year },
         }),
     });
+    registerTool(server, config, {
+        name: 'clokio_attendance_employee_day',
+        description: "One employee's detailed attendance for a single day, including breaks. Defaults to today when date " +
+            'is omitted.',
+        schema: {
+            employee_code: employeeCode,
+            date: z.string().optional().describe('YYYY-MM-DD, defaults to today'),
+        },
+        handler: (args, cfg) => request(cfg, `/attendance/employee/${seg(args.employee_code)}/today`, { query: { date: args.date } }),
+    });
+    registerTool(server, config, {
+        name: 'clokio_attendance_today_detailed',
+        description: 'Detailed attendance for EVERY employee on one day, including breaks. Defaults to today.',
+        schema: { date: z.string().optional().describe('YYYY-MM-DD, defaults to today') },
+        handler: (args, cfg) => request(cfg, '/attendance/today/detailed', { query: { date: args.date } }),
+    });
     registerTool(server, config, {
         name: 'clokio_attendance_summary',
-        description: 'Monthly attendance summary.',
+        description: 'Monthly attendance summary for the organization. month and year are both REQUIRED and are NUMBERS ' +
+            '(month 1-12), not a YYYY-MM string.',
         schema: {
-            month: z.string().optional().describe('YYYY-MM'),
+            month: z.number().int().min(1).max(12).describe('1-12, required'),
+            year: z.number().int().min(1900).max(2100).describe('e.g. 2026, required'),
         },
-        handler: (args, cfg) => request(cfg, '/attendance/summary', { query: { month: args.month } }),
+        handler: (args, cfg) => request(cfg, '/attendance/summary', { query: { month: args.month, year: args.year } }),
     });
     registerTool(server, config, {
         name: 'clokio_clock_in',
@@ -48,64 +85,132 @@ export function registerAttendanceTools(server, config) {
         description: 'Clock an employee in. A PIN may be required depending on org configuration. Timestamps are clamped to ' +
             '+/-10 minutes of server time.',
         schema: {
-            employee_code: z.string(),
-            pin: z.string().optional(),
-            location_id: z.number().int().optional(),
+            employee_code: employeeCode,
+            pin: pinArg,
+            project_id: z.number().int().optional().describe('Attribute the session to a project'),
+            timestamp: timestampArg,
+            note: noteArg,
         },
         handler: (args, cfg) => request(cfg, '/attendance/clock-in', {
             method: 'POST',
-            body: { employee_code: args.employee_code, pin: args.pin, location_id: args.location_id },
+            body: {
+                employee_code: args.employee_code,
+                pin: args.pin,
+                project_id: args.project_id,
+                timestamp: args.timestamp,
+                note: args.note,
+            },
         }),
     });
     registerTool(server, config, {
         name: 'clokio_clock_out',
         mutates: true,
-        description: 'Clock an employee out.',
+        description: 'Clock an employee out. A PIN may be required depending on org configuration.',
         schema: {
-            employee_code: z.string(),
-            pin: z.string().optional(),
+            employee_code: employeeCode,
+            pin: pinArg,
+            timestamp: timestampArg,
+            note: noteArg,
         },
         handler: (args, cfg) => request(cfg, '/attendance/clock-out', {
             method: 'POST',
-            body: { employee_code: args.employee_code, pin: args.pin },
+            body: {
+                employee_code: args.employee_code,
+                pin: args.pin,
+                timestamp: args.timestamp,
+                note: args.note,
+            },
         }),
     });
     registerTool(server, config, {
         name: 'clokio_break_start',
         mutates: true,
         description: 'Start a break for an employee.',
-        schema: { employee_code: z.string(), pin: z.string().optional() },
+        schema: {
+            employee_code: employeeCode,
+            pin: pinArg,
+            timestamp: timestampArg,
+            note: noteArg,
+        },
         handler: (args, cfg) => request(cfg, '/attendance/break-start', {
             method: 'POST',
-            body: { employee_code: args.employee_code, pin: args.pin },
+            body: {
+                employee_code: args.employee_code,
+                pin: args.pin,
+                timestamp: args.timestamp,
+                note: args.note,
+            },
         }),
     });
     registerTool(server, config, {
         name: 'clokio_break_end',
         mutates: true,
         description: 'End a break for an employee.',
-        schema: { employee_code: z.string(), pin: z.string().optional() },
+        schema: {
+            employee_code: employeeCode,
+            pin: pinArg,
+            timestamp: timestampArg,
+            note: noteArg,
+        },
         handler: (args, cfg) => request(cfg, '/attendance/break-end', {
             method: 'POST',
-            body: { employee_code: args.employee_code, pin: args.pin },
+            body: {
+                employee_code: args.employee_code,
+                pin: args.pin,
+                timestamp: args.timestamp,
+                note: args.note,
+            },
         }),
     });
     registerTool(server, config, {
         name: 'clokio_list_time_entries',
-        description: 'List time-tracking entries. Filterable by employee_code and date range.',
+        description: 'Time-tracking entries in a date range. from and to are both REQUIRED (YYYY-MM-DD, to >= from). ' +
+            'Optionally narrow to one person or one project.',
         schema: {
-            employee_code: z.string().optional(),
-            start_date: z.string().optional().describe('YYYY-MM-DD'),
-            end_date: z.string().optional().describe('YYYY-MM-DD'),
+            from: z.string().describe('YYYY-MM-DD, required'),
+            to: z.string().describe('YYYY-MM-DD, required, on or after from'),
+            employee: employeeCode.optional().describe("An employee_code, e.g. '00080'"),
+            project_id: z.number().int().optional(),
+            per_page: z.number().int().min(1).max(100).optional(),
         },
         handler: (args, cfg) => request(cfg, '/time-entries', {
-            query: { employee_code: args.employee_code, start_date: args.start_date, end_date: args.end_date },
+            query: {
+                from: args.from,
+                to: args.to,
+                employee: args.employee,
+                project_id: args.project_id,
+                per_page: args.per_page,
+            },
         }),
     });
     registerTool(server, config, {
-        name: 'clokio_get_balances',
-        description: 'Leave / hour balances.',
-        schema: { employee_code: z.string().optional() },
-        handler: (args, cfg) => request(cfg, '/balances', { query: { employee_code: args.employee_code } }),
+        name: 'clokio_list_leaves',
+        description: 'Leave requests in a date range. from and to are both REQUIRED (YYYY-MM-DD, to >= from). ' +
+            'Optionally narrow to one person by employee_code, or to one approval state.',
+        schema: {
+            from: z.string().describe('YYYY-MM-DD, required'),
+            to: z.string().describe('YYYY-MM-DD, required, on or after from'),
+            employee: employeeCode.optional().describe("An employee_code, e.g. '00080'"),
+            status: z.enum(['PENDING', 'APPROVED', 'REJECTED']).optional(),
+            per_page: z.number().int().min(1).max(100).optional(),
+        },
+        handler: (args, cfg) => request(cfg, '/leaves', {
+            query: {
+                from: args.from,
+                to: args.to,
+                employee: args.employee,
+                status: args.status,
+                per_page: args.per_page,
+            },
+        }),
+    });
+    registerTool(server, config, {
+        name: 'clokio_get_leave_balances',
+        description: "One employee's leave balances (quota, used, remaining per leave type). The employee_code is REQUIRED - " +
+            'there is no org-wide form of this call.',
+        schema: {
+            employee: employeeCode.describe("The employee_code, e.g. '00080'"),
+        },
+        handler: (args, cfg) => request(cfg, '/leaves/balances', { query: { employee: args.employee } }),
     });
 }

package/dist/tools/employees.js

@@ -14,25 +14,42 @@ const employeeCode = z
 export function registerEmployeeTools(server, config) {
     registerTool(server, config, {
         name: 'clokio_list_employees',
-        description: 'List employees. Returns employee_code (the stable id used everywhere else, e.g. for assignees), name, ' +
-            'and non-PII fields. email is only returned if the key holds the employees:pii scope.',
+        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. ' +
+            'Paginated: the response is {data, meta}, the people under data.',
         schema: {
-            search: z.string().optional().describe('Name filter'),
-            page: z.number().int().optional(),
+            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)'),
+            status: z.enum(['active', 'inactive']).optional(),
+            department: z.string().optional().describe('Exact department name'),
+            per_page: z.number().int().min(1).max(100).optional().describe('1-100, default 25'),
         },
-        handler: (args, cfg) => request(cfg, '/employees', { query: { search: args.search, page: args.page } }),
+        handler: (args, cfg) => request(cfg, '/employees', {
+            query: {
+                search: args.search,
+                email: args.email,
+                status: args.status,
+                department: args.department,
+                per_page: args.per_page,
+            },
+        }),
     });
     registerTool(server, config, {
-        name: 'clokio_lookup_employee',
-        description: 'Look up an employee by name or email to resolve their employee_code. Use this before assigning a task ' +
-            'when you only know the person\'s name.',
+        name: 'clokio_lookup_employee_by_pin',
+        description: 'Resolve an employee from their 4-6 digit clock-in PIN. This is for kiosk and terminal flows where a ' +
+            'person identifies themselves by PIN - it is NOT a name or email search. To find someone by name or ' +
+            'email use clokio_list_employees. Answers 404 when no ACTIVE employee holds that PIN.',
         schema: {
-            name: z.string().optional(),
-            email: z.string().optional(),
+            pin: z
+                .string()
+                .regex(/^\d{4,6}$/, 'pin must be 4 to 6 digits')
+                .describe("The employee's clock-in PIN"),
         },
         handler: (args, cfg) => request(cfg, '/employees/lookup', {
             method: 'POST',
-            body: { name: args.name, email: args.email },
+            body: { pin: args.pin },
         }),
     });
     registerTool(server, config, {
@@ -42,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,13 +1,21 @@
 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).',
-        schema: { search: z.string().optional() },
-        handler: (args, cfg) => request(cfg, '/projects', { query: { search: args.search } }),
+        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. Paginated: {data, meta}.',
+        schema: {
+            search: z.string().max(200).optional(),
+            status: z.enum(['active', 'archived']).optional(),
+            per_page: z.number().int().min(1).max(100).optional(),
+        },
+        handler: (args, cfg) => request(cfg, '/projects', {
+            query: { search: args.search, status: args.status, per_page: args.per_page },
+        }),
     });
     registerTool(server, config, {
         name: 'clokio_get_project_statuses',
@@ -36,17 +44,16 @@ export function registerProjectTools(server, config) {
     registerTool(server, config, {
         name: 'clokio_add_client_contact',
         mutates: true,
-        description: 'Add a contact to a client.',
+        description: 'Add a contact to a client. Every field is optional, but supply at least a name or an email.',
         schema: {
             client_id: z.number().int(),
-            name: z.string(),
-            email: z.string().optional(),
-            phone: z.string().optional(),
-            role: z.string().optional(),
+            name: z.string().max(255).optional(),
+            email: z.string().max(255).optional(),
+            phone: z.string().max(50).optional(),
         },
         handler: (args, cfg) => request(cfg, `/clients/${args.client_id}/contacts`, {
             method: 'POST',
-            body: { name: args.name, email: args.email, phone: args.phone, role: args.role },
+            body: { name: args.name, email: args.email, phone: args.phone },
         }),
     });
     // ── Reference / vocabulary lookups ──
@@ -59,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'),
     });
@@ -69,4 +78,38 @@ 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 ' +
+            'it), the rate limits that apply, and the person who issued it. It does NOT report the key\'s scopes ' +
+            'or expiry, deliberately - find out what a key may do by using it. ' +
+            'CALL THIS FIRST in a session: `issued_by.employee_code` is the value to pass as ' +
+            '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: {},
+        // 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,63 +1,137 @@
 import { z } from 'zod';
-import { request } 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
+    .string()
+    .regex(/^[A-Za-z0-9_-]{1,50}$/, 'employee_code must be 1-50 chars of letters, digits, _ or -');
 /** Task-management tools: the core of the Clokio API surface. */
 export function registerTaskTools(server, config) {
     registerTool(server, config, {
         name: 'clokio_list_tasks',
-        description: 'List tasks. Supports filters: project_id, status (slug), priority, assignee (employee_code), ' +
-            'label, search, open (1 = only open tasks), created_before / due_before (YYYY-MM-DD, org timezone). ' +
-            'Paginate with page, or crawl with cursor. Each task carries a task_url.',
+        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.\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"'),
             priority: z.enum(['low', 'medium', 'high', 'urgent']).optional(),
-            assignee: z.string().optional().describe('employee_code, e.g. "00080"'),
+            assignee_employee_code: employeeCode.optional().describe('employee_code, e.g. "00080"'),
             label: z.string().optional(),
-            search: z.string().optional(),
-            open: z.boolean().optional().describe('true = only tasks whose status is not "done"'),
-            created_before: z.string().optional().describe('YYYY-MM-DD'),
-            due_before: z.string().optional().describe('YYYY-MM-DD'),
+            search: z.string().optional().describe('Free text over title and description'),
+            open: z.boolean().optional().describe('true = only tasks whose status is not a "done" one'),
+            parent_task_id: z
+                .number()
+                .int()
+                .nullable()
+                .optional()
+                .describe('A task id returns only ITS subtasks; null returns only top-level tasks'),
+            created_before: z.string().optional().describe('YYYY-MM-DD, organization timezone'),
+            created_after: z.string().optional().describe('YYYY-MM-DD, organization timezone'),
+            due_before: z.string().optional().describe('YYYY-MM-DD, organization timezone'),
+            due_after: z
+                .string()
+                .optional()
+                .describe('YYYY-MM-DD. With due_before, asks for one window ("due this week") in a single request'),
+            updated_since: z
+                .string()
+                .optional()
+                .describe('ISO-8601. Incremental sync: only tasks changed at or after this instant'),
+            include_comments: z.boolean().optional(),
+            per_page: z.number().int().min(1).max(100).optional(),
             page: z.number().int().optional(),
-            cursor: z.string().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',
+                'due_date_desc',
+                'created_at',
+                'created_at_desc',
+                'updated_at',
+                'updated_at_desc',
+                'title',
+                'title_desc',
+                'priority',
+                'priority_desc',
+            ])
+                .optional()
+                .describe('Order the page. `priority` ascends low -> urgent. CANNOT be combined with cursor or ' +
+                'updated_since - that is a 422, because re-ordering a crawl silently skips rows.'),
         },
         handler: (args, cfg) => request(cfg, '/tasks', {
             query: {
                 project_id: args.project_id,
                 status: args.status,
                 priority: args.priority,
-                assignee: args.assignee,
+                assignee_employee_code: args.assignee_employee_code,
                 label: args.label,
                 search: args.search,
-                open: args.open ? 1 : undefined,
+                open: args.open === undefined ? undefined : args.open ? 1 : 0,
+                parent_task_id: args.parent_task_id === null ? '' : args.parent_task_id,
                 created_before: args.created_before,
+                created_after: args.created_after,
                 due_before: args.due_before,
+                due_after: args.due_after,
+                updated_since: args.updated_since,
+                include_comments: args.include_comments === undefined ? undefined : args.include_comments ? 1 : 0,
+                per_page: args.per_page,
                 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. assignees/creator use employee_code (e.g. "00080"), not internal ids. ' +
-            'To attribute the task to a person set creator_employee_code, otherwise it shows as the API key owner.',
+        description: 'Create a task in a project. People are named by employee_code (e.g. "00080"), never internal ids. ' +
+            '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(),
-            title: z.string(),
+            title: z.string().max(255),
             description: z.string().optional().describe('HTML or plain text'),
             priority: z.enum(['low', 'medium', 'high', 'urgent']).optional(),
-            status: z.string().optional().describe('Status slug'),
+            status: z.string().optional().describe("Status slug valid for THIS project's board"),
             due_date: z.string().optional().describe('YYYY-MM-DD'),
-            assignee_employee_codes: z.array(z.string()).optional(),
-            label_names: z.array(z.string()).optional(),
-            creator_employee_code: z.string().optional(),
+            start_date: z.string().optional().describe('YYYY-MM-DD'),
+            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()
+                .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',
@@ -68,36 +142,59 @@ export function registerTaskTools(server, config) {
                 priority: args.priority,
                 status: args.status,
                 due_date: args.due_date,
-                assignees: args.assignee_employee_codes,
-                labels: args.label_names,
-                created_by_employee_code: args.creator_employee_code,
+                start_date: args.start_date,
+                estimated_hours: args.estimated_hours,
+                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 ?? cfg.defaultActor,
             },
         }),
     });
     registerTool(server, config, {
         name: 'clokio_update_task',
         mutates: true,
-        description: 'Update a task. Only the fields you pass are changed. status/priority/title/description/due_date are supported.',
+        description: 'Update a task. ONLY the fields you pass are changed; omitted fields are left alone. Pass null to ' +
+            'due_date / start_date / estimated_hours / description to CLEAR them. Set actor_employee_code so the ' +
+            'activity log names the person rather than the API key.',
         schema: {
             id: z.number().int(),
-            title: z.string().optional(),
-            description: z.string().optional(),
+            title: z.string().max(255).optional(),
+            description: z.string().nullable().optional(),
             priority: z.enum(['low', 'medium', 'high', 'urgent']).optional(),
-            status: z.string().optional().describe('Status slug'),
-            due_date: z.string().optional().describe('YYYY-MM-DD, or empty string to clear'),
+            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'),
+            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
+            // semantics are "change what is named", and sending an untouched field
+            // as null would CLEAR it.
             const body = {};
-            if (args.title !== undefined)
-                body.title = args.title;
-            if (args.description !== undefined)
-                body.description = args.description;
-            if (args.priority !== undefined)
-                body.priority = args.priority;
-            if (args.status !== undefined)
-                body.status = args.status;
-            if (args.due_date !== undefined)
-                body.due_date = args.due_date;
+            for (const key of [
+                'title',
+                'description',
+                'priority',
+                'status',
+                'due_date',
+                'start_date',
+                'estimated_hours',
+                'project_id',
+                'actor_employee_code',
+            ]) {
+                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 });
         },
     });
@@ -111,16 +208,16 @@ export function registerTaskTools(server, config) {
     registerTool(server, config, {
         name: 'clokio_set_task_assignees',
         mutates: true,
-        description: 'Set a task\'s assignees. mode "add" appends, "replace" overwrites, "remove" removes. ' +
-            'Assignees are employee_codes (e.g. "00080").',
+        description: "Change a task's assignees. mode is REQUIRED: \"add\" appends, \"replace\" overwrites the whole list, " +
+            '"remove" takes those people off. People are named by employee_code (e.g. "00080").',
         schema: {
             id: z.number().int(),
-            employee_codes: z.array(z.string()),
-            mode: z.enum(['add', 'replace', 'remove']).optional().describe('default: add'),
+            employee_codes: z.array(employeeCode).min(1).max(50),
+            mode: z.enum(['add', 'replace', 'remove']).describe('Required'),
         },
         handler: (args, cfg) => request(cfg, `/tasks/${args.id}/assignees`, {
             method: 'PATCH',
-            body: { assignees: args.employee_codes, mode: args.mode ?? 'add' },
+            body: { employee_codes: args.employee_codes, mode: args.mode },
         }),
     });
     registerTool(server, config, {
@@ -132,17 +229,89 @@ 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, bullet lists); markdown ' +
-            'tables are not rendered.',
+        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 (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(),
-            author_employee_code: z.string().optional(),
+            body: z.string().max(65535),
+            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 },
+            body: {
+                body: args.body,
+                author_employee_code: args.author_employee_code ?? cfg.defaultActor,
+                notify: args.notify,
+            },
+        }),
+    });
+    registerTool(server, config, {
+        name: 'clokio_update_task_comment',
+        mutates: true,
+        description: 'Correct a comment YOUR integration published - a wrong number, a dead link, a mistaken finding. ' +
+            'Two conditions, both required: the comment was created through this API, and author_employee_code ' +
+            "names its own author. You cannot edit what a person wrote in the web or mobile app (403), and you " +
+            'cannot edit someone else\'s comment (403). There is no delete: correcting leaves an audit entry, ' +
+            'destroying would leave nothing.',
+        schema: {
+            id: z.number().int().describe('The task id'),
+            comment_id: z.number().int(),
+            body: z.string().max(65535),
+            author_employee_code: employeeCode.describe("Required: the comment's own author"),
+        },
+        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 ?? cfg.defaultActor },
+        }),
+    });
+    registerTool(server, config, {
+        name: 'clokio_list_task_attachments',
+        description: "A task's attachments: file name, size, mime type, who uploaded it, and the path to fetch the bytes. " +
+            'A task whose real content is a screenshot or a spreadsheet reads as "(no description)" without this - ' +
+            'check here before concluding a task has no detail. Use clokio_download_task_attachment for the file.',
+        schema: { id: z.number().int() },
+        handler: (args, cfg) => request(cfg, `/tasks/${args.id}/attachments`),
+    });
+    registerTool(server, config, {
+        name: 'clokio_download_task_attachment',
+        description: 'Download one attachment. Returns the FILE, not JSON: text comes back as text (truncated if very ' +
+            'large, and it says so), while binary files (images, PDFs, spreadsheets) are reported with their type ' +
+            'and size rather than dumped into the conversation. Get the attachment id - and file_name, which helps ' +
+            'this tool recognise text - from clokio_list_task_attachments.',
+        schema: {
+            id: z.number().int().describe('The task id'),
+            attachment_id: z.number().int(),
+            file_name: z
+                .string()
+                .optional()
+                .describe('The file_name from clokio_list_task_attachments. Improves text detection'),
+        },
+        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, {
@@ -171,6 +340,17 @@ export function registerTaskTools(server, config) {
             body: { depends_on_task_id: args.depends_on_task_id, type: args.type },
         }),
     });
+    registerTool(server, config, {
+        name: 'clokio_remove_task_dependency',
+        mutates: 'destructive',
+        description: 'Remove a dependency from a task. dependency_id is the id of the DEPENDENCY row, as returned by ' +
+            'clokio_list_task_dependencies - not the id of the other task.',
+        schema: {
+            id: z.number().int().describe('The task that holds the dependency'),
+            dependency_id: z.number().int(),
+        },
+        handler: (args, cfg) => request(cfg, `/tasks/${args.id}/dependencies/${args.dependency_id}`, { method: 'DELETE' }),
+    });
     registerTool(server, config, {
         name: 'clokio_set_task_custom_field',
         mutates: true,
@@ -186,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.1.2",
+  "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": {