@geanatz/cortex-mcp 5.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Geanatz
+
+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

@@ -0,0 +1,281 @@
+# Cortex MCP - Task-Based Orchestration for AI Workflows
+
+An MCP (Model Context Protocol) server for managing task-based workflows with artifact support across five orchestration phases: Explore, Search, Plan, Build, and Test.
+
+## Features
+
+- **Simplified Task Management** - Parent tasks with inline subtasks, no separate folders
+- **Phase-Aware Artifacts** - Store and manage artifacts for each orchestration phase (explore, search, plan, build, test)
+- **File-Based Storage** - All data stored in `.cortex/` directory with no database required
+- **In-Memory Caching** - High-performance caching layer with TTL for frequently accessed tasks
+- **Structured Logging** - Comprehensive logging with configurable levels
+
+## Installation
+
+### Using npx (Recommended)
+
+Run the latest version without installing:
+
+```bash
+npx -y @geanatz/cortex-mcp@latest
+```
+
+### Global Installation
+
+```bash
+npm install -g @geanatz/cortex-mcp
+```
+
+### Local Installation
+
+```bash
+npm install @geanatz/cortex-mcp
+```
+
+## Usage
+
+### Starting the Server
+
+```bash
+# Project-specific mode (stores in .cortex/ )
+cortex-mcp
+
+# Global mode (stores in ~/.cortex/)
+cortex-mcp --claude
+```
+
+### MCP Configuration
+
+Add to your MCP settings (e.g., Claude Desktop, Cursor, etc.):
+
+```json
+{
+  "cortex": {
+    "type": "local",
+    "enabled": true,
+    "command": [
+      "npx",
+      "-y",
+      "@geanatz/cortex-mcp@latest"
+    ]
+  }
+}
+```
+
+Or for global mode:
+
+```json
+{
+  "cortex": {
+    "type": "local",
+    "enabled": true,
+    "command": [
+      "npx",
+      "-y",
+      "@geanatz/cortex-mcp@latest",
+      "--claude"
+    ]
+  }
+}
+```
+
+### Creating Tasks
+
+```
+Tool: create_task
+Parameters:
+  - workingDirectory: path where tasks are stored
+  - details: task description (generates task ID)
+  - status (optional): pending | in_progress | done
+  - tags (optional): categorization tags
+```
+
+### Managing Subtasks
+
+Subtasks are created using `update_task` with the `addSubtask` parameter:
+
+```
+Tool: update_task
+Parameters:
+  - id: parent task ID
+  - addSubtask: { details: "Subtask description", status: "pending" }
+  - updateSubtask: { id: "1", status: "done" }
+  - removeSubtaskId: "1"
+```
+
+### Managing Artifacts
+
+Each task can have artifacts for 5 phases:
+- **explore**: Codebase analysis and discovery findings
+- **search**: External research and documentation findings
+- **plan**: Implementation approach and step-by-step plan
+- **build**: Implementation changes and modifications made
+- **test**: Test execution results and verification status
+
+```
+Tools: create_{phase}, update_{phase}, delete_{phase}
+Parameters:
+  - workingDirectory: project directory
+  - taskId: which task to attach artifact to
+  - content: markdown content
+  - status: pending | in-progress | completed | failed | skipped
+  - retries, error: optional metadata
+```
+
+## Storage Format
+
+Tasks are stored in `.cortex/tasks/{number}-{slug}/` directories:
+
+```
+.cortex/
+└── tasks/
+    ├── 001-implement-auth/
+    │   ├── .task.json          (parent task + subtasks array)
+    │   ├── explore.md         (explore phase artifact)
+    │   ├── search.md          (search phase artifact)
+    │   ├── plan.md            (plan phase artifact)
+    │   ├── build.md           (build phase artifact)
+    │   └── test.md            (test phase artifact)
+    └── 002-setup-database/
+        ├── .task.json
+        └── ... (optional artifacts)
+```
+
+### Task JSON Structure
+
+```json
+{
+  "id": "001-implement-auth",
+  "details": "Implement authentication system",
+  "status": "in_progress",
+  "tags": ["auth", "backend"],
+  "createdAt": "2024-01-01T00:00:00Z",
+  "updatedAt": "2024-01-01T00:00:00Z",
+  "actualHours": 2.5,
+  "subtasks": [
+    { "id": "1", "details": "Setup JWT library", "status": "done" },
+    { "id": "2", "details": "Create login endpoint", "status": "in_progress" },
+    { "id": "3", "details": "Add middleware", "status": "pending" }
+  ]
+}
+```
+
+## Data Model
+
+### Task (Parent)
+```typescript
+interface Task {
+  id: string;                    // Task ID (e.g., "001-implement-auth")
+  details: string;               // Full task description
+  status: 'pending' | 'in_progress' | 'done';
+  createdAt: string;             // ISO 8601 timestamp
+  updatedAt: string;             // Last modification timestamp
+  tags?: string[];               // Categorization tags
+  actualHours?: number;          // Time tracking
+  subtasks: Subtask[];           // Array of subtasks
+}
+```
+
+### Subtask
+```typescript
+interface Subtask {
+  id: string;                    // Simple ID ("1", "2", etc.)
+  details: string;               // Subtask description
+  status: 'pending' | 'in_progress' | 'done';
+}
+```
+
+### Artifact
+```typescript
+interface Artifact {
+  metadata: {
+    phase: 'explore' | 'search' | 'plan' | 'build' | 'test';
+    status: 'pending' | 'in-progress' | 'completed' | 'failed' | 'skipped';
+    createdAt: string;            // ISO 8601
+    updatedAt: string;            // ISO 8601
+    retries?: number;             // Attempt count
+    error?: string;               // Error message if status=failed
+  }
+  content: string;               // Markdown content
+}
+```
+
+## Available Tools
+
+### Task Management
+- `create_task` - Create a new parent task
+- `list_tasks` - List all tasks with subtasks
+- `get_task` - Get task details including subtasks and artifacts
+- `update_task` - Update task and manage subtasks
+- `delete_task` - Delete task and all its subtasks
+
+### Artifact Management
+- `create_explore` - Create explore phase artifact
+- `update_explore` - Update explore phase artifact
+- `delete_explore` - Delete explore phase artifact
+- `create_search` - Create search phase artifact
+- `update_search` - Update search phase artifact
+- `delete_search` - Delete search phase artifact
+- `create_plan` - Create plan phase artifact
+- `update_plan` - Update plan phase artifact
+- `delete_plan` - Delete plan phase artifact
+- `create_build` - Create build phase artifact
+- `update_build` - Update build phase artifact
+- `delete_build` - Delete build phase artifact
+- `create_test` - Create test phase artifact
+- `update_test` - Update test phase artifact
+- `delete_test` - Delete test phase artifact
+
+## Configuration
+
+### Environment Variables
+- `DEBUG=true` - Enable debug logging
+
+### Command-Line Flags
+- `--claude` - Use global directory mode (~/.cortex/)
+
+## Development
+
+```bash
+# Build TypeScript
+npm run build
+
+# Watch mode
+npm run dev
+
+# Start server
+npm start
+```
+
+### Build Optimization
+- Uses TypeScript with incremental builds
+- Optimized for <5s build times with ~800MB memory usage
+- Proper closure elimination for fast type inference
+
+## Architecture
+
+- **Clean layering** - Types → Utilities → Storage → Tools → Server
+- **No circular dependencies** - Easy to understand data flow
+- **Abstract storage** - File-based implementation, easily extensible
+- **MCP-compliant** - Full compliance with Model Context Protocol specification
+
+## Version
+
+Current version: **5.0.0**
+
+- v5.0.0: Simplified model - subtasks stored inline, removed dependencies, removed move_task
+- v4.0.0: Complete refactor with artifact support and optimized build
+- v3.x: Legacy memory features (deprecated)
+- v1.x: Initial implementation
+
+## License
+
+MIT - See LICENSE file for details
+
+## Author
+
+Geanatz
+
+## Contributing
+
+Contributions welcome!

package/dist/errors/errors.d.ts

@@ -0,0 +1,109 @@
+/**
+ * Custom error classes for the application
+ * Provides typed, hierarchical error handling
+ */
+/**
+ * Base application error class
+ * All custom errors should extend this
+ */
+export declare abstract class AppError extends Error {
+    readonly code: string;
+    readonly timestamp: Date;
+    readonly context?: Record<string, unknown>;
+    constructor(message: string, code: string, context?: Record<string, unknown>);
+    /**
+     * Convert error to JSON-serializable object
+     */
+    toJSON(): Record<string, unknown>;
+}
+/**
+ * Error codes enum for type-safe error handling
+ */
+export declare const ErrorCodes: {
+    readonly VALIDATION_ERROR: "VALIDATION_ERROR";
+    readonly INVALID_INPUT: "INVALID_INPUT";
+    readonly REQUIRED_FIELD_MISSING: "REQUIRED_FIELD_MISSING";
+    readonly INVALID_FORMAT: "INVALID_FORMAT";
+    readonly NOT_FOUND: "NOT_FOUND";
+    readonly TASK_NOT_FOUND: "TASK_NOT_FOUND";
+    readonly ARTIFACT_NOT_FOUND: "ARTIFACT_NOT_FOUND";
+    readonly PARENT_NOT_FOUND: "PARENT_NOT_FOUND";
+    readonly DEPENDENCY_NOT_FOUND: "DEPENDENCY_NOT_FOUND";
+    readonly ALREADY_EXISTS: "ALREADY_EXISTS";
+    readonly CIRCULAR_REFERENCE: "CIRCULAR_REFERENCE";
+    readonly SELF_REFERENCE: "SELF_REFERENCE";
+    readonly STORAGE_ERROR: "STORAGE_ERROR";
+    readonly FILE_READ_ERROR: "FILE_READ_ERROR";
+    readonly FILE_WRITE_ERROR: "FILE_WRITE_ERROR";
+    readonly DIRECTORY_ERROR: "DIRECTORY_ERROR";
+    readonly PARSE_ERROR: "PARSE_ERROR";
+    readonly INITIALIZATION_ERROR: "INITIALIZATION_ERROR";
+    readonly CONFIGURATION_ERROR: "CONFIGURATION_ERROR";
+    readonly UNKNOWN_ERROR: "UNKNOWN_ERROR";
+};
+export type ErrorCode = typeof ErrorCodes[keyof typeof ErrorCodes];
+/**
+ * Validation error for input validation failures
+ */
+export declare class ValidationError extends AppError {
+    readonly field?: string;
+    readonly value?: unknown;
+    constructor(message: string, field?: string, value?: unknown, context?: Record<string, unknown>);
+    static requiredField(field: string): ValidationError;
+    static invalidFormat(field: string, expected: string, received?: unknown): ValidationError;
+    static maxLength(field: string, max: number, actual: number): ValidationError;
+    static minLength(field: string, min: number, actual: number): ValidationError;
+    static emptyString(field: string): ValidationError;
+}
+/**
+ * Not found error for missing resources
+ */
+export declare class NotFoundError extends AppError {
+    readonly resourceType: string;
+    readonly resourceId: string;
+    constructor(resourceType: string, resourceId: string, context?: Record<string, unknown>);
+    static task(taskId: string): NotFoundError;
+    static artifact(taskId: string, phase: string): NotFoundError;
+    static parent(parentId: string): NotFoundError;
+    static dependency(depId: string): NotFoundError;
+}
+/**
+ * Conflict error for operations that would create invalid states
+ */
+export declare class ConflictError extends AppError {
+    constructor(message: string, code?: ErrorCode, context?: Record<string, unknown>);
+    static circularReference(taskId: string, targetId: string): ConflictError;
+    static selfReference(taskId: string, operation: string): ConflictError;
+}
+/**
+ * Storage error for file system operations
+ */
+export declare class StorageError extends AppError {
+    readonly path?: string;
+    readonly operation?: string;
+    constructor(message: string, code?: ErrorCode, path?: string, operation?: string, context?: Record<string, unknown>);
+    static readError(path: string, originalError?: Error): StorageError;
+    static writeError(path: string, originalError?: Error): StorageError;
+    static directoryError(path: string, originalError?: Error): StorageError;
+    static parseError(path: string, format: string, originalError?: Error): StorageError;
+    static initializationError(path: string, message: string): StorageError;
+}
+/**
+ * Type guard to check if an error is an AppError
+ */
+export declare function isAppError(error: unknown): error is AppError;
+/**
+ * Type guard for specific error types
+ */
+export declare function isValidationError(error: unknown): error is ValidationError;
+export declare function isNotFoundError(error: unknown): error is NotFoundError;
+export declare function isConflictError(error: unknown): error is ConflictError;
+export declare function isStorageError(error: unknown): error is StorageError;
+/**
+ * Extract error message from unknown error
+ */
+export declare function getErrorMessage(error: unknown): string;
+/**
+ * Wrap unknown errors in AppError
+ */
+export declare function wrapError(error: unknown, fallbackMessage?: string): AppError;

package/dist/errors/errors.js

@@ -0,0 +1,199 @@
+/**
+ * Custom error classes for the application
+ * Provides typed, hierarchical error handling
+ */
+/**
+ * Base application error class
+ * All custom errors should extend this
+ */
+export class AppError extends Error {
+    code;
+    timestamp;
+    context;
+    constructor(message, code, context) {
+        super(message);
+        this.name = this.constructor.name;
+        this.code = code;
+        this.timestamp = new Date();
+        this.context = context;
+        // Maintains proper stack trace for where error was thrown
+        Error.captureStackTrace?.(this, this.constructor);
+    }
+    /**
+     * Convert error to JSON-serializable object
+     */
+    toJSON() {
+        return {
+            name: this.name,
+            message: this.message,
+            code: this.code,
+            timestamp: this.timestamp.toISOString(),
+            context: this.context,
+        };
+    }
+}
+/**
+ * Error codes enum for type-safe error handling
+ */
+export const ErrorCodes = {
+    // Validation errors (4xx equivalent)
+    VALIDATION_ERROR: 'VALIDATION_ERROR',
+    INVALID_INPUT: 'INVALID_INPUT',
+    REQUIRED_FIELD_MISSING: 'REQUIRED_FIELD_MISSING',
+    INVALID_FORMAT: 'INVALID_FORMAT',
+    // Resource errors
+    NOT_FOUND: 'NOT_FOUND',
+    TASK_NOT_FOUND: 'TASK_NOT_FOUND',
+    ARTIFACT_NOT_FOUND: 'ARTIFACT_NOT_FOUND',
+    PARENT_NOT_FOUND: 'PARENT_NOT_FOUND',
+    DEPENDENCY_NOT_FOUND: 'DEPENDENCY_NOT_FOUND',
+    // Conflict errors
+    ALREADY_EXISTS: 'ALREADY_EXISTS',
+    CIRCULAR_REFERENCE: 'CIRCULAR_REFERENCE',
+    SELF_REFERENCE: 'SELF_REFERENCE',
+    // Storage errors
+    STORAGE_ERROR: 'STORAGE_ERROR',
+    FILE_READ_ERROR: 'FILE_READ_ERROR',
+    FILE_WRITE_ERROR: 'FILE_WRITE_ERROR',
+    DIRECTORY_ERROR: 'DIRECTORY_ERROR',
+    PARSE_ERROR: 'PARSE_ERROR',
+    // System errors
+    INITIALIZATION_ERROR: 'INITIALIZATION_ERROR',
+    CONFIGURATION_ERROR: 'CONFIGURATION_ERROR',
+    UNKNOWN_ERROR: 'UNKNOWN_ERROR',
+};
+/**
+ * Validation error for input validation failures
+ */
+export class ValidationError extends AppError {
+    field;
+    value;
+    constructor(message, field, value, context) {
+        super(message, ErrorCodes.VALIDATION_ERROR, { ...context, field, value });
+        this.field = field;
+        this.value = value;
+    }
+    static requiredField(field) {
+        return new ValidationError(`${field} is required.`, field, undefined, { code: ErrorCodes.REQUIRED_FIELD_MISSING });
+    }
+    static invalidFormat(field, expected, received) {
+        return new ValidationError(`Invalid format for ${field}. Expected ${expected}.`, field, received, { code: ErrorCodes.INVALID_FORMAT, expected });
+    }
+    static maxLength(field, max, actual) {
+        return new ValidationError(`${field} must be ${max} characters or less (got ${actual}).`, field, undefined, { code: ErrorCodes.INVALID_INPUT, max, actual });
+    }
+    static minLength(field, min, actual) {
+        return new ValidationError(`${field} must be at least ${min} characters (got ${actual}).`, field, undefined, { code: ErrorCodes.INVALID_INPUT, min, actual });
+    }
+    static emptyString(field) {
+        return new ValidationError(`${field} must not be empty.`, field, '', { code: ErrorCodes.INVALID_INPUT });
+    }
+}
+/**
+ * Not found error for missing resources
+ */
+export class NotFoundError extends AppError {
+    resourceType;
+    resourceId;
+    constructor(resourceType, resourceId, context) {
+        super(`${resourceType} with ID "${resourceId}" not found.`, ErrorCodes.NOT_FOUND, { ...context, resourceType, resourceId });
+        this.resourceType = resourceType;
+        this.resourceId = resourceId;
+    }
+    static task(taskId) {
+        return new NotFoundError('Task', taskId, { code: ErrorCodes.TASK_NOT_FOUND });
+    }
+    static artifact(taskId, phase) {
+        return new NotFoundError(`${phase} artifact`, taskId, { code: ErrorCodes.ARTIFACT_NOT_FOUND, phase });
+    }
+    static parent(parentId) {
+        return new NotFoundError('Parent task', parentId, { code: ErrorCodes.PARENT_NOT_FOUND });
+    }
+    static dependency(depId) {
+        return new NotFoundError('Dependency task', depId, { code: ErrorCodes.DEPENDENCY_NOT_FOUND });
+    }
+}
+/**
+ * Conflict error for operations that would create invalid states
+ */
+export class ConflictError extends AppError {
+    constructor(message, code = ErrorCodes.CIRCULAR_REFERENCE, context) {
+        super(message, code, context);
+    }
+    static circularReference(taskId, targetId) {
+        return new ConflictError(`Moving task would create a circular reference.`, ErrorCodes.CIRCULAR_REFERENCE, { taskId, targetId });
+    }
+    static selfReference(taskId, operation) {
+        return new ConflictError(`Task cannot ${operation} itself.`, ErrorCodes.SELF_REFERENCE, { taskId, operation });
+    }
+}
+/**
+ * Storage error for file system operations
+ */
+export class StorageError extends AppError {
+    path;
+    operation;
+    constructor(message, code = ErrorCodes.STORAGE_ERROR, path, operation, context) {
+        super(message, code, { ...context, path, operation });
+        this.path = path;
+        this.operation = operation;
+    }
+    static readError(path, originalError) {
+        return new StorageError(`Failed to read file: ${path}`, ErrorCodes.FILE_READ_ERROR, path, 'read', { originalError: originalError?.message });
+    }
+    static writeError(path, originalError) {
+        return new StorageError(`Failed to write file: ${path}`, ErrorCodes.FILE_WRITE_ERROR, path, 'write', { originalError: originalError?.message });
+    }
+    static directoryError(path, originalError) {
+        return new StorageError(`Directory operation failed: ${path}`, ErrorCodes.DIRECTORY_ERROR, path, 'directory', { originalError: originalError?.message });
+    }
+    static parseError(path, format, originalError) {
+        return new StorageError(`Failed to parse ${format} file: ${path}`, ErrorCodes.PARSE_ERROR, path, 'parse', { format, originalError: originalError?.message });
+    }
+    static initializationError(path, message) {
+        return new StorageError(message, ErrorCodes.INITIALIZATION_ERROR, path, 'initialize');
+    }
+}
+/**
+ * Type guard to check if an error is an AppError
+ */
+export function isAppError(error) {
+    return error instanceof AppError;
+}
+/**
+ * Type guard for specific error types
+ */
+export function isValidationError(error) {
+    return error instanceof ValidationError;
+}
+export function isNotFoundError(error) {
+    return error instanceof NotFoundError;
+}
+export function isConflictError(error) {
+    return error instanceof ConflictError;
+}
+export function isStorageError(error) {
+    return error instanceof StorageError;
+}
+/**
+ * Extract error message from unknown error
+ */
+export function getErrorMessage(error) {
+    if (error instanceof Error) {
+        return error.message;
+    }
+    if (typeof error === 'string') {
+        return error;
+    }
+    return 'An unknown error occurred';
+}
+/**
+ * Wrap unknown errors in AppError
+ */
+export function wrapError(error, fallbackMessage) {
+    if (isAppError(error)) {
+        return error;
+    }
+    const message = getErrorMessage(error) || fallbackMessage || 'Unknown error';
+    return new StorageError(message, ErrorCodes.UNKNOWN_ERROR);
+}

package/dist/errors/index.d.ts

@@ -0,0 +1,4 @@
+/**
+ * Central error exports
+ */
+export * from './errors.js';

package/dist/errors/index.js

@@ -0,0 +1,4 @@
+/**
+ * Central error exports
+ */
+export * from './errors.js';