@pripanggalih/clickup-mcp 1.6.1

package/dist/tools/time-tools.js

@@ -0,0 +1,338 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+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
+ */
+function isoToTimestamp(isoString) {
+    return new Date(isoString).getTime();
+}
+/**
+ * Formats timestamp to ISO string with local timezone (not UTC)
+ */
+function timestampToIso(timestamp) {
+    const date = new Date(timestamp);
+    const year = date.getFullYear();
+    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');
+    const seconds = String(date.getSeconds()).padStart(2, '0');
+    // Calculate timezone offset
+    const offset = date.getTimezoneOffset();
+    const offsetHours = Math.floor(Math.abs(offset) / 60);
+    const offsetMinutes = Math.abs(offset) % 60;
+    const sign = offset <= 0 ? '+' : '-';
+    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."),
+        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)")
+    }, {
+        readOnlyHint: true
+    }, async ({ task_id, start_date, end_date, list_id, space_id, include_all_users }) => {
+        try {
+            // Build query parameters
+            const params = new URLSearchParams();
+            if (task_id) {
+                params.append('task_id', task_id);
+            }
+            if (start_date) {
+                params.append('start_date', isoToTimestamp(start_date).toString());
+            }
+            if (end_date) {
+                params.append('end_date', isoToTimestamp(end_date).toString());
+            }
+            // Add single list_id or space_id filter (not both)
+            if (list_id) {
+                params.append('list_id', list_id);
+            }
+            else if (space_id) {
+                params.append('space_id', space_id);
+            }
+            // 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(','));
+                    }
+                }
+                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 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}`);
+            }
+            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);
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: `Error fetching time entries: ${error instanceof Error ? error.message : 'Unknown error'}`,
+                    },
+                ],
+            };
+        }
+    });
+}
+/**
+ * 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);
+                        }
+                        const entryDescription = entry.description ? ` | ${entry.description}` : '';
+                        outputLines.push(`${entryPrefix} ${entryStart} - ${entryDuration}${entryDescription}`);
+                    });
+                }
+            }
+            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.",
+        "Use decimal hours (e.g., 0.25 for 15 minutes, 0.5 for 30 minutes, 2.5 for 2.5 hours).",
+        "IMPORTANT: Before booking time, check the task's status - booking time on tasks in 'backlog', 'closed', or similar inactive states usually doesn't make sense.",
+        "Suggest moving the task to an active status like 'in progress' first."
+    ].join("\n"), {
+        task_id: zod_1.z.string().min(6).max(9).describe("The 6-9 character task ID to book time against"),
+        hours: zod_1.z.number().min(0.01).max(24).describe("Hours to book (decimal format, e.g., 0.25 = 15min, 1.5 = 1h 30min)"),
+        description: zod_1.z.string().optional().describe("Optional description for the time entry"),
+        start_time: zod_1.z.string().optional().describe("Optional start time as ISO date string (e.g., '2024-10-06T09:00:00+02:00', defaults to current time)")
+    }, {
+        readOnlyHint: false,
+        destructiveHint: false,
+        idempotentHint: false,
+    }, async ({ task_id, hours, description, start_time }) => {
+        try {
+            // Convert hours to milliseconds (ClickUp API uses milliseconds)
+            const durationMs = Math.round(hours * 60 * 60 * 1000);
+            // Convert ISO date to timestamp if provided, otherwise use current time
+            const startTimeMs = start_time ? isoToTimestamp(start_time) : Date.now();
+            const requestBody = {
+                tid: task_id,
+                start: startTimeMs,
+                duration: durationMs,
+                ...(description && { description })
+            };
+            const response = await fetch(`https://api.clickup.com/api/v2/team/${config_1.CONFIG.teamId}/time_entries`, {
+                method: 'POST',
+                headers: {
+                    Authorization: config_1.CONFIG.apiKey,
+                    'Content-Type': 'application/json'
+                },
+                body: JSON.stringify(requestBody)
+            });
+            if (!response.ok) {
+                const errorData = await response.json().catch(() => ({}));
+                throw new Error(`Error creating time entry: ${response.status} ${response.statusText} - ${JSON.stringify(errorData)}`);
+            }
+            const timeEntry = await response.json();
+            // Format duration for display
+            const displayHours = Math.floor(hours);
+            const displayMinutes = Math.round((hours - displayHours) * 60);
+            const durationDisplay = displayHours > 0 ?
+                `${displayHours}h ${displayMinutes}m` :
+                `${displayMinutes}m`;
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: [
+                            `Time entry created successfully!`,
+                            `entry_id: ${timeEntry.data?.id || 'N/A'}`,
+                            `task_id: ${task_id}`,
+                            `duration: ${durationDisplay}`,
+                            `start_time: ${timestampToIso(startTimeMs)}`,
+                            ...(description ? [`description: ${description}`] : []),
+                            `user: ${timeEntry.data?.user?.username || 'Current user'}`
+                        ].join('\n')
+                    }
+                ],
+            };
+        }
+        catch (error) {
+            console.error('Error creating time entry:', error);
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: `Error creating time entry: ${error instanceof Error ? error.message : 'Unknown error'}`,
+                    },
+                ],
+            };
+        }
+    });
+}

package/package.json

@@ -0,0 +1,74 @@
+{
+  "name": "@pripanggalih/clickup-mcp",
+  "version": "1.6.1",
+  "description": "Personal ClickUp MCP server for task context, documents, time tracking, and workspace administration.",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "bin": {
+    "clickup-mcp": "dist/index.js"
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "start": "node dist/index.js",
+    "dev": "npx tsc -w & nodemon dist/index.js",
+    "cli": "npx ts-node src/cli.ts",
+    "prettier": "prettier --write src/**/*.ts",
+    "prepublishOnly": "rm -r dist && npm run build",
+    "release": "npm run build && npm publish --access public && git add . && git commit -m \"Release v$(node -p 'require(\"./package.json\").version')\" && git tag -a v$(node -p 'require(\"./package.json\").version') -m \"Release v$(node -p 'require(\"./package.json\").version')\" && git push && git push --tags",
+    "mcpb": "npm run build && mcpb pack . ClickUp.mcpb",
+    "test": "node --test -r ts-node/register src/**/*.test.ts"
+  },
+  "keywords": [
+    "clickup",
+    "mcp",
+    "model-context-protocol",
+    "llm",
+    "ai",
+    "ticket",
+    "time-tracking",
+    "productivity",
+    "project-management",
+    "task-management",
+    "agentic-coding",
+    "automation"
+  ],
+  "author": {
+    "name": "MW Pripanggalih",
+    "email": "galihcrew07@gmail.com"
+  },
+  "license": "MIT",
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "1.15.1",
+    "fuse.js": "^7.1.0",
+    "remark-gfm": "^4.0.1",
+    "remark-parse": "^11.0.0",
+    "unified": "^11.0.5",
+    "zod": "^3.24.2"
+  },
+  "devDependencies": {
+    "@anthropic-ai/mcpb": "^1.1.1",
+    "@types/mdast": "^4.0.4",
+    "@types/node": "^22.14.1",
+    "dotenv": "^16.5.0",
+    "nodemon": "^3.1.9",
+    "prettier": "^3.5.3",
+    "ts-node": "^10.9.2",
+    "typescript": "^5.8.3",
+    "undici": "^7.16.0"
+  },
+  "engines": {
+    "node": ">=16.0.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/pripanggalih/clickup-mcp.git"
+  },
+  "bugs": {
+    "url": "https://github.com/pripanggalih/clickup-mcp/issues"
+  },
+  "homepage": "https://github.com/pripanggalih/clickup-mcp#readme"
+}