clokio-mcp 0.13.3 → 0.16.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
 
@@ -59,7 +63,7 @@ acting. An explicit code on a tool call always takes precedence.
 
 Optional: set `CLOKIO_TOOLSETS` to register only the tool groups you need, e.g.
 `CLOKIO_TOOLSETS=tasks`. This cuts the per-session tool-list cost — a
-task-focused session drops from 48 tools to 26. Optional groups are `tasks`,
+task-focused session drops from 50 tools to 31. 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
@@ -67,12 +71,12 @@ through it.
 
 ## Tools
 
-48 tools across five areas. Read-only tools carry the MCP `readOnlyHint`; writes
+50 tools across five areas. Read-only tools carry the MCP `readOnlyHint`; writes
 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 (mentions, new assignments, others' status changes), create, set status |
@@ -87,6 +91,9 @@ are marked mutating (deletes are `destructive`).
   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.
+- **Write Markdown.** Descriptions and comment bodies accept Markdown (paragraphs, lists,
+  `**bold**`, `` `code` ``, links, headings, fenced code); the server converts it to the HTML
+  Clokio stores. Text that already starts with an HTML tag is passed through untouched.
 - **Status slugs** come from `clokio_list_task_statuses` /
   `clokio_get_project_statuses`.
 - An API key sees **public custom fields only**.

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/markdown.js

@@ -0,0 +1,151 @@
+/**
+ * Markdown → HTML for the text an agent writes INTO Clokio.
+ *
+ * Clokio stores task descriptions and comments as sanitized HTML (the web
+ * editor is TipTap). A model naturally writes Markdown, and the first task
+ * created through this server from Claude arrived as one flat paragraph with
+ * literal `**` and backticks. Converting here keeps every tool's input
+ * natural for the model and correct for Clokio.
+ *
+ * Deliberately small: paragraphs, line breaks, headings, bullet and numbered
+ * lists, fenced code, blockquotes, bold, italic, inline code and links. Text
+ * that already starts with an HTML tag is passed through untouched, so a
+ * caller that sends HTML keeps working. Everything else is escaped, so a
+ * stray `<b>` in prose shows as text rather than becoming markup.
+ */
+// `"` too, not just the tag characters: escaping runs BEFORE the link regex,
+// and the generated <a href="..."> wraps the URL in double quotes - a
+// quote the URL smuggles through would close the attribute and open a new
+// one (`[x](https://e.com/"onmouseover="alert(1))` produced a live
+// onmouseover, reproduced in review). Clokio's server sanitizer strips such
+// attributes anyway, but this package is consumed outside Clokio's web
+// surfaces too, and it must not emit injectable HTML in the first place.
+const escapeHtml = (s) => s.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;').replace(/"/g, '&quot;');
+// The EXACT shape the backend's upload answers with (tasks/org-{n}/{n}/media/
+// {file}) - anchored, no slash or dot-segment room. A bare startsWith
+// allowlist let `/tasks/media/../../anything` through, and the browser
+// normalizes dot segments BEFORE sending, so that <img> fired an arbitrary
+// same-origin GET with the logged-in reader's session cookie (caught in
+// review). Anything under /tasks/media/ that is not this shape stays text.
+const MEDIA_PATH = /^\/tasks\/media\/tasks\/org-\d+\/\d+\/media\/[^/\s)]+$/;
+const VIDEO_EXT = /\.(mp4|webm|mov)$/i;
+function inline(text) {
+    // The stash protects finished HTML from the LATER rules: inline code first
+    // (so its contents are never styled or linked), then each generated
+    // image/video/anchor tag - without that, the em rule rewrote a `*` inside
+    // a URL into <em> IN THE src ATTRIBUTE and broke the image (caught in
+    // review; alt text likewise stays literal rather than styled).
+    const stashed = [];
+    const stash = (html) => {
+        stashed.push(html);
+        return `\u0000${stashed.length - 1}\u0000`;
+    };
+    let s = text.replace(/`([^`\n]+)`/g, (_m, code) => stash(`<code>${escapeHtml(code)}</code>`));
+    s = escapeHtml(s);
+    // Images BEFORE links, or the link rule eats the [alt](url) part and leaves
+    // a stray "!". Besides https, the /tasks/media/ urls that
+    // clokio_upload_task_media returns are allowed - embedding them is that
+    // tool's whole point (task #5296). A video extension gets a <video> tag:
+    // an <img> pointing at an mp4 renders as a broken image. escapeHtml
+    // already ran, so a quote in the URL is &quot; and cannot close the
+    // attribute.
+    s = s.replace(/!\[([^\]\n]*)\]\(((?:https?:\/\/|\/tasks\/media\/)[^)\s]+)\)/g, (whole, alt, url) => {
+        if (url.startsWith('/tasks/media/') && !MEDIA_PATH.test(url))
+            return whole;
+        return stash(VIDEO_EXT.test(url)
+            ? `<video src="${url}" controls></video>`
+            : `<img src="${url}" alt="${alt}">`);
+    });
+    s = s.replace(/\[([^\]\n]+)\]\((https?:\/\/[^)\s]+)\)/g, (_m, label, url) => stash(`<a href="${url}">${label}</a>`));
+    s = s.replace(/\*\*([^*\n]+)\*\*/g, '<strong>$1</strong>');
+    s = s.replace(/(^|[^*\w])\*([^*\n]+)\*(?=[^*\w]|$)/g, '$1<em>$2</em>');
+    return s.replace(/\u0000(\d+)\u0000/g, (_m, i) => stashed[Number(i)]);
+}
+export function looksLikeHtml(text) {
+    // `video` is in the list for the same reason `img` is: the media tool's
+    // HTML advice starts a body with exactly that tag, and leaving it out
+    // escaped the whole body to literal text (caught in review).
+    return /^\s*<(p|div|ul|ol|li|h[1-6]|strong|em|b|i|u|s|br|pre|code|blockquote|a|img|video|span|table)\b[^>]*>/i.test(text);
+}
+export function markdownToHtml(input) {
+    if (input == null)
+        return '';
+    const text = String(input);
+    if (!text.trim())
+        return '';
+    if (looksLikeHtml(text))
+        return text;
+    const out = [];
+    const lines = text.replace(/\r\n?/g, '\n').split('\n');
+    let para = [];
+    let list = null;
+    let quote = [];
+    const flushPara = () => {
+        if (para.length)
+            out.push(`<p>${para.map(inline).join('<br>')}</p>`);
+        para = [];
+    };
+    const flushList = () => {
+        if (list)
+            out.push(`<${list.tag}>${list.items.map((i) => `<li>${inline(i)}</li>`).join('')}</${list.tag}>`);
+        list = null;
+    };
+    const flushQuote = () => {
+        if (quote.length)
+            out.push(`<blockquote><p>${quote.map(inline).join('<br>')}</p></blockquote>`);
+        quote = [];
+    };
+    const flushAll = () => {
+        flushPara();
+        flushList();
+        flushQuote();
+    };
+    for (let i = 0; i < lines.length; i++) {
+        const line = lines[i];
+        const trimmed = line.trim();
+        if (/^```/.test(trimmed)) {
+            flushAll();
+            const code = [];
+            i++;
+            while (i < lines.length && !/^```/.test(lines[i].trim()))
+                code.push(lines[i++]);
+            out.push(`<pre><code>${escapeHtml(code.join('\n'))}</code></pre>`);
+            continue;
+        }
+        if (!trimmed) {
+            flushAll();
+            continue;
+        }
+        const heading = /^(#{1,6})\s+(.+)$/.exec(trimmed);
+        if (heading) {
+            flushAll();
+            out.push(`<h${heading[1].length}>${inline(heading[2])}</h${heading[1].length}>`);
+            continue;
+        }
+        const quoted = /^>\s?(.*)$/.exec(trimmed);
+        if (quoted) {
+            flushPara();
+            flushList();
+            quote.push(quoted[1]);
+            continue;
+        }
+        const bullet = /^[-*+]\s+(.+)$/.exec(trimmed);
+        const numbered = /^\d+[.)]\s+(.+)$/.exec(trimmed);
+        if (bullet || numbered) {
+            flushPara();
+            flushQuote();
+            const tag = bullet ? 'ul' : 'ol';
+            if (!list || list.tag !== tag) {
+                flushList();
+                list = { tag, items: [] };
+            }
+            list.items.push((bullet ?? numbered)[1]);
+            continue;
+        }
+        flushList();
+        flushQuote();
+        para.push(trimmed);
+    }
+    flushAll();
+    return out.join('');
+}

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,8 @@
 import { z } from 'zod';
-import { request, requestRaw, requestUpload } from '../client.js';
+import { markdownToHtml } from '../markdown.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()
@@ -120,7 +122,7 @@ export function registerTaskTools(server, config) {
         schema: {
             project_id: z.number().int(),
             title: z.string().max(255),
-            description: z.string().optional().describe('HTML or plain text'),
+            description: z.string().optional().describe('Markdown, HTML or plain text (Markdown is converted to HTML)'),
             priority: z.enum(['low', 'medium', 'high', 'urgent']).optional(),
             status: z.string().optional().describe("Status slug valid for THIS project's board"),
             due_date: z.string().optional().describe('YYYY-MM-DD'),
@@ -140,7 +142,7 @@ export function registerTaskTools(server, config) {
             body: {
                 project_id: args.project_id,
                 title: args.title,
-                description: args.description,
+                description: args.description === undefined ? undefined : markdownToHtml(args.description),
                 priority: args.priority,
                 status: args.status,
                 due_date: args.due_date,
@@ -190,6 +192,8 @@ export function registerTaskTools(server, config) {
                 if (args[key] !== undefined)
                     body[key] = args[key];
             }
+            if (typeof body.description === 'string')
+                body.description = markdownToHtml(body.description);
             // 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
@@ -233,7 +237,7 @@ export function registerTaskTools(server, config) {
         mutates: true,
         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 ' +
+            '(paragraphs, blank lines, bullet lists, **bold**, `code`); Markdown is converted to HTML, but 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 ' +
@@ -249,7 +253,7 @@ export function registerTaskTools(server, config) {
         handler: (args, cfg) => request(cfg, `/tasks/${args.id}/comments`, {
             method: 'POST',
             body: {
-                body: args.body,
+                body: markdownToHtml(args.body),
                 author_employee_code: args.author_employee_code ?? cfg.defaultActor,
                 notify: args.notify,
             },
@@ -271,40 +275,135 @@ export function registerTaskTools(server, config) {
         },
         handler: (args, cfg) => request(cfg, `/tasks/${args.id}/comments/${args.comment_id}`, {
             method: 'PATCH',
-            body: { body: args.body, author_employee_code: args.author_employee_code ?? cfg.defaultActor },
+            body: { body: markdownToHtml(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`),
+            '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',
         mutates: true,
-        description: 'Upload a LOCAL FILE to a task as an attachment - a screenshot, a log, a spreadsheet. Give the path to ' +
+        description: 'Upload a LOCAL FILE to a task as an attachment - a log, a spreadsheet, a PDF. 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.',
+            'uploaded_by_employee_code. NOTE: an attachment is a file in the task\'s file list - its download_path ' +
+            'only loads WITH an API key, so it can NOT be shown inline in a comment. For an image or video the ' +
+            'reader should SEE, use clokio_upload_task_media instead.',
         schema: {
             id: z.number().int().describe('The task id'),
             file_path: z.string().describe('Path to a file on THIS machine'),
@@ -316,6 +415,21 @@ export function registerTaskTools(server, config) {
             uploaded_by_employee_code: args.uploaded_by_employee_code ?? cfg.defaultActor,
         }),
     });
+    registerTool(server, config, {
+        name: 'clokio_upload_task_media',
+        mutates: true,
+        description: 'Upload an image or video the reader should SEE INLINE in a comment or the task description ' +
+            '(task #5296). Returns {url} - a /tasks/media/... path served to logged-in users with no API key. ' +
+            'Embed it in the body you then post: Markdown ![description](URL) or HTML <img src="URL">. ' +
+            'Media types only (jpg/png/gif/webp/heic/mp4/webm/mov), 50 MB; HEIC becomes JPEG. This does NOT add ' +
+            'the file to the attachments list - for a downloadable file (zip, PDF, log), use ' +
+            'clokio_upload_task_attachment instead.',
+        schema: {
+            id: z.number().int().describe('The task id'),
+            file_path: z.string().describe('Path to an image/video on THIS machine'),
+        },
+        handler: (args, cfg) => requestUpload(cfg, `/tasks/${args.id}/media`, args.file_path),
+    });
     registerTool(server, config, {
         name: 'clokio_get_task_activity',
         description: 'Get the activity log (audit trail) for a task.',

package/package.json

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