@sebastienheyd/clickup-mcp 1.9.0 → 1.10.2

package/dist/shared/comments.js

@@ -0,0 +1,158 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MAX_REPLY_FETCHES = exports.COMMENTS_PER_PAGE = 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. */
+exports.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. Never throws: a failing page (typically a 429 close to
+ * the API limit on exactly the busy tasks that need paging) keeps the comments
+ * already loaded and is reported through `incomplete`, so the caller can show a
+ * partial history with a warning instead of silently showing none.
+ */
+async function fetchAllTopLevelComments(taskId) {
+    const comments = [];
+    let cursor;
+    let pages = 0;
+    let lastPageWasFull = false;
+    while (pages < exports.MAX_COMMENT_PAGES) {
+        let page;
+        try {
+            page = await fetchCommentPage(taskId, cursor);
+        }
+        catch (error) {
+            const detail = error instanceof Error ? error.message : String(error);
+            console.error(`Error fetching comments of task ${taskId} (page ${pages + 1}, ${comments.length} loaded so far): ${detail}`);
+            return { comments, incomplete: { reason: "error", detail } };
+        }
+        pages++;
+        if (page.length === 0) {
+            lastPageWasFull = false;
+            break;
+        }
+        comments.push(...page);
+        lastPageWasFull = page.length >= exports.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) {
+        const detail = `the task has more than ${comments.length} top-level comments; loading stops after ${exports.MAX_COMMENT_PAGES} pages to protect the API budget`;
+        console.error(`Task ${taskId}: older comments were not loaded - ${detail}.`);
+        return { comments, incomplete: { reason: "capped", detail } };
+    }
+    return { comments, incomplete: null };
+}
+/**
+ * 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. `comment` is 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. Callers must check `exhaustive` before
+ * telling the user the id is invalid: past the page cap the answer is only
+ * "not among the newest comments".
+ */
+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 { comment: match, exhaustive: true };
+        }
+        if (page.length < exports.COMMENTS_PER_PAGE) {
+            return { comment: undefined, exhaustive: true };
+        }
+        const oldest = page[page.length - 1];
+        cursor = { start: String(oldest.date), startId: String(oldest.id) };
+    }
+    return { comment: undefined, exhaustive: false };
+}
+/**
+ * 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/shared/config.d.ts.map

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

package/dist/shared/config.js

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

package/dist/shared/dates.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Date parameters as tools receive them: an ISO date with a time of day
+ * ("2026-10-02T18:00:00+02:00") or a bare date ("2026-10-02").
+ */
+export interface ParsedDateInput {
+    /** Milliseconds since the epoch */
+    timestamp: number;
+    /** false for a bare date (YYYY-MM-DD), which stands for a whole local day */
+    hasTime: boolean;
+}
+/**
+ * Parse a date parameter, or throw an error that names the field.
+ *
+ * Two silent failures are turned into errors on purpose:
+ * - an unparseable string gives NaN, which JSON.stringify sends as `null` - a
+ *   due date would be cleared while the tool reports success;
+ * - JavaScript rolls impossible days over instead of rejecting them, with or
+ *   without a time ("2026-02-31" and "2026-02-31T10:00" both become March 3rd).
+ *
+ * A bare date is a whole LOCAL day: `new Date("2026-10-02")` would be UTC
+ * midnight, i.e. the previous evening east of Greenwich. `bareDateAt` picks the
+ * start (00:00:00.000) or the end (23:59:59.999) of that day.
+ */
+export declare function parseDateInput(value: string, field: string, bareDateAt?: "start" | "end"): ParsedDateInput;
+//# sourceMappingURL=dates.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"dates.d.ts","sourceRoot":"","sources":["../../src/shared/dates.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,MAAM,WAAW,eAAe;IAC9B,mCAAmC;IACnC,SAAS,EAAE,MAAM,CAAC;IAClB,6EAA6E;IAC7E,OAAO,EAAE,OAAO,CAAC;CAClB;AAID;;;;;;;;;;;;GAYG;AACH,wBAAgB,cAAc,CAC5B,KAAK,EAAE,MAAM,EACb,KAAK,EAAE,MAAM,EACb,UAAU,GAAE,OAAO,GAAG,KAAe,GACpC,eAAe,CA8BjB"}

package/dist/shared/dates.js

@@ -0,0 +1,42 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.parseDateInput = parseDateInput;
+const LEADING_DATE = /^(\d{4})-(\d{2})-(\d{2})(.*)$/;
+/**
+ * Parse a date parameter, or throw an error that names the field.
+ *
+ * Two silent failures are turned into errors on purpose:
+ * - an unparseable string gives NaN, which JSON.stringify sends as `null` - a
+ *   due date would be cleared while the tool reports success;
+ * - JavaScript rolls impossible days over instead of rejecting them, with or
+ *   without a time ("2026-02-31" and "2026-02-31T10:00" both become March 3rd).
+ *
+ * A bare date is a whole LOCAL day: `new Date("2026-10-02")` would be UTC
+ * midnight, i.e. the previous evening east of Greenwich. `bareDateAt` picks the
+ * start (00:00:00.000) or the end (23:59:59.999) of that day.
+ */
+function parseDateInput(value, field, bareDateAt = "start") {
+    const trimmed = value.trim();
+    const leading = LEADING_DATE.exec(trimmed);
+    if (leading) {
+        const [, yearText, monthText, dayText, rest] = leading;
+        const year = Number(yearText);
+        const month = Number(monthText);
+        const day = Number(dayText);
+        const daysInMonth = month >= 1 && month <= 12 ? new Date(year, month, 0).getDate() : 0;
+        if (day < 1 || day > daysInMonth) {
+            throw new Error(`Invalid ${field} "${value}": ${yearText}-${monthText}-${dayText} is not a calendar date.`);
+        }
+        if (rest === "") {
+            const timestamp = bareDateAt === "start"
+                ? new Date(year, month - 1, day, 0, 0, 0, 0).getTime()
+                : new Date(year, month - 1, day, 23, 59, 59, 999).getTime();
+            return { timestamp, hasTime: false };
+        }
+    }
+    const timestamp = Date.parse(trimmed);
+    if (Number.isNaN(timestamp)) {
+        throw new Error(`Invalid ${field} "${value}". Expected an ISO date with a time of day (e.g. 2026-10-02T18:00:00+02:00) or a bare date (YYYY-MM-DD).`);
+    }
+    return { timestamp, hasTime: true };
+}

package/dist/shared/utils.d.ts

@@ -2,7 +2,7 @@ import Fuse from 'fuse.js';
 /**
  * Checks if a string looks like a valid ClickUp task ID
  * Valid task IDs are at least 6 characters long and contain only alphanumeric characters.
- * No upper bound: ClickUp now issues IDs of 10+ characters (e.g. "wdrv93ebwx").
+ * 6-16 characters: ClickUp lengthened generated IDs in August 2026 (9 -> 10 -> 11 chars); 16 leaves headroom while still rejecting URLs and "CU-" prefixed strings before an API call.
  */
 export declare function isTaskId(str: string): boolean;
 /**

package/dist/shared/utils.js

@@ -29,11 +29,11 @@ const GLOBAL_REFRESH_INTERVAL = 60000; // 60 seconds - that is the rate limit ti
 /**
  * Checks if a string looks like a valid ClickUp task ID
  * Valid task IDs are at least 6 characters long and contain only alphanumeric characters.
- * No upper bound: ClickUp now issues IDs of 10+ characters (e.g. "wdrv93ebwx").
+ * 6-16 characters: ClickUp lengthened generated IDs in August 2026 (9 -> 10 -> 11 chars); 16 leaves headroom while still rejecting URLs and "CU-" prefixed strings before an API call.
  */
 function isTaskId(str) {
-    // Task IDs are 6+ characters long and contain only alphanumeric characters
-    return /^[a-z0-9]{6,}$/i.test(str);
+    // Task IDs are 6-16 characters long and contain only alphanumeric characters
+    return /^[a-z0-9]{6,16}$/i.test(str);
 }
 /**
  * Checks if a string looks like a ClickUp custom task ID (e.g. "SOI-4422", "PQP-123")
@@ -68,7 +68,7 @@ async function resolveTaskId(id) {
     if (isCustomTaskId(id)) {
         return resolveCustomTaskId(id);
     }
-    throw new Error(`Invalid task ID format: "${id}". Expected an internal ID (6+ alphanumeric characters) or a custom ID (e.g. "SOI-4422").`);
+    throw new Error(`Invalid task ID format: "${id}". Expected an internal ID (6-16 alphanumeric characters) or a custom ID (e.g. "SOI-4422").`);
 }
 // Cache for current user info to avoid repeated API calls and race conditions
 let cachedUserPromise = null;

package/dist/tools/list-tools.js

@@ -114,23 +114,23 @@ function registerListToolsWrite(server) {
     tool("updateListInfo", [
         "Appends to or replaces a list's description.",
         "ALWAYS reference the list URL (https://app.clickup.com/v/l/LIST_ID) when updating or discussing lists.",
-        "`append_description` adds a dated block under the existing description and is the safe default. `replace_description` rewrites the whole description - read it with getListInfo first and repeat everything worth keeping; the previous description is echoed back so it can be restored.",
+        "`append_description` adds a dated block under the existing description and is the safe default. `description` rewrites the whole description - read it with getListInfo first and repeat everything worth keeping; the previous description is echoed back so it can be restored.",
         "Use this to add project context, requirements, or guidelines that LLMs should consider when working with tasks in this list.",
         "Include links to related tasks, spaces, or external resources in the appended content.",
         "Content is appended in markdown format with timestamp for tracking changes."
     ].join("\n"), {
         list_id: zod_1.z.string().min(1).describe("The list ID to update"),
-        append_description: zod_1.z.string().min(1).optional().describe("Markdown content to APPEND under the existing list description as a dated block (preserves existing content). Mutually exclusive with replace_description"),
-        replace_description: zod_1.z.string().optional().describe("Markdown content that REPLACES the whole list description. Anything not repeated here is lost (the previous description is echoed back). Mutually exclusive with append_description")
+        append_description: zod_1.z.string().min(1).optional().describe("Markdown content to APPEND under the existing list description as a dated block (preserves existing content). Mutually exclusive with description"),
+        description: zod_1.z.string().optional().describe("Markdown content that REPLACES the whole list description. Anything not repeated here is lost (the previous description is echoed back). Mutually exclusive with append_description")
     }, {
         readOnlyHint: false,
         destructiveHint: true,
         idempotentHint: false,
-    }, async ({ list_id, append_description, replace_description }) => {
+    }, async ({ list_id, append_description, description }) => {
         try {
-            if ((append_description === undefined) === (replace_description === undefined)) {
+            if ((append_description === undefined) === (description === undefined)) {
                 return {
-                    content: [{ type: "text", text: "Pass either append_description or replace_description (exactly one). The list was NOT updated." }],
+                    content: [{ type: "text", text: "Pass either append_description or description (exactly one). The list was NOT updated." }],
                 };
             }
             // Get current list info including description (try to get markdown content)
@@ -145,8 +145,8 @@ function registerListToolsWrite(server) {
             const currentDescription = listData.markdown_description || listData.markdown_content || listData.content || "";
             const timestamp = new Date().toISOString().split('T')[0]; // YYYY-MM-DD format
             let finalDescription;
-            if (replace_description !== undefined) {
-                finalDescription = replace_description;
+            if (description !== undefined) {
+                finalDescription = description;
             }
             else {
                 const separator = currentDescription.trim() ? "\n\n---\n" : "";
@@ -171,7 +171,7 @@ function registerListToolsWrite(server) {
                 content: [
                     {
                         type: "text",
-                        text: replace_description !== undefined
+                        text: description !== undefined
                             ? [
                                 `Successfully replaced the description of list "${listData.name}" (list_id: ${list_id}).`,
                                 `previous_description: ${currentDescription.trim() ? currentDescription : '(empty)'}`,

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,QAgErE;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,CAwH/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,QAgErE;AAuPD;;GAEG;AACH,wBAAsB,oBAAoB,CAAC,IAAI,EAAE,GAAG,EAAE,WAAW,CAAC,EAAE,GAAG,EAAE,EAAE,YAAY,GAAE,OAAe,GAAG,OAAO,CAAC,YAAY,CAAC,CAuJ/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) {
     // Workaround: SDK 1.27+ dual Zod v3/v4 type causes TS2589 on server.tool() generics
@@ -20,13 +21,13 @@ function registerTaskToolsRead(server, userData) {
             .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)"
+            message: "Must be an internal task ID (6-16 alphanumeric characters) or a custom task ID (e.g. SOI-4422)"
         })
-            .describe(`The task ID: either an internal ID (6+ alphanumeric characters like "869c4za0g") or a custom task ID (e.g. "SOI-4422"). Do not include prefixes like "#", "CU-" or URLs.`),
+            .describe(`The task ID: either an internal ID (6-16 alphanumeric characters like "869c4za0g") or a custom task ID (e.g. "SOI-4422"). Do not include prefixes like "#", "CU-" or URLs.`),
     }, {
         readOnlyHint: true
     }, async ({ id }) => {
-        // Resolve custom task ID to internal ID if needed
+        // Resolve custom task IDs (e.g. "SOI-4422") to internal IDs - no API call for internal IDs
         const resolvedId = await (0, utils_1.resolveTaskId)(id);
         // 1. Load base task content, comment events, and status change events in parallel
         const [taskDetailContentBlocks, commentEvents, statusChangeEvents] = await Promise.all([
@@ -101,28 +102,63 @@ 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 [];
-    }
-    const commentsData = await response.json();
-    if (!commentsData.comments || !Array.isArray(commentsData.comments)) {
-        console.error(`Unexpected comment data structure for task ${id}`);
-        return [];
-    }
-    const commentEvents = await Promise.all(commentsData.comments.map(async (comment) => {
+    // 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).
+    // A failing page keeps what was loaded before it; the gap is reported below.
+    const { comments, incomplete } = await (0, comments_1.fetchAllTopLevelComments)(id);
+    // 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 < replyCount) {
+                // The thread has more replies than were loaded (skipped over the budget
+                // cap, failed, or truncated) - never pretend it is empty or complete.
+                const missing = replyCount - replies.length;
+                contentBlocks.push({
+                    type: "text",
+                    text: replies.length === 0
+                        ? `↳ This comment has ${replyCount} repl${replyCount === 1 ? "y" : "ies"} that could not be loaded.`
+                        : `↳ ${missing} more repl${missing === 1 ? "y" : "ies"} of this comment could not be loaded (${replies.length} of ${replyCount} shown).`,
+                });
+            }
+        }
         return {
             date: comment.date, // String timestamp from ClickUp for sorting
-            contentBlocks: [headerBlock, ...commentBodyBlocks],
+            contentBlocks,
         };
     }));
+    if (incomplete) {
+        // Missing comments are always the OLDEST ones (the list is paged newest first),
+        // so the warning is dated 0 to sort before every loaded comment. Without it the
+        // reader would take a partial (or empty) history for the whole story.
+        const loaded = comments.length;
+        const text = incomplete.reason === "capped"
+            ? `WARNING: only the ${loaded} newest top-level comments are shown - ${incomplete.detail}.`
+            : loaded === 0
+                ? `WARNING: the comments of this task could not be loaded - ${incomplete.detail}`
+                : `WARNING: only the ${loaded} newest top-level comments are shown - older comments could not be fetched: ${incomplete.detail}`;
+        commentEvents.push({ date: "0", contentBlocks: [{ type: "text", text }] });
+    }
     return commentEvents;
 }
 async function loadTimeInStatusHistory(taskId) {
@@ -244,6 +280,8 @@ async function generateTaskMetadata(task, timeEntries, isDetailView = false) {
     }
     const metadataLines = [
         `task_id: ${task.id}`,
+        // The custom ID (e.g. "PQPS-1234") is what people quote; every tool accepts it
+        ...(task.custom_id ? [`custom_id: ${task.custom_id}`] : []),
         `task_url: ${task.url}`,
         `name: ${task.name}`,
         `status: ${task.status.status}`,
@@ -301,6 +339,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;AAwIpE,wBAAgB,sBAAsB,CAAC,MAAM,EAAE,SAAS,EAAE,QAAQ,EAAE,GAAG,QA4sBtE"}
+{"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;AA6JpE,wBAAgB,sBAAsB,CAAC,MAAM,EAAE,SAAS,EAAE,QAAQ,EAAE,GAAG,QAyxBtE"}