@taazkareem/clickup-mcp-server 0.2.0 → 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

@@ -2,223 +2,323 @@
 
 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
-
-- 🔄 **Resource Management**
-  - List and read ClickUp tasks as resources
-  - View task details, status, and assignments
-  - Access task history and relationships
+## Quick Start (Recommended)
 
-- 📂 **Workspace Organization**
-  - Create and manage spaces
-  - Create, update, and delete folders
-  - Create and manage lists (in spaces or folders)
-  - Flexible identification using IDs or names
-
-- ✨ **Task Operations**
-  - Create and update tasks
-  - Move tasks between lists
-  - Duplicate tasks
-  - Set priorities and due dates
-  - Assign team members
-
-- 📊 **Information Retrieval**
-  - Get spaces and lists with their IDs
-  - List available statuses
-  - Find items by name (case-insensitive)
-  - View task relationships
-
-- 📝 **AI Integration**
-  - Generate task descriptions with AI
-  - Summarize tasks and analyze priorities
-  - Get AI-powered task recommendations
-
-- 🔒 **Security**
-  - Secure API key management
-  - Environment-based configuration
-
-## 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
-   - Shows available statuses for each list
-   - No parameters required
+- 🎯 **Task Management**
+  - Create, update, and delete tasks
+  - Move and duplicate tasks between lists, spaces, and folders 
+  - Bulk task operations
+  - Task details
 
-2. **create_task**
+- 📂 **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
+   - 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)
-     - `assignees`: Array of user IDs
-
-3. **create_list**
-   - Creates a new list in a space
-   - Required parameters:
-     - `name`: Name of the list
-   - Optional parameters:
-     - `spaceId`: ID of the space (optional if spaceName provided)
-     - `spaceName`: Name of the space (optional if spaceId provided)
-     - `content`: List description
-     - `status`: List status
-     - `priority`: Priority level (1-4)
-     - `dueDate`: Due date (ISO string)
-
-4. **create_folder**
-   - Creates a new folder in a space
-   - Required parameters:
-     - `name`: Name of the folder
-   - Optional parameters:
-     - `spaceId`: ID of the space (optional if spaceName provided)
-     - `spaceName`: Name of the space (optional if spaceId provided)
-     - `override_statuses`: Whether to override space statuses
-
-5. **create_list_in_folder**
-   - Creates a new list within a folder
-   - Required parameters:
-     - `name`: Name of the list
-   - Optional parameters:
-     - `folderId`: ID of the folder (optional if using folderName)
-     - `folderName`: Name of the folder
-     - `spaceId`: ID of the space (required if using folderName)
-     - `spaceName`: Name of the space (alternative to spaceId)
-     - `content`: List description
-     - `status`: List status
-
-6. **move_task**
-   - Moves a task to a different list
-   - Required parameters:
-     - `taskId`: ID of the task to move
-     - `listId`: ID of the destination list
-
-7. **duplicate_task**
-   - Creates a copy of a task in a specified list
-   - Required parameters:
-     - `taskId`: ID of the task to duplicate
-     - `listId`: ID of the destination list
-
-8. **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:
-     - `name`: New task name
-     - `description`: New description
-     - `status`: New status
-     - `priority`: New priority level (1-4)
-     - `dueDate`: New due date (ISO string)
-
-### 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 comprehensive summary of tasks
-   - Groups tasks by status
-   - Highlights priorities and deadlines
-   - Suggests task relationships
+   - Basic task summary by status
+   - Lists tasks with their current states
+   - Shows task relationships within lists
 
 2. **analyze_priorities**
-   - Analyzes task priority distribution
-   - Identifies misaligned priorities
+   - Reviews current task priorities
    - Suggests priority adjustments
    - Recommends task sequencing
 
 3. **generate_description**
-   - Helps generate detailed task descriptions
-   - Includes:
-     - Clear objectives
-     - Success criteria
-     - Required resources
-     - Dependencies
-     - Potential risks
-
-## Name Resolution
-
-Most tools support finding items by either ID or name:
-- Spaces can be referenced by `spaceId` or `spaceName`
-- Folders can be referenced by `folderId` or `folderName` (with space information)
-- Lists can be referenced by `listId` or found within spaces/folders
-
-Name matching is case-insensitive for convenience.
+   - Interactive prompt for creating task descriptions
+   - Helps structure task information
+   - Includes objectives, criteria, and dependencies
 
 ## Error Handling
 
-The server provides clear error messages for common scenarios:
+The server provides clear error messages for:
 - Missing required parameters
 - Invalid IDs or names
 - Items not found
 - Permission issues
 - API errors
+- Rate limiting
 
-## Using with Cursor AI Composer
-
-To add this server to Cursor AI Composer, follow these steps:
+## Support the Developer
 
-1. Go to the Features section in the settings.
-2. Add the following command under MCP Servers:
+If you find this project useful, please consider supporting the developer:
+Talib Kareem (taazkareem@icloud.com)
 
-```bash
-npx -y @taazkareem/clickup-mcp-server \
-  --env CLICKUP_API_KEY=your_api_key_here \
-  --env TEAM_ID=your_team_id_here
-```
-3. Replace `your_api_key_here` and `your_team_id_here` with your actual ClickUp credentials.
-4. Click on 'Save' to add the server.
-
-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)
+[![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/taazkareem/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
 
@@ -226,4 +326,5 @@ 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. 
+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)