@taazkareem/clickup-mcp-server 0.1.7 → 0.2.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Talib Kareem
+
+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,117 +1,324 @@
 # ClickUp MCP Server
 
-A Model Context Protocol (MCP) server for integrating ClickUp tasks with AI applications. This server allows AI agents to interact with ClickUp tasks, spaces, and lists through a standardized protocol.
+A Model Context Protocol (MCP) server for integrating ClickUp tasks with AI applications. This server allows AI agents to interact with ClickUp tasks, spaces, lists, and folders through a standardized protocol.
 
-## Features
-
-- 🔄 List and read ClickUp tasks as resources
-- ✨ Create and update tasks through tools
-- 📊 Get spaces and lists with their IDs
-- 📝 Generate task descriptions with AI
-- 📋 Summarize tasks and analyze priorities
-- 🔒 Secure API key management
+## Quick Start (Recommended)
 
-## Installation
-
-### Using npx (Recommended)
+1. Install the server:
 ```bash
-npx @taazkareem/clickup-mcp-server
+npm install -g @taazkareem/clickup-mcp-server
 ```
 
-### Global Installation
+2. Get your credentials:
+   - ClickUp API key from [ClickUp Settings](https://app.clickup.com/settings/apps)
+   - Team ID from your ClickUp workspace URL
+
+3. Start the server:
 ```bash
-npm install -g @taazkareem/clickup-mcp-server
+clickup-mcp-server --env CLICKUP_API_KEY=your_api_key_here --env TEAM_ID=your_team_id_here
 ```
 
-## Configuration
+> **Security Note**: Your API key will be stored securely and not exposed to AI models.
 
-1. Get your ClickUp API key from [ClickUp Settings](https://app.clickup.com/settings/apps)
-2. Create a `.env` file:
-```env
-CLICKUP_API_KEY=your_api_key_here
-TEAM_ID=your_team_id_here
-```
+## Using with Cursor AI Composer
 
-## Usage
+1. Go to Features in settings
+2. Add under MCP Servers:
+```bash
+clickup-mcp-server --env CLICKUP_API_KEY=your_api_key_here --env TEAM_ID=your_team_id_here
+```
+3. Replace the credentials and click Save
 
-### Starting the Server
+## Alternative Installation
+Run directly without installing:
 ```bash
-clickup-mcp-server
+npx @taazkareem/clickup-mcp-server --env CLICKUP_API_KEY=your_api_key_here --env TEAM_ID=your_team_id_here
 ```
 
-### Available Tools
+## Features
 
-1. **list_spaces**
-   - Lists all spaces and their lists with IDs
+- 🎯 **Task Management**
+  - Create, update, and delete tasks
+  - Move and duplicate tasks between lists, spaces, and folders 
+  - Bulk task operations
+  - Task details
+
+- 📂 **Workspace Organization**
+  - Hierarchical tree structure with clear relationships
+  - Efficient navigation with path tracking
+  - List and folder management in spaces
+  - Smart caching to reduce API calls
+  - Name/ID-based item lookup
+  - Optimized task organization
+
+- 🔄 **Smart Integration**
+  - Case-insensitive name lookups
+  - Markdown support
+  - Automatic rate limiting
+  - Error handling
+
+- 🤖 **AI Assistance**
+  - Task analysis and insights
+  - Status summaries and priorities
+  - Description assistance
+  - Relationship mapping
+
+## Available Tools
+
+1. **get_workspace_hierarchy**
+   - Gets complete hierarchy of spaces, folders, and lists
    - No parameters required
-
-2. **create_task**
+   - Returns tree structure showing:
+     ```
+     Workspace (root)
+     ├── Space A
+     │   ├── List 1
+     │   └── Folder 1
+     │       ├── List 2
+     │       └── List 3
+     └── Space B
+         └── List 4
+     ```
+
+2. **get_tasks**
+   - Gets tasks from a ClickUp list with optional filters
+   - List Identification (required):
+     ```
+     listId: "123"      # List ID from ClickUp
+     -- OR --
+     listName: "My List" # List name (case insensitive)
+     ```
+   - Optional Filters:
+     ```
+     archived: true/false        # Include archived tasks
+     page: number               # Page number for pagination
+     order_by: string          # Field to sort by
+     reverse: true/false       # Reverse sort order
+     subtasks: true/false      # Include subtasks
+     statuses: ["status1",..] # Filter by status
+     include_closed: true/false # Include closed tasks
+     assignees: ["user1",..]   # Filter by assignee
+     due_date_gt: timestamp    # Due after date
+     due_date_lt: timestamp    # Due before date
+     custom_fields: {...}      # Filter by custom fields
+     ```
+
+3. **get_task**
+   - Gets detailed information about a specific task
+   - Task Identification (required):
+     ```
+     taskId: "123"       # Task ID from ClickUp
+     -- OR --
+     taskName: "My Task" # Task name (case insensitive)
+     ```
+   - Optional:
+     ```
+     listName: "My List" # Narrow search to specific list
+     ```
+   - Returns full task details including attachments and custom fields
+
+4. **create_task**
    - Creates a new task in ClickUp
-   - Required parameters:
-     - `listId`: ID of the list to create the task in
-     - `name`: Name of the task
-   - Optional parameters:
-     - `description`: Task description
-     - `status`: Task status
-     - `priority`: Priority level (1-4)
-     - `dueDate`: Due date (ISO string)
-
-3. **update_task**
+   - List Identification (required):
+     ```
+     listId: "123"      # List ID from ClickUp
+     -- OR --
+     listName: "My List" # List name (case insensitive)
+     ```
+   - Task Details:
+     ```
+     # Required
+     taskName: "New Task"  # Name of the task to create
+
+     # Optional
+     description: "..."    # Task description (markdown supported)
+     status: "In Progress" # Task status
+     priority: 1-4        # Priority level (1=Urgent, 4=Low)
+     dueDate: timestamp   # Due date
+     ```
+
+5. **create_bulk_tasks**
+   - Creates multiple tasks in a list
+   - List Identification (required):
+     ```
+     listId: "123"      # List ID from ClickUp
+     -- OR --
+     listName: "My List" # List name (case insensitive)
+     ```
+   - Tasks Array (required):
+     ```
+     tasks: [
+       {
+         taskName: "Task 1",    # Required
+         description: "...",    # Optional
+         status: "In Progress", # Optional
+         priority: 1-4,        # Optional
+         dueDate: timestamp    # Optional
+       },
+       // ... more tasks
+     ]
+     ```
+   - Handles rate limiting automatically
+
+6. **update_task**
    - Updates an existing task
-   - Required parameters:
-     - `taskId`: ID of the task to update
-   - Optional parameters:
-     - Same as create_task
-
-### Available Prompts
+   - Task Identification (required):
+     ```
+     taskId: "123"       # Task ID from ClickUp
+     -- OR --
+     taskName: "My Task" # Task name (case insensitive)
+     ```
+   - Optional Updates:
+     ```
+     listName: "My List"     # Narrow search to specific list
+     newName: "Updated Task" # New task name
+     description: "..."      # New description
+     status: "Done"         # New status
+     priority: 1-4          # New priority
+     dueDate: timestamp     # New due date
+     ```
+
+7. **delete_task**
+   - Permanently deletes a task
+   - Task Identification (required):
+     ```
+     taskId: "123"       # Task ID from ClickUp
+     -- OR --
+     taskName: "My Task" # Task name (case insensitive)
+     ```
+   - Optional:
+     ```
+     listName: "My List" # Narrow search to specific list
+     ```
+
+8. **move_task**
+   - Moves a task to a different list
+   - Source Task (required):
+     ```
+     taskId: "123"       # Task ID from ClickUp
+     -- OR --
+     taskName: "My Task" # Task name (case insensitive)
+     ```
+   - Destination List (required):
+     ```
+     destinationListId: "456"      # Target list ID
+     -- OR --
+     destinationListName: "My List" # Target list name
+     ```
+   - Optional:
+     ```
+     sourceListName: "Old List" # Narrow task search to specific list
+     ```
+
+9. **duplicate_task**
+   - Creates a copy of a task in specified list
+   - Source Task (required):
+     ```
+     taskId: "123"       # Task ID from ClickUp
+     -- OR --
+     taskName: "My Task" # Task name (case insensitive)
+     ```
+   - Destination List (required):
+     ```
+     destinationListId: "456"      # Target list ID
+     -- OR --
+     destinationListName: "My List" # Target list name
+     ```
+   - Optional:
+     ```
+     sourceListName: "Current List" # Narrow task search to specific list
+     ```
+
+10. **create_list**
+    - Creates a new list in a space
+    - Space Identification (required):
+      ```
+      spaceId: "123"       # Space ID from ClickUp
+      -- OR --
+      spaceName: "My Space" # Space name (case insensitive)
+      ```
+    - List Details:
+      ```
+      # Required
+      listName: "New List" # Name for the new list
+
+      # Optional
+      content: "..."      # List description
+      dueDate: timestamp  # List due date
+      priority: 1-4       # List priority
+      assignee: "user_id" # Assign to user
+      ```
+
+11. **create_folder**
+    - Creates a new folder in a space
+    - Space Identification (required):
+      ```
+      spaceId: "123"       # Space ID from ClickUp
+      -- OR --
+      spaceName: "My Space" # Space name (case insensitive)
+      ```
+    - Folder Details:
+      ```
+      # Required
+      folderName: "New Folder" # Name for the new folder
+
+      # Optional
+      overrideStatuses: true/false # Override space statuses
+      ```
+
+12. **create_list_in_folder**
+    - Creates a new list within a folder
+    - Folder Identification (required):
+      ```
+      folderId: "123"        # Folder ID from ClickUp
+      -- OR --
+      folderName: "My Folder" # Folder name (case insensitive)
+      ```
+    - List Details:
+      ```
+      # Required
+      listName: "New List" # Name for the new list
+
+      # Optional
+      content: "..."      # List description
+      status: "Active"    # Initial list status
+      ```
+
+## Available Prompts
 
 1. **summarize_tasks**
-   - Provides a summary of all tasks
-   - Groups by status and highlights priorities
+   - Basic task summary by status
+   - Lists tasks with their current states
+   - Shows task relationships within lists
 
 2. **analyze_priorities**
-   - Analyzes task priorities
-   - Suggests optimizations and sequencing
+   - Reviews current task priorities
+   - Suggests priority adjustments
+   - Recommends task sequencing
 
 3. **generate_description**
-   - Helps generate detailed task descriptions
+   - Interactive prompt for creating task descriptions
+   - Helps structure task information
    - Includes objectives, criteria, and dependencies
 
-## Using with Cursor AI Composer
+## Error Handling
 
-To add this server to Cursor AI Composer:
+The server provides clear error messages for:
+- Missing required parameters
+- Invalid IDs or names
+- Items not found
+- Permission issues
+- API errors
+- Rate limiting
 
-```bash
-npx -y @taazkareem/clickup-mcp-server \
-  --env CLICKUP_API_KEY=your_api_key_here \
-  --env TEAM_ID=your_team_id_here
-```
+## Support the Developer
 
-You can get these values from:
-- `CLICKUP_API_KEY`: Get from [ClickUp Settings > Apps](https://app.clickup.com/settings/apps)
-- `TEAM_ID`: Your ClickUp Team ID (found in the URL when viewing your workspace or via API)
+If you find this project useful, please consider supporting the developer:
+Talib Kareem (taazkareem@icloud.com)
 
-> ⚠️ **Important**: Make sure to replace `your_api_key_here` and `your_team_id_here` with your actual ClickUp credentials.
+[![Buy me a coffee](https://img.shields.io/badge/Buy%20me%20a%20coffee-Support-orange)](https://www.buymeacoffee.com/taazkareem)
 
-> **Security Note**: Your API key will be stored securely and will not be exposed to AI models.
-
-## Development
-
-1. Clone the repository:
-```bash
-git clone https://github.com/yourusername/clickup-mcp-server.git
-cd clickup-mcp-server
-```
-
-2. Install dependencies:
-```bash
-npm install
-```
-
-3. Start in development mode:
-```bash
-npm run dev
-```
+<svg xmlns="http://www.w3.org/2000/svg" width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" style="vertical-align: middle; margin-right: 4px;"><path d="M4 18h12l4-4h-12z" /><path d="M8 14l-4-4h12l4 4" /><path d="M16 10l4-4h-12l-4 4" /></svg><span style="vertical-align: middle;">**Solana Wallet:** `GjtRksihd7SWQw7hJSCDMcTxPHbgpNs7xPW3nFubNjVM`</span>
 
 ## Contributing
 
@@ -120,3 +327,4 @@ Contributions are welcome! Please read our [Contributing Guide](CONTRIBUTING.md)
 ## License
 
 This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
+

package/build/config.js

@@ -1,6 +1,3 @@
-import dotenv from 'dotenv';
-// Load environment variables from .env file
-dotenv.config();
 // Parse command line arguments for --env flags
 const args = process.argv.slice(2);
 const envArgs = {};
@@ -15,8 +12,8 @@ for (let i = 0; i < args.length; i++) {
     }
 }
 const configuration = {
-    clickupApiKey: envArgs.clickupApiKey || process.env.CLICKUP_API_KEY || '',
-    teamId: envArgs.teamId || process.env.TEAM_ID || '',
+    clickupApiKey: envArgs.clickupApiKey || '',
+    teamId: envArgs.teamId || '',
 };
 // Check for missing environment variables
 const missingEnvVars = Object.entries(configuration)