@hauptsache.net/clickup-mcp 1.0.1 → 1.0.3

package/README.md

@@ -1,148 +1,73 @@
-# ClickUp MCP (Model Context Protocol)
+# ClickUp MCP for AI Assistants
 
-A minimal implementation of a Model Context Protocol (MCP) server for ClickUp integration, designed to allow Large Language Models (LLMs) to read ClickUp tasks and data.
+A Model Context Protocol (MCP) server that enables AI assistants like Claude, Windsurf, and Cursor to interact with your ClickUp tasks.
 
-The main focus is to represent tickets in a way that is easy for LLMs to process and understand.
-This especially includes images in the description and in comments of tickets,
-which are not that easy to understand by just passing the api responses.
+## Why This MCP Is Great
 
-## Overview
+This MCP excels at providing AI assistants with rich access to your ClickUp tasks:
 
-This MCP provides a lightweight interface for LLMs to:
-- Retrieve detailed task information by ID
-- Search for tasks using keywords
-- List open tasks assigned to the current user
+- **Complete Task Information**: View detailed task data including status, creation date, and assignees
+- **Full Comment History**: Access the entire conversation thread for context
+- **Inline Images Support**: View images embedded in task descriptions and comments
+- **Task Search**: Find relevant tasks using keywords
+- **Todo Management**: List all your open tasks
 
-The implementation includes image handling for task descriptions, allowing LLMs to process both text content and visual information from ClickUp tasks.
+The standout feature is the ability to retrieve individual tickets with their complete comment history and inline images, giving your AI assistant the full context of your work.
 
-## Prerequisites
+## Limitations
 
-- Node.js (v16 or higher)
-- A ClickUp account with API access
-- ClickUp API key and Team ID
+- **Todo Management**: The todo management feature is currently limited to 50 tasks since it would otherwise flood the context.
+- **No List/Space Support**: This MCP does not currently support browsing ClickUp Lists or Spaces due to performance issues with large instances.
+- **Image Limit**: The MCP processes only the 4 most recent images per task to prevent exceeding context limits. You can adjust this number by setting the `MAX_IMAGES` environment variable, though most AI tools have constraints that prevent using more than 4 images.
 
-## Installation
+## Setup for Claude Desktop, Windsurf, or Cursor
 
-1. Clone this repository
-2. Install dependencies:
+1. **Prerequisites**:
+   - A ClickUp account with API access (Profile Icon > Settings > Apps > API Token ~ usually starts with pk_)
+   - Your ClickUp API key and Team ID (The ~7 digit number in the url when you are in the settings)
 
-```bash
-npm install
-```
+2. **Configuration**:
+   Add the following to your MCP configuration file:
 
-3. Build the TypeScript code:
+   ```json
+   {
+     "mcpServers": {
+       "clickup": {
+         "command": "npx",
+         "args": [
+           "-y",
+           "@hauptsache.net/clickup-mcp"
+         ],
+         "env": {
+           "CLICKUP_API_KEY": "your_api_key",
+           "CLICKUP_TEAM_ID": "your_team_id"
+         }
+       }
+     }
+   }
+   ```
 
-```bash
-npm run build
-```
+   Replace `your_api_key` and `your_team_id` with your actual ClickUp credentials.
 
-## Configuration
+3. **Connect Your AI Assistant**:
+   - **Claude Desktop**: Add this configuration in Settings > MCPs
+   - **Windsurf**: Add to your MCP configuration file
+   - **Cursor**: Configure through the MCP settings panel
 
-Set the following environment variables:
+## Using with Your AI Assistant
 
-- `CLICKUP_API_KEY`: Your ClickUp API key
-- `CLICKUP_TEAM_ID`: Your ClickUp team ID
+Once connected, your AI assistant can:
 
-You can set these variables in your environment or create a `.env` file at the root of the project.
+1. **View Task Details**:
+   Ask: "Show me details for task CU-123456"
 
-## Usage
+2. **Search Tasks**:
+   Ask: "Find tasks related to login functionality"
 
-### As an MCP Server
+3. **Check Your Todo List**:
+   Ask: "What tasks are assigned to me?"
 
-To use this as an MCP server with an LLM:
-
-```bash
-npm start
-```
-
-This will start the server using the standard input/output for communication, following the Model Context Protocol.
-
-### Using with Claude Desktop or Similar LLM Apps
-
-You can use this MCP server with Claude Desktop or similar applications by adding it to your MCP configuration:
-
-```json
-{
-  "mcpServers": {
-    "clickup": {
-      "command": "npx",
-      "args": [
-        "-y",
-        "@hauptsache.net/clickup-mcp"
-      ],
-      "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. This configuration allows Claude or other LLMs to directly access your ClickUp tasks.
-
-### CLI Usage
-
-For testing or manual usage, you can use the CLI interface:
-
-```bash
-# List all available tools
-npm run cli
-
-# Get a task by ID
-npm run cli getTaskById id=abc1234
-
-# Search for tasks
-npm run cli searchTask terms="feature|bug|enhancement"
-
-# List open tasks for the current user
-npm run cli listTodo
-```
-
-## Available Tools
-
-### getTaskById
-
-Retrieves a complete ClickUp task with its description, comments, and embedded images.
-
-Parameters:
-- `id`: The 7-9 character ClickUp task ID (without "#" or "CU-" prefix)
-
-### searchTask
-
-Searches for tasks by name with support for multiple search terms (using OR logic).
-
-Parameters:
-- `terms`: Search terms separated by '|' (e.g., 'term1|term2|term3')
-
-### listTodo
-
-Lists all open tasks assigned to the current user.
-
-Parameters: None
-
-## Development
-
-For development with hot reloading:
-
-```bash
-npm run dev
-```
-
-Format code with Prettier:
-
-```bash
-npm run prettier
-```
-
-## How It Works
-
-This MCP implementation:
-
-1. Connects to the ClickUp API using your API key
-2. Provides tools for LLMs to query and process ClickUp data
-3. Handles image processing in Markdown descriptions
-4. Returns structured data in a format optimized for LLM consumption
+The AI will retrieve the information directly from ClickUp, including all text content, comments, and images, providing you with comprehensive assistance on your tasks.
 
 ## License
 

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;AAgBpE,eAAO,MAAM,MAAM,WAGjB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AAEA,OAAO,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AAiBpE,eAAO,MAAM,MAAM,WAGjB,CAAC"}

package/dist/index.js

@@ -9,6 +9,7 @@ const clickup_text_1 = require("./clickup-text");
 const CONFIG = {
     apiKey: process.env.CLICKUP_API_KEY,
     teamId: process.env.CLICKUP_TEAM_ID,
+    maxImages: process.env.MAX_IMAGES ? parseInt(process.env.MAX_IMAGES) : 4,
 };
 if (!CONFIG.apiKey || !CONFIG.teamId) {
     throw new Error("Missing Clickup API key or team ID");
@@ -18,45 +19,75 @@ exports.server = new mcp_js_1.McpServer({
     name: "Clickup MCP",
     version: "1.0.0",
 });
+/**
+ * Checks if a string looks like a valid ClickUp task ID
+ * Valid task IDs are 7-9 characters long and contain only alphanumeric characters
+ */
+function isTaskId(str) {
+    // Task IDs are 7-9 characters long and contain only alphanumeric characters
+    return /^[a-z0-9]{7,9}$/i.test(str);
+}
 exports.server.tool("getTaskById", "Get a Clickup task with images and comments by ID", {
     id: zod_1.z
         .string()
         .min(7)
         .max(9)
-        .describe(`The 7-9 character ID of the task to get without a prefix like "#" or "CU-"`),
+        .refine(val => isTaskId(val), {
+        message: "Task ID must be 7-9 alphanumeric characters only"
+    })
+        .describe(`The 7-9 character ID of the task to get without a prefix like "#", "CU-" or "https://app.clickup.com/t/"`),
 }, async ({ id }) => {
     const [content, comments] = await Promise.all([
         loadTaskContent(id),
         loadTaskComments(id),
     ]);
+    // Combine all content and limit the number of images
+    const allContent = [...content, ...comments];
+    const limitedContent = limitImages(allContent, CONFIG.maxImages);
     return {
-        content: [...content, ...comments],
+        content: limitedContent,
     };
 });
+/**
+ * Helper function to generate consistent task metadata
+ */
+function generateTaskMetadata(task) {
+    const metadataLines = [
+        `task_id: ${task.id}`,
+        `name: ${task.name}`,
+        `status: ${task.status.status}`,
+        `date_created: ${new Date(+task.date_created)}`,
+        `date_updated: ${new Date(+task.date_updated)}`,
+        `creator: ${task.creator.username}`,
+        `list: ${task.list.name} (${task.list.id})`,
+    ];
+    // Add parent task information if it exists
+    if (typeof task.parent === "string") {
+        metadataLines.push(`parent_task_id: ${task.parent}`);
+    }
+    // Add child task information if it exists
+    if (task.subtasks && task.subtasks.length > 0) {
+        metadataLines.push(`child_task_ids: ${task.subtasks.map((st) => st.id).join(', ')}`);
+    }
+    return {
+        type: "text",
+        text: metadataLines.join("\n"),
+    };
+}
 async function loadTaskContent(id) {
-    const response = await fetch(`https://api.clickup.com/api/v2/task/${id}?include_markdown_description=true`, { headers: { Authorization: CONFIG.apiKey } });
+    const response = await fetch(`https://api.clickup.com/api/v2/task/${id}?include_markdown_description=true&include_subtasks=true`, { headers: { Authorization: CONFIG.apiKey } });
     const task = await response.json();
     const content = await (0, clickup_text_1.processClickUpMarkdown)(task.markdown_description || "", task.attachments);
-    // Create the task metadata block
-    const taskMetadata = {
-        type: "text",
-        text: [
-            `task_id: ${task.id}`,
-            `name: ${task.name}`,
-            `status: ${task.status.status}`,
-            `date_created: ${new Date(+task.date_created)}`,
-            `date_updated: ${new Date(+task.date_updated)}`,
-            `creator: ${task.creator.username}`,
-            `list: ${task.list.name} (${task.list.id})`,
-        ].join("\n"),
-    };
+    // Create the task metadata block using the helper function
+    const taskMetadata = generateTaskMetadata(task);
     return [taskMetadata, ...content];
 }
 async function loadTaskComments(id) {
     const response = await fetch(`https://api.clickup.com/api/v2/task/${id}/comment`, { headers: { Authorization: CONFIG.apiKey } });
     const comments = await response.json();
     return Promise.all(comments.comments
-        .sort((a, b) => +a.date - +b.date)
+        // Sort comments by date, newest first to prioritize recent images
+        .sort((a, b) => +b.date - +a.date)
         .map(async (comment) => {
         // Create a header for the comment
         const commentHeader = {
@@ -80,6 +111,41 @@ async function loadTaskComments(id) {
         }
     }));
 }
+/**
+ * Limits the number of images in the content array, replacing excess images with text placeholders
+ * Prioritizes keeping the most recent images (assumes content is ordered with newest items last)
+ *
+ * @param content Array of content blocks that may contain images
+ * @param maxImages Maximum number of images to keep
+ * @returns Modified content array with limited images
+ */
+function limitImages(content, maxImages) {
+    // Count how many images we have
+    const imageIndices = [];
+    // Find all image blocks
+    content.forEach((block, index) => {
+        if (block.type === "image") {
+            imageIndices.push(index);
+        }
+    });
+    // If we have fewer images than the limit, return the original content
+    if (imageIndices.length <= maxImages) {
+        return content;
+    }
+    // Determine which images to keep (the most recent ones)
+    // We want to keep the last 'maxImages' images
+    const imagesToRemove = imageIndices.slice(0, imageIndices.length - maxImages);
+    // Create a new content array with excess images replaced by text
+    return content.map((block, index) => {
+        if (block.type === "image" && imagesToRemove.includes(index)) {
+            return {
+                type: "text",
+                text: "[Image removed due to size limitations. Only the most recent images are shown.]",
+            };
+        }
+        return block;
+    });
+}
 let cachedTasks = [];
 let lastTaskCacheUpdate = 0;
 exports.server.tool("searchTask", [
@@ -103,10 +169,41 @@ exports.server.tool("searchTask", [
     const searchTerms = terms
         .split("|")
         .map((term) => term.trim().toLowerCase());
-    const tasks = cachedTasks.filter((task) => {
+    // Check if any search term looks like a task ID
+    const potentialTaskIds = searchTerms.filter(isTaskId);
+    // Fetch tasks from cache that match search terms
+    const tasksFromCache = cachedTasks.filter((task) => {
         const taskNameLower = task.name.toLowerCase();
-        return searchTerms.some((term) => taskNameLower.includes(term));
+        const taskId = task.id.toLowerCase();
+        return searchTerms.some((term) => taskNameLower.includes(term) || taskId.includes(term));
+    });
+    // Fetch tasks by ID directly if they look like task IDs and they're not already in the cache
+    const tasksToFetch = potentialTaskIds.filter(id => {
+        // Check if this ID is already in the tasksFromCache
+        return !tasksFromCache.some(task => task.id.toLowerCase() === id.toLowerCase());
+    });
+    const taskPromises = tasksToFetch.map(async (id) => {
+        try {
+            // Fetch task directly from API
+            const response = await fetch(`https://api.clickup.com/api/v2/task/${id}`, { headers: { Authorization: CONFIG.apiKey } });
+            if (!response.ok)
+                return null;
+            const task = await response.json();
+            return task;
+        }
+        catch (error) {
+            console.error(`Error fetching task ${id}:`, error);
+            return null;
+        }
     });
+    // Wait for all task fetches to complete
+    const directlyFetchedTasks = await Promise.all(taskPromises);
+    // Combine tasks from cache and directly fetched tasks, removing nulls
+    const allTasks = [
+        ...tasksFromCache,
+        ...directlyFetchedTasks.filter(Boolean)
+    ];
+    const tasks = allTasks;
     if (tasks.length === 0) {
         return {
             content: [
@@ -118,18 +215,7 @@ exports.server.tool("searchTask", [
         };
     }
     return {
-        content: tasks.map((task) => ({
-            type: "text",
-            text: [
-                `task_id: ${task.id}`,
-                `name: ${task.name}`,
-                `status: ${task.status.status}`,
-                `date_created: ${new Date(+task.date_created)}`,
-                `date_updated: ${new Date(+task.date_updated)}`,
-                `creator: ${task.creator.username}`,
-                `list: ${task.list.name} (${task.list.id})`,
-            ].join("\n"),
-        })),
+        content: tasks.map((task) => generateTaskMetadata(task)),
     };
 });
 exports.server.tool("listTodo", "Lists all open tasks for the current user.", {}, async () => {
@@ -143,8 +229,8 @@ exports.server.tool("listTodo", "Lists all open tasks for the current user.", {}
     const tasks = taskLists.flatMap((tl) => tl.tasks);
     // filter out closed tasks
     const openTasks = tasks
-        .filter((task) => task.status.type !== "done")
-        .slice(0, 100);
+        .filter((task) => task.status.type !== "done") // done is not closed but also not a todo
+        .slice(0, 50);
     if (openTasks.length === 0) {
         return {
             content: [
@@ -153,18 +239,7 @@ exports.server.tool("listTodo", "Lists all open tasks for the current user.", {}
         };
     }
     return {
-        content: openTasks.map((task) => ({
-            type: "text",
-            text: [
-                `task_id: ${task.id}`,
-                `name: ${task.name}`,
-                `status: ${task.status.status}`,
-                `date_created: ${new Date(+task.date_created)}`,
-                `date_updated: ${new Date(+task.date_updated)}`,
-                `creator: ${task.creator.username}`,
-                `list: ${task.list.name} (${task.list.id})`,
-            ].join("\n"),
-        })),
+        content: openTasks.map((task) => generateTaskMetadata(task)),
     };
 });
 // Only connect to the transport if this file is being run directly (not imported)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hauptsache.net/clickup-mcp",
-  "version": "1.0.1",
+  "version": "1.0.3",
   "description": "A minimal implementation of a Model Context Protocol (MCP) server for ClickUp integration",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -15,7 +15,8 @@
     "dev": "tsc -w & nodemon dist/index.js",
     "cli": "npx ts-node src/cli.ts",
     "prettier": "prettier --write src/**/*.ts",
-    "prepublishOnly": "npm run build"
+    "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"
   },
   "keywords": [
     "clickup",