@sebastienheyd/clickup-mcp 1.9.0 → 1.10.2

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

@@ -6,10 +6,20 @@ 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");
+const dates_1 = require("../shared/dates");
 /**
  * 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.",
@@ -93,21 +103,25 @@ const taskPrioritySchema = zod_1.z.enum(["urgent", "high", "normal", "low"]).opt
 const taskDueDateSchema = zod_1.z.string().optional().describe("Optional due date as ISO date string (e.g., '2024-10-06T23:59:59+02:00')");
 const taskStartDateSchema = zod_1.z.string().optional().describe("Optional start date as ISO date string (e.g., '2024-10-06T09:00:00+02:00')");
 const taskTimeEstimateSchema = zod_1.z.number().optional().describe("Optional time estimate in hours (will be converted to milliseconds)");
-const taskPointsSchema = zod_1.z.number().nonnegative().optional().describe("Optional sprint points - requires the Sprint Points ClickApp on the space. Valid values depend on the points scale configured in that workspace: ClickUp rejects any other value with 'not a valid points selection'");
 const taskTagsSchema = zod_1.z.array(zod_1.z.string()).optional().describe("Optional array of tag names");
+const taskPointsSchema = zod_1.z.number().nonnegative().optional().describe("Optional sprint points - requires the Sprint Points ClickApp on the space. Valid values depend on the points scale configured in that workspace: ClickUp rejects any other value with 'not a valid points selection'");
+const taskIdSchema = zod_1.z.string().min(1).refine(val => (0, utils_1.isTaskId)(val) || (0, utils_1.isCustomTaskId)(val), {
+    message: "Must be an internal task ID (6-16 alphanumeric characters) or a custom task ID (e.g. SOI-4422)"
+});
 const CLEAR_HINT = " - pass null to clear the current value";
 function registerTaskToolsWrite(server, userData) {
     // Workaround: SDK 1.27+ dual Zod v3/v4 type causes TS2589 on server.tool() generics
     const tool = server.tool.bind(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",
             "- 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.",
@@ -118,32 +132,56 @@ function registerTaskToolsWrite(server, userData) {
         }
         return descriptionBase.join("\n");
     })(), {
-        task_id: zod_1.z.string().min(1).refine(val => (0, utils_1.isTaskId)(val) || (0, utils_1.isCustomTaskId)(val), {
-            message: "Must be an internal task ID (6+ alphanumeric characters) or a custom task ID (e.g. SOI-4422)"
-        }).describe("The task ID to comment on: internal ID (e.g. \"869c4za0g\") or custom ID (e.g. \"SOI-4422\")"),
+        task_id: taskIdSchema.describe("The task ID to comment on: internal ID (e.g. \"869c4za0g\") or custom ID (e.g. \"SOI-4422\")"),
         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 {
-            // Resolve custom task ID to internal ID if needed
-            const resolved_task_id = await (0, utils_1.resolveTaskId)(task_id);
+            // Resolve custom task IDs (e.g. "SOI-4422") to internal IDs
+            task_id = await (0, utils_1.resolveTaskId)(task_id);
+            // 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 { comment: parent, exhaustive } = await (0, comments_1.findTopLevelComment)(task_id, parent_comment_id);
+                if (!parent && !exhaustive) {
+                    // The lookup stopped at the page cap: the id may well be a valid but old
+                    // comment, so do not claim it is invalid.
+                    throw new Error(`Comment ${parent_comment_id} was not found among the ${comments_1.MAX_COMMENT_PAGES * comments_1.COMMENTS_PER_PAGE} newest top-level comments of task ${task_id}, so no reply was posted. ` +
+                        `The lookup stops after ${comments_1.MAX_COMMENT_PAGES} pages to protect the API budget and getTaskById shows the same range - ` +
+                        `reply to a comment listed there, or post a new top-level comment instead.`);
+                }
+                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
             // 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(resolved_task_id, images, 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)(uploaded));
             const requestBody = {
                 comment: commentBlocks,
                 notify_all: true
             };
-            const response = await fetch(`https://api.clickup.com/api/v2/task/${resolved_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,
@@ -153,7 +191,7 @@ function registerTaskToolsWrite(server, userData) {
             });
             if (!response.ok) {
                 const errorData = await response.json().catch(() => ({}));
-                throw new Error(`Error adding comment: ${response.status} ${response.statusText} - ${JSON.stringify(errorData)}`);
+                throw new Error(`ClickUp API ${response.status} ${response.statusText} - ${JSON.stringify(errorData)}`);
             }
             const commentData = await response.json();
             return {
@@ -161,9 +199,13 @@ 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'}`,
-                            `task_id: ${resolved_task_id}`,
+                            ...(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())}`,
                             `user: ${commentData.user?.username || 'Current user'}`,
@@ -192,8 +234,9 @@ function registerTaskToolsWrite(server, userData) {
             `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.",
-            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.",
+            COMMENT_FORMATTING_HINT,
+            "IMAGES ON EDIT: an edit can only KEEP the images already in this comment. Reading the comment (getTaskById) returns them as markdown, and passing that markdown back keeps them; an image whose markdown you drop disappears.",
+            "ClickUp refuses to add any other image to an existing comment - a new file, a data URI, a web URL, or an image of another comment or of the task description - so such a reference is rejected before anything is uploaded. To share a new image, post a new comment with addComment.",
             "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') {
@@ -201,10 +244,8 @@ function registerTaskToolsWrite(server, userData) {
         }
         return descriptionBase.join("\n");
     })(), {
-        task_id: zod_1.z.string().min(1).refine(val => (0, utils_1.isTaskId)(val) || (0, utils_1.isCustomTaskId)(val), {
-            message: "Must be an internal task ID (6+ alphanumeric characters) or a custom task ID (e.g. SOI-4422)"
-        }).describe("The ID of the task the comment belongs to - needed to locate the comment and to upload images. Internal ID (e.g. \"869c4za0g\") or custom ID (e.g. \"SOI-4422\")"),
-        comment_id: zod_1.z.string().min(1).describe("The ID of the comment to edit, as returned by addComment or getTaskById"),
+        task_id: taskIdSchema.describe("The ID of the task the comment belongs to - needed to locate the comment and to upload images: internal ID (e.g. \"869c4za0g\") or custom ID (e.g. \"SOI-4422\")"),
+        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,
@@ -212,21 +253,21 @@ function registerTaskToolsWrite(server, userData) {
         idempotentHint: true,
     }, async ({ task_id, comment_id, comment }) => {
         try {
-            // Resolve custom task ID to internal ID if needed
-            const resolved_task_id = await (0, utils_1.resolveTaskId)(task_id);
+            // Resolve custom task IDs (e.g. "SOI-4422") to internal IDs
+            task_id = await (0, utils_1.resolveTaskId)(task_id);
             const [existing, userData] = await Promise.all([
-                findTaskComment(resolved_task_id, comment_id),
+                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.
+            // Same converter as addComment - the undocumented rich `comment` array is
+            // accepted by PUT too, so formatting survives an edit. Images are different:
+            // ClickUp only lets an edit keep the comment's OWN images, so they are
+            // matched against the stored fragments and nothing is ever uploaded here.
             const abortNotice = "the comment was NOT changed";
-            const { markdown, images } = await resolveImagesOrAbort(comment, abortNotice);
-            const uploaded = await uploadImagesOrAbort(resolved_task_id, images, abortNotice);
-            const commentBlocks = (0, clickup_text_1.convertMarkdownToClickUpBlocks)(markdown, (0, attachments_1.toAttachmentMap)(uploaded));
+            const markdown = (0, clickup_text_1.normalizeImageDestinations)(comment);
+            const keptImages = keepOwnCommentImages(existing, markdown, abortNotice);
+            const commentBlocks = (0, clickup_text_1.convertMarkdownToClickUpBlocks)(markdown, (0, attachments_1.toAttachmentMap)(keptImages));
             // 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}`, {
@@ -239,7 +280,7 @@ function registerTaskToolsWrite(server, userData) {
             });
             if (!response.ok) {
                 const errorData = await response.json().catch(() => ({}));
-                throw new Error(`Error editing comment: ${response.status} ${response.statusText} - ${JSON.stringify(errorData)}`);
+                throw new Error(`ClickUp API ${response.status} ${response.statusText} - ${JSON.stringify(errorData)}`);
             }
             return {
                 content: [
@@ -248,12 +289,15 @@ function registerTaskToolsWrite(server, userData) {
                         text: [
                             `Comment edited successfully!`,
                             `comment_id: ${comment_id}`,
-                            `task_id: ${resolved_task_id}`,
-                            `task_url: https://app.clickup.com/t/${resolved_task_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),
+                            ...(keptImages.length > 0 ? [
+                                `images_kept: ${keptImages.length}`,
+                                ...keptImages.map((k) => `  - ${k.attachment.name} (${k.attachment.url})`),
+                            ] : []),
                         ].join('\n')
                     }
                 ],
@@ -275,9 +319,7 @@ function registerTaskToolsWrite(server, userData) {
         "Deletes a task comment. This cannot be undone - the deleted text is echoed back so it can be re-posted with addComment if needed.",
         `GUARDRAILS: same as editComment - only comments written by the API token's own user can be deleted, and only within ${config_1.CONFIG.commentEditWindowHours} hours of their creation. Replies inside a thread cannot be deleted.`,
     ].join("\n"), {
-        task_id: zod_1.z.string().min(1).refine(val => (0, utils_1.isTaskId)(val) || (0, utils_1.isCustomTaskId)(val), {
-            message: "Must be an internal task ID (6+ alphanumeric characters) or a custom task ID (e.g. SOI-4422)"
-        }).describe("The ID of the task the comment belongs to - needed to locate the comment. Internal ID (e.g. \"869c4za0g\") or custom ID (e.g. \"SOI-4422\")"),
+        task_id: taskIdSchema.describe("The ID of the task the comment belongs to - needed to locate the comment. Internal ID (e.g. \"869c4za0g\") or custom ID (e.g. \"SOI-4422\")"),
         comment_id: zod_1.z.string().min(1).describe("The ID of the comment to delete, as returned by addComment or getTaskById"),
     }, {
         readOnlyHint: false,
@@ -297,7 +339,7 @@ function registerTaskToolsWrite(server, userData) {
             });
             if (!response.ok) {
                 const errorData = await response.json().catch(() => ({}));
-                throw new Error(`Error deleting comment: ${response.status} ${response.statusText} - ${JSON.stringify(errorData)}`);
+                throw new Error(`ClickUp API ${response.status} ${response.statusText} - ${JSON.stringify(errorData)}`);
             }
             return {
                 content: [
@@ -332,11 +374,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.",
-            "DESCRIPTION: `append_description` adds a dated block under the existing description and is the safe default for notes. `replace_description` rewrites the whole description - use it to correct or restructure the specification. Read the current description with getTaskById first and repeat everything worth keeping; the previous description is echoed back so it can be restored with another call.",
+            "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."
         ];
@@ -345,12 +388,10 @@ function registerTaskToolsWrite(server, userData) {
         }
         return descriptionBase.join("\n");
     })(), {
-        task_id: zod_1.z.string().min(1).refine(val => (0, utils_1.isTaskId)(val) || (0, utils_1.isCustomTaskId)(val), {
-            message: "Must be an internal task ID (6+ alphanumeric characters) or a custom task ID (e.g. SOI-4422)"
-        }).describe("The task ID to update: internal ID (e.g. \"869c4za0g\") or custom ID (e.g. \"SOI-4422\")"),
+        task_id: taskIdSchema.describe("The task ID to update: internal ID (e.g. \"869c4za0g\") or custom ID (e.g. \"SOI-4422\")"),
         name: taskNameSchema.optional(),
-        append_description: zod_1.z.string().optional().describe("Optional markdown content to APPEND under the existing task description as a dated block (preserves existing content). Mutually exclusive with replace_description"),
-        replace_description: zod_1.z.string().optional().describe("Optional markdown content that REPLACES the whole task description. Anything not repeated here is lost (the previous description is echoed back in the response). Mutually exclusive with append_description"),
+        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.nullable().describe(taskDueDateSchema.description + CLEAR_HINT),
@@ -358,7 +399,7 @@ function registerTaskToolsWrite(server, userData) {
         time_estimate: taskTimeEstimateSchema.nullable().describe(taskTimeEstimateSchema.description + CLEAR_HINT),
         points: taskPointsSchema.nullable().describe(taskPointsSchema.description + CLEAR_HINT),
         tags: taskTagsSchema.describe("Optional array of tag names (will replace existing tags)"),
-        parent_task_id: zod_1.z.string().optional().describe("Optional parent task ID to change parent/child relationships"),
+        parent_task_id: taskIdSchema.optional().describe("Optional parent task ID to move this task under, as a subtask: internal ID (e.g. \"869c4za0g\") or custom ID (e.g. \"SOI-4422\")"),
         assignees: zod_1.z.array(zod_1.z.string()).optional().describe("Optional array of user IDs to add as assignees - existing assignees are kept"),
         remove_assignees: zod_1.z.array(zod_1.z.string()).optional().describe("Optional array of user IDs to unassign from the task. Combine with assignees to replace one assignee by another."),
         waiting_on: zod_1.z.array(zod_1.z.string()).optional().describe("Optional array of task IDs that this task should wait on (will replace existing waiting_on relationships)"),
@@ -369,18 +410,37 @@ function registerTaskToolsWrite(server, userData) {
         destructiveHint: true,
         idempotentHint: false,
         openWorldHint: true
-    }, async ({ task_id, name, append_description, replace_description, status, priority, due_date, start_date, time_estimate, points, tags, parent_task_id, assignees, remove_assignees, blocking, waiting_on, linked_tasks }) => {
+    }, async ({ task_id, name, description, append_description, status, priority, due_date, start_date, time_estimate, points, tags, parent_task_id, assignees, remove_assignees, blocking, waiting_on, linked_tasks }) => {
         try {
-            if (append_description !== undefined && replace_description !== undefined) {
+            // Argument errors are checked before anything hits the network: resolving a
+            // custom task ID costs an API call that would be wasted on a rejected request.
+            if (description !== undefined && append_description !== undefined) {
                 return {
-                    content: [{ type: "text", text: "Pass either append_description or replace_description, not both. The task was NOT updated." }],
+                    content: [{
+                            type: "text",
+                            text: "Error: `description` (replace) and `append_description` (append) are mutually exclusive - pass only one of them. The task was NOT updated."
+                        }],
                 };
             }
-            // Resolve custom task ID to internal ID if needed
-            const resolved_task_id = await (0, utils_1.resolveTaskId)(task_id);
+            // A malformed date must be refused before anything is written: it would
+            // otherwise be sent as null and clear the date (see parseDateInput).
+            assertValidTaskDates({ due_date, start_date });
+            // Resolve custom task IDs (e.g. "SOI-4422") to internal IDs
+            task_id = await (0, utils_1.resolveTaskId)(task_id);
+            // Current dependencies and links come back from ClickUp with internal IDs,
+            // so the requested lists must use them too: an unresolved "SOI-4422" would
+            // not match its own internal ID, and the existing relation would be removed
+            // as "no longer requested" while a duplicate is added. Resolved up front, so
+            // an unknown custom ID aborts the update before anything is written.
+            [blocking, waiting_on, linked_tasks] = await Promise.all([blocking, waiting_on, linked_tasks].map(resolveTaskIdList));
+            // ClickUp's `parent` field only takes an internal ID: a custom ID gets a bare
+            // 500 Internal Server Error (verified live), with nothing to tell what is wrong.
+            if (parent_task_id !== undefined) {
+                parent_task_id = await (0, utils_1.resolveTaskId)(parent_task_id);
+            }
             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/${resolved_task_id}?include_markdown_description=true`, {
+            const taskResponse = await fetch(`https://api.clickup.com/api/v2/task/${task_id}?include_markdown_description=true`, {
                 headers: { Authorization: config_1.CONFIG.apiKey },
             });
             if (!taskResponse.ok) {
@@ -390,15 +450,16 @@ 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.
-            // Both description modes go through the same pipeline: only what is done
-            // with the prepared markdown differs (appended block vs whole description).
+            // `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 = [];
-            const descriptionInput = replace_description !== undefined ? replace_description : append_description;
-            if (descriptionInput) {
+            if (descriptionInput !== undefined) {
                 const abortNotice = "the task was NOT updated";
                 const prepared = await resolveImagesOrAbort(descriptionInput, abortNotice);
-                uploadedImages = await uploadImagesOrAbort(resolved_task_id, prepared.images, 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.
                 preparedDescription = (0, clickup_text_1.rewriteMarkdownImageUrls)(prepared.markdown, (0, attachments_1.toAttachmentMap)(uploadedImages));
@@ -406,7 +467,7 @@ function registerTaskToolsWrite(server, userData) {
             // Handle dependencies separately since they need individual API calls
             let dependencyUpdateResults = [];
             if (blocking !== undefined || waiting_on !== undefined || linked_tasks !== undefined) {
-                const dependencyResults = await updateTaskDependencies(resolved_task_id, taskData, { blocking, waiting_on, linked_tasks });
+                const dependencyResults = await updateTaskDependencies(task_id, taskData, { blocking, waiting_on, linked_tasks });
                 dependencyUpdateResults = dependencyResults;
             }
             // Handle tags separately since they need individual API calls
@@ -419,7 +480,7 @@ function registerTaskToolsWrite(server, userData) {
                 // Add new tags
                 for (const tagName of tagsToAdd) {
                     try {
-                        const addTagResponse = await fetch(`https://api.clickup.com/api/v2/task/${resolved_task_id}/tag/${encodeURIComponent(tagName)}`, {
+                        const addTagResponse = await fetch(`https://api.clickup.com/api/v2/task/${task_id}/tag/${encodeURIComponent(tagName)}`, {
                             method: 'POST',
                             headers: { Authorization: config_1.CONFIG.apiKey }
                         });
@@ -436,7 +497,7 @@ function registerTaskToolsWrite(server, userData) {
                 // Remove old tags
                 for (const tagName of tagsToRemove) {
                     try {
-                        const removeTagResponse = await fetch(`https://api.clickup.com/api/v2/task/${resolved_task_id}/tag/${encodeURIComponent(tagName)}`, {
+                        const removeTagResponse = await fetch(`https://api.clickup.com/api/v2/task/${task_id}/tag/${encodeURIComponent(tagName)}`, {
                             method: 'DELETE',
                             headers: { Authorization: config_1.CONFIG.apiKey }
                         });
@@ -451,14 +512,15 @@ function registerTaskToolsWrite(server, userData) {
                     }
                 }
             }
-            // Append adds a dated block under the current description; replace sends
-            // the prepared markdown as is. An empty replace_description clears it.
+            // Build the description to write: a full replacement, or the existing
+            // text plus a dated append section.
             let finalDescription;
-            const currentDescription = taskData.markdown_description || "";
-            if (replace_description !== undefined) {
+            if (description !== undefined) {
+                // An empty string clears the description (the image pipeline skips empty input)
                 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}):** ${preparedDescription}`;
@@ -489,7 +551,7 @@ function registerTaskToolsWrite(server, userData) {
             // Update the task (if there are non-tag updates)
             let updatedTask = taskData;
             if (Object.keys(updateBody).length > 0) {
-                const updateResponse = await fetch(`https://api.clickup.com/api/v2/task/${resolved_task_id}`, {
+                const updateResponse = await fetch(`https://api.clickup.com/api/v2/task/${task_id}`, {
                     method: 'PUT',
                     headers: {
                         Authorization: config_1.CONFIG.apiKey,
@@ -499,13 +561,13 @@ function registerTaskToolsWrite(server, userData) {
                 });
                 if (!updateResponse.ok) {
                     const errorData = await updateResponse.json().catch(() => ({}));
-                    throw new Error(`Error updating task: ${updateResponse.status} ${updateResponse.statusText} - ${JSON.stringify(errorData)}`);
+                    throw new Error(`ClickUp API ${updateResponse.status} ${updateResponse.statusText} - ${JSON.stringify(errorData)}`);
                 }
                 updatedTask = await updateResponse.json();
             }
             // If only tags or dependencies were updated, fetch the task again to get the updated state
             if ((tags !== undefined || blocking !== undefined || waiting_on !== undefined || linked_tasks !== undefined) && Object.keys(updateBody).length === 0) {
-                const refreshResponse = await fetch(`https://api.clickup.com/api/v2/task/${resolved_task_id}`, {
+                const refreshResponse = await fetch(`https://api.clickup.com/api/v2/task/${task_id}`, {
                     headers: { Authorization: config_1.CONFIG.apiKey },
                 });
                 if (refreshResponse.ok) {
@@ -513,11 +575,16 @@ function registerTaskToolsWrite(server, userData) {
                 }
             }
             const responseLines = formatTaskResponse(updatedTask, 'updated', {
-                name, append_description, status, priority, due_date, start_date, time_estimate, points, tags, parent_task_id, assignees, remove_assignees, blocking, waiting_on, linked_tasks
+                name, description, append_description, status, priority, due_date, start_date, time_estimate, points, tags, parent_task_id, assignees, remove_assignees, blocking, waiting_on, linked_tasks
             }, userData);
-            // Echo what was overwritten so a wrong replacement can be undone with another call
-            if (replace_description !== undefined) {
-                responseLines.push(`previous_description: ${currentDescription.trim() ? currentDescription : '(empty)'}`);
+            if (description !== undefined) {
+                const previousDescription = taskData.markdown_description || "";
+                responseLines.push(`description: replaced (previous ${previousDescription.length} chars -> ${finalDescription?.length ?? 0} chars; the old version stays restorable via ClickUp's description history)`);
+                // Echo what was overwritten so a wrong replacement can be undone with another call
+                responseLines.push(`previous_description: ${previousDescription.trim() ? previousDescription : '(empty)'}`);
+            }
+            else if (append_description !== undefined) {
+                responseLines.push('description: appended as dated edit section');
             }
             // Add dependency update results if any
             if (dependencyUpdateResults.length > 0) {
@@ -577,7 +644,7 @@ function registerTaskToolsWrite(server, userData) {
         time_estimate: taskTimeEstimateSchema,
         points: taskPointsSchema,
         tags: taskTagsSchema,
-        parent_task_id: zod_1.z.string().optional().describe("Optional parent task ID to create this as a subtask"),
+        parent_task_id: taskIdSchema.optional().describe("Optional parent task ID to create this as a subtask: internal ID (e.g. \"869c4za0g\") or custom ID (e.g. \"SOI-4422\")"),
         assignees: zod_1.z.array(zod_1.z.string()).optional().describe(createAssigneeDescription(userData))
     }, {
         readOnlyHint: false,
@@ -591,6 +658,12 @@ function registerTaskToolsWrite(server, userData) {
             // 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");
+            // ClickUp's `parent` field only takes an internal ID: a custom ID gets a bare
+            // 500 Internal Server Error (verified live). Resolved before the task exists,
+            // so an unknown parent leaves nothing behind.
+            if (parent_task_id !== undefined) {
+                parent_task_id = await (0, utils_1.resolveTaskId)(parent_task_id);
+            }
             const userData = await (0, utils_1.getCurrentUser)();
             const currentUserId = userData.user.id;
             const requestBody = buildTaskRequestBody({
@@ -610,30 +683,29 @@ function registerTaskToolsWrite(server, userData) {
             });
             if (!response.ok) {
                 const errorData = await response.json().catch(() => ({}));
-                throw new Error(`Error creating task: ${response.status} ${response.statusText} - ${JSON.stringify(errorData)}`);
+                throw new Error(`ClickUp API ${response.status} ${response.statusText} - ${JSON.stringify(errorData)}`);
             }
-            let createdTask = await response.json();
-            // Handle tags separately via dedicated API endpoints
-            if (tags && tags.length > 0) {
+            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) {
-                    const encodedTag = encodeURIComponent(tagName);
-                    const tagResponse = await fetch(`https://api.clickup.com/api/v2/task/${createdTask.id}/tag/${encodedTag}`, {
-                        method: 'POST',
-                        headers: {
-                            Authorization: config_1.CONFIG.apiKey,
-                            'Content-Type': 'application/json'
+                    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}`);
                         }
-                    });
-                    if (!tagResponse.ok) {
-                        console.error(`Error adding tag "${tagName}" to task ${createdTask.id}: ${tagResponse.status}`);
                     }
-                }
-                // Re-fetch task to get updated tags
-                const refreshResponse = await fetch(`https://api.clickup.com/api/v2/task/${createdTask.id}`, {
-                    headers: { Authorization: config_1.CONFIG.apiKey }
-                });
-                if (refreshResponse.ok) {
-                    createdTask = await refreshResponse.json();
+                    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
@@ -671,6 +743,9 @@ function registerTaskToolsWrite(server, userData) {
             }, userData);
             responseLines.push(...formatAttachedImages(uploaded));
             responseLines.push(...imageWarnings);
+            if (tagCreateResults.length > 0) {
+                responseLines.push('tag_warnings: ' + tagCreateResults.join('; '));
+            }
             return {
                 content: [
                     {
@@ -707,9 +782,16 @@ function convertPriorityToNumber(priority) {
         default: return 3;
     }
 }
+/**
+ * The task payload carries the priority NAME (`priority: { id: "4", priority: "low" }`),
+ * so a numeric-only lookup turned every real priority into "unknown". Accept both.
+ */
 function convertPriorityToString(priority) {
+    if (typeof priority === 'string' && ['urgent', 'high', 'normal', 'low'].includes(priority.toLowerCase())) {
+        return priority.toLowerCase();
+    }
     const priorityMap = { 1: 'urgent', 2: 'high', 3: 'normal', 4: 'low' };
-    return priorityMap[priority] || 'unknown';
+    return priorityMap[Number(priority)] || 'unknown';
 }
 function formatTimeEstimate(hours) {
     const displayHours = Math.floor(hours);
@@ -717,24 +799,67 @@ function formatTimeEstimate(hours) {
     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.
+ * Match the image references of an edited comment against the images the comment
+ * already contains, and return the stored attachment object for each of them.
+ *
+ * Verified live on `PUT /comment/{id}`: an image fragment is only accepted when it
+ * carries the real attachment of an image that is ALREADY in that comment. Any
+ * other attachment - a fresh upload, the task description's image, an image of
+ * another comment - is refused with 401 ACCESS_610, and a fragment whose id is not
+ * a real attachment id fails with 404 ACCESS_028. Reusing the stored object (real
+ * id, dimensions included) is therefore the only working way to keep an image, and
+ * anything else is rejected here, before a request is made - uploading first would
+ * only leave an orphan attachment on the task behind the failed edit.
  */
-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)}`);
+function keepOwnCommentImages(existing, markdown, abortNotice) {
+    const sources = (0, clickup_text_1.collectMarkdownImageSources)(markdown);
+    if (sources.length === 0) {
+        return [];
+    }
+    const ownImages = new Map();
+    for (const fragment of existing.comment ?? []) {
+        if (fragment?.type === "image" && fragment.image?.url) {
+            ownImages.set(normalizeUrl(fragment.image.url), fragment.image);
+        }
+    }
+    const kept = [];
+    const refused = [];
+    const seen = new Set();
+    for (const { src } of sources) {
+        if (seen.has(src)) {
+            continue;
+        }
+        seen.add(src);
+        const stored = ownImages.get(normalizeUrl(src));
+        if (stored) {
+            kept.push({ src, attachment: stored });
+        }
+        else {
+            refused.push(src);
+        }
+    }
+    if (refused.length > 0) {
+        throw new Error([
+            `${refused.length} image reference(s) are not images of this comment, so ${abortNotice}:`,
+            ...refused.map((src) => `  - ${summarizeImageSource(src)}`),
+            `ClickUp only lets an edit keep the images already in the comment - it refuses to add any other image.`,
+            `Remove these references, or post the new image in a new comment with addComment.`,
+        ].join("\n"));
     }
-    const data = await response.json();
-    return Array.isArray(data.comments) ? data.comments : [];
+    return kept;
+}
+/** Compare attachment URLs regardless of percent-encoding of the filename */
+function normalizeUrl(url) {
+    try {
+        return decodeURI(url.trim());
+    }
+    catch {
+        return url.trim();
+    }
+}
+/** Shorten a data URI so an error message never repeats a base64 payload */
+function summarizeImageSource(src) {
+    return src.startsWith("data:") ? `${src.slice(0, 40)}... (data URI)` : src;
 }
 /**
  * Load a single comment of a task.
@@ -757,8 +882,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;
@@ -769,6 +894,10 @@ async function findTaskComment(taskId, commentId) {
         }
         checked += page.length;
         sawThreadedReplies || (sawThreadedReplies = page.some((entry) => (entry.reply_count ?? 0) > 0));
+        // A short page is the last one - requesting the next would only return [].
+        if (page.length < comments_1.COMMENTS_PER_PAGE) {
+            break;
+        }
         // 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];
@@ -822,6 +951,35 @@ function timestampToIso(timestamp) {
     const timezoneOffset = sign + String(offsetHours).padStart(2, '0') + ':' + String(offsetMinutes).padStart(2, '0');
     return `${year}-${month}-${day}T${hours}:${minutes}${timezoneOffset}`;
 }
+/**
+ * Convert a due/start date parameter for the task API.
+ *
+ * ClickUp drops the time of day unless `due_date_time`/`start_date_time` is true
+ * (verified live: 18:00 came back as 04:00, its all-day placeholder), so report
+ * whether the caller gave a time. A bare date (YYYY-MM-DD) is an all-day value at
+ * local midnight. Invalid or impossible dates throw instead of being sent as null.
+ */
+function parseTaskDate(value, field) {
+    return (0, dates_1.parseDateInput)(value, field, "start");
+}
+/** Validate due/start dates up front so a bad value never reaches a write */
+function assertValidTaskDates(dates) {
+    for (const field of ["due_date", "start_date"]) {
+        const value = dates[field];
+        if (typeof value === "string") {
+            parseTaskDate(value, field);
+        }
+    }
+}
+/** Resolve every ID of a relation list to an internal ID, without duplicates */
+async function resolveTaskIdList(ids) {
+    if (ids === undefined) {
+        return undefined;
+    }
+    // Deduplicate before resolving too: each custom ID costs one API call
+    const resolved = await Promise.all([...new Set(ids)].map((id) => (0, utils_1.resolveTaskId)(id)));
+    return [...new Set(resolved)];
+}
 function buildTaskRequestBody(params, currentUserId) {
     const requestBody = {};
     if (params.name !== undefined) {
@@ -836,10 +994,24 @@ function buildTaskRequestBody(params, currentUserId) {
     // null clears the value - it must be sent as is, new Date(null) would set 1970-01-01.
     // time_estimate is the exception: ClickUp accepts null but silently keeps the estimate, only 0 clears it.
     if (params.due_date !== undefined) {
-        requestBody.due_date = params.due_date === null ? null : new Date(params.due_date).getTime();
+        if (params.due_date === null) {
+            requestBody.due_date = null;
+        }
+        else {
+            const due = parseTaskDate(params.due_date, 'due_date');
+            requestBody.due_date = due.timestamp;
+            requestBody.due_date_time = due.hasTime;
+        }
     }
     if (params.start_date !== undefined) {
-        requestBody.start_date = params.start_date === null ? null : new Date(params.start_date).getTime();
+        if (params.start_date === null) {
+            requestBody.start_date = null;
+        }
+        else {
+            const start = parseTaskDate(params.start_date, 'start_date');
+            requestBody.start_date = start.timestamp;
+            requestBody.start_date_time = start.hasTime;
+        }
     }
     if (params.time_estimate !== undefined) {
         requestBody.time_estimate = params.time_estimate === null ? 0 : Math.round(params.time_estimate * 60 * 60 * 1000);
@@ -863,10 +1035,28 @@ function buildTaskRequestBody(params, currentUserId) {
 // Helper function to manage task dependencies
 async function updateTaskDependencies(taskId, taskData, dependencies) {
     const errors = [];
-    // 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) || [];
+    // Get current dependencies. The task payload has no `blocking`/`waiting_on`
+    // arrays (verified live): both directions live in one flat `dependencies` array
+    // of `{ task_id, depends_on }` records, and this task can sit on either side.
+    // Reading the missing fields made every current dependency look absent, so
+    // `waiting_on: []`/`blocking: []` never removed anything and reported no error.
+    const dependencyRecords = Array.isArray(taskData.dependencies) ? taskData.dependencies : [];
+    const currentWaitingOn = dependencyRecords
+        .filter((dep) => dep.task_id === taskId && dep.depends_on)
+        .map((dep) => dep.depends_on);
+    const currentBlocking = dependencyRecords
+        .filter((dep) => dep.depends_on === taskId && dep.task_id)
+        .map((dep) => dep.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 {