@hauptsache.net/clickup-mcp 1.2.0 → 1.3.1

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",
@@ -119,19 +115,21 @@ The ClickUp MCP supports three operational modes to balance functionality, secur
 - **📖 `read`**: Full read-only access for project exploration and workflow understanding  
 - **✏️ `write`** (Default): Complete functionality for task management and productivity workflows
 
-| Tool | read-minimal | read | write | Description |
-|------|:------------:|:----:|:-----:|-------------|
-| `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 |
-| `getListInfo` | ❌ | ✅ | ✅ | Get list details and available statuses for task creation |
-| `getTimeEntries` | ❌ | ✅ | ✅ | View time entries and analyze time spent across projects |
-| `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 |
+| Tool              | read-minimal | read | write | Description                                                                             |
+|-------------------|:------------:|:----:|:-----:|-----------------------------------------------------------------------------------------|
+| `getTaskById`     |      ✅       |  ✅   |   ✅   | Get complete task details including comments, images, and metadata                      |
+| `addComment`      |      ❌       |  ❌   |   ✅   | Add comments to tasks for collaboration                                                 |
+| `updateTask`      |      ❌       |  ❌   |   ✅   | Update tasks (status, priority, assignees, etc.) with **SAFE APPEND-ONLY** descriptions |
+| `createTask`      |      ❌       |  ❌   |   ✅   | Create new tasks with full markdown support                                             |
+| `searchTasks`     |      ✅       |  ✅   |   ✅   | Find tasks by content, keywords, assignees, or project context                          |
+| `searchSpaces`    |      ❌       |  ✅   |   ✅   | Browse workspace structure, project organization, and documents                         |
+| `getListInfo`     |      ❌       |  ✅   |   ✅   | Get list details and available statuses for task creation                               |
+| `updateListInfo`  |      ❌       |  ❌   |   ✅   | **SAFE APPEND-ONLY** updates to list descriptions (preserves existing content)          |
+| `getTimeEntries`  |      ❌       |  ✅   |   ✅   | View time entries and analyze time spent across projects                                |
+| `createTimeEntry` |      ❌       |  ❌   |   ✅   | Log time entries for task tracking                                                      |
+| `readDocument`    |      ❌       |  ✅   |   ✅   | Get document details, page structure, and content with navigation                       |
+| `searchDocuments` |      ❌       |  ✅   |   ✅   | Search documents by name and space with fuzzy matching and space filtering              |
+| `writeDocument`   |      ❌       |  ❌   |   ✅   | Universal document and page operations with smart document creation                     |
 
 ### Setting the Mode
 
@@ -142,7 +140,7 @@ Add the mode to your MCP configuration:
   "mcpServers": {
     "clickup": {
       "command": "npx",
-      "args": ["-y", "@hauptsache.net/clickup-mcp@1"],
+      "args": ["-y", "@hauptsache.net/clickup-mcp@latest"],
       "env": {
         "CLICKUP_API_KEY": "your_api_key",
         "CLICKUP_TEAM_ID": "your_team_id",
@@ -157,10 +155,6 @@ Add the mode to your MCP configuration:
 
 This MCP server can be configured using environment variables:
 
-### ⚠️ Breaking Changes for v1.2.0+
-- **Image Response Size Limiting**: A new `MAX_RESPONSE_SIZE_MB` environment variable (default: 1MB) may cause existing tasks with large images to display fewer images than before. To restore previous behavior, set `MAX_RESPONSE_SIZE_MB=10` (or higher) in your environment.
-- **Enhanced API Rate Limiting**: The search indexing now uses more conservative API call patterns to prevent rate limit exhaustion. Large workspaces may experience slightly slower initial search index building.
-
 - `CLICKUP_API_KEY`: (Required) Your ClickUp API key.
 - `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).
@@ -237,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;

package/dist/clickup-text.d.ts

@@ -44,5 +44,5 @@ export declare function processClickUpText(textItems: ClickUpTextItem[]): Promis
  * @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[]): (CallToolResult["content"][number] | ImageMetadataBlock)[];
+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;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,GAC/B,CAAC,cAAc,CAAC,SAAS,CAAC,CAAC,MAAM,CAAC,GAAG,kBAAkB,CAAC,EAAE,CAqG5D"}
+{"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

@@ -97,8 +97,10 @@ function processClickUpMarkdown(markdownText, attachments) {
     let currentTextBlock = "";
     // Create a map of attachment URLs to their full info for easy lookup
     const attachmentMap = new Map();
-    for (const attachment of attachments) {
-        attachmentMap.set(attachment.url, attachment);
+    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)
     const imageRegex = /!\[([^\]]*)\]\(([^\)]+)\)/g;
@@ -152,17 +154,19 @@ function processClickUpMarkdown(markdownText, attachments) {
         referencedUrls.add(match[2]);
     }
     // Add non-image files inline to the current text block
-    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}`;
+    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}`;
+                }
             }
         }
     }

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;AAcpE,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;AAiIpE,QAAA,MAAM,aAAa,oBAAqB,CAAC;AAIzC,OAAO,EAAE,aAAa,EAAE,CAAC"}

package/dist/index.js

@@ -1,7 +1,7 @@
 #!/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");
@@ -13,18 +13,79 @@ 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: require('../package.json').version,
-});
-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
+    });
+    // Register prompts
+    const lang = config_1.CONFIG.primaryLanguageHint === 'de' ? 'de' : 'en';
+    // Register "my-todos" prompt
+    server.registerPrompt("my-todos", {
+        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: {}
+    }, () => {
+        const messages = [{
+                role: "user",
+                content: {
+                    type: "text",
+                    text: lang === 'de'
+                        ? `Kannst du in ClickUp nachsehen, was meine aktuellen TODOs sind? Bitte suche nach allen offenen Aufgaben, die mir zugewiesen sind, analysiere deren Inhalt und kategorisiere sie nach erkennbarer Priorität (dringend, hoch, normal, niedrig). Für jede Kategorie gib eine kurze Zusammenfassung dessen, was getan werden muss und hebe Fälligkeitstermine oder wichtige Details aus den Aufgabenbeschreibungen hervor.
+
+Bitte strukturiere deine Antwort mit:
+1. **Zusammenfassung**: Gesamtanzahl der Aufgaben und allgemeine Prioritätsverteilung
+2. **Dringende Aufgaben**: Aufgaben, die sofortige Aufmerksamkeit benötigen (heute fällig, überfällig oder als dringend markiert)
+3. **Hohe Priorität**: Wichtige Aufgaben, die bald erledigt werden sollten
+4. **Normale Priorität**: Regelmäßige Aufgaben, die später geplant werden können
+5. **Niedrige Priorität**: Aufgaben, die erledigt werden können, wenn Zeit vorhanden ist
+6. **Empfehlungen**: Vorgeschlagene Maßnahmen oder Prioritäten für den kommenden Zeitraum
+
+Verwende die ClickUp-Suchtools, um mir zugewiesene Aufgaben zu finden, und hole detaillierte Informationen über die wichtigsten mit getTaskById.`
+                        : `Can you look into ClickUp and check what my current TODO's are? Please search for all open tasks assigned to me, analyze their content, and categorize them by apparent priority (urgent, high, normal, low). For each category, provide a brief summary of what needs to be done and highlight any due dates or important details from the task descriptions.
+
+Please structure your response with:
+1. **Summary**: Total number of tasks and overall priority distribution
+2. **Urgent Tasks**: Tasks that need immediate attention (due today, overdue, or marked as urgent)
+3. **High Priority**: Important tasks that should be addressed soon
+4. **Normal Priority**: Regular tasks that can be scheduled for later
+5. **Low Priority**: Tasks that can be done when time permits
+6. **Recommendations**: Suggested actions or priorities for the upcoming period
+
+Use the ClickUp search tools to find tasks assigned to me, and get detailed information about the most important ones using getTaskById.`
+                }
+            }];
+        return { messages };
+    });
     if (config_1.CONFIG.mode === 'read-minimal') {
         // Core task context tools for AI coding assistance
         // Only getTaskById and searchTasks
@@ -38,6 +99,7 @@ async function initializeServer() {
         (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)
@@ -49,6 +111,8 @@ async function initializeServer() {
         (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.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;;;;;;;CAOlB,CAAC"}
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../../src/shared/config.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,cAAc,oBAA2D,CAAC;AAkDvF,MAAM,MAAM,OAAO,GAAG,cAAc,GAAG,MAAM,GAAG,OAAO,CAAC;AAUxD,eAAO,MAAM,MAAM;;;;;;;CAOlB,CAAC"}

package/dist/shared/config.js

@@ -3,13 +3,42 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.CONFIG = exports.rawPrimaryLang = void 0;
 exports.rawPrimaryLang = process.env.CLICKUP_PRIMARY_LANGUAGE || process.env.LANG;
 let detectedLanguageHint = undefined;
-if (exports.rawPrimaryLang) {
-    // Extract the primary language part (e.g., 'en' from 'en_US.UTF-8' or 'en-GB')
-    // and convert to lowercase.
-    const langPart = exports.rawPrimaryLang.match(/^[a-zA-Z]{2,3}/);
+/**
+ * Enhanced language detection that handles various formats and common language names
+ */
+function detectLanguage(rawLang) {
+    if (!rawLang)
+        return undefined;
+    const normalizedLang = rawLang.toLowerCase().trim();
+    // German language detection
+    if (normalizedLang === 'de' || normalizedLang === 'german' || normalizedLang === 'deutsch' || normalizedLang.startsWith('de_') || normalizedLang.startsWith('de-')) {
+        return 'de';
+    }
+    // English language detection
+    if (normalizedLang === 'en' || normalizedLang === 'english' || normalizedLang.startsWith('en_') || normalizedLang.startsWith('en-')) {
+        return 'en';
+    }
+    // French language detection
+    if (normalizedLang === 'fr' || normalizedLang === 'french' || normalizedLang === 'français' || normalizedLang.startsWith('fr_') || normalizedLang.startsWith('fr-')) {
+        return 'fr';
+    }
+    // Spanish language detection
+    if (normalizedLang === 'es' || normalizedLang === 'spanish' || normalizedLang === 'español' || normalizedLang.startsWith('es_') || normalizedLang.startsWith('es-')) {
+        return 'es';
+    }
+    // Italian language detection
+    if (normalizedLang === 'it' || normalizedLang === 'italian' || normalizedLang === 'italiano' || normalizedLang.startsWith('it_') || normalizedLang.startsWith('it-')) {
+        return 'it';
+    }
+    // Fallback: extract the primary language part (e.g., 'en' from 'en_US.UTF-8' or 'en-GB')
+    const langPart = normalizedLang.match(/^[a-zA-Z]{2,3}/);
     if (langPart) {
-        detectedLanguageHint = langPart[0].toLowerCase();
+        return langPart[0].toLowerCase();
     }
+    return undefined;
+}
+if (exports.rawPrimaryLang) {
+    detectedLanguageHint = detectLanguage(exports.rawPrimaryLang);
 }
 const rawMode = process.env.CLICKUP_MCP_MODE?.toLowerCase();
 let mcpMode = 'write'; // Default to write (full functionality)

package/dist/shared/utils.d.ts

@@ -36,46 +36,36 @@ export declare function generateSpaceUrl(spaceId: string): string;
  */
 export declare function generateFolderUrl(folderId: string): string;
 /**
- * Format a ClickUp task link as markdown
+ * Generate a ClickUp document URL from a document ID and optional page ID
  */
-export declare function formatTaskLink(taskId: string, taskName?: string): string;
-/**
- * Format a ClickUp list link as markdown
- */
-export declare function formatListLink(listId: string, listName?: string): string;
-/**
- * Format a ClickUp space link as markdown
- */
-export declare function formatSpaceLink(spaceId: string, spaceName?: string): string;
-/**
- * Extract task ID from a ClickUp URL
- */
-export declare function extractTaskIdFromUrl(url: string): string | null;
-/**
- * Validate if a string is a valid ClickUp URL
- */
-export declare function isClickUpUrl(url: string): boolean;
-/**
- * Format a prominent link section for responses
- */
-export declare function formatLinksSection(links: {
-    text: string;
-    url: string;
-}[]): string;
+export declare function generateDocumentUrl(docId: string, pageId?: string): string;
 /**
  * Get or refresh the space search index
  * Caches promise to prevent race conditions on concurrent calls
  */
 export declare function getSpaceSearchIndex(): Promise<Fuse<any> | null>;
 /**
- * Get lists and folders for a specific space with caching
+ * Get lists, folders, and documents for a specific space with caching
  */
 export declare function getSpaceContent(spaceId: string): Promise<{
     lists: any[];
     folders: any[];
+    documents: any[];
 }>;
 /**
  * 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
+ * @param terms Array of search terms
+ * @returns Array of items sorted by relevance (multi-term matches ranked higher)
+ */
+export declare function performMultiTermSearch<T>(searchIndex: Fuse<T>, terms: string[]): Promise<T[]>;
 //# sourceMappingURL=utils.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"utils.d.ts","sourceRoot":"","sources":["../../src/shared/utils.ts"],"names":[],"mappings":"AAEA,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;AAiED;;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,cAAc,CAAC,MAAM,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,MAAM,GAAG,MAAM,CAIxE;AAED;;GAEG;AACH,wBAAgB,cAAc,CAAC,MAAM,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,MAAM,GAAG,MAAM,CAIxE;AAED;;GAEG;AACH,wBAAgB,eAAe,CAAC,OAAO,EAAE,MAAM,EAAE,SAAS,CAAC,EAAE,MAAM,GAAG,MAAM,CAI3E;AAED;;GAEG;AACH,wBAAgB,oBAAoB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAG/D;AAED;;GAEG;AACH,wBAAgB,YAAY,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAEjD;AAED;;GAEG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,GAAG,EAAE,MAAM,CAAA;CAAE,EAAE,GAAG,MAAM,CAKjF;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,CAAA;CAAE,CAAC,CAgEhG;AAKD;;GAEG;AACH,wBAAsB,iBAAiB,IAAI,OAAO,CAAC,MAAM,EAAE,CAAC,CA+C3D"}
+{"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;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"}