@taazkareem/clickup-mcp-server 0.2.0 → 0.2.2

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,125 @@
 
 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
+## Quick Start
 
-- 🔄 **Resource Management**
-  - List and read ClickUp tasks as resources
-  - View task details, status, and assignments
-  - Access task history and relationships
+Directions for use with Cursor Composer Agent:
 
-- 📂 **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. Get your credentials:
+   - ClickUp API key from [ClickUp Settings](https://app.clickup.com/settings/apps)
+   - Team ID from your ClickUp workspace URL
+2. Go to Features in settings
+3. Add under MCP Servers:
 ```bash
-npx @taazkareem/clickup-mcp-server
+npx -y @taazkareem/clickup-mcp-server --env CLICKUP_API_KEY=your_api_key_here --env CLICKUP_TEAM_ID=your_team_id_here
 ```
+4. Replace the credentials and click Save
+5. Use Natural Language to interact with your ClickUp Workspace!
 
-### Global Installation
-```bash
-npm install -g @taazkareem/clickup-mcp-server
-```
+## Features
 
-## Configuration
+- 🎯 **Task Management**
+  - Create, update, and delete tasks
+  - Move and duplicate tasks between lists, spaces, and folders 
+  - Bulk task operations
+  - Task details
 
-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
-```
+- 📂 **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
 
-## Usage
+- 🔄 **Smart Integration**
+  - Case-insensitive name lookups
+  - Markdown support
+  - Automatic rate limiting
+  - Error handling
 
-### Starting the Server
-```bash
-clickup-mcp-server
-```
+- 🤖 **AI Assistance**
+  - Task analysis and insights
+  - Status summaries and priorities
+  - Description assistance
+  - Relationship mapping
+
+## Available Tools
+
+### Workspace Tools
+**get_workspace_hierarchy**
+Returns complete workspace structure (spaces, folders, lists). No parameters required.
+
+### Task Tools
+**get_tasks** `(listId|listName)`
+Get tasks from list with optional filters (archived, page, order_by, reverse, subtasks, statuses, include_closed, assignees, due_date_gt/lt, custom_fields).
+
+**get_task** `(taskId|taskName, ?listName)`
+Get detailed task info including attachments and custom fields.
+
+**create_task** `(listId|listName, taskName)`
+Create task with optional description (markdown), status, priority (1-4), dueDate.
+
+**create_bulk_tasks** `(listId|listName, tasks[])`
+Bulk create tasks with automatic rate limiting. Each task: name (required), description, status, priority, dueDate (optional).
+
+**update_task** `(taskId|taskName, ?listName)`
+Update task name, description, status, priority (1-4), dueDate.
+
+**delete_task** `(taskId|taskName, ?listName)`
+Permanently delete a task.
+
+**move_task** `(taskId|taskName, destinationListId|destinationListName, ?sourceListName)`
+Move task to different list, preserving task data.
+
+**duplicate_task** `(taskId|taskName, destinationListId|destinationListName, ?sourceListName)`
+Create copy of task in specified list.
+
+### List & Folder Tools
+**create_list** `(spaceId|spaceName, listName)`
+Create list with optional content, dueDate, priority (1-4), assignee.
 
-### Available Tools
-
-1. **list_spaces**
-   - Lists all spaces and their lists with IDs
-   - Shows available statuses for each list
-   - No parameters required
-
-2. **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**
-   - 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
+**create_folder** `(spaceId|spaceName, folderName, ?overrideStatuses)`
+Create folder in space.
+
+**create_list_in_folder** `(folderId|folderName, listName)`
+Create list in folder with optional content and 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:
-
-1. Go to the Features section in the settings.
-2. Add the following command under MCP Servers:
-
-```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)
-
-> **Security Note**: Your API key will be stored securely and will not be exposed to AI models.
-
-## Development
+## Support the Developer
 
-1. Clone the repository:
-```bash
-git clone https://github.com/taazkareem/clickup-mcp-server.git
-cd clickup-mcp-server
-```
+If you find this project useful, please consider supporting the developer:
+Talib Kareem (taazkareem@icloud.com)
 
-2. Install dependencies:
-```bash
-npm install
-```
+[![Buy me a coffee](https://img.shields.io/badge/Buy%20me%20a%20coffee-Support-orange)](https://www.buymeacoffee.com/taazkareem)
 
-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 +128,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,7 +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 = {};
 for (let i = 0; i < args.length; i++) {
@@ -9,16 +5,15 @@ for (let i = 0; i < args.length; i++) {
         const [key, value] = args[i + 1].split('=');
         if (key === 'CLICKUP_API_KEY')
             envArgs.clickupApiKey = value;
-        if (key === 'TEAM_ID')
-            envArgs.teamId = value;
-        i++; // Skip the next argument since we used it
+        if (key === 'CLICKUP_TEAM_ID')
+            envArgs.clickupTeamId = value;
+        i++;
     }
 }
 const configuration = {
     clickupApiKey: envArgs.clickupApiKey || process.env.CLICKUP_API_KEY || '',
-    teamId: envArgs.teamId || process.env.TEAM_ID || '',
+    clickupTeamId: envArgs.clickupTeamId || process.env.CLICKUP_TEAM_ID || '',
 };
-// Check for missing environment variables
 const missingEnvVars = Object.entries(configuration)
     .filter(([_, value]) => !value)
     .map(([key]) => key);