@hauptsache.net/clickup-mcp 1.2.0 → 1.3.0

package/dist/tools/doc-tools.js

@@ -0,0 +1,485 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.registerDocumentToolsRead = registerDocumentToolsRead;
+exports.registerDocumentToolsWrite = registerDocumentToolsWrite;
+const zod_1 = require("zod");
+const config_1 = require("../shared/config");
+const utils_1 = require("../shared/utils");
+/**
+ * Helper function to recursively extract all pages from nested page structure
+ */
+function extractAllPages(pageGroup) {
+    const allPages = [];
+    // Add the page itself
+    allPages.push({
+        id: pageGroup.id,
+        name: pageGroup.name,
+        doc_id: pageGroup.doc_id,
+        parent_page_id: pageGroup.parent_page_id || null
+    });
+    // Recursively add nested pages
+    if (pageGroup.pages && Array.isArray(pageGroup.pages)) {
+        pageGroup.pages.forEach((nestedPage) => {
+            allPages.push(...extractAllPages(nestedPage));
+        });
+    }
+    return allPages;
+}
+/**
+ * Helper function to display page hierarchy with proper indentation
+ */
+function displayPageHierarchy(pageGroup, currentPageId, depth = 0) {
+    const result = [];
+    const indent = '  '.repeat(depth); // 2 spaces per level
+    const isCurrentPage = pageGroup.id === currentPageId;
+    const prefix = isCurrentPage ? '▶️ ' : '   ';
+    const pageIndicator = isCurrentPage ? ' ← **Currently viewing**' : '';
+    // Display this page
+    result.push(`${indent}${prefix}${pageGroup.name} (${pageGroup.id})${pageIndicator}`);
+    // Recursively display nested pages
+    if (pageGroup.pages && Array.isArray(pageGroup.pages)) {
+        pageGroup.pages.forEach((nestedPage) => {
+            result.push(...displayPageHierarchy(nestedPage, currentPageId, depth + 1));
+        });
+    }
+    return result;
+}
+function registerDocumentToolsRead(server) {
+    server.tool("readDocument", [
+        "Get a ClickUp document with page structure and content.",
+        "Always use the document URL when referencing documents in conversations or sharing with others.",
+        "The response provides complete document metadata, page structure, and requested page content.",
+        `Document URLs look like this: ${(0, utils_1.generateDocumentUrl)('doc_id', 'page_id')}`,
+    ].join("\n"), {
+        doc_id: zod_1.z
+            .string()
+            .min(1)
+            .describe("The document ID to read"),
+        page: zod_1.z
+            .string()
+            .optional()
+            .describe("Optional specific page ID or name to read (defaults to first page)")
+    }, async ({ doc_id, page }) => {
+        try {
+            // First get the document details and page structure
+            const [docResponse, pagesResponse] = await Promise.all([
+                fetch(`https://api.clickup.com/api/v3/workspaces/${config_1.CONFIG.teamId}/docs/${doc_id}`, {
+                    headers: { Authorization: config_1.CONFIG.apiKey },
+                }),
+                fetch(`https://api.clickup.com/api/v3/workspaces/${config_1.CONFIG.teamId}/docs/${doc_id}/pageListing`, {
+                    headers: { Authorization: config_1.CONFIG.apiKey },
+                })
+            ]);
+            if (!docResponse.ok) {
+                throw new Error(`Error fetching document: ${docResponse.status} ${docResponse.statusText}`);
+            }
+            if (!pagesResponse.ok) {
+                throw new Error(`Error fetching pages: ${pagesResponse.status} ${pagesResponse.statusText}`);
+            }
+            const docData = await docResponse.json();
+            const pagesData = await pagesResponse.json();
+            const doc = docData; // Document data is flat
+            // Extract all pages while preserving hierarchy for display
+            const pages = [];
+            const hierarchicalPages = pagesData; // Keep original structure for hierarchy display
+            // Extract flat list of pages for searching and navigation
+            pagesData.forEach((pageGroup) => {
+                pages.push(...extractAllPages(pageGroup));
+            });
+            if (pages.length === 0) {
+                return {
+                    content: [{
+                            type: "text",
+                            text: `📄 **Document: ${doc.name}** (doc_id: ${doc_id})
+📎 Document URL: ${(0, utils_1.generateDocumentUrl)(doc_id)}
+
+⚠️ This document exists but has no pages yet.
+
+**Next steps:**
+- Use \`writeDocument\` with parent_type="doc" and parent_id="${doc_id}" to add the first page
+- Example: writeDocument(parent_type="doc", parent_id="${doc_id}", page_name="Introduction", content="Your content here")`
+                        }],
+                };
+            }
+            // Determine which page to read
+            let targetPage = null;
+            if (page) {
+                // Look for page by ID first, then by name
+                targetPage = pages.find((p) => p.id === page || p.name === page);
+                if (!targetPage) {
+                    return {
+                        content: [{
+                                type: "text",
+                                text: `Page "${page}" not found in document "${doc.name}". Available pages: ${pages.map((p) => `"${p.name}" (${p.id})`).join(', ')}`
+                            }],
+                    };
+                }
+            }
+            else {
+                // Default to first page
+                targetPage = pages[0];
+            }
+            // Get the specific page content
+            const pageResponse = await fetch(`https://api.clickup.com/api/v3/workspaces/${config_1.CONFIG.teamId}/docs/${doc_id}/pages/${targetPage.id}`, {
+                headers: { Authorization: config_1.CONFIG.apiKey },
+            });
+            if (!pageResponse.ok) {
+                throw new Error(`Error fetching page content: ${pageResponse.status} ${pageResponse.statusText}`);
+            }
+            const pageData = await pageResponse.json();
+            const pageContent = pageData; // Page data is flat
+            // Build the response
+            const result = [];
+            // Document header with metadata
+            result.push(`doc_id: ${doc.id}`);
+            result.push(`Document Title: ${doc.name}`);
+            result.push(`Document URL: ${(0, utils_1.generateDocumentUrl)(doc_id)}`);
+            result.push(`Current page_id: ${targetPage.id}`);
+            result.push(`Current Page Title: ${pageContent.name}`);
+            result.push(`Current Page URL: ${(0, utils_1.generateDocumentUrl)(doc_id, targetPage.id)}`);
+            // Page structure overview with hierarchy
+            result.push('Page Structure:');
+            hierarchicalPages.forEach((pageGroup) => {
+                result.push(...displayPageHierarchy(pageGroup, targetPage.id));
+            });
+            // Current page content
+            if (pageContent.content && pageContent.content.trim()) {
+                result.push(`Page Content:`);
+                return {
+                    content: [
+                        { type: "text", text: result.join('\n') },
+                        { type: "text", text: pageContent.content },
+                    ],
+                };
+            }
+            else {
+                result.push('*This page is empty.*');
+                result.push('');
+                result.push('**💡 To add content to this page:**');
+                result.push(`Use \`writeDocument\` with page_id="${targetPage.id}" and your content.`);
+                result.push(`Example: writeDocument(page_id="${targetPage.id}", content="Your content here")`);
+                return {
+                    content: [
+                        { type: "text", text: result.join('\n') },
+                    ],
+                };
+            }
+        }
+        catch (error) {
+            console.error('Error reading document:', error);
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: `Error reading document ${doc_id}: ${error instanceof Error ? error.message : 'Unknown error'}`,
+                    },
+                ],
+            };
+        }
+    });
+    // Dynamically construct the searchDocuments description
+    const searchDocumentsDescriptionBase = [
+        "Search documents by name and space with fuzzy matching and support for multiple search terms (OR logic).",
+        "This can be a great knowledge based for general project information. Consider searching for documents and for tasks at the same time.",
+        "Can filter by specific space_ids. If no search terms provided, returns most recently updated documents."
+    ];
+    if (config_1.CONFIG.primaryLanguageHint && config_1.CONFIG.primaryLanguageHint.toLowerCase() !== 'en') {
+        searchDocumentsDescriptionBase.push(`For optimal results, as your ClickUp documents may be primarily in '${config_1.CONFIG.primaryLanguageHint}', consider providing search terms in English and '${config_1.CONFIG.primaryLanguageHint}'.`);
+    }
+    searchDocumentsDescriptionBase.push("Always reference documents by their URLs when discussing search results or suggesting actions.");
+    searchDocumentsDescriptionBase.push("You'll get document overview with space context - use readDocument to get full content.");
+    server.tool("searchDocuments", searchDocumentsDescriptionBase.join("\n"), {
+        terms: zod_1.z
+            .array(zod_1.z.string())
+            .optional()
+            .describe("Array of search terms to match against document names and spaces. If not provided, returns most recent documents."),
+        space_ids: zod_1.z
+            .array(zod_1.z.string())
+            .optional()
+            .describe("Filter documents to specific space IDs")
+    }, async ({ terms, space_ids }) => {
+        try {
+            // Get the document search index
+            const searchIndex = await (0, utils_1.getDocumentSearchIndex)(space_ids);
+            if (!searchIndex) {
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: "Unable to create document search index.",
+                        },
+                    ],
+                };
+            }
+            let results;
+            if (terms && terms.length > 0) {
+                // Perform multi-term search
+                results = await (0, utils_1.performMultiTermSearch)(searchIndex, terms);
+            }
+            else {
+                // Return all documents sorted by creation date (most recent first)
+                const allResults = searchIndex._docs || [];
+                results = allResults
+                    .sort((a, b) => new Date(b.date_created || 0).getTime() - new Date(a.date_created || 0).getTime());
+            }
+            // Limit results to prevent overwhelming the LLM
+            const limitedResults = results.slice(0, 50);
+            if (limitedResults.length === 0) {
+                const searchTermsText = terms && terms.length > 0 ? ` for terms: ${terms.join(", ")}` : "";
+                const spaceFilterText = space_ids && space_ids.length > 0 ? ` in spaces: ${space_ids.join(", ")}` : "";
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: [
+                                `No documents found${searchTermsText}${spaceFilterText}.`,
+                                `The content of documents is not searched, so ask the user for more details if needed.`,
+                            ].join("\n"),
+                        },
+                    ],
+                };
+            }
+            // Format results
+            const responseLines = [
+                `Found ${limitedResults.length} document${limitedResults.length === 1 ? "" : "s"}:`
+            ];
+            limitedResults.forEach((doc, index) => {
+                const docUrl = (0, utils_1.generateDocumentUrl)(doc.id);
+                const createdDate = doc.date_created ? new Date(+doc.date_created).toLocaleDateString() : 'Unknown';
+                const meta = [`doc_id ${doc.id}`];
+                // Show parent information
+                if (doc.parent_info) {
+                    meta.push(doc.parent_info);
+                }
+                meta.push(`Created: ${createdDate}`);
+                responseLines.push(`- ${doc.name} (${meta.join(', ')}) ${docUrl}`);
+            });
+            responseLines.push("", "Use `readDocument` with a document ID to view full content and page structure.");
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: responseLines.join("\n"),
+                    },
+                ],
+            };
+        }
+        catch (error) {
+            console.error('Error searching documents:', error);
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: `Error searching documents: ${error instanceof Error ? error.message : 'Unknown error'}`,
+                    },
+                ],
+            };
+        }
+    });
+}
+function registerDocumentToolsWrite(server) {
+    server.tool("writeDocument", [
+        "Universal tool for document and page operations with smart document creation.",
+        "Create new documents by using parent_type 'space' or 'list'.",
+        "Create pages in existing documents by using parent_type 'doc'.",
+        "Create sub-pages by using parent_type 'page'.",
+        "Update existing pages by providing page_id.",
+        "Always reference documents by their URLs when creating or updating."
+    ].join("\n"), {
+        page_id: zod_1.z
+            .string()
+            .optional()
+            .describe("Optional page ID to update (if provided, updates existing page; if not, creates new page/document)"),
+        parent_type: zod_1.z
+            .enum(["space", "list", "doc", "page"])
+            .optional()
+            .describe("Type of parent when creating new content (required if page_id not provided)"),
+        parent_id: zod_1.z
+            .string()
+            .optional()
+            .describe("ID of parent (space, list, document, or page) when creating new content (required if page_id not provided)"),
+        page_name: zod_1.z
+            .string()
+            .optional()
+            .describe("Name for the page (required for new pages, optional for updates to rename)"),
+        content: zod_1.z
+            .string()
+            .optional()
+            .describe("Page content in markdown format (optional for updates)"),
+        append: zod_1.z
+            .boolean()
+            .optional()
+            .describe("Whether to append content to existing page content (default: false - replaces content)")
+    }, async ({ page_id, parent_type, parent_id, page_name, content, append = false }) => {
+        try {
+            // Validate input parameters
+            if (!page_id && (!parent_type || !parent_id)) {
+                return {
+                    content: [{
+                            type: "text",
+                            text: "Error: Either page_id (for updates) or both parent_type and parent_id (for creation) must be provided."
+                        }],
+                };
+            }
+            if (!page_id && !page_name) {
+                return {
+                    content: [{
+                            type: "text",
+                            text: "Error: page_name is required when creating new pages."
+                        }],
+                };
+            }
+            // Case 1: Update existing page
+            if (page_id) {
+                const requestBody = {};
+                if (page_name) {
+                    requestBody.name = page_name;
+                }
+                if (content !== undefined) {
+                    requestBody.content = content;
+                    // Use native append mode from ClickUp API
+                    requestBody.content_edit_mode = append ? 'append' : 'replace';
+                }
+                const response = await fetch(`https://api.clickup.com/api/v3/docs/pages/${page_id}`, {
+                    method: 'PUT',
+                    headers: {
+                        Authorization: config_1.CONFIG.apiKey,
+                        'Content-Type': 'application/json',
+                    },
+                    body: JSON.stringify(requestBody),
+                });
+                if (!response.ok) {
+                    throw new Error(`Error updating page: ${response.status} ${response.statusText}`);
+                }
+                const data = await response.json();
+                const updatedPage = data.page;
+                return {
+                    content: [{
+                            type: "text",
+                            text: `✅ Successfully updated page "${updatedPage.name}" (${page_id})\n\nPage URL: ${(0, utils_1.generateDocumentUrl)(updatedPage.doc_id, page_id)}`
+                        }],
+                };
+            }
+            // Case 2: Create new content
+            let docId;
+            if (parent_type === "space" || parent_type === "list") {
+                // Create new document first, then create first page manually
+                const docRequestBody = {
+                    name: page_name, // Document name matches first page name
+                    create_page: false, // Don't auto-create page, we'll create it manually for better control
+                    parent: {
+                        id: parent_id,
+                        type: parent_type === "space" ? 4 : parent_type === "list" ? 6 : 7 // 4=Space, 6=List, 7=Workspace
+                    }
+                };
+                const docResponse = await fetch(`https://api.clickup.com/api/v3/workspaces/${config_1.CONFIG.teamId}/docs`, {
+                    method: 'POST',
+                    headers: {
+                        Authorization: config_1.CONFIG.apiKey,
+                        'Content-Type': 'application/json',
+                    },
+                    body: JSON.stringify(docRequestBody),
+                });
+                if (!docResponse.ok) {
+                    throw new Error(`Error creating document: ${docResponse.status} ${docResponse.statusText}`);
+                }
+                const docData = await docResponse.json();
+                docId = docData.id;
+                // Create the first page manually for better control
+                const pageRequestBody = {
+                    name: page_name,
+                    content: content || '',
+                };
+                const pageResponse = await fetch(`https://api.clickup.com/api/v3/workspaces/${config_1.CONFIG.teamId}/docs/${docId}/pages`, {
+                    method: 'POST',
+                    headers: {
+                        Authorization: config_1.CONFIG.apiKey,
+                        'Content-Type': 'application/json',
+                    },
+                    body: JSON.stringify(pageRequestBody),
+                });
+                if (!pageResponse.ok) {
+                    throw new Error(`Error creating first page: ${pageResponse.status} ${pageResponse.statusText}`);
+                }
+                const pageData = await pageResponse.json();
+                const firstPage = pageData.page || pageData;
+                return {
+                    content: [{
+                            type: "text",
+                            text: `✅ Successfully created new document "${page_name}" with first page\n\nDocument URL: ${(0, utils_1.generateDocumentUrl)(docId)}\nFirst Page URL: ${(0, utils_1.generateDocumentUrl)(docId, firstPage.id)}`
+                        }],
+                };
+            }
+            else if (parent_type === "doc") {
+                // Create new page in existing document
+                docId = parent_id;
+                const pageRequestBody = {
+                    name: page_name,
+                    content: content || '',
+                };
+                const response = await fetch(`https://api.clickup.com/api/v3/workspaces/${config_1.CONFIG.teamId}/docs/${docId}/pages`, {
+                    method: 'POST',
+                    headers: {
+                        Authorization: config_1.CONFIG.apiKey,
+                        'Content-Type': 'application/json',
+                    },
+                    body: JSON.stringify(pageRequestBody),
+                });
+                if (!response.ok) {
+                    throw new Error(`Error creating page: ${response.status} ${response.statusText}`);
+                }
+                const data = await response.json();
+                const newPage = data.page;
+                return {
+                    content: [{
+                            type: "text",
+                            text: `✅ Successfully created page "${newPage.name}" (${newPage.id}) in document\n\nPage URL: ${(0, utils_1.generateDocumentUrl)(docId, newPage.id)}`
+                        }],
+                };
+            }
+            else if (parent_type === "page") {
+                // Create sub-page under existing page
+                const pageRequestBody = {
+                    name: page_name,
+                    content: content || '',
+                    parent_page_id: parent_id
+                };
+                // For sub-pages, we need to get the doc_id from the parent page first
+                // This is a limitation we'll need to handle - for now, use a generic endpoint
+                const response = await fetch(`https://api.clickup.com/api/v3/docs/pages`, {
+                    method: 'POST',
+                    headers: {
+                        Authorization: config_1.CONFIG.apiKey,
+                        'Content-Type': 'application/json',
+                    },
+                    body: JSON.stringify(pageRequestBody),
+                });
+                if (!response.ok) {
+                    throw new Error(`Error creating sub-page: ${response.status} ${response.statusText}`);
+                }
+                const data = await response.json();
+                const newPage = data.page;
+                return {
+                    content: [{
+                            type: "text",
+                            text: `✅ Successfully created sub-page "${newPage.name}" (${newPage.id}) under parent page ${parent_id}\n\nPage URL: ${(0, utils_1.generateDocumentUrl)(newPage.doc_id, newPage.id)}`
+                        }],
+                };
+            }
+            return {
+                content: [{ type: "text", text: "Error: Invalid parent_type specified." }],
+            };
+        }
+        catch (error) {
+            console.error('Error in writeDocument:', error);
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: `Error in document/page operation: ${error instanceof Error ? error.message : 'Unknown error'}`,
+                    },
+                ],
+            };
+        }
+    });
+}

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;AAMpE,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,SAAS,QA+GtD;AAED,wBAAgB,sBAAsB,CAAC,MAAM,EAAE,SAAS,QAyEvD"}
+{"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,QA+GtD;AAED,wBAAgB,sBAAsB,CAAC,MAAM,EAAE,SAAS,QAyEvD"}

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;AASlE,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,SAAS,EAAE,QAAQ,EAAE,GAAG,QA8MnE"}
+{"version":3,"file":"search-tools.d.ts","sourceRoot":"","sources":["../../src/tools/search-tools.ts"],"names":[],"mappings":"AAAA,OAAO,EAAC,SAAS,EAAC,MAAM,yCAAyC,CAAC;AASlE,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,SAAS,EAAE,QAAQ,EAAE,GAAG,QAuLnE"}

package/dist/tools/search-tools.js

@@ -9,7 +9,7 @@ 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 (case insensitive) with fuzzy matching and support for multiple search terms (OR logic).",
+        "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."
     ];
@@ -94,37 +94,15 @@ function registerSearchTools(server, userData) {
                 content: await Promise.all(resultTasks.map((task) => (0, task_tools_1.generateTaskMetadata)(task, timeEntries))),
             };
         }
-        // Filter valid search terms
-        const validTerms = terms.filter(term => term && term.trim().length > 0);
-        if (validTerms.length === 0) {
-            return {
-                content: [
-                    {
-                        type: "text",
-                        text: "No valid search terms provided.",
-                    },
-                ],
-            };
-        }
+        // Create a results map to track unique tasks with scores
         const uniqueResults = new Map();
-        // Search with each term
-        validTerms.forEach(term => {
-            const results = searchIndex.search(term.toLowerCase());
-            results.forEach(result => {
-                if (result.item && typeof result.item.id === 'string') {
-                    const currentScore = result.score ?? 1;
-                    const existing = uniqueResults.get(result.item.id);
-                    if (!existing || currentScore < existing.score) {
-                        uniqueResults.set(result.item.id, {
-                            item: result.item,
-                            score: currentScore
-                        });
-                    }
-                }
-            });
+        // 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
-        const potentialTaskIds = validTerms.filter(utils_1.isTaskId);
+        const potentialTaskIds = terms.filter(utils_1.isTaskId);
         const foundTaskIdsByFuse = new Set(Array.from(uniqueResults.keys()).map(id => id.toLowerCase()));
         const taskIdsToFetchDirectly = potentialTaskIds.filter(id => {
             const lowerId = id.toLowerCase();

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;AAMpE,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,SAAS,QAqNnD"}
+{"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,QAiNnD"}