clokio-mcp 0.1.2 → 0.5.3

package/dist/client.js

@@ -41,6 +41,117 @@ 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.');
+}
 /** A Clokio API error, carrying the HTTP status and the server's message. */
 export class ClokioApiError extends Error {
     status;

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,41 @@ 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.',
         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, {

package/dist/tools/projects.js

@@ -5,9 +5,16 @@ import { registerTool } from './helpers.js';
 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.',
+        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 +43,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 ──
@@ -69,4 +75,15 @@ export function registerProjectTools(server, config) {
         schema: {},
         handler: (_args, cfg) => request(cfg, '/locations'),
     });
+    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: {},
+        handler: (_args, cfg) => request(cfg, '/me'),
+    });
 }

package/dist/tools/tasks.js

@@ -1,39 +1,83 @@
 import { z } from 'zod';
-import { request } from '../client.js';
+import { request, requestRaw } 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.',
         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'),
+            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,
             },
         }),
     });
@@ -46,18 +90,23 @@ export function registerTaskTools(server, config) {
     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. ' +
+            '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 ' +
+            '(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(),
+            created_by_employee_code: employeeCode.optional().describe('Attribute the task to this person'),
         },
         handler: (args, cfg) => request(cfg, '/tasks', {
             method: 'POST',
@@ -68,36 +117,52 @@ 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,
             },
         }),
     });
     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'),
         },
         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];
+            }
             return request(cfg, `/tasks/${args.id}`, { method: 'PATCH', body });
         },
     });
@@ -111,16 +176,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, {
@@ -133,18 +198,71 @@ export function registerTaskTools(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.',
+            '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. ' +
+            '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.',
         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('Attribute the comment to this person'),
+            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,
+                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 },
         }),
     });
+    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_get_task_activity',
         description: 'Get the activity log (audit trail) for a task.',
@@ -171,6 +289,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,

package/package.json

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