@sebastienheyd/clickup-mcp 1.6.1

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

@@ -0,0 +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,EAAE,QAAQ,EAAE,GAAG,QAiNnE"}

package/dist/tools/search-tools.js

@@ -0,0 +1,188 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.registerSearchTools = registerSearchTools;
+const zod_1 = require("zod");
+const config_1 = require("../shared/config");
+const utils_1 = require("../shared/utils");
+const task_tools_1 = require("./task-tools");
+const MAX_SEARCH_RESULTS = 50;
+function registerSearchTools(server, userData) {
+    // Dynamically construct the searchTasks description
+    const searchTasksDescriptionBase = [
+        "Searches tasks (sometimes called Tickets or Cards) by name, content, assignees, and ID 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.",
+        "Can also be used to find tasks for the current user by providing the assigned_to_me flag."
+    ];
+    if (config_1.CONFIG.primaryLanguageHint && config_1.CONFIG.primaryLanguageHint.toLowerCase() !== 'en') {
+        searchTasksDescriptionBase.push(`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}'.`);
+    }
+    searchTasksDescriptionBase.push("Always reference tasks by their URLs when discussing search results or suggesting actions.");
+    searchTasksDescriptionBase.push("You'll get a rough overview of the tasks that match the search terms, sorted by relevance.");
+    searchTasksDescriptionBase.push("Always use getTaskById to get more specific information if a task is relevant, and always share the task URL.");
+    server.tool("searchTasks", searchTasksDescriptionBase.join("\n"), {
+        terms: zod_1.z
+            .array(zod_1.z.string())
+            .optional()
+            .describe("Array of search terms (OR logic). Can include task IDs. Optional - if not provided, returns most recent tasks."),
+        list_ids: zod_1.z
+            .array(zod_1.z.string())
+            .optional()
+            .describe("Filter tasks to specific list IDs"),
+        space_ids: zod_1.z
+            .array(zod_1.z.string())
+            .optional()
+            .describe("Filter tasks to specific space IDs"),
+        only_todo: zod_1.z
+            .boolean()
+            .optional()
+            .describe("Filter for open/todo tasks only (exclude done and closed tasks)"),
+        status: zod_1.z
+            .array(zod_1.z.string())
+            .optional()
+            .describe("Filter for tasks with specific status names (overrides only_todo if provided)"),
+        assigned_to_me: zod_1.z
+            .boolean()
+            .optional()
+            .describe(`Filter for tasks assigned to the current user (${userData.user.username} (${userData.user.id}))`),
+    }, {
+        readOnlyHint: true
+    }, async ({ terms, list_ids, space_ids, only_todo, status, assigned_to_me }) => {
+        // Get current user ID if filtering by assigned_to_me
+        const assignees = assigned_to_me ? [userData.user.id] : [];
+        const searchIndex = await (0, utils_1.getTaskSearchIndex)(space_ids, list_ids, assignees);
+        if (!searchIndex) {
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: "No tasks available or index could not be built.",
+                    },
+                ],
+            };
+        }
+        // Early return for no search terms
+        if (!terms || terms.length === 0) {
+            let allTasks = searchIndex._docs || [];
+            // Apply status filtering
+            if (status && status.length > 0) {
+                const statusLower = status.map(s => s.toLowerCase());
+                allTasks = allTasks.filter((task) => statusLower.includes(task.status.status.toLowerCase()));
+            }
+            else if (only_todo) {
+                allTasks = allTasks.filter((task) => task.status.type !== "done" && task.status.type !== "closed");
+            }
+            // Sort by updated date (most recent first) and limit
+            const resultTasks = allTasks
+                .sort((a, b) => {
+                const dateA = parseInt(a.date_updated || "0");
+                const dateB = parseInt(b.date_updated || "0");
+                return dateB - dateA;
+            })
+                .slice(0, MAX_SEARCH_RESULTS);
+            if (resultTasks.length === 0) {
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: "No tasks found.",
+                        },
+                    ],
+                };
+            }
+            return {
+                content: await Promise.all(resultTasks.map((task) => (0, task_tools_1.generateTaskMetadata)(task))),
+            };
+        }
+        // Create a results map to track unique tasks with scores
+        const uniqueResults = new Map();
+        // Perform multi-term search with aggressive boosting
+        const searchResults = await (0, utils_1.performMultiTermSearch)(searchIndex, terms);
+        searchResults.forEach(task => {
+            uniqueResults.set(task.id, { item: task, score: 0.1 }); // Give search results a good score
+        });
+        // Task ID Fallback Logic (internal IDs and custom IDs)
+        const potentialTaskIds = terms.filter(utils_1.isTaskId);
+        const potentialCustomIds = terms.filter(id => (0, utils_1.isCustomTaskId)(id) && !(0, utils_1.isTaskId)(id));
+        const foundTaskIdsByFuse = new Set(Array.from(uniqueResults.keys()).map(id => id.toLowerCase()));
+        const taskIdsToFetchDirectly = potentialTaskIds.filter(id => {
+            const lowerId = id.toLowerCase();
+            return !foundTaskIdsByFuse.has(lowerId);
+        });
+        // Fetch internal task IDs not found in index
+        if (taskIdsToFetchDirectly.length > 0) {
+            console.error(`Attempting direct fetch for task IDs: ${taskIdsToFetchDirectly.join(', ')}`);
+            const directFetchPromises = taskIdsToFetchDirectly.map(async (id) => {
+                try {
+                    const response = await fetch(`https://api.clickup.com/api/v2/task/${id}`, { headers: { Authorization: config_1.CONFIG.apiKey } });
+                    if (response.ok) {
+                        const task = await response.json();
+                        if (task && typeof task.id === 'string') {
+                            const existing = uniqueResults.get(task.id);
+                            if (!existing || 0 < existing.score) {
+                                uniqueResults.set(task.id, { item: task, score: 0 });
+                            }
+                        }
+                        return task;
+                    }
+                    return null;
+                }
+                catch (error) {
+                    console.error(`Error directly fetching task ${id}:`, error);
+                    return null;
+                }
+            });
+            await Promise.all(directFetchPromises);
+        }
+        // Fetch custom task IDs via the custom_task_ids API parameter
+        if (potentialCustomIds.length > 0) {
+            console.error(`Attempting direct fetch for custom task IDs: ${potentialCustomIds.join(', ')}`);
+            const customFetchPromises = potentialCustomIds.map(async (customId) => {
+                try {
+                    const response = await fetch(`https://api.clickup.com/api/v2/task/${customId}?custom_task_ids=true&team_id=${config_1.CONFIG.teamId}`, { headers: { Authorization: config_1.CONFIG.apiKey } });
+                    if (response.ok) {
+                        const task = await response.json();
+                        if (task && typeof task.id === 'string') {
+                            const existing = uniqueResults.get(task.id);
+                            if (!existing || 0 < existing.score) {
+                                uniqueResults.set(task.id, { item: task, score: 0 });
+                            }
+                        }
+                        return task;
+                    }
+                    return null;
+                }
+                catch (error) {
+                    console.error(`Error directly fetching custom task ${customId}:`, error);
+                    return null;
+                }
+            });
+            await Promise.all(customFetchPromises);
+        }
+        let resultTasks = Array.from(uniqueResults.values())
+            .sort((a, b) => a.score - b.score)
+            .map(entry => entry.item);
+        // Apply status filtering
+        if (status && status.length > 0) {
+            const statusLower = status.map(s => s.toLowerCase());
+            resultTasks = resultTasks.filter((task) => statusLower.includes(task.status.status.toLowerCase()));
+        }
+        else if (only_todo) {
+            resultTasks = resultTasks.filter((task) => task.status.type !== "done" && task.status.type !== "closed");
+        }
+        // Apply result limit
+        resultTasks = resultTasks.slice(0, MAX_SEARCH_RESULTS);
+        if (resultTasks.length === 0) {
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: "No tasks found matching the search criteria.",
+                    },
+                ],
+            };
+        }
+        return {
+            content: await Promise.all(resultTasks.map((task) => (0, task_tools_1.generateTaskMetadata)(task))),
+        };
+    });
+}

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

@@ -0,0 +1,3 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+export declare function registerSpaceTools(server: McpServer): void;
+//# sourceMappingURL=space-tools.d.ts.map

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

@@ -0,0 +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,QA8JnD"}

package/dist/tools/space-tools.js

@@ -0,0 +1,144 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.registerSpaceTools = registerSpaceTools;
+const zod_1 = require("zod");
+const utils_1 = require("../shared/utils");
+function registerSpaceTools(server) {
+    server.tool("searchSpaces", [
+        "Searches spaces (sometimes called projects) by name or ID with fuzzy matching.",
+        "If 5 or fewer spaces match, automatically fetches all lists (sometimes called boards) and folders within those spaces to provide a complete tree structure.",
+        "If more than 5 spaces match, returns only space information with guidance to search more precisely.",
+        "You can search by space name (fuzzy matching) or provide an exact space ID.",
+        "You can also provide a folder_id to get details about a specific folder (its lists, statuses, and parent space).",
+        "Always reference spaces by their URLs when discussing projects or suggesting actions."
+    ].join("\n"), {
+        terms: zod_1.z
+            .array(zod_1.z.string())
+            .optional()
+            .describe("Array of search terms to match against space names or IDs. If not provided, returns all spaces. Ignored when folder_id is provided."),
+        folder_id: zod_1.z
+            .string()
+            .optional()
+            .describe("A ClickUp folder ID to get details about a specific folder including its lists and parent space. When provided, terms and archived are ignored."),
+        archived: zod_1.z.boolean().optional().describe("Include archived spaces (default: false)")
+    }, {
+        readOnlyHint: true
+    }, async ({ terms, folder_id, archived = false }) => {
+        try {
+            // If folder_id is provided, return folder details directly
+            if (folder_id) {
+                const folder = await (0, utils_1.getFolderDetails)(folder_id);
+                const folderText = (0, utils_1.formatFolderTree)(folder);
+                return {
+                    content: [
+                        { type: "text", text: `Folder details for folder_id: ${folder_id}:` },
+                        { type: "text", text: folderText },
+                    ],
+                };
+            }
+            const searchIndex = await (0, utils_1.getSpaceSearchIndex)();
+            if (!searchIndex) {
+                return {
+                    content: [{ type: "text", text: "Error: Could not build space search index." }],
+                };
+            }
+            let matchingSpaces = [];
+            if (!terms || terms.length === 0) {
+                // Return all spaces if no search terms
+                matchingSpaces = searchIndex._docs || [];
+            }
+            else {
+                // Perform multi-term search with aggressive boosting
+                matchingSpaces = await (0, utils_1.performMultiTermSearch)(searchIndex, terms
+                // No ID matcher or direct fetcher for spaces - they don't have direct API endpoints
+                );
+            }
+            // Filter by archived status
+            if (!archived) {
+                matchingSpaces = matchingSpaces.filter((space) => !space.archived);
+            }
+            if (matchingSpaces.length === 0) {
+                return {
+                    content: [{ type: "text", text: "No spaces found matching the search criteria." }],
+                };
+            }
+            // Conditionally fetch detailed content based on result count
+            const spaceContentPromises = matchingSpaces.map(async (space) => {
+                try {
+                    if (matchingSpaces.length <= 5) {
+                        // Detailed mode: fetch lists and folders for this space
+                        const { lists, folders, documents } = await (0, utils_1.getSpaceContent)(space.id);
+                        return { space, lists, folders, documents };
+                    }
+                    else {
+                        // Summary mode: just return space without content
+                        return { space, lists: [], folders: [], documents: [] };
+                    }
+                }
+                catch (error) {
+                    console.error(`Error fetching content for space ${space.id}:`, error);
+                    return { space, lists: [], folders: [], documents: [] };
+                }
+            });
+            const spacesWithContent = await Promise.all(spaceContentPromises);
+            const contentBlocks = [];
+            const isDetailedMode = matchingSpaces.length <= 5;
+            if (isDetailedMode) {
+                // Detailed mode: create separate blocks for each space
+                spacesWithContent.forEach(({ space, lists, folders, documents }) => {
+                    // Use shared tree formatting function
+                    const spaceTreeText = (0, utils_1.formatSpaceTree)(space, lists, folders, documents);
+                    // Add the complete space as a single content block
+                    contentBlocks.push({
+                        type: "text",
+                        text: spaceTreeText
+                    });
+                });
+            }
+            else {
+                // Summary mode: create a single combined block with all spaces
+                const allSpaceLines = [];
+                spacesWithContent.forEach(({ space }) => {
+                    allSpaceLines.push(`🏢 SPACE: ${space.name} (space_id: ${space.id}${space.private ? ', private' : ''}${space.archived ? ', archived' : ''})`);
+                });
+                contentBlocks.push({
+                    type: "text",
+                    text: allSpaceLines.join('\n')
+                });
+            }
+            // Add tip message for summary mode (when there are too many spaces)
+            if (matchingSpaces.length > 5) {
+                contentBlocks.push({
+                    type: "text",
+                    text: `\n💡 Tip: Use more specific search terms to get detailed list information (≤5 spaces will show complete structure)`
+                });
+            }
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: matchingSpaces.length <= 5
+                            ? (() => {
+                                const totalLists = spacesWithContent.reduce((sum, { lists, folders }) => sum + lists.length + folders.reduce((folderSum, f) => folderSum + (f.lists?.length || 0), 0), 0);
+                                const totalDocuments = spacesWithContent.reduce((sum, { documents }) => sum + documents.length, 0);
+                                return `Found ${matchingSpaces.length} space(s) with complete tree structure (${totalLists} total lists, ${totalDocuments} total documents):`;
+                            })()
+                            : `Found ${matchingSpaces.length} space(s) - showing names and IDs only. Use more specific search terms to get detailed information:`
+                    },
+                    ...contentBlocks
+                ],
+            };
+        }
+        catch (error) {
+            console.error('Error searching spaces:', error);
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: `Error searching spaces: ${error instanceof Error ? error.message : 'Unknown error'}`,
+                    },
+                ],
+            };
+        }
+    });
+}

package/dist/tools/task-tools.d.ts

@@ -0,0 +1,8 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { ContentBlock } from "../shared/types";
+export declare function registerTaskToolsRead(server: McpServer, userData: any): void;
+/**
+ * Helper function to generate consistent task metadata
+ */
+export declare function generateTaskMetadata(task: any, timeEntries?: any[], isDetailView?: boolean): Promise<ContentBlock>;
+//# sourceMappingURL=task-tools.d.ts.map

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

@@ -0,0 +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,QA6DrE;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,CA+G/H"}