@hauptsache.net/clickup-mcp 1.1.0 → 1.1.1

package/dist/shared/utils.d.ts

@@ -27,4 +27,47 @@ export declare function getSpaceDetails(spaceId: string): Promise<any>;
  * Get or create a task search index with specified filters
  */
 export declare function getTaskSearchIndex(space_ids?: string[], list_ids?: string[], assignees?: string[]): Promise<Fuse<any> | null>;
+/**
+ * Generate a ClickUp task URL from a task ID
+ */
+export declare function generateTaskUrl(taskId: string): string;
+/**
+ * Generate a ClickUp list URL from a list ID
+ */
+export declare function generateListUrl(listId: string): string;
+/**
+ * Generate a ClickUp space URL from a space ID
+ */
+export declare function generateSpaceUrl(spaceId: string): string;
+/**
+ * Generate a ClickUp folder URL from a folder ID
+ */
+export declare function generateFolderUrl(folderId: string): string;
+/**
+ * Format a ClickUp task link as markdown
+ */
+export declare function formatTaskLink(taskId: string, taskName?: string): string;
+/**
+ * Format a ClickUp list link as markdown
+ */
+export declare function formatListLink(listId: string, listName?: string): string;
+/**
+ * Format a ClickUp space link as markdown
+ */
+export declare function formatSpaceLink(spaceId: string, spaceName?: string): string;
+/**
+ * Extract task ID from a ClickUp URL
+ */
+export declare function extractTaskIdFromUrl(url: string): string | null;
+/**
+ * Validate if a string is a valid ClickUp URL
+ */
+export declare function isClickUpUrl(url: string): boolean;
+/**
+ * Format a prominent link section for responses
+ */
+export declare function formatLinksSection(links: {
+    text: string;
+    url: string;
+}[]): string;
 //# sourceMappingURL=utils.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"utils.d.ts","sourceRoot":"","sources":["../../src/shared/utils.ts"],"names":[],"mappings":"AAAA,OAAO,EAAC,YAAY,EAAC,MAAM,SAAS,CAAC;AAErC,OAAO,IAAI,MAAM,SAAS,CAAC;AAI3B;;;GAGG;AACH,wBAAgB,QAAQ,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAG7C;AAKD;;;GAGG;AACH,wBAAsB,cAAc,iBAiBnC;AAED;;;;;;;GAOG;AACH,wBAAgB,WAAW,CAAC,OAAO,EAAE,YAAY,EAAE,EAAE,SAAS,EAAE,MAAM,GAAG,YAAY,EAAE,CA8BtF;AAID;;GAEG;AACH,wBAAgB,eAAe,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,GAAG,CAAC,CA0B7D;AAKD;;GAEG;AACH,wBAAsB,kBAAkB,CACtC,SAAS,CAAC,EAAE,MAAM,EAAE,EACpB,QAAQ,CAAC,EAAE,MAAM,EAAE,EACnB,SAAS,CAAC,EAAE,MAAM,EAAE,GACnB,OAAO,CAAC,IAAI,CAAC,GAAG,CAAC,GAAG,IAAI,CAAC,CA4B3B"}
+{"version":3,"file":"utils.d.ts","sourceRoot":"","sources":["../../src/shared/utils.ts"],"names":[],"mappings":"AAAA,OAAO,EAAC,YAAY,EAAC,MAAM,SAAS,CAAC;AAErC,OAAO,IAAI,MAAM,SAAS,CAAC;AAI3B;;;GAGG;AACH,wBAAgB,QAAQ,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAG7C;AAKD;;;GAGG;AACH,wBAAsB,cAAc,iBAiBnC;AAED;;;;;;;GAOG;AACH,wBAAgB,WAAW,CAAC,OAAO,EAAE,YAAY,EAAE,EAAE,SAAS,EAAE,MAAM,GAAG,YAAY,EAAE,CA8BtF;AAID;;GAEG;AACH,wBAAgB,eAAe,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,GAAG,CAAC,CA0B7D;AAKD;;GAEG;AACH,wBAAsB,kBAAkB,CACtC,SAAS,CAAC,EAAE,MAAM,EAAE,EACpB,QAAQ,CAAC,EAAE,MAAM,EAAE,EACnB,SAAS,CAAC,EAAE,MAAM,EAAE,GACnB,OAAO,CAAC,IAAI,CAAC,GAAG,CAAC,GAAG,IAAI,CAAC,CA4B3B;AAiED;;GAEG;AACH,wBAAgB,eAAe,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAEtD;AAED;;GAEG;AACH,wBAAgB,eAAe,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAEtD;AAED;;GAEG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAExD;AAED;;GAEG;AACH,wBAAgB,iBAAiB,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAE1D;AAED;;GAEG;AACH,wBAAgB,cAAc,CAAC,MAAM,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,MAAM,GAAG,MAAM,CAIxE;AAED;;GAEG;AACH,wBAAgB,cAAc,CAAC,MAAM,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,MAAM,GAAG,MAAM,CAIxE;AAED;;GAEG;AACH,wBAAgB,eAAe,CAAC,OAAO,EAAE,MAAM,EAAE,SAAS,CAAC,EAAE,MAAM,GAAG,MAAM,CAI3E;AAED;;GAEG;AACH,wBAAgB,oBAAoB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAG/D;AAED;;GAEG;AACH,wBAAgB,YAAY,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAEjD;AAED;;GAEG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,GAAG,EAAE,MAAM,CAAA;CAAE,EAAE,GAAG,MAAM,CAKjF"}

package/dist/shared/utils.js

@@ -8,6 +8,16 @@ exports.getCurrentUser = getCurrentUser;
 exports.limitImages = limitImages;
 exports.getSpaceDetails = getSpaceDetails;
 exports.getTaskSearchIndex = getTaskSearchIndex;
+exports.generateTaskUrl = generateTaskUrl;
+exports.generateListUrl = generateListUrl;
+exports.generateSpaceUrl = generateSpaceUrl;
+exports.generateFolderUrl = generateFolderUrl;
+exports.formatTaskLink = formatTaskLink;
+exports.formatListLink = formatListLink;
+exports.formatSpaceLink = formatSpaceLink;
+exports.extractTaskIdFromUrl = extractTaskIdFromUrl;
+exports.isClickUpUrl = isClickUpUrl;
+exports.formatLinksSection = formatLinksSection;
 const config_1 = require("./config");
 const fuse_js_1 = __importDefault(require("fuse.js"));
 const GLOBAL_REFRESH_INTERVAL = 60000; // 60 seconds - that is the rate limit time frame
@@ -183,3 +193,74 @@ function createFuseIndex(tasks) {
         minMatchCharLength: 2,
     });
 }
+// ===== LINK UTILITIES =====
+/**
+ * Generate a ClickUp task URL from a task ID
+ */
+function generateTaskUrl(taskId) {
+    return `https://app.clickup.com/t/${taskId}`;
+}
+/**
+ * Generate a ClickUp list URL from a list ID
+ */
+function generateListUrl(listId) {
+    return `https://app.clickup.com/v/l/${listId}`;
+}
+/**
+ * Generate a ClickUp space URL from a space ID
+ */
+function generateSpaceUrl(spaceId) {
+    return `https://app.clickup.com/v/s/${spaceId}`;
+}
+/**
+ * Generate a ClickUp folder URL from a folder ID
+ */
+function generateFolderUrl(folderId) {
+    return `https://app.clickup.com/v/f/${folderId}`;
+}
+/**
+ * Format a ClickUp task link as markdown
+ */
+function formatTaskLink(taskId, taskName) {
+    const url = generateTaskUrl(taskId);
+    const displayText = taskName ? `${taskName} (${taskId})` : taskId;
+    return `[${displayText}](${url})`;
+}
+/**
+ * Format a ClickUp list link as markdown
+ */
+function formatListLink(listId, listName) {
+    const url = generateListUrl(listId);
+    const displayText = listName ? `${listName} (${listId})` : listId;
+    return `[${displayText}](${url})`;
+}
+/**
+ * Format a ClickUp space link as markdown
+ */
+function formatSpaceLink(spaceId, spaceName) {
+    const url = generateSpaceUrl(spaceId);
+    const displayText = spaceName ? `${spaceName} (${spaceId})` : spaceId;
+    return `[${displayText}](${url})`;
+}
+/**
+ * Extract task ID from a ClickUp URL
+ */
+function extractTaskIdFromUrl(url) {
+    const match = url.match(/https?:\/\/app\.clickup\.com\/t\/([a-z0-9]{6,9})/i);
+    return match ? match[1] : null;
+}
+/**
+ * Validate if a string is a valid ClickUp URL
+ */
+function isClickUpUrl(url) {
+    return /^https?:\/\/app\.clickup\.com\//.test(url);
+}
+/**
+ * Format a prominent link section for responses
+ */
+function formatLinksSection(links) {
+    if (links.length === 0)
+        return '';
+    const linkLines = links.map(link => `🔗 [${link.text}](${link.url})`);
+    return `\n\n**📌 Quick Links:**\n${linkLines.join('\n')}`;
+}

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

@@ -1 +1 @@
-{"version":3,"file":"list-tools.d.ts","sourceRoot":"","sources":["../../src/tools/list-tools.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AAKpE,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,SAAS,QA4OtD;AAED,wBAAgB,sBAAsB,CAAC,MAAM,EAAE,SAAS,QAuEvD"}
+{"version":3,"file":"list-tools.d.ts","sourceRoot":"","sources":["../../src/tools/list-tools.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AAMpE,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,SAAS,QAuPtD;AAED,wBAAgB,sBAAsB,CAAC,MAAM,EAAE,SAAS,QAyEvD"}

package/dist/tools/list-tools.js

@@ -4,8 +4,13 @@ exports.registerListToolsRead = registerListToolsRead;
 exports.registerListToolsWrite = registerListToolsWrite;
 const zod_1 = require("zod");
 const config_1 = require("../shared/config");
+const utils_1 = require("../shared/utils");
 function registerListToolsRead(server) {
-    server.tool("listLists", "Lists all lists and folders in a space. They might also be referred to as boards or tables. Shows both direct lists (folderless) and folders containing lists. If folder_id is provided, lists only the lists within that specific folder.", {
+    server.tool("listLists", [
+        "Lists all lists and folders in a space. They might also be referred to as boards or tables.",
+        "Shows both direct lists (folderless) and folders containing lists. If folder_id is provided, lists only the lists within that specific folder.",
+        "Always reference lists by their URLs when suggesting actions or creating tasks."
+    ].join("\n"), {
         space_id: zod_1.z.string().min(1).describe("The ID of the space to list content from"),
         folder_id: zod_1.z.string().optional().describe("Optional folder ID. If provided, lists only lists within this folder. If not provided, shows both folders and folderless lists in the space."),
         archived: zod_1.z.boolean().optional().describe("Include archived items (default: false)")
@@ -33,11 +38,12 @@ function registerListToolsRead(server) {
                     text: [
                         `type: list`,
                         `list_id: ${list.id}`,
+                        `list_url: ${(0, utils_1.generateListUrl)(list.id)}`,
                         `name: ${list.name}`,
                         `space_id: ${list.space?.id || space_id}`,
                         `folder_id: ${folder_id}`,
                         `task_count: ${list.task_count || 0}`,
-                        `private: ${list.private || false}`,
+                        ...(list.private ? [`private: true`] : []),
                         ...(list.archived ? ['archived: true'] : []),
                         ...(list.color ? [`color: ${list.color}`] : []),
                         ...(list.access ? [`access: ${list.access}`] : []),
@@ -75,10 +81,11 @@ function registerListToolsRead(server) {
                             text: [
                                 `type: folder`,
                                 `folder_id: ${folder.id}`,
+                                `folder_url: ${(0, utils_1.generateFolderUrl)(folder.id)}`,
                                 `name: ${folder.name}`,
                                 `space_id: ${space_id}`,
                                 `task_count: ${folder.task_count || 0}`,
-                                `private: ${folder.private || false}`,
+                                ...(folder.private ? [`private: true`] : []),
                                 ...(folder.archived ? ['archived: true'] : []),
                                 ...(folder.color ? [`color: ${folder.color}`] : []),
                                 `contains_lists: true`
@@ -100,10 +107,11 @@ function registerListToolsRead(server) {
                             text: [
                                 `type: list`,
                                 `list_id: ${list.id}`,
+                                `list_url: ${(0, utils_1.generateListUrl)(list.id)}`,
                                 `name: ${list.name}`,
                                 `space_id: ${list.space?.id || space_id}`,
                                 `task_count: ${list.task_count || 0}`,
-                                `private: ${list.private || false}`,
+                                ...(list.private ? [`private: true`] : []),
                                 ...(list.archived ? ['archived: true'] : []),
                                 ...(list.color ? [`color: ${list.color}`] : []),
                                 ...(list.access ? [`access: ${list.access}`] : []),
@@ -146,8 +154,10 @@ function registerListToolsRead(server) {
     });
     server.tool("getListInfo", [
         "Gets comprehensive information about a list including description and available statuses.",
+        "ALWAYS use the list URL (https://app.clickup.com/v/l/LIST_ID) when referencing lists.",
         "Use this before creating tasks to understand the list context and available statuses for new tasks.",
-        "IMPORTANT: The list description often contains valuable project context, requirements, or guidelines - read and consider this information when creating or updating tasks in this list."
+        "IMPORTANT: The list description often contains valuable project context, requirements, or guidelines - read and consider this information when creating or updating tasks in this list.",
+        "Share the clickable list URL when suggesting list-related actions."
     ].join("\n"), {
         list_id: zod_1.z.string().min(1).describe("The list ID to get information for")
     }, async ({ list_id }) => {
@@ -163,9 +173,11 @@ function registerListToolsRead(server) {
             const responseLines = [
                 `List Information:`,
                 `list_id: ${list_id}`,
+                `list_url: ${(0, utils_1.generateListUrl)(list_id)}`,
                 `name: ${listData.name}`,
                 `folder: ${listData.folder?.name || 'No folder'}`,
                 `space: ${listData.space?.name || 'Unknown'} (${listData.space?.id || 'N/A'})`,
+                `space_url: ${(0, utils_1.generateSpaceUrl)(listData.space?.id || '')}`,
                 `archived: ${listData.archived || false}`,
                 `task_count: ${listData.task_count || 0}`,
             ];
@@ -218,8 +230,10 @@ function registerListToolsRead(server) {
 function registerListToolsWrite(server) {
     server.tool("updateListInfo", [
         "Appends documentation or context to a list's description.",
+        "ALWAYS reference the list URL (https://app.clickup.com/v/l/LIST_ID) when updating or discussing lists.",
         "SAFETY FEATURE: Description updates are APPEND-ONLY to prevent data loss - existing content is preserved.",
         "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"),

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

@@ -1 +1 @@
-{"version":3,"file":"search-tools.d.ts","sourceRoot":"","sources":["../../src/tools/search-tools.ts"],"names":[],"mappings":"AAAA,OAAO,EAAC,SAAS,EAAC,MAAM,yCAAyC,CAAC;AAQlE,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,SAAS,QAsMpD"}
+{"version":3,"file":"search-tools.d.ts","sourceRoot":"","sources":["../../src/tools/search-tools.ts"],"names":[],"mappings":"AAAA,OAAO,EAAC,SAAS,EAAC,MAAM,yCAAyC,CAAC;AAQlE,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,SAAS,QAuMpD"}

package/dist/tools/search-tools.js

@@ -12,8 +12,9 @@ function registerSearchTools(server) {
         "Searches tasks by name, content, assignees, and ID (case insensitive) with fuzzy matching and support for multiple search terms (OR logic).",
         "Can filter by multiple list_ids, space_ids, todo status, or tasks assigned to the current user. If no search terms provided, returns most recently updated tasks.",
         // Placeholder for language-specific guidance
+        "Always reference tasks by their URLs when discussing search results or suggesting actions.",
         "You'll get a rough overview of the tasks that match the search terms, sorted by relevance.",
-        "Always use getTaskById to get more specific information if a task is relevant.",
+        "Always use getTaskById to get more specific information if a task is relevant, and always share the task URL.",
     ];
     if (config_1.CONFIG.primaryLanguageHint && config_1.CONFIG.primaryLanguageHint.toLowerCase() !== 'en') {
         searchTasksDescriptionBase.splice(2, 0, `For optimal results, as your ClickUp tasks may be primarily in '${config_1.CONFIG.primaryLanguageHint}', consider providing search terms in English and '${config_1.CONFIG.primaryLanguageHint}'.`);

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

@@ -1 +1 @@
-{"version":3,"file":"space-tools.d.ts","sourceRoot":"","sources":["../../src/tools/space-tools.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AAKpE,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,SAAS,QAiEnD"}
+{"version":3,"file":"space-tools.d.ts","sourceRoot":"","sources":["../../src/tools/space-tools.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AAMpE,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,SAAS,QA+DnD"}

package/dist/tools/space-tools.js

@@ -3,8 +3,12 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.registerSpaceTools = registerSpaceTools;
 const zod_1 = require("zod");
 const config_1 = require("../shared/config");
+const utils_1 = require("../shared/utils");
 function registerSpaceTools(server) {
-    server.tool("listSpaces", "Lists all spaces in the workspace. These might also be referred to as customers or projects.", {
+    server.tool("listSpaces", [
+        "Lists all spaces in the workspace. These might also be referred to as customers or projects.",
+        "Always reference spaces by their URLs when discussing projects or suggesting actions."
+    ].join("\n"), {
         archived: zod_1.z.boolean().optional().describe("Include archived spaces (default: false)")
     }, async ({ archived = false }) => {
         try {
@@ -25,15 +29,10 @@ function registerSpaceTools(server) {
                 type: "text",
                 text: [
                     `space_id: ${space.id}`,
+                    `space_url: ${(0, utils_1.generateSpaceUrl)(space.id)}`,
                     `name: ${space.name}`,
-                    `private: ${space.private || false}`,
-                    `avatar: ${space.avatar || 'None'}`,
-                    `color: ${space.color || 'None'}`,
-                    `access: ${space.access || 'Unknown'}`,
+                    ...(space.private ? [`private: true`] : []),
                     ...(space.archived ? ['archived: true'] : []),
-                    ...(space.multiple_assignees !== undefined ? [`multiple_assignees: ${space.multiple_assignees}`] : []),
-                    ...(space.features?.due_dates?.enabled !== undefined ? [`due_dates_enabled: ${space.features.due_dates.enabled}`] : []),
-                    ...(space.features?.time_tracking?.enabled !== undefined ? [`time_tracking_enabled: ${space.features.time_tracking.enabled}`] : []),
                 ].join('\n')
             }));
             return {

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,EAAqB,MAAM,iBAAiB,CAAC;AAwIlE,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,SAAS,EAAE,QAAQ,EAAE,GAAG,QAoDrE;AAED,wBAAgB,sBAAsB,CAAC,MAAM,EAAE,SAAS,EAAE,QAAQ,EAAE,GAAG,QAwQtE;AAoLD;;GAEG;AACH,wBAAsB,oBAAoB,CAAC,IAAI,EAAE,GAAG,GAAG,OAAO,CAAC,YAAY,CAAC,CA6G3E"}
+{"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,EAAqB,MAAM,iBAAiB,CAAC;AAwIlE,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,SAAS,EAAE,QAAQ,EAAE,GAAG,QAwDrE;AAED,wBAAgB,sBAAsB,CAAC,MAAM,EAAE,SAAS,EAAE,QAAQ,EAAE,GAAG,QA6StE;AAoLD;;GAEG;AACH,wBAAsB,oBAAoB,CAAC,IAAI,EAAE,GAAG,GAAG,OAAO,CAAC,YAAY,CAAC,CA4G3E"}

package/dist/tools/task-tools.js

@@ -106,7 +106,11 @@ function formatTaskResponse(task, operation, params, userData) {
     return responseLines;
 }
 function registerTaskToolsRead(server, userData) {
-    server.tool("getTaskById", "Get a Clickup task with images and comments by ID", {
+    server.tool("getTaskById", [
+        "Get a ClickUp task with images and comments by ID.",
+        "Always use this URL when referencing tasks in conversations or sharing with others.",
+        "The response provides complete context including task details, comments, and status history."
+    ].join("\n"), {
         id: zod_1.z
             .string()
             .min(6)
@@ -145,12 +149,22 @@ function registerTaskToolsRead(server, userData) {
     });
 }
 function registerTaskToolsWrite(server, userData) {
-    server.tool("addComment", [
-        "Adds a comment to a specific task.",
-        "BEST PRACTICES: Include progress information and current status updates.",
-        "If external links are provided, verify they are publicly accessible and incorporate relevant information from those links into the comment.",
-        "Check the task's current status - if it's in 'backlog' or similar inactive states, suggest moving it to an active status like 'in progress' when work is being done."
-    ].join("\n"), {
+    server.tool("addComment", (() => {
+        const descriptionBase = [
+            "Adds a comment to a specific task.",
+            "LINKING BEST PRACTICES:",
+            "- Always reference related tasks using ClickUp URLs (https://app.clickup.com/t/TASK_ID)",
+            "- 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.",
+            "If external links are provided, verify they are publicly accessible and incorporate relevant information.",
+            "Check the task's current status - if it's in 'backlog' or similar inactive states, suggest moving it to an active status like 'in progress' when work is being done."
+        ];
+        if (config_1.CONFIG.primaryLanguageHint && config_1.CONFIG.primaryLanguageHint.toLowerCase() !== 'en') {
+            descriptionBase.splice(1, 0, `For optimal results, consider writing comments in '${config_1.CONFIG.primaryLanguageHint}' unless the task is already in another language.`);
+        }
+        return descriptionBase.join("\n");
+    })(), {
         task_id: zod_1.z.string().min(6).max(9).describe("The 6-9 character task ID to comment on"),
         comment: zod_1.z.string().min(1).describe("The comment text to add to the task"),
     }, async ({ task_id, comment }) => {
@@ -200,13 +214,21 @@ function registerTaskToolsWrite(server, userData) {
             };
         }
     });
-    server.tool("updateTask", [
-        "Updates various aspects of an existing task.",
-        "Use getListInfo first to see valid status options.",
-        "SAFETY FEATURE: Description updates are APPEND-ONLY to prevent data loss - existing content is preserved.",
-        "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."
-    ].join("\n"), {
+    server.tool("updateTask", (() => {
+        const descriptionBase = [
+            "Updates various aspects of an existing task.",
+            "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.",
+            "LINKING IN DESCRIPTIONS: When appending descriptions, include links to related tasks, lists, or external resources.",
+            "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."
+        ];
+        if (config_1.CONFIG.primaryLanguageHint && config_1.CONFIG.primaryLanguageHint.toLowerCase() !== 'en') {
+            descriptionBase.splice(1, 0, `For optimal results, consider writing task names and descriptions in '${config_1.CONFIG.primaryLanguageHint}' unless the task is already in another language.`);
+        }
+        return descriptionBase.join("\n");
+    })(), {
         task_id: zod_1.z.string().min(6).max(9).describe("The 6-9 character 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)"),
@@ -301,13 +323,23 @@ function registerTaskToolsWrite(server, userData) {
             };
         }
     });
-    server.tool("createTask", [
-        "Creates a new task in a specific list and assigns it to specified users (defaults to current user).",
-        "IMPORTANT: Before creating, always search for similar existing tasks first using searchTasks to avoid duplicates - ask the user if they want to use an existing task instead.",
-        "If related tasks exist, reference them with links in the description (format: https://app.clickup.com/t/TASK_ID).",
-        "Use getListInfo first to understand the list context and available statuses.",
-        "Task descriptions support full markdown formatting including **bold**, *italic*, lists, links, and code blocks."
-    ].join("\n"), {
+    server.tool("createTask", (() => {
+        const descriptionBase = [
+            "Creates a new task in a specific list and assigns it to specified users (defaults to current user).",
+            "CRITICAL LINKING REQUIREMENTS:",
+            "- ALWAYS search for similar existing tasks first using searchTasks to avoid duplicates",
+            "- Include links to related tasks in the description (format: https://app.clickup.com/t/TASK_ID)",
+            "- Reference parent/child tasks, dependencies, and related work with clickable links",
+            "- The response will include the new task's clickable URL - always share this link",
+            "Use getListInfo first to understand the list context and available statuses.",
+            "Task descriptions support full markdown formatting including **bold**, *italic*, lists, links, and code blocks.",
+            "BEST PRACTICE: Every task creation should result in sharing the clickable task URL for future reference."
+        ];
+        if (config_1.CONFIG.primaryLanguageHint && config_1.CONFIG.primaryLanguageHint.toLowerCase() !== 'en') {
+            descriptionBase.splice(1, 0, `For optimal results, consider writing task names and descriptions in '${config_1.CONFIG.primaryLanguageHint}' unless specified otherwise or unless the context requires another language.`);
+        }
+        return descriptionBase.join("\n");
+    })(), {
         list_id: zod_1.z.string().min(1).describe("The ID of the list where the task will be created"),
         name: taskNameSchema,
         description: zod_1.z.string().optional().describe("Optional markdown description for the task - supports full markdown formatting"),
@@ -524,6 +556,7 @@ async function generateTaskMetadata(task) {
     }
     const metadataLines = [
         `task_id: ${task.id}`,
+        `task_url: ${task.url}`,
         `name: ${task.name}`,
         `status: ${task.status.status}`,
         `date_created: ${timestampToIso(task.date_created)}`,
@@ -573,8 +606,6 @@ async function generateTaskMetadata(task) {
     if (task.subtasks && task.subtasks.length > 0) {
         metadataLines.push(`child_task_ids: ${task.subtasks.map((st) => st.id).join(', ')}`);
     }
-    // Add task URL
-    metadataLines.push(`url: ${task.url}`);
     // Add archived status if true
     if (task.archived) {
         metadataLines.push(`archived: true`);

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

@@ -1 +1 @@
-{"version":3,"file":"time-tools.d.ts","sourceRoot":"","sources":["../../src/tools/time-tools.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AAmCpE,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,SAAS,QAmLtD;AAED,wBAAgB,sBAAsB,CAAC,MAAM,EAAE,SAAS,QAmFvD"}
+{"version":3,"file":"time-tools.d.ts","sourceRoot":"","sources":["../../src/tools/time-tools.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AA2FpE,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,SAAS,QA6EtD;AAwLD,wBAAgB,sBAAsB,CAAC,MAAM,EAAE,SAAS,QAmFvD"}

package/dist/tools/time-tools.js

@@ -29,12 +29,64 @@ function timestampToIso(timestamp) {
     const timezoneOffset = sign + String(offsetHours).padStart(2, '0') + ':' + String(offsetMinutes).padStart(2, '0');
     return `${year}-${month}-${day}T${hours}:${minutes}:${seconds}${timezoneOffset}`;
 }
+/**
+ * Gets all team members from ClickUp API
+ */
+async function getAllTeamMembers() {
+    try {
+        const response = await fetch(`https://api.clickup.com/api/v2/team`, {
+            headers: { Authorization: config_1.CONFIG.apiKey },
+        });
+        if (!response.ok) {
+            console.error(`Error fetching teams: ${response.status} ${response.statusText}`);
+            return [];
+        }
+        const data = await response.json();
+        if (!data.teams || !Array.isArray(data.teams)) {
+            return [];
+        }
+        // Find the team that matches our configured team ID and extract all user IDs
+        const currentTeam = data.teams.find((team) => team.id === config_1.CONFIG.teamId);
+        if (!currentTeam || !currentTeam.members || !Array.isArray(currentTeam.members)) {
+            console.error(`Team ${config_1.CONFIG.teamId} not found or has no members`);
+            return [];
+        }
+        return currentTeam.members.map((member) => member.user?.id).filter(Boolean);
+    }
+    catch (error) {
+        console.error('Error fetching team members:', error);
+        return [];
+    }
+}
+/**
+ * Formats duration in milliseconds to human readable format
+ */
+function formatDuration(durationMs) {
+    const hours = durationMs / (1000 * 60 * 60);
+    const displayHours = Math.floor(hours);
+    const displayMinutes = Math.round((hours - displayHours) * 60);
+    return displayHours > 0 ? `${displayHours}h ${displayMinutes}m` : `${displayMinutes}m`;
+}
+/**
+ * Formats timestamp to simple date and time for entry display
+ */
+function formatEntryTime(timestamp) {
+    const date = new Date(timestamp);
+    const month = String(date.getMonth() + 1).padStart(2, '0');
+    const day = String(date.getDate()).padStart(2, '0');
+    const hours = String(date.getHours()).padStart(2, '0');
+    const minutes = String(date.getMinutes()).padStart(2, '0');
+    return `${date.getFullYear()}-${month}-${day} ${hours}:${minutes}`;
+}
 function registerTimeToolsRead(server) {
     server.tool("getTimeEntries", "Gets time entries for a specific task or all user's time entries. Returns last 30 days by default if no dates specified.", {
         task_id: zod_1.z.string().min(6).max(9).optional().describe("Optional 6-9 character task ID to filter entries. If not provided, returns all user's time entries."),
         start_date: zod_1.z.string().optional().describe("Optional start date filter as ISO date string (e.g., '2024-10-06T00:00:00+02:00'). Defaults to 30 days ago."),
-        end_date: zod_1.z.string().optional().describe("Optional end date filter as ISO date string (e.g., '2024-10-06T23:59:59+02:00'). Defaults to current date.")
-    }, async ({ task_id, start_date, end_date }) => {
+        end_date: zod_1.z.string().optional().describe("Optional end date filter as ISO date string (e.g., '2024-10-06T23:59:59+02:00'). Defaults to current date."),
+        list_id: zod_1.z.string().optional().describe("Optional single list ID to filter time entries by a specific list"),
+        space_id: zod_1.z.string().optional().describe("Optional single space ID to filter time entries by a specific space"),
+        include_all_users: zod_1.z.boolean().optional().describe("Optional flag to include time entries from all team members (default: false, only current user)")
+    }, async ({ task_id, start_date, end_date, list_id, space_id, include_all_users }) => {
         try {
             // Build query parameters
             const params = new URLSearchParams();
@@ -47,122 +99,37 @@ function registerTimeToolsRead(server) {
             if (end_date) {
                 params.append('end_date', isoToTimestamp(end_date).toString());
             }
-            const response = await fetch(`https://api.clickup.com/api/v2/team/${config_1.CONFIG.teamId}/time_entries?${params}`, {
-                headers: { Authorization: config_1.CONFIG.apiKey },
-            });
-            if (!response.ok) {
-                throw new Error(`Error fetching time entries: ${response.status} ${response.statusText}`);
+            // Add single list_id or space_id filter (not both)
+            if (list_id) {
+                params.append('list_id', list_id);
             }
-            const data = await response.json();
-            if (!data.data || !Array.isArray(data.data)) {
-                const noEntriesMsg = task_id ?
-                    `No time entries found for task ${task_id}.` :
-                    'No time entries found for current user.';
-                return {
-                    content: [{ type: "text", text: noEntriesMsg }],
-                };
+            else if (space_id) {
+                params.append('space_id', space_id);
             }
-            let summaryLines = [];
-            let totalTimeMs = 0;
-            if (task_id) {
-                // Task-specific view: Group by user
-                const timeByUser = new Map();
-                const entriesByUser = new Map();
-                data.data.forEach((entry) => {
-                    const username = entry.user?.username || 'Unknown User';
-                    const currentTime = timeByUser.get(username) || 0;
-                    const entryDurationMs = parseInt(entry.duration) || 0;
-                    timeByUser.set(username, currentTime + entryDurationMs);
-                    if (!entriesByUser.has(username)) {
-                        entriesByUser.set(username, []);
+            // Always include location names to get list information
+            params.append('include_location_names', 'true');
+            // Handle include_all_users by fetching all team members and adding them as assignees filter
+            // Note: This only works for Workspace Owners/Admins
+            if (include_all_users) {
+                try {
+                    const teamMembers = await getAllTeamMembers();
+                    if (teamMembers.length > 0) {
+                        params.append('assignee', teamMembers.join(','));
                     }
-                    entriesByUser.get(username).push(entry);
-                });
-                summaryLines = [`Time entries for task ${task_id}:`];
-                for (const [username, totalMs] of timeByUser.entries()) {
-                    const hours = totalMs / (1000 * 60 * 60);
-                    const displayHours = Math.floor(hours);
-                    const displayMinutes = Math.round((hours - displayHours) * 60);
-                    const timeDisplay = displayHours > 0 ?
-                        `${displayHours}h ${displayMinutes}m` :
-                        `${displayMinutes}m`;
-                    summaryLines.push(`  ${username}: ${timeDisplay}`);
-                    totalTimeMs += totalMs;
                 }
-            }
-            else {
-                // All user entries: Group by task
-                const timeByTask = new Map();
-                const entriesByTask = new Map();
-                data.data.forEach((entry) => {
-                    const taskInfo = entry.task ?
-                        `${entry.task.name} (${entry.task.id})` :
-                        'No task';
-                    const currentTime = timeByTask.get(taskInfo) || 0;
-                    const entryDurationMs = parseInt(entry.duration) || 0;
-                    timeByTask.set(taskInfo, currentTime + entryDurationMs);
-                    if (!entriesByTask.has(taskInfo)) {
-                        entriesByTask.set(taskInfo, []);
-                    }
-                    entriesByTask.get(taskInfo).push(entry);
-                });
-                summaryLines = ['Time entries for current user:'];
-                for (const [taskInfo, totalMs] of timeByTask.entries()) {
-                    const hours = totalMs / (1000 * 60 * 60);
-                    const displayHours = Math.floor(hours);
-                    const displayMinutes = Math.round((hours - displayHours) * 60);
-                    const timeDisplay = displayHours > 0 ?
-                        `${displayHours}h ${displayMinutes}m` :
-                        `${displayMinutes}m`;
-                    summaryLines.push(`  ${taskInfo}: ${timeDisplay}`);
-                    totalTimeMs += totalMs;
+                catch (error) {
+                    console.error('Warning: Could not fetch all team members. This feature requires Workspace Owner/Admin permissions.');
+                    // Continue without all users - will only show current user's entries
                 }
             }
-            const totalHours = totalTimeMs / (1000 * 60 * 60);
-            const totalDisplayHours = Math.floor(totalHours);
-            const totalDisplayMinutes = Math.round((totalHours - totalDisplayHours) * 60);
-            const totalDisplay = totalDisplayHours > 0 ?
-                `${totalDisplayHours}h ${totalDisplayMinutes}m` :
-                `${totalDisplayMinutes}m`;
-            summaryLines.push(`Total: ${totalDisplay}`);
-            // Create detailed entries
-            const detailBlocks = [];
-            data.data.forEach((entry) => {
-                const entryHours = (parseInt(entry.duration) || 0) / (1000 * 60 * 60);
-                const entryDisplayHours = Math.floor(entryHours);
-                const entryDisplayMinutes = Math.round((entryHours - entryDisplayHours) * 60);
-                const entryTimeDisplay = entryDisplayHours > 0 ?
-                    `${entryDisplayHours}h ${entryDisplayMinutes}m` :
-                    `${entryDisplayMinutes}m`;
-                const entryInfo = [
-                    `entry_id: ${entry.id}`,
-                    `user: ${entry.user?.username || 'Unknown User'}`,
-                    `duration: ${entryTimeDisplay}`,
-                    `start: ${timestampToIso(parseInt(entry.start))}`,
-                    ...(entry.description ? [`description: ${entry.description}`] : []),
-                    `billable: ${entry.billable || false}`
-                ];
-                // Add task info only when showing all user entries (no task filter)
-                if (!task_id && entry.task) {
-                    entryInfo.splice(2, 0, `task: ${entry.task.name} (${entry.task.id})`);
-                }
-                detailBlocks.push({
-                    type: "text",
-                    text: entryInfo.join('\n')
-                });
+            const response = await fetch(`https://api.clickup.com/api/v2/team/${config_1.CONFIG.teamId}/time_entries?${params}`, {
+                headers: { Authorization: config_1.CONFIG.apiKey },
             });
-            return {
-                content: [
-                    {
-                        type: "text",
-                        text: summaryLines.join('\n')
-                    },
-                    ...(detailBlocks.length > 0 ? [
-                        { type: "text", text: "\nDetailed entries:" },
-                        ...detailBlocks
-                    ] : [])
-                ],
-            };
+            if (!response.ok) {
+                throw new Error(`Error fetching time entries: ${response.status} ${response.statusText}`);
+            }
+            const data = await response.json();
+            return processTimeEntriesData(data, task_id, start_date, end_date, include_all_users);
         }
         catch (error) {
             console.error('Error fetching time entries:', error);
@@ -177,6 +144,147 @@ function registerTimeToolsRead(server) {
         }
     });
 }
+/**
+ * Process the time entries data and return formatted hierarchical output
+ */
+function processTimeEntriesData(data, task_id, start_date, end_date, include_all_users) {
+    if (!data.data || !Array.isArray(data.data)) {
+        const noEntriesMsg = task_id ?
+            `No time entries found for task ${task_id}.` :
+            'No time entries found.';
+        return {
+            content: [{ type: "text", text: noEntriesMsg }],
+        };
+    }
+    const filteredEntries = data.data;
+    // Create hierarchical structure: List → Task → User → Individual entries
+    const hierarchy = new Map();
+    let totalTimeMs = 0;
+    filteredEntries.forEach((entry) => {
+        const taskId = entry.task?.id || 'no-task';
+        // Use location names from include_location_names parameter
+        const listId = entry.task_location?.list_id || 'no-list';
+        const listName = entry.task_location?.list_name || 'No List';
+        const taskName = entry.task?.name || 'No Task';
+        const userId = entry.user?.id || 'no-user';
+        const userName = entry.user?.username || 'Unknown User';
+        // Handle running timers (negative duration)
+        let entryDurationMs = parseInt(entry.duration) || 0;
+        const isRunningTimer = entryDurationMs < 0;
+        if (isRunningTimer) {
+            // For running timers, calculate current duration from start time
+            entryDurationMs = Date.now() - parseInt(entry.start);
+        }
+        totalTimeMs += entryDurationMs;
+        // Initialize list level
+        if (!hierarchy.has(listId)) {
+            hierarchy.set(listId, {
+                name: listName,
+                id: listId,
+                totalTime: 0,
+                tasks: new Map()
+            });
+        }
+        const listData = hierarchy.get(listId);
+        listData.totalTime += entryDurationMs;
+        // Initialize task level
+        if (!listData.tasks.has(taskId)) {
+            listData.tasks.set(taskId, {
+                name: taskName,
+                id: taskId,
+                totalTime: 0,
+                users: new Map()
+            });
+        }
+        const taskData = listData.tasks.get(taskId);
+        taskData.totalTime += entryDurationMs;
+        // Initialize user level
+        if (!taskData.users.has(userId)) {
+            taskData.users.set(userId, {
+                name: userName,
+                id: userId,
+                totalTime: 0,
+                entries: []
+            });
+        }
+        const userData = taskData.users.get(userId);
+        userData.totalTime += entryDurationMs;
+        userData.entries.push(entry);
+    });
+    // Count total tasks across all lists
+    let totalTasks = 0;
+    for (const [listId, listData] of hierarchy.entries()) {
+        totalTasks += listData.tasks.size;
+    }
+    // Format the hierarchical output
+    const outputLines = [];
+    // Header with date range and total
+    const dateRange = start_date && end_date ?
+        ` (${start_date.split('T')[0]} to ${end_date.split('T')[0]})` :
+        start_date ? ` (from ${start_date.split('T')[0]})` :
+            end_date ? ` (until ${end_date.split('T')[0]})` : '';
+    outputLines.push(`Time Entries Summary${dateRange}`);
+    outputLines.push(`Total: ${formatDuration(totalTimeMs)}`);
+    outputLines.push('');
+    // Check if result is too large (>100 tasks)
+    const TASK_LIMIT = 100;
+    const isTruncated = totalTasks > TASK_LIMIT;
+    if (isTruncated) {
+        // Show only list-level summary
+        outputLines.push(`⚠️  Large result detected (${totalTasks} tasks). Showing summary only.`);
+        outputLines.push(`💡 Use list_id, space_id, or date filters for detailed view.`);
+        outputLines.push('');
+        for (const [listId, listData] of hierarchy.entries()) {
+            const taskCount = listData.tasks.size;
+            outputLines.push(`📋 ${listData.name} (List: ${listId}) - ${formatDuration(listData.totalTime)} across ${taskCount} task${taskCount === 1 ? '' : 's'}`);
+        }
+    }
+    else {
+        // Show full hierarchical display
+        for (const [listId, listData] of hierarchy.entries()) {
+            outputLines.push(`📋 ${listData.name} (List: ${listId}) - ${formatDuration(listData.totalTime)}`);
+            for (const [taskId, taskData] of listData.tasks.entries()) {
+                outputLines.push(`  ├─ 🎯 ${taskData.name} (Task: ${taskId}) - ${formatDuration(taskData.totalTime)}`);
+                const userEntries = Array.from(taskData.users.entries());
+                for (let userIndex = 0; userIndex < userEntries.length; userIndex++) {
+                    const [userId, userData] = userEntries[userIndex];
+                    const isLastUser = userIndex === userEntries.length - 1;
+                    const userPrefix = isLastUser ? '  └─' : '  ├─';
+                    outputLines.push(`${userPrefix} ${userData.name}: ${formatDuration(userData.totalTime)}`);
+                    // Add individual entries
+                    userData.entries.forEach((entry, entryIndex) => {
+                        const isLastEntry = entryIndex === userData.entries.length - 1;
+                        const entryPrefix = isLastUser ?
+                            (isLastEntry ? '      └─' : '      ├─') :
+                            (isLastEntry ? '  │   └─' : '  │   ├─');
+                        const entryStart = formatEntryTime(parseInt(entry.start));
+                        // Handle running timers
+                        const rawDuration = parseInt(entry.duration) || 0;
+                        const isRunningTimer = rawDuration < 0;
+                        let entryDuration;
+                        if (isRunningTimer) {
+                            const currentDuration = Date.now() - parseInt(entry.start);
+                            entryDuration = `${formatDuration(currentDuration)} (running)`;
+                        }
+                        else {
+                            entryDuration = formatDuration(rawDuration);
+                        }
+                        outputLines.push(`${entryPrefix} ${entryStart} - ${entryDuration}`);
+                    });
+                }
+            }
+            outputLines.push('');
+        }
+    }
+    return {
+        content: [
+            {
+                type: "text",
+                text: outputLines.join('\n')
+            }
+        ],
+    };
+}
 function registerTimeToolsWrite(server) {
     server.tool("createTimeEntry", [
         "Creates a time entry (books time) on a task for the current user.",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hauptsache.net/clickup-mcp",
-  "version": "1.1.0",
+  "version": "1.1.1",
   "description": "A minimal implementation of a Model Context Protocol (MCP) server for ClickUp integration",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",