@hauptsache.net/clickup-mcp 1.1.0 → 1.2.0

package/dist/tools/time-tools.js

@@ -4,6 +4,7 @@ exports.registerTimeToolsRead = registerTimeToolsRead;
 exports.registerTimeToolsWrite = registerTimeToolsWrite;
 const zod_1 = require("zod");
 const config_1 = require("../shared/config");
+const utils_1 = require("../shared/utils");
 /**
  * Converts ISO date string to Unix timestamp in milliseconds
  */
@@ -29,12 +30,35 @@ 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}`;
 }
+/**
+ * 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 +71,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 (0, utils_1.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 +116,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,7 +1,7 @@
 {
   "name": "@hauptsache.net/clickup-mcp",
-  "version": "1.1.0",
-  "description": "A minimal implementation of a Model Context Protocol (MCP) server for ClickUp integration",
+  "version": "1.2.0",
+  "description": "Transform your AI assistant into a powerful ClickUp integration for both agentic coding and productivity management. Enables seamless task context sharing, intelligent search, time tracking, and complete project management workflows.",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "bin": "dist/index.js",
@@ -23,9 +23,19 @@
     "mcp",
     "model-context-protocol",
     "llm",
-    "ai"
+    "ai",
+    "ticket",
+    "time-tracking",
+    "productivity",
+    "project-management",
+    "task-management",
+    "agentic-coding",
+    "automation"
   ],
-  "author": "",
+  "author": {
+    "name": "Marco Pfeiffer",
+    "email": "marco@hauptsache.net"
+  },
   "license": "ISC",
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.9.0",