clokio-mcp 0.14.0 → 0.16.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,7 +71,7 @@ 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 |
@@ -91,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/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';
@@ -121,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'),
@@ -141,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,
@@ -191,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
@@ -234,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 ' +
@@ -250,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,
             },
@@ -272,7 +275,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 +398,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 +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.14.0",
+  "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": {