@chykalophia/clickup-mcp-server 3.4.0 → 4.1.2

package/README.md

@@ -1,510 +0,0 @@
-# ClickUp MCP Server - Enhanced
-
-<p align="center">
-  <img src="assets/images/clickupserverlogo.png" width="256" alt="ClickUp MCP Server - Enhanced Logo" />
-</p>
-
-<p align="center">
-  <a href="https://www.npmjs.com/package/@chykalophia/clickup-mcp-server"><img src="https://img.shields.io/npm/v/@chykalophia/clickup-mcp-server.svg" alt="npm version"></a>
-  <a href="https://opensource.org/licenses/MIT"><img src="https://img.shields.io/badge/License-MIT-blue.svg" alt="License: MIT"></a>
-  <a href="https://nodejs.org/"><img src="https://img.shields.io/badge/node-%3E%3D18.0.0-brightgreen" alt="Node.js Version"></a>
-  <a href="https://github.com/modelcontextprotocol/typescript-sdk"><img src="https://img.shields.io/badge/MCP%20SDK-1.6.1-orange" alt="MCP SDK"></a>
-</p>
-
-A comprehensive Model Context Protocol (MCP) server providing AI assistants with complete ClickUp API access. Features **170+ tools**, **AI-powered efficiency**, **production-grade security**, and **full GitHub Flavored Markdown support**.
-
-> **📦 Quick Install**: `npx @chykalophia/clickup-mcp-server` - No build required!
-
-## 📋 Attribution
-
-This Enhanced version is based on the original ClickUp MCP Server codebase by [David Whatley](https://davidwhatley.com) at [nsxdavid/clickup-mcp-server](https://github.com/nsxdavid/clickup-mcp-server).
-
-## 🚀 Key Features
-
-### 🧠 **AI-Powered Efficiency** ⭐
-- **Smart Tool Suggestions**: Context-aware recommendations for optimal workflows
-- **Workflow Optimization**: 50-70% efficiency gains in common workflows  
-- **Intelligent Discovery**: Purpose-built tools that replace inefficient navigation
-- **Direct Access**: Skip hierarchical navigation with smart discovery tools
-
-### ✅ **GitHub Flavored Markdown Support**
-- **Rich Text Formatting**: Headers, bold, italic, code blocks, lists, tables, links
-- **Smart Content Processing**: Automatic markdown ↔ HTML ↔ plain text conversion
-- **Syntax Highlighting**: Code blocks with language-specific highlighting
-- **Backward Compatible**: Existing plain text content continues to work
-
-### 🛠️ **Comprehensive API Coverage**
-- **170+ Total Tools** covering 100% of major ClickUp API endpoints
-- **9 Feature Domains**: Tasks, comments, docs, webhooks, views, dependencies, attachments, time tracking, goals
-- **Real-time Integration**: Webhook processing with HMAC validation
-- **Advanced Workflows**: Dependencies, custom fields, bulk operations
-
-### 🔒 **Production Ready Security**
-- **Zero Vulnerabilities**: Comprehensive security audit with 85+ test cases
-- **Input Validation**: XSS and injection prevention with sanitization
-- **Rate Limiting**: Configurable thresholds (1000 API, 100 webhook, 10 upload/min)
-- **HMAC Validation**: Secure webhook authentication with timing-safe comparison
-- **File Security**: Path traversal prevention, dangerous file blocking, size limits
-
-### 🏷️ **Namespaced Tool Names**
-- **Conflict Prevention**: All tools prefixed with `clickup_` to avoid conflicts with other MCP servers
-- **Clear Identification**: Easy to distinguish ClickUp tools from other services (e.g., `clickup_get_tasks` vs `taskmaster_get_tasks`)
-- **Backward Compatibility**: Previous tool names are deprecated but documented for migration
-- **Examples**: `clickup_create_task`, `clickup_get_workspaces`, `clickup_update_comment`
-
-## 📊 Complete Tool Inventory (170+ Tools)
-
-### 🧠 Efficiency & Intelligence Tools (20+ tools) ⭐
-- **Smart Discovery**: `clickup_find_chat_channels`, `clickup_search_views_by_name`, `clickup_get_workspace_overview`
-- **Workflow Analysis**: `clickup_analyze_tool_efficiency`, `clickup_suggest_tools_for_task`
-- **Enhanced Metadata**: All 153 core tools enhanced with efficiency hints and alternatives
-
-### Core Workspace Management (47 tools)
-- **Workspaces**: `clickup_get_workspaces`, `clickup_get_workspace_seats`
-- **Spaces & Lists**: `clickup_get_spaces`, `clickup_get_lists`, `clickup_create_list`, `clickup_update_list`, `clickup_delete_list`
-- **Tasks**: `clickup_get_tasks`, `clickup_create_task`, `clickup_update_task`, `clickup_get_task_details` (with markdown support)
-- **Comments**: `clickup_create_task_comment`, `clickup_create_list_comment`, `clickup_create_chat_view_comment` (with markdown)
-- **Checklists**: `clickup_create_checklist`, `clickup_update_checklist`, `clickup_create_checklist_item`
-
-### Advanced Feature Domains
-- **📄 Document Management** (18 tools): Full CRUD, pages, sharing, search with markdown support
-- **🔧 Custom Fields** (15 tools): All field types, values, templates, bulk operations
-- **📎 Attachments** (14 tools): Upload, download, versions, thumbnails, security validation
-- **👁️ Views** (13 tools): All view types, filters, grouping, sharing, custom configurations
-- **🔗 Dependencies** (12 tools): Relationships, graphs, conflict detection, critical path
-- **🎯 Goals** (12 tools): All goal types, targets, progress tracking, analytics
-- **🔔 Webhooks** (11 tools): Real-time processing, HMAC validation, event history
-- **⏱️ Time Tracking** (10 tools): Entries, timers, analytics, team tracking
-- **💬 Chat & Communication** (24 tools): Enhanced chat discovery and messaging
-
-## 🚀 Efficiency Examples
-
-### Smart Chat Discovery (60% faster)
-
-Instead of hierarchical navigation:
-```typescript
-// ❌ OLD WAY (4+ API calls)
-clickup_get_workspaces() → clickup_get_spaces() → clickup_get_views() → filter for chat
-
-// ✅ NEW WAY (1 API call)
-clickup_find_chat_channels({ channel_name: "development" })
-```
-
-### Workflow Analysis
-```typescript
-clickup_analyze_workflow_efficiency({
-  goal: "Post message to team chat",
-  planned_tools: ["clickup_get_workspaces", "clickup_get_spaces", "clickup_get_views"],
-  time_constraint: "urgent"
-})
-// Returns: Optimized workflow with 55% efficiency gain
-```
-
-### Real-time Webhook Processing
-```typescript
-// Process ClickUp webhooks with HMAC validation
-clickup_process_webhook({
-  payload: webhookData,
-  validate_signature: true,
-  signature: request.headers['x-signature'],
-  secret: process.env.WEBHOOK_SECRET
-})
-// Returns: Structured event data with relationships and changes
-```
-
-## 📝 Markdown Examples
-
-### Creating a Task with Rich Description
-
-```typescript
-// Task with markdown description using clickup_create_task
-{
-  "list_id": "123456789",
-  "name": "Project Documentation",
-  "description": `# Project Overview
-
-This project implements **advanced features** for our application.
-
-## Key Components
-
-1. **Authentication System**
-   - JWT token management
-   - Role-based access control
-
-2. **API Integration**
-   - RESTful endpoints
-   - Real-time updates
-
-## Code Example
-
-\`\`\`typescript
-interface User {
-  id: string;
-  name: string;
-  role: 'admin' | 'user';
-}
-\`\`\`
-
-## Next Steps
-
-- [x] Set up project structure
-- [ ] Complete authentication module
-- [ ] Implement API endpoints
-
-> **Note**: This is a high-priority project.`
-}
-```
-
-### Adding a Formatted Comment
-
-```typescript
-// Comment with markdown formatting using clickup_create_task_comment
-{
-  "task_id": "868f9p3bg",
-  "comment_text": `## Status Update ✅
-
-### Completed
-- Authentication system implementation
-- Database schema design
-
-### In Progress
-- **API Integration**: Currently working on REST endpoints
-
-### Code Changes
-\`\`\`diff
-+ Added user authentication middleware
-+ Implemented JWT token validation
-- Removed deprecated login method
-\`\`\`
-
-**Estimated Completion**: End of week`
-}
-```
-
-## 🚀 Easy Installation
-
-### Option 1: One-Click Installer (Recommended)
-
-Download and run the automated installer:
-
-```bash
-curl -O https://raw.githubusercontent.com/Chykalophia/ClickUp-MCP-Server---Enhanced/main/clickup-installer.js
-node clickup-installer.js
-```
-
-Or via NPX:
-```bash
-npx clickup-mcp-installer
-```
-
-### Option 2: Web Configurator
-
-Visit the web-based configurator for visual setup:
-[ClickUp MCP Configurator](https://chykalophia.github.io/ClickUp-MCP-Server---Enhanced/configurator.html)
-
-1. Select your preferred version
-2. Enter your ClickUp API token  
-3. Download the generated config file
-4. Place it in your Claude Desktop config directory
-
-### Option 3: NPM Package (Manual Setup)
-
-Use the published npm package - no build required:
-
-```
-@chykalophia/clickup-mcp-server
-```
-
-### Option 4: Build from Source
-
-For development or customization:
-
-```bash
-git clone https://github.com/Chykalophia/ClickUp-MCP-Server---Enhanced.git
-cd ClickUp-MCP-Server---Enhanced
-npm install
-npm run build
-```
-
-## Get ClickUp API Token
-
-1. Log in to ClickUp account
-2. Go to Settings > Apps
-3. Click "Generate API Token"
-4. Copy the token
-
-## Configuration
-
-Add to the MCP settings file:
-
-### 🚀 Quick Setup Configuration
-
-#### NPM Package (Recommended) ⭐
-```json
-{
-  "mcpServers": {
-    "clickup": {
-      "command": "npx",
-      "args": ["-y", "@chykalophia/clickup-mcp-server"],
-      "env": {
-        "CLICKUP_API_TOKEN": "YOUR_API_TOKEN_HERE"
-      }
-    }
-  }
-}
-```
-
-### 🔧 Build from Source (Advanced Users)
-
-If you prefer to build from source:
-
-#### Standard Version
-```json
-{
-  "mcpServers": {
-    "clickup": {
-      "command": "node",
-      "args": ["/path/to/clickup-mcp-server/build/index-enhanced.js"],
-      "env": {
-        "CLICKUP_API_TOKEN": "YOUR_API_TOKEN_HERE"
-      },
-      "disabled": false,
-      "autoApprove": []
-    }
-  }
-}
-```
-
-#### Enhanced Efficiency Version ⭐
-```json
-{
-  "mcpServers": {
-    "clickup": {
-      "command": "node",
-      "args": ["/path/to/clickup-mcp-server/build/index-efficiency-simple.js"],
-      "env": {
-        "CLICKUP_API_TOKEN": "YOUR_API_TOKEN_HERE"
-      },
-      "disabled": false,
-      "autoApprove": []
-    }
-  }
-}
-```
-
-### 📝 Configuration Notes
-
-* **Replace `YOUR_API_TOKEN_HERE`** with your actual ClickUp API token
-* **NPM method** requires no installation or cloning - the package is downloaded automatically
-* **Build from source** requires cloning this repository and running `npm run build`
-
-## Configuration File Locations
-
-- Cline VSCode Extension: `~/.vscode/extensions/saoudrizwan.claude-dev/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json`
-- Claude Desktop Apps:
-  - macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
-  - Windows: `%APPDATA%\Claude\claude_desktop_config.json`
-
-## Examples
-
-See the [`examples/`](examples/) folder for:
-- Basic MCP client usage
-- Tool integration patterns  
-- Authentication setup
-- Advanced workflows
-
-Run examples with: `node examples/basic-usage.js`
-
-## 🔒 Security Features
-
-### Production-Grade Security
-- **Input Validation**: XSS and injection prevention with comprehensive sanitization
-- **API Token Security**: Format validation, secure storage, character validation
-- **Rate Limiting**: Sliding window implementation (1000 API, 100 webhook, 10 upload/min)
-- **HMAC Validation**: Timing-safe webhook signature verification
-- **File Security**: Path traversal prevention, dangerous file blocking, 100MB size limits
-- **URL Validation**: SSRF prevention, private IP blocking, protocol validation
-- **Error Handling**: Secure responses without information leakage
-
-### Security Testing
-- **85+ Test Cases** covering all security scenarios
-- **Zero Vulnerabilities** in dependency audit
-- **Comprehensive Integration Tests** for real-world validation
-- **Security Headers** implementation for HTTP protection
-
-## 📝 Markdown Support
-
-### GitHub Flavored Markdown Features
-- **Headers**: `# H1` through `###### H6`
-- **Text Formatting**: `**bold**`, `*italic*`, `~~strikethrough~~`
-- **Code**: `inline code` and fenced blocks with syntax highlighting
-- **Lists**: Ordered, unordered, and task lists with `- [ ]` checkboxes
-- **Links & Images**: `[text](url)` and `![alt](image-url)`
-- **Tables**: Full table support with alignment
-- **Blockquotes**: `> quoted text` and nested quotes
-
-### Smart Processing
-- **Auto-Detection**: Identifies markdown, HTML, or plain text content
-- **Bidirectional Conversion**: Seamless markdown ↔ HTML ↔ plain text
-- **ClickUp Optimization**: Prepares content in format ClickUp expects
-- **Response Processing**: Converts ClickUp responses to readable markdown
-
-## 🔔 Webhook Processing
-
-### Real-time Integration
-- **Event Processing**: Handle all ClickUp events (tasks, comments, goals, etc.)
-- **HMAC Validation**: Secure signature verification with timing-safe comparison
-- **Event Analysis**: Extract relationships, changes, and context from payloads
-- **Monitoring**: Event history, statistics, and retry mechanisms
-
-### Supported Events
-- **Task Events**: Created, updated, deleted, status changed, assigned
-- **Comment Events**: Posted, updated, threaded discussions
-- **Time Events**: Time tracked, timer started/stopped
-- **Goal Events**: Created, updated, target progress
-- **Workspace Events**: Lists, folders, spaces created/updated/deleted
-
-## Development
-
-### Environment Requirements
-- **Node.js**: Version 18.x or higher
-- **Package Manager**: npm or yarn
-- **IDE**: VSCode recommended with TypeScript support
-
-### Setup
-
-```bash
-# Clone and install
-git clone https://github.com/Chykalophia/ClickUp-MCP-Server---Enhanced.git
-cd ClickUp-MCP-Server---Enhanced
-npm install
-
-# Environment configuration
-cp .env.example .env
-# Edit .env with your CLICKUP_API_TOKEN
-```
-
-### Building
-
-```bash
-npm run build
-```
-
-### Running Tests
-
-```bash
-npm test
-```
-
-### Testing Markdown Features
-
-```bash
-# Test markdown functionality specifically
-npm test -- --testPathPattern=markdown
-
-# Run all tests with coverage
-npm run test:coverage
-```
-
-## Release Procedure
-
-### Pre-release Checklist
-1. Ensure all changes are committed and pushed
-2. Verify all tests pass: `npm test`
-3. Check build process works: `npm run build`
-4. Update CHANGELOG.md with new version details
-
-### Version Update Process
-
-1. **Update package.json version** following semantic versioning:
-   - MAJOR: Incompatible API changes
-   - MINOR: New functionality (backward compatible)
-   - PATCH: Bug fixes (backward compatible)
-
-2. **Update CHANGELOG.md**:
-   ```markdown
-   ## [1.12.0] - 2025-04-14
-   ### Added
-   - New feature descriptions
-   ### Changed
-   - Modified functionality
-   ### Fixed
-   - Bug fixes
-   ```
-
-### Release Steps
-
-1. **Build and Test**:
-   ```bash
-   npm run build
-   npm test
-   ```
-
-2. **Create Git Tag**:
-   ```bash
-   git tag -a v1.12.0 -m "Release v1.12.0: Brief description"
-   git push --tags
-   ```
-
-3. **Publish to NPM**:
-   ```bash
-   npm publish --access public
-   ```
-
-4. **Create GitHub Release**:
-   ```bash
-   gh release create v1.12.0 --title "v1.12.0" --notes "Release notes from CHANGELOG.md"
-   ```
-
-### Post-release Verification
-- Check npm package: https://www.npmjs.com/package/@chykalophia/clickup-mcp-server
-- Verify GitHub release: https://github.com/Chykalophia/ClickUp-MCP-Server---Enhanced/releases
-- Test installation: `npm install @chykalophia/clickup-mcp-server@latest`
-
-## 🔧 Technical Architecture
-
-### Enhanced Client System
-- **Base Client**: Secure ClickUp API client with axios integration
-- **Specialized Clients**: 9 enhanced clients for different feature areas
-- **Type Safety**: Comprehensive TypeScript schemas with Zod validation
-- **Error Handling**: Structured error responses with user-friendly messages
-
-### Performance & Scalability
-- **Efficient Operations**: Bulk operations for multiple items in single requests
-- **Pagination Support**: Handle large datasets efficiently
-- **Memory Management**: Automatic cleanup and optimization
-- **Caching Strategy**: Optimized API usage patterns
-
-### Testing Framework
-- **Security Tests**: 47 test cases covering all attack vectors
-- **Integration Tests**: 15 test cases for end-to-end validation
-- **Error Handling Tests**: 23 test cases for robust error processing
-- **Total Coverage**: 85+ test cases with 80%+ code coverage
-
-## License
-
-MIT
-
-## 🎯 Production Readiness
-
-### Quality Assurance
-- **Security Level**: HIGH - Production approved with zero vulnerabilities
-- **Code Quality**: TypeScript strict mode, comprehensive validation
-- **Test Coverage**: Security-focused testing with 85+ test cases
-- **Documentation**: Complete guides with security audit and examples
-
-### Deployment Features
-- **Health Checks**: Built-in monitoring endpoints
-- **Environment Validation**: Secure configuration verification
-- **Logging & Monitoring**: Structured logging with security event tracking
-- **Error Recovery**: Automatic retry mechanisms and conflict resolution
-
-### Performance Metrics
-- **API Call Reduction**: 50-70% fewer calls for common workflows
-- **Execution Speed**: 40-60% faster completion times
-- **Memory Efficiency**: <1% security overhead, optimized resource usage
-- **Scalability**: Supports high concurrency with efficient batch processing
-
----
-
-**Status**: ✅ **PRODUCTION READY** - Comprehensive ClickUp integration with AI-powered efficiency, production-grade security, and complete API coverage. Ready for immediate deployment and enterprise use.