@alanse/clickup-multi-mcp-server 1.0.0

package/build/config.js

@@ -0,0 +1,237 @@
+/**
+ * SPDX-FileCopyrightText: © 2025 Talib Kareem <taazkareem@icloud.com>
+ * SPDX-License-Identifier: MIT
+ *
+ * Configuration handling for ClickUp API credentials and application settings
+ *
+ * Multiple workspace support:
+ * - CLICKUP_WORKSPACES: JSON string with workspace configurations (takes precedence)
+ * - CLICKUP_API_KEY and CLICKUP_TEAM_ID: Legacy single workspace mode (backwards compatible)
+ *
+ * The document support is optional and can be passed via command line arguments.
+ * The default value is 'false' (string), which means document support will be disabled if
+ * no parameter is passed. Pass it as 'true' (string) to enable it.
+ *
+ * Tool filtering options:
+ * - ENABLED_TOOLS: Comma-separated list of tools to enable (takes precedence over DISABLED_TOOLS)
+ * - DISABLED_TOOLS: Comma-separated list of tools to disable (ignored if ENABLED_TOOLS is specified)
+ *
+ * Server transport options:
+ * - ENABLE_SSE: Enable Server-Sent Events transport (default: false)
+ * - SSE_PORT: Port for SSE server (default: 3000)
+ * - ENABLE_STDIO: Enable STDIO transport (default: true)
+ */
+// Parse any command line environment arguments
+const args = process.argv.slice(2);
+const envArgs = {};
+for (let i = 0; i < args.length; i++) {
+    if (args[i] === '--env' && i + 1 < args.length) {
+        const [key, value] = args[i + 1].split('=');
+        if (key === 'CLICKUP_API_KEY')
+            envArgs.clickupApiKey = value;
+        if (key === 'CLICKUP_TEAM_ID')
+            envArgs.clickupTeamId = value;
+        if (key === 'CLICKUP_WORKSPACES')
+            envArgs.clickupWorkspaces = value;
+        if (key === 'DOCUMENT_SUPPORT')
+            envArgs.documentSupport = value;
+        if (key === 'LOG_LEVEL')
+            envArgs.logLevel = value;
+        if (key === 'DISABLED_TOOLS')
+            envArgs.disabledTools = value;
+        if (key === 'ENABLED_TOOLS')
+            envArgs.enabledTools = value;
+        if (key === 'ENABLE_SSE')
+            envArgs.enableSSE = value;
+        if (key === 'SSE_PORT')
+            envArgs.ssePort = value;
+        if (key === 'ENABLE_STDIO')
+            envArgs.enableStdio = value;
+        if (key === 'PORT')
+            envArgs.port = value;
+        i++;
+    }
+}
+// Log levels enum
+export var LogLevel;
+(function (LogLevel) {
+    LogLevel[LogLevel["TRACE"] = 0] = "TRACE";
+    LogLevel[LogLevel["DEBUG"] = 1] = "DEBUG";
+    LogLevel[LogLevel["INFO"] = 2] = "INFO";
+    LogLevel[LogLevel["WARN"] = 3] = "WARN";
+    LogLevel[LogLevel["ERROR"] = 4] = "ERROR";
+})(LogLevel || (LogLevel = {}));
+// Parse LOG_LEVEL string to LogLevel enum
+const parseLogLevel = (levelStr) => {
+    if (!levelStr)
+        return LogLevel.ERROR; // Default to ERROR if not specified
+    switch (levelStr.toUpperCase()) {
+        case 'TRACE': return LogLevel.TRACE;
+        case 'DEBUG': return LogLevel.DEBUG;
+        case 'INFO': return LogLevel.INFO;
+        case 'WARN': return LogLevel.WARN;
+        case 'ERROR': return LogLevel.ERROR;
+        default:
+            // Don't use console.error as it interferes with JSON-RPC communication
+            return LogLevel.ERROR;
+    }
+};
+// Parse boolean string
+const parseBoolean = (value, defaultValue) => {
+    if (value === undefined)
+        return defaultValue;
+    return value.toLowerCase() === 'true';
+};
+// Parse integer string
+const parseInteger = (value, defaultValue) => {
+    if (value === undefined)
+        return 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 !== '');
+};
+// Parse workspace configuration
+const parseWorkspaces = () => {
+    const workspacesJson = envArgs.clickupWorkspaces || process.env.CLICKUP_WORKSPACES;
+    if (workspacesJson) {
+        try {
+            const parsed = JSON.parse(workspacesJson);
+            // Validate the structure
+            if (!parsed.default || !parsed.workspaces || typeof parsed.workspaces !== 'object') {
+                throw new Error('Invalid CLICKUP_WORKSPACES format: must have "default" and "workspaces" properties');
+            }
+            // Validate each workspace has required fields
+            for (const [key, workspace] of Object.entries(parsed.workspaces)) {
+                const ws = workspace;
+                if (!ws.token || !ws.teamId) {
+                    throw new Error(`Invalid workspace "${key}": must have "token" and "teamId" properties`);
+                }
+            }
+            return parsed;
+        }
+        catch (error) {
+            throw new Error(`Failed to parse CLICKUP_WORKSPACES: ${error.message}`);
+        }
+    }
+    return undefined;
+};
+// Load configuration from command line args or environment variables
+const configuration = {
+    clickupApiKey: envArgs.clickupApiKey || process.env.CLICKUP_API_KEY || '',
+    clickupTeamId: envArgs.clickupTeamId || process.env.CLICKUP_TEAM_ID || '',
+    clickupWorkspaces: parseWorkspaces(),
+    enableSponsorMessage: process.env.ENABLE_SPONSOR_MESSAGE !== 'false',
+    documentSupport: envArgs.documentSupport || process.env.DOCUMENT_SUPPORT || process.env.DOCUMENT_MODULE || process.env.DOCUMENT_MODEL || 'false',
+    logLevel: parseLogLevel(envArgs.logLevel || process.env.LOG_LEVEL),
+    disabledTools: ((envArgs.disabledTools || process.env.DISABLED_TOOLS || process.env.DISABLED_COMMANDS)?.split(',').map(cmd => cmd.trim()).filter(cmd => cmd !== '') || []),
+    enabledTools: ((envArgs.enabledTools || process.env.ENABLED_TOOLS)?.split(',').map(cmd => cmd.trim()).filter(cmd => cmd !== '') || []),
+    enableSSE: parseBoolean(envArgs.enableSSE || process.env.ENABLE_SSE, false),
+    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 configuration
+// If CLICKUP_WORKSPACES is provided, use it (multi-workspace mode)
+// Otherwise, require CLICKUP_API_KEY and CLICKUP_TEAM_ID (single workspace mode)
+if (configuration.clickupWorkspaces) {
+    // Multi-workspace mode - validate workspace configuration
+    const defaultWorkspace = configuration.clickupWorkspaces.default;
+    if (!configuration.clickupWorkspaces.workspaces[defaultWorkspace]) {
+        throw new Error(`Default workspace "${defaultWorkspace}" not found in workspaces configuration`);
+    }
+}
+else {
+    // Single workspace mode (backwards compatible) - validate legacy variables
+    const requiredVars = ['clickupApiKey', 'clickupTeamId'];
+    const missingEnvVars = requiredVars
+        .filter(key => !configuration[key])
+        .map(key => key);
+    if (missingEnvVars.length > 0) {
+        throw new Error(`Missing required environment variables: ${missingEnvVars.join(', ')}. ` +
+            `Either provide CLICKUP_API_KEY and CLICKUP_TEAM_ID, or CLICKUP_WORKSPACES for multi-workspace support.`);
+    }
+}
+/**
+ * Get workspace configuration by workspace identifier
+ * @param workspaceId - Workspace identifier (optional, uses default if not specified)
+ * @returns Workspace configuration with token and teamId
+ */
+export function getWorkspaceConfig(workspaceId) {
+    if (configuration.clickupWorkspaces) {
+        // Multi-workspace mode
+        const wsId = workspaceId || configuration.clickupWorkspaces.default;
+        const workspace = configuration.clickupWorkspaces.workspaces[wsId];
+        if (!workspace) {
+            const available = Object.keys(configuration.clickupWorkspaces.workspaces).join(', ');
+            throw new Error(`Workspace "${wsId}" not found. Available workspaces: ${available}`);
+        }
+        return workspace;
+    }
+    else {
+        // Single workspace mode (backwards compatible)
+        if (workspaceId && workspaceId !== 'default') {
+            throw new Error(`Multiple workspaces not configured. Only default workspace is available. ` +
+                `Set CLICKUP_WORKSPACES environment variable to enable multi-workspace support.`);
+        }
+        return {
+            token: configuration.clickupApiKey,
+            teamId: configuration.clickupTeamId,
+            description: 'Default workspace'
+        };
+    }
+}
+/**
+ * Get list of available workspace identifiers
+ * @returns Array of workspace identifiers
+ */
+export function getAvailableWorkspaces() {
+    if (configuration.clickupWorkspaces) {
+        return Object.keys(configuration.clickupWorkspaces.workspaces);
+    }
+    else {
+        return ['default'];
+    }
+}
+/**
+ * Get the default workspace identifier
+ * @returns Default workspace identifier
+ */
+export function getDefaultWorkspace() {
+    if (configuration.clickupWorkspaces) {
+        return configuration.clickupWorkspaces.default;
+    }
+    else {
+        return 'default';
+    }
+}
+export default configuration;

package/build/index.js

@@ -0,0 +1,87 @@
+#!/usr/bin/env node
+/**
+ * SPDX-FileCopyrightText: © 2025 Talib Kareem <taazkareem@icloud.com>
+ * SPDX-License-Identifier: MIT
+ *
+ * ClickUp MCP Server
+ *
+ * This custom server implements the Model Context Protocol (MCP) specification to enable
+ * AI applications to interact with ClickUp workspaces. It provides a standardized
+ * interface for managing tasks, lists, folders and other ClickUp entities using Natural Language.
+ *
+ * Key Features:
+ * - Complete task management (CRUD operations, moving, duplicating)
+ * - Workspace organization (spaces, folders, lists)
+ * - Bulk operations with concurrent processing
+ * - Natural language date parsing
+ * - File attachments support
+ * - Name-based entity resolution
+ * - Markdown formatting
+ * - Built-in rate limiting
+ * - Multiple transport options (STDIO, SSE, HTTP Streamable)
+ *
+ * For full documentation and usage examples, please refer to the README.md file.
+ */
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { configureServer, server } from './server.js';
+import { info, error } from './logger.js';
+import config from './config.js';
+import { dirname } from 'path';
+import { fileURLToPath } from 'url';
+import { startSSEServer } from './sse_server.js';
+// Get directory name for module paths
+const __dirname = dirname(fileURLToPath(import.meta.url));
+// Handle uncaught exceptions
+process.on('uncaughtException', (err) => {
+    error("Uncaught Exception", { message: err.message, stack: err.stack });
+    process.exit(1);
+});
+// Handle unhandled promise rejections
+process.on('unhandledRejection', (reason, promise) => {
+    error("Unhandled Rejection", { reason });
+    process.exit(1);
+});
+async function startStdioServer() {
+    info('Starting ClickUp MCP Server...');
+    // Log essential information about the environment
+    info('Server environment', {
+        pid: process.pid,
+        node: process.version,
+        os: process.platform,
+        arch: process.arch,
+    });
+    // Configure the server with all handlers
+    info('Configuring server request handlers');
+    await configureServer();
+    // Connect using stdio transport
+    info('Connecting to MCP stdio transport');
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    info('Server startup complete - ready to handle requests');
+}
+/**
+ * Application entry point that configures and starts the MCP server.
+ */
+async function main() {
+    try {
+        if (config.enableSSE) {
+            // Start the new SSE server with HTTP Streamable support
+            startSSEServer();
+        }
+        else {
+            // Start the traditional STDIO server
+            await startStdioServer();
+        }
+    }
+    catch (err) {
+        error('Error during server startup', {
+            message: err.message,
+            stack: err.stack,
+        });
+        process.exit(1);
+    }
+}
+main().catch((err) => {
+    error("Unhandled server error", { message: err.message, stack: err.stack });
+    process.exit(1);
+});

package/build/logger.js

@@ -0,0 +1,163 @@
+/**
+ * SPDX-FileCopyrightText: © 2025 Talib Kareem <taazkareem@icloud.com>
+ * SPDX-License-Identifier: MIT
+ *
+ * Logger module for MCP Server
+ *
+ * This module provides logging functionality for the server,
+ * writing logs to only the log file to avoid interfering with JSON-RPC.
+ */
+import { createWriteStream } from 'fs';
+import { join, dirname } from 'path';
+import { fileURLToPath } from 'url';
+import config, { LogLevel } from './config.js';
+// Get the directory name of the current module
+const __dirname = dirname(fileURLToPath(import.meta.url));
+// Current process ID for logging
+const pid = process.pid;
+// Create a write stream for logging - use a fixed filename in the build directory
+const logFileName = 'server.log';
+const logStream = createWriteStream(join(__dirname, logFileName), { flags: 'w' });
+// Write init message to log file only
+logStream.write(`Logging initialized to ${join(__dirname, logFileName)}\n`);
+// Use the configured log level from config.ts
+const configuredLevel = config.logLevel;
+// Re-export LogLevel enum
+export { LogLevel };
+/**
+ * Check if a log level is enabled based on the configured level
+ * @param level The log level to check
+ * @returns True if the level should be logged
+ */
+function isLevelEnabled(level) {
+    return level >= configuredLevel;
+}
+/**
+ * Log function that writes only to file to avoid interfering with JSON-RPC
+ * @param level Log level (trace, debug, info, warn, error)
+ * @param message Message to log
+ * @param data Optional data to include in log
+ */
+function log(level, message, data) {
+    const levelEnum = level === 'trace' ? LogLevel.TRACE
+        : level === 'debug' ? LogLevel.DEBUG
+            : level === 'info' ? LogLevel.INFO
+                : level === 'warn' ? LogLevel.WARN
+                    : LogLevel.ERROR;
+    // Skip if level is below configured level
+    if (!isLevelEnabled(levelEnum)) {
+        return;
+    }
+    const timestamp = new Date().toISOString();
+    // Format the log message differently based on the level and data
+    let logMessage = `[${timestamp}] [PID:${pid}] ${level.toUpperCase()}: ${message}`;
+    // Format data differently based on content and log level
+    if (data) {
+        // For debugging and trace levels, try to make the data more readable
+        if (level === 'debug' || level === 'trace') {
+            // If data is a simple object with few properties, format it inline
+            if (typeof data === 'object' && data !== null && !Array.isArray(data) &&
+                Object.keys(data).length <= 4 && Object.keys(data).every(k => typeof data[k] !== 'object' || data[k] === null)) {
+                const dataStr = Object.entries(data)
+                    .map(([k, v]) => `${k}=${v === undefined ? 'undefined' :
+                    (v === null ? 'null' :
+                        (typeof v === 'string' ? `"${v}"` : v))}`)
+                    .join(' ');
+                logMessage += ` (${dataStr})`;
+            }
+            else {
+                // For more complex data, keep the JSON format but on new lines
+                logMessage += '\n' + JSON.stringify(data, null, 2);
+            }
+        }
+        else {
+            // For other levels, keep the original JSON format
+            logMessage += '\n' + JSON.stringify(data, null, 2);
+        }
+    }
+    // Write to file only, not to stderr which would interfere with JSON-RPC
+    logStream.write(logMessage + '\n');
+}
+/**
+ * Shorthand for info level logs
+ * @param message Message to log
+ * @param data Optional data to include in log
+ */
+export function info(message, data) {
+    log('info', message, data);
+}
+/**
+ * Shorthand for error level logs
+ * @param message Message to log
+ * @param data Optional data to include in log
+ */
+export function error(message, data) {
+    log('error', message, data);
+}
+/**
+ * Logger class for creating context-specific loggers
+ */
+export class Logger {
+    /**
+     * Create a new logger with context
+     * @param context The context to prepend to log messages
+     */
+    constructor(context) {
+        this.context = context;
+    }
+    /**
+     * Check if a log level is enabled for this logger
+     * @param level The level to check
+     * @returns True if logging at this level is enabled
+     */
+    isLevelEnabled(level) {
+        return isLevelEnabled(level);
+    }
+    /**
+     * Log at trace level
+     * @param message Message to log
+     * @param data Optional data to include in log
+     */
+    trace(message, data) {
+        log('trace', `[${this.context}] ${message}`, data);
+    }
+    /**
+     * Log at debug level
+     * @param message Message to log
+     * @param data Optional data to include in log
+     */
+    debug(message, data) {
+        log('debug', `[${this.context}] ${message}`, data);
+    }
+    /**
+     * Log at info level
+     * @param message Message to log
+     * @param data Optional data to include in log
+     */
+    info(message, data) {
+        log('info', `[${this.context}] ${message}`, data);
+    }
+    /**
+     * Log at warn level
+     * @param message Message to log
+     * @param data Optional data to include in log
+     */
+    warn(message, data) {
+        log('warn', `[${this.context}] ${message}`, data);
+    }
+    /**
+     * Log at error level
+     * @param message Message to log
+     * @param data Optional data to include in log
+     */
+    error(message, data) {
+        log('error', `[${this.context}] ${message}`, data);
+    }
+}
+// Handle SIGTERM for clean shutdown
+process.on('SIGTERM', () => {
+    log('info', 'Received SIGTERM signal, shutting down...');
+    logStream.end(() => {
+        process.exit(0);
+    });
+});