@taazkareem/clickup-mcp-server 0.8.3 → 0.8.4

package/README.md

@@ -6,7 +6,7 @@
 
 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.
 
-> 🚀 **Status Update:** v0.8.3 is released with major enhancements! Enhanced workspace tasks filtering with Views API support for multi-list tasks (Issue #43), added ENABLED_TOOLS configuration option (Issue #50), and fixed automatic priority assignment in task creation. See [Release Notes](release-notes.md) for full details.
+> 🚀 **Status Update:** v0.8.4 is released with security features and compatibility improvements! Added comprehensive opt-in enhanced security features, fixed Gemini compatibility (Issue #79), and resolved priority handling and subtask retrieval issues. See [Release Notes](release-notes.md) for full details.
 
 ## Setup
 
@@ -138,6 +138,36 @@ Available configuration options:
 | `ENABLE_SSE` | Enable the HTTP/SSE transport | `false` |
 | `PORT` | Port for the HTTP server | `3231` |
 | `ENABLE_STDIO` | Enable the STDIO transport | `true` |
+| `ENABLE_SECURITY_FEATURES` | Enable security headers and logging | `false` |
+| `ENABLE_HTTPS` | Enable HTTPS/TLS encryption | `false` |
+| `ENABLE_ORIGIN_VALIDATION` | Validate Origin header against whitelist | `false` |
+| `ENABLE_RATE_LIMIT` | Enable rate limiting protection | `false` |
+
+### 🔒 Security Features
+
+The server includes optional security enhancements for production deployments. All security features are **opt-in** and **disabled by default** to maintain backwards compatibility.
+
+**Quick security setup:**
+```bash
+# Generate SSL certificates for HTTPS
+./scripts/generate-ssl-cert.sh
+
+# Start with full security
+ENABLE_SECURITY_FEATURES=true \
+ENABLE_HTTPS=true \
+ENABLE_ORIGIN_VALIDATION=true \
+ENABLE_RATE_LIMIT=true \
+SSL_KEY_PATH=./ssl/server.key \
+SSL_CERT_PATH=./ssl/server.crt \
+npx @taazkareem/clickup-mcp-server@latest --env CLICKUP_API_KEY=your-key --env CLICKUP_TEAM_ID=your-team --env ENABLE_SSE=true
+```
+
+**HTTPS Endpoints:**
+- **Primary**: `https://127.0.0.1:3443/mcp` (Streamable HTTPS)
+- **Legacy**: `https://127.0.0.1:3443/sse` (SSE HTTPS for backwards compatibility)
+- **Health**: `https://127.0.0.1:3443/health` (Health check)
+
+For detailed security configuration, see [Security Features Documentation](docs/security-features.md).
 
 #### n8n Integration
 

package/build/config.js

@@ -87,6 +87,12 @@ const parseInteger = (value, defaultValue) => {
     const parsed = parseInt(value, 10);
     return isNaN(parsed) ? defaultValue : parsed;
 };
+// Parse comma-separated origins list
+const parseOrigins = (value, defaultValue) => {
+    if (!value)
+        return defaultValue;
+    return value.split(',').map(origin => origin.trim()).filter(origin => origin !== '');
+};
 // Load configuration from command line args or environment variables
 const configuration = {
     clickupApiKey: envArgs.clickupApiKey || process.env.CLICKUP_API_KEY || '',
@@ -100,6 +106,30 @@ const configuration = {
     ssePort: parseInteger(envArgs.ssePort || process.env.SSE_PORT, 3000),
     enableStdio: parseBoolean(envArgs.enableStdio || process.env.ENABLE_STDIO, true),
     port: envArgs.port || process.env.PORT || '3231',
+    // Security configuration (opt-in for backwards compatibility)
+    enableSecurityFeatures: parseBoolean(process.env.ENABLE_SECURITY_FEATURES, false),
+    enableOriginValidation: parseBoolean(process.env.ENABLE_ORIGIN_VALIDATION, false),
+    enableRateLimit: parseBoolean(process.env.ENABLE_RATE_LIMIT, false),
+    enableCors: parseBoolean(process.env.ENABLE_CORS, false),
+    allowedOrigins: parseOrigins(process.env.ALLOWED_ORIGINS, [
+        'http://127.0.0.1:3231',
+        'http://localhost:3231',
+        'http://127.0.0.1:3000',
+        'http://localhost:3000',
+        'https://127.0.0.1:3443',
+        'https://localhost:3443',
+        'https://127.0.0.1:3231',
+        'https://localhost:3231'
+    ]),
+    rateLimitMax: parseInteger(process.env.RATE_LIMIT_MAX, 100),
+    rateLimitWindowMs: parseInteger(process.env.RATE_LIMIT_WINDOW_MS, 60000),
+    maxRequestSize: process.env.MAX_REQUEST_SIZE || '10mb',
+    // HTTPS configuration
+    enableHttps: parseBoolean(process.env.ENABLE_HTTPS, false),
+    httpsPort: process.env.HTTPS_PORT || '3443',
+    sslKeyPath: process.env.SSL_KEY_PATH,
+    sslCertPath: process.env.SSL_CERT_PATH,
+    sslCaPath: process.env.SSL_CA_PATH,
 };
 // Don't log to console as it interferes with JSON-RPC communication
 // Validate only the required variables are present

package/build/middleware/security.js

@@ -0,0 +1,231 @@
+/**
+ * SPDX-FileCopyrightText: © 2025 Talib Kareem <taazkareem@icloud.com>
+ * SPDX-License-Identifier: MIT
+ *
+ * Security Middleware for ClickUp MCP Server
+ *
+ * This module provides optional security enhancements that can be enabled
+ * without breaking existing functionality. All security features are opt-in
+ * to maintain backwards compatibility.
+ */
+import rateLimit from 'express-rate-limit';
+import cors from 'cors';
+import config from '../config.js';
+import { Logger } from '../logger.js';
+const logger = new Logger('Security');
+/**
+ * Origin validation middleware - validates Origin header against whitelist
+ * Only enabled when ENABLE_ORIGIN_VALIDATION=true
+ */
+export function createOriginValidationMiddleware() {
+    return (req, res, next) => {
+        if (!config.enableOriginValidation) {
+            next();
+            return;
+        }
+        const origin = req.headers.origin;
+        const referer = req.headers.referer;
+        // For non-browser requests (like n8n, MCP Inspector), origin might be undefined
+        // In such cases, we allow the request but log it for monitoring
+        if (!origin && !referer) {
+            logger.debug('Request without Origin/Referer header - allowing (likely non-browser client)', {
+                userAgent: req.headers['user-agent'],
+                ip: req.ip,
+                path: req.path
+            });
+            next();
+            return;
+        }
+        // Check if origin is in allowed list
+        if (origin && !config.allowedOrigins.includes(origin)) {
+            logger.warn('Blocked request from unauthorized origin', {
+                origin,
+                ip: req.ip,
+                path: req.path,
+                userAgent: req.headers['user-agent']
+            });
+            res.status(403).json({
+                jsonrpc: '2.0',
+                error: {
+                    code: -32000,
+                    message: 'Forbidden: Origin not allowed'
+                },
+                id: null
+            });
+            return;
+        }
+        // If referer is present, validate it too
+        if (referer) {
+            try {
+                const refererOrigin = new URL(referer).origin;
+                if (!config.allowedOrigins.includes(refererOrigin)) {
+                    logger.warn('Blocked request from unauthorized referer', {
+                        referer,
+                        refererOrigin,
+                        ip: req.ip,
+                        path: req.path
+                    });
+                    res.status(403).json({
+                        jsonrpc: '2.0',
+                        error: {
+                            code: -32000,
+                            message: 'Forbidden: Referer not allowed'
+                        },
+                        id: null
+                    });
+                    return;
+                }
+            }
+            catch (error) {
+                logger.warn('Invalid referer URL', { referer, error: error.message });
+                // Continue processing if referer is malformed
+            }
+        }
+        logger.debug('Origin validation passed', { origin, referer });
+        next();
+    };
+}
+/**
+ * Rate limiting middleware - protects against DoS attacks
+ * Only enabled when ENABLE_RATE_LIMIT=true
+ */
+export function createRateLimitMiddleware() {
+    if (!config.enableRateLimit) {
+        return (_req, _res, next) => next();
+    }
+    return rateLimit({
+        windowMs: config.rateLimitWindowMs,
+        max: config.rateLimitMax,
+        message: {
+            jsonrpc: '2.0',
+            error: {
+                code: -32000,
+                message: 'Too many requests, please try again later'
+            },
+            id: null
+        },
+        standardHeaders: true,
+        legacyHeaders: false,
+        handler: (req, res) => {
+            logger.warn('Rate limit exceeded', {
+                ip: req.ip,
+                path: req.path,
+                userAgent: req.headers['user-agent']
+            });
+            res.status(429).json({
+                jsonrpc: '2.0',
+                error: {
+                    code: -32000,
+                    message: 'Too many requests, please try again later'
+                },
+                id: null
+            });
+        }
+    });
+}
+/**
+ * CORS middleware - configures cross-origin resource sharing
+ * Only enabled when ENABLE_CORS=true
+ */
+export function createCorsMiddleware() {
+    if (!config.enableCors) {
+        return (_req, _res, next) => next();
+    }
+    return cors({
+        origin: (origin, callback) => {
+            // Allow requests with no origin (like mobile apps, Postman, etc.)
+            if (!origin)
+                return callback(null, true);
+            if (config.allowedOrigins.includes(origin)) {
+                callback(null, true);
+            }
+            else {
+                logger.warn('CORS blocked origin', { origin });
+                callback(new Error('Not allowed by CORS'));
+            }
+        },
+        credentials: true,
+        methods: ['GET', 'POST', 'DELETE', 'OPTIONS'],
+        allowedHeaders: ['Content-Type', 'mcp-session-id', 'Authorization'],
+        exposedHeaders: ['mcp-session-id']
+    });
+}
+/**
+ * Security headers middleware - adds security-related HTTP headers
+ * Only enabled when ENABLE_SECURITY_FEATURES=true
+ */
+export function createSecurityHeadersMiddleware() {
+    return (req, res, next) => {
+        if (!config.enableSecurityFeatures) {
+            return next();
+        }
+        // Add security headers
+        res.setHeader('X-Content-Type-Options', 'nosniff');
+        res.setHeader('X-Frame-Options', 'DENY');
+        res.setHeader('X-XSS-Protection', '1; mode=block');
+        res.setHeader('Referrer-Policy', 'strict-origin-when-cross-origin');
+        // Only add HSTS for HTTPS
+        if (req.secure || req.headers['x-forwarded-proto'] === 'https') {
+            res.setHeader('Strict-Transport-Security', 'max-age=31536000; includeSubDomains');
+        }
+        logger.debug('Security headers applied');
+        next();
+    };
+}
+/**
+ * Request logging middleware for security monitoring
+ */
+export function createSecurityLoggingMiddleware() {
+    return (req, res, next) => {
+        if (!config.enableSecurityFeatures) {
+            return next();
+        }
+        const startTime = Date.now();
+        res.on('finish', () => {
+            const duration = Date.now() - startTime;
+            const logData = {
+                method: req.method,
+                path: req.path,
+                statusCode: res.statusCode,
+                duration,
+                ip: req.ip,
+                userAgent: req.headers['user-agent'],
+                origin: req.headers.origin,
+                sessionId: req.headers['mcp-session-id']
+            };
+            if (res.statusCode >= 400) {
+                logger.warn('HTTP error response', logData);
+            }
+            else {
+                logger.debug('HTTP request completed', logData);
+            }
+        });
+        next();
+    };
+}
+/**
+ * Input validation middleware - validates request size and content
+ */
+export function createInputValidationMiddleware() {
+    return (req, res, next) => {
+        // Always enforce reasonable request size limits
+        const contentLength = req.headers['content-length'];
+        if (contentLength && parseInt(contentLength) > 50 * 1024 * 1024) { // 50MB hard limit
+            logger.warn('Request too large', {
+                contentLength,
+                ip: req.ip,
+                path: req.path
+            });
+            res.status(413).json({
+                jsonrpc: '2.0',
+                error: {
+                    code: -32000,
+                    message: 'Request entity too large'
+                },
+                id: null
+            });
+            return;
+        }
+        next();
+    };
+}

package/build/server.js

@@ -45,7 +45,7 @@ const isToolEnabled = (toolName) => {
 };
 export const server = new Server({
     name: "clickup-mcp-server",
-    version: "0.8.3",
+    version: "0.8.4",
 }, {
     capabilities: {
         tools: {},

package/build/services/clickup/task/task-core.js

@@ -232,7 +232,7 @@ export class TaskServiceCore extends BaseClickUpService {
         this.logOperation('getSubtasks', { taskId });
         try {
             return await this.makeRequest(async () => {
-                const response = await this.client.get(`/task/${taskId}`);
+                const response = await this.client.get(`/task/${taskId}?subtasks=true&include_subtasks=true`);
                 // Return subtasks if present, otherwise empty array
                 return response.data.subtasks || [];
             });

package/build/sse_server.js

@@ -12,13 +12,43 @@ import { SSEServerTransport } from '@modelcontextprotocol/sdk/server/sse.js';
 import { StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/streamableHttp.js';
 import { isInitializeRequest } from '@modelcontextprotocol/sdk/types.js';
 import express from 'express';
+import https from 'https';
+import http from 'http';
+import fs from 'fs';
 import { server, configureServer } from './server.js';
 import configuration from './config.js';
+import { createOriginValidationMiddleware, createRateLimitMiddleware, createCorsMiddleware, createSecurityHeadersMiddleware, createSecurityLoggingMiddleware, createInputValidationMiddleware } from './middleware/security.js';
+import { Logger } from './logger.js';
 const app = express();
-app.use(express.json());
+const logger = new Logger('SSEServer');
 export function startSSEServer() {
     // Configure the unified server first
     configureServer();
+    // Apply security middleware (all are opt-in via environment variables)
+    logger.info('Configuring security middleware', {
+        securityFeatures: configuration.enableSecurityFeatures,
+        originValidation: configuration.enableOriginValidation,
+        rateLimit: configuration.enableRateLimit,
+        cors: configuration.enableCors
+    });
+    // Always apply input validation (reasonable defaults)
+    app.use(createInputValidationMiddleware());
+    // Apply optional security middleware
+    app.use(createSecurityLoggingMiddleware());
+    app.use(createSecurityHeadersMiddleware());
+    app.use(createCorsMiddleware());
+    app.use(createOriginValidationMiddleware());
+    app.use(createRateLimitMiddleware());
+    // Configure JSON parsing with configurable size limit
+    app.use(express.json({
+        limit: configuration.maxRequestSize,
+        verify: (req, res, buf) => {
+            // Additional validation can be added here if needed
+            if (buf.length === 0) {
+                logger.debug('Empty request body received');
+            }
+        }
+    }));
     const transports = {
         streamable: {},
         sse: {},
@@ -27,6 +57,12 @@ export function startSSEServer() {
     app.post('/mcp', async (req, res) => {
         try {
             const sessionId = req.headers['mcp-session-id'];
+            logger.debug('MCP request received', {
+                sessionId,
+                hasBody: !!req.body,
+                contentType: req.headers['content-type'],
+                origin: req.headers.origin
+            });
             let transport;
             if (sessionId && transports.streamable[sessionId]) {
                 transport = transports.streamable[sessionId];
@@ -87,7 +123,11 @@ export function startSSEServer() {
     app.get('/sse', async (req, res) => {
         const transport = new SSEServerTransport('/messages', res);
         transports.sse[transport.sessionId] = transport;
-        console.log(`New SSE connection established with sessionId: ${transport.sessionId}`);
+        logger.info('New SSE connection established', {
+            sessionId: transport.sessionId,
+            origin: req.headers.origin,
+            userAgent: req.headers['user-agent']
+        });
         res.on('close', () => {
             delete transports.sse[transport.sessionId];
         });
@@ -103,11 +143,135 @@ export function startSSEServer() {
             res.status(400).send('No transport found for sessionId');
         }
     });
-    const PORT = Number(configuration.port ?? '3231');
-    // Bind to localhost only for security
-    app.listen(PORT, () => {
-        console.log(`Server started on http://127.0.0.1:${PORT}`);
-        console.log(`Streamable HTTP endpoint: http://127.0.0.1:${PORT}/mcp`);
-        console.log(`Legacy SSE endpoint: http://127.0.0.1:${PORT}/sse`);
+    // Health check endpoint
+    app.get('/health', (req, res) => {
+        res.json({
+            status: 'healthy',
+            timestamp: new Date().toISOString(),
+            version: '0.8.3',
+            security: {
+                featuresEnabled: configuration.enableSecurityFeatures,
+                originValidation: configuration.enableOriginValidation,
+                rateLimit: configuration.enableRateLimit,
+                cors: configuration.enableCors
+            }
+        });
     });
+    // Server creation and startup
+    const PORT = Number(configuration.port ?? '3231');
+    const HTTPS_PORT = Number(configuration.httpsPort ?? '3443');
+    // Function to create and start HTTP server
+    function startHttpServer() {
+        const httpServer = http.createServer(app);
+        httpServer.listen(PORT, '127.0.0.1', () => {
+            logger.info('ClickUp MCP Server (HTTP) started', {
+                port: PORT,
+                protocol: 'http',
+                endpoints: {
+                    streamableHttp: `http://127.0.0.1:${PORT}/mcp`,
+                    legacySSE: `http://127.0.0.1:${PORT}/sse`,
+                    health: `http://127.0.0.1:${PORT}/health`
+                },
+                security: {
+                    featuresEnabled: configuration.enableSecurityFeatures,
+                    originValidation: configuration.enableOriginValidation,
+                    rateLimit: configuration.enableRateLimit,
+                    cors: configuration.enableCors,
+                    httpsEnabled: configuration.enableHttps
+                }
+            });
+            console.log(`✅ ClickUp MCP Server started on http://127.0.0.1:${PORT}`);
+            console.log(`📡 Streamable HTTP endpoint: http://127.0.0.1:${PORT}/mcp`);
+            console.log(`🔄 Legacy SSE endpoint: http://127.0.0.1:${PORT}/sse`);
+            console.log(`❤️  Health check: http://127.0.0.1:${PORT}/health`);
+            if (configuration.enableHttps) {
+                console.log(`⚠️  HTTP server running alongside HTTPS - consider disabling HTTP in production`);
+            }
+        });
+        return httpServer;
+    }
+    // Function to create and start HTTPS server
+    function startHttpsServer() {
+        if (!configuration.sslKeyPath || !configuration.sslCertPath) {
+            logger.error('HTTPS enabled but SSL certificate paths not provided', {
+                sslKeyPath: configuration.sslKeyPath,
+                sslCertPath: configuration.sslCertPath
+            });
+            console.log(`❌ HTTPS enabled but SSL_KEY_PATH and SSL_CERT_PATH not provided`);
+            console.log(`   Set SSL_KEY_PATH and SSL_CERT_PATH environment variables`);
+            return null;
+        }
+        try {
+            // Check if certificate files exist
+            if (!fs.existsSync(configuration.sslKeyPath)) {
+                throw new Error(`SSL key file not found: ${configuration.sslKeyPath}`);
+            }
+            if (!fs.existsSync(configuration.sslCertPath)) {
+                throw new Error(`SSL certificate file not found: ${configuration.sslCertPath}`);
+            }
+            const httpsOptions = {
+                key: fs.readFileSync(configuration.sslKeyPath),
+                cert: fs.readFileSync(configuration.sslCertPath)
+            };
+            // Add CA certificate if provided
+            if (configuration.sslCaPath && fs.existsSync(configuration.sslCaPath)) {
+                httpsOptions.ca = fs.readFileSync(configuration.sslCaPath);
+            }
+            const httpsServer = https.createServer(httpsOptions, app);
+            httpsServer.listen(HTTPS_PORT, '127.0.0.1', () => {
+                logger.info('ClickUp MCP Server (HTTPS) started', {
+                    port: HTTPS_PORT,
+                    protocol: 'https',
+                    endpoints: {
+                        streamableHttp: `https://127.0.0.1:${HTTPS_PORT}/mcp`,
+                        legacySSE: `https://127.0.0.1:${HTTPS_PORT}/sse`,
+                        health: `https://127.0.0.1:${HTTPS_PORT}/health`
+                    },
+                    security: {
+                        featuresEnabled: configuration.enableSecurityFeatures,
+                        originValidation: configuration.enableOriginValidation,
+                        rateLimit: configuration.enableRateLimit,
+                        cors: configuration.enableCors,
+                        httpsEnabled: true
+                    }
+                });
+                console.log(`🔒 ClickUp MCP Server (HTTPS) started on https://127.0.0.1:${HTTPS_PORT}`);
+                console.log(`📡 Streamable HTTPS endpoint: https://127.0.0.1:${HTTPS_PORT}/mcp`);
+                console.log(`🔄 Legacy SSE HTTPS endpoint: https://127.0.0.1:${HTTPS_PORT}/sse`);
+                console.log(`❤️  Health check HTTPS: https://127.0.0.1:${HTTPS_PORT}/health`);
+            });
+            return httpsServer;
+        }
+        catch (error) {
+            logger.error('Failed to start HTTPS server', {
+                error: error.message,
+                sslKeyPath: configuration.sslKeyPath,
+                sslCertPath: configuration.sslCertPath
+            });
+            console.log(`❌ Failed to start HTTPS server: ${error.message}`);
+            return null;
+        }
+    }
+    // Start servers based on configuration
+    const servers = [];
+    // Always start HTTP server (for backwards compatibility)
+    servers.push(startHttpServer());
+    // Start HTTPS server if enabled
+    if (configuration.enableHttps) {
+        const httpsServer = startHttpsServer();
+        if (httpsServer) {
+            servers.push(httpsServer);
+        }
+    }
+    // Security status logging
+    if (configuration.enableSecurityFeatures) {
+        console.log(`🔒 Security features enabled`);
+    }
+    else {
+        console.log(`⚠️  Security features disabled (set ENABLE_SECURITY_FEATURES=true to enable)`);
+    }
+    if (!configuration.enableHttps) {
+        console.log(`⚠️  HTTPS disabled (set ENABLE_HTTPS=true with SSL certificates to enable)`);
+    }
+    return servers;
 }

package/build/tools/task/bulk-operations.js

@@ -206,9 +206,9 @@ export const updateBulkTasksTool = {
                             description: "New status"
                         },
                         priority: {
-                            type: "number",
+                            type: "string",
                             nullable: true,
-                            enum: [1, 2, 3, 4, null],
+                            enum: ["1", "2", "3", "4", null],
                             description: "New priority (1-4 or null)"
                         },
                         dueDate: {

package/build/tools/task/handlers.js

@@ -138,9 +138,10 @@ async function buildUpdateData(params) {
         updateData.markdown_description = params.markdown_description;
     if (params.status !== undefined)
         updateData.status = params.status;
-    // Skip toTaskPriority conversion since we're handling priority in the main handler
-    if (params.priority !== undefined)
-        updateData.priority = params.priority;
+    // Use toTaskPriority to properly handle null values and validation
+    if (params.priority !== undefined) {
+        updateData.priority = toTaskPriority(params.priority);
+    }
     if (params.dueDate !== undefined) {
         updateData.due_date = parseDueDate(params.dueDate);
         updateData.due_date_time = true;

package/build/tools/task/single-operations.js

@@ -171,9 +171,9 @@ export const updateTaskTool = {
                 description: "New status. Must be valid for the task's current list."
             },
             priority: {
-                type: "number",
+                type: "string",
                 nullable: true,
-                enum: [1, 2, 3, 4, null],
+                enum: ["1", "2", "3", "4", null],
                 description: "New priority: 1 (urgent) to 4 (low). Set null to clear priority."
             },
             dueDate: {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@taazkareem/clickup-mcp-server",
-  "version": "0.8.3",
+  "version": "0.8.4",
   "description": "ClickUp MCP Server - Integrate ClickUp tasks with AI through Model Context Protocol",
   "type": "module",
   "main": "build/index.js",