@sebastienheyd/clickup-mcp 1.7.4 → 1.8.0

package/README.md

@@ -13,7 +13,7 @@ Model Context Protocol (MCP) server enabling AI assistants to interact with Clic
 | **Setup**            | Local npm/npx install                                 | Remote MCP (no install)                     |
 | **Authentication**   | API key only                                          | OAuth only                                  |
 | **Task Context**     | Complete with comments, status history, inline images | Requires mutiple tool calls for full contxt |
-| **Image Support**    | Inline images with smart size budgeting               | Not documented                              |
+| **Image Support**    | Read and write: inline images with smart size budgeting, and `![](local/path.png)` uploads automatically | Upload via separate tool calls; base64 capped at ~200KB |
 | **Search**           | Fuzzy search on recent tasks (limited scope)          | Full ClickUp search database                |
 | **Documents**        | CRUD operations                                       | CRUD + document search                      |
 | **Time Tracking**    | View and create entries                               | Timers and entries                          |
@@ -24,6 +24,7 @@ Model Context Protocol (MCP) server enabling AI assistants to interact with Clic
 
 **Choose this MCP when:**
 - You need rich task context with inline images for AI coding tools
+- You want to write screenshots into tickets by local file path (running locally, it reads the file itself instead of taking base64)
 - You need API key authentication for automation or CI/CD pipelines
 - You want the `read-minimal` mode optimized for development workflows
 
@@ -189,6 +190,7 @@ The ClickUp MCP supports three operational modes to balance functionality, secur
 |------------------------|:------------:|:----:|:-----:|-----------------------------------------------------------------------------------------|
 | `getTaskById`          |      ✅       |  ✅   |   ✅   | Get complete task details including comments, images, and metadata                      |
 | `addComment`           |      ❌       |  ❌   |   ✅   | Add comments to tasks for collaboration                                                 |
+| `editComment`          |      ❌       |  ❌   |   ✅   | Correct your own comment within 24h instead of posting a follow-up                      |
 | `updateTask`           |      ❌       |  ❌   |   ✅   | Update tasks (status, priority, assignees, etc.) with **SAFE APPEND-ONLY** descriptions |
 | `createTask`           |      ❌       |  ❌   |   ✅   | Create new tasks with full markdown support                                             |
 | `searchTasks`          |      ✅       |  ✅   |   ✅   | Find tasks by content, keywords, assignees, or project context                          |
@@ -231,6 +233,8 @@ This MCP server can be configured using environment variables:
 - `CLICKUP_MCP_MODE`: (Optional) Controls which tools are available. Options: `read-minimal`, `read`, `write` (default).
 - `MAX_IMAGES`: (Optional) The maximum number of images to return for a task in `getTaskById`. Defaults to 4.
 - `MAX_RESPONSE_SIZE_MB`: (Optional) The maximum response size in megabytes for `getTaskById`. Uses intelligent size budgeting to fit the most important images within the limit. Defaults to 1.
+- `MAX_UPLOAD_SIZE_MB`: (Optional) The maximum size of a single image uploaded when writing comments or descriptions. Defaults to 10.
+- `CLICKUP_COMMENT_EDIT_WINDOW_HOURS`: (Optional) How long after creation `editComment` may still rewrite a comment. Defaults to 24. Set to `0` to disable comment editing entirely.
 - `CLICKUP_PRIMARY_LANGUAGE`: (Optional) A hint for the primary language used in your ClickUp tasks (e.g., "de" for German, "en" for English). This helps the `searchTask` tool provide more tailored guidance in its description for multilingual searches.
 - `LANG`: (Optional) If `CLICKUP_PRIMARY_LANGUAGE` is not set, the MCP will check this standard environment variable (e.g., "en_US.UTF-8", "de_DE") as a fallback to infer the primary language.
 
@@ -286,6 +290,38 @@ When updating task descriptions, content is safely appended:
 
 This ensures no existing content is ever lost while maintaining a clear audit trail.
 
+## Writing Images Into Tickets
+
+`addComment`, `editComment`, `createTask` and `updateTask` accept images as ordinary markdown. Because
+this server runs locally, it reads the file itself - so a **local path is enough**:
+
+```markdown
+Ist umgesetzt. So sieht es aus:
+
+**1. Login öffnen** – der Kunde gibt nur seine E-Mail-Adresse ein.
+
+![Die Login-Maske fragt nur nach der E-Mail](/Users/me/shots/login.png)
+```
+
+Accepted sources: local file paths, `data:` URIs, http(s) URLs (downloaded, then
+re-uploaded), and existing ClickUp attachment URLs (embedded without re-uploading).
+
+Notes:
+
+- **Prefer paths over base64.** A path costs a few tokens; the same screenshot as a
+  `data:` URI costs roughly 4/3 of its file size in the request.
+- **The caption becomes the attachment filename**, and that filename is what ClickUp
+  displays beneath the image - so write a caption that reads well.
+- **An image inside a numbered list breaks ClickUp's numbering.** Write walkthrough
+  steps as bold lines with the image between them, as above.
+- Only real PNG/JPEG/GIF/WebP files are uploaded - the content is checked, not the
+  extension. A file that fails **aborts the write**: `addComment`, `editComment` and
+  `updateTask` report every broken reference and change nothing, so the markdown can be
+  fixed and the call retried without creating duplicates. `createTask` validates its
+  images before creating the task; only an upload failing afterwards is reported as a
+  warning, since the task already exists at that point.
+- Attachments always belong to a task, so document pages cannot embed uploads this way.
+
 ## Performance & Limitations
 
 **Optimized for AI Workflows:**

package/dist/cli.js

@@ -116,7 +116,9 @@ async function main() {
     // Parse parameters
     for (let i = 1; i < args.length; i++) {
         const arg = args[i];
-        const match = arg.match(/^([^=]+)=(.*)$/);
+        // The `s` flag matters: without it `.` stops at a newline and multi-line values
+        // (markdown descriptions, comments with images) are silently skipped entirely.
+        const match = arg.match(/^([^=]+)=(.*)$/s);
         if (match) {
             const [, key, value] = match;
             // Try to parse as JSON if it looks like a JSON value

package/dist/clickup-text.d.ts

@@ -6,6 +6,9 @@ import { ImageMetadataBlock } from "./shared/types";
 export interface ClickUpTextItem {
     text?: string;
     type?: string;
+    task_mention?: {
+        task_id?: string;
+    };
     image?: {
         id?: string;
         name?: string;
@@ -67,17 +70,94 @@ export interface ClickUpCommentBlock {
         };
         indent?: number;
         'block-id'?: string;
+        alt?: string;
     };
     list?: {
         list: 'bullet' | 'ordered' | 'unchecked' | 'checked';
     };
+    /**
+     * Present on task mention fragments. ClickUp renders these as live task references
+     * showing the current task name, status and assignee.
+     */
+    task_mention?: {
+        task_id: string;
+    };
+    /**
+     * Present on image fragments. ClickUp only renders a preview when this holds the
+     * complete attachment object from the upload response - a bare URL string produces
+     * an empty placeholder tile.
+     */
+    image?: {
+        id?: string;
+        name?: string;
+        title?: string;
+        extension?: string;
+        url: string;
+        thumbnail_small?: string;
+        thumbnail_medium?: string;
+        thumbnail_large?: string;
+        width?: number;
+        height?: number;
+    };
+}
+/**
+ * Minimal shape needed to embed an already-uploaded attachment as an image fragment
+ */
+export interface EmbeddableAttachment {
+    id?: string;
+    name?: string;
+    title?: string;
+    extension?: string;
+    url: string;
+    thumbnail_small?: string;
+    thumbnail_medium?: string;
+    thumbnail_large?: string;
+    width?: number;
+    height?: number;
+    [key: string]: any;
 }
+/**
+ * Build the image fragment ClickUp needs to render an inline image in a comment.
+ * `title`/`text` carry the caption; the rest is copied straight from the upload response.
+ */
+export declare function buildImageFragment(attachment: EmbeddableAttachment, caption: string): ClickUpCommentBlock;
+/**
+ * Extract the task ID from a ClickUp task URL, or null if it is not one.
+ */
+export declare function parseClickUpTaskUrl(url: string): string | null;
+/**
+ * Wrap image destinations that contain spaces in angle brackets.
+ *
+ * CommonMark rejects a bare destination with spaces, so `![x](/tmp/Screen Shot.png)`
+ * is not an image at all - it would silently stay literal text and never be uploaded.
+ * Screenshot filenames have spaces constantly ("Screenshot 2026-07-27 at 14.30.png"),
+ * so normalising to the `<...>` form is what makes the obvious thing work.
+ */
+export declare function normalizeImageDestinations(markdown: string): string;
+/**
+ * Collect every image reference in a markdown document, in document order.
+ * Callers use this to know what needs uploading before converting.
+ */
+export declare function collectMarkdownImageSources(markdown: string): {
+    src: string;
+    alt: string;
+}[];
+/**
+ * Replace image sources in markdown with their uploaded ClickUp URLs.
+ *
+ * Used for task descriptions: `markdown_description` renders `![alt](url)` directly,
+ * so descriptions need no fragment handling - only the URL has to be swapped.
+ * Images without an upload keep their original source untouched.
+ */
+export declare function rewriteMarkdownImageUrls(markdown: string, attachmentsBySrc: Map<string, EmbeddableAttachment>): string;
 /**
  * Convert markdown text to ClickUp comment blocks format using remark
- * Supports: headers, bold, italic, code, links, lists, blockquotes, code blocks
+ * Supports: headers, bold, italic, code, links, lists, blockquotes, code blocks, images
  *
  * @param markdown The markdown text to convert
+ * @param attachmentsBySrc Uploaded attachments keyed by the markdown `src` they came from.
+ *   Images without an entry degrade to a link so their information is not lost.
  * @returns Array of ClickUp comment blocks
  */
-export declare function convertMarkdownToClickUpBlocks(markdown: string): ClickUpCommentBlock[];
+export declare function convertMarkdownToClickUpBlocks(markdown: string, attachmentsBySrc?: Map<string, EmbeddableAttachment>): ClickUpCommentBlock[];
 //# sourceMappingURL=clickup-text.d.ts.map

package/dist/clickup-text.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"clickup-text.d.ts","sourceRoot":"","sources":["../src/clickup-text.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,MAAM,iCAAiC,CAAC;AAEjE,OAAO,EAAE,kBAAkB,EAAE,MAAM,gBAAgB,CAAC;AAOpD;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,KAAK,CAAC,EAAE;QACN,EAAE,CAAC,EAAE,MAAM,CAAC;QACZ,IAAI,CAAC,EAAE,MAAM,CAAC;QACd,KAAK,CAAC,EAAE,MAAM,CAAC;QACf,IAAI,CAAC,EAAE,MAAM,CAAC;QACd,SAAS,CAAC,EAAE,MAAM,CAAC;QACnB,eAAe,CAAC,EAAE,MAAM,CAAC;QACzB,gBAAgB,CAAC,EAAE,MAAM,CAAC;QAC1B,eAAe,CAAC,EAAE,MAAM,CAAC;QACzB,GAAG,EAAE,MAAM,CAAC;QACZ,QAAQ,CAAC,EAAE,OAAO,CAAC;KACpB,CAAC;IACF,UAAU,CAAC,EAAE,GAAG,CAAC;CAClB;AAED;;GAEG;AACH,MAAM,WAAW,iBAAiB;IAChC,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,GAAG,EAAE,MAAM,CAAC;IACZ,CAAC,GAAG,EAAE,MAAM,GAAG,GAAG,CAAC;CACpB;AA4BD;;;;;;GAMG;AACH,wBAAsB,uCAAuC,CAC3D,SAAS,EAAE,eAAe,EAAE,GAC3B,OAAO,CAAC,CAAC,cAAc,CAAC,SAAS,CAAC,CAAC,MAAM,CAAC,GAAG,kBAAkB,CAAC,EAAE,CAAC,CAsNrE;AAED;;;;;GAKG;AACH,wBAAgB,+BAA+B,CAC7C,YAAY,EAAE,MAAM,EACpB,WAAW,EAAE,iBAAiB,EAAE,GAAG,IAAI,GAAG,SAAS,GAClD,CAAC,cAAc,CAAC,SAAS,CAAC,CAAC,MAAM,CAAC,GAAG,kBAAkB,CAAC,EAAE,CA0I5D;AA8BD;;GAEG;AACH,MAAM,WAAW,mBAAmB;IAClC,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,UAAU,CAAC,EAAE;QACX,IAAI,CAAC,EAAE,OAAO,CAAC;QACf,MAAM,CAAC,EAAE,OAAO,CAAC;QACjB,IAAI,CAAC,EAAE,OAAO,CAAC;QACf,IAAI,CAAC,EAAE,MAAM,CAAC;QACd,YAAY,CAAC,EAAE;YACb,YAAY,EAAE,MAAM,CAAC;SACtB,CAAC;QACF,MAAM,CAAC,EAAE,MAAM,CAAC;QAChB,UAAU,CAAC,EAAE,EAAE,CAAC;QAChB,iBAAiB,CAAC,EAAE,OAAO,CAAC;QAC5B,IAAI,CAAC,EAAE;YACL,IAAI,EAAE,QAAQ,GAAG,SAAS,GAAG,WAAW,GAAG,SAAS,CAAC;SACtD,CAAC;QACF,MAAM,CAAC,EAAE,MAAM,CAAC;QAChB,UAAU,CAAC,EAAE,MAAM,CAAC;KACrB,CAAC;IACF,IAAI,CAAC,EAAE;QACL,IAAI,EAAE,QAAQ,GAAG,SAAS,GAAG,WAAW,GAAG,SAAS,CAAC;KACtD,CAAC;CACH;AAED;;;;;;GAMG;AACH,wBAAgB,8BAA8B,CAAC,QAAQ,EAAE,MAAM,GAAG,mBAAmB,EAAE,CAoBtF"}
+{"version":3,"file":"clickup-text.d.ts","sourceRoot":"","sources":["../src/clickup-text.ts"],"names":[],"mappings":"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"}

package/dist/clickup-text.js

@@ -5,6 +5,11 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.convertClickUpTextItemsToToolCallResult = convertClickUpTextItemsToToolCallResult;
 exports.convertMarkdownToToolCallResult = convertMarkdownToToolCallResult;
+exports.buildImageFragment = buildImageFragment;
+exports.parseClickUpTaskUrl = parseClickUpTaskUrl;
+exports.normalizeImageDestinations = normalizeImageDestinations;
+exports.collectMarkdownImageSources = collectMarkdownImageSources;
+exports.rewriteMarkdownImageUrls = rewriteMarkdownImageUrls;
 exports.convertMarkdownToClickUpBlocks = convertMarkdownToClickUpBlocks;
 const data_uri_1 = require("./shared/data-uri");
 const unified_1 = require("unified");
@@ -31,6 +36,18 @@ function extractThumbnailsFromDataAttachment(attributes) {
         return {};
     }
 }
+/**
+ * Render an image reference as markdown, escaping whatever would break the syntax.
+ *
+ * Reading and writing use the same markdown here on purpose: it lets an agent feed a
+ * comment it just read straight back into editComment without losing the images.
+ */
+function toMarkdownImage(alt, url) {
+    const safeAlt = alt.replace(/[\[\]\r\n]/g, " ").trim();
+    // Angle brackets let a URL with spaces or parentheses survive the round trip
+    const safeUrl = /[\s()]/.test(url) ? `<${url}>` : url;
+    return `![${safeAlt}](${safeUrl})`;
+}
 /**
  * Process an array of ClickUp text items into a structured content format
  * that includes both text and images in their original sequence
@@ -80,8 +97,10 @@ async function convertClickUpTextItemsToToolCallResult(textItems) {
                 }
                 continue;
             }
-            // Add image URL reference inline to current text block
-            currentTextBlock += `\nImage: ${imageFileName} - ${imageUrl}`;
+            // Reference the image in the same markdown syntax the write tools accept, so a
+            // comment read here can be handed back to editComment unchanged and keep its
+            // images - an existing ClickUp attachment URL is re-embedded without re-uploading.
+            currentTextBlock += `\n${toMarkdownImage(altText, imageUrl)}`;
             // Get working thumbnail URLs from data-attachment if available
             const extractedThumbnails = extractThumbnailsFromDataAttachment(item.attributes);
             // Determine best thumbnail URLs (prefer extracted over API thumbnails)
@@ -215,6 +234,11 @@ async function convertClickUpTextItemsToToolCallResult(textItems) {
                 currentLine += formattedText;
             }
         }
+        // Task mentions render as the task URL so the reference survives the round trip:
+        // writing that URL back through addComment/editComment regenerates the mention.
+        else if (item.type === "task_mention" && item.task_mention?.task_id) {
+            currentLine += `https://app.clickup.com/t/${item.task_mention.task_id}`;
+        }
         // Handle other types of items like bookmarks or whatever clickup can think of
         else {
             currentTextBlock += JSON.stringify(item);
@@ -288,9 +312,9 @@ function convertMarkdownToToolCallResult(markdownText, attachments) {
         // Check if this image URL exists in our attachments
         const attachment = attachmentMap.get(imageUrl);
         if (attachment) {
-            // Add image URL reference inline to current text block
+            // Keep the markdown syntax, so the reference stays usable in a write call
             const imageFileName = altText || "image";
-            currentTextBlock += `\nImage: ${imageFileName} - ${imageUrl}`;
+            currentTextBlock += `\n${toMarkdownImage(imageFileName, imageUrl)}`;
             // Only create image_metadata if we have at least one thumbnail (never use original image)
             if (attachment.thumbnail_large || attachment.thumbnail_medium || attachment.thumbnail_small) {
                 // Push accumulated text (including image URL) as a text block
@@ -380,14 +404,132 @@ function extractFileTypeFromUrl(url) {
         return null;
     return filename.substring(lastDot + 1);
 }
+/**
+ * Build the image fragment ClickUp needs to render an inline image in a comment.
+ * `title`/`text` carry the caption; the rest is copied straight from the upload response.
+ */
+function buildImageFragment(attachment, caption) {
+    const label = caption || attachment.name || 'image';
+    const fragment = {
+        type: 'image',
+        text: label,
+        image: {
+            id: attachment.id,
+            name: attachment.name,
+            title: label,
+            extension: attachment.extension,
+            url: attachment.url,
+            thumbnail_small: attachment.thumbnail_small,
+            thumbnail_medium: attachment.thumbnail_medium,
+            thumbnail_large: attachment.thumbnail_large,
+            width: attachment.width,
+            height: attachment.height,
+        },
+    };
+    if (caption) {
+        fragment.attributes = { alt: caption };
+    }
+    return fragment;
+}
+/**
+ * Matches a plain ClickUp task URL, with or without the team segment:
+ * https://app.clickup.com/t/86cb3t6t2 or https://app.clickup.com/t/4500611/86cb3t6t2
+ *
+ * Deliberately narrow: custom task IDs (PREFIX-123) and URLs carrying a query or
+ * fragment (e.g. ?comment=... deep links) do NOT match, because a mention would
+ * either not resolve or lose the anchor - those stay ordinary links.
+ */
+const CLICKUP_TASK_URL_PATTERN = /^https?:\/\/app\.clickup\.com\/t\/(?:\d+\/)?([a-z0-9]{6,12})\/?$/;
+/**
+ * Extract the task ID from a ClickUp task URL, or null if it is not one.
+ */
+function parseClickUpTaskUrl(url) {
+    const match = url.match(CLICKUP_TASK_URL_PATTERN);
+    return match ? match[1] : null;
+}
+/**
+ * Wrap image destinations that contain spaces in angle brackets.
+ *
+ * CommonMark rejects a bare destination with spaces, so `![x](/tmp/Screen Shot.png)`
+ * is not an image at all - it would silently stay literal text and never be uploaded.
+ * Screenshot filenames have spaces constantly ("Screenshot 2026-07-27 at 14.30.png"),
+ * so normalising to the `<...>` form is what makes the obvious thing work.
+ */
+function normalizeImageDestinations(markdown) {
+    return markdown.replace(/!\[([^\]]*)\]\(([^)\n]*)\)/g, (match, alt, inner) => {
+        const trimmed = inner.trim();
+        // Already bracketed, or nothing to fix
+        if (trimmed.startsWith('<') || trimmed.includes('>')) {
+            return match;
+        }
+        // Split off an optional markdown title: dest "title" / 'title'
+        const titleMatch = trimmed.match(/^(.*?)(\s+(?:"[^"]*"|'[^']*'))$/s);
+        const dest = titleMatch ? titleMatch[1] : trimmed;
+        const title = titleMatch ? titleMatch[2] : '';
+        if (!dest || !/\s/.test(dest)) {
+            return match;
+        }
+        return `![${alt}](<${dest}>${title})`;
+    });
+}
+/**
+ * Collect every image reference in a markdown document, in document order.
+ * Callers use this to know what needs uploading before converting.
+ */
+function collectMarkdownImageSources(markdown) {
+    const images = [];
+    try {
+        const tree = (0, unified_1.unified)()
+            .use(remark_parse_1.default)
+            .use(remark_gfm_1.default)
+            .parse(markdown);
+        const visit = (nodes) => {
+            for (const node of nodes) {
+                if (node.type === 'image' && typeof node.url === 'string') {
+                    images.push({ src: node.url, alt: typeof node.alt === 'string' ? node.alt : '' });
+                }
+                else if (Array.isArray(node.children)) {
+                    visit(node.children);
+                }
+            }
+        };
+        visit(tree.children);
+    }
+    catch (error) {
+        console.error('Failed to collect markdown images:', error);
+    }
+    return images;
+}
+/**
+ * Replace image sources in markdown with their uploaded ClickUp URLs.
+ *
+ * Used for task descriptions: `markdown_description` renders `![alt](url)` directly,
+ * so descriptions need no fragment handling - only the URL has to be swapped.
+ * Images without an upload keep their original source untouched.
+ */
+function rewriteMarkdownImageUrls(markdown, attachmentsBySrc) {
+    if (attachmentsBySrc.size === 0) {
+        return markdown;
+    }
+    return markdown.replace(/!\[([^\]]*)\]\(\s*(<[^>]*>|[^)\s]+)([^)]*)\)/g, (match, alt, rawSrc, trailing) => {
+        const src = rawSrc.startsWith('<') && rawSrc.endsWith('>') ? rawSrc.slice(1, -1) : rawSrc;
+        const attachment = attachmentsBySrc.get(src);
+        if (!attachment) {
+            return match;
+        }
+        return `![${alt}](${attachment.url}${trailing})`;
+    });
+}
 /**
  * Convert markdown text to ClickUp comment blocks format using remark
- * Supports: headers, bold, italic, code, links, lists, blockquotes, code blocks
+ * Supports: headers, bold, italic, code, links, lists, blockquotes, code blocks, images
  *
  * @param markdown The markdown text to convert
+ * @param attachmentsBySrc Uploaded attachments keyed by the markdown `src` they came from.
+ *   Images without an entry degrade to a link so their information is not lost.
  * @returns Array of ClickUp comment blocks
  */
-function convertMarkdownToClickUpBlocks(markdown) {
+function convertMarkdownToClickUpBlocks(markdown, attachmentsBySrc) {
     const blocks = [];
     try {
         // Parse the entire markdown document using remark with GFM support (for task lists)
@@ -396,7 +538,7 @@ function convertMarkdownToClickUpBlocks(markdown) {
             .use(remark_gfm_1.default)
             .parse(markdown);
         // Walk the tree recursively
-        walkMdastNodes(tree.children, {}, blocks);
+        walkMdastNodes(tree.children, {}, blocks, 0, attachmentsBySrc);
     }
     catch (error) {
         console.error('Failed to parse markdown:', error);
@@ -412,20 +554,20 @@ function convertMarkdownToClickUpBlocks(markdown) {
  * @param blocks Output array to append ClickUp blocks to
  * @param depth Nesting depth for lists (0 = top level, 1 = first nest, etc.)
  */
-function walkMdastNodes(nodes, inheritedAttrs, blocks, depth = 0) {
+function walkMdastNodes(nodes, inheritedAttrs, blocks, depth = 0, attachmentsBySrc) {
     for (let i = 0; i < nodes.length; i++) {
         const node = nodes[i];
         const currentAttrs = { ...inheritedAttrs };
         switch (node.type) {
             case 'heading':
                 // Process heading content with inline formatting
-                walkPhrasingContent(node.children, currentAttrs, blocks);
+                walkPhrasingContent(node.children, currentAttrs, blocks, attachmentsBySrc);
                 // Add newline with header attribute
                 blocks.push({ text: '\n', attributes: { header: node.depth } });
                 break;
             case 'paragraph':
                 // Process paragraph content with inline formatting
-                walkPhrasingContent(node.children, currentAttrs, blocks);
+                walkPhrasingContent(node.children, currentAttrs, blocks, attachmentsBySrc);
                 // Add newline unless it's the last node
                 if (i < nodes.length - 1) {
                     blocks.push({ text: '\n', attributes: {} });
@@ -437,7 +579,7 @@ function walkMdastNodes(nodes, inheritedAttrs, blocks, depth = 0) {
                 const blockquoteChildren = node.children;
                 for (const child of blockquoteChildren) {
                     if (child.type === 'paragraph') {
-                        walkPhrasingContent(child.children, currentAttrs, blocks);
+                        walkPhrasingContent(child.children, currentAttrs, blocks, attachmentsBySrc);
                         blocks.push({ text: '\n', attributes: { blockquote: {} } });
                     }
                     // Note: Other child types (heading, list) are not supported by ClickUp blockquotes
@@ -457,7 +599,7 @@ function walkMdastNodes(nodes, inheritedAttrs, blocks, depth = 0) {
                     for (const itemChild of listItem.children) {
                         if (itemChild.type === 'paragraph') {
                             // Process paragraph content with inline formatting
-                            walkPhrasingContent(itemChild.children, currentAttrs, blocks);
+                            walkPhrasingContent(itemChild.children, currentAttrs, blocks, attachmentsBySrc);
                             // Add newline with list formatting and optional indent
                             const listAttrs = {
                                 list: { list: finalListType }
@@ -470,7 +612,7 @@ function walkMdastNodes(nodes, inheritedAttrs, blocks, depth = 0) {
                         }
                         else if (itemChild.type === 'list') {
                             // Nested list - recursively process with increased depth
-                            walkMdastNodes([itemChild], currentAttrs, blocks, depth + 1);
+                            walkMdastNodes([itemChild], currentAttrs, blocks, depth + 1, attachmentsBySrc);
                         }
                     }
                 }
@@ -493,7 +635,7 @@ function walkMdastNodes(nodes, inheritedAttrs, blocks, depth = 0) {
             default:
                 // For any other block-level nodes, try to process children
                 if ('children' in node && Array.isArray(node.children)) {
-                    walkMdastNodes(node.children, currentAttrs, blocks, depth);
+                    walkMdastNodes(node.children, currentAttrs, blocks, depth, attachmentsBySrc);
                 }
                 break;
         }
@@ -503,10 +645,30 @@ function walkMdastNodes(nodes, inheritedAttrs, blocks, depth = 0) {
  * Recursively walk phrasing content (inline nodes) and build ClickUp blocks
  * Accumulates formatting attributes from parent nodes
  */
-function walkPhrasingContent(nodes, inheritedAttrs, blocks) {
+function walkPhrasingContent(nodes, inheritedAttrs, blocks, attachmentsBySrc) {
     for (const node of nodes) {
         const currentAttrs = { ...inheritedAttrs };
         switch (node.type) {
+            case 'image': {
+                // An image node has neither `value` nor `children`, so without this case it
+                // would fall through to `default` and vanish silently.
+                const attachment = attachmentsBySrc?.get(node.url);
+                const caption = node.alt || '';
+                if (attachment) {
+                    blocks.push(buildImageFragment(attachment, caption));
+                }
+                else {
+                    // Nothing was uploaded for this source - degrade to a link rather than
+                    // dropping the reference, so the information survives.
+                    const label = caption || node.url;
+                    const isEmbeddable = /^https?:\/\//i.test(node.url);
+                    blocks.push({
+                        text: label,
+                        attributes: isEmbeddable ? { ...currentAttrs, link: node.url } : currentAttrs,
+                    });
+                }
+                break;
+            }
             case 'text':
                 // Plain text node
                 if (node.value) {
@@ -519,12 +681,12 @@ function walkPhrasingContent(nodes, inheritedAttrs, blocks) {
             case 'strong':
                 // Bold text - recurse with bold attribute
                 currentAttrs.bold = true;
-                walkPhrasingContent(node.children, currentAttrs, blocks);
+                walkPhrasingContent(node.children, currentAttrs, blocks, attachmentsBySrc);
                 break;
             case 'emphasis':
                 // Italic text - recurse with italic attribute
                 currentAttrs.italic = true;
-                walkPhrasingContent(node.children, currentAttrs, blocks);
+                walkPhrasingContent(node.children, currentAttrs, blocks, attachmentsBySrc);
                 break;
             case 'inlineCode':
                 // Inline code
@@ -536,11 +698,20 @@ function walkPhrasingContent(nodes, inheritedAttrs, blocks) {
                     });
                 }
                 break;
-            case 'link':
-                // Link - recurse with link attribute
+            case 'link': {
+                // A link to a ClickUp task becomes a real task mention, matching what the
+                // ClickUp UI does when a task URL is pasted. The mention renders the live
+                // task name, so any custom link text is intentionally replaced by it.
+                const mentionedTaskId = parseClickUpTaskUrl(node.url);
+                if (mentionedTaskId) {
+                    blocks.push({ type: 'task_mention', task_mention: { task_id: mentionedTaskId } });
+                    break;
+                }
+                // Ordinary link - recurse with link attribute
                 currentAttrs.link = node.url;
-                walkPhrasingContent(node.children, currentAttrs, blocks);
+                walkPhrasingContent(node.children, currentAttrs, blocks, attachmentsBySrc);
                 break;
+            }
             case 'break':
                 // Line break - add as plain text
                 blocks.push({ text: '\n', attributes: {} });
@@ -555,7 +726,7 @@ function walkPhrasingContent(nodes, inheritedAttrs, blocks) {
                 }
                 else if ('children' in node && Array.isArray(node.children)) {
                     // Recurse into children for other container nodes
-                    walkPhrasingContent(node.children, currentAttrs, blocks);
+                    walkPhrasingContent(node.children, currentAttrs, blocks, attachmentsBySrc);
                 }
                 break;
         }

package/dist/shared/attachments.d.ts

@@ -0,0 +1,112 @@
+import { Buffer } from "buffer";
+/**
+ * Attachment object as returned by POST /api/v2/task/{task_id}/attachment.
+ * ClickUp only renders an image inside a comment when the fragment carries this
+ * whole object - a bare URL string renders as an empty placeholder tile.
+ */
+export interface ClickUpUploadedAttachment {
+    id: string;
+    name: string;
+    title?: string;
+    extension?: string;
+    url: string;
+    thumbnail_small?: string;
+    thumbnail_medium?: string;
+    thumbnail_large?: string;
+    width?: number;
+    height?: number;
+    [key: string]: any;
+}
+/** Image bytes ready to be uploaded */
+interface ResolvedBytes {
+    kind: "bytes";
+    bytes: Buffer;
+    mimeType: string;
+    suggestedName: string;
+}
+/** Already an attachment on ClickUp's CDN - reuse it instead of uploading again */
+interface ResolvedExisting {
+    kind: "existing";
+    url: string;
+}
+export type ResolvedImageSource = ResolvedBytes | ResolvedExisting;
+/**
+ * ClickUp serves attachments from *.clickup-attachments.com. Such a URL is
+ * already uploaded, so it can be embedded directly.
+ */
+export declare function isClickUpAttachmentUrl(url: string): boolean;
+/**
+ * Turn the `src` of a markdown image into something uploadable.
+ *
+ * Supported sources, in this order:
+ * - a ClickUp attachment URL      -> reused as-is, no upload
+ * - a base64 data URI             -> decoded
+ * - any other http(s) URL         -> downloaded
+ * - anything else                 -> read from the local filesystem
+ *
+ * The local path case is the interesting one: this server runs next to the agent,
+ * so a screenshot can be referenced by path instead of being inlined as base64,
+ * which would otherwise cost a multiple of the file size in tokens.
+ */
+export declare function resolveImageSource(src: string, baseDir?: string): Promise<ResolvedImageSource>;
+/**
+ * Derive the upload filename from the markdown alt text.
+ *
+ * ClickUp shows the *attachment filename* underneath an image, not the fragment
+ * text - so naming the upload after the caption is what makes a readable caption
+ * appear in the ticket.
+ */
+export declare function captionToFilename(caption: string, fallbackName: string): string;
+/**
+ * Upload a single image to a task and return the full attachment object.
+ */
+export declare function uploadTaskAttachment(taskId: string, filename: string, bytes: Buffer, mimeType: string): Promise<ClickUpUploadedAttachment>;
+/** A markdown image whose source resolved to uploadable bytes or an existing attachment */
+export interface ResolvedMarkdownImage {
+    /** The original `src` as written in the markdown */
+    src: string;
+    alt: string;
+    resolved: ResolvedImageSource;
+}
+/** One markdown image reference that could not be used, and why */
+export interface ImageFailure {
+    src: string;
+    error: string;
+}
+/**
+ * Phase 1 of attaching images: resolve every source without writing anything.
+ *
+ * Reads local files, downloads http(s) URLs, decodes data URIs and validates
+ * magic bytes and size. Failures are collected instead of thrown so the caller
+ * can report every broken reference at once - and abort before anything is
+ * posted to ClickUp. Identical sources are resolved once.
+ */
+export declare function resolveMarkdownImages(images: {
+    src: string;
+    alt: string;
+}[], baseDir?: string): Promise<{
+    resolved: ResolvedMarkdownImage[];
+    failures: ImageFailure[];
+}>;
+/** A successfully uploaded (or reused) attachment for one markdown source */
+export interface UploadedMarkdownImage {
+    src: string;
+    attachment: ClickUpUploadedAttachment;
+}
+/**
+ * Phase 2: upload the resolved images to the task.
+ *
+ * Uploads run sequentially: a typical comment has a handful of screenshots, and
+ * N uploads plus one write call stays well inside ClickUp's 100 calls/minute.
+ * Stops at the first upload error - an API failure is unlikely to heal mid-batch,
+ * and everything uploaded so far is returned so the caller can tell a retry to
+ * reference those CDN URLs directly instead of uploading again.
+ */
+export declare function uploadResolvedImages(taskId: string, images: ResolvedMarkdownImage[]): Promise<{
+    uploaded: UploadedMarkdownImage[];
+    failure: ImageFailure | null;
+}>;
+/** Map from markdown `src` to the attachment that should be embedded for it. */
+export declare function toAttachmentMap(uploaded: UploadedMarkdownImage[]): Map<string, ClickUpUploadedAttachment>;
+export {};
+//# sourceMappingURL=attachments.d.ts.map