@hauptsache.net/clickup-mcp 1.7.3 → 1.9.0

package/README.md

@@ -78,7 +78,7 @@ Turn natural language into powerful ClickUp actions:
 - Filter by assignees, projects, status, and metadata
 
 ### 💬 **Complete Context**
-- Full comment histories and team discussions
+- Comment histories and team discussions (up to 250 top-level comments), including threaded comment replies
 - Task descriptions with embedded images  
 - List descriptions and project guidelines
 - Document content with page navigation
@@ -186,10 +186,10 @@ The ClickUp MCP supports three operational modes to balance functionality, secur
 
 | Tool                   | read-minimal | read | write | Description                                                                             |
 |------------------------|:------------:|:----:|:-----:|-----------------------------------------------------------------------------------------|
-| `getTaskById`          |      ✅       |  ✅   |   ✅   | Get complete task details including comments, images, and metadata                      |
-| `addComment`           |      ❌       |  ❌   |   ✅   | Add comments to tasks for collaboration                                                 |
+| `getTaskById`          |      ✅       |  ✅   |   ✅   | Get complete task details including comments (with threaded replies), images, and metadata |
+| `addComment`           |      ❌       |  ❌   |   ✅   | Add comments to tasks, or reply inside a comment thread via `parent_comment_id`         |
 | `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 |
+| `updateTask`           |      ❌       |  ❌   |   ✅   | Update tasks (status, priority, assignees, etc.); descriptions can be appended to or replaced entirely |
 | `createTask`           |      ❌       |  ❌   |   ✅   | Create new tasks with full markdown support                                             |
 | `searchTasks`          |      ✅       |  ✅   |   ✅   | Find tasks by content, keywords, assignees, or project context                          |
 | `searchSpaces`         |      ❌       |  ✅   |   ✅   | Browse workspace structure, project organization, and documents                         |

package/dist/clickup-text.js

@@ -595,6 +595,14 @@ function walkMdastNodes(nodes, inheritedAttrs, blocks, depth = 0, attachmentsByS
     for (let i = 0; i < nodes.length; i++) {
         const node = nodes[i];
         const currentAttrs = { ...inheritedAttrs };
+        // ClickUp has no paragraph margins: two paragraphs separated by a single '\n'
+        // render as consecutive lines. The UI stores a paragraph break as an extra
+        // empty '\n' fragment (what a user gets by pressing Enter twice), so emit one
+        // between adjacent flow blocks. Headings, code blocks and blockquotes bring
+        // their own spacing - a blank line next to them would double the gap.
+        if (i > 0 && needsBlankLineBetween(nodes[i - 1], node)) {
+            blocks.push({ text: '\n', attributes: {} });
+        }
         switch (node.type) {
             case 'heading':
                 // Process heading content with inline formatting
@@ -689,6 +697,14 @@ function walkMdastNodes(nodes, inheritedAttrs, blocks, depth = 0, attachmentsByS
         }
     }
 }
+/**
+ * Block types that render without their own vertical margin in ClickUp comments.
+ * Two of them in a row need an explicit empty line to read as separate blocks.
+ */
+const FLOW_BLOCK_TYPES = new Set(['paragraph', 'list']);
+function needsBlankLineBetween(prev, next) {
+    return FLOW_BLOCK_TYPES.has(prev.type) && FLOW_BLOCK_TYPES.has(next.type);
+}
 /**
  * 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'

package/dist/shared/comments.d.ts

@@ -0,0 +1,65 @@
+/** A task comment as returned by GET /api/v2/task/{task_id}/comment or GET /comment/{id}/reply */
+export interface ExistingComment {
+    id: string;
+    date: string;
+    comment?: any[];
+    comment_text?: string;
+    user?: {
+        id?: number | string;
+        username?: string;
+    };
+    reply_count?: number;
+}
+/** Cursor into the comment list: the date and id of the last comment of the previous page */
+export interface CommentPageCursor {
+    start: string;
+    startId: string;
+}
+/**
+ * Never page further back than this. A busy ticket would otherwise walk its
+ * entire comment history and eat the 100 calls/minute budget.
+ */
+export declare const MAX_COMMENT_PAGES = 10;
+/** One page of task comments, newest first, 25 per page */
+export declare function fetchCommentPage(taskId: string, cursor?: CommentPageCursor): Promise<ExistingComment[]>;
+/**
+ * All top-level comments of a task, newest first.
+ *
+ * The comment list endpoint returns 25 comments per page, so longer histories are
+ * paged with `start`/`start_id`. Paging is capped at MAX_COMMENT_PAGES (250 comments)
+ * to protect the API budget; hitting the cap is logged instead of failing.
+ */
+export declare function fetchAllTopLevelComments(taskId: string): Promise<ExistingComment[]>;
+/**
+ * Find a top-level comment of a task by id, paging as far as MAX_COMMENT_PAGES.
+ *
+ * Unlike editComment's lookup this does not stop at the edit window, because a
+ * thread parent can be arbitrarily old. Returns undefined when the id is not a
+ * top-level comment of this task - which also catches reply ids, since replies
+ * never appear in the task's comment list.
+ */
+export declare function findTopLevelComment(taskId: string, commentId: string): Promise<ExistingComment | undefined>;
+/**
+ * The replies inside a comment thread, oldest first.
+ *
+ * `GET /task/{id}/comment` only returns top-level comments; the replies of a
+ * thread (Threaded Comments ClickApp) live behind `GET /comment/{id}/reply`.
+ * Any failure (non-ok response, network error, malformed body) is logged and
+ * returns an empty array so one broken thread does not take down the whole
+ * task view.
+ */
+export declare function fetchCommentReplies(commentId: string): Promise<ExistingComment[]>;
+/**
+ * Never fetch more threads than this per task read, and never more than a few
+ * at once - together with MAX_COMMENT_PAGES this keeps a single getTaskById
+ * within ClickUp's 100 calls/minute budget even on a heavily threaded task.
+ */
+export declare const MAX_REPLY_FETCHES = 30;
+/**
+ * Fetch the replies of every comment with reply_count > 0, bounded in count and
+ * concurrency. Returns a map of comment id -> replies; a thread that was skipped
+ * (over the cap) or failed to load is simply absent or empty, so callers can
+ * render a "replies not loaded" hint from reply_count.
+ */
+export declare function fetchRepliesByComment(comments: ExistingComment[]): Promise<Map<string, ExistingComment[]>>;
+//# sourceMappingURL=comments.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"comments.d.ts","sourceRoot":"","sources":["../../src/shared/comments.ts"],"names":[],"mappings":"AAEA,kGAAkG;AAClG,MAAM,WAAW,eAAe;IAC9B,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,CAAC,EAAE,GAAG,EAAE,CAAC;IAChB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,IAAI,CAAC,EAAE;QAAE,EAAE,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;QAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IACnD,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED,6FAA6F;AAC7F,MAAM,WAAW,iBAAiB;IAChC,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,MAAM,CAAC;CACjB;AAED;;;GAGG;AACH,eAAO,MAAM,iBAAiB,KAAK,CAAC;AAKpC,2DAA2D;AAC3D,wBAAsB,gBAAgB,CACpC,MAAM,EAAE,MAAM,EACd,MAAM,CAAC,EAAE,iBAAiB,GACzB,OAAO,CAAC,eAAe,EAAE,CAAC,CAqB5B;AAED;;;;;;GAMG;AACH,wBAAsB,wBAAwB,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,eAAe,EAAE,CAAC,CA+BzF;AAED;;;;;;;GAOG;AACH,wBAAsB,mBAAmB,CACvC,MAAM,EAAE,MAAM,EACd,SAAS,EAAE,MAAM,GAChB,OAAO,CAAC,eAAe,GAAG,SAAS,CAAC,CAiBtC;AAED;;;;;;;;GAQG;AACH,wBAAsB,mBAAmB,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,eAAe,EAAE,CAAC,CAsBvF;AAED;;;;GAIG;AACH,eAAO,MAAM,iBAAiB,KAAK,CAAC;AAGpC;;;;;GAKG;AACH,wBAAsB,qBAAqB,CACzC,QAAQ,EAAE,eAAe,EAAE,GAC1B,OAAO,CAAC,GAAG,CAAC,MAAM,EAAE,eAAe,EAAE,CAAC,CAAC,CAsBzC"}

package/dist/shared/comments.js

@@ -0,0 +1,143 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MAX_REPLY_FETCHES = exports.MAX_COMMENT_PAGES = void 0;
+exports.fetchCommentPage = fetchCommentPage;
+exports.fetchAllTopLevelComments = fetchAllTopLevelComments;
+exports.findTopLevelComment = findTopLevelComment;
+exports.fetchCommentReplies = fetchCommentReplies;
+exports.fetchRepliesByComment = fetchRepliesByComment;
+const config_1 = require("./config");
+/**
+ * Never page further back than this. A busy ticket would otherwise walk its
+ * entire comment history and eat the 100 calls/minute budget.
+ */
+exports.MAX_COMMENT_PAGES = 10;
+/** Page size ClickUp uses for the comment list - a shorter page means the last page. */
+const COMMENTS_PER_PAGE = 25;
+/** 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 : [];
+}
+/**
+ * All top-level comments of a task, newest first.
+ *
+ * The comment list endpoint returns 25 comments per page, so longer histories are
+ * paged with `start`/`start_id`. Paging is capped at MAX_COMMENT_PAGES (250 comments)
+ * to protect the API budget; hitting the cap is logged instead of failing.
+ */
+async function fetchAllTopLevelComments(taskId) {
+    const comments = [];
+    let cursor;
+    let pages = 0;
+    let lastPageWasFull = false;
+    while (pages < exports.MAX_COMMENT_PAGES) {
+        const page = await fetchCommentPage(taskId, cursor);
+        pages++;
+        if (page.length === 0) {
+            lastPageWasFull = false;
+            break;
+        }
+        comments.push(...page);
+        lastPageWasFull = page.length >= COMMENTS_PER_PAGE;
+        if (!lastPageWasFull) {
+            break;
+        }
+        const oldest = page[page.length - 1];
+        cursor = { start: String(oldest.date), startId: String(oldest.id) };
+    }
+    if (lastPageWasFull && pages >= exports.MAX_COMMENT_PAGES) {
+        console.error(`Task ${taskId} has more than ${comments.length} top-level comments - older comments were not loaded (capped at ${exports.MAX_COMMENT_PAGES} pages).`);
+    }
+    return comments;
+}
+/**
+ * Find a top-level comment of a task by id, paging as far as MAX_COMMENT_PAGES.
+ *
+ * Unlike editComment's lookup this does not stop at the edit window, because a
+ * thread parent can be arbitrarily old. Returns undefined when the id is not a
+ * top-level comment of this task - which also catches reply ids, since replies
+ * never appear in the task's comment list.
+ */
+async function findTopLevelComment(taskId, commentId) {
+    let cursor;
+    for (let pages = 0; pages < exports.MAX_COMMENT_PAGES; pages++) {
+        const page = await fetchCommentPage(taskId, cursor);
+        const match = page.find((entry) => String(entry.id) === String(commentId));
+        if (match) {
+            return match;
+        }
+        if (page.length < COMMENTS_PER_PAGE) {
+            return undefined;
+        }
+        const oldest = page[page.length - 1];
+        cursor = { start: String(oldest.date), startId: String(oldest.id) };
+    }
+    return undefined;
+}
+/**
+ * The replies inside a comment thread, oldest first.
+ *
+ * `GET /task/{id}/comment` only returns top-level comments; the replies of a
+ * thread (Threaded Comments ClickApp) live behind `GET /comment/{id}/reply`.
+ * Any failure (non-ok response, network error, malformed body) is logged and
+ * returns an empty array so one broken thread does not take down the whole
+ * task view.
+ */
+async function fetchCommentReplies(commentId) {
+    try {
+        const response = await fetch(`https://api.clickup.com/api/v2/comment/${commentId}/reply`, { headers: { Authorization: config_1.CONFIG.apiKey } });
+        if (!response.ok) {
+            const errorData = await response.json().catch(() => ({}));
+            console.error(`Error fetching replies for comment ${commentId}: ${response.status} ${response.statusText} - ${JSON.stringify(errorData)}`);
+            return [];
+        }
+        const data = await response.json();
+        const replies = Array.isArray(data?.comments) ? data.comments : [];
+        return replies.sort((a, b) => Number(a.date) - Number(b.date));
+    }
+    catch (error) {
+        console.error(`Error fetching replies for comment ${commentId}:`, error);
+        return [];
+    }
+}
+/**
+ * Never fetch more threads than this per task read, and never more than a few
+ * at once - together with MAX_COMMENT_PAGES this keeps a single getTaskById
+ * within ClickUp's 100 calls/minute budget even on a heavily threaded task.
+ */
+exports.MAX_REPLY_FETCHES = 30;
+const REPLY_FETCH_CONCURRENCY = 5;
+/**
+ * Fetch the replies of every comment with reply_count > 0, bounded in count and
+ * concurrency. Returns a map of comment id -> replies; a thread that was skipped
+ * (over the cap) or failed to load is simply absent or empty, so callers can
+ * render a "replies not loaded" hint from reply_count.
+ */
+async function fetchRepliesByComment(comments) {
+    const threaded = comments.filter((comment) => (comment.reply_count ?? 0) > 0);
+    const toFetch = threaded.slice(0, exports.MAX_REPLY_FETCHES);
+    if (threaded.length > toFetch.length) {
+        console.error(`Skipping replies of ${threaded.length - toFetch.length} comment thread(s) - only the ${exports.MAX_REPLY_FETCHES} newest threads are loaded to stay within the API budget.`);
+    }
+    const replies = new Map();
+    let next = 0;
+    const worker = async () => {
+        while (next < toFetch.length) {
+            const comment = toFetch[next++];
+            replies.set(String(comment.id), await fetchCommentReplies(String(comment.id)));
+        }
+    };
+    await Promise.all(Array.from({ length: Math.min(REPLY_FETCH_CONCURRENCY, toFetch.length) }, worker));
+    return replies;
+}

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

@@ -1 +1 @@
-{"version":3,"file":"task-tools.d.ts","sourceRoot":"","sources":["../../src/tools/task-tools.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AAGpE,OAAO,EAAE,YAAY,EAAyC,MAAM,iBAAiB,CAAC;AAOtF,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,SAAS,EAAE,QAAQ,EAAE,GAAG,QA2DrE;AA+MD;;GAEG;AACH,wBAAsB,oBAAoB,CAAC,IAAI,EAAE,GAAG,EAAE,WAAW,CAAC,EAAE,GAAG,EAAE,EAAE,YAAY,GAAE,OAAe,GAAG,OAAO,CAAC,YAAY,CAAC,CAmH/H"}
+{"version":3,"file":"task-tools.d.ts","sourceRoot":"","sources":["../../src/tools/task-tools.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AAGpE,OAAO,EAAE,YAAY,EAAyC,MAAM,iBAAiB,CAAC;AAQtF,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,SAAS,EAAE,QAAQ,EAAE,GAAG,QA2DrE;AA2OD;;GAEG;AACH,wBAAsB,oBAAoB,CAAC,IAAI,EAAE,GAAG,EAAE,WAAW,CAAC,EAAE,GAAG,EAAE,EAAE,YAAY,GAAE,OAAe,GAAG,OAAO,CAAC,YAAY,CAAC,CAgJ/H"}

package/dist/tools/task-tools.js

@@ -7,6 +7,7 @@ const clickup_text_1 = require("../clickup-text");
 const config_1 = require("../shared/config");
 const utils_1 = require("../shared/utils");
 const image_processing_1 = require("../shared/image-processing");
+const comments_1 = require("../shared/comments");
 // Read-specific utility functions
 function registerTaskToolsRead(server, userData) {
     server.tool("getTaskById", [
@@ -98,26 +99,52 @@ async function loadTaskContent(taskId) {
     return [taskMetadata, ...content];
 }
 async function loadTaskComments(id) {
-    const response = await fetch(`https://api.clickup.com/api/v2/task/${id}/comment?start_date=0`, // Ensure all comments are fetched
-    { headers: { Authorization: config_1.CONFIG.apiKey } });
-    if (!response.ok) {
-        console.error(`Error fetching comments for task ${id}: ${response.status} ${response.statusText}`);
-        return [];
+    let comments;
+    try {
+        // The comment list only returns 25 top-level comments per page - page through
+        // all of them (the previous `?start_date=0` was silently ignored by ClickUp).
+        comments = await (0, comments_1.fetchAllTopLevelComments)(id);
     }
-    const commentsData = await response.json();
-    if (!commentsData.comments || !Array.isArray(commentsData.comments)) {
-        console.error(`Unexpected comment data structure for task ${id}`);
+    catch (error) {
+        console.error(`Error fetching comments for task ${id}:`, error);
         return [];
     }
-    const commentEvents = await Promise.all(commentsData.comments.map(async (comment) => {
+    // Replies live behind their own endpoint and are missing from the comment
+    // list. Only threads (reply_count > 0) cost extra requests, bounded in count
+    // and concurrency to protect the API budget.
+    const repliesByComment = await (0, comments_1.fetchRepliesByComment)(comments);
+    const formatUser = (user) => `${user?.username ?? "unknown"} (user_id: ${user?.id ?? "unknown"})`;
+    const commentEvents = await Promise.all(comments.map(async (comment) => {
+        // The comment_id makes the comment addressable for editComment and for
+        // threaded replies via addComment's parent_comment_id.
         const headerBlock = {
             type: "text",
-            text: `Comment by ${comment.user.username} on ${timestampToIso(comment.date)}:`,
+            text: `Comment by ${formatUser(comment.user)} on ${timestampToIso(comment.date)} (comment_id: ${comment.id}):`,
         };
-        const commentBodyBlocks = await (0, clickup_text_1.convertClickUpTextItemsToToolCallResult)(comment.comment);
+        const commentBodyBlocks = await (0, clickup_text_1.convertClickUpTextItemsToToolCallResult)(comment.comment ?? []);
+        const contentBlocks = [headerBlock, ...commentBodyBlocks];
+        const replyCount = comment.reply_count ?? 0;
+        if (replyCount > 0) {
+            const replies = repliesByComment.get(String(comment.id)) ?? [];
+            for (const reply of replies) {
+                contentBlocks.push({
+                    type: "text",
+                    text: `↳ Reply by ${formatUser(reply.user)} on ${timestampToIso(reply.date)} (comment_id: ${reply.id}):`,
+                });
+                contentBlocks.push(...await (0, clickup_text_1.convertClickUpTextItemsToToolCallResult)(reply.comment ?? []));
+            }
+            if (replies.length === 0) {
+                // The thread exists (reply_count says so) but its replies were skipped
+                // over the budget cap or failed to load - never pretend it is empty.
+                contentBlocks.push({
+                    type: "text",
+                    text: `↳ This comment has ${replyCount} repl${replyCount === 1 ? "y" : "ies"} that could not be loaded.`,
+                });
+            }
+        }
         return {
             date: comment.date, // String timestamp from ClickUp for sorting
-            contentBlocks: [headerBlock, ...commentBodyBlocks],
+            contentBlocks,
         };
     }));
     return commentEvents;
@@ -294,6 +321,32 @@ async function generateTaskMetadata(task, timeEntries, isDetailView = false) {
     if (task.subtasks && task.subtasks.length > 0) {
         metadataLines.push(`child_task_ids: ${task.subtasks.map((st) => st.id).join(', ')}`);
     }
+    // Add dependencies if they exist. The API returns a single flat `dependencies`
+    // array for both directions; which side of the pair this task sits on decides
+    // whether it is waiting on the other task or blocking it.
+    if (task.dependencies && task.dependencies.length > 0) {
+        const waitingOn = task.dependencies
+            .filter((dep) => dep.task_id === task.id)
+            .map((dep) => dep.depends_on);
+        const blocking = task.dependencies
+            .filter((dep) => dep.depends_on === task.id)
+            .map((dep) => dep.task_id);
+        if (waitingOn.length > 0) {
+            metadataLines.push(`waiting_on: ${waitingOn.join(', ')}`);
+        }
+        if (blocking.length > 0) {
+            metadataLines.push(`blocking: ${blocking.join(', ')}`);
+        }
+    }
+    // Add linked (related, non-blocking) tasks if they exist
+    if (task.linked_tasks && task.linked_tasks.length > 0) {
+        const linked = task.linked_tasks
+            .map((link) => (link.task_id === task.id ? link.link_id : link.task_id))
+            .filter((id) => id);
+        if (linked.length > 0) {
+            metadataLines.push(`linked_tasks: ${linked.join(', ')}`);
+        }
+    }
     // Add archived status if true
     if (task.archived) {
         metadataLines.push(`archived: true`);

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

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

@@ -6,6 +6,7 @@ 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");
+const comments_1 = require("../shared/comments");
 /**
  * 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.
@@ -105,7 +106,7 @@ const taskTagsSchema = zod_1.z.array(zod_1.z.string()).optional().describe("Opti
 function registerTaskToolsWrite(server, userData) {
     server.tool("addComment", (() => {
         const descriptionBase = [
-            "Adds a comment to a specific task.",
+            "Adds a comment to a specific task, or a threaded reply to an existing comment when `parent_comment_id` is set.",
             "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",
@@ -125,12 +126,26 @@ function registerTaskToolsWrite(server, userData) {
     })(), {
         task_id: zod_1.z.string().min(6).max(16).describe("The 6-16 character task ID to comment on"),
         comment: zod_1.z.string().min(1).describe("The comment text to add to the task"),
+        parent_comment_id: zod_1.z.string().min(1).optional().describe("Optional: reply inside an existing comment thread instead of posting a new top-level comment. Pass the comment_id of a TOP-LEVEL comment as returned by getTaskById or addComment - ClickUp threads are one level deep, so a reply cannot have replies of its own."),
     }, {
         readOnlyHint: false,
         destructiveHint: false,
         idempotentHint: false,
-    }, async ({ task_id, comment }) => {
+    }, async ({ task_id, comment, parent_comment_id }) => {
         try {
+            // The reply endpoint anchors the reply to the parent comment's task and
+            // ignores task_id, while images below are uploaded to task_id - so the
+            // parent must verifiably be a top-level comment of THIS task before
+            // anything is written. This also rejects reply ids (nested replies are
+            // not supported by ClickUp's one-level threads).
+            if (parent_comment_id) {
+                const parent = await (0, comments_1.findTopLevelComment)(task_id, parent_comment_id);
+                if (!parent) {
+                    throw new Error(`Comment ${parent_comment_id} is not a top-level comment of task ${task_id}, so no reply was posted. ` +
+                        `parent_comment_id must be the comment_id of a top-level comment of this task as returned by getTaskById - ` +
+                        `a reply's id or a comment of another task cannot be used.`);
+                }
+            }
             // 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
@@ -144,7 +159,12 @@ function registerTaskToolsWrite(server, userData) {
                 comment: commentBlocks,
                 notify_all: true
             };
-            const response = await fetch(`https://api.clickup.com/api/v2/task/${task_id}/comment`, {
+            // A threaded reply goes to the parent comment's reply endpoint; the body
+            // is identical to a top-level comment.
+            const url = parent_comment_id
+                ? `https://api.clickup.com/api/v2/comment/${parent_comment_id}/reply`
+                : `https://api.clickup.com/api/v2/task/${task_id}/comment`;
+            const response = await fetch(url, {
                 method: 'POST',
                 headers: {
                     Authorization: config_1.CONFIG.apiKey,
@@ -162,8 +182,12 @@ function registerTaskToolsWrite(server, userData) {
                     {
                         type: "text",
                         text: [
-                            `Comment added successfully!`,
+                            parent_comment_id ? `Reply added successfully!` : `Comment added successfully!`,
                             `comment_id: ${commentData.id || 'N/A'}`,
+                            ...(parent_comment_id ? [
+                                `parent_comment_id: ${parent_comment_id}`,
+                                `note: ClickUp threads are one level deep - a reply's comment_id cannot be used as parent_comment_id or with editComment.`,
+                            ] : []),
                             `task_id: ${task_id}`,
                             `comment: ${summarizeMarkdownForEcho(comment)}`,
                             `date: ${timestampToIso(commentData.date || Date.now())}`,
@@ -204,7 +228,7 @@ function registerTaskToolsWrite(server, userData) {
         return descriptionBase.join("\n");
     })(), {
         task_id: zod_1.z.string().min(6).max(16).describe("The 6-16 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_id: zod_1.z.string().min(1).describe("The ID of the comment to edit, as returned by addComment or getTaskById. Only top-level comments can be edited - replies inside a thread cannot."),
         comment: zod_1.z.string().min(1).describe("The new comment text, replacing the previous text completely"),
     }, {
         readOnlyHint: false,
@@ -274,11 +298,12 @@ function registerTaskToolsWrite(server, userData) {
             "Updates various aspects of an existing task including dependencies and relationships.",
             "ALWAYS include the task URL (https://app.clickup.com/t/TASK_ID) when updating or referencing tasks.",
             "Use getListInfo first to see valid status options.",
-            "SAFETY FEATURE: Description updates are APPEND-ONLY to prevent data loss - existing content is preserved.",
+            "DESCRIPTIONS: `append_description` adds a dated section below the existing text; `description` REPLACES the whole text (use it to restructure, shorten or correct a description). Pass only one of them.",
+            "Before replacing, read the current description via getTaskById and carry over everything that is still needed - ClickUp keeps a description history, so a bad replacement can be restored in the UI (edits within the same minute merge into one version), but the MCP cannot undo it.",
             "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.",
+            "LINKING IN DESCRIPTIONS: Include links to related tasks, lists, or external resources (format: https://app.clickup.com/t/TASK_ID).",
             "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.",
             "Suggest appropriate status transitions and always provide the clickable task URL in responses."
         ];
@@ -289,7 +314,8 @@ function registerTaskToolsWrite(server, userData) {
     })(), {
         task_id: zod_1.z.string().min(6).max(16).describe("The 6-16 character task ID to update"),
         name: taskNameSchema.optional(),
-        append_description: zod_1.z.string().optional().describe("Optional markdown content to APPEND to existing task description (preserves existing content for safety)"),
+        description: zod_1.z.string().optional().describe("Optional markdown that REPLACES the entire task description. Read the current description first (getTaskById) and repeat everything worth keeping - nothing is merged. Cannot be combined with append_description."),
+        append_description: zod_1.z.string().optional().describe("Optional markdown content to APPEND below the existing task description as a dated `**Edit (YYYY-MM-DD):**` section (existing content is preserved). Cannot be combined with description."),
         status: zod_1.z.string().optional().describe("Optional new status name - use getListInfo to see valid options"),
         priority: taskPrioritySchema,
         due_date: taskDueDateSchema,
@@ -306,8 +332,16 @@ function registerTaskToolsWrite(server, userData) {
         destructiveHint: true,
         idempotentHint: false,
         openWorldHint: true
-    }, async ({ task_id, name, append_description, status, priority, due_date, start_date, time_estimate, tags, parent_task_id, assignees, blocking, waiting_on, linked_tasks }) => {
+    }, async ({ task_id, name, description, append_description, status, priority, due_date, start_date, time_estimate, tags, parent_task_id, assignees, blocking, waiting_on, linked_tasks }) => {
         try {
+            if (description !== undefined && append_description !== undefined) {
+                return {
+                    content: [{
+                            type: "text",
+                            text: "Error: `description` (replace) and `append_description` (append) are mutually exclusive - pass only one of them. The task was NOT updated."
+                        }],
+                };
+            }
             const userData = await (0, utils_1.getCurrentUser)();
             // Get task details including current markdown description
             const taskResponse = await fetch(`https://api.clickup.com/api/v2/task/${task_id}?include_markdown_description=true`, {
@@ -320,15 +354,19 @@ function registerTaskToolsWrite(server, userData) {
             // 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;
+            // `description` replaces, `append_description` appends; both go through
+            // the same image pipeline. An empty `description` is a valid request to
+            // clear the description, so check for undefined rather than truthiness.
+            const descriptionInput = description !== undefined ? description : append_description;
+            let preparedDescription;
             let uploadedImages = [];
-            if (append_description) {
+            if (descriptionInput !== undefined) {
                 const abortNotice = "the task was NOT updated";
-                const prepared = await resolveImagesOrAbort(append_description, abortNotice);
+                const prepared = await resolveImagesOrAbort(descriptionInput, 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));
+                preparedDescription = (0, clickup_text_1.rewriteMarkdownImageUrls)(prepared.markdown, (0, attachments_1.toAttachmentMap)(uploadedImages));
             }
             // Handle dependencies separately since they need individual API calls
             let dependencyUpdateResults = [];
@@ -378,13 +416,17 @@ function registerTaskToolsWrite(server, userData) {
                     }
                 }
             }
-            // Handle append-only description update with markdown support
+            // Build the description to write: a full replacement, or the existing
+            // text plus a dated append section.
             let finalDescription;
-            if (appendedDescription !== undefined) {
+            if (description !== undefined) {
+                finalDescription = preparedDescription;
+            }
+            else if (preparedDescription !== 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}):** ${appendedDescription}`;
+                finalDescription = currentDescription + separator + `**Edit (${timestamp}):** ${preparedDescription}`;
             }
             // Build update body without tags (they're handled separately)
             const updateBody = buildTaskRequestBody({
@@ -436,8 +478,15 @@ function registerTaskToolsWrite(server, userData) {
                 }
             }
             const responseLines = formatTaskResponse(updatedTask, 'updated', {
-                name, append_description, status, priority, due_date, start_date, time_estimate, tags, parent_task_id, assignees, blocking, waiting_on, linked_tasks
+                name, description, append_description, status, priority, due_date, start_date, time_estimate, tags, parent_task_id, assignees, blocking, waiting_on, linked_tasks
             }, userData);
+            if (description !== undefined) {
+                const previousLength = (taskData.markdown_description || "").length;
+                responseLines.push(`description: replaced (previous ${previousLength} chars -> ${finalDescription?.length ?? 0} chars; the old version stays restorable via ClickUp's description history)`);
+            }
+            else if (append_description !== undefined) {
+                responseLines.push('description: appended as dated edit section');
+            }
             // Add dependency update results if any
             if (dependencyUpdateResults.length > 0) {
                 responseLines.push('dependency_warnings: ' + dependencyUpdateResults.join('; '));
@@ -636,26 +685,6 @@ 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.
  *
@@ -677,8 +706,8 @@ async function findTaskComment(taskId, commentId) {
     let checked = 0;
     let pages = 0;
     let sawThreadedReplies = false;
-    while (pages < MAX_COMMENT_PAGES) {
-        const page = await fetchCommentPage(taskId, cursor);
+    while (pages < comments_1.MAX_COMMENT_PAGES) {
+        const page = await (0, comments_1.fetchCommentPage)(taskId, cursor);
         pages++;
         if (page.length === 0) {
             break;
@@ -780,7 +809,16 @@ async function updateTaskDependencies(taskId, taskData, dependencies) {
     // Get current dependencies
     const currentBlocking = taskData.blocking?.map((dep) => dep.id) || [];
     const currentWaitingOn = taskData.waiting_on?.map((dep) => dep.id) || [];
-    const currentLinked = taskData.linked_tasks?.map((task) => task.id) || [];
+    // `linked_tasks` entries are link records, not tasks: each has `task_id` and
+    // `link_id` (the two ends of the link) and no `id` at all. Mapping `.id` here
+    // produced `[undefined, ...]`, so every existing link looked like it was no
+    // longer requested, and the removal loop then issued
+    // `DELETE /task/{id}/link/undefined`, which the API rejects. The result was a
+    // `linked_tasks` field documented as "replace" that could never remove
+    // anything. Take whichever end of the record is not the task being updated.
+    const currentLinked = taskData.linked_tasks
+        ?.map((link) => (link.task_id === taskData.id ? link.link_id : link.task_id))
+        .filter((id) => Boolean(id)) || [];
     // Helper function to make dependency API calls
     async function modifyDependency(operation, type, fromTaskId, toTaskId, dependsOn) {
         try {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hauptsache.net/clickup-mcp",
-  "version": "1.7.3",
+  "version": "1.9.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",