@hauptsache.net/clickup-mcp 1.7.0 → 1.7.2

package/README.md

@@ -188,6 +188,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                          |
@@ -223,7 +224,7 @@ Add the mode to your MCP configuration:
 
 ## Configuration
 
-This MCP server can be configured using environment variables:
+This MCP server can be configured using environment variables. In the desktop extension (`.mcpb`) installer, the API key, team ID, primary language, upload size limit and comment edit window are offered as form fields; the remaining variables have to be set on the server environment directly.
 
 - `CLICKUP_API_KEY`: (Required) Your ClickUp API key.
 - `CLICKUP_TEAM_ID`: (Required) Your ClickUp Team ID (formerly Workspace ID).
@@ -231,6 +232,7 @@ This MCP server can be configured using environment variables:
 - `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.
 
@@ -288,7 +290,7 @@ This ensures no existing content is ever lost while maintaining a clear audit tr
 
 ## Writing Images Into Tickets
 
-`addComment`, `createTask` and `updateTask` accept images as ordinary markdown. Because
+`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
@@ -311,8 +313,11 @@ Notes:
 - **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.
+  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

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;
@@ -54,6 +57,7 @@ export interface ClickUpCommentBlock {
     attributes?: {
         bold?: boolean;
         italic?: boolean;
+        strike?: boolean;
         code?: boolean;
         link?: string;
         'code-block'?: {
@@ -72,6 +76,13 @@ export interface ClickUpCommentBlock {
     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
@@ -111,6 +122,10 @@ export interface EmbeddableAttachment {
  * `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.
  *

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

@@ -1 +1 @@
-{"version":3,"file":"clickup-text.d.ts","sourceRoot":"","sources":["../src/clickup-text.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"clickup-text.d.ts","sourceRoot":"","sources":["../src/clickup-text.ts"],"names":[],"mappings":"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"}

package/dist/clickup-text.js

@@ -6,6 +6,7 @@ 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;
@@ -35,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
@@ -49,11 +62,24 @@ async function convertClickUpTextItemsToToolCallResult(textItems) {
     // Track current formatting state to avoid unnecessary close/reopen
     let activeBold = false;
     let activeItalic = false;
+    let activeStrike = false;
     let activeCode = false;
+    // ClickUp emits one '\n' fragment with a code-block attribute per code LINE;
+    // consecutive ones belong to the same fenced block when read back as markdown.
+    let inCodeBlock = false;
+    let currentFenceLang = '';
+    const closeCodeFence = () => {
+        if (inCodeBlock) {
+            currentTextBlock += '```\n';
+            inCodeBlock = false;
+            currentFenceLang = '';
+        }
+    };
     for (let i = 0; i < textItems.length; i++) {
         const item = textItems[i];
         // Handle image items
         if (item.type === "image" && item.image && item.image.url) {
+            closeCodeFence();
             const imageFileName = item.image.name || item.image.title || "image";
             const imageUrl = item.image.url;
             const altText = item.text || imageFileName;
@@ -84,8 +110,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)
@@ -118,6 +146,27 @@ async function convertClickUpTextItemsToToolCallResult(textItems) {
         else if (typeof item.text === "string") {
             // Check if this is a newline with block formatting (header, blockquote, list)
             if (item.text === '\n' && item.attributes) {
+                // Code block formatting: append this line to the open fence (or open one).
+                // The attribute value carries the language, either directly or nested as
+                // {'code-block': lang}; 'plain' means no language.
+                if (item.attributes['code-block']) {
+                    const rawLang = item.attributes['code-block'];
+                    const lang = typeof rawLang === 'string' ? rawLang : rawLang?.['code-block'] ?? '';
+                    const fenceLang = lang === 'plain' ? '' : lang;
+                    if (inCodeBlock && fenceLang !== currentFenceLang) {
+                        closeCodeFence();
+                    }
+                    if (!inCodeBlock) {
+                        currentTextBlock += '```' + fenceLang + '\n';
+                        inCodeBlock = true;
+                        currentFenceLang = fenceLang;
+                    }
+                    currentTextBlock += currentLine + '\n';
+                    currentLine = "";
+                    continue;
+                }
+                // Any other line terminator ends a code block
+                closeCodeFence();
                 // Header formatting
                 if (item.attributes.header) {
                     const level = item.attributes.header;
@@ -148,17 +197,8 @@ async function convertClickUpTextItemsToToolCallResult(textItems) {
                             break;
                     }
                 }
-                // Code block formatting
-                else if (item.attributes['code-block']) {
-                    // Wrap the current line in code block markers
-                    currentLine = '```\n' + currentLine + '\n```';
-                }
                 // Add formatted line to text block
-                currentTextBlock += currentLine;
-                // Add newline unless it's code block (already has newlines)
-                if (!item.attributes['code-block']) {
-                    currentTextBlock += '\n';
-                }
+                currentTextBlock += currentLine + '\n';
                 currentLine = ""; // Reset for next line
                 continue;
             }
@@ -167,15 +207,18 @@ async function convertClickUpTextItemsToToolCallResult(textItems) {
             // Determine current and next formatting state
             const hasBold = item.attributes?.bold === true;
             const hasItalic = item.attributes?.italic === true;
+            const hasStrike = item.attributes?.strike === true;
             const hasLink = item.attributes?.link;
             // Look ahead to next non-newline block
             let nextHasBold = false;
             let nextHasItalic = false;
+            let nextHasStrike = false;
             for (let j = i + 1; j < textItems.length; j++) {
                 const nextItem = textItems[j];
                 if (nextItem.text !== '\n' || !nextItem.attributes) {
                     nextHasBold = nextItem.attributes?.bold === true;
                     nextHasItalic = nextItem.attributes?.italic === true;
+                    nextHasStrike = nextItem.attributes?.strike === true;
                     break;
                 }
             }
@@ -185,14 +228,20 @@ async function convertClickUpTextItemsToToolCallResult(textItems) {
                 prefix += "**";
             if (hasItalic && !activeItalic)
                 prefix += "*";
+            if (hasStrike && !activeStrike)
+                prefix += "~~";
             // Build suffix (close formatting that won't continue)
             let suffix = "";
+            if (hasStrike && !nextHasStrike)
+                suffix += "~~";
             if (hasItalic && !nextHasItalic)
                 suffix += "*";
             if (hasBold && !nextHasBold)
                 suffix += "**";
             // Close formatting that's active but not in this block
             let closingPrefix = "";
+            if (activeStrike && !hasStrike)
+                closingPrefix += "~~";
             if (activeBold && !hasBold)
                 closingPrefix += "**";
             if (activeItalic && !hasItalic)
@@ -201,6 +250,7 @@ async function convertClickUpTextItemsToToolCallResult(textItems) {
             // Update state
             activeBold = hasBold && nextHasBold;
             activeItalic = hasItalic && nextHasItalic;
+            activeStrike = hasStrike && nextHasStrike;
             // Link formatting (wraps everything)
             if (hasLink) {
                 formattedText = `[${formattedText}](${hasLink})`;
@@ -212,6 +262,7 @@ async function convertClickUpTextItemsToToolCallResult(textItems) {
             // Add to current line (not text block yet)
             if (item.text === '\n') {
                 // Plain newline without formatting
+                closeCodeFence();
                 currentTextBlock += currentLine + '\n';
                 currentLine = "";
             }
@@ -219,12 +270,18 @@ 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);
         }
     }
     // Add any remaining text
+    closeCodeFence();
     if (currentLine) {
         currentTextBlock += currentLine;
     }
@@ -292,9 +349,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
@@ -411,6 +468,22 @@ function buildImageFragment(attachment, 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.
  *
@@ -585,25 +658,119 @@ function walkMdastNodes(nodes, inheritedAttrs, blocks, depth = 0, attachmentsByS
                 // Code block
                 const codeNode = node;
                 if (codeNode.value) {
-                    blocks.push({ text: codeNode.value, attributes: {} });
-                    blocks.push({
-                        text: '\n',
-                        attributes: { 'code-block': { 'code-block': codeNode.lang || 'plain' } }
-                    });
+                    pushCodeBlockLines(blocks, codeNode.value, codeNode.lang || 'plain');
                 }
                 break;
             case 'thematicBreak':
                 // Horizontal rule - just add a line break
                 blocks.push({ text: '\n', attributes: {} });
                 break;
+            case 'table': {
+                // ClickUp comments cannot render tables (there is no table fragment in the
+                // comment format - unknown attributes are stored but render as plain text).
+                // Re-render the table as an aligned pipe table inside a code block so the
+                // information survives and stays readable in monospace.
+                const tableText = serializeTableAsAlignedPipes(node);
+                if (tableText) {
+                    pushCodeBlockLines(blocks, tableText, 'plain');
+                }
+                break;
+            }
             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, attachmentsBySrc);
                 }
+                else if ('value' in node && typeof node.value === 'string') {
+                    // Last-resort safety net: never drop text content silently
+                    blocks.push({ text: node.value, attributes: {} });
+                }
+                break;
+        }
+    }
+}
+/**
+ * Emit a (possibly multi-line) code block the way ClickUp's Quill-based format
+ * expects it: block attributes apply per line, so EVERY line needs its own '\n'
+ * fragment carrying the code-block attribute. A single text fragment with embedded
+ * newlines renders only its last line as code - the rest degrades to plain text.
+ */
+function pushCodeBlockLines(blocks, code, lang) {
+    for (const line of code.split('\n')) {
+        if (line) {
+            blocks.push({ text: line, attributes: {} });
+        }
+        blocks.push({
+            text: '\n',
+            attributes: { 'code-block': { 'code-block': lang } }
+        });
+    }
+}
+/**
+ * Serialize phrasing content back to compact markdown for use inside a code block.
+ * Inline formatting markers are kept so nothing is lost, even though a code block
+ * renders them literally.
+ */
+function serializePhrasingToMarkdown(nodes) {
+    let out = '';
+    for (const node of nodes) {
+        switch (node.type) {
+            case 'text':
+                out += node.value;
+                break;
+            case 'strong':
+                out += `**${serializePhrasingToMarkdown(node.children)}**`;
+                break;
+            case 'emphasis':
+                out += `*${serializePhrasingToMarkdown(node.children)}*`;
+                break;
+            case 'delete':
+                out += `~~${serializePhrasingToMarkdown(node.children)}~~`;
+                break;
+            case 'inlineCode':
+                out += `\`${node.value}\``;
+                break;
+            case 'link':
+                out += `[${serializePhrasingToMarkdown(node.children)}](${node.url})`;
+                break;
+            case 'image':
+                out += node.alt || node.url;
+                break;
+            case 'break':
+                out += ' ';
+                break;
+            default:
+                if ('value' in node && typeof node.value === 'string') {
+                    out += node.value;
+                }
+                else if ('children' in node && Array.isArray(node.children)) {
+                    out += serializePhrasingToMarkdown(node.children);
+                }
                 break;
         }
     }
+    return out;
+}
+/**
+ * Render an mdast table as a column-aligned pipe table string.
+ */
+function serializeTableAsAlignedPipes(table) {
+    const rows = table.children.map((row) => row.children.map((cell) => serializePhrasingToMarkdown(cell.children).replace(/\|/g, '\\|').trim()));
+    if (rows.length === 0) {
+        return '';
+    }
+    const colCount = Math.max(...rows.map((r) => r.length));
+    const widths = [];
+    for (let col = 0; col < colCount; col++) {
+        widths[col] = Math.max(3, ...rows.map((r) => (r[col] ?? '').length));
+    }
+    const renderRow = (cells) => '| ' + widths.map((w, col) => (cells[col] ?? '').padEnd(w)).join(' | ') + ' |';
+    const lines = [renderRow(rows[0])];
+    lines.push('| ' + widths.map((w) => '-'.repeat(w)).join(' | ') + ' |');
+    for (const row of rows.slice(1)) {
+        lines.push(renderRow(row));
+    }
+    return lines.join('\n');
 }
 /**
  * Recursively walk phrasing content (inline nodes) and build ClickUp blocks
@@ -652,6 +819,11 @@ function walkPhrasingContent(nodes, inheritedAttrs, blocks, attachmentsBySrc) {
                 currentAttrs.italic = true;
                 walkPhrasingContent(node.children, currentAttrs, blocks, attachmentsBySrc);
                 break;
+            case 'delete':
+                // GFM strikethrough (~~text~~) - ClickUp renders this via the strike attribute
+                currentAttrs.strike = true;
+                walkPhrasingContent(node.children, currentAttrs, blocks, attachmentsBySrc);
+                break;
             case 'inlineCode':
                 // Inline code
                 if (node.value) {
@@ -662,11 +834,20 @@ function walkPhrasingContent(nodes, inheritedAttrs, blocks, attachmentsBySrc) {
                     });
                 }
                 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, attachmentsBySrc);
                 break;
+            }
             case 'break':
                 // Line break - add as plain text
                 blocks.push({ text: '\n', attributes: {} });

package/dist/shared/attachments.d.ts

@@ -61,31 +61,52 @@ export declare function captionToFilename(caption: string, fallbackName: 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 {
+/** 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;
-    /** Attachment to embed, or null when the upload failed */
-    attachment: ClickUpUploadedAttachment | null;
-    /** Reason the upload failed, for reporting back to the caller */
-    error?: string;
+    alt: string;
+    resolved: ResolvedImageSource;
+}
+/** One markdown image reference that could not be used, and why */
+export interface ImageFailure {
+    src: string;
+    error: string;
 }
 /**
- * Upload every image referenced in the markdown to the given task.
+ * Phase 1 of attaching images: resolve every source without writing anything.
  *
- * 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.
+ * 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 uploadMarkdownImages(taskId: string, images: {
+export declare function resolveMarkdownImages(images: {
     src: string;
     alt: string;
-}[], baseDir?: string): Promise<ImageUploadResult[]>;
+}[], baseDir?: string): Promise<{
+    resolved: ResolvedMarkdownImage[];
+    failures: ImageFailure[];
+}>;
+/** A successfully uploaded (or reused) attachment for one markdown source */
+export interface UploadedMarkdownImage {
+    src: string;
+    attachment: ClickUpUploadedAttachment;
+}
 /**
- * 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.
+ * 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 toAttachmentMap(results: ImageUploadResult[]): Map<string, ClickUpUploadedAttachment>;
+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

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

@@ -1 +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"}
+{"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,2FAA2F;AAC3F,MAAM,WAAW,qBAAqB;IACpC,oDAAoD;IACpD,GAAG,EAAE,MAAM,CAAC;IACZ,GAAG,EAAE,MAAM,CAAC;IACZ,QAAQ,EAAE,mBAAmB,CAAC;CAC/B;AAED,mEAAmE;AACnE,MAAM,WAAW,YAAY;IAC3B,GAAG,EAAE,MAAM,CAAC;IACZ,KAAK,EAAE,MAAM,CAAC;CACf;AAED;;;;;;;GAOG;AACH,wBAAsB,qBAAqB,CACzC,MAAM,EAAE;IAAE,GAAG,EAAE,MAAM,CAAC;IAAC,GAAG,EAAE,MAAM,CAAA;CAAE,EAAE,EACtC,OAAO,GAAE,MAAsB,GAC9B,OAAO,CAAC;IAAE,QAAQ,EAAE,qBAAqB,EAAE,CAAC;IAAC,QAAQ,EAAE,YAAY,EAAE,CAAA;CAAE,CAAC,CAqB1E;AAED,6EAA6E;AAC7E,MAAM,WAAW,qBAAqB;IACpC,GAAG,EAAE,MAAM,CAAC;IACZ,UAAU,EAAE,yBAAyB,CAAC;CACvC;AAED;;;;;;;;GAQG;AACH,wBAAsB,oBAAoB,CACxC,MAAM,EAAE,MAAM,EACd,MAAM,EAAE,qBAAqB,EAAE,GAC9B,OAAO,CAAC;IAAE,QAAQ,EAAE,qBAAqB,EAAE,CAAC;IAAC,OAAO,EAAE,YAAY,GAAG,IAAI,CAAA;CAAE,CAAC,CAwC9E;AAED,gFAAgF;AAChF,wBAAgB,eAAe,CAC7B,QAAQ,EAAE,qBAAqB,EAAE,GAChC,GAAG,CAAC,MAAM,EAAE,yBAAyB,CAAC,CAMxC"}

package/dist/shared/attachments.js

@@ -4,7 +4,8 @@ exports.isClickUpAttachmentUrl = isClickUpAttachmentUrl;
 exports.resolveImageSource = resolveImageSource;
 exports.captionToFilename = captionToFilename;
 exports.uploadTaskAttachment = uploadTaskAttachment;
-exports.uploadMarkdownImages = uploadMarkdownImages;
+exports.resolveMarkdownImages = resolveMarkdownImages;
+exports.uploadResolvedImages = uploadResolvedImages;
 exports.toAttachmentMap = toAttachmentMap;
 const buffer_1 = require("buffer");
 const crypto_1 = require("crypto");
@@ -185,31 +186,51 @@ async function uploadTaskAttachment(taskId, filename, bytes, mimeType) {
     return attachment;
 }
 /**
- * Upload every image referenced in the markdown to the given task.
+ * Phase 1 of attaching images: resolve every source without writing anything.
  *
- * 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.
+ * 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.
  */
-async function uploadMarkdownImages(taskId, images, baseDir = process.cwd()) {
-    const results = [];
-    // Identical sources are uploaded once and reused.
-    const seen = new Map();
+async function resolveMarkdownImages(images, baseDir = process.cwd()) {
+    const resolved = [];
+    const failures = [];
+    const seen = new Set();
     for (const { src, alt } of images) {
-        const cached = seen.get(src);
-        if (cached) {
-            results.push(cached);
+        if (seen.has(src)) {
             continue;
         }
-        let result;
+        seen.add(src);
+        try {
+            resolved.push({ src, alt, resolved: await resolveImageSource(src, baseDir) });
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : "unknown error";
+            console.error(`Cannot use image "${src}": ${message}`);
+            failures.push({ src, error: message });
+        }
+    }
+    return { resolved, failures };
+}
+/**
+ * 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.
+ */
+async function uploadResolvedImages(taskId, images) {
+    const uploaded = [];
+    for (const { src, alt, resolved } of images) {
         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 = {
+                uploaded.push({
                     src,
                     attachment: {
                         id: name,
@@ -221,34 +242,27 @@ async function uploadMarkdownImages(taskId, images, baseDir = process.cwd()) {
                         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 };
+                uploaded.push({ 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 };
+            return { uploaded, failure: { src, error: message } };
         }
-        seen.set(src, result);
-        results.push(result);
     }
-    return results;
+    return { uploaded, failure: null };
 }
-/**
- * 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) {
+/** Map from markdown `src` to the attachment that should be embedded for it. */
+function toAttachmentMap(uploaded) {
     const map = new Map();
-    for (const result of results) {
-        if (result.attachment) {
-            map.set(result.src, result.attachment);
-        }
+    for (const { src, attachment } of uploaded) {
+        map.set(src, attachment);
     }
     return map;
 }

package/dist/shared/config.d.ts

@@ -6,6 +6,7 @@ export declare const CONFIG: {
     maxImages: number;
     maxResponseSizeMB: number;
     maxUploadSizeMB: number;
+    commentEditWindowHours: 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;;;;;;;;CAWlB,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;AA8CxD,eAAO,MAAM,MAAM;;;;;;;;;CAqBlB,CAAC"}

package/dist/shared/config.js

@@ -48,6 +48,36 @@ if (rawMode === 'read-minimal' || rawMode === 'read') {
 else if (rawMode && rawMode !== 'write') {
     console.error(`Invalid CLICKUP_MCP_MODE "${rawMode}". Using default "write". Valid options: read-minimal, read, write`);
 }
+/**
+ * Numeric settings are exposed as optional MCPB user_config fields, so their env
+ * values can arrive blank or - if the host does not substitute an unset optional
+ * field - as the literal `${user_config.x}` placeholder. Both mean "not configured"
+ * and must fall back to the default rather than fail or turn into NaN.
+ */
+function readOptionalEnv(name) {
+    const raw = process.env[name]?.trim();
+    if (!raw || /^\$\{.*}$/.test(raw)) {
+        return undefined;
+    }
+    return raw;
+}
+/**
+ * A typo must not silently change a limit: `parseFloat("Infinity")` would disable
+ * the comment age check altogether and `parseFloat("abc")` would yield NaN, which
+ * compares false against every size and so lifts the upload limit instead of
+ * enforcing it. Fail at startup instead.
+ */
+function parseNumericEnv(name, fallback, { min, expectation }) {
+    const raw = readOptionalEnv(name);
+    if (raw === undefined) {
+        return fallback;
+    }
+    const value = Number(raw);
+    if (!Number.isFinite(value) || value < min) {
+        throw new Error(`Invalid ${name} "${raw}". ${expectation}`);
+    }
+    return value;
+}
 exports.CONFIG = {
     apiKey: process.env.CLICKUP_API_KEY,
     teamId: process.env.CLICKUP_TEAM_ID,
@@ -56,7 +86,17 @@ exports.CONFIG = {
     // 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,
+    maxUploadSizeMB: parseNumericEnv("MAX_UPLOAD_SIZE_MB", 10, {
+        min: 1,
+        expectation: "Expected a positive number of megabytes.",
+    }),
+    // How long after creation a comment may still be edited. ClickUp has no way to tell
+    // "written by this MCP" apart from "written by the token owner in the UI", so this
+    // window is the actual guard against rewriting history. 0 disables editing entirely.
+    commentEditWindowHours: parseNumericEnv("CLICKUP_COMMENT_EDIT_WINDOW_HOURS", 24, {
+        min: 0,
+        expectation: "Expected a non-negative number of hours (0 disables editComment).",
+    }),
     primaryLanguageHint: detectedLanguageHint, // Store the cleaned code directly
     mode: mcpMode,
 };

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;AAgGpE,wBAAgB,sBAAsB,CAAC,MAAM,EAAE,SAAS,EAAE,QAAQ,EAAE,GAAG,QA+ctE"}
+{"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;AA+IpE,wBAAgB,sBAAsB,CAAC,MAAM,EAAE,SAAS,EAAE,QAAQ,EAAE,GAAG,QAumBtE"}

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

@@ -10,6 +10,14 @@ 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.
  */
+/**
+ * Shared wording for what markdown ClickUp comments can actually render.
+ * Kept in one place so addComment and editComment stay consistent.
+ */
+const COMMENT_FORMATTING_HINT = [
+    "FORMATTING: Headings, **bold**, *italic*, ~~strikethrough~~, `inline code`, code blocks, links, blockquotes, bullet/numbered/nested lists and checkboxes (- [ ] / - [x]) all render natively.",
+    "TABLES ARE NOT SUPPORTED by ClickUp comments - a markdown table is automatically converted to a monospace code block, which is readable but plain. Prefer bold labels or lists over tables when writing comments.",
+].join("\n");
 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.",
@@ -17,25 +25,57 @@ const IMAGE_SUPPORT_HINT = [
     "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.
+ * Phase 1 of image handling: parse the markdown and resolve every image source
+ * (read files, download URLs, decode data URIs) WITHOUT writing anything.
+ *
+ * Throws when any reference is unusable, listing every broken source at once.
+ * Nothing has been posted to ClickUp when this throws, so the caller's generic
+ * error path returns the report and the client can fix the markdown and retry.
  */
-async function prepareMarkdownImages(taskId, markdown) {
+async function resolveImagesOrAbort(markdown, abortNotice) {
     if (!markdown) {
-        return { results: [], failures: [], markdown: markdown ?? "" };
+        return { markdown: markdown ?? "", images: [] };
     }
     // 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 };
+        return { markdown: normalized, images: [] };
+    }
+    const { resolved, failures } = await (0, attachments_1.resolveMarkdownImages)(sources);
+    if (failures.length > 0) {
+        throw new Error([
+            `${failures.length} image reference(s) could not be used, so ${abortNotice}:`,
+            ...failures.map((failure) => `  - ${failure.src}: ${failure.error}`),
+            `Fix or remove these image references and retry.`,
+        ].join("\n"));
+    }
+    return { markdown: normalized, images: resolved };
+}
+/**
+ * Phase 2: upload the resolved images to the task.
+ *
+ * Throws on the first upload failure. Everything uploaded before the failure is
+ * listed with its CDN URL so a retry can reference those URLs directly (existing
+ * ClickUp URLs are embedded without re-uploading).
+ */
+async function uploadImagesOrAbort(taskId, images, abortNotice) {
+    if (images.length === 0) {
+        return [];
+    }
+    const { uploaded, failure } = await (0, attachments_1.uploadResolvedImages)(taskId, images);
+    if (failure) {
+        const lines = [
+            `Uploading image "${failure.src}" failed, so ${abortNotice}:`,
+            `  ${failure.error}`,
+        ];
+        if (uploaded.length > 0) {
+            lines.push(`${uploaded.length} image(s) were already uploaded to task ${taskId} before the failure - on retry, reference these URLs directly to avoid duplicate uploads:`, ...uploaded.map((u) => `  - ${u.attachment.name}: ${u.attachment.url}`));
+        }
+        throw new Error(lines.join("\n"));
     }
-    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 };
+    return uploaded;
 }
 /**
  * Echo a markdown field back without repeating inline base64 payloads.
@@ -45,25 +85,14 @@ async function prepareMarkdownImages(taskId, markdown) {
 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) {
+/** Report successfully attached images so the caller can verify and link to them */
+function formatAttachedImages(uploaded) {
+    if (uploaded.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}`),
+        `images_attached: ${uploaded.length}`,
+        ...uploaded.map((u) => `  - ${u.attachment.name} (${u.attachment.url})`),
     ];
 }
 // Shared schemas for task parameters
@@ -79,9 +108,11 @@ function registerTaskToolsWrite(server, userData) {
             "Adds a comment to a specific task.",
             "LINKING BEST PRACTICES:",
             "- Always reference related tasks using ClickUp URLs (https://app.clickup.com/t/TASK_ID)",
+            "- Task URLs become live task references (chip with task name and status), so write them bare - any custom link text on a task URL is replaced by the live task name",
             "- 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.",
+            COMMENT_FORMATTING_HINT,
             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.",
@@ -100,11 +131,15 @@ 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);
+            // Resolve and upload referenced images first - the fragments need the
+            // attachment objects from the upload response, a bare URL renders as an
+            // empty tile. Any image problem aborts BEFORE the comment is posted, so
+            // the caller can fix the markdown and retry without creating duplicates.
+            const abortNotice = "the comment was NOT posted";
+            const { markdown, images } = await resolveImagesOrAbort(comment, abortNotice);
+            const uploaded = await uploadImagesOrAbort(task_id, images, abortNotice);
             // Convert markdown to ClickUp formatted blocks
-            const commentBlocks = (0, clickup_text_1.convertMarkdownToClickUpBlocks)(markdown, (0, attachments_1.toAttachmentMap)(results));
+            const commentBlocks = (0, clickup_text_1.convertMarkdownToClickUpBlocks)(markdown, (0, attachments_1.toAttachmentMap)(uploaded));
             const requestBody = {
                 comment: commentBlocks,
                 notify_all: true
@@ -133,8 +168,7 @@ function registerTaskToolsWrite(server, userData) {
                             `comment: ${summarizeMarkdownForEcho(comment)}`,
                             `date: ${timestampToIso(commentData.date || Date.now())}`,
                             `user: ${commentData.user?.username || 'Current user'}`,
-                            ...formatAttachedImages(results),
-                            ...formatImageFailures(failures),
+                            ...formatAttachedImages(uploaded),
                         ].join('\n')
                     }
                 ],
@@ -152,6 +186,89 @@ function registerTaskToolsWrite(server, userData) {
             };
         }
     });
+    server.tool("editComment", (() => {
+        const descriptionBase = [
+            "Replaces the full text of an existing task comment - use this to correct a comment you just posted instead of adding a follow-up comment.",
+            "The new text REPLACES the old one completely, it is not appended. Anything worth keeping must be repeated in `comment`.",
+            `GUARDRAILS: only comments written by the API token's own user can be edited, and only within ${config_1.CONFIG.commentEditWindowHours} hours of their creation. Older comments and other people's comments must be answered with a new comment via addComment.`,
+            "ClickUp shows no 'edited' marker, so people who already read the comment will not notice the change - for anything that changes meaning after a discussion has started, prefer a follow-up comment.",
+            "Editing does not reset the creation date, so the edit window does not get extended by editing.",
+            COMMENT_FORMATTING_HINT,
+            IMAGE_SUPPORT_HINT,
+            "IMAGES ON EDIT: reading a comment (getTaskById) returns its images as markdown, so passing that text back keeps them - an existing ClickUp attachment URL is re-embedded without uploading again. Only an image whose markdown you drop disappears.",
+            "Task URLs (https://app.clickup.com/t/TASK_ID) become live task references, and existing references are read back as such URLs - passing the text back keeps them.",
+        ];
+        if (config_1.CONFIG.primaryLanguageHint && config_1.CONFIG.primaryLanguageHint.toLowerCase() !== 'en') {
+            descriptionBase.splice(1, 0, `For optimal results, consider writing comments in '${config_1.CONFIG.primaryLanguageHint}' unless the task is already in another language.`);
+        }
+        return descriptionBase.join("\n");
+    })(), {
+        task_id: zod_1.z.string().min(6).max(9).describe("The 6-9 character ID of the task the comment belongs to - needed to locate the comment and to upload images"),
+        comment_id: zod_1.z.string().min(1).describe("The ID of the comment to edit, as returned by addComment or getTaskById"),
+        comment: zod_1.z.string().min(1).describe("The new comment text, replacing the previous text completely"),
+    }, {
+        readOnlyHint: false,
+        destructiveHint: true,
+        idempotentHint: true,
+    }, async ({ task_id, comment_id, comment }) => {
+        try {
+            const [existing, userData] = await Promise.all([
+                findTaskComment(task_id, comment_id),
+                (0, utils_1.getCurrentUser)(),
+            ]);
+            assertCommentIsEditable(existing, userData.user.id);
+            // Same pipeline as addComment - the undocumented rich `comment` array is
+            // accepted by PUT too, so formatting and images survive an edit. Images are
+            // resolved and uploaded before the PUT, so a broken reference leaves the
+            // existing comment untouched.
+            const abortNotice = "the comment was NOT changed";
+            const { markdown, images } = await resolveImagesOrAbort(comment, abortNotice);
+            const uploaded = await uploadImagesOrAbort(task_id, images, abortNotice);
+            const commentBlocks = (0, clickup_text_1.convertMarkdownToClickUpBlocks)(markdown, (0, attachments_1.toAttachmentMap)(uploaded));
+            // Only `comment` is sent: sending `comment_text` alongside it appends that
+            // string to the blocks instead of being ignored.
+            const response = await fetch(`https://api.clickup.com/api/v2/comment/${comment_id}`, {
+                method: 'PUT',
+                headers: {
+                    Authorization: config_1.CONFIG.apiKey,
+                    'Content-Type': 'application/json'
+                },
+                body: JSON.stringify({ comment: commentBlocks })
+            });
+            if (!response.ok) {
+                const errorData = await response.json().catch(() => ({}));
+                throw new Error(`Error editing comment: ${response.status} ${response.statusText} - ${JSON.stringify(errorData)}`);
+            }
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: [
+                            `Comment edited successfully!`,
+                            `comment_id: ${comment_id}`,
+                            `task_id: ${task_id}`,
+                            `task_url: https://app.clickup.com/t/${task_id}`,
+                            `created: ${timestampToIso(existing.date)} (unchanged by the edit)`,
+                            `previous_text: ${existing.comment_text || '(no plain text available)'}`,
+                            `new_comment: ${summarizeMarkdownForEcho(comment)}`,
+                            ...formatAttachedImages(uploaded),
+                        ].join('\n')
+                    }
+                ],
+            };
+        }
+        catch (error) {
+            console.error('Error editing comment:', error);
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: `Error editing comment: ${error instanceof Error ? error.message : 'Unknown error'}`,
+                    },
+                ],
+            };
+        }
+    });
     server.tool("updateTask", (() => {
         const descriptionBase = [
             "Updates various aspects of an existing task including dependencies and relationships.",
@@ -200,6 +317,19 @@ function registerTaskToolsWrite(server, userData) {
                 throw new Error(`Error fetching task: ${taskResponse.status} ${taskResponse.statusText}`);
             }
             const taskData = await taskResponse.json();
+            // Resolve and upload description images FIRST - an image problem must
+            // abort before dependencies, tags or the task itself are touched, so the
+            // caller can fix the markdown and retry the whole call cleanly.
+            let appendedDescription;
+            let uploadedImages = [];
+            if (append_description) {
+                const abortNotice = "the task was NOT updated";
+                const prepared = await resolveImagesOrAbort(append_description, abortNotice);
+                uploadedImages = await uploadImagesOrAbort(task_id, prepared.images, abortNotice);
+                // Descriptions render plain markdown, so no image fragments are involved
+                // here - the local paths are simply swapped for the CDN URLs.
+                appendedDescription = (0, clickup_text_1.rewriteMarkdownImageUrls)(prepared.markdown, (0, attachments_1.toAttachmentMap)(uploadedImages));
+            }
             // Handle dependencies separately since they need individual API calls
             let dependencyUpdateResults = [];
             if (blocking !== undefined || waiting_on !== undefined || linked_tasks !== undefined) {
@@ -250,19 +380,11 @@ 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));
+            if (appendedDescription !== undefined) {
                 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}):** ${appended}`;
+                finalDescription = currentDescription + separator + `**Edit (${timestamp}):** ${appendedDescription}`;
             }
             // Build update body without tags (they're handled separately)
             const updateBody = buildTaskRequestBody({
@@ -324,8 +446,7 @@ function registerTaskToolsWrite(server, userData) {
             if (tagUpdateResults.length > 0) {
                 responseLines.push('tag_warnings: ' + tagUpdateResults.join('; '));
             }
-            responseLines.push(...formatAttachedImages(imageResults));
-            responseLines.push(...formatImageFailures(imageFailures));
+            responseLines.push(...formatAttachedImages(uploadedImages));
             return {
                 content: [
                     {
@@ -383,6 +504,11 @@ function registerTaskToolsWrite(server, userData) {
         openWorldHint: true
     }, async ({ list_id, name, description, status, priority, due_date, start_date, time_estimate, tags, parent_task_id, assignees }) => {
         try {
+            // Resolve description images BEFORE creating the task: a broken reference
+            // (missing file, dead URL, non-image) must not leave a half-finished task
+            // behind. Uploading has to wait until the task exists, though - ClickUp
+            // attachments always belong to a task.
+            const { markdown: normalizedDescription, images } = await resolveImagesOrAbort(description, "the task was NOT created");
             const userData = await (0, utils_1.getCurrentUser)();
             const currentUserId = userData.user.id;
             const requestBody = buildTaskRequestBody({
@@ -405,10 +531,40 @@ function registerTaskToolsWrite(server, userData) {
                 throw new Error(`Error creating task: ${response.status} ${response.statusText} - ${JSON.stringify(errorData)}`);
             }
             const createdTask = await response.json();
+            // Tags are omitted from the create body by buildTaskRequestBody because they
+            // need the dedicated tag endpoints, so apply them here - the same way
+            // updateTask does - otherwise the requested tags are silently dropped.
+            const tagCreateResults = [];
+            if (tags !== undefined && tags.length > 0) {
+                for (const tagName of tags) {
+                    try {
+                        const addTagResponse = await fetch(`https://api.clickup.com/api/v2/task/${createdTask.id}/tag/${encodeURIComponent(tagName)}`, {
+                            method: 'POST',
+                            headers: { Authorization: config_1.CONFIG.apiKey }
+                        });
+                        if (!addTagResponse.ok) {
+                            console.error(`Failed to add tag "${tagName}": ${addTagResponse.status}`);
+                            tagCreateResults.push(`Failed to add tag: ${tagName}`);
+                        }
+                    }
+                    catch (error) {
+                        console.error(`Error adding tag "${tagName}":`, error);
+                        tagCreateResults.push(`Error adding tag: ${tagName}`);
+                    }
+                }
+            }
             // 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);
+            // At this point every source resolved successfully - only the upload API
+            // itself can still fail, and then the task already exists, so that is
+            // reported as a warning instead of pretending the task was not created.
+            const imageWarnings = [];
+            const { uploaded, failure: uploadFailure } = await (0, attachments_1.uploadResolvedImages)(createdTask.id, images);
+            if (uploadFailure) {
+                console.error(`Failed to attach image "${uploadFailure.src}": ${uploadFailure.error}`);
+                imageWarnings.push(`WARNING: the task was created, but uploading image "${uploadFailure.src}" failed: ${uploadFailure.error}`, `The description still references the original image source. Fix the problem and add the image via updateTask.`);
+            }
+            const attachmentMap = (0, attachments_1.toAttachmentMap)(uploaded);
             if (description && attachmentMap.size > 0) {
                 const rewritten = (0, clickup_text_1.rewriteMarkdownImageUrls)(normalizedDescription, attachmentMap);
                 if (rewritten !== description) {
@@ -423,15 +579,18 @@ function registerTaskToolsWrite(server, userData) {
                     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`);
+                        imageWarnings.push(`WARNING: description update failed (${descriptionResponse.status} ${descriptionResponse.statusText}) - the images are attached to the task but not embedded in the description`);
                     }
                 }
             }
             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));
+            responseLines.push(...formatAttachedImages(uploaded));
+            responseLines.push(...imageWarnings);
+            if (tagCreateResults.length > 0) {
+                responseLines.push('tag_warnings: ' + tagCreateResults.join('; '));
+            }
             return {
                 content: [
                     {
@@ -477,6 +636,93 @@ function formatTimeEstimate(hours) {
     const displayMinutes = Math.round((hours - displayHours) * 60);
     return displayHours > 0 ? `${displayHours}h ${displayMinutes}m` : `${displayMinutes}m`;
 }
+/**
+ * Never page further back than this. A generous edit window would otherwise walk
+ * the entire comment history of a busy ticket and eat the 100 calls/minute budget.
+ */
+const MAX_COMMENT_PAGES = 10;
+/** One page of task comments, newest first, 25 per page */
+async function fetchCommentPage(taskId, cursor) {
+    // Note there is no `start_date` parameter - passing one is silently ignored.
+    // Older pages are reached with `start` + `start_id` of the previous page's last entry.
+    const query = cursor
+        ? `?${new URLSearchParams({ start: cursor.start, start_id: cursor.startId })}`
+        : "";
+    const response = await fetch(`https://api.clickup.com/api/v2/task/${taskId}/comment${query}`, { headers: { Authorization: config_1.CONFIG.apiKey } });
+    if (!response.ok) {
+        const errorData = await response.json().catch(() => ({}));
+        throw new Error(`Error loading comments of task ${taskId}: ${response.status} ${response.statusText} - ${JSON.stringify(errorData)}`);
+    }
+    const data = await response.json();
+    return Array.isArray(data.comments) ? data.comments : [];
+}
+/**
+ * Load a single comment of a task.
+ *
+ * ClickUp has no `GET /comment/{id}`, so the task's comment list is the only way
+ * to learn a comment's author and age - both of which editComment has to check
+ * before touching anything.
+ *
+ * The list returns the 25 newest comments per page, so a busy ticket needs paging
+ * to reach the wanted comment. Paging stops as soon as a page ends outside the edit
+ * window: everything older would be refused anyway, which keeps this to a single
+ * request in the normal case.
+ *
+ * Note the list only contains top-level comments; replies inside a thread live
+ * behind `/comment/{parent_id}/reply` and are therefore not editable here.
+ */
+async function findTaskComment(taskId, commentId) {
+    const oldestEditableDate = Date.now() - config_1.CONFIG.commentEditWindowHours * 60 * 60 * 1000;
+    let cursor;
+    let checked = 0;
+    let pages = 0;
+    let sawThreadedReplies = false;
+    while (pages < MAX_COMMENT_PAGES) {
+        const page = await fetchCommentPage(taskId, cursor);
+        pages++;
+        if (page.length === 0) {
+            break;
+        }
+        const match = page.find((entry) => String(entry.id) === String(commentId));
+        if (match) {
+            return match;
+        }
+        checked += page.length;
+        sawThreadedReplies || (sawThreadedReplies = page.some((entry) => (entry.reply_count ?? 0) > 0));
+        // Comments come back newest first, so once a page runs past the edit window
+        // there is nothing editable further back.
+        const oldest = page[page.length - 1];
+        if (Number(oldest.date) < oldestEditableDate) {
+            break;
+        }
+        cursor = { start: String(oldest.date), startId: String(oldest.id) };
+    }
+    const threadedHint = sawThreadedReplies
+        ? " This task has threaded replies, and replies inside a thread cannot be edited - answer them with a new comment instead."
+        : "";
+    throw new Error(`Comment ${commentId} was not found on task ${taskId} (${checked} top-level comment(s) checked across ${pages} page(s), newest first).${threadedHint}`);
+}
+/**
+ * The whole safety model of editComment.
+ *
+ * ClickUp cannot tell "written through this MCP" from "written by the token owner
+ * in the web UI" - both carry the same user id - so the author check only keeps
+ * other people's comments safe, and the time window is what keeps the tool from
+ * rewriting history.
+ */
+function assertCommentIsEditable(comment, currentUserId) {
+    const windowHours = config_1.CONFIG.commentEditWindowHours;
+    if (!(windowHours > 0)) {
+        throw new Error(`Editing comments is disabled (CLICKUP_COMMENT_EDIT_WINDOW_HOURS=${windowHours}). Add a new comment instead.`);
+    }
+    if (String(comment.user?.id ?? '') !== String(currentUserId)) {
+        throw new Error(`Comment ${comment.id} was written by ${comment.user?.username || 'someone else'} (user_id: ${comment.user?.id ?? 'unknown'}), not by the current user (user_id: ${currentUserId}). Only your own comments can be edited - reply with a new comment instead.`);
+    }
+    const ageHours = (Date.now() - Number(comment.date)) / (1000 * 60 * 60);
+    if (ageHours > windowHours) {
+        throw new Error(`Comment ${comment.id} was created ${ageHours.toFixed(1)} hours ago (${timestampToIso(comment.date)}), which is outside the ${windowHours} hour edit window. Add a new comment instead of rewriting an old one.`);
+    }
+}
 /**
  * Formats timestamp to ISO string with local timezone (not UTC)
  */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hauptsache.net/clickup-mcp",
-  "version": "1.7.0",
+  "version": "1.7.2",
   "description": "Search, create, and retrieve tasks, add comments, and track time through natural language commands.",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",