@geanatz/cortex-mcp 5.0.1

package/dist/utils/logger.d.ts

@@ -0,0 +1,77 @@
+/**
+ * Logger utility with levels and formatting
+ * Provides consistent logging throughout the application
+ */
+/**
+ * Log levels
+ */
+export declare enum LogLevel {
+    DEBUG = 0,
+    INFO = 1,
+    WARN = 2,
+    ERROR = 3,
+    SILENT = 4
+}
+/**
+ * Logger configuration
+ */
+export interface LoggerConfig {
+    level: LogLevel;
+    prefix?: string;
+    timestamps?: boolean;
+    colors?: boolean;
+}
+/**
+ * Simple structured logger
+ */
+export declare class Logger {
+    private level;
+    private prefix;
+    private timestamps;
+    private colors;
+    constructor(config?: Partial<LoggerConfig>);
+    /**
+     * Set log level
+     */
+    setLevel(level: LogLevel): void;
+    /**
+     * Format a log message
+     */
+    private format;
+    /**
+     * Log at DEBUG level
+     */
+    debug(message: string, data?: Record<string, unknown>): void;
+    /**
+     * Log at INFO level
+     */
+    info(message: string, data?: Record<string, unknown>): void;
+    /**
+     * Log at WARN level
+     */
+    warn(message: string, data?: Record<string, unknown>): void;
+    /**
+     * Log at ERROR level
+     */
+    error(message: string, error?: Error | unknown, data?: Record<string, unknown>): void;
+    /**
+     * Create a child logger with a prefix
+     */
+    child(prefix: string): Logger;
+    /**
+     * Log operation timing
+     */
+    time<T>(label: string, fn: () => T): T;
+    /**
+     * Log async operation timing
+     */
+    timeAsync<T>(label: string, fn: () => Promise<T>): Promise<T>;
+}
+/**
+ * Default application logger
+ */
+export declare const logger: Logger;
+/**
+ * Create a logger for a specific module
+ */
+export declare function createLogger(module: string): Logger;

package/dist/utils/logger.js

@@ -0,0 +1,173 @@
+/**
+ * Logger utility with levels and formatting
+ * Provides consistent logging throughout the application
+ */
+/**
+ * Log levels
+ */
+export var LogLevel;
+(function (LogLevel) {
+    LogLevel[LogLevel["DEBUG"] = 0] = "DEBUG";
+    LogLevel[LogLevel["INFO"] = 1] = "INFO";
+    LogLevel[LogLevel["WARN"] = 2] = "WARN";
+    LogLevel[LogLevel["ERROR"] = 3] = "ERROR";
+    LogLevel[LogLevel["SILENT"] = 4] = "SILENT";
+})(LogLevel || (LogLevel = {}));
+/**
+ * ANSI color codes for terminal output
+ */
+const Colors = {
+    reset: '\x1b[0m',
+    dim: '\x1b[2m',
+    red: '\x1b[31m',
+    green: '\x1b[32m',
+    yellow: '\x1b[33m',
+    blue: '\x1b[34m',
+    magenta: '\x1b[35m',
+    cyan: '\x1b[36m',
+};
+/**
+ * Log level configurations
+ */
+const LevelConfig = {
+    [LogLevel.DEBUG]: { label: 'DEBUG', color: Colors.dim },
+    [LogLevel.INFO]: { label: 'INFO', color: Colors.blue },
+    [LogLevel.WARN]: { label: 'WARN', color: Colors.yellow },
+    [LogLevel.ERROR]: { label: 'ERROR', color: Colors.red },
+};
+/**
+ * Simple structured logger
+ */
+export class Logger {
+    level;
+    prefix;
+    timestamps;
+    colors;
+    constructor(config = {}) {
+        this.level = config.level ?? LogLevel.INFO;
+        this.prefix = config.prefix ?? '';
+        this.timestamps = config.timestamps ?? true;
+        this.colors = config.colors ?? true;
+    }
+    /**
+     * Set log level
+     */
+    setLevel(level) {
+        this.level = level;
+    }
+    /**
+     * Format a log message
+     */
+    format(level, message, data) {
+        const parts = [];
+        const config = LevelConfig[level];
+        if (this.timestamps) {
+            const time = new Date().toISOString().slice(11, 19);
+            parts.push(this.colors ? `${Colors.dim}[${time}]${Colors.reset}` : `[${time}]`);
+        }
+        if (config) {
+            const label = this.colors
+                ? `${config.color}[${config.label}]${Colors.reset}`
+                : `[${config.label}]`;
+            parts.push(label);
+        }
+        if (this.prefix) {
+            parts.push(this.colors ? `${Colors.cyan}${this.prefix}${Colors.reset}` : this.prefix);
+        }
+        parts.push(message);
+        if (data && Object.keys(data).length > 0) {
+            parts.push(JSON.stringify(data));
+        }
+        return parts.join(' ');
+    }
+    /**
+     * Log at DEBUG level
+     */
+    debug(message, data) {
+        if (this.level <= LogLevel.DEBUG) {
+            console.error(this.format(LogLevel.DEBUG, message, data));
+        }
+    }
+    /**
+     * Log at INFO level
+     */
+    info(message, data) {
+        if (this.level <= LogLevel.INFO) {
+            console.error(this.format(LogLevel.INFO, message, data));
+        }
+    }
+    /**
+     * Log at WARN level
+     */
+    warn(message, data) {
+        if (this.level <= LogLevel.WARN) {
+            console.error(this.format(LogLevel.WARN, message, data));
+        }
+    }
+    /**
+     * Log at ERROR level
+     */
+    error(message, error, data) {
+        if (this.level <= LogLevel.ERROR) {
+            const errorData = error instanceof Error
+                ? { error: error.message, stack: error.stack, ...data }
+                : { error, ...data };
+            console.error(this.format(LogLevel.ERROR, message, errorData));
+        }
+    }
+    /**
+     * Create a child logger with a prefix
+     */
+    child(prefix) {
+        return new Logger({
+            level: this.level,
+            prefix: this.prefix ? `${this.prefix}:${prefix}` : prefix,
+            timestamps: this.timestamps,
+            colors: this.colors,
+        });
+    }
+    /**
+     * Log operation timing
+     */
+    time(label, fn) {
+        const start = performance.now();
+        try {
+            const result = fn();
+            const duration = performance.now() - start;
+            this.debug(`${label} completed`, { duration: `${duration.toFixed(2)}ms` });
+            return result;
+        }
+        catch (error) {
+            const duration = performance.now() - start;
+            this.error(`${label} failed`, error, { duration: `${duration.toFixed(2)}ms` });
+            throw error;
+        }
+    }
+    /**
+     * Log async operation timing
+     */
+    async timeAsync(label, fn) {
+        const start = performance.now();
+        try {
+            const result = await fn();
+            const duration = performance.now() - start;
+            this.debug(`${label} completed`, { duration: `${duration.toFixed(2)}ms` });
+            return result;
+        }
+        catch (error) {
+            const duration = performance.now() - start;
+            this.error(`${label} failed`, error, { duration: `${duration.toFixed(2)}ms` });
+            throw error;
+        }
+    }
+}
+/**
+ * Default application logger
+ */
+export const logger = new Logger({ prefix: 'cortex' });
+/**
+ * Create a logger for a specific module
+ */
+export function createLogger(module) {
+    return logger.child(module);
+}

package/dist/utils/response-builder.d.ts

@@ -0,0 +1,4 @@
+import { McpToolResponse } from '../types/common.js';
+export declare function successResponse(text: string): McpToolResponse;
+export declare function errorResponse(text: string): McpToolResponse;
+export declare function createErrorResponse(error: unknown): McpToolResponse;

package/dist/utils/response-builder.js

@@ -0,0 +1,19 @@
+import { getErrorMessage } from '../errors/errors.js';
+function textContent(text) {
+    return { type: 'text', text };
+}
+export function successResponse(text) {
+    return {
+        content: [textContent(text)],
+    };
+}
+export function errorResponse(text) {
+    return {
+        content: [textContent(`Error: ${text}`)],
+        isError: true,
+    };
+}
+export function createErrorResponse(error) {
+    const message = getErrorMessage(error);
+    return errorResponse(message);
+}

package/dist/utils/storage-config.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Configuration for storage directory resolution
+ */
+export interface StorageConfig {
+    /** Whether to use global user directory instead of project-specific directories */
+    useGlobalDirectory: boolean;
+}
+/**
+ * Parse command-line arguments to determine storage configuration
+ */
+export declare function parseCommandLineArgs(): StorageConfig;
+/**
+ * Get the global storage directory path
+ * - Windows: C:\Users\{username}\.cortex\
+ * - macOS/Linux: ~/.cortex/
+ */
+export declare function getGlobalStorageDirectory(): string;
+/**
+ * Resolve the actual working directory based on configuration
+ *
+ * @param providedPath - The working directory path provided by the user
+ * @param config - Storage configuration including global directory flag
+ * @returns The actual working directory to use for storage
+ */
+export declare function resolveWorkingDirectory(providedPath: string, config: StorageConfig): string;
+/**
+ * Get parameter description for workingDirectory
+ */
+export declare function getWorkingDirectoryDescription(config: StorageConfig): string;

package/dist/utils/storage-config.js

@@ -0,0 +1,51 @@
+import { homedir } from 'os';
+import { join } from 'path';
+/**
+ * Parse command-line arguments to determine storage configuration
+ */
+export function parseCommandLineArgs() {
+    try {
+        const args = process.argv.slice(2);
+        const useGlobalDirectory = args.includes('--claude');
+        return {
+            useGlobalDirectory
+        };
+    }
+    catch (error) {
+        // Default to project-specific mode if there's any issue parsing args
+        return {
+            useGlobalDirectory: false
+        };
+    }
+}
+/**
+ * Get the global storage directory path
+ * - Windows: C:\Users\{username}\.cortex\
+ * - macOS/Linux: ~/.cortex/
+ */
+export function getGlobalStorageDirectory() {
+    const userHome = homedir();
+    return join(userHome, '.cortex');
+}
+/**
+ * Resolve the actual working directory based on configuration
+ *
+ * @param providedPath - The working directory path provided by the user
+ * @param config - Storage configuration including global directory flag
+ * @returns The actual working directory to use for storage
+ */
+export function resolveWorkingDirectory(providedPath, config) {
+    if (config.useGlobalDirectory) {
+        return getGlobalStorageDirectory();
+    }
+    return providedPath;
+}
+/**
+ * Get parameter description for workingDirectory
+ */
+export function getWorkingDirectoryDescription(config) {
+    const baseDescription = 'The full absolute path to the working directory where data is stored. MUST be an absolute path, never relative.';
+    return config.useGlobalDirectory
+        ? baseDescription + ' NOTE: Server started with --claude flag, so this parameter is ignored.'
+        : baseDescription;
+}

package/dist/utils/string-utils.d.ts

@@ -0,0 +1,2 @@
+export declare function sanitizeFileName(input: string, maxLength?: number): string;
+export declare function padNumber(num: number, length: number): string;

package/dist/utils/string-utils.js

@@ -0,0 +1,16 @@
+export function sanitizeFileName(input, maxLength = 50) {
+    let sanitized = input
+        .toLowerCase()
+        .replace(/[/\\:*?"<>|]/g, '-')
+        .replace(/\s+/g, '-')
+        .replace(/-{2,}/g, '-')
+        .replace(/^-+|-+$/g, '');
+    if (sanitized.length > maxLength) {
+        sanitized = sanitized.substring(0, maxLength);
+        sanitized = sanitized.replace(/-+$/, '');
+    }
+    return sanitized || 'file';
+}
+export function padNumber(num, length) {
+    return String(num).padStart(length, '0');
+}

package/dist/utils/validation.d.ts

@@ -0,0 +1,9 @@
+export declare const ValidationLimits: {
+    readonly TASK_DETAILS_MAX_LENGTH: 2000;
+    readonly TASK_DETAILS_MIN_LENGTH: 1;
+    readonly TAG_MAX_LENGTH: 50;
+    readonly TAG_MIN_LENGTH: 1;
+    readonly MAX_TAGS: 20;
+    readonly MAX_DEPENDENCIES: 50;
+    readonly TASK_ID_MAX_LENGTH: 100;
+};

package/dist/utils/validation.js

@@ -0,0 +1,9 @@
+export const ValidationLimits = {
+    TASK_DETAILS_MAX_LENGTH: 2000,
+    TASK_DETAILS_MIN_LENGTH: 1,
+    TAG_MAX_LENGTH: 50,
+    TAG_MIN_LENGTH: 1,
+    MAX_TAGS: 20,
+    MAX_DEPENDENCIES: 50,
+    TASK_ID_MAX_LENGTH: 100,
+};

package/dist/utils/version.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Read the version from package.json
+ * Works in both development (src/) and compiled (dist/) versions
+ */
+export declare function getVersion(): string;
+/**
+ * Get formatted version string for display
+ */
+export declare function getVersionString(): string;

package/dist/utils/version.js

@@ -0,0 +1,41 @@
+import { readFileSync } from 'fs';
+import { fileURLToPath } from 'url';
+import { dirname, join } from 'path';
+/**
+ * Read the version from package.json
+ * Works in both development (src/) and compiled (dist/) versions
+ */
+export function getVersion() {
+    try {
+        const currentDir = dirname(fileURLToPath(import.meta.url));
+        // Try multiple paths to find package.json
+        const pathsToTry = [
+            join(currentDir, '..', '..', 'package.json'), // dist/utils/version.js -> ../../package.json
+            join(currentDir, '..', '..', '..', 'package.json'), // src/utils/version.ts -> ../../../package.json
+            join(process.cwd(), 'package.json'), // fallback to cwd
+        ];
+        for (const packageJsonPath of pathsToTry) {
+            try {
+                const packageJson = JSON.parse(readFileSync(packageJsonPath, 'utf-8'));
+                if (packageJson.version) {
+                    return packageJson.version;
+                }
+            }
+            catch {
+                // Try next path
+                continue;
+            }
+        }
+        return '5.0.0'; // Fallback version — keep in sync with package.json
+    }
+    catch {
+        return '5.0.0'; // Fallback version — keep in sync with package.json
+    }
+}
+/**
+ * Get formatted version string for display
+ */
+export function getVersionString() {
+    const version = getVersion();
+    return `v${version}`;
+}

package/package.json

@@ -0,0 +1,60 @@
+{
+  "name": "@geanatz/cortex-mcp",
+  "version": "5.0.1",
+  "description": "An MCP server for task-based orchestration workflows with phase artifacts for agentic development",
+  "main": "dist/index.js",
+  "type": "module",
+  "bin": {
+    "cortex-mcp": "dist/index.js"
+  },
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch",
+    "start": "node dist/index.js",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "task-management",
+    "orchestration",
+    "agentic-workflow",
+    "file-storage",
+    "productivity",
+    "ai-tools",
+    "opencode"
+  ],
+  "author": "Geanatz",
+  "license": "MIT",
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.12.0",
+    "zod": "^3.23.8"
+  },
+  "devDependencies": {
+    "@types/node": "^20.0.0",
+    "typescript": "^5.0.0"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/geanatz/cortex-mcp.git"
+  },
+  "files": [
+    "dist/**/*",
+    "!dist/.tsbuildinfo",
+    "README.md",
+    "LICENSE"
+  ],
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}