@hauptsache.net/clickup-mcp 1.8.0 → 1.9.0

package/README.md

@@ -189,7 +189,7 @@ The ClickUp MCP supports three operational modes to balance functionality, secur
 | `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/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;AAsJpE,wBAAgB,sBAAsB,CAAC,MAAM,EAAE,SAAS,EAAE,QAAQ,EAAE,GAAG,QAooBtE"}
+{"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

@@ -298,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."
         ];
@@ -313,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,
@@ -330,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`, {
@@ -344,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 = [];
@@ -402,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({
@@ -460,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('; '));

package/package.json

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