@hauptsache.net/clickup-mcp 1.1.1 → 1.3.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Marco Pfeiffer
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,23 +1,10 @@
 # ClickUp MCP for AI Assistants
 
-Transform your AI assistant into a powerful ClickUp integration for both **agentic coding** and **productivity management**. This Model Context Protocol (MCP) server enables Claude, Windsurf, Cursor, and other AI assistants to seamlessly interact with your ClickUp workspace.
+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. 🧪
 
-## Two Powerful Use Cases
-
-### 🛠️ **For Developers & Agentic Coding**
-Originally built to supercharge coding sessions by providing complete task context to AI coding assistants:
-
-- **Instant Requirements**: *"Get task CU-abc123"* → AI gets full requirements, acceptance criteria, comments, and images
-- **Complete Context**: Pass entire task histories to Claude Code, Windsurf, or Cursor for informed development
-- **Visual Specifications**: Include embedded wireframes, mockups, and screenshots in your coding context
-- **Implementation History**: Access all previous discussions and decisions for better code alignment
-
-### 📋 **For Project Management & Productivity**
-Extended capabilities for conversational ClickUp management and daily workflow optimization.
-
 ## What You Can Do
 
 Turn natural language into powerful ClickUp actions:
@@ -49,6 +36,14 @@ Turn natural language into powerful ClickUp actions:
 - *"What's the latest update on the database migration?"*
 - *"Add a comment to the design task about the new wireframes"*
 
+**Document Management:**
+- *"Find documents about job posting in hauptsache.net space"*
+- *"Search for API documentation across all spaces"*
+- *"Read the API documentation in the development space"*
+- *"Create a new requirements document for the mobile app project"*
+- *"Update the meeting notes with today's decisions"*
+- *"What documents are in the product strategy space?"*
+
 ## Key Features
 
 ### 🔍 **Intelligent Search**
@@ -60,6 +55,7 @@ Turn natural language into powerful ClickUp actions:
 - Full comment histories and team discussions
 - Task descriptions with embedded images  
 - List descriptions and project guidelines
+- Document content with page navigation
 - Access to complete task history and decisions
 
 ### ⏱️ **Time Tracking**
@@ -67,8 +63,9 @@ Turn natural language into powerful ClickUp actions:
 - View historical time logs and entries
 - Query time entries by task or date range
 
-### 📋 **Task Management**
+### 📋 **Task & Document Management**
 - Create and update tasks with markdown descriptions
+- Create, read, and update documents and pages
 - Add comments and collaborate with team members
 - Manage priorities, due dates, assignees, and tags
 - Handle time estimates and custom field values
@@ -92,8 +89,7 @@ Turn natural language into powerful ClickUp actions:
        "clickup": {
          "command": "npx",
          "args": [
-           "-y",
-           "@hauptsache.net/clickup-mcp@1"
+           "@hauptsache.net/clickup-mcp@latest"
          ],
          "env": {
            "CLICKUP_API_KEY": "your_api_key",
@@ -123,15 +119,17 @@ The ClickUp MCP supports three operational modes to balance functionality, secur
 |------|:------------:|:----:|:-----:|-------------|
 | `getTaskById` | ✅ | ✅ | ✅ | Get complete task details including comments, images, and metadata |
 | `searchTasks` | ✅ | ✅ | ✅ | Find tasks by content, keywords, assignees, or project context |
-| `listSpaces` | ❌ | ✅ | ✅ | Browse workspace structure and project organization |
-| `listLists` | ❌ | ✅ | ✅ | Browse lists and folders within spaces |
+| `searchSpaces` | ❌ | ✅ | ✅ | Browse workspace structure, project organization, and documents |
 | `getListInfo` | ❌ | ✅ | ✅ | Get list details and available statuses for task creation |
 | `getTimeEntries` | ❌ | ✅ | ✅ | View time entries and analyze time spent across projects |
+| `readDocument` | ❌ | ✅ | ✅ | Get document details, page structure, and content with navigation |
+| `searchDocuments` | ❌ | ✅ | ✅ | Search documents by name and space with fuzzy matching and space filtering |
 | `createTask` | ❌ | ❌ | ✅ | Create new tasks with full markdown support |
 | `updateTask` | ❌ | ❌ | ✅ | Update tasks (status, priority, assignees, etc.) with **SAFE APPEND-ONLY** descriptions |
 | `updateListInfo` | ❌ | ❌ | ✅ | **SAFE APPEND-ONLY** updates to list descriptions (preserves existing content) |
 | `addComment` | ❌ | ❌ | ✅ | Add comments to tasks for collaboration |
 | `createTimeEntry` | ❌ | ❌ | ✅ | Log time entries for task tracking |
+| `writeDocument` | ❌ | ❌ | ✅ | Universal document and page operations with smart document creation |
 
 ### Setting the Mode
 
@@ -161,6 +159,7 @@ This MCP server can be configured using environment variables:
 - `CLICKUP_TEAM_ID`: (Required) Your ClickUp Team ID (formerly Workspace ID).
 - `CLICKUP_MCP_MODE`: (Optional) Controls which tools are available. Options: `read-minimal`, `read`, `write` (default).
 - `MAX_IMAGES`: (Optional) The maximum number of images to return for a task in `getTaskById`. Defaults to 4.
+- `MAX_RESPONSE_SIZE_MB`: (Optional) The maximum response size in megabytes for `getTaskById`. Uses intelligent size budgeting to fit the most important images within the limit. Defaults to 1.
 - `CLICKUP_PRIMARY_LANGUAGE`: (Optional) A hint for the primary language used in your ClickUp tasks (e.g., "de" for German, "en" for English). This helps the `searchTask` tool provide more tailored guidance in its description for multilingual searches.
 - `LANG`: (Optional) If `CLICKUP_PRIMARY_LANGUAGE` is not set, the MCP will check this standard environment variable (e.g., "en_US.UTF-8", "de_DE") as a fallback to infer the primary language.
 
@@ -219,7 +218,7 @@ This ensures no existing content is ever lost while maintaining a clear audit tr
 ## Performance & Limitations
 
 **Optimized for AI Workflows:**
-- **Image Processing**: Limited to 4 most recent images per task to prevent running into mcp client limitations (configurable via `MAX_IMAGES`)
+- **Smart Image Processing**: Intelligent size budgeting prioritizes the most recent images while respecting both count (`MAX_IMAGES`, default: 4) and total response size limits (`MAX_RESPONSE_SIZE_MB`, default: 1MB)
 - **Search Scope**: Searches within the most recent 1000-3000 tasks to prevent running into rate limits (exact number varies by endpoint)
 - **Search Results**: Returns up to 50 most relevant matches to prevent flooding the agent with too many results
 
@@ -232,4 +231,4 @@ These limitations ensure reliable performance while covering the most common use
 
 ## License
 
-ISC
+MIT

package/dist/cli.js

@@ -7,8 +7,15 @@ async function main() {
     // Wait for server initialization to complete
     const server = await index_1.serverPromise;
     const args = process.argv.slice(2);
+    // Special command to show instructions
+    if (args.length === 1 && args[0] === 'instructions') {
+        console.log("Server Instructions:");
+        console.log(server.server._instructions || "No instructions configured");
+        process.exit(0);
+    }
     if (args.length < 1) {
         console.error("Usage: npm run cli <tool-name> [param1=value1 param2=value2 ...]");
+        console.error("       npm run cli instructions");
         console.error("\nAvailable tools:");
         // @ts-ignore - Accessing private property for testing purposes
         const tools = server._registeredTools;
@@ -90,6 +97,7 @@ async function main() {
         // Call the tool's callback function
         const result = await tool.callback(params);
         console.dir(result.content);
+        process.exit(0);
     }
     catch (error) {
         if (error instanceof Error) {

package/dist/clickup-text.d.ts

@@ -1,4 +1,5 @@
 import { CallToolResult } from "@modelcontextprotocol/sdk/types";
+import { ImageMetadataBlock } from "./shared/types";
 /**
  * Represents a ClickUp text item which can be plain text or an image
  */
@@ -24,6 +25,8 @@ export interface ClickUpTextItem {
  */
 export interface ClickUpAttachment {
     thumbnail_large?: string;
+    thumbnail_medium?: string;
+    thumbnail_small?: string;
     url: string;
     [key: string]: any;
 }
@@ -34,12 +37,12 @@ export interface ClickUpAttachment {
  * @param textItems Array of text items from ClickUp API
  * @returns Promise resolving to an array of content blocks (text and images)
  */
-export declare function processClickUpText(textItems: ClickUpTextItem[]): Promise<CallToolResult["content"]>;
+export declare function processClickUpText(textItems: ClickUpTextItem[]): Promise<(CallToolResult["content"][number] | ImageMetadataBlock)[]>;
 /**
  * Splits markdown text at image references and converts them to image blocks
  * @param markdownText The markdown text to process
  * @param attachments Array of attachments from the Clickup API
  * @returns Array of content blocks (text and images)
  */
-export declare function processClickUpMarkdown(markdownText: string, attachments: ClickUpAttachment[]): Promise<CallToolResult["content"]>;
+export declare function processClickUpMarkdown(markdownText: string, attachments: ClickUpAttachment[] | null | undefined): (CallToolResult["content"][number] | ImageMetadataBlock)[];
 //# sourceMappingURL=clickup-text.d.ts.map

package/dist/clickup-text.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"clickup-text.d.ts","sourceRoot":"","sources":["../src/clickup-text.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,MAAM,iCAAiC,CAAC;AAGjE;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,KAAK,CAAC,EAAE;QACN,EAAE,CAAC,EAAE,MAAM,CAAC;QACZ,IAAI,CAAC,EAAE,MAAM,CAAC;QACd,KAAK,CAAC,EAAE,MAAM,CAAC;QACf,IAAI,CAAC,EAAE,MAAM,CAAC;QACd,SAAS,CAAC,EAAE,MAAM,CAAC;QACnB,eAAe,CAAC,EAAE,MAAM,CAAC;QACzB,gBAAgB,CAAC,EAAE,MAAM,CAAC;QAC1B,eAAe,CAAC,EAAE,MAAM,CAAC;QACzB,GAAG,EAAE,MAAM,CAAC;QACZ,QAAQ,CAAC,EAAE,OAAO,CAAC;KACpB,CAAC;IACF,UAAU,CAAC,EAAE,GAAG,CAAC;CAClB;AAED;;GAEG;AACH,MAAM,WAAW,iBAAiB;IAChC,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,GAAG,EAAE,MAAM,CAAC;IACZ,CAAC,GAAG,EAAE,MAAM,GAAG,GAAG,CAAC;CACpB;AAED;;;;;;GAMG;AACH,wBAAsB,kBAAkB,CACtC,SAAS,EAAE,eAAe,EAAE,GAC3B,OAAO,CAAC,cAAc,CAAC,SAAS,CAAC,CAAC,CAqDpC;AAED;;;;;GAKG;AACH,wBAAsB,sBAAsB,CAC1C,YAAY,EAAE,MAAM,EACpB,WAAW,EAAE,iBAAiB,EAAE,GAC/B,OAAO,CAAC,cAAc,CAAC,SAAS,CAAC,CAAC,CAsEpC"}
+{"version":3,"file":"clickup-text.d.ts","sourceRoot":"","sources":["../src/clickup-text.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,MAAM,iCAAiC,CAAC;AAEjE,OAAO,EAAE,kBAAkB,EAAE,MAAM,gBAAgB,CAAC;AAEpD;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,KAAK,CAAC,EAAE;QACN,EAAE,CAAC,EAAE,MAAM,CAAC;QACZ,IAAI,CAAC,EAAE,MAAM,CAAC;QACd,KAAK,CAAC,EAAE,MAAM,CAAC;QACf,IAAI,CAAC,EAAE,MAAM,CAAC;QACd,SAAS,CAAC,EAAE,MAAM,CAAC;QACnB,eAAe,CAAC,EAAE,MAAM,CAAC;QACzB,gBAAgB,CAAC,EAAE,MAAM,CAAC;QAC1B,eAAe,CAAC,EAAE,MAAM,CAAC;QACzB,GAAG,EAAE,MAAM,CAAC;QACZ,QAAQ,CAAC,EAAE,OAAO,CAAC;KACpB,CAAC;IACF,UAAU,CAAC,EAAE,GAAG,CAAC;CAClB;AAED;;GAEG;AACH,MAAM,WAAW,iBAAiB;IAChC,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,GAAG,EAAE,MAAM,CAAC;IACZ,CAAC,GAAG,EAAE,MAAM,GAAG,GAAG,CAAC;CACpB;AA4BD;;;;;;GAMG;AACH,wBAAsB,kBAAkB,CACtC,SAAS,EAAE,eAAe,EAAE,GAC3B,OAAO,CAAC,CAAC,cAAc,CAAC,SAAS,CAAC,CAAC,MAAM,CAAC,GAAG,kBAAkB,CAAC,EAAE,CAAC,CAiErE;AAED;;;;;GAKG;AACH,wBAAgB,sBAAsB,CACpC,YAAY,EAAE,MAAM,EACpB,WAAW,EAAE,iBAAiB,EAAE,GAAG,IAAI,GAAG,SAAS,GAClD,CAAC,cAAc,CAAC,SAAS,CAAC,CAAC,MAAM,CAAC,GAAG,kBAAkB,CAAC,EAAE,CAyG5D"}

package/dist/clickup-text.js

@@ -2,7 +2,27 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.processClickUpText = processClickUpText;
 exports.processClickUpMarkdown = processClickUpMarkdown;
-const buffer_1 = require("buffer");
+/**
+ * Extract thumbnail URLs from data-attachment attribute JSON
+ * ClickUp API sometimes has broken thumbnail URLs, but data-attachment contains working ones
+ */
+function extractThumbnailsFromDataAttachment(attributes) {
+    if (!attributes || !attributes['data-attachment']) {
+        return {};
+    }
+    try {
+        const attachmentData = JSON.parse(attributes['data-attachment']);
+        return {
+            thumbnail_large: attachmentData.thumbnail_large,
+            thumbnail_medium: attachmentData.thumbnail_medium,
+            thumbnail_small: attachmentData.thumbnail_small,
+        };
+    }
+    catch (error) {
+        console.error('Error parsing data-attachment:', error);
+        return {};
+    }
+}
 /**
  * Process an array of ClickUp text items into a structured content format
  * that includes both text and images in their original sequence
@@ -16,23 +36,37 @@ async function processClickUpText(textItems) {
     for (let i = 0; i < textItems.length; i++) {
         const item = textItems[i];
         // Handle image items
-        if (item.type === "image" && item.image && item.image.thumbnail_large) {
-            // If we have accumulated text, add it as a text block before adding the image
-            if (currentTextBlock.trim()) {
-                contentBlocks.push(Promise.resolve({
-                    type: "text",
-                    text: currentTextBlock.trim(),
-                }));
-            }
-            // Reset current text block after pushing it
-            currentTextBlock = "";
-            // Add this image as an image block
-            if (typeof item.image.thumbnail_large === "string") {
-                contentBlocks.push(loadImageContentBlock(item.image.thumbnail_large, {
-                    type: "text",
-                    text: item.text || "Image",
-                }));
+        if (item.type === "image" && item.image && item.image.url) {
+            // Add image URL reference inline to current text block
+            const imageFileName = item.image.name || item.image.title || "image";
+            currentTextBlock += `\nImage: ${imageFileName} - ${item.image.url}`;
+            // Get working thumbnail URLs from data-attachment if available
+            const extractedThumbnails = extractThumbnailsFromDataAttachment(item.attributes);
+            // Determine best thumbnail URLs (prefer extracted over API thumbnails)
+            const thumbnail_large = extractedThumbnails.thumbnail_large || item.image.thumbnail_large;
+            const thumbnail_medium = extractedThumbnails.thumbnail_medium || item.image.thumbnail_medium;
+            const thumbnail_small = extractedThumbnails.thumbnail_small || item.image.thumbnail_small;
+            // Only create image_metadata if we have at least one thumbnail (never use original image)
+            if (thumbnail_large || thumbnail_medium || thumbnail_small) {
+                // Push accumulated text (including image URL) as a text block
+                if (currentTextBlock.trim()) {
+                    contentBlocks.push({
+                        type: "text",
+                        text: currentTextBlock.trim(),
+                    });
+                }
+                // Reset current text block after pushing it
+                currentTextBlock = "";
+                // Create URLs array with largest to smallest preference, filter out undefined
+                const urls = [thumbnail_large, thumbnail_medium, thumbnail_small].filter(Boolean);
+                // Add image_metadata block for lazy loading
+                contentBlocks.push({
+                    type: "image_metadata",
+                    urls: urls,
+                    alt: item.text || imageFileName,
+                });
             }
+            // If no thumbnails, just treat as a file reference (already added to currentTextBlock)
         }
         // Handle text items
         else if (typeof item.text === "string") {
@@ -45,12 +79,12 @@ async function processClickUpText(textItems) {
     }
     // Add any remaining text
     if (currentTextBlock.trim()) {
-        contentBlocks.push(Promise.resolve({
+        contentBlocks.push({
             type: "text",
             text: currentTextBlock.trim(),
-        }));
+        });
     }
-    return Promise.all(contentBlocks);
+    return contentBlocks;
 }
 /**
  * Splits markdown text at image references and converts them to image blocks
@@ -58,14 +92,14 @@ async function processClickUpText(textItems) {
  * @param attachments Array of attachments from the Clickup API
  * @returns Array of content blocks (text and images)
  */
-async function processClickUpMarkdown(markdownText, attachments) {
+function processClickUpMarkdown(markdownText, attachments) {
     const contentBlocks = [];
     let currentTextBlock = "";
-    // Create a map of attachment URLs to their thumbnail_large URLs for easy lookup
-    const thumbnailMap = new Map();
-    for (const attachment of attachments) {
-        if (typeof attachment.thumbnail_large === "string") {
-            thumbnailMap.set(attachment.url, attachment.thumbnail_large);
+    // Create a map of attachment URLs to their full info for easy lookup
+    const attachmentMap = new Map();
+    if (attachments && Array.isArray(attachments)) {
+        for (const attachment of attachments) {
+            attachmentMap.set(attachment.url, attachment);
         }
     }
     // Regular expression to match markdown image syntax: ![alt text](url)
@@ -77,59 +111,97 @@ async function processClickUpMarkdown(markdownText, attachments) {
         // Add text before the image reference to the current text block
         currentTextBlock += markdownText.substring(lastIndex, match.index);
         // Check if this image URL exists in our attachments
-        const thumbnailUrl = thumbnailMap.get(imageUrl);
-        if (thumbnailUrl) {
-            // If we have accumulated text, add it as a text block before adding the image
-            if (currentTextBlock.trim()) {
-                contentBlocks.push(Promise.resolve({
-                    type: "text",
-                    text: currentTextBlock.trim(),
-                }));
+        const attachment = attachmentMap.get(imageUrl);
+        if (attachment) {
+            // Add image URL reference inline to current text block
+            const imageFileName = altText || "image";
+            currentTextBlock += `\nImage: ${imageFileName} - ${imageUrl}`;
+            // Only create image_metadata if we have at least one thumbnail (never use original image)
+            if (attachment.thumbnail_large || attachment.thumbnail_medium || attachment.thumbnail_small) {
+                // Push accumulated text (including image URL) as a text block
+                if (currentTextBlock.trim()) {
+                    contentBlocks.push({
+                        type: "text",
+                        text: currentTextBlock.trim(),
+                    });
+                }
+                // Reset current text block after pushing it
+                currentTextBlock = "";
+                // Create URLs array with largest to smallest preference, filter out undefined
+                const urls = [attachment.thumbnail_large, attachment.thumbnail_medium, attachment.thumbnail_small].filter(Boolean);
+                // Add image_metadata block for lazy loading
+                contentBlocks.push({
+                    type: "image_metadata",
+                    urls: urls,
+                    alt: altText || imageFileName,
+                });
             }
-            // Reset current text block after pushing it
-            currentTextBlock = "";
-            // Add this image as an image block
-            contentBlocks.push(loadImageContentBlock(thumbnailUrl, {
-                type: "text",
-                text: fullMatch.trim(),
-            }));
+            // If no thumbnails, just treat as a file reference (already added to currentTextBlock)
         }
         else {
             // If the image URL doesn't match any attachment, keep the original markdown in the current text block
             currentTextBlock += fullMatch;
-            console.error(`Image URL ${imageUrl} not found in attachments`, thumbnailMap);
+            console.error(`Image URL ${imageUrl} not found in attachments`, attachmentMap);
         }
         lastIndex = match.index + fullMatch.length;
     }
     // Add any remaining text after the last image
     currentTextBlock += markdownText.substring(lastIndex);
+    // Process non-image attachments that weren't referenced in markdown
+    const referencedUrls = new Set();
+    const imageMatches = markdownText.matchAll(/!\[([^\]]*)\]\(([^\)]+)\)/g);
+    for (const match of imageMatches) {
+        referencedUrls.add(match[2]);
+    }
+    // Add non-image files inline to the current text block
+    if (attachments && Array.isArray(attachments)) {
+        for (const attachment of attachments) {
+            if (!referencedUrls.has(attachment.url)) {
+                // Determine if this is an image based on URL or type
+                const isImage = attachment.thumbnail_large ||
+                    /\.(jpg|jpeg|png|gif|webp|svg)$/i.test(attachment.url);
+                if (!isImage) {
+                    // This is a non-image file - add inline to current text block
+                    const fileName = extractFileNameFromUrl(attachment.url) || "file";
+                    const fileType = extractFileTypeFromUrl(attachment.url);
+                    const fileTypeText = fileType ? ` (${fileType.toUpperCase()})` : "";
+                    currentTextBlock += `\nFile: ${fileName}${fileTypeText} - ${attachment.url}`;
+                }
+            }
+        }
+    }
+    // Add any remaining text (including file references) as final text block
     if (currentTextBlock.trim()) {
-        contentBlocks.push(Promise.resolve({
+        contentBlocks.push({
             type: "text",
             text: currentTextBlock.trim(),
-        }));
+        });
     }
-    return Promise.all(contentBlocks);
+    return contentBlocks;
 }
 /**
- * Loads an image from a URL and converts it to a base64-encoded content block
- *
- * @param url URL of the image to load
- * @param fallback Fallback content if image loading fails
- * @returns Promise resolving to a content block (either image or fallback text)
+ * Extract filename from URL
  */
-async function loadImageContentBlock(url, fallback) {
+function extractFileNameFromUrl(url) {
     try {
-        const response = await fetch(url);
-        const imageBuffer = await response.arrayBuffer();
-        return {
-            type: "image",
-            mimeType: response.headers.get("Content-Type") || "image/png",
-            data: buffer_1.Buffer.from(imageBuffer).toString("base64"),
-        };
+        const urlObj = new URL(url);
+        const pathname = urlObj.pathname;
+        const filename = pathname.split('/').pop();
+        return filename && filename !== '' ? filename : null;
     }
-    catch (error) {
-        console.error(`Error fetching image: ${error.message || "Unknown error"}`);
-        return fallback;
+    catch {
+        return null;
     }
 }
+/**
+ * Extract file extension from URL
+ */
+function extractFileTypeFromUrl(url) {
+    const filename = extractFileNameFromUrl(url);
+    if (!filename)
+        return null;
+    const lastDot = filename.lastIndexOf('.');
+    if (lastDot === -1)
+        return null;
+    return filename.substring(lastDot + 1);
+}

package/dist/index.d.ts

@@ -1,6 +1,5 @@
 #!/usr/bin/env node
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
-declare const server: McpServer;
 declare const serverPromise: Promise<McpServer>;
-export { server, serverPromise };
+export { serverPromise };
 //# sourceMappingURL=index.d.ts.map

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;AAapE,QAAA,MAAM,MAAM,WAGV,CAAC;AAsCH,QAAA,MAAM,aAAa,oBAAqB,CAAC;AAGzC,OAAO,EAAE,MAAM,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;AAkFpE,QAAA,MAAM,aAAa,oBAAqB,CAAC;AAIzC,OAAO,EAAE,aAAa,EAAE,CAAC"}

package/dist/index.js

@@ -1,53 +1,77 @@
 #!/usr/bin/env node
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.serverPromise = exports.server = void 0;
+exports.serverPromise = void 0;
 const mcp_js_1 = require("@modelcontextprotocol/sdk/server/mcp.js");
 const stdio_js_1 = require("@modelcontextprotocol/sdk/server/stdio.js");
 const config_1 = require("./shared/config");
 const utils_1 = require("./shared/utils");
 // Import tool registration functions
 const task_tools_1 = require("./tools/task-tools");
+const task_write_tools_1 = require("./tools/task-write-tools");
 const search_tools_1 = require("./tools/search-tools");
 const space_tools_1 = require("./tools/space-tools");
 const list_tools_1 = require("./tools/list-tools");
 const time_tools_1 = require("./tools/time-tools");
-// Create an MCP server
-const server = new mcp_js_1.McpServer({
-    name: "Clickup MCP",
-    version: "1.0.0",
-});
-exports.server = server;
+const doc_tools_1 = require("./tools/doc-tools");
+// Create server variable that will be initialized later
+let server;
 // Register tools based on mode with user data for enhanced documentation
 async function initializeServer() {
     console.error(`Starting ClickUp MCP in ${config_1.CONFIG.mode} mode`);
-    // Fetch current user for enhanced tool documentation and API health check
-    const userData = await (0, utils_1.getCurrentUser)();
+    // Fetch current user and spaces for enhanced tool documentation and API health check
+    const [userData, spacesIndex] = await Promise.all([
+        (0, utils_1.getCurrentUser)(),
+        (0, utils_1.getSpaceSearchIndex)()
+    ]);
+    const spaces = spacesIndex._docs || [];
     console.error(`Connected as: ${userData.user.username} (${userData.user.email})`);
+    // Filter out archived spaces and format as simple list
+    const activeSpaces = spaces.filter((s) => !s.archived);
+    const formattedSpaces = activeSpaces
+        .map((s) => `- ${s.name} (space_id: ${s.id})`)
+        .join('\n');
+    const instructions = [
+        `ClickUp is a Ticket system. It is used to track tasks, bugs, and other work items.`,
+        `Is you are asked for infos about projects or tasks, search for tasks or documents in ClickUp (this MCP) first.`,
+        `The following spaces/projects are available:`,
+        formattedSpaces
+    ].join('\n');
+    console.error(`Pre-loaded ${activeSpaces.length} active spaces`);
+    // Create the MCP server with instructions
+    server = new mcp_js_1.McpServer({
+        name: "Clickup MCP",
+        version: require('../package.json').version,
+    }, {
+        instructions
+    });
     if (config_1.CONFIG.mode === 'read-minimal') {
         // Core task context tools for AI coding assistance
         // Only getTaskById and searchTasks
         (0, task_tools_1.registerTaskToolsRead)(server, userData);
-        (0, search_tools_1.registerSearchTools)(server);
+        (0, search_tools_1.registerSearchTools)(server, userData);
     }
     else if (config_1.CONFIG.mode === 'read') {
         // All read-only tools
         (0, task_tools_1.registerTaskToolsRead)(server, userData);
-        (0, search_tools_1.registerSearchTools)(server);
+        (0, search_tools_1.registerSearchTools)(server, userData);
         (0, space_tools_1.registerSpaceTools)(server);
         (0, list_tools_1.registerListToolsRead)(server);
         (0, time_tools_1.registerTimeToolsRead)(server);
+        (0, doc_tools_1.registerDocumentToolsRead)(server);
     }
     else if (config_1.CONFIG.mode === 'write') {
         // All tools (full functionality)
         (0, task_tools_1.registerTaskToolsRead)(server, userData);
-        (0, task_tools_1.registerTaskToolsWrite)(server, userData);
-        (0, search_tools_1.registerSearchTools)(server);
+        (0, task_write_tools_1.registerTaskToolsWrite)(server, userData);
+        (0, search_tools_1.registerSearchTools)(server, userData);
         (0, space_tools_1.registerSpaceTools)(server);
         (0, list_tools_1.registerListToolsRead)(server);
         (0, list_tools_1.registerListToolsWrite)(server);
         (0, time_tools_1.registerTimeToolsRead)(server);
         (0, time_tools_1.registerTimeToolsWrite)(server);
+        (0, doc_tools_1.registerDocumentToolsRead)(server);
+        (0, doc_tools_1.registerDocumentToolsWrite)(server);
     }
     return server;
 }

package/dist/shared/config.d.ts

@@ -4,6 +4,7 @@ export declare const CONFIG: {
     apiKey: string;
     teamId: string;
     maxImages: number;
+    maxResponseSizeMB: number;
     primaryLanguageHint: string | undefined;
     mode: McpMode;
 };

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

@@ -1 +1 @@
-{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../../src/shared/config.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,cAAc,oBAA2D,CAAC;AAavF,MAAM,MAAM,OAAO,GAAG,cAAc,GAAG,MAAM,GAAG,OAAO,CAAC;AAUxD,eAAO,MAAM,MAAM;;;;;;CAMlB,CAAC"}
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../../src/shared/config.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,cAAc,oBAA2D,CAAC;AAavF,MAAM,MAAM,OAAO,GAAG,cAAc,GAAG,MAAM,GAAG,OAAO,CAAC;AAUxD,eAAO,MAAM,MAAM;;;;;;;CAOlB,CAAC"}

package/dist/shared/config.js

@@ -23,6 +23,7 @@ exports.CONFIG = {
     apiKey: process.env.CLICKUP_API_KEY,
     teamId: process.env.CLICKUP_TEAM_ID,
     maxImages: process.env.MAX_IMAGES ? parseInt(process.env.MAX_IMAGES) : 4,
+    maxResponseSizeMB: process.env.MAX_RESPONSE_SIZE_MB ? parseFloat(process.env.MAX_RESPONSE_SIZE_MB) : 1,
     primaryLanguageHint: detectedLanguageHint, // Store the cleaned code directly
     mode: mcpMode,
 };

package/dist/shared/image-processing.d.ts

@@ -0,0 +1,13 @@
+import { ContentBlock, ImageMetadataBlock } from "./types";
+/**
+ * Downloads images from image_metadata blocks and applies smart size/count limiting
+ * Prioritizes keeping the most recent images (assumes content is ordered with newest items last)
+ * Uses intelligent size calculation accounting for text content
+ *
+ * @param content Array of content blocks that may contain image_metadata blocks
+ * @param maxImages Maximum number of images to keep (defaults to CONFIG.maxImages)
+ * @param maxSizeMB Maximum response size in MB (defaults to CONFIG.maxResponseSizeMB)
+ * @returns Promise resolving to content array with downloaded images or placeholders
+ */
+export declare function downloadImages(content: (ContentBlock | ImageMetadataBlock)[], maxImages?: number, maxSizeMB?: number): Promise<ContentBlock[]>;
+//# sourceMappingURL=image-processing.d.ts.map

package/dist/shared/image-processing.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"image-processing.d.ts","sourceRoot":"","sources":["../../src/shared/image-processing.ts"],"names":[],"mappings":"AAAA,OAAO,EAAC,YAAY,EAAE,kBAAkB,EAAC,MAAM,SAAS,CAAC;AAIzD;;;;;;;;;GASG;AACH,wBAAsB,cAAc,CAAC,OAAO,EAAE,CAAC,YAAY,GAAG,kBAAkB,CAAC,EAAE,EAAE,SAAS,GAAE,MAAyB,EAAE,SAAS,GAAE,MAAiC,GAAG,OAAO,CAAC,YAAY,EAAE,CAAC,CAwBhM"}