clokio-mcp 0.14.0 → 0.17.0

package/README.md

@@ -63,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
@@ -71,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 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 |
+| **Tasks** | list (with `compact` / `sort` / `updated_since` / `recurring`), get (with `comments_limit`), create, update (incl. recurring series: set a rule, pause/resume, stop), 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 |
@@ -91,8 +91,20 @@ 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`.
+- **Recurring tasks are templates.** Pass `recurrence` on create/update
+  (`{frequency, every?, days_of_week?, day_of_month?, anchor?}`) and the task
+  becomes the series template; **moving it to a done status starts the
+  schedule**. A fresh copy (same content, assignees, labels, estimate) is
+  created early on each matching day, due that day, independent of earlier
+  copies. Pause/resume with `recurrence_active`, stop with `recurrence: null`;
+  `recurrence.armed` on a task says whether the series is live, a copy names
+  its template as `recurrence.spawned_from`, and `series_of` on the list tool
+  returns every occurrence of one series.
 - An API key sees **public custom fields only**.
 
 ## Security

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

@@ -1,4 +1,5 @@
 import { z } from 'zod';
+import { markdownToHtml } from '../markdown.js';
 import { request, requestUpload } from '../client.js';
 import { registerTool } from './helpers.js';
 import { asAttachmentArray, downloadAttachment, safeAttachmentName, stampIsLatest, } from '../attachments.js';
@@ -6,6 +7,122 @@ import { asAttachmentArray, downloadAttachment, safeAttachmentName, stampIsLates
 const employeeCode = z
     .string()
     .regex(/^[A-Za-z0-9_-]{1,50}$/, 'employee_code must be 1-50 chars of letters, digits, _ or -');
+/**
+ * Recurrence, as a structured object the agent fills, serialized here into
+ * the rule string the Clokio scheduler executes (`daily`, `weekly:sun,wed`,
+ * `monthly:15`, `quarterly:MM-DD`, `custom:N:unit[:detail]`, ...).
+ *
+ * The server model is a TEMPLATE: the task itself is the series. Once the
+ * template sits in a done status (completing it ARMS the series), the
+ * scheduler creates a fresh copy - same title, description, assignees,
+ * labels, priority, estimate - early on each matching day, due that day,
+ * regardless of whether earlier copies were closed. The template stays done
+ * forever; the copies are the actual work items.
+ */
+const recurrenceInput = z.object({
+    frequency: z.enum(['daily', 'weekly', 'monthly', 'quarterly', 'semiannual', 'yearly']),
+    every: z
+        .number()
+        .int()
+        .min(1)
+        .max(999)
+        .optional()
+        .describe('Every N periods (default 1). "Every 2 weeks" = frequency weekly + every 2.'),
+    days_of_week: z
+        .array(z.enum(['mon', 'tue', 'wed', 'thu', 'fri', 'sat', 'sun']))
+        .min(1)
+        .optional()
+        .describe('weekly: which weekday(s). REQUIRED for weekly.'),
+    day_of_month: z
+        .number()
+        .int()
+        .min(1)
+        .max(31)
+        .optional()
+        .describe('monthly: which day of the month. REQUIRED for monthly.'),
+    anchor: z
+        .string()
+        .regex(/^\d{2}-\d{2}$/, 'anchor must be MM-DD')
+        .optional()
+        .describe('quarterly / semiannual / yearly: the MM-DD date the cycle starts from. REQUIRED for those.'),
+});
+/** Canonical weekday order for serialized rules - see recurrenceToRule(). */
+const WEEKDAY_ORDER = ['mon', 'tue', 'wed', 'thu', 'fri', 'sat', 'sun'];
+/**
+ * A field that names a day the chosen frequency does not use is REFUSED, not
+ * ignored: {frequency: 'daily', days_of_week: ['mon']} reads like "every
+ * Monday", and silently dropping the days spawns SEVEN copies a week.
+ */
+function refuseIrrelevant(r, allowed) {
+    for (const field of ['days_of_week', 'day_of_month', 'anchor']) {
+        if (r[field] !== undefined && !allowed.includes(field)) {
+            throw new Error(`${field} does not apply to frequency "${r.frequency}" and would be silently ignored - remove it, or pick the frequency it belongs to.`);
+        }
+    }
+}
+/** Serialize the structured object into the scheduler's rule grammar. */
+export function recurrenceToRule(r) {
+    const every = r.every ?? 1;
+    switch (r.frequency) {
+        case 'daily':
+            refuseIrrelevant(r, []);
+            return every === 1 ? 'daily' : `custom:${every}:day`;
+        case 'weekly': {
+            refuseIrrelevant(r, ['days_of_week']);
+            if (!r.days_of_week?.length) {
+                // A day-less weekly is the exact rule shape behind a production
+                // outage - the server refuses it too, but failing here names the fix.
+                throw new Error('weekly recurrence requires days_of_week (e.g. ["sun"]).');
+            }
+            // Canonical: dedupe + fixed weekday order, so the same intent always
+            // stores the same rule string ("did the rule change?" comparisons and
+            // health reports read these back).
+            const unique = [...new Set(r.days_of_week)];
+            const days = WEEKDAY_ORDER.filter((d) => unique.includes(d)).join(',');
+            if (every > 1 && unique.length > 1) {
+                // The scheduler's custom:N:week rule spawns ONE occurrence per cycle
+                // (the day list only seeds which day), so "every 2 weeks on Mon and
+                // Thu" would silently become "every 2 weeks on Mon". Refuse rather
+                // than surprise - weekly (every: 1) does cover multiple days. The
+                // server refuses the same shape (ValidRecurrenceRule).
+                throw new Error('every > 1 with multiple days_of_week is not supported by the scheduler (it would spawn only on the earliest day). Use one day, or every: 1 for all of them.');
+            }
+            return every === 1 ? `weekly:${days}` : `custom:${every}:week:${days}`;
+        }
+        case 'monthly': {
+            refuseIrrelevant(r, ['day_of_month']);
+            if (!r.day_of_month) {
+                throw new Error('monthly recurrence requires day_of_month (1-31).');
+            }
+            return every === 1 ? `monthly:${r.day_of_month}` : `custom:${every}:month:${r.day_of_month}`;
+        }
+        case 'quarterly':
+        case 'semiannual':
+        case 'yearly': {
+            refuseIrrelevant(r, ['anchor']);
+            if (!r.anchor) {
+                throw new Error(`${r.frequency} recurrence requires anchor (MM-DD, the cycle's first date).`);
+            }
+            // The MM-DD shape is schema-checked; the RANGE is checked here so
+            // "13-45" fails fast with the field named, not as a generic server 422.
+            const [mo, dy] = r.anchor.split('-').map(Number);
+            if (mo < 1 || mo > 12 || dy < 1 || dy > 31) {
+                throw new Error(`anchor "${r.anchor}" is not a real date - MM must be 01-12 and DD 01-31.`);
+            }
+            if (every !== 1) {
+                throw new Error(`${r.frequency} does not take "every" - its cadence is fixed. For other cadences use frequency monthly/weekly with every.`);
+            }
+            return `${r.frequency}:${r.anchor}`;
+        }
+    }
+}
+/** The one description of the template model, shared by both task tools. */
+const RECURRENCE_MODEL_NOTE = 'RECURRING TASKS: pass `recurrence` to make this task a repeating series. The task becomes the series ' +
+    'TEMPLATE - move it to a done status to START the schedule (an open template is configured but not ' +
+    'spawning; the resource reports this as recurrence.armed). The scheduler then creates a fresh copy of ' +
+    'the template (title, description, assignees, labels, priority, estimate) early on each matching day, ' +
+    'due that day, independent of whether earlier copies were closed. A multi-period cadence ' +
+    '(every: N > 1) counts whole periods from the task\'s DUE DATE, so set one.';
 /** Task-management tools: the core of the Clokio API surface. */
 export function registerTaskTools(server, config) {
     registerTool(server, config, {
@@ -23,6 +140,17 @@ export function registerTaskTools(server, config) {
             label: z.string().optional(),
             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'),
+            recurring: z
+                .boolean()
+                .optional()
+                .describe('true = only the recurring SERIES TEMPLATES (tasks carrying a recurrence rule); false = only ' +
+                'ordinary tasks, which includes the copies a template spawns. Omit for no filter.'),
+            series_of: z
+                .number()
+                .int()
+                .optional()
+                .describe('A series template\'s task id: returns every occurrence that template spawned ("did the Sunday ' +
+                'check actually happen every week?"). A copy also names its template as recurrence.spawned_from.'),
             parent_task_id: z
                 .number()
                 .int()
@@ -78,6 +206,8 @@ export function registerTaskTools(server, config) {
                 label: args.label,
                 search: args.search,
                 open: args.open === undefined ? undefined : args.open ? 1 : 0,
+                recurring: args.recurring === undefined ? undefined : args.recurring ? 1 : 0,
+                series_of: args.series_of,
                 parent_task_id: args.parent_task_id === null ? '' : args.parent_task_id,
                 created_before: args.created_before,
                 created_after: args.created_after,
@@ -117,11 +247,12 @@ export function registerTaskTools(server, config) {
             'You do NOT normally need created_by_employee_code: an unnamed task is attributed to the key\'s issuer ' +
             'automatically (whoami shows who that is). Set it only to credit someone OTHER than the key owner. ' +
             'Pass parent_task_id to create it as a SUBTASK of that task ' +
-            '(same project, and the parent must not itself be a subtask - one level deep only).',
+            '(same project, and the parent must not itself be a subtask - one level deep only).\n\n' +
+            RECURRENCE_MODEL_NOTE,
         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'),
@@ -135,31 +266,61 @@ export function registerTaskTools(server, config) {
                 .optional()
                 .describe('Label names. A name that does not exist yet is CREATED - check clokio_list_task_labels first'),
             created_by_employee_code: employeeCode.optional().describe('Credit someone OTHER than the key owner; omit to use the key issuer / CLOKIO_DEFAULT_ACTOR'),
+            recurrence: recurrenceInput
+                .optional()
+                .describe('Make this task a recurring series (see the tool description for how the template model works)'),
+        },
+        handler: async (args, cfg) => {
+            const result = (await request(cfg, '/tasks', {
+                method: 'POST',
+                body: {
+                    project_id: args.project_id,
+                    title: args.title,
+                    description: args.description === undefined ? undefined : markdownToHtml(args.description),
+                    priority: args.priority,
+                    status: args.status,
+                    due_date: args.due_date,
+                    start_date: args.start_date,
+                    estimated_hours: args.estimated_hours,
+                    parent_task_id: args.parent_task_id,
+                    assignee_employee_codes: args.assignee_employee_codes,
+                    label_names: args.label_names,
+                    created_by_employee_code: args.created_by_employee_code ?? cfg.defaultActor,
+                    ...(args.recurrence
+                        ? { is_recurring: true, recurrence_rule: recurrenceToRule(args.recurrence) }
+                        : {}),
+                },
+            }));
+            // A Clokio older than the recurrence fields IGNORES unknown body keys
+            // on create (Laravel validate() drops what it has no rule for), so the
+            // task would be born NON-recurring with a 201 - and the agent would
+            // report a weekly series that never spawns. The echoed resource is the
+            // truth: if we asked for recurrence and it is not reflected, say so
+            // loudly instead of letting the silence stand.
+            if (args.recurrence && result && typeof result === 'object') {
+                const data = result.data;
+                const echoed = data?.recurrence;
+                if (echoed?.is_recurring !== true) {
+                    result.warning =
+                        'The task WAS created, but the server IGNORED the recurrence fields - this Clokio version ' +
+                            'predates recurring-series support on the API. The task will NOT repeat. Update the server, ' +
+                            'then set the recurrence again with clokio_update_task.';
+                }
+            }
+            return result;
         },
-        handler: (args, cfg) => request(cfg, '/tasks', {
-            method: 'POST',
-            body: {
-                project_id: args.project_id,
-                title: args.title,
-                description: args.description,
-                priority: args.priority,
-                status: args.status,
-                due_date: args.due_date,
-                start_date: args.start_date,
-                estimated_hours: args.estimated_hours,
-                parent_task_id: args.parent_task_id,
-                assignee_employee_codes: args.assignee_employee_codes,
-                label_names: args.label_names,
-                created_by_employee_code: args.created_by_employee_code ?? cfg.defaultActor,
-            },
-        }),
     });
     registerTool(server, config, {
         name: 'clokio_update_task',
         mutates: true,
         description: 'Update a task. ONLY the fields you pass are changed; 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.',
+            'activity log names the person rather than the API key.\n\n' +
+            RECURRENCE_MODEL_NOTE +
+            '\n\nManage an existing series here: `recurrence` (an object) sets or retunes the rule and switches ' +
+            'the series ON; `recurrence: null` STOPS it (future copies stop; already-spawned copies are ordinary ' +
+            'tasks and stay). To PAUSE while keeping the rule stored, pass `recurrence_active: false`, and ' +
+            '`recurrence_active: true` to resume.',
         schema: {
             id: z.number().int(),
             title: z.string().max(255).optional(),
@@ -171,6 +332,14 @@ export function registerTaskTools(server, config) {
             estimated_hours: z.number().min(0).max(9999.99).nullable().optional(),
             project_id: z.number().int().optional().describe('Move the task to another project'),
             actor_employee_code: employeeCode.optional().describe('Who to credit in the activity log; omit to use the key issuer / CLOKIO_DEFAULT_ACTOR'),
+            recurrence: recurrenceInput
+                .nullable()
+                .optional()
+                .describe('Set/retune the series rule (and switch it on), or null to STOP the series'),
+            recurrence_active: z
+                .boolean()
+                .optional()
+                .describe('Pause (false) / resume (true) the series without touching its stored rule'),
         },
         handler: (args, cfg) => {
             // Only keys the caller actually supplied may go in the body: PATCH
@@ -191,6 +360,26 @@ export function registerTaskTools(server, config) {
                 if (args[key] !== undefined)
                     body[key] = args[key];
             }
+            if (typeof body.description === 'string')
+                body.description = markdownToHtml(body.description);
+            // Series management maps onto the API's two columns. `recurrence`
+            // carries the whole intent (rule + on/off), so combining it with the
+            // bare pause/resume switch is ambiguous and refused rather than
+            // silently picking a winner.
+            if (args.recurrence !== undefined && args.recurrence_active !== undefined) {
+                throw new Error('Pass either recurrence or recurrence_active, not both.');
+            }
+            if (args.recurrence === null) {
+                body.is_recurring = false;
+                body.recurrence_rule = null;
+            }
+            else if (args.recurrence !== undefined) {
+                body.is_recurring = true;
+                body.recurrence_rule = recurrenceToRule(args.recurrence);
+            }
+            else if (args.recurrence_active !== undefined) {
+                body.is_recurring = args.recurrence_active;
+            }
             // 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
@@ -234,7 +423,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 ' +
@@ -250,7 +439,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,
             },
@@ -272,7 +461,7 @@ export function registerTaskTools(server, config) {
         },
         handler: (args, cfg) => request(cfg, `/tasks/${args.id}/comments/${args.comment_id}`, {
             method: 'PATCH',
-            body: { body: args.body, author_employee_code: args.author_employee_code ?? cfg.defaultActor },
+            body: { body: markdownToHtml(args.body), author_employee_code: args.author_employee_code ?? cfg.defaultActor },
         }),
     });
     registerTool(server, config, {
@@ -395,10 +584,12 @@ export function registerTaskTools(server, config) {
     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'),
@@ -410,6 +601,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.14.0",
+  "version": "0.17.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": {