@hauptsache.net/clickup-mcp 1.6.2 → 1.7.0

package/README.md

@@ -11,7 +11,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                          |
@@ -22,6 +22,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
 
@@ -229,6 +230,7 @@ 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_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.
 
@@ -284,6 +286,35 @@ 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`, `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 is reported in the response, and the comment or task is
+  still written.
+- 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

@@ -67,17 +67,83 @@ export interface ClickUpCommentBlock {
         };
         indent?: number;
         'block-id'?: string;
+        alt?: string;
     };
     list?: {
         list: 'bullet' | 'ordered' | 'unchecked' | 'checked';
     };
+    /**
+     * 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;
+/**
+ * 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,10 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.convertClickUpTextItemsToToolCallResult = convertClickUpTextItemsToToolCallResult;
 exports.convertMarkdownToToolCallResult = convertMarkdownToToolCallResult;
+exports.buildImageFragment = buildImageFragment;
+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");
@@ -380,14 +384,116 @@ 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;
+}
+/**
+ * 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 +502,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 +518,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 +543,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 +563,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 +576,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 +599,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 +609,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 +645,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
@@ -539,7 +665,7 @@ function walkPhrasingContent(nodes, inheritedAttrs, blocks) {
             case 'link':
                 // 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
@@ -555,7 +681,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,91 @@
+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>;
+/** One markdown image reference and what became of it */
+export interface ImageUploadResult {
+    /** The original `src` as written in the markdown */
+    src: string;
+    /** Attachment to embed, or null when the upload failed */
+    attachment: ClickUpUploadedAttachment | null;
+    /** Reason the upload failed, for reporting back to the caller */
+    error?: string;
+}
+/**
+ * Upload every image referenced in the markdown to the given 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.
+ * A failing image never fails the whole batch - the caller writes the comment
+ * anyway and reports which images did not make it.
+ */
+export declare function uploadMarkdownImages(taskId: string, images: {
+    src: string;
+    alt: string;
+}[], baseDir?: string): Promise<ImageUploadResult[]>;
+/**
+ * Map from markdown `src` to the attachment that should be embedded for it.
+ * Sources whose upload failed are absent, so the converters fall back to text.
+ */
+export declare function toAttachmentMap(results: ImageUploadResult[]): Map<string, ClickUpUploadedAttachment>;
+export {};
+//# sourceMappingURL=attachments.d.ts.map

package/dist/shared/attachments.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"attachments.d.ts","sourceRoot":"","sources":["../../src/shared/attachments.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAC;AAQhC;;;;GAIG;AACH,MAAM,WAAW,yBAAyB;IACxC,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,GAAG,EAAE,MAAM,CAAC;IACZ,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,CAAC,GAAG,EAAE,MAAM,GAAG,GAAG,CAAC;CACpB;AAED,uCAAuC;AACvC,UAAU,aAAa;IACrB,IAAI,EAAE,OAAO,CAAC;IACd,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE,MAAM,CAAC;IACjB,aAAa,EAAE,MAAM,CAAC;CACvB;AAED,mFAAmF;AACnF,UAAU,gBAAgB;IACxB,IAAI,EAAE,UAAU,CAAC;IACjB,GAAG,EAAE,MAAM,CAAC;CACb;AAED,MAAM,MAAM,mBAAmB,GAAG,aAAa,GAAG,gBAAgB,CAAC;AAoCnE;;;GAGG;AACH,wBAAgB,sBAAsB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAM3D;AAED;;;;;;;;;;;;GAYG;AACH,wBAAsB,kBAAkB,CACtC,GAAG,EAAE,MAAM,EACX,OAAO,GAAE,MAAsB,GAC9B,OAAO,CAAC,mBAAmB,CAAC,CA2C9B;AAcD;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,GAAG,MAAM,CAS/E;AAmCD;;GAEG;AACH,wBAAsB,oBAAoB,CACxC,MAAM,EAAE,MAAM,EACd,QAAQ,EAAE,MAAM,EAChB,KAAK,EAAE,MAAM,EACb,QAAQ,EAAE,MAAM,GACf,OAAO,CAAC,yBAAyB,CAAC,CAwBpC;AAED,yDAAyD;AACzD,MAAM,WAAW,iBAAiB;IAChC,oDAAoD;IACpD,GAAG,EAAE,MAAM,CAAC;IACZ,0DAA0D;IAC1D,UAAU,EAAE,yBAAyB,GAAG,IAAI,CAAC;IAC7C,iEAAiE;IACjE,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED;;;;;;;GAOG;AACH,wBAAsB,oBAAoB,CACxC,MAAM,EAAE,MAAM,EACd,MAAM,EAAE;IAAE,GAAG,EAAE,MAAM,CAAC;IAAC,GAAG,EAAE,MAAM,CAAA;CAAE,EAAE,EACtC,OAAO,GAAE,MAAsB,GAC9B,OAAO,CAAC,iBAAiB,EAAE,CAAC,CAqD9B;AAED;;;GAGG;AACH,wBAAgB,eAAe,CAC7B,OAAO,EAAE,iBAAiB,EAAE,GAC3B,GAAG,CAAC,MAAM,EAAE,yBAAyB,CAAC,CAQxC"}

package/dist/shared/attachments.js

@@ -0,0 +1,254 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isClickUpAttachmentUrl = isClickUpAttachmentUrl;
+exports.resolveImageSource = resolveImageSource;
+exports.captionToFilename = captionToFilename;
+exports.uploadTaskAttachment = uploadTaskAttachment;
+exports.uploadMarkdownImages = uploadMarkdownImages;
+exports.toAttachmentMap = toAttachmentMap;
+const buffer_1 = require("buffer");
+const crypto_1 = require("crypto");
+const promises_1 = require("fs/promises");
+const path_1 = require("path");
+const config_1 = require("./config");
+const data_uri_1 = require("./data-uri");
+const image_processing_1 = require("./image-processing");
+const MIME_EXTENSIONS = {
+    "image/png": ".png",
+    "image/jpeg": ".jpg",
+    "image/gif": ".gif",
+    "image/webp": ".webp",
+};
+/**
+ * Detect the mime type from magic bytes and reject anything that is not an image
+ * we know how to display. This is both a correctness guard (ClickUp needs a real
+ * image to render a preview) and a safety guard: it stops arbitrary local files
+ * from being pushed into a ticket just because a path was mentioned in markdown.
+ */
+function assertSupportedImage(bytes, source) {
+    // Copy into a fresh view - Buffer instances share a pooled ArrayBuffer, so
+    // passing bytes.buffer directly would hand over unrelated neighbouring data.
+    const detected = (0, image_processing_1.detectMimeTypeFromBuffer)(new Uint8Array(bytes).buffer);
+    if (!detected) {
+        throw new Error(`${source} is not a supported image (expected PNG, JPEG, GIF or WebP based on its content)`);
+    }
+    return detected;
+}
+function assertWithinSizeLimit(byteLength, source) {
+    const limit = config_1.CONFIG.maxUploadSizeMB * 1024 * 1024;
+    if (byteLength > limit) {
+        throw new Error(`${source} is ${(byteLength / 1024 / 1024).toFixed(1)} MB which exceeds the ${config_1.CONFIG.maxUploadSizeMB} MB upload limit (raise MAX_UPLOAD_SIZE_MB to allow it)`);
+    }
+}
+/**
+ * ClickUp serves attachments from *.clickup-attachments.com. Such a URL is
+ * already uploaded, so it can be embedded directly.
+ */
+function isClickUpAttachmentUrl(url) {
+    try {
+        return new URL(url).hostname.endsWith(".clickup-attachments.com");
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * 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.
+ */
+async function resolveImageSource(src, baseDir = process.cwd()) {
+    if (isClickUpAttachmentUrl(src)) {
+        return { kind: "existing", url: src };
+    }
+    const dataUri = (0, data_uri_1.parseDataUri)(src);
+    if (dataUri) {
+        const bytes = buffer_1.Buffer.from(dataUri.base64Data, "base64");
+        assertWithinSizeLimit(bytes.byteLength, "The inline image");
+        const mimeType = assertSupportedImage(bytes, "The inline image");
+        return {
+            kind: "bytes",
+            bytes,
+            mimeType,
+            suggestedName: `image${MIME_EXTENSIONS[mimeType] ?? ".png"}`,
+        };
+    }
+    if (/^https?:\/\//i.test(src)) {
+        const response = await fetch(src);
+        if (!response.ok) {
+            throw new Error(`Could not download ${src}: ${response.status} ${response.statusText}`);
+        }
+        const bytes = buffer_1.Buffer.from(await response.arrayBuffer());
+        assertWithinSizeLimit(bytes.byteLength, src);
+        const mimeType = assertSupportedImage(bytes, src);
+        const urlName = (0, path_1.basename)(new URL(src).pathname) || `image${MIME_EXTENSIONS[mimeType] ?? ".png"}`;
+        return { kind: "bytes", bytes, mimeType, suggestedName: decodeURIComponent(urlName) };
+    }
+    const filePath = (0, path_1.isAbsolute)(src) ? src : (0, path_1.resolve)(baseDir, decodeFilePath(src));
+    let bytes;
+    try {
+        bytes = await (0, promises_1.readFile)(filePath);
+    }
+    catch (error) {
+        if (error?.code === "ENOENT") {
+            throw new Error(`No such file: ${filePath}`);
+        }
+        throw new Error(`Could not read ${filePath}: ${error?.message || "unknown error"}`);
+    }
+    assertWithinSizeLimit(bytes.byteLength, filePath);
+    const mimeType = assertSupportedImage(bytes, filePath);
+    return { kind: "bytes", bytes, mimeType, suggestedName: (0, path_1.basename)(filePath) };
+}
+/**
+ * Markdown writers tend to percent-encode spaces in paths (`my%20shot.png`).
+ * Decode them, but leave the path alone if it is not valid encoding.
+ */
+function decodeFilePath(src) {
+    try {
+        return decodeURIComponent(src);
+    }
+    catch {
+        return src;
+    }
+}
+/**
+ * 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.
+ */
+function captionToFilename(caption, fallbackName) {
+    const extension = (0, path_1.extname)(fallbackName) || ".png";
+    const cleaned = caption
+        .replace(/[/\\:*?"<>|]/g, " ")
+        .replace(/\s+/g, " ")
+        .trim()
+        .slice(0, 120)
+        .trim();
+    return cleaned ? `${cleaned}${extension}` : fallbackName;
+}
+/**
+ * Build the multipart/form-data body by hand.
+ *
+ * Deliberately not using `FormData`: the global FormData is only understood by the
+ * fetch implementation it ships with, so swapping fetch (as the tests do) silently
+ * turns the body into the string "[object FormData]". A hand-built buffer behaves
+ * identically everywhere and keeps the wire format assertable.
+ */
+function buildMultipartBody(filename, bytes, mimeType) {
+    const boundary = `----clickupmcp${(0, crypto_1.randomUUID)().replace(/-/g, "")}`;
+    // Quotes and newlines would break out of the header - strip them.
+    const safeName = filename.replace(/["\r\n]/g, "");
+    const head = buffer_1.Buffer.from(`--${boundary}\r\n` +
+        `Content-Disposition: form-data; name="attachment"; filename="${safeName}"\r\n` +
+        `Content-Type: ${mimeType}\r\n\r\n`, "utf8");
+    const tail = buffer_1.Buffer.from(`\r\n--${boundary}--\r\n`, "utf8");
+    // Hand over a bare ArrayBuffer: Buffer and Uint8Array both trip up the BodyInit
+    // typing here. Copying into a fresh Uint8Array also detaches from Buffer's shared
+    // pool, so the ArrayBuffer contains exactly our bytes and nothing else.
+    const combined = new Uint8Array(buffer_1.Buffer.concat([head, bytes, tail]));
+    return {
+        body: combined.buffer,
+        contentType: `multipart/form-data; boundary=${boundary}`,
+    };
+}
+/**
+ * Upload a single image to a task and return the full attachment object.
+ */
+async function uploadTaskAttachment(taskId, filename, bytes, mimeType) {
+    const { body, contentType } = buildMultipartBody(filename, bytes, mimeType);
+    const response = await fetch(`https://api.clickup.com/api/v2/task/${taskId}/attachment`, {
+        method: "POST",
+        headers: {
+            Authorization: config_1.CONFIG.apiKey,
+            "Content-Type": contentType,
+        },
+        body,
+    });
+    if (!response.ok) {
+        const errorText = await response.text().catch(() => "");
+        throw new Error(`Upload of "${filename}" failed: ${response.status} ${response.statusText}${errorText ? ` - ${errorText.slice(0, 300)}` : ""}`);
+    }
+    const attachment = (await response.json());
+    if (!attachment?.url) {
+        throw new Error(`Upload of "${filename}" returned no URL: ${JSON.stringify(attachment)}`);
+    }
+    return attachment;
+}
+/**
+ * Upload every image referenced in the markdown to the given 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.
+ * A failing image never fails the whole batch - the caller writes the comment
+ * anyway and reports which images did not make it.
+ */
+async function uploadMarkdownImages(taskId, images, baseDir = process.cwd()) {
+    const results = [];
+    // Identical sources are uploaded once and reused.
+    const seen = new Map();
+    for (const { src, alt } of images) {
+        const cached = seen.get(src);
+        if (cached) {
+            results.push(cached);
+            continue;
+        }
+        let result;
+        try {
+            const resolved = await resolveImageSource(src, baseDir);
+            if (resolved.kind === "existing") {
+                // Already on ClickUp's CDN - synthesise the minimal attachment shape so
+                // the fragment builder has something to work with.
+                const name = decodeURIComponent((0, path_1.basename)(new URL(resolved.url).pathname));
+                result = {
+                    src,
+                    attachment: {
+                        id: name,
+                        name,
+                        title: alt || name,
+                        extension: (0, path_1.extname)(name).replace(/^\./, "") || undefined,
+                        url: resolved.url,
+                        thumbnail_small: resolved.url,
+                        thumbnail_medium: resolved.url,
+                        thumbnail_large: resolved.url,
+                    },
+                };
+            }
+            else {
+                const filename = captionToFilename(alt, resolved.suggestedName);
+                const attachment = await uploadTaskAttachment(taskId, filename, resolved.bytes, resolved.mimeType);
+                result = { src, attachment };
+            }
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : "unknown error";
+            console.error(`Failed to attach image "${src}": ${message}`);
+            result = { src, attachment: null, error: message };
+        }
+        seen.set(src, result);
+        results.push(result);
+    }
+    return results;
+}
+/**
+ * Map from markdown `src` to the attachment that should be embedded for it.
+ * Sources whose upload failed are absent, so the converters fall back to text.
+ */
+function toAttachmentMap(results) {
+    const map = new Map();
+    for (const result of results) {
+        if (result.attachment) {
+            map.set(result.src, result.attachment);
+        }
+    }
+    return map;
+}

package/dist/shared/config.d.ts

@@ -5,6 +5,7 @@ export declare const CONFIG: {
     teamId: string;
     maxImages: number;
     maxResponseSizeMB: number;
+    maxUploadSizeMB: number;
     primaryLanguageHint: string | undefined;
     mode: McpMode;
 };

package/dist/shared/config.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../../src/shared/config.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,cAAc,oBAA2D,CAAC;AAkDvF,MAAM,MAAM,OAAO,GAAG,cAAc,GAAG,MAAM,GAAG,OAAO,CAAC;AAUxD,eAAO,MAAM,MAAM;;;;;;;CAOlB,CAAC"}
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../../src/shared/config.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,cAAc,oBAA2D,CAAC;AAkDvF,MAAM,MAAM,OAAO,GAAG,cAAc,GAAG,MAAM,GAAG,OAAO,CAAC;AAUxD,eAAO,MAAM,MAAM;;;;;;;;CAWlB,CAAC"}

package/dist/shared/config.js

@@ -53,6 +53,10 @@ exports.CONFIG = {
     teamId: process.env.CLICKUP_TEAM_ID,
     maxImages: process.env.MAX_IMAGES ? parseInt(process.env.MAX_IMAGES) : 4,
     maxResponseSizeMB: process.env.MAX_RESPONSE_SIZE_MB ? parseFloat(process.env.MAX_RESPONSE_SIZE_MB) : 1,
+    // Upper bound for a single image uploaded to ClickUp. Unlike maxResponseSizeMB this is
+    // not about context window budget - it only guards against accidentally pushing huge
+    // files into a ticket.
+    maxUploadSizeMB: process.env.MAX_UPLOAD_SIZE_MB ? parseFloat(process.env.MAX_UPLOAD_SIZE_MB) : 10,
     primaryLanguageHint: detectedLanguageHint, // Store the cleaned code directly
     mode: mcpMode,
 };

package/dist/shared/image-processing.d.ts

@@ -1,4 +1,9 @@
 import { ContentBlock, ImageMetadataBlock } from "./types";
+/**
+ * Detect MIME type from image binary data using magic bytes (file signatures)
+ * Returns null if the format is not recognized
+ */
+export declare function detectMimeTypeFromBuffer(buffer: ArrayBuffer): string | null;
 /**
  * Downloads images from image_metadata blocks and applies smart size/count limiting
  * Prioritizes keeping the most recent images (assumes content is ordered with newest items last)

package/dist/shared/image-processing.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"image-processing.d.ts","sourceRoot":"","sources":["../../src/shared/image-processing.ts"],"names":[],"mappings":"AAAA,OAAO,EAAC,YAAY,EAAE,kBAAkB,EAAC,MAAM,SAAS,CAAC;AAmDzD;;;;;;;;;GASG;AACH,wBAAsB,cAAc,CAAC,OAAO,EAAE,CAAC,YAAY,GAAG,kBAAkB,CAAC,EAAE,EAAE,SAAS,GAAE,MAAyB,EAAE,SAAS,GAAE,MAAiC,GAAG,OAAO,CAAC,YAAY,EAAE,CAAC,CA0BhM"}
+{"version":3,"file":"image-processing.d.ts","sourceRoot":"","sources":["../../src/shared/image-processing.ts"],"names":[],"mappings":"AAAA,OAAO,EAAC,YAAY,EAAE,kBAAkB,EAAC,MAAM,SAAS,CAAC;AAKzD;;;GAGG;AACH,wBAAgB,wBAAwB,CAAC,MAAM,EAAE,WAAW,GAAG,MAAM,GAAG,IAAI,CA0B3E;AAgBD;;;;;;;;;GASG;AACH,wBAAsB,cAAc,CAAC,OAAO,EAAE,CAAC,YAAY,GAAG,kBAAkB,CAAC,EAAE,EAAE,SAAS,GAAE,MAAyB,EAAE,SAAS,GAAE,MAAiC,GAAG,OAAO,CAAC,YAAY,EAAE,CAAC,CA0BhM"}

package/dist/shared/image-processing.js

@@ -1,5 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.detectMimeTypeFromBuffer = detectMimeTypeFromBuffer;
 exports.downloadImages = downloadImages;
 const config_1 = require("./config");
 const data_uri_1 = require("./data-uri");

package/dist/tools/task-write-tools.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"task-write-tools.d.ts","sourceRoot":"","sources":["../../src/tools/task-write-tools.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AAcpE,wBAAgB,sBAAsB,CAAC,MAAM,EAAE,SAAS,EAAE,QAAQ,EAAE,GAAG,QAsZtE"}
+{"version":3,"file":"task-write-tools.d.ts","sourceRoot":"","sources":["../../src/tools/task-write-tools.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AAgGpE,wBAAgB,sBAAsB,CAAC,MAAM,EAAE,SAAS,EAAE,QAAQ,EAAE,GAAG,QA+ctE"}

package/dist/tools/task-write-tools.js

@@ -5,6 +5,67 @@ const zod_1 = require("zod");
 const config_1 = require("../shared/config");
 const utils_1 = require("../shared/utils");
 const clickup_text_1 = require("../clickup-text");
+const attachments_1 = require("../shared/attachments");
+/**
+ * Shared wording for the image support of every markdown field in this file.
+ * Kept in one place so the tools stay consistent about what a client may pass.
+ */
+const IMAGE_SUPPORT_HINT = [
+    "IMAGES: Reference images with normal markdown - `![caption](/absolute/path/to/screenshot.png)`.",
+    "This server runs locally, so a local file path is read and uploaded automatically - never inline a screenshot as base64 when a path exists, it costs orders of magnitude more tokens.",
+    "Also accepted: `data:` URIs, http(s) URLs (downloaded and re-uploaded), and existing ClickUp attachment URLs (embedded as-is).",
+    "The caption becomes the attachment filename, which is what ClickUp displays beneath the image - so write a caption that reads well.",
+].join("\n");
+/**
+ * Upload every image referenced in a markdown field and report what failed.
+ * Never throws: a broken image must not cost the user their comment or task.
+ */
+async function prepareMarkdownImages(taskId, markdown) {
+    if (!markdown) {
+        return { results: [], failures: [], markdown: markdown ?? "" };
+    }
+    // Normalise first, then use the same string for collecting and converting - the
+    // sources must line up with what the converter later looks up.
+    const normalized = (0, clickup_text_1.normalizeImageDestinations)(markdown);
+    const sources = (0, clickup_text_1.collectMarkdownImageSources)(normalized);
+    if (sources.length === 0) {
+        return { results: [], failures: [], markdown: normalized };
+    }
+    const results = await (0, attachments_1.uploadMarkdownImages)(taskId, sources);
+    const failures = results
+        .filter((result) => !result.attachment)
+        .map((result) => `${result.src}: ${result.error || "unknown error"}`);
+    return { results, failures, markdown: normalized };
+}
+/**
+ * Echo a markdown field back without repeating inline base64 payloads.
+ * Without this a single data-URI screenshot would be mirrored back into the
+ * response, costing as many tokens again as it did going in.
+ */
+function summarizeMarkdownForEcho(markdown) {
+    return markdown.replace(/(!\[[^\]]*\]\()data:([^;,)]+)[^)]*(\))/g, (_match, prefix, mimeType, suffix) => `${prefix}[inline ${mimeType} data]${suffix}`);
+}
+/** Report successfully attached images so the caller can link to them later */
+function formatAttachedImages(results) {
+    const attached = results.filter((result) => result.attachment);
+    if (attached.length === 0) {
+        return [];
+    }
+    return [
+        `images_attached: ${attached.length}`,
+        ...attached.map((result) => `  - ${result.attachment.name} (${result.attachment.url})`),
+    ];
+}
+/** Render upload failures as response lines so they are never silently swallowed */
+function formatImageFailures(failures) {
+    if (failures.length === 0) {
+        return [];
+    }
+    return [
+        `WARNING: ${failures.length} image(s) could not be attached and were replaced by their caption:`,
+        ...failures.map((failure) => `  - ${failure}`),
+    ];
+}
 // Shared schemas for task parameters
 const taskNameSchema = zod_1.z.string().min(1).describe("The name/title of the task");
 const taskPrioritySchema = zod_1.z.enum(["urgent", "high", "normal", "low"]).optional().describe("Optional priority level");
@@ -21,6 +82,8 @@ function registerTaskToolsWrite(server, userData) {
             "- Include task links when mentioning dependencies, related work, or follow-ups",
             "- Link to relevant lists, spaces, or other ClickUp entities when applicable",
             "PROGRESS UPDATES: Include current status, progress information, and next steps.",
+            IMAGE_SUPPORT_HINT,
+            "IMAGE LAYOUT: An image inside a numbered list breaks ClickUp's numbering. Write walkthrough steps as bold lines with a blank line before and after the image instead (`**1. Open the login page**`).",
             "If external links are provided, verify they are publicly accessible and incorporate relevant information.",
             "Check the task's current status - if it's in 'backlog' or similar inactive states, suggest moving it to an active status like 'in progress' when work is being done."
         ];
@@ -37,8 +100,11 @@ function registerTaskToolsWrite(server, userData) {
         idempotentHint: false,
     }, async ({ task_id, comment }) => {
         try {
+            // Upload referenced images first - the fragments need the attachment objects
+            // from the upload response, a bare URL renders as an empty tile.
+            const { results, failures, markdown } = await prepareMarkdownImages(task_id, comment);
             // Convert markdown to ClickUp formatted blocks
-            const commentBlocks = (0, clickup_text_1.convertMarkdownToClickUpBlocks)(comment);
+            const commentBlocks = (0, clickup_text_1.convertMarkdownToClickUpBlocks)(markdown, (0, attachments_1.toAttachmentMap)(results));
             const requestBody = {
                 comment: commentBlocks,
                 notify_all: true
@@ -64,9 +130,11 @@ function registerTaskToolsWrite(server, userData) {
                             `Comment added successfully!`,
                             `comment_id: ${commentData.id || 'N/A'}`,
                             `task_id: ${task_id}`,
-                            `comment: ${comment}`,
+                            `comment: ${summarizeMarkdownForEcho(comment)}`,
                             `date: ${timestampToIso(commentData.date || Date.now())}`,
                             `user: ${commentData.user?.username || 'Current user'}`,
+                            ...formatAttachedImages(results),
+                            ...formatImageFailures(failures),
                         ].join('\n')
                     }
                 ],
@@ -91,6 +159,7 @@ function registerTaskToolsWrite(server, userData) {
             "Use getListInfo first to see valid status options.",
             "SAFETY FEATURE: Description updates are APPEND-ONLY to prevent data loss - existing content is preserved.",
             "STATUS UPDATES: Use the `addComment` tool for progress reports, work logs, and status updates rather than the task description.",
+            IMAGE_SUPPORT_HINT,
             "Task descriptions should contain requirements, specifications, and core task information.",
             "LINKING IN DESCRIPTIONS: When appending descriptions, include links to related tasks, lists, or external resources.",
             "IMPORTANT: When updating tasks (especially when booking time or adding progress), ensure the status makes sense for the work being done - tasks in 'backlog' or 'closed' states usually shouldn't have active work.",
@@ -181,11 +250,19 @@ function registerTaskToolsWrite(server, userData) {
             }
             // Handle append-only description update with markdown support
             let finalDescription;
+            let imageResults = [];
+            let imageFailures = [];
             if (append_description) {
+                // Upload first, then swap the local paths for CDN URLs. Descriptions render
+                // plain markdown, so no image fragments are involved here.
+                const prepared = await prepareMarkdownImages(task_id, append_description);
+                imageResults = prepared.results;
+                imageFailures = prepared.failures;
+                const appended = (0, clickup_text_1.rewriteMarkdownImageUrls)(prepared.markdown, (0, attachments_1.toAttachmentMap)(imageResults));
                 const currentDescription = taskData.markdown_description || "";
                 const timestamp = new Date().toISOString().split('T')[0]; // YYYY-MM-DD format
                 const separator = currentDescription.trim() ? "\n\n---\n" : "";
-                finalDescription = currentDescription + separator + `**Edit (${timestamp}):** ${append_description}`;
+                finalDescription = currentDescription + separator + `**Edit (${timestamp}):** ${appended}`;
             }
             // Build update body without tags (they're handled separately)
             const updateBody = buildTaskRequestBody({
@@ -247,6 +324,8 @@ function registerTaskToolsWrite(server, userData) {
             if (tagUpdateResults.length > 0) {
                 responseLines.push('tag_warnings: ' + tagUpdateResults.join('; '));
             }
+            responseLines.push(...formatAttachedImages(imageResults));
+            responseLines.push(...formatImageFailures(imageFailures));
             return {
                 content: [
                     {
@@ -278,6 +357,7 @@ function registerTaskToolsWrite(server, userData) {
             "- The response will include the new task's clickable URL - always share this link",
             "Use getListInfo first to understand the list context and available statuses.",
             "Task descriptions support full markdown formatting including **bold**, *italic*, lists, links, and code blocks.",
+            IMAGE_SUPPORT_HINT,
             "BEST PRACTICE: Every task creation should result in sharing the clickable task URL for future reference."
         ];
         if (config_1.CONFIG.primaryLanguageHint && config_1.CONFIG.primaryLanguageHint.toLowerCase() !== 'en') {
@@ -325,9 +405,33 @@ function registerTaskToolsWrite(server, userData) {
                 throw new Error(`Error creating task: ${response.status} ${response.statusText} - ${JSON.stringify(errorData)}`);
             }
             const createdTask = await response.json();
+            // Images can only be attached once the task exists, so the description is
+            // written first with its original sources and then rewritten to the CDN URLs.
+            const { results: imageResults, failures: imageFailures, markdown: normalizedDescription, } = await prepareMarkdownImages(createdTask.id, description);
+            const attachmentMap = (0, attachments_1.toAttachmentMap)(imageResults);
+            if (description && attachmentMap.size > 0) {
+                const rewritten = (0, clickup_text_1.rewriteMarkdownImageUrls)(normalizedDescription, attachmentMap);
+                if (rewritten !== description) {
+                    const descriptionResponse = await fetch(`https://api.clickup.com/api/v2/task/${createdTask.id}`, {
+                        method: 'PUT',
+                        headers: {
+                            Authorization: config_1.CONFIG.apiKey,
+                            'Content-Type': 'application/json'
+                        },
+                        body: JSON.stringify({ markdown_description: rewritten })
+                    });
+                    if (!descriptionResponse.ok) {
+                        // The task itself exists - report the problem instead of failing the call.
+                        console.error(`Failed to write image URLs into description: ${descriptionResponse.status}`);
+                        imageFailures.push(`description update failed (${descriptionResponse.status} ${descriptionResponse.statusText}) - images are attached but not embedded`);
+                    }
+                }
+            }
             const responseLines = formatTaskResponse(createdTask, 'created', {
                 list_id, name, description, status, priority, due_date, start_date, time_estimate, tags, parent_task_id, assignees
             }, userData);
+            responseLines.push(...formatAttachedImages(imageResults));
+            responseLines.push(...formatImageFailures(imageFailures));
             return {
                 content: [
                     {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hauptsache.net/clickup-mcp",
-  "version": "1.6.2",
+  "version": "1.7.0",
   "description": "Search, create, and retrieve tasks, add comments, and track time through natural language commands.",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -14,11 +14,12 @@
     "start": "node dist/index.js",
     "dev": "npx tsc -w & nodemon dist/index.js",
     "cli": "npx ts-node src/cli.ts",
+    "smoke": "npx ts-node src/protocol-smoke.ts",
     "prettier": "prettier --write src/**/*.ts",
     "prepublishOnly": "rm -r dist && npm run build",
     "release": "npm run build && npm publish --access public && git add . && git commit -m \"Release v$(node -p 'require(\"./package.json\").version')\" && git tag -a v$(node -p 'require(\"./package.json\").version') -m \"Release v$(node -p 'require(\"./package.json\").version')\" && git push && git push --tags",
     "mcpb": "npm run build && mcpb pack . ClickUp.mcpb",
-    "test": "node --test -r ts-node/register src/**/*.test.ts"
+    "test": "node --test -r ts-node/register -r ./src/tests/setup.ts src/**/*.test.ts"
   },
   "keywords": [
     "clickup",