clokio-mcp 0.13.2 → 0.14.0

package/README.md

@@ -9,9 +9,13 @@ to your Clokio workspace to read and manage tasks, projects, clients, employees
 and attendance in natural language.
 
 Every request is authenticated with **your own** Clokio API key (`clk_...`),
-sent as `X-API-Key`. The key carries its own scopes, so this server never
-re-implements authorization: it is a thin, stateless client, and a `403` / `422`
-from the API is surfaced verbatim.
+sent in the **`X-API-Key`** header. The key carries its own scopes, so this
+server never re-implements authorization: it is a thin, stateless client, and a
+`403` / `422` from the API is surfaced verbatim.
+
+> **Auth header:** the Clokio Public API accepts the key only in `X-API-Key`.
+> An `Authorization: Bearer <key>` header is **not** recognised and returns
+> `401`. If you call the API directly (not through this server), use `X-API-Key`.
 
 ## Install
 
@@ -72,10 +76,10 @@ are marked mutating (deletes are `destructive`).
 
 | Area | Tools |
 |------|-------|
-| **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 |
+| **Tasks** | list (with `compact` / `sort` / `updated_since`), get (with `comments_limit`), create, update, delete, bulk update, set assignees, list/add/edit comments, list attachments (with `is_latest` + `latest_only`), upload, download one (save to disk, or read PDF text / ZIP entries / images / text inline), download all to a folder, 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, list webhooks (read-only), whoami |
-| **Employees** | list (name search), lookup by PIN, task-stats, inbox, create, set status |
+| **Employees** | list (name search), lookup by PIN, task-stats, inbox (mentions, new assignments, others' status changes), create, set status |
 | **Attendance** | daily, range, per-employee, monthly summary, clock in/out, break start/end, time entries, leaves, leave balances |
 
 ### Conventions

package/dist/attachments.js

@@ -0,0 +1,362 @@
+/**
+ * Attachment handling: everything that turns the raw bytes of a Clokio
+ * attachment into something an agent can actually use - save it to disk, read a
+ * PDF's text, list a ZIP's entries, or hand an image to the model.
+ *
+ * The bytes themselves come from client.ts (requestRawBytes), which owns the
+ * credential and redirect handling. This module never fetches; it only decides
+ * what to DO with what it was given.
+ */
+import { ClokioApiError, looksLikeText, requestRawBytes } from './client.js';
+import { mcpContent } from './tools/helpers.js';
+/**
+ * How much decoded text (PDF or text file) we return inline before truncating.
+ * Same reasoning as the text cap in requestRaw: a 5 MB PDF of logs would bury
+ * the conversation. The caller can always pass save_path for the whole file.
+ */
+const TEXT_INLINE_LIMIT = 100_000;
+/**
+ * How large an image we are willing to hand to the model as base64. Images ride
+ * in the context as tokens; a 20 MB screenshot is both unusable and ruinous.
+ * Over this, we describe it and point at save_path.
+ */
+const IMAGE_INLINE_LIMIT = 4 * 1024 * 1024; // 4 MB
+function extensionOf(fileName) {
+    return (fileName ?? '').toLowerCase().match(/\.([a-z0-9]+)$/)?.[1] ?? '';
+}
+async function sha256Hex(buffer) {
+    // Dynamic import, not require(): this is an ES module.
+    const { createHash } = await import('node:crypto');
+    return createHash('sha256').update(buffer).digest('hex');
+}
+const IMAGE_MIME = {
+    png: 'image/png',
+    jpg: 'image/jpeg',
+    jpeg: 'image/jpeg',
+    gif: 'image/gif',
+    webp: 'image/webp',
+    bmp: 'image/bmp',
+};
+function imageMimeFor(contentType, fileName) {
+    if (contentType.startsWith('image/'))
+        return contentType.split(';')[0].trim();
+    const ext = extensionOf(fileName);
+    return IMAGE_MIME[ext] ?? null;
+}
+/**
+ * Extract text from a PDF buffer, page by page, with pdfjs-dist (Mozilla's
+ * maintained PDF engine). Loaded lazily so a session that never reads a PDF
+ * pays nothing for it, and wrapped by the caller so a parse failure (encrypted
+ * or image-only PDF) degrades to a clear message rather than crashing the tool.
+ *
+ * The `legacy` build is used deliberately: it is the CommonJS/Node-targeted bundle
+ * that runs without a browser Worker. `pdf-parse` was tried first and REJECTED -
+ * version 1.1.x fails "bad XRef entry" on valid PDFs (reproduced against a
+ * reportlab PDF and a macOS system PDF), so it would have failed on real
+ * attachments in production while passing a naive smoke test.
+ */
+async function extractPdfText(buffer) {
+    // @ts-ignore - the legacy build has no bundled types; its runtime shape is used.
+    const pdfjs = await import('pdfjs-dist/legacy/build/pdf.mjs');
+    const data = new Uint8Array(buffer);
+    const doc = await pdfjs.getDocument({ data, useSystemFonts: true, isEvalSupported: false }).promise;
+    // destroy() in finally: a throw from getPage/getTextContent on a malformed PDF
+    // is caught by the caller for the user message, but WITHOUT this the pdfjs
+    // document and its worker would leak for the life of the process, and a run of
+    // failing PDFs would pile them up.
+    try {
+        const parts = [];
+        for (let n = 1; n <= doc.numPages; n++) {
+            const page = await doc.getPage(n);
+            const content = await page.getTextContent();
+            parts.push(content.items.map((i) => (typeof i.str === 'string' ? i.str : '')).join(' '));
+        }
+        return { text: parts.join('\n\n'), pages: doc.numPages };
+    }
+    finally {
+        await doc.destroy();
+    }
+}
+function capText(text) {
+    if (text.length <= TEXT_INLINE_LIMIT)
+        return { body: text, truncated: false };
+    return {
+        body: text.slice(0, TEXT_INLINE_LIMIT) +
+            `\n\n[...truncated. ${(text.length - TEXT_INLINE_LIMIT).toLocaleString()} more characters not shown. ` +
+            'Pass save_path to write the whole file to disk.]',
+        truncated: true,
+    };
+}
+/**
+ * List a ZIP's entries by reading its End Of Central Directory record and the
+ * Central Directory, with no third-party library and WITHOUT inflating any
+ * entry. This is a read of the archive's table of contents only - names, sizes
+ * and modification dates - which is exactly what the spec asks for.
+ *
+ * Format: PKZIP APPNOTE. EOCD signature 0x06054b50 sits near the end (it may be
+ * followed by up to 65,535 bytes of comment, so we scan backwards for it).
+ * Each central-directory header is signature 0x02014b50 followed by fixed
+ * fields, then variable name/extra/comment lengths.
+ */
+export function listZipEntries(buffer) {
+    const EOCD_SIG = 0x06054b50;
+    const CEN_SIG = 0x02014b50;
+    const ZIP64_EOCD_LOCATOR_SIG = 0x07064b50;
+    // Find EOCD by scanning back from the end for its signature. This is how every
+    // ZIP reader locates it (the record has no fixed position - it may be followed
+    // by up to 64 KB of comment), so a signature embedded in a comment or in stored
+    // data could in principle false-match. We accept that: it is the standard
+    // approach, the listing is advisory (names/sizes, never extraction), and a
+    // misread yields a clear "not a readable ZIP" rather than a wrong file. 22
+    // bytes is the minimum EOCD size.
+    let eocd = -1;
+    const minEocd = 22;
+    const scanStart = Math.max(0, buffer.length - (minEocd + 0xffff));
+    for (let i = buffer.length - minEocd; i >= scanStart; i--) {
+        if (buffer.readUInt32LE(i) === EOCD_SIG) {
+            eocd = i;
+            break;
+        }
+    }
+    if (eocd < 0) {
+        throw new ClokioApiError(0, 'Not a readable ZIP (no end-of-central-directory record found).');
+    }
+    let entryCount = buffer.readUInt16LE(eocd + 10);
+    let cdOffset = buffer.readUInt32LE(eocd + 16);
+    // ZIP64: a 0xffff count or 0xffffffff offset means the real values live in the
+    // ZIP64 EOCD, located via the ZIP64 EOCD locator just before the EOCD.
+    if ((entryCount === 0xffff || cdOffset === 0xffffffff) && eocd - 20 >= 0) {
+        const locator = eocd - 20;
+        if (buffer.readUInt32LE(locator) === ZIP64_EOCD_LOCATOR_SIG) {
+            const z64 = Number(buffer.readBigUInt64LE(locator + 8));
+            if (buffer.readUInt32LE(z64) === 0x06064b50) {
+                entryCount = Number(buffer.readBigUInt64LE(z64 + 32));
+                cdOffset = Number(buffer.readBigUInt64LE(z64 + 48));
+            }
+        }
+    }
+    const entries = [];
+    let p = cdOffset;
+    for (let n = 0; n < entryCount && p + 46 <= buffer.length; n++) {
+        if (buffer.readUInt32LE(p) !== CEN_SIG)
+            break;
+        const compressedSize = buffer.readUInt32LE(p + 20);
+        const uncompressedSize = buffer.readUInt32LE(p + 24);
+        const nameLen = buffer.readUInt16LE(p + 28);
+        const extraLen = buffer.readUInt16LE(p + 30);
+        const commentLen = buffer.readUInt16LE(p + 32);
+        const dosTime = buffer.readUInt16LE(p + 12);
+        const dosDate = buffer.readUInt16LE(p + 14);
+        const name = buffer.toString('utf8', p + 46, p + 46 + nameLen);
+        entries.push({
+            name,
+            size: uncompressedSize,
+            compressed_size: compressedSize,
+            modified: dosDateToIso(dosDate, dosTime),
+        });
+        p += 46 + nameLen + extraLen + commentLen;
+    }
+    return entries;
+}
+/** Decode a DOS date+time pair (ZIP's native stamp) into an ISO-ish string. */
+function dosDateToIso(dosDate, dosTime) {
+    if (dosDate === 0)
+        return null;
+    const day = dosDate & 0x1f;
+    const month = (dosDate >> 5) & 0x0f;
+    const year = ((dosDate >> 9) & 0x7f) + 1980;
+    const second = (dosTime & 0x1f) * 2;
+    const minute = (dosTime >> 5) & 0x3f;
+    const hour = (dosTime >> 11) & 0x1f;
+    const pad = (v) => String(v).padStart(2, '0');
+    return `${year}-${pad(month)}-${pad(day)} ${pad(hour)}:${pad(minute)}:${pad(second)}`;
+}
+/**
+ * Write a buffer to an absolute-or-relative path, creating parent directories.
+ * Refuses to overwrite unless told to. Returns the resolved absolute path.
+ */
+export async function saveBuffer(buffer, savePath, overwrite) {
+    const { mkdir, writeFile, access } = await import('node:fs/promises');
+    const { dirname, resolve } = await import('node:path');
+    const abs = resolve(savePath);
+    if (!overwrite) {
+        let exists = true;
+        try {
+            await access(abs);
+        }
+        catch {
+            exists = false;
+        }
+        if (exists) {
+            throw new ClokioApiError(0, `Refusing to overwrite an existing file at ${abs}. Pass overwrite: true to replace it.`);
+        }
+    }
+    await mkdir(dirname(abs), { recursive: true });
+    await writeFile(abs, buffer);
+    return abs;
+}
+/**
+ * Download one attachment and either save it, or return its content in the most
+ * usable form for its type:
+ *   - save_path set  -> write to disk, return {saved_to, sha256, ...}
+ *   - text-like      -> the decoded text (capped)
+ *   - PDF            -> extracted text + page count (capped)
+ *   - ZIP            -> the entry list
+ *   - image          -> the image itself, as MCP image content
+ *   - anything else  -> a type+size description, as today
+ */
+export async function downloadAttachment(config, taskId, attachmentId, opts) {
+    const { buffer, contentType } = await requestRawBytes(config, `/tasks/${taskId}/attachments/${attachmentId}`);
+    const kb = (buffer.byteLength / 1024).toFixed(1);
+    if (opts.savePath) {
+        const abs = await saveBuffer(buffer, opts.savePath, opts.overwrite ?? false);
+        const saved = {
+            saved_to: abs,
+            file_name: opts.fileName,
+            mime_type: contentType,
+            file_size: buffer.byteLength,
+            sha256: await sha256Hex(buffer),
+        };
+        return saved;
+    }
+    const ext = extensionOf(opts.fileName);
+    // PDF -> text
+    if (ext === 'pdf' || contentType.includes('application/pdf')) {
+        try {
+            const { text, pages } = await extractPdfText(buffer);
+            const { body, truncated } = capText(text);
+            return {
+                kind: 'pdf',
+                pages,
+                truncated,
+                file_size: buffer.byteLength,
+                text: body,
+            };
+        }
+        catch (e) {
+            return {
+                kind: 'pdf',
+                error: `Could not extract text from this PDF: ${e.message}. ` +
+                    'It may be encrypted or image-only. Pass save_path to write the raw file to disk.',
+                file_size: buffer.byteLength,
+            };
+        }
+    }
+    // ZIP -> entry list
+    if (ext === 'zip' || contentType.includes('application/zip')) {
+        try {
+            const entries = listZipEntries(buffer);
+            return { kind: 'zip', entry_count: entries.length, entries };
+        }
+        catch (e) {
+            return {
+                kind: 'zip',
+                error: `Could not list this ZIP: ${e.message}. Pass save_path to write it to disk.`,
+                file_size: buffer.byteLength,
+            };
+        }
+    }
+    // Image -> hand it to the model
+    const imageMime = imageMimeFor(contentType, opts.fileName);
+    if (imageMime) {
+        if (buffer.byteLength > IMAGE_INLINE_LIMIT) {
+            return (`[image: ${imageMime}, ${kb} KB] - too large to return inline ` +
+                `(limit ${(IMAGE_INLINE_LIMIT / 1024 / 1024).toFixed(0)} MB). ` +
+                'Pass save_path to write it to disk.');
+        }
+        const result = mcpContent([
+            {
+                type: 'image',
+                data: buffer.toString('base64'),
+                mimeType: imageMime,
+            },
+        ]);
+        return result;
+    }
+    // Text -> decoded text (capped)
+    if (looksLikeText(contentType, opts.fileName)) {
+        const { body, truncated } = capText(buffer.toString('utf8'));
+        if (!truncated)
+            return body;
+        return `[truncated: showing the first ${TEXT_INLINE_LIMIT.toLocaleString()} characters of ${kb} KB]\n\n${body}`;
+    }
+    // Anything else -> describe it.
+    return (`[binary file: ${contentType}, ${kb} KB]\n\n` +
+        'The bytes are not included - they would be unreadable here and would cost a great deal of context. ' +
+        'Pass save_path to write the file to disk, or ask the person to open it in Clokio.');
+}
+/**
+ * Coerce whatever the attachments endpoint returned into a plain array of rows,
+ * or null if it is not list-shaped.
+ *
+ * request() returns the bare `data` array for an un-paginated list TODAY, but it
+ * returns `{data, meta}` the moment the API attaches a meta envelope (it does
+ * for every paginated list). A bare `Array.isArray` check would then silently
+ * drop is_latest stamping and make the bulk tool report "no list" over a task
+ * that has attachments. Accept both shapes so the feature survives that change.
+ */
+/**
+ * Turn an API-supplied file_name into a safe basename to write under a chosen
+ * directory. The file_name is UNTRUSTED on the write path (same posture as the
+ * redirect checks in client.ts): strip any directory part so `../`, an absolute
+ * path or a Windows drive letter can only ever land a file INSIDE the target
+ * directory. A name that was nothing but a path (yields '', '.' or '..') falls
+ * back to a per-id name so it is still saved, just not where it asked.
+ */
+export function safeAttachmentName(rawName, id) {
+    // Split on BOTH separators: basename() on POSIX does not strip a Windows
+    // backslash, so "..\\..\\evil" would survive a posix basename().
+    const last = (rawName ?? '').split(/[\\/]/).pop() ?? '';
+    return last && last !== '.' && last !== '..' ? last : `attachment-${id}`;
+}
+export function asAttachmentArray(value) {
+    if (Array.isArray(value))
+        return value;
+    if (value &&
+        typeof value === 'object' &&
+        Array.isArray(value.data)) {
+        return value.data;
+    }
+    return null;
+}
+/**
+ * Stamp each attachment with is_latest: whether it is the newest upload bearing
+ * its file_name on this task. "Newest" is decided by created_at (falling back to
+ * uploaded_at, then id as a monotonic tiebreaker). A file_name with a single
+ * upload is trivially latest.
+ *
+ * This is computed client-side rather than asked of the API, deliberately: the
+ * API has no versioning concept, and the MCP is a thin wrapper that adds no
+ * server state. The field is ADDITIVE - existing readers that ignore it are
+ * unaffected.
+ */
+export function stampIsLatest(rows) {
+    // Rank as a (timestamp, id) PAIR, compared lexicographically - never folded
+    // into one number. A millisecond epoch is ~1.7e12; multiplying by an id to
+    // make room overflows Number.MAX_SAFE_INTEGER (9e15), silently dropping the
+    // id and losing the tiebreak - a real bug the tie test caught. A row with no
+    // parseable stamp sorts below any that has one (-Infinity), then by id.
+    const nameOf = (r) => r.file_name ?? `__id_${r.id}`;
+    const stampMs = (r) => {
+        const s = r.created_at ?? r.uploaded_at;
+        const t = s ? Date.parse(s) : NaN;
+        return Number.isNaN(t) ? -Infinity : t;
+    };
+    // true if a ranks strictly higher than b (newer stamp, or equal stamp + higher id).
+    const higher = (a, b) => {
+        const ta = stampMs(a);
+        const tb = stampMs(b);
+        return ta !== tb ? ta > tb : a.id > b.id;
+    };
+    const winner = new Map();
+    for (const r of rows) {
+        const name = nameOf(r);
+        const current = winner.get(name);
+        if (current === undefined || higher(r, current))
+            winner.set(name, r);
+    }
+    return rows.map((r) => ({
+        ...r,
+        is_latest: winner.get(nameOf(r))?.id === r.id,
+    }));
+}

package/dist/client.js

@@ -57,6 +57,84 @@ export function seg(value) {
  * The description still answers the question the caller actually had - is
  * there a file here, what kind, how big.
  */
+/**
+ * The raw bytes of a file endpoint, plus the content-type the API reported.
+ *
+ * This is the shared core: it owns the /api/v1 prefix guard, the by-hand
+ * redirect to signed storage with NO credential attached, and the redirect
+ * target scheme check - all the security-load-bearing parts of the download
+ * path. `requestRaw` renders these bytes as text/description for the model;
+ * the save-to-disk and typed-content tools consume the bytes directly.
+ */
+export async function requestRawBytes(config, 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 res;
+    try {
+        // `manual`, not 'error' and not 'follow' - see the long note below.
+        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.');
+            }
+            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 contentType = res.headers.get('content-type') ?? 'application/octet-stream';
+    const buffer = Buffer.from(await res.arrayBuffer());
+    return { buffer, contentType };
+}
+/**
+ * Decide whether an attachment is text, from BOTH the content-type and the file
+ * extension. Exported because the download tool needs the same verdict the
+ * renderer uses, to choose between text, PDF, image and binary handling.
+ *
+ * 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.
+ */
+export function looksLikeText(contentType, fileName) {
+    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',
+    ]);
+    return (contentType.startsWith('text/') ||
+        /\b(json|xml|csv|yaml|javascript|markdown)\b/.test(contentType) ||
+        TEXT_EXTENSIONS.has(extension));
+}
 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/';
@@ -126,19 +204,7 @@ export async function requestRaw(config, path, fileName) {
     }
     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 isText = looksLikeText(type, fileName);
     const kb = (buffer.byteLength / 1024).toFixed(1);
     if (isText) {
         // A CAP ON TEXT TOO. Attachments go up to 200 MB and .csv/.log are

package/dist/tools/employees.js

@@ -73,16 +73,25 @@ export function registerEmployeeTools(server, config) {
     });
     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).',
+        description: 'What needs one person\'s attention, in three lists: mentions_waiting (comments that @-mention them and ' +
+            'that they have NOT replied to yet; mentions on closed tasks are excluded), newly_assigned (tasks ' +
+            'assigned to them in the window), and status_changes (status moves on tasks they hold or created, made ' +
+            'by SOMEONE ELSE - their own moves and task-creation rows are excluded). This is how you find that ' +
+            'someone asked a question or moved your work, without scanning the board. `since` defaults to 14 days ' +
+            '(max 90). status_changes is capped by `limit` (default 100, max 500); the response sets ' +
+            'status_changes_truncated=true when more exist past the cap. 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'),
+            limit: z
+                .number()
+                .int()
+                .optional()
+                .describe('Max status_changes to return (default 100, max 500). status_changes_truncated flags overflow'),
         },
         handler: (args, cfg) => request(cfg, `/employees/${seg(args.employee_code)}/inbox`, {
-            query: { since: args.since },
+            query: { since: args.since, limit: args.limit },
         }),
     });
     registerTool(server, config, {

package/dist/tools/helpers.js

@@ -1,10 +1,24 @@
 import { ClokioApiError } from '../client.js';
+export function mcpContent(content, isError = false) {
+    return { __mcpContent: true, content, isError };
+}
+function isMcpContentResult(value) {
+    return (typeof value === 'object' &&
+        value !== null &&
+        value.__mcpContent === true &&
+        Array.isArray(value.content));
+}
 /**
  * Register one Clokio tool. The handler returns any JSON-serialisable value,
  * rendered as pretty JSON text. ClokioApiError becomes an isError tool result
  * carrying the API's own status + message, so the model can correct its request
  * (a 422 naming the bad field, a 404, a 403 scope refusal).
  *
+ * A handler may instead return `mcpContent([...])` to emit raw MCP content
+ * blocks - an image the model can see, or several blocks together. That path is
+ * used by the attachment tools (an image comes back as an image, not a size
+ * description); every other tool returns a plain value and is rendered as text.
+ *
  * `mutates` marks a tool that changes data (create/update/delete): it sets the
  * MCP readOnlyHint/destructiveHint annotations so clients can surface a warning.
  */
@@ -12,6 +26,11 @@ export function registerTool(server, config, def) {
     const callback = async (args) => {
         try {
             const result = await def.handler(args, config);
+            // A handler may hand back pre-built MCP content (an image, multiple
+            // blocks). Pass it through verbatim rather than JSON-stringifying it.
+            if (isMcpContentResult(result)) {
+                return { content: result.content, ...(result.isError ? { isError: true } : {}) };
+            }
             return {
                 content: [
                     {

package/dist/tools/tasks.js

@@ -1,6 +1,7 @@
 import { z } from 'zod';
-import { request, requestRaw, requestUpload } from '../client.js';
+import { request, requestUpload } from '../client.js';
 import { registerTool } from './helpers.js';
+import { asAttachmentArray, downloadAttachment, safeAttachmentName, stampIsLatest, } from '../attachments.js';
 /** See employees.ts - the same stable-identifier rule applies to task filters. */
 const employeeCode = z
     .string()
@@ -278,25 +279,118 @@ export function registerTaskTools(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`),
+            'check here before concluding a task has no detail. Each row carries is_latest: whether it is the newest ' +
+            'upload with the same file name (the same name can be uploaded more than once; nothing else marks which ' +
+            'is current). Pass latest_only: true to drop superseded duplicates. Use clokio_download_task_attachment ' +
+            'for one file, or clokio_download_task_attachments to save them all at once.',
+        schema: {
+            id: z.number().int(),
+            latest_only: z
+                .boolean()
+                .optional()
+                .describe('Return only the newest upload of each file name, dropping superseded duplicates'),
+        },
+        handler: async (args, cfg) => {
+            const raw = await request(cfg, `/tasks/${args.id}/attachments`);
+            const rows = asAttachmentArray(raw);
+            if (!rows)
+                return raw; // unexpected shape - hand it back rather than hide it
+            const stamped = stampIsLatest(rows);
+            return args.latest_only ? stamped.filter((r) => r.is_latest) : stamped;
+        },
     });
     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.',
+        description: 'Download one attachment. With save_path, writes the file to disk (creating missing folders, refusing to ' +
+            'overwrite unless overwrite: true) and returns {saved_to, sha256, mime_type, file_size}. Without ' +
+            'save_path it returns the content in the most usable form: text files as text; a PDF as its extracted ' +
+            'text plus page count; a ZIP as its entry list; an image as an image you can see; anything else as a ' +
+            'type-and-size description. Large text/PDF is truncated with a note (use save_path for the whole file). ' +
+            'Get the attachment id and file_name from clokio_list_task_attachments - file_name drives type detection.',
         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'),
+                .describe('The file_name from clokio_list_task_attachments. Drives type detection (text/PDF/zip/image)'),
+            save_path: z
+                .string()
+                .optional()
+                .describe('Write the file here instead of returning its content; parent folders are created'),
+            overwrite: z
+                .boolean()
+                .optional()
+                .describe('Allow save_path to replace an existing file (default false)'),
+        },
+        handler: (args, cfg) => downloadAttachment(cfg, args.id, args.attachment_id, {
+            fileName: args.file_name,
+            savePath: args.save_path,
+            overwrite: args.overwrite,
+        }),
+    });
+    registerTool(server, config, {
+        name: 'clokio_download_task_attachments',
+        description: "Save ALL of a task's attachments to a folder in one call. Creates save_dir if missing, writes each file " +
+            'under its own name, and returns the list of saved paths with sizes and sha256. Pass latest_only: true to ' +
+            'skip superseded duplicates (older uploads of a name that was uploaded again). A file name that appears ' +
+            'more than once is disambiguated with a numeric suffix so nothing is clobbered.',
+        schema: {
+            id: z.number().int().describe('The task id'),
+            save_dir: z.string().describe('Directory to write the files into; created if missing'),
+            latest_only: z
+                .boolean()
+                .optional()
+                .describe('Save only the newest upload of each file name'),
+            overwrite: z
+                .boolean()
+                .optional()
+                .describe('Allow replacing existing files in save_dir (default false)'),
+        },
+        handler: async (args, cfg) => {
+            const { join } = await import('node:path');
+            const rows = asAttachmentArray(await request(cfg, `/tasks/${args.id}/attachments`));
+            if (!rows) {
+                return { error: 'The attachments endpoint did not return a list.' };
+            }
+            const stamped = stampIsLatest(rows);
+            const selected = args.latest_only ? stamped.filter((r) => r.is_latest) : stamped;
+            const saved = [];
+            const failed = [];
+            const usedNames = new Set();
+            for (const row of selected) {
+                // file_name is API-supplied and UNTRUSTED on the write path;
+                // safeAttachmentName strips any directory part so it stays in save_dir.
+                const original = safeAttachmentName(row.file_name, row.id);
+                let name = original;
+                let counter = 2;
+                while (usedNames.has(name)) {
+                    const dot = original.lastIndexOf('.');
+                    name =
+                        dot > 0
+                            ? `${original.slice(0, dot)} (${counter})${original.slice(dot)}`
+                            : `${original} (${counter})`;
+                    counter++;
+                }
+                usedNames.add(name);
+                try {
+                    const result = (await downloadAttachment(cfg, args.id, row.id, {
+                        fileName: row.file_name,
+                        savePath: join(args.save_dir, name),
+                        overwrite: args.overwrite,
+                    }));
+                    saved.push(result);
+                }
+                catch (e) {
+                    failed.push({
+                        attachment_id: row.id,
+                        file_name: row.file_name,
+                        error: e.message,
+                    });
+                }
+            }
+            return { saved_count: saved.length, saved, ...(failed.length ? { failed } : {}) };
         },
-        handler: (args, cfg) => requestRaw(cfg, `/tasks/${args.id}/attachments/${args.attachment_id}`, args.file_name),
     });
     registerTool(server, config, {
         name: 'clokio_upload_task_attachment',

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "clokio-mcp",
-  "version": "0.13.2",
+  "version": "0.14.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": {
@@ -40,10 +40,11 @@
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.0.4",
+    "pdfjs-dist": "^4.10.38",
     "zod": "^3.23.8"
   },
   "devDependencies": {
-    "@types/node": "^22.20.4",
+    "@types/node": "^22.20.5",
     "typescript": "^5.9.3"
   },
   "engines": {