@hauptsache.net/clickup-mcp 1.4.2 → 1.5.0

package/README.md

@@ -2,9 +2,6 @@
 
 Model Context Protocol (MCP) server enabling AI assistants to interact with ClickUp workspaces. Get complete task context with comments and images, search across projects, create and update tasks, collaborate through comments, and track time - all through natural language.
 
-> **⚠️ Experimental Software Notice**  
-> This MCP is experimental and under active development. While implemented with great care to prevent data loss through append-only description updates and other safety measures, it cannot be guaranteed to be completely safe. Please use with caution, especially in production environments. Always test in a non-critical workspace first. 🧪
-
 ## What You Can Do
 
 Turn natural language into powerful ClickUp actions:
@@ -74,38 +71,81 @@ Turn natural language into powerful ClickUp actions:
 - **Append-Only Descriptions**: Description fields are never overwritten - new content is safely appended with timestamps
 - **Normal Field Updates**: Status, priority, assignees, tags, and dates can be updated normally (easily revertible through ClickUp's history)
 
-## Setup for Claude Desktop, Windsurf, or Cursor
-
-1. **Prerequisites**:
-   - Your `CLICKUP_API_KEY` (Profile Icon > Settings > Apps > API Token ~ usually starts with pk_)
-   - and your `CLICKUP_TEAM_ID` (The ~7 digit number in the url when you are in the settings)
-
-2. **Configuration**:
-   Add the following to your MCP configuration file:
-
-   ```json
-   {
-     "mcpServers": {
-       "clickup": {
-         "command": "npx",
-         "args": [
-           "@hauptsache.net/clickup-mcp@latest"
-         ],
-         "env": {
-           "CLICKUP_API_KEY": "your_api_key",
-           "CLICKUP_TEAM_ID": "your_team_id"
-         }
-       }
-     }
-   }
-   ```
-
-   Replace `your_api_key` and `your_team_id` with your actual ClickUp credentials.
-
-3. **Connect Your AI Assistant**:
-   - **Claude Desktop**: Add this configuration in Settings > Developer > Edit Config
-   - **Windsurf**: Add to your MCP configuration file
-   - **Cursor**: Configure through the MCP settings panel
+## Installation
+
+### Prerequisites
+
+For all installation methods, you'll need:
+- Your `CLICKUP_API_KEY` (Profile Icon > Settings > Apps > API Token ~ usually starts with pk_)
+- Your `CLICKUP_TEAM_ID` (The 7–10 digit number in the URL when you are in the settings)
+
+### Option 1: MCPB Bundle (Recommended for Claude Desktop)
+
+Download the pre-built bundle from our [releases page](https://github.com/hauptsacheNet/clickup-mcp/releases). This method requires no Node.js installation.
+
+You'll get a configuration screen where you are prompted to enter your API key and team ID.
+
+### Option 2: NPX Installation
+
+This method automatically updates to the latest version and is preferred for users who want the newest features.
+
+**For Claude Desktop, Windsurf, Cursor and others:**
+
+Add the following to your MCP configuration file:
+
+```json
+{
+  "mcpServers": {
+    "clickup": {
+      "command": "npx",
+      "args": [
+        "@hauptsache.net/clickup-mcp@latest"
+      ],
+      "env": {
+        "CLICKUP_API_KEY": "your_api_key",
+        "CLICKUP_TEAM_ID": "your_team_id"
+      }
+    }
+  }
+}
+```
+
+Replace `your_api_key` and `your_team_id` with your actual ClickUp credentials.
+
+**Where to add this configuration:**
+- **Claude Desktop**: Settings > Developer > Edit Config
+- **Windsurf**: Add to your MCP configuration file
+- **Cursor**: Configure through the MCP settings panel
+
+### Option 3: Coding Tools Integration
+
+**Claude Code (CLI):**
+```bash
+claude mcp add --scope user clickup \
+  --env CLICKUP_API_KEY=YOUR_KEY \
+  --env CLICKUP_TEAM_ID=YOUR_ID \
+  --env CLICKUP_MCP_MODE=read-minimal \
+  --env MAX_IMAGES=16 \
+  --env MAX_RESPONSE_SIZE_MB=4 \
+  -- npx -y @hauptsache.net/clickup-mcp
+```
+
+> Claude Code can handle a lot of images, thus the recommended increased limits.
+ 
+> Note the `CLICKUP_MCP_MODE=read-minimal`. This is my usage recommendation, but feel free to use one of the other modes.
+
+**OpenAI Codex:**
+Add these lines to your `~/.codex/config.toml` file:
+```toml
+[mcp_servers.clickup]
+command = "npx"
+args = ["-y", "@hauptsache.net/clickup-mcp@latest"]
+env = { "CLICKUP_API_KEY" = "YOUR_KEY", "CLICKUP_TEAM_ID" = "YOUR_ID", "CLICKUP_MCP_MODE" = "read-minimal" }
+```
+
+> Codex seems to not be able to handle images from MCP's. See [this issue](https://github.com/openai/codex/issues/3741) for more details.
+
+> Note the `CLICKUP_MCP_MODE=read-minimal`. This is my usage recommendation, but feel free to use one of the other modes.
 
 ## MCP Modes & Available Tools
 

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AAEA,OAAO,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AAqIpE,QAAA,MAAM,aAAa,oBAAqB,CAAC;AAIzC,OAAO,EAAE,aAAa,EAAE,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AAEA,OAAO,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AAoIpE,QAAA,MAAM,aAAa,oBAAqB,CAAC;AAIzC,OAAO,EAAE,aAAa,EAAE,CAAC"}

package/dist/index.js

@@ -53,8 +53,7 @@ async function initializeServer() {
         title: lang === 'de' ? "Meine TODOs" : "My TODOs",
         description: lang === 'de'
             ? "Meine aktuellen TODO-Aufgaben aus ClickUp abrufen und nach Priorität kategorisiert analysieren"
-            : "Get and analyze my current TODO tasks from ClickUp, categorized by priority",
-        argsSchema: {}
+            : "Get and analyze my current TODO tasks from ClickUp, categorized by priority"
     }, () => {
         const messages = [{
                 role: "user",

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

@@ -1 +1 @@
-{"version":3,"file":"space-resources.d.ts","sourceRoot":"","sources":["../../src/resources/space-resources.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAoB,MAAM,yCAAyC,CAAC;AAiBtF;;GAEG;AACH,wBAAgB,sBAAsB,CAAC,MAAM,EAAE,SAAS,QAuFvD"}
+{"version":3,"file":"space-resources.d.ts","sourceRoot":"","sources":["../../src/resources/space-resources.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAoB,MAAM,yCAAyC,CAAC;AAiBtF;;GAEG;AACH,wBAAgB,sBAAsB,CAAC,MAAM,EAAE,SAAS,QAwFvD"}

package/dist/resources/space-resources.js

@@ -35,6 +35,7 @@ function registerSpaceResources(server) {
                     resources: activeSpaces.map((space) => ({
                         uri: `clickup://space/${space.id}`,
                         name: space.name,
+                        title: space.name,
                         mimeType: "text/plain"
                     }))
                 };

package/dist/shared/utils.d.ts

@@ -61,11 +61,6 @@ export declare function getSpaceContent(spaceId: string): Promise<{
  * Gets all team members from ClickUp API with caching
  */
 export declare function getAllTeamMembers(): Promise<string[]>;
-/**
- * Get or create a document search index with space name resolution
- * Caches promises to prevent race conditions on concurrent calls
- */
-export declare function getDocumentSearchIndex(space_ids?: string[]): Promise<Fuse<any> | null>;
 /**
  * Performs multi-term search with aggressive boosting for items matching multiple terms
  * @param searchIndex Fuse search index to search within

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

@@ -1 +1 @@
-{"version":3,"file":"utils.d.ts","sourceRoot":"","sources":["../../src/shared/utils.ts"],"names":[],"mappings":"AACA,OAAO,IAAI,MAAM,SAAS,CAAC;AAI3B;;;GAGG;AACH,wBAAgB,QAAQ,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAG7C;AAKD;;;GAGG;AACH,wBAAsB,cAAc,iBA6BnC;AAGD,OAAO,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAC;AAIpD;;GAEG;AACH,wBAAgB,eAAe,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,GAAG,CAAC,CA0B7D;AAKD;;;GAGG;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,CA+B3B;AAkED;;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,mBAAmB,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,GAAG,MAAM,CAK1E;AAED;;;GAGG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,GAAG,EAAE,KAAK,EAAE,GAAG,EAAE,EAAE,OAAO,EAAE,GAAG,EAAE,EAAE,SAAS,EAAE,GAAG,EAAE,GAAG,MAAM,CA4ElG;AAKD;;;GAGG;AACH,wBAAsB,mBAAmB,IAAI,OAAO,CAAC,IAAI,CAAC,GAAG,CAAC,GAAG,IAAI,CAAC,CA+CrE;AAKD;;GAEG;AACH,wBAAsB,eAAe,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC;IAAE,KAAK,EAAE,GAAG,EAAE,CAAC;IAAC,OAAO,EAAE,GAAG,EAAE,CAAC;IAAC,SAAS,EAAE,GAAG,EAAE,CAAA;CAAE,CAAC,CAgFlH;AAKD;;GAEG;AACH,wBAAsB,iBAAiB,IAAI,OAAO,CAAC,MAAM,EAAE,CAAC,CA+C3D;AAKD;;;GAGG;AACH,wBAAsB,sBAAsB,CAC1C,SAAS,CAAC,EAAE,MAAM,EAAE,GACnB,OAAO,CAAC,IAAI,CAAC,GAAG,CAAC,GAAG,IAAI,CAAC,CA6B3B;AAuID;;;;;GAKG;AACH,wBAAsB,sBAAsB,CAAC,CAAC,EAC5C,WAAW,EAAE,IAAI,CAAC,CAAC,CAAC,EACpB,KAAK,EAAE,MAAM,EAAE,GACd,OAAO,CAAC,CAAC,EAAE,CAAC,CA8Dd"}
+{"version":3,"file":"utils.d.ts","sourceRoot":"","sources":["../../src/shared/utils.ts"],"names":[],"mappings":"AACA,OAAO,IAAI,MAAM,SAAS,CAAC;AAI3B;;;GAGG;AACH,wBAAgB,QAAQ,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAG7C;AAKD;;;GAGG;AACH,wBAAsB,cAAc,iBA6BnC;AAGD,OAAO,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAC;AAIpD;;GAEG;AACH,wBAAgB,eAAe,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,GAAG,CAAC,CA0B7D;AAKD;;;GAGG;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,CA+B3B;AAkED;;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,mBAAmB,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,GAAG,MAAM,CAK1E;AAED;;;GAGG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,GAAG,EAAE,KAAK,EAAE,GAAG,EAAE,EAAE,OAAO,EAAE,GAAG,EAAE,EAAE,SAAS,EAAE,GAAG,EAAE,GAAG,MAAM,CA4ElG;AAKD;;;GAGG;AACH,wBAAsB,mBAAmB,IAAI,OAAO,CAAC,IAAI,CAAC,GAAG,CAAC,GAAG,IAAI,CAAC,CA+CrE;AAKD;;GAEG;AACH,wBAAsB,eAAe,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC;IAAE,KAAK,EAAE,GAAG,EAAE,CAAC;IAAC,OAAO,EAAE,GAAG,EAAE,CAAC;IAAC,SAAS,EAAE,GAAG,EAAE,CAAA;CAAE,CAAC,CAgFlH;AAKD;;GAEG;AACH,wBAAsB,iBAAiB,IAAI,OAAO,CAAC,MAAM,EAAE,CAAC,CA+C3D;AAED;;;;;GAKG;AACH,wBAAsB,sBAAsB,CAAC,CAAC,EAC5C,WAAW,EAAE,IAAI,CAAC,CAAC,CAAC,EACpB,KAAK,EAAE,MAAM,EAAE,GACd,OAAO,CAAC,CAAC,EAAE,CAAC,CA8Dd"}

package/dist/shared/utils.js

@@ -17,7 +17,6 @@ exports.formatSpaceTree = formatSpaceTree;
 exports.getSpaceSearchIndex = getSpaceSearchIndex;
 exports.getSpaceContent = getSpaceContent;
 exports.getAllTeamMembers = getAllTeamMembers;
-exports.getDocumentSearchIndex = getDocumentSearchIndex;
 exports.performMultiTermSearch = performMultiTermSearch;
 const config_1 = require("./config");
 const fuse_js_1 = __importDefault(require("fuse.js"));
@@ -449,156 +448,6 @@ async function getAllTeamMembers() {
     }, GLOBAL_REFRESH_INTERVAL);
     return fetchPromise;
 }
-// Document search index management - cache promises to prevent race conditions
-const documentIndices = new Map();
-/**
- * Get or create a document search index with space name resolution
- * Caches promises to prevent race conditions on concurrent calls
- */
-async function getDocumentSearchIndex(space_ids) {
-    // Create cache key from sorted filter arrays
-    const key = JSON.stringify({
-        space_ids: space_ids?.sort()
-    });
-    // Check for existing valid index promise
-    const cachedPromise = documentIndices.get(key);
-    if (cachedPromise) {
-        return cachedPromise;
-    }
-    // Create the fetch promise
-    const fetchPromise = (async () => {
-        console.error(`Refreshing document index for filters: ${key}`);
-        const documents = await fetchDocuments(space_ids);
-        const index = createDocumentFuseIndex(documents);
-        console.error(`Document index created with ${documents.length} documents`);
-        return index;
-    })();
-    // Store promise with auto-cleanup
-    documentIndices.set(key, fetchPromise);
-    setTimeout(() => {
-        documentIndices.delete(key);
-        console.error(`Auto-cleaned document index for filters: ${key}`);
-    }, GLOBAL_REFRESH_INTERVAL);
-    return fetchPromise;
-}
-/**
- * Fetch documents and resolve space names
- */
-async function fetchDocuments(space_ids) {
-    try {
-        // Fetch spaces first
-        const spacesResponse = await fetch(`https://api.clickup.com/api/v2/team/${config_1.CONFIG.teamId}/space`, {
-            headers: { Authorization: config_1.CONFIG.apiKey }
-        });
-        if (!spacesResponse.ok) {
-            console.error('Error fetching spaces:', spacesResponse.status);
-            return [];
-        }
-        const spacesData = await spacesResponse.json();
-        // Fetch documents with pagination
-        const allDocuments = [];
-        let nextCursor = null;
-        let pageCount = 0;
-        const maxPages = 10; // Limit to 10 pages to avoid excessive API calls
-        do {
-            const url = new URL(`https://api.clickup.com/api/v3/workspaces/${config_1.CONFIG.teamId}/docs`);
-            url.searchParams.set('limit', '100');
-            if (nextCursor) {
-                url.searchParams.set('next_cursor', nextCursor);
-            }
-            const documentsResponse = await fetch(url.toString(), {
-                headers: { Authorization: config_1.CONFIG.apiKey }
-            });
-            if (!documentsResponse.ok) {
-                console.error('Error fetching documents:', documentsResponse.status);
-                break;
-            }
-            const documentsData = await documentsResponse.json();
-            const pageDocs = documentsData.docs || [];
-            allDocuments.push(...pageDocs);
-            nextCursor = documentsData.next_cursor || null;
-            pageCount++;
-            console.error(`Fetched page ${pageCount} with ${pageDocs.length} documents (total: ${allDocuments.length})`);
-        } while (nextCursor && pageCount < maxPages);
-        const documents = allDocuments;
-        const spaces = spacesData.spaces || [];
-        // Create space lookup map
-        const spaceMap = new Map(spaces.map((space) => [space.id, space]));
-        // Enhance documents with parent information
-        const enhancedDocuments = documents.map((doc) => {
-            // Parent types: 4=Space, 5=Folder, 6=List, 7=Workspace
-            if (doc.parent?.type === 4) {
-                // Space parent - we can resolve the name
-                const space = spaceMap.get(doc.parent.id);
-                return {
-                    ...doc,
-                    space_name: space?.name || 'Unknown',
-                    space_id: doc.parent.id,
-                    parent_info: space?.name ? `Space: ${space.name} (${doc.parent.id})` : `Space: ${doc.parent.id}`
-                };
-            }
-            else if (doc.parent?.type === 6) {
-                // List parent - just show ID
-                return {
-                    ...doc,
-                    space_name: 'N/A',
-                    space_id: null,
-                    parent_info: `List: ${doc.parent.id}`
-                };
-            }
-            else if (doc.parent?.type === 5) {
-                // Folder parent - just show ID
-                return {
-                    ...doc,
-                    space_name: 'N/A',
-                    space_id: null,
-                    parent_info: `Folder: ${doc.parent.id}`
-                };
-            }
-            else if (doc.parent?.type === 7) {
-                // Workspace parent
-                return {
-                    ...doc,
-                    space_name: 'N/A',
-                    space_id: null,
-                    parent_info: `Workspace`
-                };
-            }
-            // Unknown parent type
-            return {
-                ...doc,
-                space_name: 'Unknown',
-                space_id: doc.parent?.id,
-                parent_info: doc.parent ? `Unknown (type ${doc.parent.type})` : 'Unknown'
-            };
-        });
-        // Filter by space_ids if provided
-        if (space_ids?.length) {
-            return enhancedDocuments.filter((doc) => space_ids.includes(doc.space_id));
-        }
-        return enhancedDocuments;
-    }
-    catch (error) {
-        console.error('Error fetching documents:', error);
-        return [];
-    }
-}
-/**
- * Create a Fuse index from documents array
- */
-function createDocumentFuseIndex(documents) {
-    return new fuse_js_1.default(documents, {
-        keys: [
-            { name: 'name', weight: 0.8 },
-            { name: 'space_name', weight: 0.6 },
-            { name: 'id', weight: 0.4 }
-        ],
-        findAllMatches: true,
-        includeScore: true,
-        minMatchCharLength: 2,
-        threshold: 0.4,
-    });
-}
 /**
  * Performs multi-term search with aggressive boosting for items matching multiple terms
  * @param searchIndex Fuse search index to search within

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

@@ -1 +1 @@
-{"version":3,"file":"doc-tools.d.ts","sourceRoot":"","sources":["../../src/tools/doc-tools.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AAoDpE,wBAAgB,yBAAyB,CAAC,MAAM,EAAE,SAAS,QAuR1D;AAED,wBAAgB,0BAA0B,CAAC,MAAM,EAAE,SAAS,QAiP3D"}
+{"version":3,"file":"doc-tools.d.ts","sourceRoot":"","sources":["../../src/tools/doc-tools.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AAoDpE,wBAAgB,yBAAyB,CAAC,MAAM,EAAE,SAAS,QA0J1D;AAED,wBAAgB,0BAA0B,CAAC,MAAM,EAAE,SAAS,QA+R3D"}

package/dist/tools/doc-tools.js

@@ -47,6 +47,7 @@ function displayPageHierarchy(pageGroup, currentPageId, depth = 0) {
 function registerDocumentToolsRead(server) {
     server.tool("readDocument", [
         "Get a ClickUp document with page structure and content.",
+        "Documents can be discovered via searchSpaces (which includes documents in space tree) or by direct URL from the user or within tasks.",
         "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')}`,
@@ -98,8 +99,8 @@ function registerDocumentToolsRead(server) {
 ⚠️ 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")`
+- Use \`createDocumentOrPage\` with doc_id="${doc_id}" to add the first page
+- Example: createDocumentOrPage(doc_id="${doc_id}", name="Introduction", content="Your content here")`
                         }],
                 };
             }
@@ -158,8 +159,8 @@ function registerDocumentToolsRead(server) {
                 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")`);
+                result.push(`Use \`updateDocumentPage\` with doc_id="${doc_id}", page_id="${targetPage.id}" and your content.`);
+                result.push(`Example: updateDocumentPage(doc_id="${doc_id}", page_id="${targetPage.id}", content="Your content here")`);
                 return {
                     content: [
                         { type: "text", text: result.join('\n') },
@@ -179,203 +180,164 @@ function registerDocumentToolsRead(server) {
             };
         }
     });
-    // 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())
+}
+function registerDocumentToolsWrite(server) {
+    server.tool("updateDocumentPage", [
+        "Updates an existing document page's content and/or name.",
+        "Use this when you have both doc_id and page_id from readDocument.",
+        "Content is in markdown format and can be replaced or appended.",
+        "Always reference documents by their URLs when sharing with users."
+    ].join("\n"), {
+        doc_id: zod_1.z
+            .string()
+            .min(1)
+            .describe("The document ID containing the page (from readDocument)"),
+        page_id: zod_1.z
+            .string()
+            .min(1)
+            .describe("The page ID to update (from readDocument)"),
+        name: 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())
+            .describe("Optional: new name for the page"),
+        content: zod_1.z
+            .string()
+            .optional()
+            .describe("Optional: page content in markdown format"),
+        append: zod_1.z
+            .boolean()
             .optional()
-            .describe("Filter documents to specific space IDs")
+            .describe("Whether to append content to existing page content (default: false - replaces content)")
     }, {
-        readOnlyHint: true
-    }, async ({ terms, space_ids }) => {
+        readOnlyHint: false
+    }, async ({ doc_id, page_id, name, content, append = false }) => {
         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.",
-                        },
-                    ],
-                };
+            const requestBody = {};
+            if (name) {
+                requestBody.name = name;
             }
-            let results;
-            if (terms && terms.length > 0) {
-                // Perform multi-term search
-                results = await (0, utils_1.performMultiTermSearch)(searchIndex, terms);
+            if (content !== undefined) {
+                requestBody.content = content;
+                requestBody.content_edit_mode = append ? 'append' : 'replace';
             }
-            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(", ")}` : "";
+            if (Object.keys(requestBody).length === 0) {
                 return {
-                    content: [
-                        {
+                    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"),
-                        },
-                    ],
+                            text: "Error: At least one of 'name' or 'content' must be provided for update."
+                        }],
                 };
             }
-            // 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}`);
+            const response = await fetch(`https://api.clickup.com/api/v3/workspaces/${config_1.CONFIG.teamId}/docs/${doc_id}/pages/${page_id}`, {
+                method: 'PUT',
+                headers: {
+                    Authorization: config_1.CONFIG.apiKey,
+                    'Content-Type': 'application/json',
+                },
+                body: JSON.stringify(requestBody),
             });
-            responseLines.push("", "Use `readDocument` with a document ID to view full content and page structure.");
+            if (!response.ok) {
+                const errorText = await response.text();
+                throw new Error(`Error updating page: ${response.status} ${response.statusText}. ${errorText}`);
+            }
+            // Handle potentially empty response
+            const responseText = await response.text();
+            let updatedPage = {};
+            if (responseText && responseText.trim()) {
+                try {
+                    const data = JSON.parse(responseText);
+                    updatedPage = data.page || data;
+                }
+                catch (e) {
+                    // If JSON parsing fails, continue with empty updatedPage object
+                    console.error('Warning: Could not parse response JSON, but update was successful');
+                }
+            }
+            const pageName = updatedPage.name || name || "page";
             return {
-                content: [
-                    {
+                content: [{
                         type: "text",
-                        text: responseLines.join("\n"),
-                    },
-                ],
+                        text: `✅ Successfully updated page "${pageName}" (page_id: ${page_id})\n\nPage URL: ${(0, utils_1.generateDocumentUrl)(doc_id, page_id)}`
+                    }],
             };
         }
         catch (error) {
-            console.error('Error searching documents:', error);
+            console.error('Error updating document page:', error);
             return {
                 content: [
                     {
                         type: "text",
-                        text: `Error searching documents: ${error instanceof Error ? error.message : 'Unknown error'}`,
+                        text: `Error updating page: ${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."
+    server.tool("createDocumentOrPage", [
+        "Creates a new document with its first page, OR adds a page to an existing document.",
+        "To create a NEW document: provide space_id OR list_id + name + content",
+        "To add a page to EXISTING document: provide doc_id + name + content",
+        "To create a sub-page: provide doc_id + parent_page_id + name + content",
+        "Content is in markdown format and supports ClickUp's markdown features.",
+        "Always reference documents by their URLs when sharing with users."
     ].join("\n"), {
-        page_id: zod_1.z
+        space_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"])
+            .describe("Create NEW document in this space (mutually exclusive with list_id and doc_id)"),
+        list_id: zod_1.z
+            .string()
             .optional()
-            .describe("Type of parent when creating new content (required if page_id not provided)"),
-        parent_id: zod_1.z
+            .describe("Create NEW document in this list (mutually exclusive with space_id and doc_id)"),
+        doc_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
+            .describe("Add page to EXISTING document with this ID (mutually exclusive with space_id and list_id)"),
+        parent_page_id: zod_1.z
             .string()
             .optional()
-            .describe("Name for the page (required for new pages, optional for updates to rename)"),
+            .describe("Optional: when provided with doc_id, creates a sub-page under this parent page"),
+        name: zod_1.z
+            .string()
+            .min(1)
+            .describe("Name for the document/page being created"),
         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)")
+            .describe("Optional: page content in markdown format")
     }, {
         readOnlyHint: false
-    }, async ({ page_id, parent_type, parent_id, page_name, content, append = false }) => {
+    }, async ({ space_id, list_id, doc_id, parent_page_id, name, content }) => {
         try {
-            // Validate input parameters
-            if (!page_id && (!parent_type || !parent_id)) {
+            // Validate mutually exclusive parameters
+            const locationParams = [space_id, list_id, doc_id].filter(Boolean).length;
+            if (locationParams !== 1) {
                 return {
                     content: [{
                             type: "text",
-                            text: "Error: Either page_id (for updates) or both parent_type and parent_id (for creation) must be provided."
+                            text: "Error: Provide exactly ONE of: space_id (new doc in space), list_id (new doc in list), or doc_id (page in existing doc)."
                         }],
                 };
             }
-            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;
+            if (parent_page_id && !doc_id) {
                 return {
                     content: [{
                             type: "text",
-                            text: `✅ Successfully updated page "${updatedPage.name}" (${page_id})\n\nPage URL: ${(0, utils_1.generateDocumentUrl)(updatedPage.doc_id, page_id)}`
+                            text: "Error: parent_page_id requires doc_id to be provided."
                         }],
                 };
             }
-            // Case 2: Create new content
-            let docId;
-            if (parent_type === "space" || parent_type === "list") {
-                // Create new document first, then create first page manually
+            // Case 1: Create new document in space or list
+            if (space_id || list_id) {
+                const parentId = space_id || list_id;
+                const parentType = space_id ? 4 : 6; // 4=Space, 6=List
+                // Create new document
                 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
+                    name: name,
+                    create_page: false,
                     parent: {
-                        id: parent_id,
-                        type: parent_type === "space" ? 4 : parent_type === "list" ? 6 : 7 // 4=Space, 6=List, 7=Workspace
+                        id: parentId,
+                        type: parentType
                     }
                 };
                 const docResponse = await fetch(`https://api.clickup.com/api/v3/workspaces/${config_1.CONFIG.teamId}/docs`, {
@@ -387,16 +349,17 @@ function registerDocumentToolsWrite(server) {
                     body: JSON.stringify(docRequestBody),
                 });
                 if (!docResponse.ok) {
-                    throw new Error(`Error creating document: ${docResponse.status} ${docResponse.statusText}`);
+                    const errorText = await docResponse.text();
+                    throw new Error(`Error creating document: ${docResponse.status} ${docResponse.statusText}. ${errorText}`);
                 }
                 const docData = await docResponse.json();
-                docId = docData.id;
-                // Create the first page manually for better control
+                const newDocId = docData.id;
+                // Create the first page
                 const pageRequestBody = {
-                    name: page_name,
+                    name: name,
                     content: content || '',
                 };
-                const pageResponse = await fetch(`https://api.clickup.com/api/v3/workspaces/${config_1.CONFIG.teamId}/docs/${docId}/pages`, {
+                const pageResponse = await fetch(`https://api.clickup.com/api/v3/workspaces/${config_1.CONFIG.teamId}/docs/${newDocId}/pages`, {
                     method: 'POST',
                     headers: {
                         Authorization: config_1.CONFIG.apiKey,
@@ -405,54 +368,28 @@ function registerDocumentToolsWrite(server) {
                     body: JSON.stringify(pageRequestBody),
                 });
                 if (!pageResponse.ok) {
-                    throw new Error(`Error creating first page: ${pageResponse.status} ${pageResponse.statusText}`);
+                    const errorText = await pageResponse.text();
+                    throw new Error(`Error creating first page: ${pageResponse.status} ${pageResponse.statusText}. ${errorText}`);
                 }
                 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)}`
+                            text: `✅ Successfully created new document "${name}" (doc_id: ${newDocId})\n\nDocument URL: ${(0, utils_1.generateDocumentUrl)(newDocId)}\nFirst Page URL: ${(0, utils_1.generateDocumentUrl)(newDocId, firstPage.id)}`
                         }],
                 };
             }
-            else if (parent_type === "doc") {
-                // Create new page in existing document
-                docId = parent_id;
+            // Case 2: Add page to existing document or create sub-page
+            if (doc_id) {
                 const pageRequestBody = {
-                    name: page_name,
+                    name: 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}`);
+                if (parent_page_id) {
+                    pageRequestBody.parent_page_id = parent_page_id;
                 }
-                const data = await response.json();
-                const newPage = data.page || data; // Handle both nested and flat response formats
-                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`, {
+                const response = await fetch(`https://api.clickup.com/api/v3/workspaces/${config_1.CONFIG.teamId}/docs/${doc_id}/pages`, {
                     method: 'POST',
                     headers: {
                         Authorization: config_1.CONFIG.apiKey,
@@ -461,28 +398,31 @@ function registerDocumentToolsWrite(server) {
                     body: JSON.stringify(pageRequestBody),
                 });
                 if (!response.ok) {
-                    throw new Error(`Error creating sub-page: ${response.status} ${response.statusText}`);
+                    const errorText = await response.text();
+                    throw new Error(`Error creating page: ${response.status} ${response.statusText}. ${errorText}`);
                 }
                 const data = await response.json();
-                const newPage = data.page || data; // Handle both nested and flat response formats
+                const newPage = data.page || data;
+                const pageType = parent_page_id ? "sub-page" : "page";
+                const parentInfo = parent_page_id ? ` under parent page ${parent_page_id}` : "";
                 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)}`
+                            text: `✅ Successfully created ${pageType} "${newPage.name}" (page_id: ${newPage.id})${parentInfo}\n\nPage URL: ${(0, utils_1.generateDocumentUrl)(doc_id, newPage.id)}`
                         }],
                 };
             }
             return {
-                content: [{ type: "text", text: "Error: Invalid parent_type specified." }],
+                content: [{ type: "text", text: "Error: Unexpected state in document/page creation." }],
             };
         }
         catch (error) {
-            console.error('Error in writeDocument:', error);
+            console.error('Error creating document or page:', error);
             return {
                 content: [
                     {
                         type: "text",
-                        text: `Error in document/page operation: ${error instanceof Error ? error.message : 'Unknown error'}`,
+                        text: `Error creating document or page: ${error instanceof Error ? error.message : 'Unknown error'}`,
                     },
                 ],
             };

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,QA2LnE"}
+{"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,QAmLnE"}

package/dist/tools/search-tools.js

@@ -89,11 +89,8 @@ function registerSearchTools(server, userData) {
                     ],
                 };
             }
-            // Fetch time entries for all unique list IDs
-            const uniqueListIds = [...new Set(resultTasks.map((task) => task.list?.id).filter(Boolean))];
-            const timeEntries = await fetchBulkTimeEntries(uniqueListIds);
             return {
-                content: await Promise.all(resultTasks.map((task) => (0, task_tools_1.generateTaskMetadata)(task, timeEntries))),
+                content: await Promise.all(resultTasks.map((task) => (0, task_tools_1.generateTaskMetadata)(task))),
             };
         }
         // Create a results map to track unique tasks with scores
@@ -157,52 +154,8 @@ function registerSearchTools(server, userData) {
                 ],
             };
         }
-        // Fetch time entries for all unique list IDs
-        const uniqueListIds = [...new Set(resultTasks.map((task) => task.list?.id).filter(Boolean))];
-        const timeEntries = await fetchBulkTimeEntries(uniqueListIds);
         return {
-            content: await Promise.all(resultTasks.map((task) => (0, task_tools_1.generateTaskMetadata)(task, timeEntries))),
+            content: await Promise.all(resultTasks.map((task) => (0, task_tools_1.generateTaskMetadata)(task))),
         };
     });
 }
-/**
- * Fetch time entries for a list of unique list IDs
- */
-async function fetchBulkTimeEntries(listIds) {
-    try {
-        // Get all team members for assignee filter
-        const teamMembers = await (0, utils_1.getAllTeamMembers)();
-        const assigneeParam = teamMembers.length > 0 ? teamMembers.join(',') : '';
-        // Calculate 30 days ago timestamp
-        const thirtyDaysAgo = new Date();
-        thirtyDaysAgo.setDate(thirtyDaysAgo.getDate() - 30);
-        const startDate = thirtyDaysAgo.getTime();
-        // Fetch time entries for each unique list ID
-        const timeEntryPromises = listIds.map(async (listId) => {
-            const params = new URLSearchParams({
-                list_id: listId,
-                start_date: startDate.toString(),
-                include_location_names: 'true'
-            });
-            if (assigneeParam) {
-                params.append('assignee', assigneeParam);
-            }
-            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) {
-                console.error(`Error fetching time entries for list ${listId}: ${response.status} ${response.statusText}`);
-                return [];
-            }
-            const data = await response.json();
-            return data.data || [];
-        });
-        // Wait for all requests to complete and flatten results
-        const results = await Promise.all(timeEntryPromises);
-        return results.flat();
-    }
-    catch (error) {
-        console.error('Error fetching bulk time entries:', error);
-        return [];
-    }
-}

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;AA0DpE,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,SAAS,QAgFtD;AAwLD,wBAAgB,sBAAsB,CAAC,MAAM,EAAE,SAAS,QAsFvD"}
+{"version":3,"file":"time-tools.d.ts","sourceRoot":"","sources":["../../src/tools/time-tools.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AAyDpE,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,SAAS,QAgFtD;AAwLD,wBAAgB,sBAAsB,CAAC,MAAM,EAAE,SAAS,QAsFvD"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hauptsache.net/clickup-mcp",
-  "version": "1.4.2",
+  "version": "1.5.0",
   "description": "Search, create, and retrieve tasks, add comments, and track time through natural language commands.",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -12,12 +12,12 @@
   "scripts": {
     "build": "tsc",
     "start": "node dist/index.js",
-    "dev": "tsc -w & nodemon 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",
-    "dxt": "npm run build && npx dxt pack",
+    "mcpb": "npm run build && mcpb pack . ClickUp.mcpb",
     "test": "node --test -r ts-node/register src/**/*.test.ts"
   },
   "keywords": [
@@ -45,6 +45,7 @@
     "zod": "^3.24.2"
   },
   "devDependencies": {
+    "@anthropic-ai/mcpb": "^1.1.1",
     "@types/node": "^22.14.1",
     "dotenv": "^16.5.0",
     "nodemon": "^3.1.9",