fix: shebang issues

Closes #241 #211 #184 #193

.changeset/brave-seas-pull.md

@@ -0,0 +1,6 @@
+---
+'task-master-ai': patch
+---
+
+- Fixes shebang issue not allowing task-master to run on certain windows operating systems
+- Resolves #241 #211 #184 #193

.changeset/chubby-moose-stay.md

@@ -0,0 +1,5 @@
+---
+'task-master-ai': patch
+---
+
+Updates the parameter descriptions for update, update-task and update-subtask to ensure the MCP server correctly reaches for the right update command based on what is being updated -- all tasks, one task, or a subtask.

.changeset/slick-women-relate.md

@@ -1,5 +0,0 @@
----
-"task-master-ai": patch
----
-
-Add license to repo

.changeset/two-bats-smoke.md

@@ -1,126 +0,0 @@
----
-"task-master-ai": patch
----
-
-- Adjusts the MCP server invokation in the mcp.json we ship with `task-master init`. Fully functional now.
-- Rename the npx -y command. It's now `npx -y task-master-ai task-master-mcp`
-- Rename MCP tools to better align with API conventions and natural language in client chat:
-  - Rename `list-tasks` to `get-tasks` for more intuitive client requests like "get my tasks"
-  - Rename `show-task` to `get-task` for consistency with GET-based API naming conventions
-
-- **Optimize MCP response payloads:**
-  - Add custom `processTaskResponse` function to `get-task` MCP tool to filter out unnecessary `allTasks` array data
-  - Significantly reduce response size by returning only the specific requested task instead of all tasks
-  - Preserve dependency status relationships for the UI/CLI while keeping MCP responses lean and efficient
-
-- **Implement complete remove-task functionality:**
-  - Add `removeTask` core function to permanently delete tasks or subtasks from tasks.json
-  - Implement CLI command `remove-task` with confirmation prompt and force flag support
-  - Create MCP `remove_task` tool for AI-assisted task removal
-  - Automatically handle dependency cleanup by removing references to deleted tasks
-  - Update task files after removal to maintain consistency
-  - Provide robust error handling and detailed feedback messages
-
-- **Update Cursor rules and documentation:**
-  - Enhance `new_features.mdc` with comprehensive guidelines for implementing removal commands
-  - Update `commands.mdc` with best practices for confirmation flows and cleanup procedures
-  - Expand `mcp.mdc` with detailed instructions for MCP tool implementation patterns
-  - Add examples of proper error handling and parameter validation to all relevant rules
-  - Include new sections about handling dependencies during task removal operations
-  - Document naming conventions and implementation patterns for destructive operations
-
-- **Implement silent mode across all direct functions:**
-  - Add `enableSilentMode` and `disableSilentMode` utility imports to all direct function files
-  - Wrap all core function calls with silent mode to prevent console logs from interfering with JSON responses
-  - Add comprehensive error handling to ensure silent mode is disabled even when errors occur
-  - Fix "Unexpected token 'I', "[INFO] Gene"... is not valid JSON" errors by suppressing log output
-  - Apply consistent silent mode pattern across all MCP direct functions
-  - Maintain clean JSON responses for better integration with client tools
-
-- **Implement AsyncOperationManager for background task processing:**
-  - Add new `async-manager.js` module to handle long-running operations asynchronously
-  - Support background execution of computationally intensive tasks like expansion and analysis
-  - Implement unique operation IDs with UUID generation for reliable tracking
-  - Add operation status tracking (pending, running, completed, failed)
-  - Create `get_operation_status` MCP tool to check on background task progress
-  - Forward progress reporting from background tasks to the client
-  - Implement operation history with automatic cleanup of completed operations
-  - Support proper error handling in background tasks with detailed status reporting
-  - Maintain context (log, session) for background operations ensuring consistent behavior
-
-- **Implement initialize_project command:**
-  - Add new MCP tool to allow project setup via integrated MCP clients
-  - Create `initialize_project` direct function with proper parameter handling
-  - Improve onboarding experience by adding to mcp.json configuration
-  - Support project-specific metadata like name, description, and version
-  - Handle shell alias creation with proper confirmation
-  - Improve first-time user experience in AI environments
-
-- **Refactor project root handling for MCP Server:**
-  - **Prioritize Session Roots**: MCP tools now extract the project root path directly from `session.roots[0].uri` provided by the client (e.g., Cursor).
-  - **New Utility `getProjectRootFromSession`**: Added to `mcp-server/src/tools/utils.js` to encapsulate session root extraction and decoding. **Further refined for more reliable detection, especially in integrated environments, including deriving root from script path and avoiding fallback to '/'.**
-  - **Simplify `findTasksJsonPath`**: The core path finding utility in `mcp-server/src/core/utils/path-utils.js` now prioritizes the `projectRoot` passed in `args` (originating from the session). Removed checks for `TASK_MASTER_PROJECT_ROOT` env var (we do not use this anymore) and package directory fallback. **Enhanced error handling to include detailed debug information (paths searched, CWD, server dir, etc.) and clearer potential solutions when `tasks.json` is not found.**
-  - **Retain CLI Fallbacks**: Kept `lastFoundProjectRoot` cache check and CWD search in `findTasksJsonPath` for compatibility with direct CLI usage.
-
-- Updated all MCP tools to use the new project root handling:
-  - Tools now call `getProjectRootFromSession` to determine the root.
-  - This root is passed explicitly as `projectRoot` in the `args` object to the corresponding `*Direct` function.
-  - Direct functions continue to use the (now simplified) `findTasksJsonPath` to locate `tasks.json` within the provided root.
-  - This ensures tools work reliably in integrated environments without requiring the user to specify `--project-root`.
-
-- Add comprehensive PROJECT_MARKERS array for detecting common project files (used in CLI fallback logic).
-- Improved error messages with specific troubleshooting guidance.
-- **Enhanced logging:**
-    - Indicate the source of project root selection more clearly.
-    - **Add verbose logging in `get-task.js` to trace session object content and resolved project root path, aiding debugging.**
-
-- DRY refactoring by centralizing path utilities in `core/utils/path-utils.js` and session handling in `tools/utils.js`.
-- Keep caching of `lastFoundProjectRoot` for CLI performance.
-
-- Split monolithic task-master-core.js into separate function files within direct-functions directory.
-- Implement update-task MCP command for updating a single task by ID.
-- Implement update-subtask MCP command for appending information to specific subtasks.
-- Implement generate MCP command for creating individual task files from tasks.json.
-- Implement set-status MCP command for updating task status.
-- Implement get-task MCP command for displaying detailed task information (renamed from show-task).
-- Implement next-task MCP command for finding the next task to work on.
-- Implement expand-task MCP command for breaking down tasks into subtasks.
-- Implement add-task MCP command for creating new tasks using AI assistance.
-- Implement add-subtask MCP command for adding subtasks to existing tasks.
-- Implement remove-subtask MCP command for removing subtasks from parent tasks.
-- Implement expand-all MCP command for expanding all tasks into subtasks.
-- Implement analyze-complexity MCP command for analyzing task complexity.
-- Implement clear-subtasks MCP command for clearing subtasks from parent tasks.
-- Implement remove-dependency MCP command for removing dependencies from tasks.
-- Implement validate-dependencies MCP command for checking validity of task dependencies.
-- Implement fix-dependencies MCP command for automatically fixing invalid dependencies.
-- Implement complexity-report MCP command for displaying task complexity analysis reports.
-- Implement add-dependency MCP command for creating dependency relationships between tasks.
-- Implement get-tasks MCP command for listing all tasks (renamed from list-tasks).
-- Implement `initialize_project` MCP tool to allow project setup via MCP client and radically improve and simplify onboarding by adding to mcp.json (e.g., Cursor).
-
-- Enhance documentation and tool descriptions:
-  - Create new `taskmaster.mdc` Cursor rule for comprehensive MCP tool and CLI command reference.
-  - Bundle taskmaster.mdc with npm package and include in project initialization.
-  - Add detailed descriptions for each tool's purpose, parameters, and common use cases.
-  - Include natural language patterns and keywords for better intent recognition.
-  - Document parameter descriptions with clear examples and default values.
-  - Add usage examples and context for each command/tool.
-  - **Update documentation (`mcp.mdc`, `utilities.mdc`, `architecture.mdc`, `new_features.mdc`, `commands.mdc`) to reflect the new session-based project root handling and the preferred MCP vs. CLI interaction model.**
-  - Improve clarity around project root auto-detection in tool documentation.
-  - Update tool descriptions to better reflect their actual behavior and capabilities.
-  - Add cross-references between related tools and commands.
-  - Include troubleshooting guidance in tool descriptions.
-  - **Add default values for `DEFAULT_SUBTASKS` and `DEFAULT_PRIORITY` to the example `.cursor/mcp.json` configuration.**
-
-- Document MCP server naming conventions in architecture.mdc and mcp.mdc files (file names use kebab-case, direct functions use camelCase with Direct suffix, tool registration functions use camelCase with Tool suffix, and MCP tool names use snake_case).
-- Update MCP tool naming to follow more intuitive conventions that better align with natural language requests in client chat applications.
-- Enhance task show view with a color-coded progress bar for visualizing subtask completion percentage.
-- Add "cancelled" status to UI module status configurations for marking tasks as cancelled without deletion.
-- Improve MCP server resource documentation with comprehensive implementation examples and best practices.
-- Enhance progress bars with status breakdown visualization showing proportional sections for different task statuses.
-- Add improved status tracking for both tasks and subtasks with detailed counts by status.
-- Optimize progress bar display with width constraints to prevent UI overflow on smaller terminals.
-- Improve status counts display with clear text labels beside status icons for better readability.
-- Treat deferred and cancelled tasks as effectively complete for progress calculation while maintaining visual distinction.
-- **Fix `reportProgress` calls** to use the correct `{ progress, total? }` format.

.cursor/mcp.json

@@ -1,20 +1,18 @@
 {
-    "mcpServers": {
+	"mcpServers": {
-        "taskmaster-ai": {
+		"taskmaster-ai": {
-            "command": "node",
+			"command": "node",
-            "args": [
+			"args": ["./mcp-server/server.js"],
-                "./mcp-server/server.js"
+			"env": {
-            ],
+				"ANTHROPIC_API_KEY": "YOUR_ANTHROPIC_API_KEY_HERE",
-            "env": {
+				"PERPLEXITY_API_KEY": "YOUR_PERPLEXITY_API_KEY_HERE",
-                "ANTHROPIC_API_KEY": "YOUR_ANTHROPIC_API_KEY_HERE",
+				"MODEL": "claude-3-7-sonnet-20250219",
-                "PERPLEXITY_API_KEY": "YOUR_PERPLEXITY_API_KEY_HERE",
+				"PERPLEXITY_MODEL": "sonar-pro",
-                "MODEL": "claude-3-7-sonnet-20250219",
+				"MAX_TOKENS": 64000,
-                "PERPLEXITY_MODEL": "sonar-pro",
+				"TEMPERATURE": 0.2,
-                "MAX_TOKENS": 64000,
+				"DEFAULT_SUBTASKS": 5,
-                "TEMPERATURE": 0.4,
+				"DEFAULT_PRIORITY": "medium"
-                "DEFAULT_SUBTASKS": 5,
+			}
-                "DEFAULT_PRIORITY": "medium"
+		}
-            }
+	}
-        }
-    }
 }

.cursor/rules/architecture.mdc

@@ -14,13 +14,13 @@ alwaysApply: false
     - **Purpose**: Defines and registers all CLI commands using Commander.js.
     - **Responsibilities** (See also: [`commands.mdc`](mdc:.cursor/rules/commands.mdc)):
       - Parses command-line arguments and options.
-      - Invokes appropriate functions from other modules to execute commands.
+      - Invokes appropriate functions from other modules to execute commands (e.g., calls `initializeProject` from `init.js` for the `init` command).
       - Handles user input and output related to command execution.
       - Implements input validation and error handling for CLI commands.
     - **Key Components**:
       - `programInstance` (Commander.js `Command` instance): Manages command definitions.
       - `registerCommands(programInstance)`: Function to register all application commands.
-      - Command action handlers: Functions executed when a specific command is invoked.
+      - Command action handlers: Functions executed when a specific command is invoked, delegating to core modules.
 
   - **[`task-manager.js`](mdc:scripts/modules/task-manager.js): Task Data Management**
     - **Purpose**: Manages task data, including loading, saving, creating, updating, deleting, and querying tasks.
@@ -148,14 +148,134 @@ alwaysApply: false
         - Robust error handling for background tasks
       - **Usage**: Used for CPU-intensive operations like task expansion and PRD parsing
 
+  - **[`init.js`](mdc:scripts/init.js): Project Initialization Logic**
+    - **Purpose**: Contains the core logic for setting up a new Task Master project structure.
+    - **Responsibilities**:
+      - Creates necessary directories (`.cursor/rules`, `scripts`, `tasks`).
+      - Copies template files (`.env.example`, `.gitignore`, rule files, `dev.js`, etc.).
+      - Creates or merges `package.json` with required dependencies and scripts.
+      - Sets up MCP configuration (`.cursor/mcp.json`).
+      - Optionally initializes a git repository and installs dependencies.
+      - Handles user prompts for project details *if* called without skip flags (`-y`).
+    - **Key Function**:
+      - `initializeProject(options)`: The main function exported and called by the `init` command's action handler in [`commands.js`](mdc:scripts/modules/commands.js). It receives parsed options directly.
+    - **Note**: This script is used as a module and no longer handles its own argument parsing or direct execution via a separate `bin` file.
+
 - **Data Flow and Module Dependencies**:
 
-  - **Commands Initiate Actions**: User commands entered via the CLI (handled by [`commands.js`](mdc:scripts/modules/commands.js)) are the entry points for most operations.
+  - **Commands Initiate Actions**: User commands entered via the CLI (parsed by `commander` based on definitions in [`commands.js`](mdc:scripts/modules/commands.js)) are the entry points for most operations.
-  - **Command Handlers Delegate to Managers**: Command handlers in [`commands.js`](mdc:scripts/modules/commands.js) call functions in [`task-manager.js`](mdc:scripts/modules/task-manager.js) and [`dependency-manager.js`](mdc:scripts/modules/dependency-manager.js) to perform core task and dependency management logic.
+  - **Command Handlers Delegate to Core Logic**: Action handlers within [`commands.js`](mdc:scripts/modules/commands.js) call functions in core modules like [`task-manager.js`](mdc:scripts/modules/task-manager.js), [`dependency-manager.js`](mdc:scripts/modules/dependency-manager.js), and [`init.js`](mdc:scripts/init.js) (for the `init` command) to perform the actual work.
   - **UI for Presentation**:  [`ui.js`](mdc:scripts/modules/ui.js) is used by command handlers and task/dependency managers to display information to the user. UI functions primarily consume data and format it for output, without modifying core application state.
   - **Utilities for Common Tasks**: [`utils.js`](mdc:scripts/modules/utils.js) provides helper functions used by all other modules for configuration, logging, file operations, and common data manipulations.
   - **AI Services Integration**: AI functionalities (complexity analysis, task expansion, PRD parsing) are invoked from [`task-manager.js`](mdc:scripts/modules/task-manager.js) and potentially [`commands.js`](mdc:scripts/modules/commands.js), likely using functions that would reside in a dedicated `ai-services.js` module or be integrated within `utils.js` or `task-manager.js`.
-  - **MCP Server Interaction**: External tools interact with the `mcp-server`. MCP Tool `execute` methods use `getProjectRootFromSession` to find the project root, then call direct function wrappers (in `mcp-server/src/core/direct-functions/`) passing the root in `args`. These wrappers handle path finding for `tasks.json` (using `path-utils.js`), validation, caching, call the core logic from `scripts/modules/`, and return a standardized result. The final MCP response is formatted by `mcp-server/src/tools/utils.js`. See [`mcp.mdc`](mdc:.cursor/rules/mcp.mdc) for details.
+  - **MCP Server Interaction**: External tools interact with the `mcp-server`. MCP Tool `execute` methods use `getProjectRootFromSession` to find the project root, then call direct function wrappers (in `mcp-server/src/core/direct-functions/`) passing the root in `args`. These wrappers handle path finding for `tasks.json` (using `path-utils.js`), validation, caching, call the core logic from `scripts/modules/` (passing logging context via the standard wrapper pattern detailed in mcp.mdc), and return a standardized result. The final MCP response is formatted by `mcp-server/src/tools/utils.js`. See [`mcp.mdc`](mdc:.cursor/rules/mcp.mdc) for details.
+
+## Silent Mode Implementation Pattern in MCP Direct Functions
+
+Direct functions (the `*Direct` functions in `mcp-server/src/core/direct-functions/`) need to carefully implement silent mode to prevent console logs from interfering with the structured JSON responses required by MCP. This involves both using `enableSilentMode`/`disableSilentMode` around core function calls AND passing the MCP logger via the standard wrapper pattern (see mcp.mdc). Here's the standard pattern for correct implementation:
+
+1. **Import Silent Mode Utilities**:
+   ```javascript
+   import { enableSilentMode, disableSilentMode, isSilentMode } from '../../../../scripts/modules/utils.js';
+   ```
+
+2. **Parameter Matching with Core Functions**:
+   - ✅ **DO**: Ensure direct function parameters match the core function parameters
+   - ✅ **DO**: Check the original core function signature before implementing
+   - ❌ **DON'T**: Add parameters to direct functions that don't exist in core functions
+   ```javascript
+   // Example: Core function signature
+   // async function expandTask(tasksPath, taskId, numSubtasks, useResearch, additionalContext, options)
+   
+   // Direct function implementation - extract only parameters that exist in core
+   export async function expandTaskDirect(args, log, context = {}) {
+     // Extract parameters that match the core function
+     const taskId = parseInt(args.id, 10);
+     const numSubtasks = args.num ? parseInt(args.num, 10) : undefined;
+     const useResearch = args.research === true;
+     const additionalContext = args.prompt || '';
+     
+     // Later pass these parameters in the correct order to the core function
+     const result = await expandTask(
+       tasksPath, 
+       taskId, 
+       numSubtasks, 
+       useResearch, 
+       additionalContext,
+       { mcpLog: log, session: context.session }
+     );
+   }
+   ```
+
+3. **Checking Silent Mode State**:
+   - ✅ **DO**: Always use `isSilentMode()` function to check current status
+   - ❌ **DON'T**: Directly access the global `silentMode` variable or `global.silentMode`
+   ```javascript
+   // CORRECT: Use the function to check current state
+   if (!isSilentMode()) {
+     // Only create a loading indicator if not in silent mode
+     loadingIndicator = startLoadingIndicator('Processing...');
+   }
+   
+   // INCORRECT: Don't access global variables directly
+   if (!silentMode) { // ❌ WRONG
+     loadingIndicator = startLoadingIndicator('Processing...');
+   }
+   ```
+
+4. **Wrapping Core Function Calls**:
+   - ✅ **DO**: Use a try/finally block pattern to ensure silent mode is always restored
+   - ✅ **DO**: Enable silent mode before calling core functions that produce console output
+   - ✅ **DO**: Disable silent mode in a finally block to ensure it runs even if errors occur
+   - ❌ **DON'T**: Enable silent mode without ensuring it gets disabled
+   ```javascript
+   export async function someDirectFunction(args, log) {
+     try {
+       // Argument preparation
+       const tasksPath = findTasksJsonPath(args, log);
+       const someArg = args.someArg;
+       
+       // Enable silent mode to prevent console logs
+       enableSilentMode();
+       
+       try {
+         // Call core function which might produce console output
+         const result = await someCoreFunction(tasksPath, someArg);
+         
+         // Return standardized result object
+         return { 
+           success: true, 
+           data: result, 
+           fromCache: false 
+         };
+       } finally {
+         // ALWAYS disable silent mode in finally block
+         disableSilentMode();
+       }
+     } catch (error) {
+       // Standard error handling
+       log.error(`Error in direct function: ${error.message}`);
+       return { 
+         success: false, 
+         error: { code: 'OPERATION_ERROR', message: error.message }, 
+         fromCache: false 
+       };
+     }
+   }
+   ```
+
+5. **Mixed Parameter and Global Silent Mode Handling**:
+   - For functions that need to handle both a passed `silentMode` parameter and check global state:
+   ```javascript
+   // Check both the function parameter and global state
+   const isSilent = options.silentMode || (typeof options.silentMode === 'undefined' && isSilentMode());
+   
+   if (!isSilent) {
+     console.log('Operation starting...');
+   }
+   ```
+
+By following these patterns consistently, direct functions will properly manage console output suppression while ensuring that silent mode is always properly reset, even when errors occur. This creates a more robust system that helps prevent unexpected silent mode states that could cause logging problems in subsequent operations.
 
 - **Testing Architecture**:
 
@@ -205,7 +325,7 @@ Follow these steps to add MCP support for an existing Task Master command (see [
 
 1.  **Ensure Core Logic Exists**: Verify the core functionality is implemented and exported from the relevant module in `scripts/modules/`.
 
-2.  **Create Direct Function File in `mcp-server/src/core/direct-functions/`**:
+2.  **Create Direct Function File in `mcp-server/src/core/direct-functions/`:**
     - Create a new file (e.g., `your-command.js`) using **kebab-case** naming.
     - Import necessary core functions, **`findTasksJsonPath` from `../utils/path-utils.js`**, and **silent mode utilities**.
     - Implement `async function yourCommandDirect(args, log)` using **camelCase** with `Direct` suffix:

.cursor/rules/commands.mdc

@@ -24,7 +24,7 @@ While this document details the implementation of Task Master's **CLI commands**
   programInstance
     .command('command-name')
     .description('Clear, concise description of what the command does')
-    .option('-s, --short-option <value>', 'Option description', 'default value')
+    .option('-o, --option <value>', 'Option description', 'default value')
     .option('--long-option <value>', 'Option description')
     .action(async (options) => {
       // Command implementation
@@ -34,7 +34,8 @@ While this document details the implementation of Task Master's **CLI commands**
 - **Command Handler Organization**:
   - ✅ DO: Keep action handlers concise and focused
   - ✅ DO: Extract core functionality to appropriate modules
-  - ✅ DO: Include validation for required parameters
+  - ✅ DO: Have the action handler import and call the relevant function(s) from core modules (e.g., `task-manager.js`, `init.js`), passing the parsed `options`.
+  - ✅ DO: Perform basic parameter validation (e.g., checking for required options) within the action handler or at the start of the called core function.
   - ❌ DON'T: Implement business logic in command handlers
 
 ## Best Practices for Removal/Delete Commands
@@ -152,8 +153,8 @@ When implementing commands that delete or remove data (like `remove-task` or `re
   ```javascript
   // ✅ DO: Suggest alternatives for destructive operations
   console.log(chalk.yellow('Note: If you just want to exclude this task from active work, consider:'));
-  console.log(chalk.cyan(`  task-master set-status --id=${taskId} --status=cancelled`));
+  console.log(chalk.cyan(`  task-master set-status --id='${taskId}' --status='cancelled'`));
-  console.log(chalk.cyan(`  task-master set-status --id=${taskId} --status=deferred`));
+  console.log(chalk.cyan(`  task-master set-status --id='${taskId}' --status='deferred'`));
   console.log('This preserves the task and its history for reference.');
   ```
 
@@ -253,7 +254,7 @@ When implementing commands that delete or remove data (like `remove-task` or `re
   const taskId = parseInt(options.id, 10);
   if (isNaN(taskId) || taskId <= 0) {
     console.error(chalk.red(`Error: Invalid task ID: ${options.id}. Task ID must be a positive integer.`));
-    console.log(chalk.yellow('Usage example: task-master update-task --id=23 --prompt="Update with new information"'));
+    console.log(chalk.yellow('Usage example: task-master update-task --id=\'23\' --prompt=\'Update with new information.\nEnsure proper error handling.\''));
     process.exit(1);
   }
   
@@ -299,8 +300,8 @@ When implementing commands that delete or remove data (like `remove-task` or `re
     (dependencies.length > 0 ? chalk.white(`Dependencies: ${dependencies.join(', ')}`) + '\n' : '') +
     '\n' +
     chalk.white.bold('Next Steps:') + '\n' +
-    chalk.cyan(`1. Run ${chalk.yellow(`task-master show ${parentId}`)} to see the parent task with all subtasks`) + '\n' +
+    chalk.cyan(`1. Run ${chalk.yellow(`task-master show '${parentId}'`)} to see the parent task with all subtasks`) + '\n' +
-    chalk.cyan(`2. Run ${chalk.yellow(`task-master set-status --id=${parentId}.${subtask.id} --status=in-progress`)} to start working on it`),
+    chalk.cyan(`2. Run ${chalk.yellow(`task-master set-status --id='${parentId}.${subtask.id}' --status='in-progress'`)} to start working on it`),
     { padding: 1, borderColor: 'green', borderStyle: 'round', margin: { top: 1 } }
   ));
   ```
@@ -375,7 +376,7 @@ When implementing commands that delete or remove data (like `remove-task` or `re
       '  --option1 <value>    Description of option1 (required)\n' +
       '  --option2 <value>    Description of option2\n\n' +
       chalk.cyan('Examples:') + '\n' +
-      '  task-master command --option1=value --option2=value',
+      '  task-master command --option1=\'value1\' --option2=\'value2\'',
       { padding: 1, borderColor: 'blue', borderStyle: 'round' }
     ));
   }
@@ -418,7 +419,7 @@ When implementing commands that delete or remove data (like `remove-task` or `re
     // Provide more helpful error messages for common issues
     if (error.message.includes('task') && error.message.includes('not found')) {
       console.log(chalk.yellow('\nTo fix this issue:'));
-      console.log('  1. Run task-master list to see all available task IDs');
+      console.log('  1. Run \'task-master list\' to see all available task IDs');
       console.log('  2. Use a valid task ID with the --id parameter');
     } else if (error.message.includes('API key')) {
       console.log(chalk.yellow('\nThis error is related to API keys. Check your environment variables.'));
@@ -562,3 +563,45 @@ When implementing commands that delete or remove data (like `remove-task` or `re
   ```
 
 Refer to [`commands.js`](mdc:scripts/modules/commands.js) for implementation examples and [`new_features.mdc`](mdc:.cursor/rules/new_features.mdc) for integration guidelines. 
+// Helper function to show add-subtask command help
+function showAddSubtaskHelp() {
+  console.log(boxen(
+    chalk.white.bold('Add Subtask Command Help') + '\n\n' +
+    chalk.cyan('Usage:') + '\n' +
+    `  task-master add-subtask --parent=<id> [options]\n\n` +
+    chalk.cyan('Options:') + '\n' +
+    '  -p, --parent <id>         Parent task ID (required)\n' +
+    '  -i, --task-id <id>        Existing task ID to convert to subtask\n' +
+    '  -t, --title <title>       Title for the new subtask\n' +
+    '  -d, --description <text>  Description for the new subtask\n' +
+    '  --details <text>          Implementation details for the new subtask\n' +
+    '  --dependencies <ids>      Comma-separated list of dependency IDs\n' +
+    '  -s, --status <status>     Status for the new subtask (default: "pending")\n' +
+    '  -f, --file <file>         Path to the tasks file (default: "tasks/tasks.json")\n' +
+    '  --skip-generate           Skip regenerating task files\n\n' +
+    chalk.cyan('Examples:') + '\n' +
+    '  task-master add-subtask --parent=\'5\' --task-id=\'8\'\n' +
+    '  task-master add-subtask -p \'5\' -t \'Implement login UI\' -d \'Create the login form\'\n' +
+    '  task-master add-subtask -p \'5\' -t \'Handle API Errors\' --details $\'Handle 401 Unauthorized.\nHandle 500 Server Error.\'',
+    { padding: 1, borderColor: 'blue', borderStyle: 'round' }
+  ));
+}
+
+// Helper function to show remove-subtask command help
+function showRemoveSubtaskHelp() {
+  console.log(boxen(
+    chalk.white.bold('Remove Subtask Command Help') + '\n\n' +
+    chalk.cyan('Usage:') + '\n' +
+    `  task-master remove-subtask --id=<parentId.subtaskId> [options]\n\n` +
+    chalk.cyan('Options:') + '\n' +
+    '  -i, --id <id>       Subtask ID(s) to remove in format "parentId.subtaskId" (can be comma-separated, required)\n' +
+    '  -c, --convert       Convert the subtask to a standalone task instead of deleting it\n' +
+    '  -f, --file <file>   Path to the tasks file (default: "tasks/tasks.json")\n' +
+    '  --skip-generate     Skip regenerating task files\n\n' +
+    chalk.cyan('Examples:') + '\n' +
+    '  task-master remove-subtask --id=\'5.2\'\n' +
+    '  task-master remove-subtask --id=\'5.2,6.3,7.1\'\n' +
+    '  task-master remove-subtask --id=\'5.2\' --convert',
+    { padding: 1, borderColor: 'blue', borderStyle: 'round' }
+  ));
+} 

.cursor/rules/dev_workflow.mdc

@@ -29,7 +29,7 @@ Task Master offers two primary ways to interact:
 
 ## Standard Development Workflow Process
 
--   Start new projects by running `init` tool / `task-master init` or `parse_prd` / `task-master parse-prd --input=<prd-file.txt>` (see [`taskmaster.mdc`](mdc:.cursor/rules/taskmaster.mdc)) to generate initial tasks.json
+-   Start new projects by running `init` tool / `task-master init` or `parse_prd` / `task-master parse-prd --input='<prd-file.txt>'` (see [`taskmaster.mdc`](mdc:.cursor/rules/taskmaster.mdc)) to generate initial tasks.json
 -   Begin coding sessions with `get_tasks` / `task-master list` (see [`taskmaster.mdc`](mdc:.cursor/rules/taskmaster.mdc)) to see current tasks, status, and IDs
 -   Determine the next task to work on using `next_task` / `task-master next` (see [`taskmaster.mdc`](mdc:.cursor/rules/taskmaster.mdc)).
 -   Analyze task complexity with `analyze_complexity` / `task-master analyze-complexity --research` (see [`taskmaster.mdc`](mdc:.cursor/rules/taskmaster.mdc)) before breaking down tasks
@@ -45,7 +45,7 @@ Task Master offers two primary ways to interact:
 -   Update dependent tasks when implementation differs from original plan using `update` / `task-master update --from=<id> --prompt="..."` or `update_task` / `task-master update-task --id=<id> --prompt="..."` (see [`taskmaster.mdc`](mdc:.cursor/rules/taskmaster.mdc))
 -   Add new tasks discovered during implementation using `add_task` / `task-master add-task --prompt="..."` (see [`taskmaster.mdc`](mdc:.cursor/rules/taskmaster.mdc)).
 -   Add new subtasks as needed using `add_subtask` / `task-master add-subtask --parent=<id> --title="..."` (see [`taskmaster.mdc`](mdc:.cursor/rules/taskmaster.mdc)).
--   Append notes or details to subtasks using `update_subtask` / `task-master update-subtask --id=<subtaskId> --prompt="..."` (see [`taskmaster.mdc`](mdc:.cursor/rules/taskmaster.mdc)).
+-   Append notes or details to subtasks using `update_subtask` / `task-master update-subtask --id=<subtaskId> --prompt='Add implementation notes here...\nMore details...'` (see [`taskmaster.mdc`](mdc:.cursor/rules/taskmaster.mdc)).
 -   Generate task files with `generate` / `task-master generate` (see [`taskmaster.mdc`](mdc:.cursor/rules/taskmaster.mdc)) after updating tasks.json
 -   Maintain valid dependency structure with `add_dependency`/`remove_dependency` tools or `task-master add-dependency`/`remove-dependency` commands, `validate_dependencies` / `task-master validate-dependencies`, and `fix_dependencies` / `task-master fix-dependencies` (see [`taskmaster.mdc`](mdc:.cursor/rules/taskmaster.mdc)) when needed
 -   Respect dependency chains and task priorities when selecting work
@@ -74,8 +74,8 @@ Task Master offers two primary ways to interact:
 -   When implementation differs significantly from planned approach
 -   When future tasks need modification due to current implementation choices
 -   When new dependencies or requirements emerge
--   Use `update` / `task-master update --from=<futureTaskId> --prompt="<explanation>"` (see [`taskmaster.mdc`](mdc:.cursor/rules/taskmaster.mdc)) to update multiple future tasks.
+-   Use `update` / `task-master update --from=<futureTaskId> --prompt='<explanation>\nUpdate context...'` (see [`taskmaster.mdc`](mdc:.cursor/rules/taskmaster.mdc)) to update multiple future tasks.
--   Use `update_task` / `task-master update-task --id=<taskId> --prompt="<explanation>"` (see [`taskmaster.mdc`](mdc:.cursor/rules/taskmaster.mdc)) to update a single specific task.
+-   Use `update_task` / `task-master update-task --id=<taskId> --prompt='<explanation>\nUpdate context...'` (see [`taskmaster.mdc`](mdc:.cursor/rules/taskmaster.mdc)) to update a single specific task.
 
 ## Task Status Management
 
@@ -150,6 +150,59 @@ Task Master offers two primary ways to interact:
 - Task files are automatically regenerated after dependency changes
 - Dependencies are visualized with status indicators in task listings and files
 
+## Iterative Subtask Implementation
+
+Once a task has been broken down into subtasks using `expand_task` or similar methods, follow this iterative process for implementation:
+
+1.  **Understand the Goal (Preparation):**
+    *   Use `get_task` / `task-master show <subtaskId>` (see [`taskmaster.mdc`](mdc:.cursor/rules/taskmaster.mdc)) to thoroughly understand the specific goals and requirements of the subtask.
+
+2.  **Initial Exploration & Planning (Iteration 1):**
+    *   This is the first attempt at creating a concrete implementation plan.
+    *   Explore the codebase to identify the precise files, functions, and even specific lines of code that will need modification.
+    *   Determine the intended code changes (diffs) and their locations.
+    *   Gather *all* relevant details from this exploration phase.
+
+3.  **Log the Plan:**
+    *   Run `update_subtask` / `task-master update-subtask --id=<subtaskId> --prompt='<detailed plan>'` (see [`taskmaster.mdc`](mdc:.cursor/rules/taskmaster.mdc)).
+    *   Provide the *complete and detailed* findings from the exploration phase in the prompt. Include file paths, line numbers, proposed diffs, reasoning, and any potential challenges identified. Do not omit details. The goal is to create a rich, timestamped log within the subtask's `details`.
+
+4.  **Verify the Plan:**
+    *   Run `get_task` / `task-master show <subtaskId>` again to confirm that the detailed implementation plan has been successfully appended to the subtask's details.
+
+5.  **Begin Implementation:**
+    *   Set the subtask status using `set_task_status` / `task-master set-status --id=<subtaskId> --status=in-progress` (see [`taskmaster.mdc`](mdc:.cursor/rules/taskmaster.mdc)).
+    *   Start coding based on the logged plan.
+
+6.  **Refine and Log Progress (Iteration 2+):**
+    *   As implementation progresses, you will encounter challenges, discover nuances, or confirm successful approaches.
+    *   **Before appending new information**: Briefly review the *existing* details logged in the subtask (using `get_task` or recalling from context) to ensure the update adds fresh insights and avoids redundancy.
+    *   **Regularly** use `update_subtask` / `task-master update-subtask --id=<subtaskId> --prompt='<update details>\n- What worked...\n- What didn't work...'` to append new findings.
+    *   **Crucially, log:**
+        *   What worked ("fundamental truths" discovered).
+        *   What didn't work and why (to avoid repeating mistakes).
+        *   Specific code snippets or configurations that were successful.
+        *   Decisions made, especially if confirmed with user input.
+        *   Any deviations from the initial plan and the reasoning.
+    *   The objective is to continuously enrich the subtask's details, creating a log of the implementation journey that helps the AI (and human developers) learn, adapt, and avoid repeating errors.
+
+7.  **Review & Update Rules (Post-Implementation):**
+    *   Once the implementation for the subtask is functionally complete, review all code changes and the relevant chat history.
+    *   Identify any new or modified code patterns, conventions, or best practices established during the implementation.
+    *   Create new or update existing Cursor rules in the `.cursor/rules/` directory to capture these patterns, following the guidelines in [`cursor_rules.mdc`](mdc:.cursor/rules/cursor_rules.mdc) and [`self_improve.mdc`](mdc:.cursor/rules/self_improve.mdc).
+
+8.  **Mark Task Complete:**
+    *   After verifying the implementation and updating any necessary rules, mark the subtask as completed: `set_task_status` / `task-master set-status --id=<subtaskId> --status=done`.
+
+9.  **Commit Changes (If using Git):**
+    *   Stage the relevant code changes and any updated/new rule files (`git add .`).
+    *   Craft a comprehensive Git commit message summarizing the work done for the subtask, including both code implementation and any rule adjustments.
+    *   Execute the commit command directly in the terminal (e.g., `git commit -m 'feat(module): Implement feature X for subtask <subtaskId>\n\n- Details about changes...\n- Updated rule Y for pattern Z'`).
+    *   Consider if a Changeset is needed according to [`changeset.mdc`](mdc:.cursor/rules/changeset.mdc). If so, run `npm run changeset`, stage the generated file, and amend the commit or create a new one.
+
+10. **Proceed to Next Subtask:**
+    *   Identify the next subtask in the dependency chain (e.g., using `next_task` / `task-master next`) and repeat this iterative process starting from step 1.
+
 ## Code Analysis & Refactoring Techniques
 
 - **Top-Level Function Search**:

.cursor/rules/mcp.mdc

@@ -67,65 +67,127 @@ When implementing a new direct function in `mcp-server/src/core/direct-functions
      ```
 
 4. **Comprehensive Error Handling**:
-   - ✅ **DO**: Wrap core function calls in try/catch blocks
+   - ✅ **DO**: Wrap core function calls *and AI calls* in try/catch blocks
    - ✅ **DO**: Log errors with appropriate severity and context
-   - ✅ **DO**: Return standardized error objects with code and message
+   - ✅ **DO**: Return standardized error objects with code and message (`{ success: false, error: { code: '...', message: '...' } }`)
-   - ✅ **DO**: Handle file system errors separately from function-specific errors
+   - ✅ **DO**: Handle file system errors, AI client errors, AI processing errors, and core function errors distinctly with appropriate codes.
    - **Example**:
      ```javascript
      try {
-       // Core function call
+       // Core function call or AI logic
      } catch (error) {
-       log.error(`Failed to execute command: ${error.message}`);
+       log.error(`Failed to execute direct function logic: ${error.message}`);
        return {
          success: false,
          error: {
-           code: error.code || 'DIRECT_FUNCTION_ERROR',
+           code: error.code || 'DIRECT_FUNCTION_ERROR', // Use specific codes like AI_CLIENT_ERROR, etc.
            message: error.message,
-           details: error.stack
+           details: error.stack // Optional: Include stack in debug mode
          },
-         fromCache: false
+         fromCache: false // Ensure this is included if applicable
        };
      }
      ```
 
-5. **Silent Mode Implementation**:
+5. **Handling Logging Context (`mcpLog`)**:
-   - ✅ **DO**: Import silent mode utilities at the top of your file
+   - **Requirement**: Core functions that use the internal `report` helper function (common in `task-manager.js`, `dependency-manager.js`, etc.) expect the `options` object to potentially contain an `mcpLog` property. This `mcpLog` object **must** have callable methods for each log level (e.g., `mcpLog.info(...)`, `mcpLog.error(...)`).
+   - **Challenge**: The `log` object provided by FastMCP to the direct function's context, while functional, might not perfectly match this expected structure or could change in the future. Passing it directly can lead to runtime errors like `mcpLog[level] is not a function`.
+   - **Solution: The Logger Wrapper Pattern**: To reliably bridge the FastMCP `log` object and the core function's `mcpLog` expectation, use a simple wrapper object within the direct function:
      ```javascript
-     import { enableSilentMode, disableSilentMode } from '../../../../scripts/modules/utils.js';
+     // Standard logWrapper pattern within a Direct Function
-     ```
+     const logWrapper = {
-   - ✅ **DO**: Wrap core function calls with silent mode control
+       info: (message, ...args) => log.info(message, ...args),
-     ```javascript
+       warn: (message, ...args) => log.warn(message, ...args),
-     // Enable silent mode before the core function call
+       error: (message, ...args) => log.error(message, ...args),
-     enableSilentMode();
+       debug: (message, ...args) => log.debug && log.debug(message, ...args), // Handle optional debug
+       success: (message, ...args) => log.info(message, ...args) // Map success to info if needed
+     };
 
-     // Execute core function
+     // ... later when calling the core function ...
-     const result = await coreFunction(param1, param2);
+     await coreFunction(
+       // ... other arguments ...
+       tasksPath, 
+       taskId,
+       { 
+         mcpLog: logWrapper, // Pass the wrapper object
+         session 
+       },
+       'json' // Pass 'json' output format if supported by core function
+     );
+     ```
+   - **Critical For JSON Output Format**: Passing the `logWrapper` as `mcpLog` serves a dual purpose:
+     1. **Prevents Runtime Errors**: It ensures the `mcpLog[level](...)` calls within the core function succeed
+     2. **Controls Output Format**: In functions like `updateTaskById` and `updateSubtaskById`, the presence of `mcpLog` in the options triggers setting `outputFormat = 'json'` (instead of 'text'). This prevents UI elements (spinners, boxes) from being generated, which would break the JSON response.
+   - **Proven Solution**: This pattern has successfully fixed multiple issues in our MCP tools (including `update-task` and `update-subtask`), where direct passing of the `log` object or omitting `mcpLog` led to either runtime errors or JSON parsing failures from UI output.
+   - **When To Use**: Implement this wrapper in any direct function that calls a core function with an `options` object that might use `mcpLog` for logging or output format control.
+   - **Why it Works**: The `logWrapper` explicitly defines the `.info()`, `.warn()`, `.error()`, etc., methods that the core function's `report` helper needs, ensuring the `mcpLog[level](...)` call succeeds. It simply forwards the logging calls to the actual FastMCP `log` object.
+   - **Combined with Silent Mode**: Remember that using the `logWrapper` for `mcpLog` is **necessary *in addition* to using `enableSilentMode()` / `disableSilentMode()`** (see next point). The wrapper handles structured logging *within* the core function, while silent mode suppresses direct `console.log` and UI elements (spinners, boxes) that would break the MCP JSON response.
 
-     // Restore normal logging
+6. **Silent Mode Implementation**:
-     disableSilentMode();
+    - ✅ **DO**: Import silent mode utilities at the top: `import { enableSilentMode, disableSilentMode, isSilentMode } from '../../../../scripts/modules/utils.js';`
-     ```
+    - ✅ **DO**: Ensure core Task Master functions called from direct functions do **not** pollute `stdout` with console output (banners, spinners, logs) that would break MCP's JSON communication.
-   - ✅ **DO**: Add proper error handling to ensure silent mode is disabled
+      - **Preferred**: Modify the core function to accept an `outputFormat: 'json'` parameter and check it internally before printing UI elements. Pass `'json'` from the direct function.
-     ```javascript
+      - **Required Fallback/Guarantee**: If the core function cannot be modified or its output suppression is unreliable, **wrap the core function call** within the direct function using `enableSilentMode()` / `disableSilentMode()` in a `try/finally` block. This guarantees no console output interferes with the MCP response.
-     try {
+    - ✅ **DO**: Use `isSilentMode()` function to check global silent mode status if needed (rare in direct functions), NEVER access the global `silentMode` variable directly.
-       enableSilentMode();
+    - ❌ **DON'T**: Wrap AI client initialization or AI API calls in `enable/disableSilentMode`; their logging is controlled via the `log` object (passed potentially within the `logWrapper` for core functions).
-       // Core function execution
+    - ❌ **DON'T**: Assume a core function is silent just because it *should* be. Verify or use the `enable/disableSilentMode` wrapper.
-       const result = await coreFunction(param1, param2);
+    - **Example (Direct Function Guaranteeing Silence and using Log Wrapper)**:
-       disableSilentMode();
+      ```javascript
-       return { success: true, data: result };
+      export async function coreWrapperDirect(args, log, context = {}) {
-     } catch (error) {
+        const { session } = context;
-       // Make sure to restore normal logging even if there's an error
+        const tasksPath = findTasksJsonPath(args, log);
-       disableSilentMode();
+        
-       log.error(`Error in function: ${error.message}`);
+        // Create the logger wrapper
-       return { 
+        const logWrapper = { /* ... as defined above ... */ };
-         success: false, 
+
-         error: { code: 'ERROR_CODE', message: error.message } 
+        enableSilentMode(); // Ensure silence for direct console output
-       };
+        try {
-     }
+          // Call core function, passing wrapper and 'json' format
-     ```
+          const result = await coreFunction(
-   - ❌ **DON'T**: Forget to disable silent mode when errors occur
+             tasksPath, 
-   - ❌ **DON'T**: Leave silent mode enabled outside a direct function's scope
+             args.param1, 
-   - ❌ **DON'T**: Skip silent mode for core function calls that generate logs
+             { mcpLog: logWrapper, session }, 
+             'json' // Explicitly request JSON format if supported
+          ); 
+          return { success: true, data: result };
+        } catch (error) {
+           log.error(`Error: ${error.message}`);
+           // Return standardized error object
+           return { success: false, error: { /* ... */ } };
+        } finally {
+           disableSilentMode(); // Critical: Always disable in finally
+        }
+      }
+      ```
+
+7. **Debugging MCP/Core Logic Interaction**:
+    - ✅ **DO**: If an MCP tool fails with unclear errors (like JSON parsing failures), run the equivalent `task-master` CLI command in the terminal. The CLI often provides more detailed error messages originating from the core logic (e.g., `ReferenceError`, stack traces) that are obscured by the MCP layer.
+
+### Specific Guidelines for AI-Based Direct Functions
+
+Direct functions that interact with AI (e.g., `addTaskDirect`, `expandTaskDirect`) have additional responsibilities:
+
+- **Context Parameter**: These functions receive an additional `context` object as their third parameter. **Critically, this object should only contain `{ session }`**. Do NOT expect or use `reportProgress` from this context.
+  ```javascript
+  export async function yourAIDirect(args, log, context = {}) {
+    const { session } = context; // Only expect session
+    // ...
+  }
+  ```
+- **AI Client Initialization**:
+  - ✅ **DO**: Use the utilities from [`mcp-server/src/core/utils/ai-client-utils.js`](mdc:mcp-server/src/core/utils/ai-client-utils.js) (e.g., `getAnthropicClientForMCP(session, log)`) to get AI client instances. These correctly use the `session` object to resolve API keys.
+  - ✅ **DO**: Wrap client initialization in a try/catch block and return a specific `AI_CLIENT_ERROR` on failure.
+- **AI Interaction**:
+  - ✅ **DO**: Build prompts using helper functions where appropriate (e.g., from `ai-prompt-helpers.js`).
+  - ✅ **DO**: Make the AI API call using appropriate helpers (e.g., `_handleAnthropicStream`). Pass the `log` object to these helpers for internal logging. **Do NOT pass `reportProgress`**.
+  - ✅ **DO**: Parse the AI response using helpers (e.g., `parseTaskJsonResponse`) and handle parsing errors with a specific code (e.g., `RESPONSE_PARSING_ERROR`).
+- **Calling Core Logic**:
+  - ✅ **DO**: After successful AI interaction, call the relevant core Task Master function (from `scripts/modules/`) if needed (e.g., `addTaskDirect` calls `addTask`).
+  - ✅ **DO**: Pass necessary data, including potentially the parsed AI results, to the core function.
+  - ✅ **DO**: If the core function can produce console output, call it with an `outputFormat: 'json'` argument (or similar, depending on the function) to suppress CLI output. Ensure the core function is updated to respect this. Use `enableSilentMode/disableSilentMode` around the core function call as a fallback if `outputFormat` is not supported or insufficient.
+- **Progress Indication**:
+  - ❌ **DON'T**: Call `reportProgress` within the direct function.
+  - ✅ **DO**: If intermediate progress status is needed *within* the long-running direct function, use standard logging: `log.info('Progress: Processing AI response...')`.
 
 ## Tool Definition and Execution
 
@@ -159,14 +221,21 @@ server.addTool({
 The `execute` function receives validated arguments and the FastMCP context:
 
 ```javascript
+// Standard signature
 execute: async (args, context) => {
   // Tool implementation
 }
+
+// Destructured signature (recommended)
+execute: async (args, { log, reportProgress, session }) => {
+  // Tool implementation
+}
 ```
 
 - **args**: The first parameter contains all the validated parameters defined in the tool's schema.
 - **context**: The second parameter is an object containing `{ log, reportProgress, session }` provided by FastMCP.
-  - ✅ **DO**: `execute: async (args, { log, reportProgress, session }) => {}`
+  - ✅ **DO**: Use `{ log, session }` when calling direct functions.
+  - ⚠️ **WARNING**: Avoid passing `reportProgress` down to direct functions due to client compatibility issues. See Progress Reporting Convention below.
 
 ### Standard Tool Execution Pattern
 
@@ -174,20 +243,27 @@ The `execute` method within each MCP tool (in `mcp-server/src/tools/*.js`) shoul
 
 1.  **Log Entry**: Log the start of the tool execution with relevant arguments.
 2.  **Get Project Root**: Use the `getProjectRootFromSession(session, log)` utility (from [`tools/utils.js`](mdc:mcp-server/src/tools/utils.js)) to extract the project root path from the client session. Fall back to `args.projectRoot` if the session doesn't provide a root.
-3.  **Call Direct Function**: Invoke the corresponding `*Direct` function wrapper (e.g., `listTasksDirect` from [`task-master-core.js`](mdc:mcp-server/src/core/task-master-core.js)), passing an updated `args` object that includes the resolved `projectRoot`, along with the `log` object: `await someDirectFunction({ ...args, projectRoot: resolvedRootFolder }, log);`
+3.  **Call Direct Function**: Invoke the corresponding `*Direct` function wrapper (e.g., `listTasksDirect` from [`task-master-core.js`](mdc:mcp-server/src/core/task-master-core.js)), passing an updated `args` object that includes the resolved `projectRoot`. Crucially, the third argument (context) passed to the direct function should **only include `{ log, session }`**. **Do NOT pass `reportProgress`**.
+    ```javascript
+    // Example call to a non-AI direct function
+    const result = await someDirectFunction({ ...args, projectRoot }, log); 
+    
+    // Example call to an AI-based direct function
+    const resultAI = await someAIDirect({ ...args, projectRoot }, log, { session }); 
+    ```
 4.  **Handle Result**: Receive the result object (`{ success, data/error, fromCache }`) from the `*Direct` function.
 5.  **Format Response**: Pass this result object to the `handleApiResult` utility (from [`tools/utils.js`](mdc:mcp-server/src/tools/utils.js)) for standardized MCP response formatting and error handling.
 6.  **Return**: Return the formatted response object provided by `handleApiResult`.
 
 ```javascript
-// Example execute method structure
+// Example execute method structure for a tool calling an AI-based direct function
 import { getProjectRootFromSession, handleApiResult, createErrorResponse } from './utils.js';
-import { someDirectFunction } from '../core/task-master-core.js';
+import { someAIDirectFunction } from '../core/task-master-core.js';
 
 // ... inside server.addTool({...})
-execute: async (args, { log, reportProgress, session }) => {
+execute: async (args, { log, session }) => { // Note: reportProgress is omitted here
   try {
-    log.info(`Starting tool execution with args: ${JSON.stringify(args)}`);
+    log.info(`Starting AI tool execution with args: ${JSON.stringify(args)}`);
 
     // 1. Get Project Root
     let rootFolder = getProjectRootFromSession(session, log);
@@ -196,17 +272,17 @@ execute: async (args, { log, reportProgress, session }) => {
       log.info(`Using project root from args as fallback: ${rootFolder}`);
     }
 
-    // 2. Call Direct Function (passing resolved root)
+    // 2. Call AI-Based Direct Function (passing only log and session in context)
-    const result = await someDirectFunction({
+    const result = await someAIDirectFunction({
       ...args,
       projectRoot: rootFolder // Ensure projectRoot is explicitly passed
-    }, log);
+    }, log, { session }); // Pass session here, NO reportProgress
 
     // 3. Handle and Format Response
     return handleApiResult(result, log);
 
   } catch (error) {
-    log.error(`Error during tool execution: ${error.message}`);
+    log.error(`Error during AI tool execution: ${error.message}`);
     return createErrorResponse(error.message);
   }
 }
@@ -214,15 +290,17 @@ execute: async (args, { log, reportProgress, session }) => {
 
 ### Using AsyncOperationManager for Background Tasks
 
-For tools that execute long-running operations, use the AsyncOperationManager to run them in the background:
+For tools that execute potentially long-running operations *where the AI call is just one part* (e.g., `expand-task`, `update`), use the AsyncOperationManager. The `add-task` command, as refactored, does *not* require this in the MCP tool layer because the direct function handles the primary AI work and returns the final result synchronously from the perspective of the MCP tool.
+
+For tools that *do* use `AsyncOperationManager`:
 
 ```javascript
-import { asyncOperationManager } from '../core/utils/async-manager.js';
+import { AsyncOperationManager } from '../utils/async-operation-manager.js'; // Correct path assuming utils location
 import { getProjectRootFromSession, createContentResponse, createErrorResponse } from './utils.js';
 import { someIntensiveDirect } from '../core/task-master-core.js';
 
 // ... inside server.addTool({...})
-execute: async (args, { log, reportProgress, session }) => {
+execute: async (args, { log, session }) => { // Note: reportProgress omitted
   try {
     log.info(`Starting background operation with args: ${JSON.stringify(args)}`);
 
@@ -233,52 +311,58 @@ execute: async (args, { log, reportProgress, session }) => {
       log.info(`Using project root from args as fallback: ${rootFolder}`);
     }
     
-    // 2. Add operation to the async manager
+    // Create operation description
-    const operationId = asyncOperationManager.addOperation(
+    const operationDescription = `Expanding task ${args.id}...`; // Example
-      someIntensiveDirect, // The direct function to execute
+
-      { ...args, projectRoot: rootFolder }, // Args to pass
+    // 2. Start async operation using AsyncOperationManager
-      { log, reportProgress, session } // Context to preserve
+    const operation = AsyncOperationManager.createOperation(
+      operationDescription,
+      async (reportProgressCallback) => { // This callback is provided by AsyncOperationManager
+        // This runs in the background
+        try {
+          // Report initial progress *from the manager's callback*
+          reportProgressCallback({ progress: 0, status: 'Starting operation...' });
+
+          // Call the direct function (passing only session context)
+          const result = await someIntensiveDirect(
+            { ...args, projectRoot: rootFolder }, 
+            log, 
+            { session } // Pass session, NO reportProgress
+          );
+
+          // Report final progress *from the manager's callback*
+          reportProgressCallback({
+            progress: 100,
+            status: result.success ? 'Operation completed' : 'Operation failed',
+            result: result.data, // Include final data if successful
+            error: result.error   // Include error object if failed
+          });
+
+          return result; // Return the direct function's result
+        } catch (error) {
+          // Handle errors within the async task
+           reportProgressCallback({
+            progress: 100,
+            status: 'Operation failed critically',
+            error: { message: error.message, code: error.code || 'ASYNC_OPERATION_FAILED' }
+          });
+          throw error; // Re-throw for the manager to catch
+        }
+      }
     );
 
     // 3. Return immediate response with operation ID
-    return createContentResponse({
+    return {
-      message: "Operation started successfully",
+        status: 202, // StatusCodes.ACCEPTED
-      operationId,
+        body: {
-      status: "pending"
+            success: true,
-    });
+            message: 'Operation started',
+            operationId: operation.id
+        }
+    };
   } catch (error) {
     log.error(`Error starting background operation: ${error.message}`);
-    return createErrorResponse(error.message);
+    return createErrorResponse(`Failed to start operation: ${error.message}`); // Use standard error response
-  }
-}
-```
-
-Clients should then use the `get_operation_status` tool to check on operation progress:
-
-```javascript
-// In get-operation-status.js
-import { asyncOperationManager } from '../core/utils/async-manager.js';
-import { createContentResponse, createErrorResponse } from './utils.js';
-
-// ... inside server.addTool({...})
-execute: async (args, { log }) => {
-  try {
-    const { operationId } = args;
-    log.info(`Checking status of operation: ${operationId}`);
-    
-    const status = asyncOperationManager.getStatus(operationId);
-    
-    if (status.status === 'not_found') {
-      return createErrorResponse(status.error.message);
-    }
-    
-    return createContentResponse({
-      ...status,
-      message: `Operation status: ${status.status}`
-    });
-  } catch (error) {
-    log.error(`Error checking operation status: ${error.message}`);
-    return createErrorResponse(error.message);
   }
 }
 ```
@@ -322,7 +406,7 @@ export function registerInitializeProjectTool(server) {
 
 ### Logging Convention
 
-The `log` object (destructured from `context`) provides standardized logging methods. Use it within both the `execute` method and the `*Direct` functions.
+The `log` object (destructured from `context`) provides standardized logging methods. Use it within both the `execute` method and the `*Direct` functions. **If progress indication is needed within a direct function, use `log.info()` instead of `reportProgress`**.
 
 ```javascript
 // Proper logging usage
@@ -330,19 +414,14 @@ log.info(`Starting ${toolName} with parameters: ${JSON.stringify(sanitizedArgs)}
 log.debug("Detailed operation info", { data });
 log.warn("Potential issue detected");
 log.error(`Error occurred: ${error.message}`, { stack: error.stack });
+log.info('Progress: 50% - AI call initiated...'); // Example progress logging
 ```
 
 ### Progress Reporting Convention
 
-Use `reportProgress` (destructured from `context`) for long-running operations. It expects an object `{ progress: number, total?: number }`.
+- ⚠️ **DEPRECATED within Direct Functions**: The `reportProgress` function passed in the `context` object should **NOT** be called from within `*Direct` functions. Doing so can cause client-side validation errors due to missing/incorrect `progressToken` handling.
-
+- ✅ **DO**: For tools using `AsyncOperationManager`, use the `reportProgressCallback` function *provided by the manager* within the background task definition (as shown in the `AsyncOperationManager` example above) to report progress updates for the *overall operation*.
-```javascript
+- ✅ **DO**: If finer-grained progress needs to be indicated *during* the execution of a `*Direct` function (whether called directly or via `AsyncOperationManager`), use `log.info()` statements (e.g., `log.info('Progress: Parsing AI response...')`).
-await reportProgress({ progress: 0 }); // Start
-// ... work ...
-await reportProgress({ progress: 50 }); // Intermediate (total optional)
-// ... more work ...
-await reportProgress({ progress: 100 }); // Complete
-```
 
 ### Session Usage Convention
 
@@ -350,32 +429,39 @@ The `session` object (destructured from `context`) contains authenticated sessio
 
 - **Authentication**: Access user-specific data (`session.userId`, etc.) if authentication is implemented.
 - **Project Root**: The primary use in Task Master is accessing `session.roots` to determine the client's project root directory via the `getProjectRootFromSession` utility (from [`tools/utils.js`](mdc:mcp-server/src/tools/utils.js)). See the Standard Tool Execution Pattern above.
+- **Environment Variables**: The `session.env` object is critical for AI tools. Pass the `session` object to the `*Direct` function's context, and then to AI client utility functions (like `getAnthropicClientForMCP`) which will extract API keys and other relevant environment settings (e.g., `MODEL`, `MAX_TOKENS`) from `session.env`.
 - **Capabilities**: Can be used to check client capabilities (`session.clientCapabilities`).
 
 ## Direct Function Wrappers (`*Direct`)
 
 These functions, located in `mcp-server/src/core/direct-functions/`, form the core logic execution layer for MCP tools.
 
-- **Purpose**: Bridge MCP tools and core Task Master modules (`scripts/modules/*`).
+- **Purpose**: Bridge MCP tools and core Task Master modules (`scripts/modules/*`). Handle AI interactions if applicable.
 - **Responsibilities**:
-  - Receive `args` (including the `projectRoot` determined by the tool) and `log` object.
+  - Receive `args` (including the `projectRoot` determined by the tool), `log` object, and optionally a `context` object (containing **only `{ session }` if needed).
-  - **Find `tasks.json`**: Use `findTasksJsonPath(args, log)` from [`core/utils/path-utils.js`](mdc:mcp-server/src/core/utils/path-utils.js). This function prioritizes the provided `args.projectRoot`.
+  - **Find `tasks.json`**: Use `findTasksJsonPath(args, log)` from [`core/utils/path-utils.js`](mdc:mcp-server/src/core/utils/path-utils.js).
   - Validate arguments specific to the core logic.
-  - **Implement Silent Mode**: Import and use `enableSilentMode` and `disableSilentMode` around core function calls.
+  - **Handle AI Logic (if applicable)**: Initialize AI clients (using `session` from context), build prompts, make AI calls, parse responses.
-  - **Implement Caching**: Use `getCachedOrExecute` from [`tools/utils.js`](mdc:mcp-server/src/tools/utils.js) for read operations.
+  - **Implement Caching (if applicable)**: Use `getCachedOrExecute` from [`tools/utils.js`](mdc:mcp-server/src/tools/utils.js) for read operations.
-  - Call the underlying function from the core Task Master modules.
+  - **Call Core Logic**: Call the underlying function from the core Task Master modules, passing necessary data (including AI results if applicable).
-  - Handle errors gracefully.
+    - ✅ **DO**: Pass `outputFormat: 'json'` (or similar) to the core function if it might produce console output.
-  - Return a standardized result object: `{ success: boolean, data?: any, error?: { code: string, message: string }, fromCache: boolean }`.
+    - ✅ **DO**: Wrap the core function call with `enableSilentMode/disableSilentMode` if necessary.
+  - Handle errors gracefully (AI errors, core logic errors, file errors).
+  - Return a standardized result object: `{ success: boolean, data?: any, error?: { code: string, message: string }, fromCache?: boolean }`.
+  - ❌ **DON'T**: Call `reportProgress`. Use `log.info` for progress indication if needed.
 
 ## Key Principles
 
 - **Prefer Direct Function Calls**: MCP tools should always call `*Direct` wrappers instead of `executeTaskMasterCommand`.
-- **Standardized Execution Flow**: Follow the pattern: MCP Tool -> `getProjectRootFromSession` -> `*Direct` Function -> Core Logic.
+- **Standardized Execution Flow**: Follow the pattern: MCP Tool -> `getProjectRootFromSession` -> `*Direct` Function -> Core Logic / AI Logic.
 - **Path Resolution via Direct Functions**: The `*Direct` function is responsible for finding the exact `tasks.json` path using `findTasksJsonPath`, relying on the `projectRoot` passed in `args`.
-- **Silent Mode in Direct Functions**: Wrap all core function calls with `enableSilentMode()` and `disableSilentMode()` to prevent logs from interfering with JSON responses.
+- **AI Logic in Direct Functions**: For AI-based tools, the `*Direct` function handles AI client initialization, calls, and parsing, using the `session` object passed in its context.
-- **Async Processing for Intensive Operations**: Use AsyncOperationManager for CPU-intensive or long-running operations.
+- **Silent Mode in Direct Functions**: Wrap *core function* calls (from `scripts/modules`) with `enableSilentMode()` and `disableSilentMode()` if they produce console output not handled by `outputFormat`. Do not wrap AI calls.
+- **Selective Async Processing**: Use `AsyncOperationManager` in the *MCP Tool layer* for operations involving multiple steps or long waits beyond a single AI call (e.g., file processing + AI call + file writing). Simple AI calls handled entirely within the `*Direct` function (like `addTaskDirect`) may not need it at the tool layer.
+- **No `reportProgress` in Direct Functions**: Do not pass or use `reportProgress` within `*Direct` functions. Use `log.info()` for internal progress or report progress from the `AsyncOperationManager` callback in the MCP tool layer.
+- **Output Formatting**: Ensure core functions called by `*Direct` functions can suppress CLI output, ideally via an `outputFormat` parameter.
 - **Project Initialization**: Use the initialize_project tool for setting up new projects in integrated environments.
-- **Centralized Utilities**: Use helpers from `mcp-server/src/tools/utils.js` (like `handleApiResult`, `getProjectRootFromSession`, `getCachedOrExecute`) and `mcp-server/src/core/utils/path-utils.js` (`findTasksJsonPath`). See [`utilities.mdc`](mdc:.cursor/rules/utilities.mdc).
+- **Centralized Utilities**: Use helpers from `mcp-server/src/tools/utils.js`, `mcp-server/src/core/utils/path-utils.js`, and `mcp-server/src/core/utils/ai-client-utils.js`. See [`utilities.mdc`](mdc:.cursor/rules/utilities.mdc).
 - **Caching in Direct Functions**: Caching logic resides *within* the `*Direct` functions using `getCachedOrExecute`.
 
 ## Resources and Resource Templates
@@ -392,32 +478,38 @@ Resources provide LLMs with static or dynamic data without executing tools.
 
 Follow these steps to add MCP support for an existing Task Master command (see [`new_features.mdc`](mdc:.cursor/rules/new_features.mdc) for more detail):
 
-1.  **Ensure Core Logic Exists**: Verify the core functionality is implemented and exported from the relevant module in `scripts/modules/`.
+1.  **Ensure Core Logic Exists**: Verify the core functionality is implemented and exported from the relevant module in `scripts/modules/`. Ensure the core function can suppress console output (e.g., via an `outputFormat` parameter).
 
 2.  **Create Direct Function File in `mcp-server/src/core/direct-functions/`**:
     - Create a new file (e.g., `your-command.js`) using **kebab-case** naming.
-    - Import necessary core functions, **`findTasksJsonPath` from `../utils/path-utils.js`**, and **silent mode utilities**.
+    - Import necessary core functions, `findTasksJsonPath`, silent mode utilities, and potentially AI client/prompt utilities.
-    - Implement `async function yourCommandDirect(args, log)` using **camelCase** with `Direct` suffix:
+    - Implement `async function yourCommandDirect(args, log, context = {})` using **camelCase** with `Direct` suffix. **Remember `context` should only contain `{ session }` if needed (for AI keys/config).**
-        - **Path Resolution**: Obtain the tasks file path using `const tasksPath = findTasksJsonPath(args, log);`. This handles project root detection automatically based on `args.projectRoot`.
+        - **Path Resolution**: Obtain `tasksPath` using `findTasksJsonPath(args, log)`.
         - Parse other `args` and perform necessary validation.
-        - **Implement Silent Mode**: Wrap core function calls with enableSilentMode/disableSilentMode.
+        - **Handle AI (if applicable)**: Initialize clients using `get*ClientForMCP(session, log)`, build prompts, call AI, parse response. Handle AI-specific errors.
-        - **If Caching**: Implement caching using `getCachedOrExecute` from `../../tools/utils.js`.
+        - **Implement Caching (if applicable)**: Use `getCachedOrExecute`.
-        - **If Not Caching**: Directly call the core logic function within a try/catch block.
+        - **Call Core Logic**:
-        - Format the return as `{ success: true/false, data/error, fromCache: boolean }`.
+            - Wrap with `enableSilentMode/disableSilentMode` if necessary.
+            - Pass `outputFormat: 'json'` (or similar) if applicable.
+            - Handle errors from the core function.
+        - Format the return as `{ success: true/false, data/error, fromCache?: boolean }`.
+        - ❌ **DON'T**: Call `reportProgress`.
     - Export the wrapper function.
 
 3.  **Update `task-master-core.js` with Import/Export**: Import and re-export your `*Direct` function and add it to the `directFunctions` map.
 
 4.  **Create MCP Tool (`mcp-server/src/tools/`)**:
     - Create a new file (e.g., `your-command.js`) using **kebab-case**.
-    - Import `zod`, `handleApiResult`, `createErrorResponse`, **`getProjectRootFromSession`**, and your `yourCommandDirect` function.
+    - Import `zod`, `handleApiResult`, `createErrorResponse`, `getProjectRootFromSession`, and your `yourCommandDirect` function. Import `AsyncOperationManager` if needed.
     - Implement `registerYourCommandTool(server)`.
     - Define the tool `name` using **snake_case** (e.g., `your_command`).
-    - Define the `parameters` using `zod`. **Crucially, define `projectRoot` as optional**: `projectRoot: z.string().optional().describe(...)`. Include `file` if applicable.
+    - Define the `parameters` using `zod`. Include `projectRoot: z.string().optional()`.
-    - Implement the standard `async execute(args, { log, reportProgress, session })` method:
+    - Implement the `async execute(args, { log, session })` method (omitting `reportProgress` from destructuring).
-      - Get `rootFolder` using `getProjectRootFromSession` (with fallback to `args.projectRoot`).
+        - Get `rootFolder` using `getProjectRootFromSession(session, log)`.
-      - Call `yourCommandDirect({ ...args, projectRoot: rootFolder }, log)`. 
+        - **Determine Execution Strategy**:
-      - Pass the result to `handleApiResult(result, log, 'Error Message')`.
+            - **If using `AsyncOperationManager`**: Create the operation, call the `*Direct` function from within the async task callback (passing `log` and `{ session }`), report progress *from the callback*, and return the initial `ACCEPTED` response.
+            - **If calling `*Direct` function synchronously** (like `add-task`): Call `await yourCommandDirect({ ...args, projectRoot }, log, { session });`. Handle the result with `handleApiResult`.
+        - ❌ **DON'T**: Pass `reportProgress` down to the direct function in either case.
 
 5.  **Register Tool**: Import and call `registerYourCommandTool` in `mcp-server/src/tools/index.js`.
 

.cursor/rules/new_features.mdc

@@ -34,9 +34,9 @@ The standard pattern for adding a feature follows this workflow:
 ## Critical Checklist for New Features
 
 - **Comprehensive Function Exports**:
-  - ✅ **DO**: Export all helper functions and utility methods needed by your new function
+  - ✅ **DO**: Export **all core functions, helper functions (like `generateSubtaskPrompt`), and utility methods** needed by your new function or command from their respective modules.
-  - ✅ **DO**: Review dependencies and ensure functions like `findTaskById`, `taskExists` are exported
+  - ✅ **DO**: **Explicitly review the module's `export { ... }` block** at the bottom of the file to ensure every required dependency (even seemingly minor helpers like `findTaskById`, `taskExists`, specific prompt generators, AI call handlers, etc.) is included.
-  - ❌ **DON'T**: Assume internal functions are already exported - always check and add them explicitly
+  - ❌ **DON'T**: Assume internal functions are already exported - **always verify**. A missing export will cause runtime errors (e.g., `ReferenceError: generateSubtaskPrompt is not defined`).
   - **Example**: If implementing a feature that checks task existence, ensure the helper function is in exports:
   ```javascript
   // At the bottom of your module file:
@@ -45,14 +45,21 @@ The standard pattern for adding a feature follows this workflow:
     yourNewFunction,
     taskExists,  // Helper function used by yourNewFunction
     findTaskById, // Helper function used by yourNewFunction
+    generateSubtaskPrompt, // Helper needed by expand/add features
+    getSubtasksFromAI,     // Helper needed by expand/add features
   };
   ```
 
-- **Parameter Completeness**:
+- **Parameter Completeness and Matching**:
   - ✅ **DO**: Pass all required parameters to functions you call within your implementation
   - ✅ **DO**: Check function signatures before implementing calls to them
+  - ✅ **DO**: Verify that direct function parameters match their core function counterparts
+  - ✅ **DO**: When implementing a direct function for MCP, ensure it only accepts parameters that exist in the core function
+  - ✅ **DO**: Verify the expected *internal structure* of complex object parameters (like the `mcpLog` object, see mcp.mdc for the required logger wrapper pattern)
+  - ❌ **DON'T**: Add parameters to direct functions that don't exist in core functions
   - ❌ **DON'T**: Assume default parameter values will handle missing arguments
-  - **Example**: When calling file generation, pass both required parameters:
+  - ❌ **DON'T**: Assume object parameters will work without verifying their required internal structure or methods.
+  - **Example**: When calling file generation, pass all required parameters:
   ```javascript
   // ✅ DO: Pass all required parameters
   await generateTaskFiles(tasksPath, path.dirname(tasksPath));
@@ -61,11 +68,58 @@ The standard pattern for adding a feature follows this workflow:
   await generateTaskFiles(tasksPath); // Error - missing outputDir parameter
   ```
   
+  **Example**: Properly match direct function parameters to core function:
+  ```javascript
+  // Core function signature
+  async function expandTask(tasksPath, taskId, numSubtasks, useResearch = false, additionalContext = '', options = {}) {
+    // Implementation...
+  }
+  
+  // ✅ DO: Match direct function parameters to core function
+  export async function expandTaskDirect(args, log, context = {}) {
+    // Extract only parameters that exist in the core function
+    const taskId = parseInt(args.id, 10);
+    const numSubtasks = args.num ? parseInt(args.num, 10) : undefined;
+    const useResearch = args.research === true;
+    const additionalContext = args.prompt || '';
+    
+    // Call core function with matched parameters
+    const result = await expandTask(
+      tasksPath,
+      taskId,
+      numSubtasks,
+      useResearch,
+      additionalContext,
+      { mcpLog: log, session: context.session }
+    );
+    
+    // Return result
+    return { success: true, data: result, fromCache: false };
+  }
+  
+  // ❌ DON'T: Use parameters that don't exist in the core function
+  export async function expandTaskDirect(args, log, context = {}) {
+    // DON'T extract parameters that don't exist in the core function!
+    const force = args.force === true; // ❌ WRONG - 'force' doesn't exist in core function
+    
+    // DON'T pass non-existent parameters to core functions
+    const result = await expandTask(
+      tasksPath,
+      args.id,
+      args.num,
+      args.research,
+      args.prompt,
+      force, // ❌ WRONG - this parameter doesn't exist in the core function
+      { mcpLog: log }
+    );
+  }
+  ```
+
 - **Consistent File Path Handling**:
-  - ✅ **DO**: Use consistent file naming conventions: `task_${id.toString().padStart(3, '0')}.txt`
+  - ✅ DO: Use consistent file naming conventions: `task_${id.toString().padStart(3, '0')}.txt`
-  - ✅ **DO**: Use `path.join()` for composing file paths
+  - ✅ DO: Use `path.join()` for composing file paths
-  - ✅ **DO**: Use appropriate file extensions (.txt for tasks, .json for data)
+  - ✅ DO: Use appropriate file extensions (.txt for tasks, .json for data)
-  - ❌ **DON'T**: Hardcode path separators or inconsistent file extensions
+  - ❌ DON'T: Hardcode path separators or inconsistent file extensions
   - **Example**: Creating file paths for tasks:
   ```javascript
   // ✅ DO: Use consistent file naming and path.join
@@ -79,10 +133,10 @@ The standard pattern for adding a feature follows this workflow:
   ```
 
 - **Error Handling and Reporting**:
-  - ✅ **DO**: Use structured error objects with code and message properties
+  - ✅ DO: Use structured error objects with code and message properties
-  - ✅ **DO**: Include clear error messages identifying the specific problem
+  - ✅ DO: Include clear error messages identifying the specific problem
-  - ✅ **DO**: Handle both function-specific errors and potential file system errors
+  - ✅ DO: Handle both function-specific errors and potential file system errors
-  - ✅ **DO**: Log errors at appropriate severity levels
+  - ✅ DO: Log errors at appropriate severity levels
   - **Example**: Structured error handling in core functions:
   ```javascript
   try {
@@ -98,33 +152,43 @@ The standard pattern for adding a feature follows this workflow:
   ```
 
 - **Silent Mode Implementation**:
-  - ✅ **DO**: Import silent mode utilities in direct functions: `import { enableSilentMode, disableSilentMode } from '../../../../scripts/modules/utils.js';`
+  - ✅ **DO**: Import all silent mode utilities together:
-  - ✅ **DO**: Wrap core function calls with silent mode: 
+    ```javascript
-  ```javascript
+    import { enableSilentMode, disableSilentMode, isSilentMode } from '../../../../scripts/modules/utils.js';
-  // Enable silent mode to prevent console logs from interfering with JSON response
+    ```
-  enableSilentMode();
+  - ✅ **DO**: Always use `isSilentMode()` function to check global silent mode status, never reference global variables.
+  - ✅ **DO**: Wrap core function calls **within direct functions** using `enableSilentMode()` and `disableSilentMode()` in a `try/finally` block if the core function might produce console output (like banners, spinners, direct `console.log`s) that isn't reliably controlled by an `outputFormat` parameter.
+    ```javascript
+    // Direct Function Example:
+    try {
+      // Prefer passing 'json' if the core function reliably handles it
+      const result = await coreFunction(...args, 'json'); 
+      // OR, if outputFormat is not enough/unreliable:
+      // enableSilentMode(); // Enable *before* the call
+      // const result = await coreFunction(...args);
+      // disableSilentMode(); // Disable *after* the call (typically in finally)
 
-  // Call the core function
+      return { success: true, data: result };
-  const result = await coreFunction(...);
+    } catch (error) {
+       log.error(`Error: ${error.message}`);
+       return { success: false, error: { message: error.message } };
+    } finally {
+       // If you used enable/disable, ensure disable is called here
+       // disableSilentMode(); 
+    }
+    ```
+  - ✅ **DO**: Core functions themselves *should* ideally check `outputFormat === 'text'` before displaying UI elements (banners, spinners, boxes) and use internal logging (`log`/`report`) that respects silent mode. The `enable/disableSilentMode` wrapper in the direct function is a safety net.
+  - ✅ **DO**: Handle mixed parameter/global silent mode correctly for functions accepting both (less common now, prefer `outputFormat`):
+    ```javascript
+    // Check both the passed parameter and global silent mode
+    const isSilent = silentMode || (typeof silentMode === 'undefined' && isSilentMode());
+    ```
+  - ❌ **DON'T**: Forget to disable silent mode in a `finally` block if you enabled it.
+  - ❌ **DON'T**: Access the global `silentMode` flag directly.
 
-  // Restore normal logging
+- **Debugging Strategy**:
-  disableSilentMode();
+  - ✅ **DO**: If an MCP tool fails with vague errors (e.g., JSON parsing issues like `Unexpected token ... is not valid JSON`), **try running the equivalent CLI command directly in the terminal** (e.g., `task-master expand --all`). CLI output often provides much more specific error messages (like missing function definitions or stack traces from the core logic) that pinpoint the root cause.
-  ```
+  - ❌ **DON'T**: Rely solely on MCP logs if the error is unclear; use the CLI as a complementary debugging tool for core logic issues.
-  - ✅ **DO**: Ensure silent mode is disabled in error handling:
-  ```javascript
-  try {
-    enableSilentMode();
-    // Core function call
-    disableSilentMode();
-  } catch (error) {
-    // Make sure to restore normal logging even if there's an error
-    disableSilentMode();
-    throw error; // Rethrow to be caught by outer catch block
-  }
-  ```
-  - ✅ **DO**: Add silent mode handling in all direct functions that call core functions
-  - ❌ **DON'T**: Forget to disable silent mode, which would suppress all future logs
-  - ❌ **DON'T**: Enable silent mode outside of direct functions in the MCP server
 
 ```javascript
 // 1. CORE LOGIC: Add function to appropriate module (example in task-manager.js)

.cursor/rules/taskmaster.mdc

@@ -10,6 +10,8 @@ This document provides a detailed reference for interacting with Taskmaster, cov
 
 **Note:** For interacting with Taskmaster programmatically or via integrated tools, using the **MCP tools is strongly recommended** due to better performance, structured data, and error handling. The CLI commands serve as a user-friendly alternative and fallback. See [`mcp.mdc`](mdc:.cursor/rules/mcp.mdc) for MCP implementation details and [`commands.mdc`](mdc:.cursor/rules/commands.mdc) for CLI implementation guidelines.
 
+**Important:** Several MCP tools involve AI processing and are long-running operations that may take up to a minute to complete. When using these tools, always inform users that the operation is in progress and to wait patiently for results. The AI-powered tools include: `parse_prd`, `analyze_project_complexity`, `update_subtask`, `update_task`, `update`, `expand_all`, `expand_task`, and `add_task`.
+
 ---
 
 ## Initialization & Setup
@@ -35,7 +37,7 @@ This document provides a detailed reference for interacting with Taskmaster, cov
     *   `addAliases`: `Add shell aliases (tm, taskmaster) (default: false).` (CLI: `--aliases`)
     *   `yes`: `Skip prompts and use defaults/provided arguments (default: false).` (CLI: `-y, --yes`)
 *   **Usage:** Run this once at the beginning of a new project, typically via an integrated tool like Cursor. Operates on the current working directory of the MCP server. 
-
+*   **Important:** Once complete, you *MUST* parse a prd in order to generate tasks. There will be no tasks files until then. The next step after initializing should be to create a PRD using the example PRD in scripts/example_prd.txt. 
 
 ### 2. Parse PRD (`parse_prd`)
 
@@ -49,6 +51,7 @@ This document provides a detailed reference for interacting with Taskmaster, cov
     *   `force`: `Use this to allow Taskmaster to overwrite an existing 'tasks.json' without asking for confirmation.` (CLI: `-f, --force`)
 *   **Usage:** Useful for bootstrapping a project from an existing requirements document.
 *   **Notes:** Task Master will strictly adhere to any specific requirements mentioned in the PRD (libraries, database schemas, frameworks, tech stacks, etc.) while filling in any gaps where the PRD isn't fully specified. Tasks are designed to provide the most direct implementation path while avoiding over-engineering.
+*   **Important:** This MCP tool makes AI calls and can take up to a minute to complete. Please inform users to hang tight while the operation is in progress. If the user does not have a PRD, suggest discussing their idea and then use the example PRD in scripts/example_prd.txt as a template for creating the PRD based on their idea, for use with parse-prd.
 
 ---
 
@@ -99,6 +102,7 @@ This document provides a detailed reference for interacting with Taskmaster, cov
     *   `priority`: `Set the priority for the new task ('high', 'medium', 'low'; default: 'medium').` (CLI: `--priority <priority>`)
     *   `file`: `Path to your Taskmaster 'tasks.json' file (default relies on auto-detection).` (CLI: `-f, --file <file>`)
 *   **Usage:** Quickly add newly identified tasks during development.
+*   **Important:** This MCP tool makes AI calls and can take up to a minute to complete. Please inform users to hang tight while the operation is in progress.
 
 ### 7. Add Subtask (`add_subtask`)
 
@@ -127,7 +131,8 @@ This document provides a detailed reference for interacting with Taskmaster, cov
     *   `prompt`: `Required. Explain the change or new context for Taskmaster to apply to the tasks (e.g., "We are now using React Query instead of Redux Toolkit for data fetching").` (CLI: `-p, --prompt <text>`)
     *   `research`: `Enable Taskmaster to use Perplexity AI for more informed updates based on external knowledge (requires PERPLEXITY_API_KEY).` (CLI: `-r, --research`)
     *   `file`: `Path to your Taskmaster 'tasks.json' file (default relies on auto-detection).` (CLI: `-f, --file <file>`)
-*   **Usage:** Handle significant implementation changes or pivots that affect multiple future tasks.
+*   **Usage:** Handle significant implementation changes or pivots that affect multiple future tasks. Example CLI: `task-master update --from='18' --prompt='Switching to React Query.\nNeed to refactor data fetching...'`
+*   **Important:** This MCP tool makes AI calls and can take up to a minute to complete. Please inform users to hang tight while the operation is in progress.
 
 ### 9. Update Task (`update_task`)
 
@@ -139,19 +144,21 @@ This document provides a detailed reference for interacting with Taskmaster, cov
     *   `prompt`: `Required. Explain the specific changes or provide the new information Taskmaster should incorporate into this task.` (CLI: `-p, --prompt <text>`)
     *   `research`: `Enable Taskmaster to use Perplexity AI for more informed updates (requires PERPLEXITY_API_KEY).` (CLI: `-r, --research`)
     *   `file`: `Path to your Taskmaster 'tasks.json' file (default relies on auto-detection).` (CLI: `-f, --file <file>`)
-*   **Usage:** Refine a specific task based on new understanding or feedback.
+*   **Usage:** Refine a specific task based on new understanding or feedback. Example CLI: `task-master update-task --id='15' --prompt='Clarification: Use PostgreSQL instead of MySQL.\nUpdate schema details...'`
+*   **Important:** This MCP tool makes AI calls and can take up to a minute to complete. Please inform users to hang tight while the operation is in progress.
 
 ### 10. Update Subtask (`update_subtask`)
 
 *   **MCP Tool:** `update_subtask`
 *   **CLI Command:** `task-master update-subtask [options]`
-*   **Description:** `Append timestamped notes or details to a specific Taskmaster subtask without overwriting existing content.`
+*   **Description:** `Append timestamped notes or details to a specific Taskmaster subtask without overwriting existing content. Intended for iterative implementation logging.`
 *   **Key Parameters/Options:**
     *   `id`: `Required. The specific ID of the Taskmaster subtask (e.g., '15.2') you want to add information to.` (CLI: `-i, --id <id>`)
-    *   `prompt`: `Required. Provide the information or notes Taskmaster should append to the subtask's details.` (CLI: `-p, --prompt <text>`)
+    *   `prompt`: `Required. Provide the information or notes Taskmaster should append to the subtask's details. Ensure this adds *new* information not already present.` (CLI: `-p, --prompt <text>`)
     *   `research`: `Enable Taskmaster to use Perplexity AI for more informed updates (requires PERPLEXITY_API_KEY).` (CLI: `-r, --research`)
     *   `file`: `Path to your Taskmaster 'tasks.json' file (default relies on auto-detection).` (CLI: `-f, --file <file>`)
-*   **Usage:** Add implementation notes, code snippets, or clarifications to a subtask during development.
+*   **Usage:** Add implementation notes, code snippets, or clarifications to a subtask during development. Before calling, review the subtask's current details to append only fresh insights, helping to build a detailed log of the implementation journey and avoid redundancy. Example CLI: `task-master update-subtask --id='15.2' --prompt='Discovered that the API requires header X.\nImplementation needs adjustment...'`
+*   **Important:** This MCP tool makes AI calls and can take up to a minute to complete. Please inform users to hang tight while the operation is in progress.
 
 ### 11. Set Task Status (`set_task_status`)
 
@@ -193,6 +200,7 @@ This document provides a detailed reference for interacting with Taskmaster, cov
     *   `force`: `Use this to make Taskmaster replace existing subtasks with newly generated ones.` (CLI: `--force`)
     *   `file`: `Path to your Taskmaster 'tasks.json' file (default relies on auto-detection).` (CLI: `-f, --file <file>`)
 *   **Usage:** Generate a detailed implementation plan for a complex task before starting coding.
+*   **Important:** This MCP tool makes AI calls and can take up to a minute to complete. Please inform users to hang tight while the operation is in progress.
 
 ### 14. Expand All Tasks (`expand_all`)
 
@@ -206,6 +214,7 @@ This document provides a detailed reference for interacting with Taskmaster, cov
     *   `force`: `Make Taskmaster replace existing subtasks.` (CLI: `--force`)
     *   `file`: `Path to your Taskmaster 'tasks.json' file (default relies on auto-detection).` (CLI: `-f, --file <file>`)
 *   **Usage:** Useful after initial task generation or complexity analysis to break down multiple tasks at once.
+*   **Important:** This MCP tool makes AI calls and can take up to a minute to complete. Please inform users to hang tight while the operation is in progress.
 
 ### 15. Clear Subtasks (`clear_subtasks`)
 
@@ -278,45 +287,67 @@ This document provides a detailed reference for interacting with Taskmaster, cov
 
 ## Analysis & Reporting
 
-### 21. Analyze Complexity (`analyze_complexity`)
+### 21. Analyze Project Complexity (`analyze_project_complexity`)
 
-*   **MCP Tool:** `analyze_complexity`
+*   **MCP Tool:** `analyze_project_complexity`
 *   **CLI Command:** `task-master analyze-complexity [options]`
-*   **Description:** `Let Taskmaster analyze the complexity of your tasks and generate a report with recommendations for which ones need breaking down.`
+*   **Description:** `Have Taskmaster analyze your tasks to determine their complexity and suggest which ones need to be broken down further.`
 *   **Key Parameters/Options:**
-    *   `output`: `Where Taskmaster should save the JSON complexity analysis report (default: 'scripts/task-complexity-report.json').` (CLI: `-o, --output <file>`)
+    *   `output`: `Where to save the complexity analysis report (default: 'scripts/task-complexity-report.json').` (CLI: `-o, --output <file>`)
-    *   `threshold`: `The minimum complexity score (1-10) for Taskmaster to recommend expanding a task.` (CLI: `-t, --threshold <number>`)
+    *   `threshold`: `The minimum complexity score (1-10) that should trigger a recommendation to expand a task.` (CLI: `-t, --threshold <number>`)
-    *   `research`: `Enable Taskmaster to use Perplexity AI for more informed complexity analysis (requires PERPLEXITY_API_KEY).` (CLI: `-r, --research`)
+    *   `research`: `Enable Perplexity AI for more accurate complexity analysis (requires PERPLEXITY_API_KEY).` (CLI: `-r, --research`)
     *   `file`: `Path to your Taskmaster 'tasks.json' file (default relies on auto-detection).` (CLI: `-f, --file <file>`)
-*   **Usage:** Identify which tasks are likely too large and need further breakdown before implementation.
+*   **Usage:** Used before breaking down tasks to identify which ones need the most attention.
+*   **Important:** This MCP tool makes AI calls and can take up to a minute to complete. Please inform users to hang tight while the operation is in progress.
 
-### 22. Complexity Report (`complexity_report`)
+### 22. View Complexity Report (`complexity_report`)
 
 *   **MCP Tool:** `complexity_report`
 *   **CLI Command:** `task-master complexity-report [options]`
-*   **Description:** `Display the Taskmaster task complexity analysis report generated by 'analyze-complexity'.`
+*   **Description:** `Display the task complexity analysis report in a readable format.`
 *   **Key Parameters/Options:**
-    *   `file`: `Path to the JSON complexity report file (default: 'scripts/task-complexity-report.json').` (CLI: `-f, --file <file>`)
+    *   `file`: `Path to the complexity report (default: 'scripts/task-complexity-report.json').` (CLI: `-f, --file <file>`)
-*   **Usage:** View the formatted results of the complexity analysis to guide task expansion.
+*   **Usage:** Review and understand the complexity analysis results after running analyze-complexity.
 
 ---
 
-## File Generation
+## File Management
 
 ### 23. Generate Task Files (`generate`)
 
 *   **MCP Tool:** `generate`
 *   **CLI Command:** `task-master generate [options]`
-*   **Description:** `Generate individual markdown files for each task and subtask defined in your Taskmaster 'tasks.json'.`
+*   **Description:** `Create or update individual Markdown files for each task based on your tasks.json.`
 *   **Key Parameters/Options:**
-    *   `file`: `Path to your Taskmaster 'tasks.json' file containing the task data (default relies on auto-detection).` (CLI: `-f, --file <file>`)
+    *   `output`: `The directory where Taskmaster should save the task files (default: in a 'tasks' directory).` (CLI: `-o, --output <directory>`)
-    *   `output`: `The directory where Taskmaster should save the generated markdown task files (default: 'tasks').` (CLI: `-o, --output <dir>`)
+    *   `file`: `Path to your Taskmaster 'tasks.json' file (default relies on auto-detection).` (CLI: `-f, --file <file>`)
-*   **Usage:** Create/update the individual `.md` files in the `tasks/` directory, useful for tracking changes in git or viewing tasks individually.
+*   **Usage:** Run this after making changes to tasks.json to keep individual task files up to date.
 
 ---
 
-## Configuration & Metadata
+## Environment Variables Configuration
 
--   **Environment Variables**: Taskmaster relies on environment variables for configuration (API keys, model preferences, default settings). See [`dev_workflow.mdc`](mdc:.cursor/rules/dev_workflow.mdc) or the project README for a list.
+Taskmaster's behavior can be customized via environment variables. These affect both CLI and MCP server operation:
--   **`tasks.json`**: The core data file containing the array of tasks and their details. See [`tasks.mdc`](mdc:.cursor/rules/tasks.mdc) for details.
+
--   **`task_xxx.md` files**: Individual markdown files generated by the `generate` command/tool, reflecting the content of `tasks.json`.
+*   **ANTHROPIC_API_KEY** (Required): Your Anthropic API key for Claude.
+*   **MODEL**: Claude model to use (default: `claude-3-opus-20240229`). 
+*   **MAX_TOKENS**: Maximum tokens for AI responses (default: 8192).
+*   **TEMPERATURE**: Temperature for AI model responses (default: 0.7).
+*   **DEBUG**: Enable debug logging (`true`/`false`, default: `false`).
+*   **LOG_LEVEL**: Console output level (`debug`, `info`, `warn`, `error`, default: `info`).
+*   **DEFAULT_SUBTASKS**: Default number of subtasks for `expand` (default: 5).
+*   **DEFAULT_PRIORITY**: Default priority for new tasks (default: `medium`).
+*   **PROJECT_NAME**: Project name used in metadata.
+*   **PROJECT_VERSION**: Project version used in metadata.
+*   **PERPLEXITY_API_KEY**: API key for Perplexity AI (for `--research` flags).
+*   **PERPLEXITY_MODEL**: Perplexity model to use (default: `sonar-medium-online`).
+
+Set these in your `.env` file in the project root or in your environment before running Taskmaster.
+
+---
+
+For implementation details:
+*   CLI commands: See [`commands.mdc`](mdc:.cursor/rules/commands.mdc)
+*   MCP server: See [`mcp.mdc`](mdc:.cursor/rules/mcp.mdc)
+*   Task structure: See [`tasks.mdc`](mdc:.cursor/rules/tasks.mdc)
+*   Workflow: See [`dev_workflow.mdc`](mdc:.cursor/rules/dev_workflow.mdc)

.cursor/rules/tests.mdc

@@ -5,6 +5,8 @@ globs: "**/*.test.js,tests/**/*"
 
 # Testing Guidelines for Task Master CLI
 
+*Note:* Never use asynchronous operations in tests. Always mock tests properly based on the way the tested functions are defined and used. Do not arbitrarily create tests. Based them on the low-level details and execution of the underlying code being tested. 
+
 ## Test Organization Structure
 
 - **Unit Tests** (See [`architecture.mdc`](mdc:.cursor/rules/architecture.mdc) for module breakdown)
@@ -88,6 +90,122 @@ describe('Feature or Function Name', () => {
 });
 ```
 
+## Commander.js Command Testing Best Practices
+
+When testing CLI commands built with Commander.js, several special considerations must be made to avoid common pitfalls:
+
+- **Direct Action Handler Testing**
+  - ✅ **DO**: Test the command action handlers directly rather than trying to mock the entire Commander.js chain
+  - ✅ **DO**: Create simplified test-specific implementations of command handlers that match the original behavior
+  - ✅ **DO**: Explicitly handle all options, including defaults and shorthand flags (e.g., `-p` for `--prompt`)
+  - ✅ **DO**: Include null/undefined checks in test implementations for parameters that might be optional
+  - ✅ **DO**: Use fixtures from `tests/fixtures/` for consistent sample data across tests
+  
+  ```javascript
+  // ✅ DO: Create a simplified test version of the command handler
+  const testAddTaskAction = async (options) => {
+    options = options || {}; // Ensure options aren't undefined
+    
+    // Validate parameters
+    const isManualCreation = options.title && options.description;
+    const prompt = options.prompt || options.p; // Handle shorthand flags
+    
+    if (!prompt && !isManualCreation) {
+      throw new Error('Expected error message');
+    }
+    
+    // Call the mocked task manager
+    return mockTaskManager.addTask(/* parameters */);
+  };
+  
+  test('should handle required parameters correctly', async () => {
+    // Call the test implementation directly
+    await expect(async () => {
+      await testAddTaskAction({ file: 'tasks.json' });
+    }).rejects.toThrow('Expected error message');
+  });
+  ```
+
+- **Commander Chain Mocking (If Necessary)**
+  - ✅ **DO**: Mock ALL chainable methods (`option`, `argument`, `action`, `on`, etc.)
+  - ✅ **DO**: Return `this` (or the mock object) from all chainable method mocks
+  - ✅ **DO**: Remember to mock not only the initial object but also all objects returned by methods
+  - ✅ **DO**: Implement a mechanism to capture the action handler for direct testing
+  
+  ```javascript
+  // If you must mock the Commander.js chain:
+  const mockCommand = {
+    command: jest.fn().mockReturnThis(),
+    description: jest.fn().mockReturnThis(),
+    option: jest.fn().mockReturnThis(),
+    argument: jest.fn().mockReturnThis(), // Don't forget this one
+    action: jest.fn(fn => { 
+      actionHandler = fn; // Capture the handler for testing
+      return mockCommand; 
+    }),
+    on: jest.fn().mockReturnThis() // Don't forget this one
+  };
+  ```
+
+- **Parameter Handling**
+  - ✅ **DO**: Check for both main flag and shorthand flags (e.g., `prompt` and `p`)
+  - ✅ **DO**: Handle parameters like Commander would (comma-separated lists, etc.)
+  - ✅ **DO**: Set proper default values as defined in the command
+  - ✅ **DO**: Validate that required parameters are actually required in tests
+  
+  ```javascript
+  // Parse dependencies like Commander would
+  const dependencies = options.dependencies 
+    ? options.dependencies.split(',').map(id => id.trim())
+    : [];
+  ```
+
+- **Environment and Session Handling**
+  - ✅ **DO**: Properly mock session objects when required by functions
+  - ✅ **DO**: Reset environment variables between tests if modified
+  - ✅ **DO**: Use a consistent pattern for environment-dependent tests
+  
+  ```javascript
+  // Session parameter mock pattern
+  const sessionMock = { session: process.env };
+  
+  // In test:
+  expect(mockAddTask).toHaveBeenCalledWith(
+    expect.any(String),
+    'Test prompt',
+    [],
+    'medium',
+    sessionMock,
+    false,
+    null,
+    null
+  );
+  ```
+
+- **Common Pitfalls to Avoid**
+  - ❌ **DON'T**: Try to use the real action implementation without proper mocking
+  - ❌ **DON'T**: Mock Commander partially - either mock it completely or test the action directly
+  - ❌ **DON'T**: Forget to handle optional parameters that may be undefined
+  - ❌ **DON'T**: Neglect to test shorthand flag functionality (e.g., `-p`, `-r`)
+  - ❌ **DON'T**: Create circular dependencies in your test mocks
+  - ❌ **DON'T**: Access variables before initialization in your test implementations
+  - ❌ **DON'T**: Include actual command execution in unit tests
+  - ❌ **DON'T**: Overwrite the same file path in multiple tests
+  
+  ```javascript
+  // ❌ DON'T: Create circular references in mocks
+  const badMock = {
+    method: jest.fn().mockImplementation(() => badMock.method())
+  };
+  
+  // ❌ DON'T: Access uninitialized variables
+  const badImplementation = () => {
+    const result = uninitialized;
+    let uninitialized = 'value';
+    return result;
+  };
+  ```
+
 ## Jest Module Mocking Best Practices
 
 - **Mock Hoisting Behavior**
@@ -552,6 +670,102 @@ npm test -- -t "pattern to match"
   });
   ```
 
+## Testing AI Service Integrations
+
+- **DO NOT import real AI service clients**
+  - ❌ DON'T: Import actual AI clients from their libraries
+  - ✅ DO: Create fully mocked versions that return predictable responses
+
+  ```javascript
+  // ❌ DON'T: Import and instantiate real AI clients
+  import { Anthropic } from '@anthropic-ai/sdk';
+  const anthropic = new Anthropic({ apiKey: process.env.ANTHROPIC_API_KEY });
+
+  // ✅ DO: Mock the entire module with controlled behavior
+  jest.mock('@anthropic-ai/sdk', () => ({
+    Anthropic: jest.fn().mockImplementation(() => ({
+      messages: {
+        create: jest.fn().mockResolvedValue({
+          content: [{ type: 'text', text: 'Mocked AI response' }]
+        })
+      }
+    }))
+  }));
+  ```
+
+- **DO NOT rely on environment variables for API keys**
+  - ❌ DON'T: Assume environment variables are set in tests
+  - ✅ DO: Set mock environment variables in test setup
+
+  ```javascript
+  // In tests/setup.js or at the top of test file
+  process.env.ANTHROPIC_API_KEY = 'test-mock-api-key-for-tests';
+  process.env.PERPLEXITY_API_KEY = 'test-mock-perplexity-key-for-tests';
+  ```
+
+- **DO NOT use real AI client initialization logic**
+  - ❌ DON'T: Use code that attempts to initialize or validate real AI clients
+  - ✅ DO: Create test-specific paths that bypass client initialization
+
+  ```javascript
+  // ❌ DON'T: Test functions that require valid AI client initialization
+  // This will fail without proper API keys or network access
+  test('should use AI client', async () => {
+    const result = await functionThatInitializesAIClient();
+    expect(result).toBeDefined();
+  });
+
+  // ✅ DO: Test with bypassed initialization or manual task paths
+  test('should handle manual task creation without AI', () => {
+    // Using a path that doesn't require AI client initialization
+    const result = addTaskDirect({ 
+      title: 'Manual Task', 
+      description: 'Test Description'
+    }, mockLogger);
+    
+    expect(result.success).toBe(true);
+  });
+  ```
+
+## Testing Asynchronous Code
+
+- **DO NOT rely on asynchronous operations in tests**
+  - ❌ DON'T: Use real async/await or Promise resolution in tests
+  - ✅ DO: Make all mocks return synchronous values when possible
+
+  ```javascript
+  // ❌ DON'T: Use real async functions that might fail unpredictably
+  test('should handle async operation', async () => {
+    const result = await realAsyncFunction(); // Can time out or fail for external reasons
+    expect(result).toBe(expectedValue);
+  });
+
+  // ✅ DO: Make async operations synchronous in tests
+  test('should handle operation', () => {
+    mockAsyncFunction.mockReturnValue({ success: true, data: 'test' });
+    const result = functionUnderTest();
+    expect(result).toEqual({ success: true, data: 'test' });
+  });
+  ```
+
+- **DO NOT test exact error messages**
+  - ❌ DON'T: Assert on exact error message text that might change
+  - ✅ DO: Test for error presence and general properties
+
+  ```javascript
+  // ❌ DON'T: Test for exact error message text
+  expect(result.error).toBe('Could not connect to API: Network error');
+
+  // ✅ DO: Test for general error properties or message patterns
+  expect(result.success).toBe(false);
+  expect(result.error).toContain('Could not connect');
+  // Or even better:
+  expect(result).toMatchObject({ 
+    success: false,
+    error: expect.stringContaining('connect')
+  });
+  ```
+
 ## Reliable Testing Techniques
 
 - **Create Simplified Test Functions**
@@ -564,99 +778,125 @@ npm test -- -t "pattern to match"
   const setTaskStatus = async (taskId, newStatus) => {
     const tasksPath = 'tasks/tasks.json';
     const data = await readJSON(tasksPath);
-    // Update task status logic
+    // [implementation]
     await writeJSON(tasksPath, data);
-    return data;
+    return { success: true };
   };
   
-  // Test-friendly simplified function (easy to test)
+  // Test-friendly version (easier to test)
-  const testSetTaskStatus = (tasksData, taskIdInput, newStatus) => {
+  const updateTaskStatus = (tasks, taskId, newStatus) => {
-    // Same core logic without file operations
+    // Pure logic without side effects
-    // Update task status logic on provided tasksData object
+    const updatedTasks = [...tasks];
-    return tasksData; // Return updated data for assertions
+    const taskIndex = findTaskById(updatedTasks, taskId);
+    if (taskIndex === -1) return { success: false, error: 'Task not found' };
+    updatedTasks[taskIndex].status = newStatus;
+    return { success: true, tasks: updatedTasks };
   };
   ```
 
-- **Avoid Real File System Operations**
-  - Never write to real files during tests
-  - Create test-specific versions of file operation functions
-  - Mock all file system operations including read, write, exists, etc.
-  - Verify function behavior using the in-memory data structures
-  
-  ```javascript
-  // Mock file operations
-  const mockReadJSON = jest.fn();
-  const mockWriteJSON = jest.fn();
-  
-  jest.mock('../../scripts/modules/utils.js', () => ({
-    readJSON: mockReadJSON,
-    writeJSON: mockWriteJSON,
-  }));
-  
-  test('should update task status correctly', () => {
-    // Setup mock data
-    const testData = JSON.parse(JSON.stringify(sampleTasks));
-    mockReadJSON.mockReturnValue(testData);
-    
-    // Call the function that would normally modify files
-    const result = testSetTaskStatus(testData, '1', 'done');
-    
-    // Assert on the in-memory data structure
-    expect(result.tasks[0].status).toBe('done');
-  });
-  ```
-
-- **Data Isolation Between Tests**
-  - Always create fresh copies of test data for each test
-  - Use `JSON.parse(JSON.stringify(original))` for deep cloning
-  - Reset all mocks before each test with `jest.clearAllMocks()`
-  - Avoid state that persists between tests
-  
-  ```javascript
-  beforeEach(() => {
-    jest.clearAllMocks();
-    // Deep clone the test data
-    testTasksData = JSON.parse(JSON.stringify(sampleTasks));
-  });
-  ```
-
-- **Test All Path Variations**
-  - Regular tasks and subtasks
-  - Single items and multiple items
-  - Success paths and error paths
-  - Edge cases (empty data, invalid inputs, etc.)
-  
-  ```javascript
-  // Multiple test cases covering different scenarios
-  test('should update regular task status', () => {
-    /* test implementation */
-  });
-  
-  test('should update subtask status', () => {
-    /* test implementation */
-  });
-  
-  test('should update multiple tasks when given comma-separated IDs', () => {
-    /* test implementation */
-  });
-  
-  test('should throw error for non-existent task ID', () => {
-    /* test implementation */
-  });
-  ```
-
-- **Stabilize Tests With Predictable Input/Output**
-  - Use consistent, predictable test fixtures
-  - Avoid random values or time-dependent data
-  - Make tests deterministic for reliable CI/CD
-  - Control all variables that might affect test outcomes
-  
-  ```javascript
-  // Use a specific known date instead of current date
-  const fixedDate = new Date('2023-01-01T12:00:00Z');
-  jest.spyOn(global, 'Date').mockImplementation(() => fixedDate);
-  ```
-
 See [tests/README.md](mdc:tests/README.md) for more details on the testing approach.
 
 Refer to [jest.config.js](mdc:jest.config.js) for Jest configuration options.
+
+## Variable Hoisting and Module Initialization Issues
+
+When testing ES modules or working with complex module imports, you may encounter variable hoisting and initialization issues. These can be particularly tricky to debug and often appear as "Cannot access 'X' before initialization" errors.
+
+- **Understanding Module Initialization Order**
+  - ✅ **DO**: Declare and initialize global variables at the top of modules
+  - ✅ **DO**: Use proper function declarations to avoid hoisting issues
+  - ✅ **DO**: Initialize variables before they are referenced, especially in imported modules
+  - ✅ **DO**: Be aware that imports are hoisted to the top of the file
+  
+  ```javascript
+  // ✅ DO: Define global state variables at the top of the module
+  let silentMode = false; // Declare and initialize first
+  
+  const CONFIG = { /* configuration */ };
+  
+  function isSilentMode() {
+    return silentMode; // Reference variable after it's initialized
+  }
+  
+  function log(level, message) {
+    if (isSilentMode()) return; // Use the function instead of accessing variable directly
+    // ...
+  }
+  ```
+
+- **Testing Modules with Initialization-Dependent Functions**
+  - ✅ **DO**: Create test-specific implementations that initialize all variables correctly
+  - ✅ **DO**: Use factory functions in mocks to ensure proper initialization order
+  - ✅ **DO**: Be careful with how you mock or stub functions that depend on module state
+  
+  ```javascript
+  // ✅ DO: Test-specific implementation that avoids initialization issues
+  const testLog = (level, ...args) => {
+    // Local implementation with proper initialization
+    const isSilent = false; // Explicit initialization
+    if (isSilent) return;
+    // Test implementation...
+  };
+  ```
+
+- **Common Hoisting-Related Errors to Avoid**
+  - ❌ **DON'T**: Reference variables before their declaration in module scope
+  - ❌ **DON'T**: Create circular dependencies between modules
+  - ❌ **DON'T**: Rely on variable initialization order across module boundaries
+  - ❌ **DON'T**: Define functions that use hoisted variables before they're initialized
+  
+  ```javascript
+  // ❌ DON'T: Create reference-before-initialization patterns
+  function badFunction() {
+    if (silentMode) { /* ... */ } // ReferenceError if silentMode is declared later
+  }
+  
+  let silentMode = false;
+  
+  // ❌ DON'T: Create cross-module references that depend on initialization order
+  // module-a.js
+  import { getSetting } from './module-b.js';
+  export const config = { value: getSetting() };
+  
+  // module-b.js
+  import { config } from './module-a.js';
+  export function getSetting() {
+    return config.value; // Circular dependency causing initialization issues
+  }
+  ```
+
+- **Dynamic Imports as a Solution**
+  - ✅ **DO**: Use dynamic imports (`import()`) to avoid initialization order issues
+  - ✅ **DO**: Structure modules to avoid circular dependencies that cause initialization issues
+  - ✅ **DO**: Consider factory functions for modules with complex state
+  
+  ```javascript
+  // ✅ DO: Use dynamic imports to avoid initialization issues
+  async function getTaskManager() {
+    return import('./task-manager.js');
+  }
+  
+  async function someFunction() {
+    const taskManager = await getTaskManager();
+    return taskManager.someMethod();
+  }
+  ```
+
+- **Testing Approach for Modules with Initialization Issues**
+  - ✅ **DO**: Create self-contained test implementations rather than using real implementations
+  - ✅ **DO**: Mock dependencies at module boundaries instead of trying to mock deep dependencies
+  - ✅ **DO**: Isolate module-specific state in tests
+  
+  ```javascript
+  // ✅ DO: Create isolated test implementation instead of reusing module code
+  test('should log messages when not in silent mode', () => {
+    // Local test implementation instead of importing from module
+    const testLog = (level, message) => {
+      if (false) return; // Always non-silent for this test
+      mockConsole(level, message);
+    };
+    
+    testLog('info', 'test message');
+    expect(mockConsole).toHaveBeenCalledWith('info', 'test message');
+  });
+  ``` 

.cursor/rules/utilities.mdc

@@ -109,6 +109,29 @@ alwaysApply: false
   - ✅ DO: Use appropriate icons for different log levels
   - ✅ DO: Respect the configured log level
   - ❌ DON'T: Add direct console.log calls outside the logging utility
+  - **Note on Passed Loggers**: When a logger object (like the FastMCP `log` object) is passed *as a parameter* (e.g., as `mcpLog`) into core Task Master functions, the receiving function often expects specific methods (`.info`, `.warn`, `.error`, etc.) to be directly callable on that object (e.g., `mcpLog[level](...)`). If the passed logger doesn't have this exact structure, a wrapper object may be needed. See the **Handling Logging Context (`mcpLog`)** section in [`mcp.mdc`](mdc:.cursor/rules/mcp.mdc) for the standard pattern used in direct functions.
+
+- **Logger Wrapper Pattern**: 
+  - ✅ DO: Use the logger wrapper pattern when passing loggers to prevent `mcpLog[level] is not a function` errors:
+  ```javascript
+  // Standard logWrapper pattern to wrap FastMCP's log object
+  const logWrapper = {
+    info: (message, ...args) => log.info(message, ...args),
+    warn: (message, ...args) => log.warn(message, ...args),
+    error: (message, ...args) => log.error(message, ...args),
+    debug: (message, ...args) => log.debug && log.debug(message, ...args),
+    success: (message, ...args) => log.info(message, ...args) // Map success to info
+  };
+  
+  // Pass this wrapper as mcpLog to ensure consistent method availability
+  // This also ensures output format is set to 'json' in many core functions
+  const options = { mcpLog: logWrapper, session };
+  ```
+  - ✅ DO: Implement this pattern in any direct function that calls core functions expecting `mcpLog`
+  - ✅ DO: Use this solution in conjunction with silent mode for complete output control
+  - ❌ DON'T: Pass the FastMCP `log` object directly as `mcpLog` to core functions
+  - **Important**: This pattern has successfully fixed multiple issues in MCP tools (e.g., `update-task`, `update-subtask`) where using or omitting `mcpLog` incorrectly led to runtime errors or JSON parsing failures.
+  - For complete implementation details, see the **Handling Logging Context (`mcpLog`)** section in [`mcp.mdc`](mdc:.cursor/rules/mcp.mdc).
 
   ```javascript
   // ✅ DO: Implement a proper logging utility
@@ -135,6 +158,107 @@ alwaysApply: false
   }
   ```
 
+## Silent Mode Utilities (in `scripts/modules/utils.js`)
+
+- **Silent Mode Control**:
+  - ✅ DO: Use the exported silent mode functions rather than accessing global variables
+  - ✅ DO: Always use `isSilentMode()` to check the current silent mode state
+  - ✅ DO: Ensure silent mode is disabled in a `finally` block to prevent it from staying enabled
+  - ❌ DON'T: Access the global `silentMode` variable directly
+  - ❌ DON'T: Forget to disable silent mode after enabling it
+
+  ```javascript
+  // ✅ DO: Use the silent mode control functions properly
+  
+  // Example of proper implementation in utils.js:
+  
+  // Global silent mode flag (private to the module)
+  let silentMode = false;
+  
+  // Enable silent mode
+  function enableSilentMode() {
+    silentMode = true;
+  }
+  
+  // Disable silent mode
+  function disableSilentMode() {
+    silentMode = false;
+  }
+  
+  // Check if silent mode is enabled
+  function isSilentMode() {
+    return silentMode;
+  }
+  
+  // Example of proper usage in another module:
+  import { enableSilentMode, disableSilentMode, isSilentMode } from './utils.js';
+  
+  // Check current status
+  if (!isSilentMode()) {
+    console.log('Silent mode is not enabled');
+  }
+  
+  // Use try/finally pattern to ensure silent mode is disabled
+  try {
+    enableSilentMode();
+    // Do something that should suppress console output
+    performOperation();
+  } finally {
+    disableSilentMode();
+  }
+  ```
+
+- **Integration with Logging**:
+  - ✅ DO: Make the `log` function respect silent mode
+  ```javascript
+  function log(level, ...args) {
+    // Skip logging if silent mode is enabled
+    if (isSilentMode()) {
+      return;
+    }
+    
+    // Rest of logging logic...
+  }
+  ```
+
+- **Common Patterns for Silent Mode**:
+  - ✅ DO: In **direct functions** (`mcp-server/src/core/direct-functions/*`) that call **core functions** (`scripts/modules/*`), ensure console output from the core function is suppressed to avoid breaking MCP JSON responses.
+    - **Preferred Method**: Update the core function to accept an `outputFormat` parameter (e.g., `outputFormat = 'text'`) and make it check `outputFormat === 'text'` before displaying any UI elements (banners, spinners, boxes, direct `console.log`s). Pass `'json'` from the direct function.
+    - **Necessary Fallback/Guarantee**: If the core function *cannot* be modified or its output suppression via `outputFormat` is unreliable, **wrap the core function call within the direct function** using `enableSilentMode()` and `disableSilentMode()` in a `try/finally` block. This acts as a safety net.
+  ```javascript
+  // Example in a direct function
+  export async function someOperationDirect(args, log) {
+    let result;
+    const tasksPath = findTasksJsonPath(args, log); // Get path first
+    
+    // Option 1: Core function handles 'json' format (Preferred)
+    try {
+      result = await coreFunction(tasksPath, ...otherArgs, 'json'); // Pass 'json'
+      return { success: true, data: result, fromCache: false };
+    } catch (error) {
+      // Handle error...
+    }
+
+    // Option 2: Core function output unreliable (Fallback/Guarantee)
+    try {
+      enableSilentMode(); // Enable before call
+      result = await coreFunction(tasksPath, ...otherArgs); // Call without format param
+    } catch (error) {
+      // Handle error...
+      log.error(`Failed: ${error.message}`);
+      return { success: false, error: { /* ... */ } };
+    } finally {
+      disableSilentMode(); // ALWAYS disable in finally
+    }
+    return { success: true, data: result, fromCache: false }; // Assuming success if no error caught
+  }
+  ```
+  - ✅ DO: For functions that accept a silent mode parameter but also need to check global state (less common):
+  ```javascript
+  // Check both the passed parameter and global silent mode
+  const isSilent = options.silentMode || (typeof options.silentMode === 'undefined' && isSilentMode());
+  ```
+
 ## File Operations (in `scripts/modules/utils.js`)
 
 - **Error Handling**:

.env.example

@@ -1,20 +1,20 @@
 # API Keys (Required)
-ANTHROPIC_API_KEY=your_anthropic_api_key_here  # Format: sk-ant-api03-...
+ANTHROPIC_API_KEY=your_anthropic_api_key_here       # Format: sk-ant-api03-...
-PERPLEXITY_API_KEY=your_perplexity_api_key_here  # Format: pplx-...
+PERPLEXITY_API_KEY=your_perplexity_api_key_here     # Format: pplx-...
 
 # Model Configuration
-MODEL=claude-3-7-sonnet-20250219  # Recommended models: claude-3-7-sonnet-20250219, claude-3-opus-20240229
+MODEL=claude-3-7-sonnet-20250219                    # Recommended models: claude-3-7-sonnet-20250219, claude-3-opus-20240229
-PERPLEXITY_MODEL=sonar-pro  # Perplexity model for research-backed subtasks
+PERPLEXITY_MODEL=sonar-pro                          # Perplexity model for research-backed subtasks
-MAX_TOKENS=64000                   # Maximum tokens for model responses
+MAX_TOKENS=64000                                    # Maximum tokens for model responses
-TEMPERATURE=0.4                   # Temperature for model responses (0.0-1.0)
+TEMPERATURE=0.2                                     # Temperature for model responses (0.0-1.0)
 
 # Logging Configuration
-DEBUG=false                       # Enable debug logging (true/false)
+DEBUG=false                                         # Enable debug logging (true/false)
-LOG_LEVEL=info                    # Log level (debug, info, warn, error)
+LOG_LEVEL=info                                      # Log level (debug, info, warn, error)
 
 # Task Generation Settings
-DEFAULT_SUBTASKS=4                # Default number of subtasks when expanding
+DEFAULT_SUBTASKS=5                                  # Default number of subtasks when expanding
-DEFAULT_PRIORITY=medium           # Default priority for generated tasks (high, medium, low)
+DEFAULT_PRIORITY=medium                             # Default priority for generated tasks (high, medium, low)
 
 # Project Metadata (Optional)
-PROJECT_NAME=Your Project Name    # Override default project name in tasks.json
+    PROJECT_NAME=Your Project Name                  # Override default project name in tasks.json

.github/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,39 @@
+---
+name: Bug report
+about: Create a report to help us improve
+title: 'bug: '
+labels: bug
+assignees: ''
+---
+
+### Description
+
+Detailed description of the problem, including steps to reproduce the issue.
+
+### Steps to Reproduce
+
+1. Step-by-step instructions to reproduce the issue
+2. Include command examples or UI interactions
+
+### Expected Behavior
+
+Describe clearly what the expected outcome or behavior should be.
+
+### Actual Behavior
+
+Describe clearly what the actual outcome or behavior is.
+
+### Screenshots or Logs
+
+Provide screenshots, logs, or error messages if applicable.
+
+### Environment
+
+- Task Master version:
+- Node.js version:
+- Operating system:
+- IDE (if applicable):
+
+### Additional Context
+
+Any additional information or context that might help diagnose the issue.

.github/ISSUE_TEMPLATE/enhancements---feature-requests.md

@@ -0,0 +1,51 @@
+---
+name: Enhancements & feature requests
+about: Suggest an idea for this project
+title: 'feat: '
+labels: enhancement
+assignees: ''
+---
+
+> "Direct quote or clear summary of user request or need or user story."
+
+### Motivation
+
+Detailed explanation of why this feature is important. Describe the problem it solves or the benefit it provides.
+
+### Proposed Solution
+
+Clearly describe the proposed feature, including:
+
+- High-level overview of the feature
+- Relevant technologies or integrations
+- How it fits into the existing workflow or architecture
+
+### High-Level Workflow
+
+1. Step-by-step description of how the feature will be implemented
+2. Include necessary intermediate milestones
+
+### Key Elements
+
+- Bullet-point list of technical or UX/UI enhancements
+- Mention specific integrations or APIs
+- Highlight changes needed in existing data models or commands
+
+### Example Workflow
+
+Provide a clear, concrete example demonstrating the feature:
+
+```shell
+$ task-master [action]
+→ Expected response/output
+```
+
+### Implementation Considerations
+
+- Dependencies on external components or APIs
+- Backward compatibility requirements
+- Potential performance impacts or resource usage
+
+### Out of Scope (Future Considerations)
+
+Clearly list any features or improvements not included but relevant for future iterations.

.github/ISSUE_TEMPLATE/feedback.md

@@ -0,0 +1,31 @@
+---
+name: Feedback
+about: Give us specific feedback on the product/approach/tech
+title: 'feedback: '
+labels: feedback
+assignees: ''
+---
+
+### Feedback Summary
+
+Provide a clear summary or direct quote from user feedback.
+
+### User Context
+
+Explain the user's context or scenario in which this feedback was provided.
+
+### User Impact
+
+Describe how this feedback affects the user experience or workflow.
+
+### Suggestions
+
+Provide any initial thoughts, potential solutions, or improvements based on the feedback.
+
+### Relevant Screenshots or Examples
+
+Attach screenshots, logs, or examples that illustrate the feedback.
+
+### Additional Notes
+
+Any additional context or related information.

.github/workflows/ci.yml

@@ -0,0 +1,95 @@
+name: CI
+
+on:
+  push:
+    branches:
+      - main
+      - next
+  pull_request:
+    branches:
+      - main
+      - next
+
+permissions:
+  contents: read
+
+jobs:
+  setup:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 20
+          cache: 'npm'
+
+      - name: Install Dependencies
+        id: install
+        run: npm ci
+        timeout-minutes: 2
+
+      - name: Cache node_modules
+        uses: actions/cache@v4
+        with:
+          path: node_modules
+          key: ${{ runner.os }}-node-modules-${{ hashFiles('**/package-lock.json') }}
+
+  format-check:
+    needs: setup
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 20
+
+      - name: Restore node_modules
+        uses: actions/cache@v4
+        with:
+          path: node_modules
+          key: ${{ runner.os }}-node-modules-${{ hashFiles('**/package-lock.json') }}
+
+      - name: Format Check
+        run: npm run format-check
+        env:
+          FORCE_COLOR: 1
+
+  test:
+    needs: setup
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 20
+
+      - name: Restore node_modules
+        uses: actions/cache@v4
+        with:
+          path: node_modules
+          key: ${{ runner.os }}-node-modules-${{ hashFiles('**/package-lock.json') }}
+
+      - name: Run Tests
+        run: |
+          npm run test:coverage -- --coverageThreshold '{"global":{"branches":0,"functions":0,"lines":0,"statements":0}}' --detectOpenHandles --forceExit
+        env:
+          NODE_ENV: test
+          CI: true
+          FORCE_COLOR: 1
+        timeout-minutes: 10
+
+      - name: Upload Test Results
+        if: always()
+        uses: actions/upload-artifact@v4
+        with:
+          name: test-results
+          path: |
+            test-results
+            coverage
+            junit.xml
+          retention-days: 30

.github/workflows/release.yml

@@ -3,7 +3,6 @@ on:
   push:
     branches:
       - main
-      - next
 jobs:
   release:
     runs-on: ubuntu-latest
@@ -15,9 +14,21 @@ jobs:
       - uses: actions/setup-node@v4
         with:
           node-version: 20
+          cache: 'npm'
+
+      - name: Cache node_modules
+        uses: actions/cache@v4
+        with:
+          path: |
+            node_modules
+            */*/node_modules
+          key: ${{ runner.os }}-node-${{ hashFiles('**/package-lock.json') }}
+          restore-keys: |
+            ${{ runner.os }}-node-
 
       - name: Install Dependencies
-        run: npm install
+        run: npm ci
+        timeout-minutes: 2
 
       - name: Create Release Pull Request or Publish to npm
         uses: changesets/action@v1

.gitignore

@@ -9,6 +9,9 @@ jspm_packages/
 .env.test.local
 .env.production.local
 
+# Cursor configuration -- might have ENV variables. Included by default
+# .cursor/mcp.json
+
 # Logs
 logs
 *.log

.prettierignore

@@ -0,0 +1,7 @@
+# Ignore artifacts:
+build
+coverage
+.changeset
+tasks
+package-lock.json
+tests/fixture/*.json

.prettierrc

@@ -0,0 +1,11 @@
+{
+	"printWidth": 80,
+	"tabWidth": 2,
+	"useTabs": true,
+	"semi": true,
+	"singleQuote": true,
+	"trailingComma": "none",
+	"bracketSpacing": true,
+	"arrowParens": "always",
+	"endOfLine": "lf"
+}

.vscode/extensions.json

@@ -0,0 +1,3 @@
+{
+	"recommendations": ["esbenp.prettier-vscode"]
+}

CHANGELOG.md

@@ -1,5 +1,76 @@
 # task-master-ai
 
+## 0.11.0
+
+### Minor Changes
+
+- [#71](https://github.com/eyaltoledano/claude-task-master/pull/71) [`7141062`](https://github.com/eyaltoledano/claude-task-master/commit/71410629ba187776d92a31ea0729b2ff341b5e38) Thanks [@eyaltoledano](https://github.com/eyaltoledano)! - - **Easier Ways to Use Taskmaster (CLI & MCP):**
+  - You can now use Taskmaster either by installing it as a standard command-line tool (`task-master`) or as an MCP server directly within integrated development tools like Cursor (using its built-in features). **This makes Taskmaster accessible regardless of your preferred workflow.**
+  - Setting up a new project is simpler in integrated tools, thanks to the new `initialize_project` capability.
+  - **Complete MCP Implementation:**
+    - NOTE: Many MCP clients charge on a per tool basis. In that regard, the most cost-efficient way to use Taskmaster is through the CLI directly. Otherwise, the MCP offers the smoothest and most recommended user experience.
+    - All MCP tools now follow a standardized output format that mimicks RESTful API responses. They are lean JSON responses that are context-efficient. This is a net improvement over the last version which sent the whole CLI output directly, which needlessly wasted tokens.
+    - Added a `remove-task` command to permanently delete tasks you no longer need.
+    - Many new MCP tools are available for managing tasks (updating details, adding/removing subtasks, generating task files, setting status, finding the next task, breaking down complex tasks, handling dependencies, analyzing complexity, etc.), usable both from the command line and integrated tools. **(See the `taskmaster.mdc` reference guide and improved readme for a full list).**
+  - **Better Task Tracking:**
+    - Added a "cancelled" status option for tasks, providing more ways to categorize work.
+  - **Smoother Experience in Integrated Tools:**
+    - Long-running operations (like breaking down tasks or analysis) now run in the background **via an Async Operation Manager** with progress updates, so you know what's happening without waiting and can check status later.
+  - **Improved Documentation:**
+    - Added a comprehensive reference guide (`taskmaster.mdc`) detailing all commands and tools with examples, usage tips, and troubleshooting info. This is mostly for use by the AI but can be useful for human users as well.
+    - Updated the main README with clearer instructions and added a new tutorial/examples guide.
+    - Added documentation listing supported integrated tools (like Cursor).
+  - **Increased Stability & Reliability:**
+    - Using Taskmaster within integrated tools (like Cursor) is now **more stable and the recommended approach.**
+    - Added automated testing (CI) to catch issues earlier, leading to a more reliable tool.
+    - Fixed release process issues to ensure users get the correct package versions when installing or updating via npm.
+  - **Better Command-Line Experience:**
+    - Fixed bugs in the `expand-all` command that could cause **NaN errors or JSON formatting issues (especially when using `--research`).**
+    - Fixed issues with parameter validation in the `analyze-complexity` command (specifically related to the `threshold` parameter).
+    - Made the `add-task` command more consistent by adding standard flags like `--title`, `--description` for manual task creation so you don't have to use `--prompt` and can quickly drop new ideas and stay in your flow.
+    - Improved error messages for incorrect commands or flags, making them easier to understand.
+    - Added confirmation warnings before permanently deleting tasks (`remove-task`) to prevent mistakes. There's a known bug for deleting multiple tasks with comma-separated values. It'll be fixed next release.
+    - Renamed some background tool names used by integrated tools (e.g., `list-tasks` is now `get_tasks`) to be more intuitive if seen in logs or AI interactions.
+    - Smoother project start: **Improved the guidance provided to AI assistants immediately after setup** (related to `init` and `parse-prd` steps). This ensures the AI doesn't go on a tangent deciding its own workflow, and follows the exact process outlined in the Taskmaster workflow.
+  - **Clearer Error Messages:**
+    - When generating subtasks fails, error messages are now clearer, **including specific task IDs and potential suggestions.**
+    - AI fallback from Claude to Perplexity now also works the other way around. If Perplexity is down, will switch to Claude.
+  - **Simplified Setup & Configuration:**
+    - Made it clearer how to configure API keys depending on whether you're using the command-line tool (`.env` file) or an integrated tool (`.cursor/mcp.json` file).
+    - Taskmaster is now better at automatically finding your project files, especially in integrated tools, reducing the need for manual path settings.
+    - Fixed an issue that could prevent Taskmaster from working correctly immediately after initialization in integrated tools (related to how the MCP server was invoked). This should solve the issue most users were experiencing with the last release (0.10.x)
+    - Updated setup templates with clearer examples for API keys.
+    - \*\*For advanced users setting up the MCP server manually, the command is now `npx -y task-master-ai task-master-mcp`.
+  - **Enhanced Performance & AI:**
+    - Updated underlying AI model settings:
+      - **Increased Context Window:** Can now handle larger projects/tasks due to an increased Claude context window (64k -> 128k tokens).
+      - **Reduced AI randomness:** More consistent and predictable AI outputs (temperature 0.4 -> 0.2).
+      - **Updated default AI models:** Uses newer models like `claude-3-7-sonnet-20250219` and Perplexity `sonar-pro` by default.
+      - **More granular breakdown:** Increased the default number of subtasks generated by `expand` to 5 (from 4).
+      - **Consistent defaults:** Set the default priority for new tasks consistently to "medium".
+    - Improved performance when viewing task details in integrated tools by sending less redundant data.
+  - **Documentation Clarity:**
+    - Clarified in documentation that Markdown files (`.md`) can be used for Product Requirements Documents (`parse_prd`).
+    - Improved the description for the `numTasks` option in `parse_prd` for better guidance.
+  - **Improved Visuals (CLI):**
+    - Enhanced the look and feel of progress bars and status updates in the command line.
+    - Added a helpful color-coded progress bar to the task details view (`show` command) to visualize subtask completion.
+    - Made progress bars show a breakdown of task statuses (e.g., how many are pending vs. done).
+    - Made status counts clearer with text labels next to icons.
+    - Prevented progress bars from messing up the display on smaller terminal windows.
+    - Adjusted how progress is calculated for 'deferred' and 'cancelled' tasks in the progress bar, while still showing their distinct status visually.
+  - **Fixes for Integrated Tools:**
+    - Fixed how progress updates are sent to integrated tools, ensuring they display correctly.
+    - Fixed internal issues that could cause errors or invalid JSON responses when using Taskmaster with integrated tools.
+
+## 0.10.1
+
+### Patch Changes
+
+- [#80](https://github.com/eyaltoledano/claude-task-master/pull/80) [`aa185b2`](https://github.com/eyaltoledano/claude-task-master/commit/aa185b28b248b4ca93f9195b502e2f5187868eaa) Thanks [@Crunchyman-ralph](https://github.com/Crunchyman-ralph)! - Remove non-existent package `@model-context-protocol/sdk`
+
+- [#45](https://github.com/eyaltoledano/claude-task-master/pull/45) [`757fd47`](https://github.com/eyaltoledano/claude-task-master/commit/757fd478d2e2eff8506ae746c3470c6088f4d944) Thanks [@Crunchyman-ralph](https://github.com/Crunchyman-ralph)! - Add license to repo
+
 ## 0.10.0
 
 ### Minor Changes

LICENSE.md

@@ -1,90 +0,0 @@
-# Dual License
-
-This project is licensed under two separate licenses:
-
-1. [Business Source License 1.1](#business-source-license-11) (BSL 1.1) for commercial use of Task Master itself
-2. [Apache License 2.0](#apache-license-20) for all other uses
-
-## Business Source License 1.1
-
-Terms: https://mariadb.com/bsl11/
-
-Licensed Work: Task Master AI
-Additional Use Grant: You may use Task Master AI to create and commercialize your own projects and products.
-
-Change Date: 2025-03-30
-Change License: None
-
-The Licensed Work is subject to the Business Source License 1.1. If you are interested in using the Licensed Work in a way that competes directly with Task Master, please contact the licensors.
-
-### Licensor
-
-- Eyal Toledano (GitHub: @eyaltoledano)
-- Ralph (GitHub: @Crunchyman-ralph)
-
-### Commercial Use Restrictions
-
-This license explicitly restricts certain commercial uses of Task Master AI to the Licensors listed above. Restricted commercial uses include:
-
-1. Creating commercial products or services that directly compete with Task Master AI
-2. Selling Task Master AI itself as a service
-3. Offering Task Master AI's functionality as a commercial managed service
-4. Reselling or redistributing Task Master AI for a fee
-
-### Explicitly Permitted Uses
-
-The following uses are explicitly allowed under this license:
-
-1. Using Task Master AI to create and commercialize your own projects
-2. Using Task Master AI in commercial environments for internal development
-3. Building and selling products or services that were created using Task Master AI
-4. Using Task Master AI for commercial development as long as you're not selling Task Master AI itself
-
-### Additional Terms
-
-1. The right to commercialize Task Master AI itself is exclusively reserved for the Licensors
-2. No party may create commercial products that directly compete with Task Master AI without explicit written permission
-3. Forks of this repository are subject to the same restrictions regarding direct competition
-4. Contributors agree that their contributions will be subject to this same dual licensing structure
-
-## Apache License 2.0
-
-For all uses other than those restricted above. See [APACHE-LICENSE](./APACHE-LICENSE) for the full license text.
-
-### Permitted Use Definition
-
-You may use Task Master AI for any purpose, including commercial purposes, as long as you are not:
-
-1. Creating a direct competitor to Task Master AI
-2. Selling Task Master AI itself as a service
-3. Redistributing Task Master AI for a fee
-
-### Requirements for Use
-
-1. You must include appropriate copyright notices
-2. You must state significant changes made to the software
-3. You must preserve all license notices
-
-## Questions and Commercial Licensing
-
-For questions about licensing or to inquire about commercial use that may compete with Task Master, please contact:
-
-- Eyal Toledano (GitHub: @eyaltoledano)
-- Ralph (GitHub: @Crunchyman-ralph)
-
-## Examples
-
-### ✅ Allowed Uses
-
-- Using Task Master to create a commercial SaaS product
-- Using Task Master in your company for development
-- Creating and selling products that were built using Task Master
-- Using Task Master to generate code for commercial projects
-- Offering consulting services where you use Task Master
-
-### ❌ Restricted Uses
-
-- Creating a competing AI task management tool
-- Selling access to Task Master as a service
-- Creating a hosted version of Task Master
-- Reselling Task Master's functionality

README-task-master.md

@@ -58,6 +58,7 @@ This will prompt you for project details and set up a new project with the neces
 ### Important Notes
 
 1. **ES Modules Configuration:**
+
    - This project uses ES Modules (ESM) instead of CommonJS.
    - This is set via `"type": "module"` in your package.json.
    - Use `import/export` syntax instead of `require()`.
@@ -145,7 +146,7 @@ To enable enhanced task management capabilities directly within Cursor using the
 4. Configure with the following details:
    - Name: "Task Master"
    - Type: "Command"
-   - Command: "npx -y --package task-master-ai task-master-mcp"
+   - Command: "npx -y task-master-mcp"
 5. Save the settings
 
 Once configured, you can interact with Task Master's task management commands directly through Cursor's interface, providing a more integrated experience.

README.md

@@ -1,58 +1,74 @@
-# Task Master
+# Task Master [![GitHub stars](https://img.shields.io/github/stars/eyaltoledano/claude-task-master?style=social)](https://github.com/eyaltoledano/claude-task-master/stargazers)
 
-### by [@eyaltoledano](https://x.com/eyaltoledano)
+[![CI](https://github.com/eyaltoledano/claude-task-master/actions/workflows/ci.yml/badge.svg)](https://github.com/eyaltoledano/claude-task-master/actions/workflows/ci.yml) [![npm version](https://badge.fury.io/js/task-master-ai.svg)](https://badge.fury.io/js/task-master-ai) ![Discord Follow](https://dcbadge.limes.pink/api/server/https://discord.gg/2ms58QJjqp?style=flat) [![License: MIT with Commons Clause](https://img.shields.io/badge/license-MIT%20with%20Commons%20Clause-blue.svg)](LICENSE)
+
+### By [@eyaltoledano](https://x.com/eyaltoledano) & [@RalphEcom](https://x.com/RalphEcom)
+
+[![Twitter Follow](https://img.shields.io/twitter/follow/eyaltoledano?style=flat)](https://x.com/eyaltoledano)
+[![Twitter Follow](https://img.shields.io/twitter/follow/RalphEcom?style=flat)](https://x.com/RalphEcom)
 
 A task management system for AI-driven development with Claude, designed to work seamlessly with Cursor AI.
 
-## Licensing
-
-Task Master is licensed under the MIT License with Commons Clause. This means you can:
-
-✅ **Allowed**:
-
-- Use Task Master for any purpose (personal, commercial, academic)
-- Modify the code
-- Distribute copies
-- Create and sell products built using Task Master
-
-❌ **Not Allowed**:
-
-- Sell Task Master itself
-- Offer Task Master as a hosted service
-- Create competing products based on Task Master
-
-See the [LICENSE](LICENSE) file for the complete license text.
-
 ## Requirements
 
-- Node.js 14.0.0 or higher
 - Anthropic API key (Claude API)
-- Anthropic SDK version 0.39.0 or higher
 - OpenAI SDK (for Perplexity API integration, optional)
 
-## Configuration
+## Quick Start
 
-The script can be configured through environment variables in a `.env` file at the root of the project:
+### Option 1 | MCP (Recommended):
 
-### Required Configuration
+MCP (Model Control Protocol) provides the easiest way to get started with Task Master directly in your editor.
 
-- `ANTHROPIC_API_KEY`: Your Anthropic API key for Claude
+1. **Install the package**
 
-### Optional Configuration
+```bash
+npm i -g task-master-ai
+```
 
-- `MODEL`: Specify which Claude model to use (default: "claude-3-7-sonnet-20250219")
+2. **Add the MCP config to your editor** (Cursor recommended, but it works with other text editors):
-- `MAX_TOKENS`: Maximum tokens for model responses (default: 4000)
-- `TEMPERATURE`: Temperature for model responses (default: 0.7)
-- `PERPLEXITY_API_KEY`: Your Perplexity API key for research-backed subtask generation
-- `PERPLEXITY_MODEL`: Specify which Perplexity model to use (default: "sonar-medium-online")
-- `DEBUG`: Enable debug logging (default: false)
-- `LOG_LEVEL`: Log level - debug, info, warn, error (default: info)
-- `DEFAULT_SUBTASKS`: Default number of subtasks when expanding (default: 3)
-- `DEFAULT_PRIORITY`: Default priority for generated tasks (default: medium)
-- `PROJECT_NAME`: Override default project name in tasks.json
-- `PROJECT_VERSION`: Override default version in tasks.json
 
-## Installation
+```json
+{
+	"mcpServers": {
+		"taskmaster-ai": {
+			"command": "npx",
+			"args": ["-y", "task-master-mcp"],
+			"env": {
+				"ANTHROPIC_API_KEY": "YOUR_ANTHROPIC_API_KEY_HERE",
+				"PERPLEXITY_API_KEY": "YOUR_PERPLEXITY_API_KEY_HERE",
+				"MODEL": "claude-3-7-sonnet-20250219",
+				"PERPLEXITY_MODEL": "sonar-pro",
+				"MAX_TOKENS": 64000,
+				"TEMPERATURE": 0.2,
+				"DEFAULT_SUBTASKS": 5,
+				"DEFAULT_PRIORITY": "medium"
+			}
+		}
+	}
+}
+```
+
+2. **Enable the MCP** in your editor
+
+3. **Prompt the AI** to initialize Task Master:
+
+```
+Can you please initialize taskmaster-ai into my project?
+```
+
+4. **Use common commands** directly through your AI assistant:
+
+```txt
+Can you parse my PRD at scripts/prd.txt?
+What's the next task I should work on?
+Can you help me implement task 3?
+Can you help me expand task 4?
+```
+
+### Option 2: Using Command Line
+
+#### Installation
 
 ```bash
 # Install globally
@@ -62,7 +78,7 @@ npm install -g task-master-ai
 npm install task-master-ai
 ```
 
-### Initialize a new project
+#### Initialize a new project
 
 ```bash
 # If installed globally
@@ -74,14 +90,7 @@ npx task-master-init
 
 This will prompt you for project details and set up a new project with the necessary files and structure.
 
-### Important Notes
+#### Common Commands
-
-1. This package uses ES modules. Your package.json should include `"type": "module"`.
-2. The Anthropic SDK version should be 0.39.0 or higher.
-
-## Quick Start with Global Commands
-
-After installing the package globally, you can use these CLI commands from any directory:
 
 ```bash
 # Initialize a new project
@@ -100,6 +109,16 @@ task-master next
 task-master generate
 ```
 
+## Documentation
+
+For more detailed information, check out the documentation in the `docs` directory:
+
+- [Configuration Guide](docs/configuration.md) - Set up environment variables and customize Task Master
+- [Tutorial](docs/tutorial.md) - Step-by-step guide to getting started with Task Master
+- [Command Reference](docs/command-reference.md) - Complete list of all available commands
+- [Task Structure](docs/task-structure.md) - Understanding the task format and features
+- [Example Interactions](docs/examples.md) - Common Cursor AI interaction examples
+
 ## Troubleshooting
 
 ### If `task-master init` doesn't respond:
@@ -118,577 +137,31 @@ cd claude-task-master
 node scripts/init.js
 ```
 
-## Task Structure
+## Contributors
 
-Tasks in tasks.json have the following structure:
+<a href="https://github.com/eyaltoledano/claude-task-master/graphs/contributors">
+  <img src="https://contrib.rocks/image?repo=eyaltoledano/claude-task-master" alt="Task Master project contributors" />
+</a>
 
-- `id`: Unique identifier for the task (Example: `1`)
+## Star History
-- `title`: Brief, descriptive title of the task (Example: `"Initialize Repo"`)
-- `description`: Concise description of what the task involves (Example: `"Create a new repository, set up initial structure."`)
-- `status`: Current state of the task (Example: `"pending"`, `"done"`, `"deferred"`)
-- `dependencies`: IDs of tasks that must be completed before this task (Example: `[1, 2]`)
-  - Dependencies are displayed with status indicators (✅ for completed, ⏱️ for pending)
-  - This helps quickly identify which prerequisite tasks are blocking work
-- `priority`: Importance level of the task (Example: `"high"`, `"medium"`, `"low"`)
-- `details`: In-depth implementation instructions (Example: `"Use GitHub client ID/secret, handle callback, set session token."`)
-- `testStrategy`: Verification approach (Example: `"Deploy and call endpoint to confirm 'Hello World' response."`)
-- `subtasks`: List of smaller, more specific tasks that make up the main task (Example: `[{"id": 1, "title": "Configure OAuth", ...}]`)
 
-## Integrating with Cursor AI
+[![Star History Chart](https://api.star-history.com/svg?repos=eyaltoledano/claude-task-master&type=Timeline)](https://www.star-history.com/#eyaltoledano/claude-task-master&Timeline)
 
-Claude Task Master is designed to work seamlessly with [Cursor AI](https://www.cursor.so/), providing a structured workflow for AI-driven development.
+## Licensing
 
-### Setup with Cursor
+Task Master is licensed under the MIT License with Commons Clause. This means you can:
 
-1. After initializing your project, open it in Cursor
+✅ **Allowed**:
-2. The `.cursor/rules/dev_workflow.mdc` file is automatically loaded by Cursor, providing the AI with knowledge about the task management system
-3. Place your PRD document in the `scripts/` directory (e.g., `scripts/prd.txt`)
-4. Open Cursor's AI chat and switch to Agent mode
 
-### Setting up MCP in Cursor
+- Use Task Master for any purpose (personal, commercial, academic)
+- Modify the code
+- Distribute copies
+- Create and sell products built using Task Master
 
-To enable enhanced task management capabilities directly within Cursor using the Model Control Protocol (MCP):
+❌ **Not Allowed**:
 
-1. Go to Cursor settings
+- Sell Task Master itself
-2. Navigate to the MCP section
+- Offer Task Master as a hosted service
-3. Click on "Add New MCP Server"
+- Create competing products based on Task Master
-4. Configure with the following details:
-   - Name: "Task Master"
-   - Type: "Command"
-   - Command: "npx -y --package task-master-ai task-master-mcp"
-5. Save the settings
 
-Once configured, you can interact with Task Master's task management commands directly through Cursor's interface, providing a more integrated experience.
+See the [LICENSE](LICENSE) file for the complete license text and [licensing details](docs/licensing.md) for more information.
-
-### Initial Task Generation
-
-In Cursor's AI chat, instruct the agent to generate tasks from your PRD:
-
-```
-Please use the task-master parse-prd command to generate tasks from my PRD. The PRD is located at scripts/prd.txt.
-```
-
-The agent will execute:
-
-```bash
-task-master parse-prd scripts/prd.txt
-```
-
-This will:
-
-- Parse your PRD document
-- Generate a structured `tasks.json` file with tasks, dependencies, priorities, and test strategies
-- The agent will understand this process due to the Cursor rules
-
-### Generate Individual Task Files
-
-Next, ask the agent to generate individual task files:
-
-```
-Please generate individual task files from tasks.json
-```
-
-The agent will execute:
-
-```bash
-task-master generate
-```
-
-This creates individual task files in the `tasks/` directory (e.g., `task_001.txt`, `task_002.txt`), making it easier to reference specific tasks.
-
-## AI-Driven Development Workflow
-
-The Cursor agent is pre-configured (via the rules file) to follow this workflow:
-
-### 1. Task Discovery and Selection
-
-Ask the agent to list available tasks:
-
-```
-What tasks are available to work on next?
-```
-
-The agent will:
-
-- Run `task-master list` to see all tasks
-- Run `task-master next` to determine the next task to work on
-- Analyze dependencies to determine which tasks are ready to be worked on
-- Prioritize tasks based on priority level and ID order
-- Suggest the next task(s) to implement
-
-### 2. Task Implementation
-
-When implementing a task, the agent will:
-
-- Reference the task's details section for implementation specifics
-- Consider dependencies on previous tasks
-- Follow the project's coding standards
-- Create appropriate tests based on the task's testStrategy
-
-You can ask:
-
-```
-Let's implement task 3. What does it involve?
-```
-
-### 3. Task Verification
-
-Before marking a task as complete, verify it according to:
-
-- The task's specified testStrategy
-- Any automated tests in the codebase
-- Manual verification if required
-
-### 4. Task Completion
-
-When a task is completed, tell the agent:
-
-```
-Task 3 is now complete. Please update its status.
-```
-
-The agent will execute:
-
-```bash
-task-master set-status --id=3 --status=done
-```
-
-### 5. Handling Implementation Drift
-
-If during implementation, you discover that:
-
-- The current approach differs significantly from what was planned
-- Future tasks need to be modified due to current implementation choices
-- New dependencies or requirements have emerged
-
-Tell the agent:
-
-```
-We've changed our approach. We're now using Express instead of Fastify. Please update all future tasks to reflect this change.
-```
-
-The agent will execute:
-
-```bash
-task-master update --from=4 --prompt="Now we are using Express instead of Fastify."
-```
-
-This will rewrite or re-scope subsequent tasks in tasks.json while preserving completed work.
-
-### 6. Breaking Down Complex Tasks
-
-For complex tasks that need more granularity:
-
-```
-Task 5 seems complex. Can you break it down into subtasks?
-```
-
-The agent will execute:
-
-```bash
-task-master expand --id=5 --num=3
-```
-
-You can provide additional context:
-
-```
-Please break down task 5 with a focus on security considerations.
-```
-
-The agent will execute:
-
-```bash
-task-master expand --id=5 --prompt="Focus on security aspects"
-```
-
-You can also expand all pending tasks:
-
-```
-Please break down all pending tasks into subtasks.
-```
-
-The agent will execute:
-
-```bash
-task-master expand --all
-```
-
-For research-backed subtask generation using Perplexity AI:
-
-```
-Please break down task 5 using research-backed generation.
-```
-
-The agent will execute:
-
-```bash
-task-master expand --id=5 --research
-```
-
-## Command Reference
-
-Here's a comprehensive reference of all available commands:
-
-### Parse PRD
-
-```bash
-# Parse a PRD file and generate tasks
-task-master parse-prd <prd-file.txt>
-
-# Limit the number of tasks generated
-task-master parse-prd <prd-file.txt> --num-tasks=10
-```
-
-### List Tasks
-
-```bash
-# List all tasks
-task-master list
-
-# List tasks with a specific status
-task-master list --status=<status>
-
-# List tasks with subtasks
-task-master list --with-subtasks
-
-# List tasks with a specific status and include subtasks
-task-master list --status=<status> --with-subtasks
-```
-
-### Show Next Task
-
-```bash
-# Show the next task to work on based on dependencies and status
-task-master next
-```
-
-### Show Specific Task
-
-```bash
-# Show details of a specific task
-task-master show <id>
-# or
-task-master show --id=<id>
-
-# View a specific subtask (e.g., subtask 2 of task 1)
-task-master show 1.2
-```
-
-### Update Tasks
-
-```bash
-# Update tasks from a specific ID and provide context
-task-master update --from=<id> --prompt="<prompt>"
-```
-
-### Update a Specific Task
-
-```bash
-# Update a single task by ID with new information
-task-master update-task --id=<id> --prompt="<prompt>"
-
-# Use research-backed updates with Perplexity AI
-task-master update-task --id=<id> --prompt="<prompt>" --research
-```
-
-### Update a Subtask
-
-```bash
-# Append additional information to a specific subtask
-task-master update-subtask --id=<parentId.subtaskId> --prompt="<prompt>"
-
-# Example: Add details about API rate limiting to subtask 2 of task 5
-task-master update-subtask --id=5.2 --prompt="Add rate limiting of 100 requests per minute"
-
-# Use research-backed updates with Perplexity AI
-task-master update-subtask --id=<parentId.subtaskId> --prompt="<prompt>" --research
-```
-
-Unlike the `update-task` command which replaces task information, the `update-subtask` command _appends_ new information to the existing subtask details, marking it with a timestamp. This is useful for iteratively enhancing subtasks while preserving the original content.
-
-### Remove Task
-
-```bash
-# Remove a task permanently
-task-master remove-task --id=<id>
-
-# Remove a subtask permanently
-task-master remove-task --id=<parentId.subtaskId>
-
-# Skip the confirmation prompt
-task-master remove-task --id=<id> --yes
-```
-
-The `remove-task` command permanently deletes a task or subtask from `tasks.json`. It also automatically cleans up any references to the deleted task in other tasks' dependencies. Consider using 'blocked', 'cancelled', or 'deferred' status instead if you want to keep the task for reference.
-
-### Generate Task Files
-
-```bash
-# Generate individual task files from tasks.json
-task-master generate
-```
-
-### Set Task Status
-
-```bash
-# Set status of a single task
-task-master set-status --id=<id> --status=<status>
-
-# Set status for multiple tasks
-task-master set-status --id=1,2,3 --status=<status>
-
-# Set status for subtasks
-task-master set-status --id=1.1,1.2 --status=<status>
-```
-
-When marking a task as "done", all of its subtasks will automatically be marked as "done" as well.
-
-### Expand Tasks
-
-```bash
-# Expand a specific task with subtasks
-task-master expand --id=<id> --num=<number>
-
-# Expand with additional context
-task-master expand --id=<id> --prompt="<context>"
-
-# Expand all pending tasks
-task-master expand --all
-
-# Force regeneration of subtasks for tasks that already have them
-task-master expand --all --force
-
-# Research-backed subtask generation for a specific task
-task-master expand --id=<id> --research
-
-# Research-backed generation for all tasks
-task-master expand --all --research
-```
-
-### Clear Subtasks
-
-```bash
-# Clear subtasks from a specific task
-task-master clear-subtasks --id=<id>
-
-# Clear subtasks from multiple tasks
-task-master clear-subtasks --id=1,2,3
-
-# Clear subtasks from all tasks
-task-master clear-subtasks --all
-```
-
-### Analyze Task Complexity
-
-```bash
-# Analyze complexity of all tasks
-task-master analyze-complexity
-
-# Save report to a custom location
-task-master analyze-complexity --output=my-report.json
-
-# Use a specific LLM model
-task-master analyze-complexity --model=claude-3-opus-20240229
-
-# Set a custom complexity threshold (1-10)
-task-master analyze-complexity --threshold=6
-
-# Use an alternative tasks file
-task-master analyze-complexity --file=custom-tasks.json
-
-# Use Perplexity AI for research-backed complexity analysis
-task-master analyze-complexity --research
-```
-
-### View Complexity Report
-
-```bash
-# Display the task complexity analysis report
-task-master complexity-report
-
-# View a report at a custom location
-task-master complexity-report --file=my-report.json
-```
-
-### Managing Task Dependencies
-
-```bash
-# Add a dependency to a task
-task-master add-dependency --id=<id> --depends-on=<id>
-
-# Remove a dependency from a task
-task-master remove-dependency --id=<id> --depends-on=<id>
-
-# Validate dependencies without fixing them
-task-master validate-dependencies
-
-# Find and fix invalid dependencies automatically
-task-master fix-dependencies
-```
-
-### Add a New Task
-
-```bash
-# Add a new task using AI
-task-master add-task --prompt="Description of the new task"
-
-# Add a task with dependencies
-task-master add-task --prompt="Description" --dependencies=1,2,3
-
-# Add a task with priority
-task-master add-task --prompt="Description" --priority=high
-```
-
-## Feature Details
-
-### Analyzing Task Complexity
-
-The `analyze-complexity` command:
-
-- Analyzes each task using AI to assess its complexity on a scale of 1-10
-- Recommends optimal number of subtasks based on configured DEFAULT_SUBTASKS
-- Generates tailored prompts for expanding each task
-- Creates a comprehensive JSON report with ready-to-use commands
-- Saves the report to scripts/task-complexity-report.json by default
-
-The generated report contains:
-
-- Complexity analysis for each task (scored 1-10)
-- Recommended number of subtasks based on complexity
-- AI-generated expansion prompts customized for each task
-- Ready-to-run expansion commands directly within each task analysis
-
-### Viewing Complexity Report
-
-The `complexity-report` command:
-
-- Displays a formatted, easy-to-read version of the complexity analysis report
-- Shows tasks organized by complexity score (highest to lowest)
-- Provides complexity distribution statistics (low, medium, high)
-- Highlights tasks recommended for expansion based on threshold score
-- Includes ready-to-use expansion commands for each complex task
-- If no report exists, offers to generate one on the spot
-
-### Smart Task Expansion
-
-The `expand` command automatically checks for and uses the complexity report:
-
-When a complexity report exists:
-
-- Tasks are automatically expanded using the recommended subtask count and prompts
-- When expanding all tasks, they're processed in order of complexity (highest first)
-- Research-backed generation is preserved from the complexity analysis
-- You can still override recommendations with explicit command-line options
-
-Example workflow:
-
-```bash
-# Generate the complexity analysis report with research capabilities
-task-master analyze-complexity --research
-
-# Review the report in a readable format
-task-master complexity-report
-
-# Expand tasks using the optimized recommendations
-task-master expand --id=8
-# or expand all tasks
-task-master expand --all
-```
-
-### Finding the Next Task
-
-The `next` command:
-
-- Identifies tasks that are pending/in-progress and have all dependencies satisfied
-- Prioritizes tasks by priority level, dependency count, and task ID
-- Displays comprehensive information about the selected task:
-  - Basic task details (ID, title, priority, dependencies)
-  - Implementation details
-  - Subtasks (if they exist)
-- Provides contextual suggested actions:
-  - Command to mark the task as in-progress
-  - Command to mark the task as done
-  - Commands for working with subtasks
-
-### Viewing Specific Task Details
-
-The `show` command:
-
-- Displays comprehensive details about a specific task or subtask
-- Shows task status, priority, dependencies, and detailed implementation notes
-- For parent tasks, displays all subtasks and their status
-- For subtasks, shows parent task relationship
-- Provides contextual action suggestions based on the task's state
-- Works with both regular tasks and subtasks (using the format taskId.subtaskId)
-
-## Best Practices for AI-Driven Development
-
-1. **Start with a detailed PRD**: The more detailed your PRD, the better the generated tasks will be.
-
-2. **Review generated tasks**: After parsing the PRD, review the tasks to ensure they make sense and have appropriate dependencies.
-
-3. **Analyze task complexity**: Use the complexity analysis feature to identify which tasks should be broken down further.
-
-4. **Follow the dependency chain**: Always respect task dependencies - the Cursor agent will help with this.
-
-5. **Update as you go**: If your implementation diverges from the plan, use the update command to keep future tasks aligned with your current approach.
-
-6. **Break down complex tasks**: Use the expand command to break down complex tasks into manageable subtasks.
-
-7. **Regenerate task files**: After any updates to tasks.json, regenerate the task files to keep them in sync.
-
-8. **Communicate context to the agent**: When asking the Cursor agent to help with a task, provide context about what you're trying to achieve.
-
-9. **Validate dependencies**: Periodically run the validate-dependencies command to check for invalid or circular dependencies.
-
-## Example Cursor AI Interactions
-
-### Starting a new project
-
-```
-I've just initialized a new project with Claude Task Master. I have a PRD at scripts/prd.txt.
-Can you help me parse it and set up the initial tasks?
-```
-
-### Working on tasks
-
-```
-What's the next task I should work on? Please consider dependencies and priorities.
-```
-
-### Implementing a specific task
-
-```
-I'd like to implement task 4. Can you help me understand what needs to be done and how to approach it?
-```
-
-### Managing subtasks
-
-```
-I need to regenerate the subtasks for task 3 with a different approach. Can you help me clear and regenerate them?
-```
-
-### Handling changes
-
-```
-We've decided to use MongoDB instead of PostgreSQL. Can you update all future tasks to reflect this change?
-```
-
-### Completing work
-
-```
-I've finished implementing the authentication system described in task 2. All tests are passing.
-Please mark it as complete and tell me what I should work on next.
-```
-
-### Analyzing complexity
-
-```
-Can you analyze the complexity of our tasks to help me understand which ones need to be broken down further?
-```
-
-### Viewing complexity report
-
-```
-Can you show me the complexity report in a more readable format?
-```

assets/scripts_README.md

@@ -21,9 +21,11 @@ In an AI-driven development process—particularly with tools like [Cursor](http
 The script can be configured through environment variables in a `.env` file at the root of the project:
 
 ### Required Configuration
+
 - `ANTHROPIC_API_KEY`: Your Anthropic API key for Claude
 
 ### Optional Configuration
+
 - `MODEL`: Specify which Claude model to use (default: "claude-3-7-sonnet-20250219")
 - `MAX_TOKENS`: Maximum tokens for model responses (default: 4000)
 - `TEMPERATURE`: Temperature for model responses (default: 0.7)
@@ -39,6 +41,7 @@ The script can be configured through environment variables in a `.env` file at t
 ## How It Works
 
 1. **`tasks.json`**:
+
    - A JSON file at the project root containing an array of tasks (each with `id`, `title`, `description`, `status`, etc.).
    - The `meta` field can store additional info like the project's name, version, or reference to the PRD.
    - Tasks can have `subtasks` for more detailed implementation steps.
@@ -111,6 +114,7 @@ task-master update --file=custom-tasks.json --from=5 --prompt="Change database f
 ```
 
 Notes:
+
 - The `--prompt` parameter is required and should explain the changes or new context
 - Only tasks that aren't marked as 'done' will be updated
 - Tasks with ID >= the specified --from value will be updated
@@ -134,6 +138,7 @@ task-master set-status --id=1,2,3 --status=done
 ```
 
 Notes:
+
 - When marking a parent task as "done", all of its subtasks will automatically be marked as "done" as well
 - Common status values are 'done', 'pending', and 'deferred', but any string is accepted
 - You can specify multiple task IDs by separating them with commas
@@ -183,6 +188,7 @@ task-master clear-subtasks --all
 ```
 
 Notes:
+
 - After clearing subtasks, task files are automatically regenerated
 - This is useful when you want to regenerate subtasks with a different approach
 - Can be combined with the `expand` command to immediately generate new subtasks
@@ -198,6 +204,7 @@ The script integrates with two AI services:
 The Perplexity integration uses the OpenAI client to connect to Perplexity's API, which provides enhanced research capabilities for generating more informed subtasks. If the Perplexity API is unavailable or encounters an error, the script will automatically fall back to using Anthropic's Claude.
 
 To use the Perplexity integration:
+
 1. Obtain a Perplexity API key
 2. Add `PERPLEXITY_API_KEY` to your `.env` file
 3. Optionally specify `PERPLEXITY_MODEL` in your `.env` file (default: "sonar-medium-online")
@@ -206,6 +213,7 @@ To use the Perplexity integration:
 ## Logging
 
 The script supports different logging levels controlled by the `LOG_LEVEL` environment variable:
+
 - `debug`: Detailed information, typically useful for troubleshooting
 - `info`: Confirmation that things are working as expected (default)
 - `warn`: Warning messages that don't prevent execution
@@ -228,17 +236,20 @@ task-master remove-dependency --id=<id> --depends-on=<id>
 These commands:
 
 1. **Allow precise dependency management**:
+
    - Add dependencies between tasks with automatic validation
    - Remove dependencies when they're no longer needed
    - Update task files automatically after changes
 
 2. **Include validation checks**:
+
    - Prevent circular dependencies (a task depending on itself)
    - Prevent duplicate dependencies
    - Verify that both tasks exist before adding/removing dependencies
    - Check if dependencies exist before attempting to remove them
 
 3. **Provide clear feedback**:
+
    - Success messages confirm when dependencies are added/removed
    - Error messages explain why operations failed (if applicable)
 
@@ -263,6 +274,7 @@ task-master validate-dependencies --file=custom-tasks.json
 ```
 
 This command:
+
 - Scans all tasks and subtasks for non-existent dependencies
 - Identifies potential self-dependencies (tasks referencing themselves)
 - Reports all found issues without modifying files
@@ -284,6 +296,7 @@ task-master fix-dependencies --file=custom-tasks.json
 ```
 
 This command:
+
 1. **Validates all dependencies** across tasks and subtasks
 2. **Automatically removes**:
    - References to non-existent tasks and subtasks
@@ -321,6 +334,7 @@ task-master analyze-complexity --research
 ```
 
 Notes:
+
 - The command uses Claude to analyze each task's complexity (or Perplexity with --research flag)
 - Tasks are scored on a scale of 1-10
 - Each task receives a recommended number of subtasks based on DEFAULT_SUBTASKS configuration
@@ -345,33 +359,35 @@ task-master expand --id=8 --num=5 --prompt="Custom prompt"
 ```
 
 When a complexity report exists:
+
 - The `expand` command will use the recommended subtask count from the report (unless overridden)
 - It will use the tailored expansion prompt from the report (unless a custom prompt is provided)
 - When using `--all`, tasks are sorted by complexity score (highest first)
 - The `--research` flag is preserved from the complexity analysis to expansion
 
 The output report structure is:
+
 ```json
 {
-  "meta": {
+	"meta": {
-    "generatedAt": "2023-06-15T12:34:56.789Z",
+		"generatedAt": "2023-06-15T12:34:56.789Z",
-    "tasksAnalyzed": 20,
+		"tasksAnalyzed": 20,
-    "thresholdScore": 5,
+		"thresholdScore": 5,
-    "projectName": "Your Project Name",
+		"projectName": "Your Project Name",
-    "usedResearch": true
+		"usedResearch": true
-  },
+	},
-  "complexityAnalysis": [
+	"complexityAnalysis": [
-    {
+		{
-      "taskId": 8,
+			"taskId": 8,
-      "taskTitle": "Develop Implementation Drift Handling",
+			"taskTitle": "Develop Implementation Drift Handling",
-      "complexityScore": 9.5,
+			"complexityScore": 9.5,
-      "recommendedSubtasks": 6,
+			"recommendedSubtasks": 6,
-      "expansionPrompt": "Create subtasks that handle detecting...",
+			"expansionPrompt": "Create subtasks that handle detecting...",
-      "reasoning": "This task requires sophisticated logic...",
+			"reasoning": "This task requires sophisticated logic...",
-      "expansionCommand": "task-master expand --id=8 --num=6 --prompt=\"Create subtasks...\" --research"
+			"expansionCommand": "task-master expand --id=8 --num=6 --prompt=\"Create subtasks...\" --research"
-    },
+		}
-    // More tasks sorted by complexity score (highest first)
+		// More tasks sorted by complexity score (highest first)
-  ]
+	]
 }
 ```
 

bin/task-master-init.js

@@ -1,30 +0,0 @@
-#!/usr/bin/env node
-
-/**
- * Claude Task Master Init
- * Direct executable for the init command
- */
-
-import { spawn } from 'child_process';
-import { fileURLToPath } from 'url';
-import { dirname, resolve } from 'path';
-
-const __filename = fileURLToPath(import.meta.url);
-const __dirname = dirname(__filename);
-
-// Get the path to the init script
-const initScriptPath = resolve(__dirname, '../scripts/init.js');
-
-// Pass through all arguments
-const args = process.argv.slice(2);
-
-// Spawn the init script with all arguments
-const child = spawn('node', [initScriptPath, ...args], {
-  stdio: 'inherit',
-  cwd: process.cwd()
-});
-
-// Handle exit
-child.on('close', (code) => {
-  process.exit(code);
-}); 

bin/task-master.js

@@ -44,30 +44,36 @@ const initScriptPath = resolve(__dirname, '../scripts/init.js');
 
 // Helper function to run dev.js with arguments
 function runDevScript(args) {
-  // Debug: Show the transformed arguments when DEBUG=1 is set
+	// Debug: Show the transformed arguments when DEBUG=1 is set
-  if (process.env.DEBUG === '1') {
+	if (process.env.DEBUG === '1') {
-    console.error('\nDEBUG - CLI Wrapper Analysis:');
+		console.error('\nDEBUG - CLI Wrapper Analysis:');
-    console.error('- Original command: ' + process.argv.join(' '));
+		console.error('- Original command: ' + process.argv.join(' '));
-    console.error('- Transformed args: ' + args.join(' '));
+		console.error('- Transformed args: ' + args.join(' '));
-    console.error('- dev.js will receive: node ' + devScriptPath + ' ' + args.join(' ') + '\n');
+		console.error(
-  }
+			'- dev.js will receive: node ' +
+				devScriptPath +
+				' ' +
+				args.join(' ') +
+				'\n'
+		);
+	}
 
-  // For testing: If TEST_MODE is set, just print args and exit
+	// For testing: If TEST_MODE is set, just print args and exit
-  if (process.env.TEST_MODE === '1') {
+	if (process.env.TEST_MODE === '1') {
-    console.log('Would execute:');
+		console.log('Would execute:');
-    console.log(`node ${devScriptPath} ${args.join(' ')}`);
+		console.log(`node ${devScriptPath} ${args.join(' ')}`);
-    process.exit(0);
+		process.exit(0);
-    return;
+		return;
-  }
+	}
 
-  const child = spawn('node', [devScriptPath, ...args], {
+	const child = spawn('node', [devScriptPath, ...args], {
-    stdio: 'inherit',
+		stdio: 'inherit',
-    cwd: process.cwd()
+		cwd: process.cwd()
-  });
+	});
 
-  child.on('close', (code) => {
+	child.on('close', (code) => {
-    process.exit(code);
+		process.exit(code);
-  });
+	});
 }
 
 // Helper function to detect camelCase and convert to kebab-case
@@ -79,228 +85,239 @@ const toKebabCase = (str) => str.replace(/([A-Z])/g, '-$1').toLowerCase();
  * @returns {Function} Wrapper action function
  */
 function createDevScriptAction(commandName) {
-  return (options, cmd) => {
+	return (options, cmd) => {
-    // Check for camelCase flags and error out with helpful message
+		// Check for camelCase flags and error out with helpful message
-    const camelCaseFlags = detectCamelCaseFlags(process.argv);
+		const camelCaseFlags = detectCamelCaseFlags(process.argv);
 
-    // If camelCase flags were found, show error and exit
+		// If camelCase flags were found, show error and exit
-    if (camelCaseFlags.length > 0) {
+		if (camelCaseFlags.length > 0) {
-      console.error('\nError: Please use kebab-case for CLI flags:');
+			console.error('\nError: Please use kebab-case for CLI flags:');
-      camelCaseFlags.forEach(flag => {
+			camelCaseFlags.forEach((flag) => {
-        console.error(`  Instead of: --${flag.original}`);
+				console.error(`  Instead of: --${flag.original}`);
-        console.error(`  Use:        --${flag.kebabCase}`);
+				console.error(`  Use:        --${flag.kebabCase}`);
-      });
+			});
-      console.error('\nExample: task-master parse-prd --num-tasks=5 instead of --numTasks=5\n');
+			console.error(
-      process.exit(1);
+				'\nExample: task-master parse-prd --num-tasks=5 instead of --numTasks=5\n'
-    }
+			);
+			process.exit(1);
+		}
 
-    // Since we've ensured no camelCase flags, we can now just:
+		// Since we've ensured no camelCase flags, we can now just:
-    // 1. Start with the command name
+		// 1. Start with the command name
-    const args = [commandName];
+		const args = [commandName];
 
-    // 3. Get positional arguments and explicit flags from the command line
+		// 3. Get positional arguments and explicit flags from the command line
-    const commandArgs = [];
+		const commandArgs = [];
-    const positionals = new Set(); // Track positional args we've seen
+		const positionals = new Set(); // Track positional args we've seen
 
-    // Find the command in raw process.argv to extract args
+		// Find the command in raw process.argv to extract args
-    const commandIndex = process.argv.indexOf(commandName);
+		const commandIndex = process.argv.indexOf(commandName);
-    if (commandIndex !== -1) {
+		if (commandIndex !== -1) {
-      // Process all args after the command name
+			// Process all args after the command name
-      for (let i = commandIndex + 1; i < process.argv.length; i++) {
+			for (let i = commandIndex + 1; i < process.argv.length; i++) {
-        const arg = process.argv[i];
+				const arg = process.argv[i];
 
-        if (arg.startsWith('--')) {
+				if (arg.startsWith('--')) {
-          // It's a flag - pass through as is
+					// It's a flag - pass through as is
-          commandArgs.push(arg);
+					commandArgs.push(arg);
-          // Skip the next arg if this is a flag with a value (not --flag=value format)
+					// Skip the next arg if this is a flag with a value (not --flag=value format)
-          if (!arg.includes('=') && 
+					if (
-              i + 1 < process.argv.length && 
+						!arg.includes('=') &&
-              !process.argv[i+1].startsWith('--')) {
+						i + 1 < process.argv.length &&
-            commandArgs.push(process.argv[++i]);
+						!process.argv[i + 1].startsWith('--')
-          }
+					) {
-        } else if (!positionals.has(arg)) {
+						commandArgs.push(process.argv[++i]);
-          // It's a positional argument we haven't seen
+					}
-          commandArgs.push(arg);
+				} else if (!positionals.has(arg)) {
-          positionals.add(arg);
+					// It's a positional argument we haven't seen
-        }
+					commandArgs.push(arg);
-      }
+					positionals.add(arg);
-    }
+				}
+			}
+		}
 
-    // Add all command line args we collected
+		// Add all command line args we collected
-    args.push(...commandArgs);
+		args.push(...commandArgs);
 
-    // 4. Add default options from Commander if not specified on command line
+		// 4. Add default options from Commander if not specified on command line
-    // Track which options we've seen on the command line
+		// Track which options we've seen on the command line
-    const userOptions = new Set();
+		const userOptions = new Set();
-    for (const arg of commandArgs) {
+		for (const arg of commandArgs) {
-      if (arg.startsWith('--')) {
+			if (arg.startsWith('--')) {
-        // Extract option name (without -- and value)
+				// Extract option name (without -- and value)
-        const name = arg.split('=')[0].slice(2);
+				const name = arg.split('=')[0].slice(2);
-        userOptions.add(name);
+				userOptions.add(name);
 
-        // Add the kebab-case version too, to prevent duplicates
+				// Add the kebab-case version too, to prevent duplicates
-        const kebabName = name.replace(/([A-Z])/g, '-$1').toLowerCase();
+				const kebabName = name.replace(/([A-Z])/g, '-$1').toLowerCase();
-        userOptions.add(kebabName);
+				userOptions.add(kebabName);
 
-        // Add the camelCase version as well
+				// Add the camelCase version as well
-        const camelName = kebabName.replace(/-([a-z])/g, (_, letter) => letter.toUpperCase());
+				const camelName = kebabName.replace(/-([a-z])/g, (_, letter) =>
-        userOptions.add(camelName);
+					letter.toUpperCase()
-      }
+				);
-    }
+				userOptions.add(camelName);
+			}
+		}
 
-    // Add Commander-provided defaults for options not specified by user
+		// Add Commander-provided defaults for options not specified by user
-    Object.entries(options).forEach(([key, value]) => {
+		Object.entries(options).forEach(([key, value]) => {
-      // Debug output to see what keys we're getting
+			// Debug output to see what keys we're getting
-      if (process.env.DEBUG === '1') {
+			if (process.env.DEBUG === '1') {
-        console.error(`DEBUG - Processing option: ${key} = ${value}`);
+				console.error(`DEBUG - Processing option: ${key} = ${value}`);
-      }
+			}
 
-      // Special case for numTasks > num-tasks (a known problem case)
+			// Special case for numTasks > num-tasks (a known problem case)
-      if (key === 'numTasks') {
+			if (key === 'numTasks') {
-        if (process.env.DEBUG === '1') {
+				if (process.env.DEBUG === '1') {
-          console.error('DEBUG - Converting numTasks to num-tasks');
+					console.error('DEBUG - Converting numTasks to num-tasks');
-        }
+				}
-        if (!userOptions.has('num-tasks') && !userOptions.has('numTasks')) {
+				if (!userOptions.has('num-tasks') && !userOptions.has('numTasks')) {
-          args.push(`--num-tasks=${value}`);
+					args.push(`--num-tasks=${value}`);
-        }
+				}
-        return;
+				return;
-      }
+			}
 
-      // Skip built-in Commander properties and options the user provided
+			// Skip built-in Commander properties and options the user provided
-      if (['parent', 'commands', 'options', 'rawArgs'].includes(key) || userOptions.has(key)) {
+			if (
-        return;
+				['parent', 'commands', 'options', 'rawArgs'].includes(key) ||
-      }
+				userOptions.has(key)
+			) {
+				return;
+			}
 
-      // Also check the kebab-case version of this key
+			// Also check the kebab-case version of this key
-      const kebabKey = key.replace(/([A-Z])/g, '-$1').toLowerCase();
+			const kebabKey = key.replace(/([A-Z])/g, '-$1').toLowerCase();
-      if (userOptions.has(kebabKey)) {
+			if (userOptions.has(kebabKey)) {
-        return;
+				return;
-      }
+			}
 
-      // Add default values, using kebab-case for the parameter name
+			// Add default values, using kebab-case for the parameter name
-      if (value !== undefined) {
+			if (value !== undefined) {
-        if (typeof value === 'boolean') {
+				if (typeof value === 'boolean') {
-          if (value === true) {
+					if (value === true) {
-            args.push(`--${kebabKey}`);
+						args.push(`--${kebabKey}`);
-          } else if (value === false && key === 'generate') {
+					} else if (value === false && key === 'generate') {
-            args.push('--skip-generate');
+						args.push('--skip-generate');
-          }
+					}
-        } else {
+				} else {
-          // Always use kebab-case for option names
+					// Always use kebab-case for option names
-          args.push(`--${kebabKey}=${value}`);
+					args.push(`--${kebabKey}=${value}`);
-        }
+				}
-      }
+			}
-    });
+		});
 
-    // Special handling for parent parameter (uses -p)
+		// Special handling for parent parameter (uses -p)
-    if (options.parent && !args.includes('-p') && !userOptions.has('parent')) {
+		if (options.parent && !args.includes('-p') && !userOptions.has('parent')) {
-      args.push('-p', options.parent);
+			args.push('-p', options.parent);
-    }
+		}
 
-    // Debug output for troubleshooting
+		// Debug output for troubleshooting
-    if (process.env.DEBUG === '1') {
+		if (process.env.DEBUG === '1') {
-      console.error('DEBUG - Command args:', commandArgs);
+			console.error('DEBUG - Command args:', commandArgs);
-      console.error('DEBUG - User options:', Array.from(userOptions));
+			console.error('DEBUG - User options:', Array.from(userOptions));
-      console.error('DEBUG - Commander options:', options);
+			console.error('DEBUG - Commander options:', options);
-      console.error('DEBUG - Final args:', args);
+			console.error('DEBUG - Final args:', args);
-    }
+		}
 
-    // Run the script with our processed args
+		// Run the script with our processed args
-    runDevScript(args);
+		runDevScript(args);
-  };
+	};
 }
 
-// Special case for the 'init' command which uses a different script
+// // Special case for the 'init' command which uses a different script
-function registerInitCommand(program) {
+// function registerInitCommand(program) {
-  program
+// 	program
-    .command('init')
+// 		.command('init')
-    .description('Initialize a new project')
+// 		.description('Initialize a new project')
-    .option('-y, --yes', 'Skip prompts and use default values')
+// 		.option('-y, --yes', 'Skip prompts and use default values')
-    .option('-n, --name <name>', 'Project name')
+// 		.option('-n, --name <name>', 'Project name')
-    .option('-d, --description <description>', 'Project description')
+// 		.option('-d, --description <description>', 'Project description')
-    .option('-v, --version <version>', 'Project version')
+// 		.option('-v, --version <version>', 'Project version')
-    .option('-a, --author <author>', 'Author name')
+// 		.option('-a, --author <author>', 'Author name')
-    .option('--skip-install', 'Skip installing dependencies')
+// 		.option('--skip-install', 'Skip installing dependencies')
-    .option('--dry-run', 'Show what would be done without making changes')
+// 		.option('--dry-run', 'Show what would be done without making changes')
-    .action((options) => {
+// 		.action((options) => {
-      // Pass through any options to the init script
+// 			// Pass through any options to the init script
-      const args = ['--yes', 'name', 'description', 'version', 'author', 'skip-install', 'dry-run']
+// 			const args = [
-        .filter(opt => options[opt])
+// 				'--yes',
-        .map(opt => {
+// 				'name',
-          if (opt === 'yes' || opt === 'skip-install' || opt === 'dry-run') {
+// 				'description',
-            return `--${opt}`;
+// 				'version',
-          }
+// 				'author',
-          return `--${opt}=${options[opt]}`;
+// 				'skip-install',
-        });
+// 				'dry-run'
+// 			]
+// 				.filter((opt) => options[opt])
+// 				.map((opt) => {
+// 					if (opt === 'yes' || opt === 'skip-install' || opt === 'dry-run') {
+// 						return `--${opt}`;
+// 					}
+// 					return `--${opt}=${options[opt]}`;
+// 				});
 
-      const child = spawn('node', [initScriptPath, ...args], {
+// 			const child = spawn('node', [initScriptPath, ...args], {
-        stdio: 'inherit',
+// 				stdio: 'inherit',
-        cwd: process.cwd()
+// 				cwd: process.cwd()
-      });
+// 			});
 
-      child.on('close', (code) => {
+// 			child.on('close', (code) => {
-        process.exit(code);
+// 				process.exit(code);
-      });
+// 			});
-    });
+// 		});
-}
+// }
 
 // Set up the command-line interface
 const program = new Command();
 
 program
-  .name('task-master')
+	.name('task-master')
-  .description('Claude Task Master CLI')
+	.description('Claude Task Master CLI')
-  .version(version)
+	.version(version)
-  .addHelpText('afterAll', () => {
+	.addHelpText('afterAll', () => {
-    // Use the same help display function as dev.js for consistency
+		// Use the same help display function as dev.js for consistency
-    displayHelp();
+		displayHelp();
-    return ''; // Return empty string to prevent commander's default help
+		return ''; // Return empty string to prevent commander's default help
-  });
+	});
 
 // Add custom help option to directly call our help display
 program.helpOption('-h, --help', 'Display help information');
 program.on('--help', () => {
-  displayHelp();
+	displayHelp();
 });
 
-// Add special case commands
+// // Add special case commands
-registerInitCommand(program);
+// registerInitCommand(program);
 
 program
-  .command('dev')
+	.command('dev')
-  .description('Run the dev.js script')
+	.description('Run the dev.js script')
-  .action(() => {
+	.action(() => {
-    const args = process.argv.slice(process.argv.indexOf('dev') + 1);
+		const args = process.argv.slice(process.argv.indexOf('dev') + 1);
-    runDevScript(args);
+		runDevScript(args);
-  });
+	});
 
 // Use a temporary Command instance to get all command definitions
 const tempProgram = new Command();
 registerCommands(tempProgram);
 
 // For each command in the temp instance, add a modified version to our actual program
-tempProgram.commands.forEach(cmd => {
+tempProgram.commands.forEach((cmd) => {
-  if (['init', 'dev'].includes(cmd.name())) {
+	if (['dev'].includes(cmd.name())) {
-    // Skip commands we've already defined specially
+		// Skip commands we've already defined specially
-    return;
+		return;
-  }
+	}
 
-  // Create a new command with the same name and description
+	// Create a new command with the same name and description
-  const newCmd = program
+	const newCmd = program.command(cmd.name()).description(cmd.description());
-    .command(cmd.name())
-    .description(cmd.description());
 
-  // Copy all options
+	// Copy all options
-  cmd.options.forEach(opt => {
+	cmd.options.forEach((opt) => {
-    newCmd.option(
+		newCmd.option(opt.flags, opt.description, opt.defaultValue);
-      opt.flags,
+	});
-      opt.description,
-      opt.defaultValue
-    );
-  });
 
-  // Set the action to proxy to dev.js
+	// Set the action to proxy to dev.js
-  newCmd.action(createDevScriptAction(cmd.name()));
+	newCmd.action(createDevScriptAction(cmd.name()));
 });
 
 // Parse the command line arguments
@@ -308,47 +325,56 @@ program.parse(process.argv);
 
 // Add global error handling for unknown commands and options
 process.on('uncaughtException', (err) => {
-  // Check if this is a commander.js unknown option error
+	// Check if this is a commander.js unknown option error
-  if (err.code === 'commander.unknownOption') {
+	if (err.code === 'commander.unknownOption') {
-    const option = err.message.match(/'([^']+)'/)?.[1];
+		const option = err.message.match(/'([^']+)'/)?.[1];
-    const commandArg = process.argv.find(arg => !arg.startsWith('-') && 
+		const commandArg = process.argv.find(
-                                            arg !== 'task-master' && 
+			(arg) =>
-                                            !arg.includes('/') && 
+				!arg.startsWith('-') &&
-                                            arg !== 'node');
+				arg !== 'task-master' &&
-    const command = commandArg || 'unknown';
+				!arg.includes('/') &&
+				arg !== 'node'
+		);
+		const command = commandArg || 'unknown';
 
-    console.error(chalk.red(`Error: Unknown option '${option}'`));
+		console.error(chalk.red(`Error: Unknown option '${option}'`));
-    console.error(chalk.yellow(`Run 'task-master ${command} --help' to see available options for this command`));
+		console.error(
-    process.exit(1);
+			chalk.yellow(
-  }
+				`Run 'task-master ${command} --help' to see available options for this command`
+			)
+		);
+		process.exit(1);
+	}
 
-  // Check if this is a commander.js unknown command error
+	// Check if this is a commander.js unknown command error
-  if (err.code === 'commander.unknownCommand') {
+	if (err.code === 'commander.unknownCommand') {
-    const command = err.message.match(/'([^']+)'/)?.[1];
+		const command = err.message.match(/'([^']+)'/)?.[1];
 
-    console.error(chalk.red(`Error: Unknown command '${command}'`));
+		console.error(chalk.red(`Error: Unknown command '${command}'`));
-    console.error(chalk.yellow(`Run 'task-master --help' to see available commands`));
+		console.error(
-    process.exit(1);
+			chalk.yellow(`Run 'task-master --help' to see available commands`)
-  }
+		);
+		process.exit(1);
+	}
 
-  // Handle other uncaught exceptions
+	// Handle other uncaught exceptions
-  console.error(chalk.red(`Error: ${err.message}`));
+	console.error(chalk.red(`Error: ${err.message}`));
-  if (process.env.DEBUG === '1') {
+	if (process.env.DEBUG === '1') {
-    console.error(err);
+		console.error(err);
-  }
+	}
-  process.exit(1);
+	process.exit(1);
 });
 
 // Show help if no command was provided (just 'task-master' with no args)
 if (process.argv.length <= 2) {
-  displayBanner();
+	displayBanner();
-  displayHelp();
+	displayHelp();
-  process.exit(0);
+	process.exit(0);
 }
 
 // Add exports at the end of the file
 if (typeof module !== 'undefined') {
-  module.exports = {
+	module.exports = {
-    detectCamelCaseFlags
+		detectCamelCaseFlags
-  };
+	};
 }

context/MCP_INTEGRATION.md

@@ -41,39 +41,39 @@ Core functions should follow this pattern to support both CLI and MCP use:
  * @returns {Object|undefined} - Returns data when source is 'mcp'
  */
 function exampleFunction(param1, param2, options = {}) {
-  try {
+	try {
-    // Skip UI for MCP
+		// Skip UI for MCP
-    if (options.source !== 'mcp') {
+		if (options.source !== 'mcp') {
-      displayBanner();
+			displayBanner();
-      console.log(chalk.blue('Processing operation...'));
+			console.log(chalk.blue('Processing operation...'));
-    }
+		}
 
-    // Do the core business logic
+		// Do the core business logic
-    const result = doSomething(param1, param2);
+		const result = doSomething(param1, param2);
 
-    // For MCP, return structured data
+		// For MCP, return structured data
-    if (options.source === 'mcp') {
+		if (options.source === 'mcp') {
-      return {
+			return {
-        success: true,
+				success: true,
-        data: result
+				data: result
-      };
+			};
-    }
+		}
 
-    // For CLI, display output
+		// For CLI, display output
-    console.log(chalk.green('Operation completed successfully!'));
+		console.log(chalk.green('Operation completed successfully!'));
-  } catch (error) {
+	} catch (error) {
-    // Handle errors based on source
+		// Handle errors based on source
-    if (options.source === 'mcp') {
+		if (options.source === 'mcp') {
-      return {
+			return {
-        success: false,
+				success: false,
-        error: error.message
+				error: error.message
-      };
+			};
-    }
+		}
 
-    // CLI error handling
+		// CLI error handling
-    console.error(chalk.red(`Error: ${error.message}`));
+		console.error(chalk.red(`Error: ${error.message}`));
-    process.exit(1);
+		process.exit(1);
-  }
+	}
 }
 ```
 
@@ -89,17 +89,17 @@ export const simpleFunction = adaptForMcp(originalFunction);
 
 // Split implementation - completely different code paths for CLI vs MCP
 export const complexFunction = sourceSplitFunction(
-  // CLI version with UI
+	// CLI version with UI
-  function(param1, param2) {
+	function (param1, param2) {
-    displayBanner();
+		displayBanner();
-    console.log(`Processing ${param1}...`);
+		console.log(`Processing ${param1}...`);
-    // ... CLI implementation
+		// ... CLI implementation
-  },
+	},
-  // MCP version with structured return
+	// MCP version with structured return
-  function(param1, param2, options = {}) {
+	function (param1, param2, options = {}) {
-    // ... MCP implementation
+		// ... MCP implementation
-    return { success: true, data };
+		return { success: true, data };
-  }
+	}
 );
 ```
 
@@ -119,39 +119,39 @@ When adding new features, follow these steps to ensure CLI and MCP compatibility
 ```javascript
 // In scripts/modules/task-manager.js
 export async function newFeature(param1, param2, options = {}) {
-  try {
+	try {
-    // Source-specific UI
+		// Source-specific UI
-    if (options.source !== 'mcp') {
+		if (options.source !== 'mcp') {
-      displayBanner();
+			displayBanner();
-      console.log(chalk.blue('Running new feature...'));
+			console.log(chalk.blue('Running new feature...'));
-    }
+		}
 
-    // Shared core logic
+		// Shared core logic
-    const result = processFeature(param1, param2);
+		const result = processFeature(param1, param2);
 
-    // Source-specific return handling
+		// Source-specific return handling
-    if (options.source === 'mcp') {
+		if (options.source === 'mcp') {
-      return {
+			return {
-        success: true,
+				success: true,
-        data: result
+				data: result
-      };
+			};
-    }
+		}
 
-    // CLI output
+		// CLI output
-    console.log(chalk.green('Feature completed successfully!'));
+		console.log(chalk.green('Feature completed successfully!'));
-    displayOutput(result);
+		displayOutput(result);
-  } catch (error) {
+	} catch (error) {
-    // Error handling based on source
+		// Error handling based on source
-    if (options.source === 'mcp') {
+		if (options.source === 'mcp') {
-      return {
+			return {
-        success: false,
+				success: false,
-        error: error.message
+				error: error.message
-      };
+			};
-    }
+		}
 
-    console.error(chalk.red(`Error: ${error.message}`));
+		console.error(chalk.red(`Error: ${error.message}`));
-    process.exit(1);
+		process.exit(1);
-  }
+	}
 }
 ```
 
@@ -163,12 +163,12 @@ import { newFeature } from '../../../scripts/modules/task-manager.js';
 
 // Add to exports
 export default {
-  // ... existing functions
+	// ... existing functions
 
-  async newFeature(args = {}, options = {}) {
+	async newFeature(args = {}, options = {}) {
-    const { param1, param2 } = args;
+		const { param1, param2 } = args;
-    return executeFunction(newFeature, [param1, param2], options);
+		return executeFunction(newFeature, [param1, param2], options);
-  }
+	}
 };
 ```
 
@@ -177,8 +177,8 @@ export default {
 ```javascript
 // In mcp-server/src/tools/utils.js
 const commandMap = {
-  // ... existing mappings
+	// ... existing mappings
-  'new-feature': 'newFeature'
+	'new-feature': 'newFeature'
 };
 ```
 
@@ -186,53 +186,53 @@ const commandMap = {
 
 ```javascript
 // In mcp-server/src/tools/newFeature.js
-import { z } from "zod";
+import { z } from 'zod';
 import {
-  executeTaskMasterCommand,
+	executeTaskMasterCommand,
-  createContentResponse,
+	createContentResponse,
-  createErrorResponse,
+	createErrorResponse
-} from "./utils.js";
+} from './utils.js';
 
 export function registerNewFeatureTool(server) {
-  server.addTool({
+	server.addTool({
-    name: "newFeature",
+		name: 'newFeature',
-    description: "Run the new feature",
+		description: 'Run the new feature',
-    parameters: z.object({
+		parameters: z.object({
-      param1: z.string().describe("First parameter"),
+			param1: z.string().describe('First parameter'),
-      param2: z.number().optional().describe("Second parameter"),
+			param2: z.number().optional().describe('Second parameter'),
-      file: z.string().optional().describe("Path to the tasks file"),
+			file: z.string().optional().describe('Path to the tasks file'),
-      projectRoot: z.string().describe("Root directory of the project")
+			projectRoot: z.string().describe('Root directory of the project')
-    }),
+		}),
-    execute: async (args, { log }) => {
+		execute: async (args, { log }) => {
-      try {
+			try {
-        log.info(`Running new feature with args: ${JSON.stringify(args)}`);
+				log.info(`Running new feature with args: ${JSON.stringify(args)}`);
 
-        const cmdArgs = [];
+				const cmdArgs = [];
-        if (args.param1) cmdArgs.push(`--param1=${args.param1}`);
+				if (args.param1) cmdArgs.push(`--param1=${args.param1}`);
-        if (args.param2) cmdArgs.push(`--param2=${args.param2}`);
+				if (args.param2) cmdArgs.push(`--param2=${args.param2}`);
-        if (args.file) cmdArgs.push(`--file=${args.file}`);
+				if (args.file) cmdArgs.push(`--file=${args.file}`);
 
-        const projectRoot = args.projectRoot;
+				const projectRoot = args.projectRoot;
 
-        // Execute the command
+				// Execute the command
-        const result = await executeTaskMasterCommand(
+				const result = await executeTaskMasterCommand(
-          "new-feature",
+					'new-feature',
-          log,
+					log,
-          cmdArgs,
+					cmdArgs,
-          projectRoot
+					projectRoot
-        );
+				);
 
-        if (!result.success) {
+				if (!result.success) {
-          throw new Error(result.error);
+					throw new Error(result.error);
-        }
+				}
 
-        return createContentResponse(result.stdout);
+				return createContentResponse(result.stdout);
-      } catch (error) {
+			} catch (error) {
-        log.error(`Error in new feature: ${error.message}`);
+				log.error(`Error in new feature: ${error.message}`);
-        return createErrorResponse(`Error in new feature: ${error.message}`);
+				return createErrorResponse(`Error in new feature: ${error.message}`);
-      }
+			}
-    },
+		}
-  });
+	});
 }
 ```
 
@@ -240,11 +240,11 @@ export function registerNewFeatureTool(server) {
 
 ```javascript
 // In mcp-server/src/tools/index.js
-import { registerNewFeatureTool } from "./newFeature.js";
+import { registerNewFeatureTool } from './newFeature.js';
 
 export function registerTaskMasterTools(server) {
-  // ... existing registrations
+	// ... existing registrations
-  registerNewFeatureTool(server);
+	registerNewFeatureTool(server);
 }
 ```
 

docs/README.md

@@ -0,0 +1,22 @@
+# Task Master Documentation
+
+Welcome to the Task Master documentation. Use the links below to navigate to the information you need:
+
+## Getting Started
+
+- [Configuration Guide](configuration.md) - Set up environment variables and customize Task Master
+- [Tutorial](tutorial.md) - Step-by-step guide to getting started with Task Master
+
+## Reference
+
+- [Command Reference](command-reference.md) - Complete list of all available commands
+- [Task Structure](task-structure.md) - Understanding the task format and features
+
+## Examples & Licensing
+
+- [Example Interactions](examples.md) - Common Cursor AI interaction examples
+- [Licensing Information](licensing.md) - Detailed information about the license
+
+## Need More Help?
+
+If you can't find what you're looking for in these docs, please check the [main README](../README.md) or visit our [GitHub repository](https://github.com/eyaltoledano/claude-task-master).

docs/ai-client-utils-example.md

@@ -7,56 +7,54 @@ This document provides examples of how to use the new AI client utilities with A
 ```javascript
 // In your direct function implementation:
 import {
-  getAnthropicClientForMCP, 
+	getAnthropicClientForMCP,
-  getModelConfig, 
+	getModelConfig,
-  handleClaudeError 
+	handleClaudeError
 } from '../utils/ai-client-utils.js';
 
 export async function someAiOperationDirect(args, log, context) {
-  try {
+	try {
-    // Initialize Anthropic client with session from context
+		// Initialize Anthropic client with session from context
-    const client = getAnthropicClientForMCP(context.session, log);
+		const client = getAnthropicClientForMCP(context.session, log);
 
-    // Get model configuration with defaults or session overrides
+		// Get model configuration with defaults or session overrides
-    const modelConfig = getModelConfig(context.session);
+		const modelConfig = getModelConfig(context.session);
 
-    // Make API call with proper error handling
+		// Make API call with proper error handling
-    try {
+		try {
-      const response = await client.messages.create({
+			const response = await client.messages.create({
-        model: modelConfig.model,
+				model: modelConfig.model,
-        max_tokens: modelConfig.maxTokens,
+				max_tokens: modelConfig.maxTokens,
-        temperature: modelConfig.temperature,
+				temperature: modelConfig.temperature,
-        messages: [
+				messages: [{ role: 'user', content: 'Your prompt here' }]
-          { role: 'user', content: 'Your prompt here' }
+			});
-        ]
-      });
 
-      return {
+			return {
-        success: true,
+				success: true,
-        data: response
+				data: response
-      };
+			};
-    } catch (apiError) {
+		} catch (apiError) {
-      // Use helper to get user-friendly error message
+			// Use helper to get user-friendly error message
-      const friendlyMessage = handleClaudeError(apiError);
+			const friendlyMessage = handleClaudeError(apiError);
 
-      return {
+			return {
-        success: false,
+				success: false,
-        error: {
+				error: {
-          code: 'AI_API_ERROR',
+					code: 'AI_API_ERROR',
-          message: friendlyMessage
+					message: friendlyMessage
-        }
+				}
-      };
+			};
-    }
+		}
-  } catch (error) {
+	} catch (error) {
-    // Handle client initialization errors
+		// Handle client initialization errors
-    return {
+		return {
-      success: false,
+			success: false,
-      error: {
+			error: {
-        code: 'AI_CLIENT_ERROR',
+				code: 'AI_CLIENT_ERROR',
-        message: error.message
+				message: error.message
-      }
+			}
-    };
+		};
-  }
+	}
 }
 ```
 
@@ -64,86 +62,85 @@ export async function someAiOperationDirect(args, log, context) {
 
 ```javascript
 // In your MCP tool implementation:
-import { AsyncOperationManager, StatusCodes } from '../../utils/async-operation-manager.js';
+import {
+	AsyncOperationManager,
+	StatusCodes
+} from '../../utils/async-operation-manager.js';
 import { someAiOperationDirect } from '../../core/direct-functions/some-ai-operation.js';
 
 export async function someAiOperation(args, context) {
-  const { session, mcpLog } = context;
+	const { session, mcpLog } = context;
-  const log = mcpLog || console;
+	const log = mcpLog || console;
 
-  try {
+	try {
-    // Create operation description
+		// Create operation description
-    const operationDescription = `AI operation: ${args.someParam}`;
+		const operationDescription = `AI operation: ${args.someParam}`;
 
-    // Start async operation
+		// Start async operation
-    const operation = AsyncOperationManager.createOperation(
+		const operation = AsyncOperationManager.createOperation(
-      operationDescription,
+			operationDescription,
-      async (reportProgress) => {
+			async (reportProgress) => {
-        try {
+				try {
-          // Initial progress report
+					// Initial progress report
-          reportProgress({
+					reportProgress({
-            progress: 0,
+						progress: 0,
-            status: 'Starting AI operation...'
+						status: 'Starting AI operation...'
-          });
+					});
 
-          // Call direct function with session and progress reporting
+					// Call direct function with session and progress reporting
-          const result = await someAiOperationDirect(
+					const result = await someAiOperationDirect(args, log, {
-            args, 
+						reportProgress,
-            log, 
+						mcpLog: log,
-            {
+						session
-              reportProgress,
+					});
-              mcpLog: log,
-              session
-            }
-          );
 
-          // Final progress update
+					// Final progress update
-          reportProgress({
+					reportProgress({
-            progress: 100,
+						progress: 100,
-            status: result.success ? 'Operation completed' : 'Operation failed',
+						status: result.success ? 'Operation completed' : 'Operation failed',
-            result: result.data,
+						result: result.data,
-            error: result.error
+						error: result.error
-          });
+					});
 
-          return result;
+					return result;
-        } catch (error) {
+				} catch (error) {
-          // Handle errors in the operation
+					// Handle errors in the operation
-          reportProgress({
+					reportProgress({
-            progress: 100,
+						progress: 100,
-            status: 'Operation failed',
+						status: 'Operation failed',
-            error: {
+						error: {
-              message: error.message,
+							message: error.message,
-              code: error.code || 'OPERATION_FAILED'
+							code: error.code || 'OPERATION_FAILED'
-            }
+						}
-          });
+					});
-          throw error;
+					throw error;
-        }
+				}
-      }
+			}
-    );
+		);
 
-    // Return immediate response with operation ID
+		// Return immediate response with operation ID
-    return {
+		return {
-      status: StatusCodes.ACCEPTED,
+			status: StatusCodes.ACCEPTED,
-      body: {
+			body: {
-        success: true,
+				success: true,
-        message: 'Operation started',
+				message: 'Operation started',
-        operationId: operation.id
+				operationId: operation.id
-      }
+			}
-    };
+		};
-  } catch (error) {
+	} catch (error) {
-    // Handle errors in the MCP tool
+		// Handle errors in the MCP tool
-    log.error(`Error in someAiOperation: ${error.message}`);
+		log.error(`Error in someAiOperation: ${error.message}`);
-    return {
+		return {
-      status: StatusCodes.INTERNAL_SERVER_ERROR,
+			status: StatusCodes.INTERNAL_SERVER_ERROR,
-      body: {
+			body: {
-        success: false,
+				success: false,
-        error: {
+				error: {
-          code: 'OPERATION_FAILED',
+					code: 'OPERATION_FAILED',
-          message: error.message
+					message: error.message
-        }
+				}
-      }
+			}
-    };
+		};
-  }
+	}
 }
 ```
 
@@ -152,57 +149,55 @@ export async function someAiOperation(args, context) {
 ```javascript
 // In your direct function:
 import {
-  getPerplexityClientForMCP, 
+	getPerplexityClientForMCP,
-  getBestAvailableAIModel 
+	getBestAvailableAIModel
 } from '../utils/ai-client-utils.js';
 
 export async function researchOperationDirect(args, log, context) {
-  try {
+	try {
-    // Get the best AI model for this operation based on needs
+		// Get the best AI model for this operation based on needs
-    const { type, client } = await getBestAvailableAIModel(
+		const { type, client } = await getBestAvailableAIModel(
-      context.session, 
+			context.session,
-      { requiresResearch: true },
+			{ requiresResearch: true },
-      log
+			log
-    );
+		);
 
-    // Report which model we're using
+		// Report which model we're using
-    if (context.reportProgress) {
+		if (context.reportProgress) {
-      await context.reportProgress({
+			await context.reportProgress({
-        progress: 10,
+				progress: 10,
-        status: `Using ${type} model for research...`
+				status: `Using ${type} model for research...`
-      });
+			});
-    }
+		}
 
-    // Make API call based on the model type
+		// Make API call based on the model type
-    if (type === 'perplexity') {
+		if (type === 'perplexity') {
-      // Call Perplexity
+			// Call Perplexity
-      const response = await client.chat.completions.create({
+			const response = await client.chat.completions.create({
-        model: context.session?.env?.PERPLEXITY_MODEL || 'sonar-medium-online',
+				model: context.session?.env?.PERPLEXITY_MODEL || 'sonar-medium-online',
-        messages: [
+				messages: [{ role: 'user', content: args.researchQuery }],
-          { role: 'user', content: args.researchQuery }
+				temperature: 0.1
-        ],
+			});
-        temperature: 0.1
-      });
 
-      return {
+			return {
-        success: true,
+				success: true,
-        data: response.choices[0].message.content
+				data: response.choices[0].message.content
-      };
+			};
-    } else {
+		} else {
-      // Call Claude as fallback
+			// Call Claude as fallback
-      // (Implementation depends on specific needs)
+			// (Implementation depends on specific needs)
-      // ...
+			// ...
-    }
+		}
-  } catch (error) {
+	} catch (error) {
-    // Handle errors
+		// Handle errors
-    return {
+		return {
-      success: false,
+			success: false,
-      error: {
+			error: {
-        code: 'RESEARCH_ERROR',
+				code: 'RESEARCH_ERROR',
-        message: error.message
+				message: error.message
-      }
+			}
-    };
+		};
-  }
+	}
 }
 ```
 
@@ -214,9 +209,9 @@ import { getModelConfig } from '../utils/ai-client-utils.js';
 
 // Using custom defaults for a specific operation
 const operationDefaults = {
-  model: 'claude-3-haiku-20240307',  // Faster, smaller model
+	model: 'claude-3-haiku-20240307', // Faster, smaller model
-  maxTokens: 1000,                  // Lower token limit
+	maxTokens: 1000, // Lower token limit
-  temperature: 0.2                  // Lower temperature for more deterministic output
+	temperature: 0.2 // Lower temperature for more deterministic output
 };
 
 // Get model config with operation-specific defaults
@@ -224,30 +219,34 @@ const modelConfig = getModelConfig(context.session, operationDefaults);
 
 // Now use modelConfig in your API calls
 const response = await client.messages.create({
-  model: modelConfig.model,
+	model: modelConfig.model,
-  max_tokens: modelConfig.maxTokens,
+	max_tokens: modelConfig.maxTokens,
-  temperature: modelConfig.temperature,
+	temperature: modelConfig.temperature
-  // Other parameters...
+	// Other parameters...
 });
 ```
 
 ## Best Practices
 
 1. **Error Handling**:
+
    - Always use try/catch blocks around both client initialization and API calls
    - Use `handleClaudeError` to provide user-friendly error messages
    - Return standardized error objects with code and message
 
 2. **Progress Reporting**:
+
    - Report progress at key points (starting, processing, completing)
    - Include meaningful status messages
    - Include error details in progress reports when failures occur
 
 3. **Session Handling**:
+
    - Always pass the session from the context to the AI client getters
    - Use `getModelConfig` to respect user settings from session
 
 4. **Model Selection**:
+
    - Use `getBestAvailableAIModel` when you need to select between different models
    - Set `requiresResearch: true` when you need Perplexity capabilities
 

docs/command-reference.md

@@ -0,0 +1,205 @@
+# Task Master Command Reference
+
+Here's a comprehensive reference of all available commands:
+
+## Parse PRD
+
+```bash
+# Parse a PRD file and generate tasks
+task-master parse-prd <prd-file.txt>
+
+# Limit the number of tasks generated
+task-master parse-prd <prd-file.txt> --num-tasks=10
+```
+
+## List Tasks
+
+```bash
+# List all tasks
+task-master list
+
+# List tasks with a specific status
+task-master list --status=<status>
+
+# List tasks with subtasks
+task-master list --with-subtasks
+
+# List tasks with a specific status and include subtasks
+task-master list --status=<status> --with-subtasks
+```
+
+## Show Next Task
+
+```bash
+# Show the next task to work on based on dependencies and status
+task-master next
+```
+
+## Show Specific Task
+
+```bash
+# Show details of a specific task
+task-master show <id>
+# or
+task-master show --id=<id>
+
+# View a specific subtask (e.g., subtask 2 of task 1)
+task-master show 1.2
+```
+
+## Update Tasks
+
+```bash
+# Update tasks from a specific ID and provide context
+task-master update --from=<id> --prompt="<prompt>"
+```
+
+## Update a Specific Task
+
+```bash
+# Update a single task by ID with new information
+task-master update-task --id=<id> --prompt="<prompt>"
+
+# Use research-backed updates with Perplexity AI
+task-master update-task --id=<id> --prompt="<prompt>" --research
+```
+
+## Update a Subtask
+
+```bash
+# Append additional information to a specific subtask
+task-master update-subtask --id=<parentId.subtaskId> --prompt="<prompt>"
+
+# Example: Add details about API rate limiting to subtask 2 of task 5
+task-master update-subtask --id=5.2 --prompt="Add rate limiting of 100 requests per minute"
+
+# Use research-backed updates with Perplexity AI
+task-master update-subtask --id=<parentId.subtaskId> --prompt="<prompt>" --research
+```
+
+Unlike the `update-task` command which replaces task information, the `update-subtask` command _appends_ new information to the existing subtask details, marking it with a timestamp. This is useful for iteratively enhancing subtasks while preserving the original content.
+
+## Generate Task Files
+
+```bash
+# Generate individual task files from tasks.json
+task-master generate
+```
+
+## Set Task Status
+
+```bash
+# Set status of a single task
+task-master set-status --id=<id> --status=<status>
+
+# Set status for multiple tasks
+task-master set-status --id=1,2,3 --status=<status>
+
+# Set status for subtasks
+task-master set-status --id=1.1,1.2 --status=<status>
+```
+
+When marking a task as "done", all of its subtasks will automatically be marked as "done" as well.
+
+## Expand Tasks
+
+```bash
+# Expand a specific task with subtasks
+task-master expand --id=<id> --num=<number>
+
+# Expand with additional context
+task-master expand --id=<id> --prompt="<context>"
+
+# Expand all pending tasks
+task-master expand --all
+
+# Force regeneration of subtasks for tasks that already have them
+task-master expand --all --force
+
+# Research-backed subtask generation for a specific task
+task-master expand --id=<id> --research
+
+# Research-backed generation for all tasks
+task-master expand --all --research
+```
+
+## Clear Subtasks
+
+```bash
+# Clear subtasks from a specific task
+task-master clear-subtasks --id=<id>
+
+# Clear subtasks from multiple tasks
+task-master clear-subtasks --id=1,2,3
+
+# Clear subtasks from all tasks
+task-master clear-subtasks --all
+```
+
+## Analyze Task Complexity
+
+```bash
+# Analyze complexity of all tasks
+task-master analyze-complexity
+
+# Save report to a custom location
+task-master analyze-complexity --output=my-report.json
+
+# Use a specific LLM model
+task-master analyze-complexity --model=claude-3-opus-20240229
+
+# Set a custom complexity threshold (1-10)
+task-master analyze-complexity --threshold=6
+
+# Use an alternative tasks file
+task-master analyze-complexity --file=custom-tasks.json
+
+# Use Perplexity AI for research-backed complexity analysis
+task-master analyze-complexity --research
+```
+
+## View Complexity Report
+
+```bash
+# Display the task complexity analysis report
+task-master complexity-report
+
+# View a report at a custom location
+task-master complexity-report --file=my-report.json
+```
+
+## Managing Task Dependencies
+
+```bash
+# Add a dependency to a task
+task-master add-dependency --id=<id> --depends-on=<id>
+
+# Remove a dependency from a task
+task-master remove-dependency --id=<id> --depends-on=<id>
+
+# Validate dependencies without fixing them
+task-master validate-dependencies
+
+# Find and fix invalid dependencies automatically
+task-master fix-dependencies
+```
+
+## Add a New Task
+
+```bash
+# Add a new task using AI
+task-master add-task --prompt="Description of the new task"
+
+# Add a task with dependencies
+task-master add-task --prompt="Description" --dependencies=1,2,3
+
+# Add a task with priority
+task-master add-task --prompt="Description" --priority=high
+```
+
+## Initialize a Project
+
+```bash
+# Initialize a new project with Task Master structure
+task-master init
+```

docs/configuration.md

@@ -0,0 +1,65 @@
+# Configuration
+
+Task Master can be configured through environment variables in a `.env` file at the root of your project.
+
+## Required Configuration
+
+- `ANTHROPIC_API_KEY`: Your Anthropic API key for Claude (Example: `ANTHROPIC_API_KEY=sk-ant-api03-...`)
+
+## Optional Configuration
+
+- `MODEL` (Default: `"claude-3-7-sonnet-20250219"`): Claude model to use (Example: `MODEL=claude-3-opus-20240229`)
+- `MAX_TOKENS` (Default: `"4000"`): Maximum tokens for responses (Example: `MAX_TOKENS=8000`)
+- `TEMPERATURE` (Default: `"0.7"`): Temperature for model responses (Example: `TEMPERATURE=0.5`)
+- `DEBUG` (Default: `"false"`): Enable debug logging (Example: `DEBUG=true`)
+- `LOG_LEVEL` (Default: `"info"`): Console output level (Example: `LOG_LEVEL=debug`)
+- `DEFAULT_SUBTASKS` (Default: `"3"`): Default subtask count (Example: `DEFAULT_SUBTASKS=5`)
+- `DEFAULT_PRIORITY` (Default: `"medium"`): Default priority (Example: `DEFAULT_PRIORITY=high`)
+- `PROJECT_NAME` (Default: `"MCP SaaS MVP"`): Project name in metadata (Example: `PROJECT_NAME=My Awesome Project`)
+- `PROJECT_VERSION` (Default: `"1.0.0"`): Version in metadata (Example: `PROJECT_VERSION=2.1.0`)
+- `PERPLEXITY_API_KEY`: For research-backed features (Example: `PERPLEXITY_API_KEY=pplx-...`)
+- `PERPLEXITY_MODEL` (Default: `"sonar-medium-online"`): Perplexity model (Example: `PERPLEXITY_MODEL=sonar-large-online`)
+
+## Example .env File
+
+```
+# Required
+ANTHROPIC_API_KEY=sk-ant-api03-your-api-key
+
+# Optional - Claude Configuration
+MODEL=claude-3-7-sonnet-20250219
+MAX_TOKENS=4000
+TEMPERATURE=0.7
+
+# Optional - Perplexity API for Research
+PERPLEXITY_API_KEY=pplx-your-api-key
+PERPLEXITY_MODEL=sonar-medium-online
+
+# Optional - Project Info
+PROJECT_NAME=My Project
+PROJECT_VERSION=1.0.0
+
+# Optional - Application Configuration
+DEFAULT_SUBTASKS=3
+DEFAULT_PRIORITY=medium
+DEBUG=false
+LOG_LEVEL=info
+```
+
+## Troubleshooting
+
+### If `task-master init` doesn't respond:
+
+Try running it with Node directly:
+
+```bash
+node node_modules/claude-task-master/scripts/init.js
+```
+
+Or clone the repository and run:
+
+```bash
+git clone https://github.com/eyaltoledano/claude-task-master.git
+cd claude-task-master
+node scripts/init.js
+```

docs/examples.md

@@ -0,0 +1,53 @@
+# Example Cursor AI Interactions
+
+Here are some common interactions with Cursor AI when using Task Master:
+
+## Starting a new project
+
+```
+I've just initialized a new project with Claude Task Master. I have a PRD at scripts/prd.txt.
+Can you help me parse it and set up the initial tasks?
+```
+
+## Working on tasks
+
+```
+What's the next task I should work on? Please consider dependencies and priorities.
+```
+
+## Implementing a specific task
+
+```
+I'd like to implement task 4. Can you help me understand what needs to be done and how to approach it?
+```
+
+## Managing subtasks
+
+```
+I need to regenerate the subtasks for task 3 with a different approach. Can you help me clear and regenerate them?
+```
+
+## Handling changes
+
+```
+We've decided to use MongoDB instead of PostgreSQL. Can you update all future tasks to reflect this change?
+```
+
+## Completing work
+
+```
+I've finished implementing the authentication system described in task 2. All tests are passing.
+Please mark it as complete and tell me what I should work on next.
+```
+
+## Analyzing complexity
+
+```
+Can you analyze the complexity of our tasks to help me understand which ones need to be broken down further?
+```
+
+## Viewing complexity report
+
+```
+Can you show me the complexity report in a more readable format?
+```

docs/licensing.md

@@ -0,0 +1,18 @@
+# Licensing
+
+Task Master is licensed under the MIT License with Commons Clause. This means you can:
+
+## ✅ Allowed:
+
+- Use Task Master for any purpose (personal, commercial, academic)
+- Modify the code
+- Distribute copies
+- Create and sell products built using Task Master
+
+## ❌ Not Allowed:
+
+- Sell Task Master itself
+- Offer Task Master as a hosted service
+- Create competing products based on Task Master
+
+See the [LICENSE](../LICENSE) file for the complete license text.

docs/task-structure.md

@@ -0,0 +1,139 @@
+# Task Structure
+
+Tasks in Task Master follow a specific format designed to provide comprehensive information for both humans and AI assistants.
+
+## Task Fields in tasks.json
+
+Tasks in tasks.json have the following structure:
+
+- `id`: Unique identifier for the task (Example: `1`)
+- `title`: Brief, descriptive title of the task (Example: `"Initialize Repo"`)
+- `description`: Concise description of what the task involves (Example: `"Create a new repository, set up initial structure."`)
+- `status`: Current state of the task (Example: `"pending"`, `"done"`, `"deferred"`)
+- `dependencies`: IDs of tasks that must be completed before this task (Example: `[1, 2]`)
+  - Dependencies are displayed with status indicators (✅ for completed, ⏱️ for pending)
+  - This helps quickly identify which prerequisite tasks are blocking work
+- `priority`: Importance level of the task (Example: `"high"`, `"medium"`, `"low"`)
+- `details`: In-depth implementation instructions (Example: `"Use GitHub client ID/secret, handle callback, set session token."`)
+- `testStrategy`: Verification approach (Example: `"Deploy and call endpoint to confirm 'Hello World' response."`)
+- `subtasks`: List of smaller, more specific tasks that make up the main task (Example: `[{"id": 1, "title": "Configure OAuth", ...}]`)
+
+## Task File Format
+
+Individual task files follow this format:
+
+```
+# Task ID: <id>
+# Title: <title>
+# Status: <status>
+# Dependencies: <comma-separated list of dependency IDs>
+# Priority: <priority>
+# Description: <brief description>
+# Details:
+<detailed implementation notes>
+
+# Test Strategy:
+<verification approach>
+```
+
+## Features in Detail
+
+### Analyzing Task Complexity
+
+The `analyze-complexity` command:
+
+- Analyzes each task using AI to assess its complexity on a scale of 1-10
+- Recommends optimal number of subtasks based on configured DEFAULT_SUBTASKS
+- Generates tailored prompts for expanding each task
+- Creates a comprehensive JSON report with ready-to-use commands
+- Saves the report to scripts/task-complexity-report.json by default
+
+The generated report contains:
+
+- Complexity analysis for each task (scored 1-10)
+- Recommended number of subtasks based on complexity
+- AI-generated expansion prompts customized for each task
+- Ready-to-run expansion commands directly within each task analysis
+
+### Viewing Complexity Report
+
+The `complexity-report` command:
+
+- Displays a formatted, easy-to-read version of the complexity analysis report
+- Shows tasks organized by complexity score (highest to lowest)
+- Provides complexity distribution statistics (low, medium, high)
+- Highlights tasks recommended for expansion based on threshold score
+- Includes ready-to-use expansion commands for each complex task
+- If no report exists, offers to generate one on the spot
+
+### Smart Task Expansion
+
+The `expand` command automatically checks for and uses the complexity report:
+
+When a complexity report exists:
+
+- Tasks are automatically expanded using the recommended subtask count and prompts
+- When expanding all tasks, they're processed in order of complexity (highest first)
+- Research-backed generation is preserved from the complexity analysis
+- You can still override recommendations with explicit command-line options
+
+Example workflow:
+
+```bash
+# Generate the complexity analysis report with research capabilities
+task-master analyze-complexity --research
+
+# Review the report in a readable format
+task-master complexity-report
+
+# Expand tasks using the optimized recommendations
+task-master expand --id=8
+# or expand all tasks
+task-master expand --all
+```
+
+### Finding the Next Task
+
+The `next` command:
+
+- Identifies tasks that are pending/in-progress and have all dependencies satisfied
+- Prioritizes tasks by priority level, dependency count, and task ID
+- Displays comprehensive information about the selected task:
+  - Basic task details (ID, title, priority, dependencies)
+  - Implementation details
+  - Subtasks (if they exist)
+- Provides contextual suggested actions:
+  - Command to mark the task as in-progress
+  - Command to mark the task as done
+  - Commands for working with subtasks
+
+### Viewing Specific Task Details
+
+The `show` command:
+
+- Displays comprehensive details about a specific task or subtask
+- Shows task status, priority, dependencies, and detailed implementation notes
+- For parent tasks, displays all subtasks and their status
+- For subtasks, shows parent task relationship
+- Provides contextual action suggestions based on the task's state
+- Works with both regular tasks and subtasks (using the format taskId.subtaskId)
+
+## Best Practices for AI-Driven Development
+
+1. **Start with a detailed PRD**: The more detailed your PRD, the better the generated tasks will be.
+
+2. **Review generated tasks**: After parsing the PRD, review the tasks to ensure they make sense and have appropriate dependencies.
+
+3. **Analyze task complexity**: Use the complexity analysis feature to identify which tasks should be broken down further.
+
+4. **Follow the dependency chain**: Always respect task dependencies - the Cursor agent will help with this.
+
+5. **Update as you go**: If your implementation diverges from the plan, use the update command to keep future tasks aligned with your current approach.
+
+6. **Break down complex tasks**: Use the expand command to break down complex tasks into manageable subtasks.
+
+7. **Regenerate task files**: After any updates to tasks.json, regenerate the task files to keep them in sync.
+
+8. **Communicate context to the agent**: When asking the Cursor agent to help with a task, provide context about what you're trying to achieve.
+
+9. **Validate dependencies**: Periodically run the validate-dependencies command to check for invalid or circular dependencies.

docs/tutorial.md

@@ -0,0 +1,361 @@
+# Task Master Tutorial
+
+This tutorial will guide you through setting up and using Task Master for AI-driven development.
+
+## Initial Setup
+
+There are two ways to set up Task Master: using MCP (recommended) or via npm installation.
+
+### Option 1: Using MCP (Recommended)
+
+MCP (Model Control Protocol) provides the easiest way to get started with Task Master directly in your editor.
+
+1. **Install the package**
+
+```bash
+npm i -g task-master-ai
+```
+
+2. **Add the MCP config to your editor** (Cursor recommended, but it works with other text editors):
+
+```json
+{
+	"mcpServers": {
+		"taskmaster-ai": {
+			"command": "npx",
+			"args": ["-y", "task-master-mcp"],
+			"env": {
+				"ANTHROPIC_API_KEY": "YOUR_ANTHROPIC_API_KEY_HERE",
+				"PERPLEXITY_API_KEY": "YOUR_PERPLEXITY_API_KEY_HERE",
+				"MODEL": "claude-3-7-sonnet-20250219",
+				"PERPLEXITY_MODEL": "sonar-pro",
+				"MAX_TOKENS": 64000,
+				"TEMPERATURE": 0.2,
+				"DEFAULT_SUBTASKS": 5,
+				"DEFAULT_PRIORITY": "medium"
+			}
+		}
+	}
+}
+```
+
+2. **Enable the MCP** in your editor settings
+
+3. **Prompt the AI** to initialize Task Master:
+
+```
+Can you please initialize taskmaster-ai into my project?
+```
+
+The AI will:
+
+- Create necessary project structure
+- Set up initial configuration files
+- Guide you through the rest of the process
+
+4. Place your PRD document in the `scripts/` directory (e.g., `scripts/prd.txt`)
+
+5. **Use natural language commands** to interact with Task Master:
+
+```
+Can you parse my PRD at scripts/prd.txt?
+What's the next task I should work on?
+Can you help me implement task 3?
+```
+
+### Option 2: Manual Installation
+
+If you prefer to use the command line interface directly:
+
+```bash
+# Install globally
+npm install -g task-master-ai
+
+# OR install locally within your project
+npm install task-master-ai
+```
+
+Initialize a new project:
+
+```bash
+# If installed globally
+task-master init
+
+# If installed locally
+npx task-master-init
+```
+
+This will prompt you for project details and set up a new project with the necessary files and structure.
+
+## Common Commands
+
+After setting up Task Master, you can use these commands (either via AI prompts or CLI):
+
+```bash
+# Parse a PRD and generate tasks
+task-master parse-prd your-prd.txt
+
+# List all tasks
+task-master list
+
+# Show the next task to work on
+task-master next
+
+# Generate task files
+task-master generate
+```
+
+## Setting up Cursor AI Integration
+
+Task Master is designed to work seamlessly with [Cursor AI](https://www.cursor.so/), providing a structured workflow for AI-driven development.
+
+### Using Cursor with MCP (Recommended)
+
+If you've already set up Task Master with MCP in Cursor, the integration is automatic. You can simply use natural language to interact with Task Master:
+
+```
+What tasks are available to work on next?
+Can you analyze the complexity of our tasks?
+I'd like to implement task 4. What does it involve?
+```
+
+### Manual Cursor Setup
+
+If you're not using MCP, you can still set up Cursor integration:
+
+1. After initializing your project, open it in Cursor
+2. The `.cursor/rules/dev_workflow.mdc` file is automatically loaded by Cursor, providing the AI with knowledge about the task management system
+3. Place your PRD document in the `scripts/` directory (e.g., `scripts/prd.txt`)
+4. Open Cursor's AI chat and switch to Agent mode
+
+### Alternative MCP Setup in Cursor
+
+You can also set up the MCP server in Cursor settings:
+
+1. Go to Cursor settings
+2. Navigate to the MCP section
+3. Click on "Add New MCP Server"
+4. Configure with the following details:
+   - Name: "Task Master"
+   - Type: "Command"
+   - Command: "npx -y task-master-mcp"
+5. Save the settings
+
+Once configured, you can interact with Task Master's task management commands directly through Cursor's interface, providing a more integrated experience.
+
+## Initial Task Generation
+
+In Cursor's AI chat, instruct the agent to generate tasks from your PRD:
+
+```
+Please use the task-master parse-prd command to generate tasks from my PRD. The PRD is located at scripts/prd.txt.
+```
+
+The agent will execute:
+
+```bash
+task-master parse-prd scripts/prd.txt
+```
+
+This will:
+
+- Parse your PRD document
+- Generate a structured `tasks.json` file with tasks, dependencies, priorities, and test strategies
+- The agent will understand this process due to the Cursor rules
+
+### Generate Individual Task Files
+
+Next, ask the agent to generate individual task files:
+
+```
+Please generate individual task files from tasks.json
+```
+
+The agent will execute:
+
+```bash
+task-master generate
+```
+
+This creates individual task files in the `tasks/` directory (e.g., `task_001.txt`, `task_002.txt`), making it easier to reference specific tasks.
+
+## AI-Driven Development Workflow
+
+The Cursor agent is pre-configured (via the rules file) to follow this workflow:
+
+### 1. Task Discovery and Selection
+
+Ask the agent to list available tasks:
+
+```
+What tasks are available to work on next?
+```
+
+The agent will:
+
+- Run `task-master list` to see all tasks
+- Run `task-master next` to determine the next task to work on
+- Analyze dependencies to determine which tasks are ready to be worked on
+- Prioritize tasks based on priority level and ID order
+- Suggest the next task(s) to implement
+
+### 2. Task Implementation
+
+When implementing a task, the agent will:
+
+- Reference the task's details section for implementation specifics
+- Consider dependencies on previous tasks
+- Follow the project's coding standards
+- Create appropriate tests based on the task's testStrategy
+
+You can ask:
+
+```
+Let's implement task 3. What does it involve?
+```
+
+### 3. Task Verification
+
+Before marking a task as complete, verify it according to:
+
+- The task's specified testStrategy
+- Any automated tests in the codebase
+- Manual verification if required
+
+### 4. Task Completion
+
+When a task is completed, tell the agent:
+
+```
+Task 3 is now complete. Please update its status.
+```
+
+The agent will execute:
+
+```bash
+task-master set-status --id=3 --status=done
+```
+
+### 5. Handling Implementation Drift
+
+If during implementation, you discover that:
+
+- The current approach differs significantly from what was planned
+- Future tasks need to be modified due to current implementation choices
+- New dependencies or requirements have emerged
+
+Tell the agent:
+
+```
+We've changed our approach. We're now using Express instead of Fastify. Please update all future tasks to reflect this change.
+```
+
+The agent will execute:
+
+```bash
+task-master update --from=4 --prompt="Now we are using Express instead of Fastify."
+```
+
+This will rewrite or re-scope subsequent tasks in tasks.json while preserving completed work.
+
+### 6. Breaking Down Complex Tasks
+
+For complex tasks that need more granularity:
+
+```
+Task 5 seems complex. Can you break it down into subtasks?
+```
+
+The agent will execute:
+
+```bash
+task-master expand --id=5 --num=3
+```
+
+You can provide additional context:
+
+```
+Please break down task 5 with a focus on security considerations.
+```
+
+The agent will execute:
+
+```bash
+task-master expand --id=5 --prompt="Focus on security aspects"
+```
+
+You can also expand all pending tasks:
+
+```
+Please break down all pending tasks into subtasks.
+```
+
+The agent will execute:
+
+```bash
+task-master expand --all
+```
+
+For research-backed subtask generation using Perplexity AI:
+
+```
+Please break down task 5 using research-backed generation.
+```
+
+The agent will execute:
+
+```bash
+task-master expand --id=5 --research
+```
+
+## Example Cursor AI Interactions
+
+### Starting a new project
+
+```
+I've just initialized a new project with Claude Task Master. I have a PRD at scripts/prd.txt.
+Can you help me parse it and set up the initial tasks?
+```
+
+### Working on tasks
+
+```
+What's the next task I should work on? Please consider dependencies and priorities.
+```
+
+### Implementing a specific task
+
+```
+I'd like to implement task 4. Can you help me understand what needs to be done and how to approach it?
+```
+
+### Managing subtasks
+
+```
+I need to regenerate the subtasks for task 3 with a different approach. Can you help me clear and regenerate them?
+```
+
+### Handling changes
+
+```
+We've decided to use MongoDB instead of PostgreSQL. Can you update all future tasks to reflect this change?
+```
+
+### Completing work
+
+```
+I've finished implementing the authentication system described in task 2. All tests are passing.
+Please mark it as complete and tell me what I should work on next.
+```
+
+### Analyzing complexity
+
+```
+Can you analyze the complexity of our tasks to help me understand which ones need to be broken down further?
+```
+
+### Viewing complexity report
+
+```
+Can you show me the complexity report in a more readable format?
+```

entries.json

@@ -1,41 +0,0 @@
-import os
-import json
-
-# Path to Cursor's history folder
-history_path = os.path.expanduser('~/Library/Application Support/Cursor/User/History')
-
-# File to search for
-target_file = 'tasks/tasks.json'
-
-# Function to search through all entries.json files
-def search_entries_for_file(history_path, target_file):
-    matching_folders = []
-    for folder in os.listdir(history_path):
-        folder_path = os.path.join(history_path, folder)
-        if not os.path.isdir(folder_path):
-            continue
-
-        # Look for entries.json
-        entries_file = os.path.join(folder_path, 'entries.json')
-        if not os.path.exists(entries_file):
-            continue
-
-        # Parse entries.json to find the resource key
-        with open(entries_file, 'r') as f:
-            data = json.load(f)
-            resource = data.get('resource', None)
-            if resource and target_file in resource:
-                matching_folders.append(folder_path)
-
-    return matching_folders
-
-# Search for the target file
-matching_folders = search_entries_for_file(history_path, target_file)
-
-# Output the matching folders
-if matching_folders:
-    print(f"Found {target_file} in the following folders:")
-    for folder in matching_folders:
-        print(folder)
-else:
-    print(f"No matches found for {target_file}.")

index.js

@@ -41,27 +41,27 @@ export const devScriptPath = resolve(__dirname, './scripts/dev.js');
 
 // Export a function to initialize a new project programmatically
 export const initProject = async (options = {}) => {
-  const init = await import('./scripts/init.js');
+	const init = await import('./scripts/init.js');
-  return init.initializeProject(options);
+	return init.initializeProject(options);
 };
 
 // Export a function to run init as a CLI command
 export const runInitCLI = async () => {
-  // Using spawn to ensure proper handling of stdio and process exit
+	// Using spawn to ensure proper handling of stdio and process exit
-  const child = spawn('node', [resolve(__dirname, './scripts/init.js')], {
+	const child = spawn('node', [resolve(__dirname, './scripts/init.js')], {
-    stdio: 'inherit',
+		stdio: 'inherit',
-    cwd: process.cwd()
+		cwd: process.cwd()
-  });
+	});
 
-  return new Promise((resolve, reject) => {
+	return new Promise((resolve, reject) => {
-    child.on('close', (code) => {
+		child.on('close', (code) => {
-      if (code === 0) {
+			if (code === 0) {
-        resolve();
+				resolve();
-      } else {
+			} else {
-        reject(new Error(`Init script exited with code ${code}`));
+				reject(new Error(`Init script exited with code ${code}`));
-      }
+			}
-    });
+		});
-  });
+	});
 };
 
 // Export version information
@@ -69,81 +69,81 @@ export const version = packageJson.version;
 
 // CLI implementation
 if (import.meta.url === `file://${process.argv[1]}`) {
-  const program = new Command();
+	const program = new Command();
 
-  program
+	program
-    .name('task-master')
+		.name('task-master')
-    .description('Claude Task Master CLI')
+		.description('Claude Task Master CLI')
-    .version(version);
+		.version(version);
 
-  program
+	program
-    .command('init')
+		.command('init')
-    .description('Initialize a new project')
+		.description('Initialize a new project')
-    .action(() => {
+		.action(() => {
-      runInitCLI().catch(err => {
+			runInitCLI().catch((err) => {
-        console.error('Init failed:', err.message);
+				console.error('Init failed:', err.message);
-        process.exit(1);
+				process.exit(1);
-      });
+			});
-    });
+		});
 
-  program
+	program
-    .command('dev')
+		.command('dev')
-    .description('Run the dev.js script')
+		.description('Run the dev.js script')
-    .allowUnknownOption(true)
+		.allowUnknownOption(true)
-    .action(() => {
+		.action(() => {
-      const args = process.argv.slice(process.argv.indexOf('dev') + 1);
+			const args = process.argv.slice(process.argv.indexOf('dev') + 1);
-      const child = spawn('node', [devScriptPath, ...args], {
+			const child = spawn('node', [devScriptPath, ...args], {
-        stdio: 'inherit',
+				stdio: 'inherit',
-        cwd: process.cwd()
+				cwd: process.cwd()
-      });
+			});
 
-      child.on('close', (code) => {
+			child.on('close', (code) => {
-        process.exit(code);
+				process.exit(code);
-      });
+			});
-    });
+		});
 
-  // Add shortcuts for common dev.js commands
+	// Add shortcuts for common dev.js commands
-  program
+	program
-    .command('list')
+		.command('list')
-    .description('List all tasks')
+		.description('List all tasks')
-    .action(() => {
+		.action(() => {
-      const child = spawn('node', [devScriptPath, 'list'], {
+			const child = spawn('node', [devScriptPath, 'list'], {
-        stdio: 'inherit',
+				stdio: 'inherit',
-        cwd: process.cwd()
+				cwd: process.cwd()
-      });
+			});
 
-      child.on('close', (code) => {
+			child.on('close', (code) => {
-        process.exit(code);
+				process.exit(code);
-      });
+			});
-    });
+		});
 
-  program
+	program
-    .command('next')
+		.command('next')
-    .description('Show the next task to work on')
+		.description('Show the next task to work on')
-    .action(() => {
+		.action(() => {
-      const child = spawn('node', [devScriptPath, 'next'], {
+			const child = spawn('node', [devScriptPath, 'next'], {
-        stdio: 'inherit',
+				stdio: 'inherit',
-        cwd: process.cwd()
+				cwd: process.cwd()
-      });
+			});
 
-      child.on('close', (code) => {
+			child.on('close', (code) => {
-        process.exit(code);
+				process.exit(code);
-      });
+			});
-    });
+		});
 
-  program
+	program
-    .command('generate')
+		.command('generate')
-    .description('Generate task files')
+		.description('Generate task files')
-    .action(() => {
+		.action(() => {
-      const child = spawn('node', [devScriptPath, 'generate'], {
+			const child = spawn('node', [devScriptPath, 'generate'], {
-        stdio: 'inherit',
+				stdio: 'inherit',
-        cwd: process.cwd()
+				cwd: process.cwd()
-      });
+			});
 
-      child.on('close', (code) => {
+			child.on('close', (code) => {
-        process.exit(code);
+				process.exit(code);
-      });
+			});
-    });
+		});
 
-  program.parse(process.argv);
+	program.parse(process.argv);
 }

jest.config.js

@@ -1,56 +1,56 @@
 export default {
-  // Use Node.js environment for testing
+	// Use Node.js environment for testing
-  testEnvironment: 'node',
+	testEnvironment: 'node',
 
-  // Automatically clear mock calls between every test
+	// Automatically clear mock calls between every test
-  clearMocks: true,
+	clearMocks: true,
 
-  // Indicates whether the coverage information should be collected while executing the test
+	// Indicates whether the coverage information should be collected while executing the test
-  collectCoverage: false,
+	collectCoverage: false,
 
-  // The directory where Jest should output its coverage files
+	// The directory where Jest should output its coverage files
-  coverageDirectory: 'coverage',
+	coverageDirectory: 'coverage',
 
-  // A list of paths to directories that Jest should use to search for files in
+	// A list of paths to directories that Jest should use to search for files in
-  roots: ['<rootDir>/tests'],
+	roots: ['<rootDir>/tests'],
 
-  // The glob patterns Jest uses to detect test files
+	// The glob patterns Jest uses to detect test files
-  testMatch: [
+	testMatch: [
-    '**/__tests__/**/*.js',
+		'**/__tests__/**/*.js',
-    '**/?(*.)+(spec|test).js',
+		'**/?(*.)+(spec|test).js',
-    '**/tests/*.test.js'
+		'**/tests/*.test.js'
-  ],
+	],
 
-  // Transform files
+	// Transform files
-  transform: {},
+	transform: {},
 
-  // Disable transformations for node_modules
+	// Disable transformations for node_modules
-  transformIgnorePatterns: ['/node_modules/'],
+	transformIgnorePatterns: ['/node_modules/'],
 
-  // Set moduleNameMapper for absolute paths
+	// Set moduleNameMapper for absolute paths
-  moduleNameMapper: {
+	moduleNameMapper: {
-    '^@/(.*)$': '<rootDir>/$1'
+		'^@/(.*)$': '<rootDir>/$1'
-  },
+	},
 
-  // Setup module aliases
+	// Setup module aliases
-  moduleDirectories: ['node_modules', '<rootDir>'],
+	moduleDirectories: ['node_modules', '<rootDir>'],
 
-  // Configure test coverage thresholds
+	// Configure test coverage thresholds
-  coverageThreshold: {
+	coverageThreshold: {
-    global: {
+		global: {
-      branches: 80,
+			branches: 80,
-      functions: 80,
+			functions: 80,
-      lines: 80,
+			lines: 80,
-      statements: 80
+			statements: 80
-    }
+		}
-  },
+	},
 
-  // Generate coverage report in these formats
+	// Generate coverage report in these formats
-  coverageReporters: ['text', 'lcov'],
+	coverageReporters: ['text', 'lcov'],
 
-  // Verbose output
+	// Verbose output
-  verbose: true,
+	verbose: true,
 
-  // Setup file
+	// Setup file
-  setupFilesAfterEnv: ['<rootDir>/tests/setup.js']
+	setupFilesAfterEnv: ['<rootDir>/tests/setup.js']
 };

mcp-server/server.js

@@ -1,8 +1,8 @@
 #!/usr/bin/env node
 
-import TaskMasterMCPServer from "./src/index.js";
+import TaskMasterMCPServer from './src/index.js';
-import dotenv from "dotenv";
+import dotenv from 'dotenv';
-import logger from "./src/logger.js";
+import logger from './src/logger.js';
 
 // Load environment variables
 dotenv.config();
@@ -11,25 +11,25 @@ dotenv.config();
  * Start the MCP server
  */
 async function startServer() {
-  const server = new TaskMasterMCPServer();
+	const server = new TaskMasterMCPServer();
 
-  // Handle graceful shutdown
+	// Handle graceful shutdown
-  process.on("SIGINT", async () => {
+	process.on('SIGINT', async () => {
-    await server.stop();
+		await server.stop();
-    process.exit(0);
+		process.exit(0);
-  });
+	});
 
-  process.on("SIGTERM", async () => {
+	process.on('SIGTERM', async () => {
-    await server.stop();
+		await server.stop();
-    process.exit(0);
+		process.exit(0);
-  });
+	});
 
-  try {
+	try {
-    await server.start();
+		await server.start();
-  } catch (error) {
+	} catch (error) {
-    logger.error(`Failed to start MCP server: ${error.message}`);
+		logger.error(`Failed to start MCP server: ${error.message}`);
-    process.exit(1);
+		process.exit(1);
-  }
+	}
 }
 
 // Start the server

mcp-server/src/core/__tests__/context-manager.test.js

@@ -2,84 +2,90 @@ import { jest } from '@jest/globals';
 import { ContextManager } from '../context-manager.js';
 
 describe('ContextManager', () => {
-  let contextManager;
+	let contextManager;
 
-  beforeEach(() => {
+	beforeEach(() => {
-    contextManager = new ContextManager({
+		contextManager = new ContextManager({
-      maxCacheSize: 10,
+			maxCacheSize: 10,
-      ttl: 1000, // 1 second for testing
+			ttl: 1000, // 1 second for testing
-      maxContextSize: 1000
+			maxContextSize: 1000
-    });
+		});
-  });
+	});
 
-  describe('getContext', () => {
+	describe('getContext', () => {
-    it('should create a new context when not in cache', async () => {
+		it('should create a new context when not in cache', async () => {
-      const context = await contextManager.getContext('test-id', { test: true });
+			const context = await contextManager.getContext('test-id', {
-      expect(context.id).toBe('test-id');
+				test: true
-      expect(context.metadata.test).toBe(true);
+			});
-      expect(contextManager.stats.misses).toBe(1);
+			expect(context.id).toBe('test-id');
-      expect(contextManager.stats.hits).toBe(0);
+			expect(context.metadata.test).toBe(true);
-    });
+			expect(contextManager.stats.misses).toBe(1);
+			expect(contextManager.stats.hits).toBe(0);
+		});
 
-    it('should return cached context when available', async () => {
+		it('should return cached context when available', async () => {
-      // First call creates the context
+			// First call creates the context
-      await contextManager.getContext('test-id', { test: true });
+			await contextManager.getContext('test-id', { test: true });
 
-      // Second call should hit cache
+			// Second call should hit cache
-      const context = await contextManager.getContext('test-id', { test: true });
+			const context = await contextManager.getContext('test-id', {
-      expect(context.id).toBe('test-id');
+				test: true
-      expect(context.metadata.test).toBe(true);
+			});
-      expect(contextManager.stats.hits).toBe(1);
+			expect(context.id).toBe('test-id');
-      expect(contextManager.stats.misses).toBe(1);
+			expect(context.metadata.test).toBe(true);
-    });
+			expect(contextManager.stats.hits).toBe(1);
+			expect(contextManager.stats.misses).toBe(1);
+		});
 
-    it('should respect TTL settings', async () => {
+		it('should respect TTL settings', async () => {
-      // Create context
+			// Create context
-      await contextManager.getContext('test-id', { test: true });
+			await contextManager.getContext('test-id', { test: true });
 
-      // Wait for TTL to expire
+			// Wait for TTL to expire
-      await new Promise(resolve => setTimeout(resolve, 1100));
+			await new Promise((resolve) => setTimeout(resolve, 1100));
 
-      // Should create new context
+			// Should create new context
-      await contextManager.getContext('test-id', { test: true });
+			await contextManager.getContext('test-id', { test: true });
-      expect(contextManager.stats.misses).toBe(2);
+			expect(contextManager.stats.misses).toBe(2);
-      expect(contextManager.stats.hits).toBe(0);
+			expect(contextManager.stats.hits).toBe(0);
-    });
+		});
-  });
+	});
 
-  describe('updateContext', () => {
+	describe('updateContext', () => {
-    it('should update existing context metadata', async () => {
+		it('should update existing context metadata', async () => {
-      await contextManager.getContext('test-id', { initial: true });
+			await contextManager.getContext('test-id', { initial: true });
-      const updated = await contextManager.updateContext('test-id', { updated: true });
+			const updated = await contextManager.updateContext('test-id', {
+				updated: true
+			});
 
-      expect(updated.metadata.initial).toBe(true);
+			expect(updated.metadata.initial).toBe(true);
-      expect(updated.metadata.updated).toBe(true);
+			expect(updated.metadata.updated).toBe(true);
-    });
+		});
-  });
+	});
 
-  describe('invalidateContext', () => {
+	describe('invalidateContext', () => {
-    it('should remove context from cache', async () => {
+		it('should remove context from cache', async () => {
-      await contextManager.getContext('test-id', { test: true });
+			await contextManager.getContext('test-id', { test: true });
-      contextManager.invalidateContext('test-id', { test: true });
+			contextManager.invalidateContext('test-id', { test: true });
 
-      // Should be a cache miss
+			// Should be a cache miss
-      await contextManager.getContext('test-id', { test: true });
+			await contextManager.getContext('test-id', { test: true });
-      expect(contextManager.stats.invalidations).toBe(1);
+			expect(contextManager.stats.invalidations).toBe(1);
-      expect(contextManager.stats.misses).toBe(2);
+			expect(contextManager.stats.misses).toBe(2);
-    });
+		});
-  });
+	});
 
-  describe('getStats', () => {
+	describe('getStats', () => {
-    it('should return current cache statistics', async () => {
+		it('should return current cache statistics', async () => {
-      await contextManager.getContext('test-id', { test: true });
+			await contextManager.getContext('test-id', { test: true });
-      const stats = contextManager.getStats();
+			const stats = contextManager.getStats();
 
-      expect(stats.hits).toBe(0);
+			expect(stats.hits).toBe(0);
-      expect(stats.misses).toBe(1);
+			expect(stats.misses).toBe(1);
-      expect(stats.invalidations).toBe(0);
+			expect(stats.invalidations).toBe(0);
-      expect(stats.size).toBe(1);
+			expect(stats.size).toBe(1);
-      expect(stats.maxSize).toBe(10);
+			expect(stats.maxSize).toBe(10);
-      expect(stats.ttl).toBe(1000);
+			expect(stats.ttl).toBe(1000);
-    });
+		});
-  });
+	});
 });

mcp-server/src/core/context-manager.js

@@ -15,155 +15,156 @@ import { LRUCache } from 'lru-cache';
  */
 
 export class ContextManager {
-  /**
+	/**
-   * Create a new ContextManager instance
+	 * Create a new ContextManager instance
-   * @param {ContextManagerConfig} config - Configuration options
+	 * @param {ContextManagerConfig} config - Configuration options
-   */
+	 */
-  constructor(config = {}) {
+	constructor(config = {}) {
-    this.config = {
+		this.config = {
-      maxCacheSize: config.maxCacheSize || 1000,
+			maxCacheSize: config.maxCacheSize || 1000,
-      ttl: config.ttl || 1000 * 60 * 5, // 5 minutes default
+			ttl: config.ttl || 1000 * 60 * 5, // 5 minutes default
-      maxContextSize: config.maxContextSize || 4000
+			maxContextSize: config.maxContextSize || 4000
-    };
+		};
 
-    // Initialize LRU cache for context data
+		// Initialize LRU cache for context data
-    this.cache = new LRUCache({
+		this.cache = new LRUCache({
-      max: this.config.maxCacheSize,
+			max: this.config.maxCacheSize,
-      ttl: this.config.ttl,
+			ttl: this.config.ttl,
-      updateAgeOnGet: true
+			updateAgeOnGet: true
-    });
+		});
 
-    // Cache statistics
+		// Cache statistics
-    this.stats = {
+		this.stats = {
-      hits: 0,
+			hits: 0,
-      misses: 0,
+			misses: 0,
-      invalidations: 0
+			invalidations: 0
-    };
+		};
-  }
+	}
 
-  /**
+	/**
-   * Create a new context or retrieve from cache
+	 * Create a new context or retrieve from cache
-   * @param {string} contextId - Unique identifier for the context
+	 * @param {string} contextId - Unique identifier for the context
-   * @param {Object} metadata - Additional metadata for the context
+	 * @param {Object} metadata - Additional metadata for the context
-   * @returns {Object} Context object with metadata
+	 * @returns {Object} Context object with metadata
-   */
+	 */
-  async getContext(contextId, metadata = {}) {
+	async getContext(contextId, metadata = {}) {
-    const cacheKey = this._getCacheKey(contextId, metadata);
+		const cacheKey = this._getCacheKey(contextId, metadata);
 
-    // Try to get from cache first
+		// Try to get from cache first
-    const cached = this.cache.get(cacheKey);
+		const cached = this.cache.get(cacheKey);
-    if (cached) {
+		if (cached) {
-      this.stats.hits++;
+			this.stats.hits++;
-      return cached;
+			return cached;
-    }
+		}
 
-    this.stats.misses++;
+		this.stats.misses++;
 
-    // Create new context if not in cache
+		// Create new context if not in cache
-    const context = {
+		const context = {
-      id: contextId,
+			id: contextId,
-      metadata: {
+			metadata: {
-        ...metadata,
+				...metadata,
-        created: new Date().toISOString()
+				created: new Date().toISOString()
-      }
+			}
-    };
+		};
 
-    // Cache the new context
+		// Cache the new context
-    this.cache.set(cacheKey, context);
+		this.cache.set(cacheKey, context);
 
-    return context;
+		return context;
-  }
+	}
 
-  /**
+	/**
-   * Update an existing context
+	 * Update an existing context
-   * @param {string} contextId - Context identifier
+	 * @param {string} contextId - Context identifier
-   * @param {Object} updates - Updates to apply to the context
+	 * @param {Object} updates - Updates to apply to the context
-   * @returns {Object} Updated context
+	 * @returns {Object} Updated context
-   */
+	 */
-  async updateContext(contextId, updates) {
+	async updateContext(contextId, updates) {
-    const context = await this.getContext(contextId);
+		const context = await this.getContext(contextId);
 
-    // Apply updates to context
+		// Apply updates to context
-    Object.assign(context.metadata, updates);
+		Object.assign(context.metadata, updates);
 
-    // Update cache
+		// Update cache
-    const cacheKey = this._getCacheKey(contextId, context.metadata);
+		const cacheKey = this._getCacheKey(contextId, context.metadata);
-    this.cache.set(cacheKey, context);
+		this.cache.set(cacheKey, context);
 
-    return context;
+		return context;
-  }
+	}
 
-  /**
+	/**
-   * Invalidate a context in the cache
+	 * Invalidate a context in the cache
-   * @param {string} contextId - Context identifier
+	 * @param {string} contextId - Context identifier
-   * @param {Object} metadata - Metadata used in the cache key
+	 * @param {Object} metadata - Metadata used in the cache key
-   */
+	 */
-  invalidateContext(contextId, metadata = {}) {
+	invalidateContext(contextId, metadata = {}) {
-    const cacheKey = this._getCacheKey(contextId, metadata);
+		const cacheKey = this._getCacheKey(contextId, metadata);
-    this.cache.delete(cacheKey);
+		this.cache.delete(cacheKey);
-    this.stats.invalidations++;
+		this.stats.invalidations++;
-  }
+	}
 
-  /**
+	/**
-   * Get cached data associated with a specific key.
+	 * Get cached data associated with a specific key.
-   * Increments cache hit stats if found.
+	 * Increments cache hit stats if found.
-   * @param {string} key - The cache key.
+	 * @param {string} key - The cache key.
-   * @returns {any | undefined} The cached data or undefined if not found/expired.
+	 * @returns {any | undefined} The cached data or undefined if not found/expired.
-   */
+	 */
-  getCachedData(key) {
+	getCachedData(key) {
-    const cached = this.cache.get(key);
+		const cached = this.cache.get(key);
-    if (cached !== undefined) { // Check for undefined specifically, as null/false might be valid cached values
+		if (cached !== undefined) {
-      this.stats.hits++;
+			// Check for undefined specifically, as null/false might be valid cached values
-      return cached;
+			this.stats.hits++;
-    }
+			return cached;
-    this.stats.misses++;
+		}
-    return undefined;
+		this.stats.misses++;
-  }
+		return undefined;
+	}
 
-  /**
+	/**
-   * Set data in the cache with a specific key.
+	 * Set data in the cache with a specific key.
-   * @param {string} key - The cache key.
+	 * @param {string} key - The cache key.
-   * @param {any} data - The data to cache.
+	 * @param {any} data - The data to cache.
-   */
+	 */
-  setCachedData(key, data) {
+	setCachedData(key, data) {
-    this.cache.set(key, data);
+		this.cache.set(key, data);
-  }
+	}
 
-  /**
+	/**
-   * Invalidate a specific cache key.
+	 * Invalidate a specific cache key.
-   * Increments invalidation stats.
+	 * Increments invalidation stats.
-   * @param {string} key - The cache key to invalidate.
+	 * @param {string} key - The cache key to invalidate.
-   */
+	 */
-  invalidateCacheKey(key) {
+	invalidateCacheKey(key) {
-    this.cache.delete(key);
+		this.cache.delete(key);
-    this.stats.invalidations++;
+		this.stats.invalidations++;
-  }
+	}
 
-  /**
+	/**
-   * Get cache statistics
+	 * Get cache statistics
-   * @returns {Object} Cache statistics
+	 * @returns {Object} Cache statistics
-   */
+	 */
-  getStats() {
+	getStats() {
-    return {
+		return {
-      hits: this.stats.hits,
+			hits: this.stats.hits,
-      misses: this.stats.misses,
+			misses: this.stats.misses,
-      invalidations: this.stats.invalidations,
+			invalidations: this.stats.invalidations,
-      size: this.cache.size,
+			size: this.cache.size,
-      maxSize: this.config.maxCacheSize,
+			maxSize: this.config.maxCacheSize,
-      ttl: this.config.ttl
+			ttl: this.config.ttl
-    };
+		};
-  }
+	}
 
-  /**
+	/**
-   * Generate a cache key from context ID and metadata
+	 * Generate a cache key from context ID and metadata
-   * @private
+	 * @private
-   * @deprecated No longer used for direct cache key generation outside the manager.
+	 * @deprecated No longer used for direct cache key generation outside the manager.
-   *             Prefer generating specific keys in calling functions.
+	 *             Prefer generating specific keys in calling functions.
-   */
+	 */
-  _getCacheKey(contextId, metadata) {
+	_getCacheKey(contextId, metadata) {
-    // Kept for potential backward compatibility or internal use if needed later.
+		// Kept for potential backward compatibility or internal use if needed later.
-    return `${contextId}:${JSON.stringify(metadata)}`;
+		return `${contextId}:${JSON.stringify(metadata)}`;
-  }
+	}
 }
 
 // Export a singleton instance with default config

mcp-server/src/core/direct-functions/add-dependency.js

@@ -4,82 +4,103 @@
  */
 
 import { addDependency } from '../../../../scripts/modules/dependency-manager.js';
-import { findTasksJsonPath } from '../utils/path-utils.js';
+import {
-import { enableSilentMode, disableSilentMode } from '../../../../scripts/modules/utils.js';
+	enableSilentMode,
+	disableSilentMode
+} from '../../../../scripts/modules/utils.js';
 
 /**
  * Direct function wrapper for addDependency with error handling.
  *
  * @param {Object} args - Command arguments
+ * @param {string} args.tasksJsonPath - Explicit path to the tasks.json file.
  * @param {string|number} args.id - Task ID to add dependency to
  * @param {string|number} args.dependsOn - Task ID that will become a dependency
- * @param {string} [args.file] - Path to the tasks file
- * @param {string} [args.projectRoot] - Project root directory
  * @param {Object} log - Logger object
  * @returns {Promise<Object>} - Result object with success status and data/error information
  */
 export async function addDependencyDirect(args, log) {
-  try {
+	// Destructure expected args
-    log.info(`Adding dependency with args: ${JSON.stringify(args)}`);
+	const { tasksJsonPath, id, dependsOn } = args;
+	try {
+		log.info(`Adding dependency with args: ${JSON.stringify(args)}`);
 
-    // Validate required parameters
+		// Check if tasksJsonPath was provided
-    if (!args.id) {
+		if (!tasksJsonPath) {
-      return {
+			log.error('addDependencyDirect called without tasksJsonPath');
-        success: false,
+			return {
-        error: {
+				success: false,
-          code: 'INPUT_VALIDATION_ERROR',
+				error: {
-          message: 'Task ID (id) is required'
+					code: 'MISSING_ARGUMENT',
-        }
+					message: 'tasksJsonPath is required'
-      };
+				}
-    }
+			};
+		}
 
-    if (!args.dependsOn) {
+		// Validate required parameters
-      return {
+		if (!id) {
-        success: false,
+			return {
-        error: {
+				success: false,
-          code: 'INPUT_VALIDATION_ERROR',
+				error: {
-          message: 'Dependency ID (dependsOn) is required'
+					code: 'INPUT_VALIDATION_ERROR',
-        }
+					message: 'Task ID (id) is required'
-      };
+				}
-    }
+			};
+		}
 
-    // Find the tasks.json path
+		if (!dependsOn) {
-    const tasksPath = findTasksJsonPath(args, log);
+			return {
+				success: false,
+				error: {
+					code: 'INPUT_VALIDATION_ERROR',
+					message: 'Dependency ID (dependsOn) is required'
+				}
+			};
+		}
 
-    // Format IDs for the core function
+		// Use provided path
-    const taskId = args.id.includes && args.id.includes('.') ? args.id : parseInt(args.id, 10);
+		const tasksPath = tasksJsonPath;
-    const dependencyId = args.dependsOn.includes && args.dependsOn.includes('.') ? args.dependsOn : parseInt(args.dependsOn, 10);
 
-    log.info(`Adding dependency: task ${taskId} will depend on ${dependencyId}`);
+		// Format IDs for the core function
+		const taskId =
+			id && id.includes && id.includes('.') ? id : parseInt(id, 10);
+		const dependencyId =
+			dependsOn && dependsOn.includes && dependsOn.includes('.')
+				? dependsOn
+				: parseInt(dependsOn, 10);
 
-    // Enable silent mode to prevent console logs from interfering with JSON response
+		log.info(
-    enableSilentMode();
+			`Adding dependency: task ${taskId} will depend on ${dependencyId}`
+		);
 
-    // Call the core function
+		// Enable silent mode to prevent console logs from interfering with JSON response
-    await addDependency(tasksPath, taskId, dependencyId);
+		enableSilentMode();
 
-    // Restore normal logging
+		// Call the core function using the provided path
-    disableSilentMode();
+		await addDependency(tasksPath, taskId, dependencyId);
 
-    return {
+		// Restore normal logging
-      success: true,
+		disableSilentMode();
-      data: {
-        message: `Successfully added dependency: Task ${taskId} now depends on ${dependencyId}`,
-        taskId: taskId,
-        dependencyId: dependencyId
-      }
-    };
-  } catch (error) {
-    // Make sure to restore normal logging even if there's an error
-    disableSilentMode();
 
-    log.error(`Error in addDependencyDirect: ${error.message}`);
+		return {
-    return {
+			success: true,
-      success: false,
+			data: {
-      error: {
+				message: `Successfully added dependency: Task ${taskId} now depends on ${dependencyId}`,
-        code: 'CORE_FUNCTION_ERROR',
+				taskId: taskId,
-        message: error.message
+				dependencyId: dependencyId
-      }
+			}
-    };
+		};
-  }
+	} catch (error) {
+		// Make sure to restore normal logging even if there's an error
+		disableSilentMode();
+
+		log.error(`Error in addDependencyDirect: ${error.message}`);
+		return {
+			success: false,
+			error: {
+				code: 'CORE_FUNCTION_ERROR',
+				message: error.message
+			}
+		};
+	}
 }

mcp-server/src/core/direct-functions/add-subtask.js

@@ -3,12 +3,15 @@
  */
 
 import { addSubtask } from '../../../../scripts/modules/task-manager.js';
-import { findTasksJsonPath } from '../utils/path-utils.js';
+import {
-import { enableSilentMode, disableSilentMode } from '../../../../scripts/modules/utils.js';
+	enableSilentMode,
+	disableSilentMode
+} from '../../../../scripts/modules/utils.js';
 
 /**
  * Add a subtask to an existing task
  * @param {Object} args - Function arguments
+ * @param {string} args.tasksJsonPath - Explicit path to the tasks.json file.
  * @param {string} args.id - Parent task ID
  * @param {string} [args.taskId] - Existing task ID to convert to subtask (optional)
  * @param {string} [args.title] - Title for new subtask (when creating a new subtask)
@@ -16,113 +19,147 @@ import { enableSilentMode, disableSilentMode } from '../../../../scripts/modules
  * @param {string} [args.details] - Implementation details for new subtask
  * @param {string} [args.status] - Status for new subtask (default: 'pending')
  * @param {string} [args.dependencies] - Comma-separated list of dependency IDs
- * @param {string} [args.file] - Path to the tasks file
  * @param {boolean} [args.skipGenerate] - Skip regenerating task files
- * @param {string} [args.projectRoot] - Project root directory
  * @param {Object} log - Logger object
  * @returns {Promise<{success: boolean, data?: Object, error?: string}>}
  */
 export async function addSubtaskDirect(args, log) {
-  try {
+	// Destructure expected args
-    log.info(`Adding subtask with args: ${JSON.stringify(args)}`);
+	const {
+		tasksJsonPath,
+		id,
+		taskId,
+		title,
+		description,
+		details,
+		status,
+		dependencies: dependenciesStr,
+		skipGenerate
+	} = args;
+	try {
+		log.info(`Adding subtask with args: ${JSON.stringify(args)}`);
 
-    if (!args.id) {
+		// Check if tasksJsonPath was provided
-      return {
+		if (!tasksJsonPath) {
-        success: false,
+			log.error('addSubtaskDirect called without tasksJsonPath');
-        error: {
+			return {
-          code: 'INPUT_VALIDATION_ERROR',
+				success: false,
-          message: 'Parent task ID is required'
+				error: {
-        }
+					code: 'MISSING_ARGUMENT',
-      };
+					message: 'tasksJsonPath is required'
-    }
+				}
+			};
+		}
 
-    // Either taskId or title must be provided
+		if (!id) {
-    if (!args.taskId && !args.title) {
+			return {
-      return {
+				success: false,
-        success: false,
+				error: {
-        error: {
+					code: 'INPUT_VALIDATION_ERROR',
-          code: 'INPUT_VALIDATION_ERROR',
+					message: 'Parent task ID is required'
-          message: 'Either taskId or title must be provided'
+				}
-        }
+			};
-      };
+		}
-    }
 
-    // Find the tasks.json path
+		// Either taskId or title must be provided
-    const tasksPath = findTasksJsonPath(args, log);
+		if (!taskId && !title) {
+			return {
+				success: false,
+				error: {
+					code: 'INPUT_VALIDATION_ERROR',
+					message: 'Either taskId or title must be provided'
+				}
+			};
+		}
 
-    // Parse dependencies if provided
+		// Use provided path
-    let dependencies = [];
+		const tasksPath = tasksJsonPath;
-    if (args.dependencies) {
-      dependencies = args.dependencies.split(',').map(id => {
-        // Handle both regular IDs and dot notation
-        return id.includes('.') ? id.trim() : parseInt(id.trim(), 10);
-      });
-    }
 
-    // Convert existingTaskId to a number if provided
+		// Parse dependencies if provided
-    const existingTaskId = args.taskId ? parseInt(args.taskId, 10) : null;
+		let dependencies = [];
+		if (dependenciesStr) {
+			dependencies = dependenciesStr.split(',').map((depId) => {
+				// Handle both regular IDs and dot notation
+				return depId.includes('.') ? depId.trim() : parseInt(depId.trim(), 10);
+			});
+		}
 
-    // Convert parent ID to a number
+		// Convert existingTaskId to a number if provided
-    const parentId = parseInt(args.id, 10);
+		const existingTaskId = taskId ? parseInt(taskId, 10) : null;
 
-    // Determine if we should generate files
+		// Convert parent ID to a number
-    const generateFiles = !args.skipGenerate;
+		const parentId = parseInt(id, 10);
 
-    // Enable silent mode to prevent console logs from interfering with JSON response
+		// Determine if we should generate files
-    enableSilentMode();
+		const generateFiles = !skipGenerate;
 
-    // Case 1: Convert existing task to subtask
+		// Enable silent mode to prevent console logs from interfering with JSON response
-    if (existingTaskId) {
+		enableSilentMode();
-      log.info(`Converting task ${existingTaskId} to a subtask of ${parentId}`);
-      const result = await addSubtask(tasksPath, parentId, existingTaskId, null, generateFiles);
 
-      // Restore normal logging
+		// Case 1: Convert existing task to subtask
-      disableSilentMode();
+		if (existingTaskId) {
+			log.info(`Converting task ${existingTaskId} to a subtask of ${parentId}`);
+			const result = await addSubtask(
+				tasksPath,
+				parentId,
+				existingTaskId,
+				null,
+				generateFiles
+			);
 
-      return {
+			// Restore normal logging
-        success: true,
+			disableSilentMode();
-        data: {
-          message: `Task ${existingTaskId} successfully converted to a subtask of task ${parentId}`,
-          subtask: result
-        }
-      };
-    } 
-    // Case 2: Create new subtask
-    else {
-      log.info(`Creating new subtask for parent task ${parentId}`);
 
-      const newSubtaskData = {
+			return {
-        title: args.title,
+				success: true,
-        description: args.description || '',
+				data: {
-        details: args.details || '',
+					message: `Task ${existingTaskId} successfully converted to a subtask of task ${parentId}`,
-        status: args.status || 'pending',
+					subtask: result
-        dependencies: dependencies
+				}
-      };
+			};
+		}
+		// Case 2: Create new subtask
+		else {
+			log.info(`Creating new subtask for parent task ${parentId}`);
 
-      const result = await addSubtask(tasksPath, parentId, null, newSubtaskData, generateFiles);
+			const newSubtaskData = {
+				title: title,
+				description: description || '',
+				details: details || '',
+				status: status || 'pending',
+				dependencies: dependencies
+			};
 
-      // Restore normal logging
+			const result = await addSubtask(
-      disableSilentMode();
+				tasksPath,
+				parentId,
+				null,
+				newSubtaskData,
+				generateFiles
+			);
 
-      return {
+			// Restore normal logging
-        success: true,
+			disableSilentMode();
-        data: {
-          message: `New subtask ${parentId}.${result.id} successfully created`,
-          subtask: result
-        }
-      };
-    }
-  } catch (error) {
-    // Make sure to restore normal logging even if there's an error
-    disableSilentMode();
 
-    log.error(`Error in addSubtaskDirect: ${error.message}`);
+			return {
-    return {
+				success: true,
-      success: false,
+				data: {
-      error: {
+					message: `New subtask ${parentId}.${result.id} successfully created`,
-        code: 'CORE_FUNCTION_ERROR',
+					subtask: result
-        message: error.message
+				}
-      }
+			};
-    };
+		}
-  }
+	} catch (error) {
+		// Make sure to restore normal logging even if there's an error
+		disableSilentMode();
+
+		log.error(`Error in addSubtaskDirect: ${error.message}`);
+		return {
+			success: false,
+			error: {
+				code: 'CORE_FUNCTION_ERROR',
+				message: error.message
+			}
+		};
+	}
 }

mcp-server/src/core/direct-functions/add-task.js

@@ -4,81 +4,256 @@
  */
 
 import { addTask } from '../../../../scripts/modules/task-manager.js';
-import { findTasksJsonPath } from '../utils/path-utils.js';
+import {
-import { enableSilentMode, disableSilentMode } from '../../../../scripts/modules/utils.js';
+	enableSilentMode,
+	disableSilentMode
+} from '../../../../scripts/modules/utils.js';
+import {
+	getAnthropicClientForMCP,
+	getModelConfig
+} from '../utils/ai-client-utils.js';
+import {
+	_buildAddTaskPrompt,
+	parseTaskJsonResponse,
+	_handleAnthropicStream
+} from '../../../../scripts/modules/ai-services.js';
 
 /**
  * Direct function wrapper for adding a new task with error handling.
  *
  * @param {Object} args - Command arguments
- * @param {string} args.prompt - Description of the task to add
+ * @param {string} [args.prompt] - Description of the task to add (required if not using manual fields)
- * @param {Array<number>} [args.dependencies=[]] - Task dependencies as array of IDs
+ * @param {string} [args.title] - Task title (for manual task creation)
+ * @param {string} [args.description] - Task description (for manual task creation)
+ * @param {string} [args.details] - Implementation details (for manual task creation)
+ * @param {string} [args.testStrategy] - Test strategy (for manual task creation)
+ * @param {string} [args.dependencies] - Comma-separated list of task IDs this task depends on
  * @param {string} [args.priority='medium'] - Task priority (high, medium, low)
- * @param {string} [args.file] - Path to the tasks file
+ * @param {string} [args.file='tasks/tasks.json'] - Path to the tasks file
  * @param {string} [args.projectRoot] - Project root directory
+ * @param {boolean} [args.research=false] - Whether to use research capabilities for task creation
  * @param {Object} log - Logger object
+ * @param {Object} context - Additional context (reportProgress, session)
  * @returns {Promise<Object>} - Result object { success: boolean, data?: any, error?: { code: string, message: string } }
  */
-export async function addTaskDirect(args, log) {
+export async function addTaskDirect(args, log, context = {}) {
-  try {
+	// Destructure expected args
-    // Enable silent mode to prevent console logs from interfering with JSON response
+	const { tasksJsonPath, prompt, dependencies, priority, research } = args;
-    enableSilentMode();
+	try {
+		// Enable silent mode to prevent console logs from interfering with JSON response
+		enableSilentMode();
 
-    // Find the tasks.json path
+		// Check if tasksJsonPath was provided
-    const tasksPath = findTasksJsonPath(args, log);
+		if (!tasksJsonPath) {
+			log.error('addTaskDirect called without tasksJsonPath');
+			disableSilentMode(); // Disable before returning
+			return {
+				success: false,
+				error: {
+					code: 'MISSING_ARGUMENT',
+					message: 'tasksJsonPath is required'
+				}
+			};
+		}
 
-    // Check required parameters
+		// Use provided path
-    if (!args.prompt) {
+		const tasksPath = tasksJsonPath;
-      log.error('Missing required parameter: prompt');
-      return {
-        success: false,
-        error: {
-          code: 'MISSING_PARAMETER',
-          message: 'The prompt parameter is required for adding a task'
-        }
-      };
-    }
 
-    // Extract and prepare parameters
+		// Check if this is manual task creation or AI-driven task creation
-    const prompt = args.prompt;
+		const isManualCreation = args.title && args.description;
-    const dependencies = Array.isArray(args.dependencies) 
-      ? args.dependencies 
-      : (args.dependencies ? String(args.dependencies).split(',').map(id => parseInt(id.trim(), 10)) : []);
-    const priority = args.priority || 'medium';
 
-    log.info(`Adding new task with prompt: "${prompt}", dependencies: [${dependencies.join(', ')}], priority: ${priority}`);
+		// Check required parameters
+		if (!args.prompt && !isManualCreation) {
+			log.error(
+				'Missing required parameters: either prompt or title+description must be provided'
+			);
+			disableSilentMode();
+			return {
+				success: false,
+				error: {
+					code: 'MISSING_PARAMETER',
+					message:
+						'Either the prompt parameter or both title and description parameters are required for adding a task'
+				}
+			};
+		}
 
-    // Call the addTask function with 'json' outputFormat to prevent console output when called via MCP
+		// Extract and prepare parameters
-    const newTaskId = await addTask(
+		const taskPrompt = prompt;
-      tasksPath, 
+		const taskDependencies = Array.isArray(dependencies)
-      prompt, 
+			? dependencies
-      dependencies, 
+			: dependencies
-      priority, 
+				? String(dependencies)
-      { mcpLog: log }, 
+						.split(',')
-      'json'
+						.map((id) => parseInt(id.trim(), 10))
-    );
+				: [];
+		const taskPriority = priority || 'medium';
 
-    // Restore normal logging
+		// Extract context parameters for advanced functionality
-    disableSilentMode();
+		const { session } = context;
 
-    return {
+		let manualTaskData = null;
-      success: true,
-      data: {
-        taskId: newTaskId,
-        message: `Successfully added new task #${newTaskId}`
-      }
-    };
-  } catch (error) {
-    // Make sure to restore normal logging even if there's an error
-    disableSilentMode();
 
-    log.error(`Error in addTaskDirect: ${error.message}`);
+		if (isManualCreation) {
-    return {
+			// Create manual task data object
-      success: false,
+			manualTaskData = {
-      error: {
+				title: args.title,
-        code: 'ADD_TASK_ERROR',
+				description: args.description,
-        message: error.message
+				details: args.details || '',
-      }
+				testStrategy: args.testStrategy || ''
-    };
+			};
-  }
+
+			log.info(
+				`Adding new task manually with title: "${args.title}", dependencies: [${taskDependencies.join(', ')}], priority: ${priority}`
+			);
+
+			// Call the addTask function with manual task data
+			const newTaskId = await addTask(
+				tasksPath,
+				null, // No prompt needed for manual creation
+				taskDependencies,
+				priority,
+				{
+					mcpLog: log,
+					session
+				},
+				'json', // Use JSON output format to prevent console output
+				null, // No custom environment
+				manualTaskData // Pass the manual task data
+			);
+
+			// Restore normal logging
+			disableSilentMode();
+
+			return {
+				success: true,
+				data: {
+					taskId: newTaskId,
+					message: `Successfully added new task #${newTaskId}`
+				}
+			};
+		} else {
+			// AI-driven task creation
+			log.info(
+				`Adding new task with prompt: "${prompt}", dependencies: [${taskDependencies.join(', ')}], priority: ${priority}`
+			);
+
+			// Initialize AI client with session environment
+			let localAnthropic;
+			try {
+				localAnthropic = getAnthropicClientForMCP(session, log);
+			} catch (error) {
+				log.error(`Failed to initialize Anthropic client: ${error.message}`);
+				disableSilentMode();
+				return {
+					success: false,
+					error: {
+						code: 'AI_CLIENT_ERROR',
+						message: `Cannot initialize AI client: ${error.message}`
+					}
+				};
+			}
+
+			// Get model configuration from session
+			const modelConfig = getModelConfig(session);
+
+			// Read existing tasks to provide context
+			let tasksData;
+			try {
+				const fs = await import('fs');
+				tasksData = JSON.parse(fs.readFileSync(tasksPath, 'utf8'));
+			} catch (error) {
+				log.warn(`Could not read existing tasks for context: ${error.message}`);
+				tasksData = { tasks: [] };
+			}
+
+			// Build prompts for AI
+			const { systemPrompt, userPrompt } = _buildAddTaskPrompt(
+				prompt,
+				tasksData.tasks
+			);
+
+			// Make the AI call using the streaming helper
+			let responseText;
+			try {
+				responseText = await _handleAnthropicStream(
+					localAnthropic,
+					{
+						model: modelConfig.model,
+						max_tokens: modelConfig.maxTokens,
+						temperature: modelConfig.temperature,
+						messages: [{ role: 'user', content: userPrompt }],
+						system: systemPrompt
+					},
+					{
+						mcpLog: log
+					}
+				);
+			} catch (error) {
+				log.error(`AI processing failed: ${error.message}`);
+				disableSilentMode();
+				return {
+					success: false,
+					error: {
+						code: 'AI_PROCESSING_ERROR',
+						message: `Failed to generate task with AI: ${error.message}`
+					}
+				};
+			}
+
+			// Parse the AI response
+			let taskDataFromAI;
+			try {
+				taskDataFromAI = parseTaskJsonResponse(responseText);
+			} catch (error) {
+				log.error(`Failed to parse AI response: ${error.message}`);
+				disableSilentMode();
+				return {
+					success: false,
+					error: {
+						code: 'RESPONSE_PARSING_ERROR',
+						message: `Failed to parse AI response: ${error.message}`
+					}
+				};
+			}
+
+			// Call the addTask function with 'json' outputFormat to prevent console output when called via MCP
+			const newTaskId = await addTask(
+				tasksPath,
+				prompt,
+				taskDependencies,
+				priority,
+				{
+					mcpLog: log,
+					session
+				},
+				'json',
+				null,
+				taskDataFromAI // Pass the parsed AI result as the manual task data
+			);
+
+			// Restore normal logging
+			disableSilentMode();
+
+			return {
+				success: true,
+				data: {
+					taskId: newTaskId,
+					message: `Successfully added new task #${newTaskId}`
+				}
+			};
+		}
+	} catch (error) {
+		// Make sure to restore normal logging even if there's an error
+		disableSilentMode();
+
+		log.error(`Error in addTaskDirect: ${error.message}`);
+		return {
+			success: false,
+			error: {
+				code: 'ADD_TASK_ERROR',
+				message: error.message
+			}
+		};
+	}
 }

mcp-server/src/core/direct-functions/analyze-task-complexity.js

@@ -3,99 +3,180 @@
  */
 
 import { analyzeTaskComplexity } from '../../../../scripts/modules/task-manager.js';
-import { findTasksJsonPath } from '../utils/path-utils.js';
+import {
-import { enableSilentMode, disableSilentMode } from '../../../../scripts/modules/utils.js';
+	enableSilentMode,
+	disableSilentMode,
+	isSilentMode,
+	readJSON
+} from '../../../../scripts/modules/utils.js';
 import fs from 'fs';
 import path from 'path';
 
 /**
  * Analyze task complexity and generate recommendations
  * @param {Object} args - Function arguments
- * @param {string} [args.file] - Path to the tasks file
+ * @param {string} args.tasksJsonPath - Explicit path to the tasks.json file.
- * @param {string} [args.output] - Output file path for the report
+ * @param {string} args.outputPath - Explicit absolute path to save the report.
  * @param {string} [args.model] - LLM model to use for analysis
  * @param {string|number} [args.threshold] - Minimum complexity score to recommend expansion (1-10)
  * @param {boolean} [args.research] - Use Perplexity AI for research-backed complexity analysis
- * @param {string} [args.projectRoot] - Project root directory
  * @param {Object} log - Logger object
+ * @param {Object} [context={}] - Context object containing session data
  * @returns {Promise<{success: boolean, data?: Object, error?: {code: string, message: string}}>}
  */
-export async function analyzeTaskComplexityDirect(args, log) {
+export async function analyzeTaskComplexityDirect(args, log, context = {}) {
-  try {
+	const { session } = context; // Only extract session, not reportProgress
-    log.info(`Analyzing task complexity with args: ${JSON.stringify(args)}`);
+	// Destructure expected args
+	const { tasksJsonPath, outputPath, model, threshold, research } = args;
 
-    // Find the tasks.json path
+	try {
-    const tasksPath = findTasksJsonPath(args, log);
+		log.info(`Analyzing task complexity with args: ${JSON.stringify(args)}`);
 
-    // Determine output path
+		// Check if required paths were provided
-    let outputPath = args.output || 'scripts/task-complexity-report.json';
+		if (!tasksJsonPath) {
-    if (!path.isAbsolute(outputPath) && args.projectRoot) {
+			log.error('analyzeTaskComplexityDirect called without tasksJsonPath');
-      outputPath = path.join(args.projectRoot, outputPath);
+			return {
-    }
+				success: false,
+				error: {
+					code: 'MISSING_ARGUMENT',
+					message: 'tasksJsonPath is required'
+				}
+			};
+		}
+		if (!outputPath) {
+			log.error('analyzeTaskComplexityDirect called without outputPath');
+			return {
+				success: false,
+				error: { code: 'MISSING_ARGUMENT', message: 'outputPath is required' }
+			};
+		}
 
-    // Create options object for analyzeTaskComplexity
+		// Use the provided paths
-    const options = {
+		const tasksPath = tasksJsonPath;
-      file: tasksPath,
+		const resolvedOutputPath = outputPath;
-      output: outputPath,
-      model: args.model,
-      threshold: args.threshold,
-      research: args.research === true
-    };
 
-    log.info(`Analyzing task complexity from: ${tasksPath}`);
+		log.info(`Analyzing task complexity from: ${tasksPath}`);
-    log.info(`Output report will be saved to: ${outputPath}`);
+		log.info(`Output report will be saved to: ${resolvedOutputPath}`);
 
-    if (options.research) {
+		if (research) {
-      log.info('Using Perplexity AI for research-backed complexity analysis');
+			log.info('Using Perplexity AI for research-backed complexity analysis');
-    }
+		}
 
-    // Enable silent mode to prevent console logs from interfering with JSON response
+		// Create options object for analyzeTaskComplexity using provided paths
-    enableSilentMode();
+		const options = {
+			file: tasksPath,
+			output: resolvedOutputPath,
+			model: model,
+			threshold: threshold,
+			research: research === true
+		};
 
-    // Call the core function
+		// Enable silent mode to prevent console logs from interfering with JSON response
-    await analyzeTaskComplexity(options);
+		const wasSilent = isSilentMode();
+		if (!wasSilent) {
+			enableSilentMode();
+		}
 
-    // Restore normal logging
+		// Create a logWrapper that matches the expected mcpLog interface as specified in utilities.mdc
-    disableSilentMode();
+		const logWrapper = {
+			info: (message, ...args) => log.info(message, ...args),
+			warn: (message, ...args) => log.warn(message, ...args),
+			error: (message, ...args) => log.error(message, ...args),
+			debug: (message, ...args) => log.debug && log.debug(message, ...args),
+			success: (message, ...args) => log.info(message, ...args) // Map success to info
+		};
 
-    // Verify the report file was created
+		try {
-    if (!fs.existsSync(outputPath)) {
+			// Call the core function with session and logWrapper as mcpLog
-      return {
+			await analyzeTaskComplexity(options, {
-        success: false,
+				session,
-        error: {
+				mcpLog: logWrapper // Use the wrapper instead of passing log directly
-          code: 'ANALYZE_ERROR',
+			});
-          message: 'Analysis completed but no report file was created'
+		} catch (error) {
-        }
+			log.error(`Error in analyzeTaskComplexity: ${error.message}`);
-      };
+			return {
-    }
+				success: false,
+				error: {
+					code: 'ANALYZE_ERROR',
+					message: `Error running complexity analysis: ${error.message}`
+				}
+			};
+		} finally {
+			// Always restore normal logging in finally block, but only if we enabled it
+			if (!wasSilent) {
+				disableSilentMode();
+			}
+		}
 
-    // Read the report file
+		// Verify the report file was created
-    const report = JSON.parse(fs.readFileSync(outputPath, 'utf8'));
+		if (!fs.existsSync(resolvedOutputPath)) {
+			return {
+				success: false,
+				error: {
+					code: 'ANALYZE_ERROR',
+					message: 'Analysis completed but no report file was created'
+				}
+			};
+		}
 
-    return {
+		// Read the report file
-      success: true,
+		let report;
-      data: {
+		try {
-        message: `Task complexity analysis complete. Report saved to ${outputPath}`,
+			report = JSON.parse(fs.readFileSync(resolvedOutputPath, 'utf8'));
-        reportPath: outputPath,
-        reportSummary: {
-          taskCount: report.length,
-          highComplexityTasks: report.filter(t => t.complexityScore >= 8).length,
-          mediumComplexityTasks: report.filter(t => t.complexityScore >= 5 && t.complexityScore < 8).length,
-          lowComplexityTasks: report.filter(t => t.complexityScore < 5).length,
-        }
-      }
-    };
-  } catch (error) {
-    // Make sure to restore normal logging even if there's an error
-    disableSilentMode();
 
-    log.error(`Error in analyzeTaskComplexityDirect: ${error.message}`);
+			// Important: Handle different report formats
-    return {
+			// The core function might return an array or an object with a complexityAnalysis property
-      success: false,
+			const analysisArray = Array.isArray(report)
-      error: {
+				? report
-        code: 'CORE_FUNCTION_ERROR',
+				: report.complexityAnalysis || [];
-        message: error.message
+
-      }
+			// Count tasks by complexity
-    };
+			const highComplexityTasks = analysisArray.filter(
-  }
+				(t) => t.complexityScore >= 8
+			).length;
+			const mediumComplexityTasks = analysisArray.filter(
+				(t) => t.complexityScore >= 5 && t.complexityScore < 8
+			).length;
+			const lowComplexityTasks = analysisArray.filter(
+				(t) => t.complexityScore < 5
+			).length;
+
+			return {
+				success: true,
+				data: {
+					message: `Task complexity analysis complete. Report saved to ${resolvedOutputPath}`,
+					reportPath: resolvedOutputPath,
+					reportSummary: {
+						taskCount: analysisArray.length,
+						highComplexityTasks,
+						mediumComplexityTasks,
+						lowComplexityTasks
+					}
+				}
+			};
+		} catch (parseError) {
+			log.error(`Error parsing report file: ${parseError.message}`);
+			return {
+				success: false,
+				error: {
+					code: 'REPORT_PARSE_ERROR',
+					message: `Error parsing complexity report: ${parseError.message}`
+				}
+			};
+		}
+	} catch (error) {
+		// Make sure to restore normal logging even if there's an error
+		if (isSilentMode()) {
+			disableSilentMode();
+		}
+
+		log.error(`Error in analyzeTaskComplexityDirect: ${error.message}`);
+		return {
+			success: false,
+			error: {
+				code: 'CORE_FUNCTION_ERROR',
+				message: error.message
+			}
+		};
+	}
 }

mcp-server/src/core/direct-functions/cache-stats.js

@@ -12,21 +12,21 @@ import { contextManager } from '../context-manager.js';
  * @returns {Object} - Cache statistics
  */
 export async function getCacheStatsDirect(args, log) {
-  try {
+	try {
-    log.info('Retrieving cache statistics');
+		log.info('Retrieving cache statistics');
-    const stats = contextManager.getStats();
+		const stats = contextManager.getStats();
-    return {
+		return {
-      success: true,
+			success: true,
-      data: stats
+			data: stats
-    };
+		};
-  } catch (error) {
+	} catch (error) {
-    log.error(`Error getting cache stats: ${error.message}`);
+		log.error(`Error getting cache stats: ${error.message}`);
-    return {
+		return {
-      success: false,
+			success: false,
-      error: {
+			error: {
-        code: 'CACHE_STATS_ERROR',
+				code: 'CACHE_STATS_ERROR',
-        message: error.message || 'Unknown error occurred'
+				message: error.message || 'Unknown error occurred'
-      }
+			}
-    };
+		};
-  }
+	}
 }

mcp-server/src/core/direct-functions/clear-subtasks.js

@@ -3,110 +3,126 @@
  */
 
 import { clearSubtasks } from '../../../../scripts/modules/task-manager.js';
-import { findTasksJsonPath } from '../utils/path-utils.js';
+import {
-import { enableSilentMode, disableSilentMode } from '../../../../scripts/modules/utils.js';
+	enableSilentMode,
+	disableSilentMode
+} from '../../../../scripts/modules/utils.js';
 import fs from 'fs';
 
 /**
  * Clear subtasks from specified tasks
  * @param {Object} args - Function arguments
+ * @param {string} args.tasksJsonPath - Explicit path to the tasks.json file.
  * @param {string} [args.id] - Task IDs (comma-separated) to clear subtasks from
  * @param {boolean} [args.all] - Clear subtasks from all tasks
- * @param {string} [args.file] - Path to the tasks file
- * @param {string} [args.projectRoot] - Project root directory
  * @param {Object} log - Logger object
  * @returns {Promise<{success: boolean, data?: Object, error?: {code: string, message: string}}>}
  */
 export async function clearSubtasksDirect(args, log) {
-  try {
+	// Destructure expected args
-    log.info(`Clearing subtasks with args: ${JSON.stringify(args)}`);
+	const { tasksJsonPath, id, all } = args;
+	try {
+		log.info(`Clearing subtasks with args: ${JSON.stringify(args)}`);
 
-    // Either id or all must be provided
+		// Check if tasksJsonPath was provided
-    if (!args.id && !args.all) {
+		if (!tasksJsonPath) {
-      return {
+			log.error('clearSubtasksDirect called without tasksJsonPath');
-        success: false,
+			return {
-        error: {
+				success: false,
-          code: 'INPUT_VALIDATION_ERROR',
+				error: {
-          message: 'Either task IDs with id parameter or all parameter must be provided'
+					code: 'MISSING_ARGUMENT',
-        }
+					message: 'tasksJsonPath is required'
-      };
+				}
-    }
+			};
+		}
 
-    // Find the tasks.json path
+		// Either id or all must be provided
-    const tasksPath = findTasksJsonPath(args, log);
+		if (!id && !all) {
+			return {
+				success: false,
+				error: {
+					code: 'INPUT_VALIDATION_ERROR',
+					message:
+						'Either task IDs with id parameter or all parameter must be provided'
+				}
+			};
+		}
 
-    // Check if tasks.json exists
+		// Use provided path
-    if (!fs.existsSync(tasksPath)) {
+		const tasksPath = tasksJsonPath;
-      return {
-        success: false,
-        error: {
-          code: 'FILE_NOT_FOUND_ERROR',
-          message: `Tasks file not found at ${tasksPath}`
-        }
-      };
-    }
 
-    let taskIds;
+		// Check if tasks.json exists
+		if (!fs.existsSync(tasksPath)) {
+			return {
+				success: false,
+				error: {
+					code: 'FILE_NOT_FOUND_ERROR',
+					message: `Tasks file not found at ${tasksPath}`
+				}
+			};
+		}
 
-    // If all is specified, get all task IDs
+		let taskIds;
-    if (args.all) {
-      log.info('Clearing subtasks from all tasks');
-      const data = JSON.parse(fs.readFileSync(tasksPath, 'utf8'));
-      if (!data || !data.tasks || data.tasks.length === 0) {
-        return {
-          success: false,
-          error: {
-            code: 'INPUT_VALIDATION_ERROR',
-            message: 'No valid tasks found in the tasks file'
-          }
-        };
-      }
-      taskIds = data.tasks.map(t => t.id).join(',');
-    } else {
-      // Use the provided task IDs
-      taskIds = args.id;
-    }
 
-    log.info(`Clearing subtasks from tasks: ${taskIds}`);
+		// If all is specified, get all task IDs
+		if (all) {
+			log.info('Clearing subtasks from all tasks');
+			const data = JSON.parse(fs.readFileSync(tasksPath, 'utf8'));
+			if (!data || !data.tasks || data.tasks.length === 0) {
+				return {
+					success: false,
+					error: {
+						code: 'INPUT_VALIDATION_ERROR',
+						message: 'No valid tasks found in the tasks file'
+					}
+				};
+			}
+			taskIds = data.tasks.map((t) => t.id).join(',');
+		} else {
+			// Use the provided task IDs
+			taskIds = id;
+		}
 
-    // Enable silent mode to prevent console logs from interfering with JSON response
+		log.info(`Clearing subtasks from tasks: ${taskIds}`);
-    enableSilentMode();
 
-    // Call the core function
+		// Enable silent mode to prevent console logs from interfering with JSON response
-    clearSubtasks(tasksPath, taskIds);
+		enableSilentMode();
 
-    // Restore normal logging
+		// Call the core function
-    disableSilentMode();
+		clearSubtasks(tasksPath, taskIds);
 
-    // Read the updated data to provide a summary
+		// Restore normal logging
-    const updatedData = JSON.parse(fs.readFileSync(tasksPath, 'utf8'));
+		disableSilentMode();
-    const taskIdArray = taskIds.split(',').map(id => parseInt(id.trim(), 10));
 
-    // Build a summary of what was done
+		// Read the updated data to provide a summary
-    const clearedTasksCount = taskIdArray.length;
+		const updatedData = JSON.parse(fs.readFileSync(tasksPath, 'utf8'));
-    const taskSummary = taskIdArray.map(id => {
+		const taskIdArray = taskIds.split(',').map((id) => parseInt(id.trim(), 10));
-      const task = updatedData.tasks.find(t => t.id === id);
-      return task ? { id, title: task.title } : { id, title: 'Task not found' };
-    });
 
-    return {
+		// Build a summary of what was done
-      success: true,
+		const clearedTasksCount = taskIdArray.length;
-      data: {
+		const taskSummary = taskIdArray.map((id) => {
-        message: `Successfully cleared subtasks from ${clearedTasksCount} task(s)`,
+			const task = updatedData.tasks.find((t) => t.id === id);
-        tasksCleared: taskSummary
+			return task ? { id, title: task.title } : { id, title: 'Task not found' };
-      }
+		});
-    };
-  } catch (error) {
-    // Make sure to restore normal logging even if there's an error
-    disableSilentMode();
 
-    log.error(`Error in clearSubtasksDirect: ${error.message}`);
+		return {
-    return {
+			success: true,
-      success: false,
+			data: {
-      error: {
+				message: `Successfully cleared subtasks from ${clearedTasksCount} task(s)`,
-        code: 'CORE_FUNCTION_ERROR',
+				tasksCleared: taskSummary
-        message: error.message
+			}
-      }
+		};
-    };
+	} catch (error) {
-  }
+		// Make sure to restore normal logging even if there's an error
+		disableSilentMode();
+
+		log.error(`Error in clearSubtasksDirect: ${error.message}`);
+		return {
+			success: false,
+			error: {
+				code: 'CORE_FUNCTION_ERROR',
+				message: error.message
+			}
+		};
+	}
 }

mcp-server/src/core/direct-functions/complexity-report.js

@@ -3,119 +3,128 @@
  * Direct function implementation for displaying complexity analysis report
  */
 
-import { readComplexityReport, enableSilentMode, disableSilentMode } from '../../../../scripts/modules/utils.js';
+import {
-import { findTasksJsonPath } from '../utils/path-utils.js';
+	readComplexityReport,
+	enableSilentMode,
+	disableSilentMode
+} from '../../../../scripts/modules/utils.js';
 import { getCachedOrExecute } from '../../tools/utils.js';
 import path from 'path';
 
 /**
  * Direct function wrapper for displaying the complexity report with error handling and caching.
  *
- * @param {Object} args - Command arguments containing file path option
+ * @param {Object} args - Command arguments containing reportPath.
+ * @param {string} args.reportPath - Explicit path to the complexity report file.
  * @param {Object} log - Logger object
  * @returns {Promise<Object>} - Result object with success status and data/error information
  */
 export async function complexityReportDirect(args, log) {
-  try {
+	// Destructure expected args
-    log.info(`Getting complexity report with args: ${JSON.stringify(args)}`);
+	const { reportPath } = args;
+	try {
+		log.info(`Getting complexity report with args: ${JSON.stringify(args)}`);
 
-    // Get tasks file path to determine project root for the default report location
+		// Check if reportPath was provided
-    let tasksPath;
+		if (!reportPath) {
-    try {
+			log.error('complexityReportDirect called without reportPath');
-      tasksPath = findTasksJsonPath(args, log);
+			return {
-    } catch (error) {
+				success: false,
-      log.warn(`Tasks file not found, using current directory: ${error.message}`);
+				error: { code: 'MISSING_ARGUMENT', message: 'reportPath is required' },
-      // Continue with default or specified report path
+				fromCache: false
-    }
+			};
+		}
 
-    // Get report file path from args or use default
+		// Use the provided report path
-    const reportPath = args.file || path.join(process.cwd(), 'scripts', 'task-complexity-report.json');
+		log.info(`Looking for complexity report at: ${reportPath}`);
 
-    log.info(`Looking for complexity report at: ${reportPath}`);
+		// Generate cache key based on report path
+		const cacheKey = `complexityReport:${reportPath}`;
 
-    // Generate cache key based on report path
+		// Define the core action function to read the report
-    const cacheKey = `complexityReport:${reportPath}`;
+		const coreActionFn = async () => {
+			try {
+				// Enable silent mode to prevent console logs from interfering with JSON response
+				enableSilentMode();
 
-    // Define the core action function to read the report
+				const report = readComplexityReport(reportPath);
-    const coreActionFn = async () => {
-      try {
-        // Enable silent mode to prevent console logs from interfering with JSON response
-        enableSilentMode();
 
-        const report = readComplexityReport(reportPath);
+				// Restore normal logging
+				disableSilentMode();
 
-        // Restore normal logging
+				if (!report) {
-        disableSilentMode();
+					log.warn(`No complexity report found at ${reportPath}`);
+					return {
+						success: false,
+						error: {
+							code: 'FILE_NOT_FOUND_ERROR',
+							message: `No complexity report found at ${reportPath}. Run 'analyze-complexity' first.`
+						}
+					};
+				}
 
-        if (!report) {
+				return {
-          log.warn(`No complexity report found at ${reportPath}`);
+					success: true,
-          return { 
+					data: {
-            success: false, 
+						report,
-            error: { 
+						reportPath
-              code: 'FILE_NOT_FOUND_ERROR', 
+					}
-              message: `No complexity report found at ${reportPath}. Run 'analyze-complexity' first.` 
+				};
-            }
+			} catch (error) {
-          };
+				// Make sure to restore normal logging even if there's an error
-        }
+				disableSilentMode();
 
-        return {
+				log.error(`Error reading complexity report: ${error.message}`);
-          success: true,
+				return {
-          data: {
+					success: false,
-            report,
+					error: {
-            reportPath
+						code: 'READ_ERROR',
-          }
+						message: error.message
-        };
+					}
-      } catch (error) {
+				};
-        // Make sure to restore normal logging even if there's an error
+			}
-        disableSilentMode();
+		};
 
-        log.error(`Error reading complexity report: ${error.message}`);
+		// Use the caching utility
-        return { 
+		try {
-          success: false, 
+			const result = await getCachedOrExecute({
-          error: { 
+				cacheKey,
-            code: 'READ_ERROR', 
+				actionFn: coreActionFn,
-            message: error.message 
+				log
-          }
+			});
-        };
+			log.info(
-      }
+				`complexityReportDirect completed. From cache: ${result.fromCache}`
-    };
+			);
+			return result; // Returns { success, data/error, fromCache }
+		} catch (error) {
+			// Catch unexpected errors from getCachedOrExecute itself
+			// Ensure silent mode is disabled
+			disableSilentMode();
 
-    // Use the caching utility
+			log.error(
-    try {
+				`Unexpected error during getCachedOrExecute for complexityReport: ${error.message}`
-      const result = await getCachedOrExecute({
+			);
-        cacheKey,
+			return {
-        actionFn: coreActionFn,
+				success: false,
-        log
+				error: {
-      });
+					code: 'UNEXPECTED_ERROR',
-      log.info(`complexityReportDirect completed. From cache: ${result.fromCache}`);
+					message: error.message
-      return result; // Returns { success, data/error, fromCache }
+				},
-    } catch (error) {
+				fromCache: false
-      // Catch unexpected errors from getCachedOrExecute itself
+			};
-      // Ensure silent mode is disabled
+		}
-      disableSilentMode();
+	} catch (error) {
+		// Ensure silent mode is disabled if an outer error occurs
+		disableSilentMode();
 
-      log.error(`Unexpected error during getCachedOrExecute for complexityReport: ${error.message}`);
+		log.error(`Error in complexityReportDirect: ${error.message}`);
-      return { 
+		return {
-        success: false, 
+			success: false,
-        error: { 
+			error: {
-          code: 'UNEXPECTED_ERROR', 
+				code: 'UNEXPECTED_ERROR',
-          message: error.message 
+				message: error.message
-        }, 
+			},
-        fromCache: false 
+			fromCache: false
-      };
+		};
-    }
+	}
-  } catch (error) {
-    // Ensure silent mode is disabled if an outer error occurs
-    disableSilentMode();
-    
-    log.error(`Error in complexityReportDirect: ${error.message}`);
-    return { 
-      success: false, 
-      error: { 
-        code: 'UNEXPECTED_ERROR', 
-        message: error.message 
-      }, 
-      fromCache: false 
-    };
-  }
 }

mcp-server/src/core/direct-functions/expand-all-tasks.js

@@ -3,84 +3,140 @@
  */
 
 import { expandAllTasks } from '../../../../scripts/modules/task-manager.js';
-import { enableSilentMode, disableSilentMode } from '../../../../scripts/modules/utils.js';
+import {
-import { findTasksJsonPath } from '../utils/path-utils.js';
+	enableSilentMode,
+	disableSilentMode,
+	isSilentMode
+} from '../../../../scripts/modules/utils.js';
+import { getAnthropicClientForMCP } from '../utils/ai-client-utils.js';
+import path from 'path';
+import fs from 'fs';
 
 /**
  * Expand all pending tasks with subtasks
  * @param {Object} args - Function arguments
+ * @param {string} args.tasksJsonPath - Explicit path to the tasks.json file.
  * @param {number|string} [args.num] - Number of subtasks to generate
  * @param {boolean} [args.research] - Enable Perplexity AI for research-backed subtask generation
  * @param {string} [args.prompt] - Additional context to guide subtask generation
  * @param {boolean} [args.force] - Force regeneration of subtasks for tasks that already have them
- * @param {string} [args.file] - Path to the tasks file
- * @param {string} [args.projectRoot] - Project root directory
  * @param {Object} log - Logger object
+ * @param {Object} context - Context object containing session
  * @returns {Promise<{success: boolean, data?: Object, error?: {code: string, message: string}}>}
  */
-export async function expandAllTasksDirect(args, log) {
+export async function expandAllTasksDirect(args, log, context = {}) {
-  try {
+	const { session } = context; // Only extract session, not reportProgress
-    log.info(`Expanding all tasks with args: ${JSON.stringify(args)}`);
+	// Destructure expected args
+	const { tasksJsonPath, num, research, prompt, force } = args;
 
-    // Find the tasks.json path
+	try {
-    const tasksPath = findTasksJsonPath(args, log);
+		log.info(`Expanding all tasks with args: ${JSON.stringify(args)}`);
 
-    // Parse parameters
+		// Check if tasksJsonPath was provided
-    const numSubtasks = args.num ? parseInt(args.num, 10) : undefined;
+		if (!tasksJsonPath) {
-    const useResearch = args.research === true;
+			log.error('expandAllTasksDirect called without tasksJsonPath');
-    const additionalContext = args.prompt || '';
+			return {
-    const forceFlag = args.force === true;
+				success: false,
+				error: {
+					code: 'MISSING_ARGUMENT',
+					message: 'tasksJsonPath is required'
+				}
+			};
+		}
 
-    log.info(`Expanding all tasks with ${numSubtasks || 'default'} subtasks each...`);
+		// Enable silent mode early to prevent any console output
-    if (useResearch) {
+		enableSilentMode();
-      log.info('Using Perplexity AI for research-backed subtask generation');
-    }
-    if (additionalContext) {
-      log.info(`Additional context: "${additionalContext}"`);
-    }
-    if (forceFlag) {
-      log.info('Force regeneration of subtasks is enabled');
-    }
 
-    try {
+		try {
-      // Enable silent mode to prevent console logs from interfering with JSON response
+			// Remove internal path finding
-      enableSilentMode();
+			/*
+			const tasksPath = findTasksJsonPath(args, log);
+			*/
+			// Use provided path
+			const tasksPath = tasksJsonPath;
 
-      // Call the core function
+			// Parse parameters
-      await expandAllTasks(numSubtasks, useResearch, additionalContext, forceFlag);
+			const numSubtasks = num ? parseInt(num, 10) : undefined;
+			const useResearch = research === true;
+			const additionalContext = prompt || '';
+			const forceFlag = force === true;
 
-      // Restore normal logging
+			log.info(
-      disableSilentMode();
+				`Expanding all tasks with ${numSubtasks || 'default'} subtasks each...`
+			);
 
-      // The expandAllTasks function doesn't have a return value, so we'll create our own success response
+			if (useResearch) {
-      return {
+				log.info('Using Perplexity AI for research-backed subtask generation');
-        success: true,
-        data: {
-          message: "Successfully expanded all pending tasks with subtasks",
-          details: {
-            numSubtasks: numSubtasks,
-            research: useResearch,
-            prompt: additionalContext,
-            force: forceFlag
-          }
-        }
-      };
-    } catch (error) {
-      // Make sure to restore normal logging even if there's an error
-      disableSilentMode();
-      throw error; // Rethrow to be caught by outer catch block
-    }
-  } catch (error) {
-    // Ensure silent mode is disabled
-    disableSilentMode();
 
-    log.error(`Error in expandAllTasksDirect: ${error.message}`);
+				// Initialize AI client for research-backed expansion
-    return {
+				try {
-      success: false,
+					await getAnthropicClientForMCP(session, log);
-      error: {
+				} catch (error) {
-        code: 'CORE_FUNCTION_ERROR',
+					// Ensure silent mode is disabled before returning error
-        message: error.message
+					disableSilentMode();
-      }
+
-    };
+					log.error(`Failed to initialize AI client: ${error.message}`);
-  }
+					return {
+						success: false,
+						error: {
+							code: 'AI_CLIENT_ERROR',
+							message: `Cannot initialize AI client: ${error.message}`
+						}
+					};
+				}
+			}
+
+			if (additionalContext) {
+				log.info(`Additional context: "${additionalContext}"`);
+			}
+			if (forceFlag) {
+				log.info('Force regeneration of subtasks is enabled');
+			}
+
+			// Call the core function with session context for AI operations
+			// and outputFormat as 'json' to prevent UI elements
+			const result = await expandAllTasks(
+				tasksPath,
+				numSubtasks,
+				useResearch,
+				additionalContext,
+				forceFlag,
+				{ mcpLog: log, session },
+				'json' // Use JSON output format to prevent UI elements
+			);
+
+			// The expandAllTasks function now returns a result object
+			return {
+				success: true,
+				data: {
+					message: 'Successfully expanded all pending tasks with subtasks',
+					details: {
+						numSubtasks: numSubtasks,
+						research: useResearch,
+						prompt: additionalContext,
+						force: forceFlag,
+						tasksExpanded: result.expandedCount,
+						totalEligibleTasks: result.tasksToExpand
+					}
+				}
+			};
+		} finally {
+			// Restore normal logging in finally block to ensure it runs even if there's an error
+			disableSilentMode();
+		}
+	} catch (error) {
+		// Ensure silent mode is disabled if an error occurs
+		if (isSilentMode()) {
+			disableSilentMode();
+		}
+
+		log.error(`Error in expandAllTasksDirect: ${error.message}`);
+		return {
+			success: false,
+			error: {
+				code: 'CORE_FUNCTION_ERROR',
+				message: error.message
+			}
+		};
+	}
 }

mcp-server/src/core/direct-functions/expand-task.js

@@ -4,8 +4,17 @@
  */
 
 import { expandTask } from '../../../../scripts/modules/task-manager.js';
-import { readJSON, writeJSON, enableSilentMode, disableSilentMode } from '../../../../scripts/modules/utils.js';
+import {
-import { findTasksJsonPath } from '../utils/path-utils.js';
+	readJSON,
+	writeJSON,
+	enableSilentMode,
+	disableSilentMode,
+	isSilentMode
+} from '../../../../scripts/modules/utils.js';
+import {
+	getAnthropicClientForMCP,
+	getModelConfig
+} from '../utils/ai-client-utils.js';
 import path from 'path';
 import fs from 'fs';
 
@@ -13,162 +22,249 @@ import fs from 'fs';
  * Direct function wrapper for expanding a task into subtasks with error handling.
  *
  * @param {Object} args - Command arguments
+ * @param {string} args.tasksJsonPath - Explicit path to the tasks.json file.
+ * @param {string} args.id - The ID of the task to expand.
+ * @param {number|string} [args.num] - Number of subtasks to generate.
+ * @param {boolean} [args.research] - Enable Perplexity AI for research-backed subtask generation.
+ * @param {string} [args.prompt] - Additional context to guide subtask generation.
+ * @param {boolean} [args.force] - Force expansion even if subtasks exist.
  * @param {Object} log - Logger object
+ * @param {Object} context - Context object containing session and reportProgress
  * @returns {Promise<Object>} - Task expansion result { success: boolean, data?: any, error?: { code: string, message: string }, fromCache: boolean }
  */
-export async function expandTaskDirect(args, log) {
+export async function expandTaskDirect(args, log, context = {}) {
-  let tasksPath;
+	const { session } = context;
-  try {
+	// Destructure expected args
-    // Find the tasks path first
+	const { tasksJsonPath, id, num, research, prompt, force } = args;
-    tasksPath = findTasksJsonPath(args, log);
-  } catch (error) {
-    log.error(`Tasks file not found: ${error.message}`);
-    return { 
-      success: false, 
-      error: { 
-        code: 'FILE_NOT_FOUND_ERROR', 
-        message: error.message 
-      }, 
-      fromCache: false 
-    };
-  }
 
-  // Validate task ID
+	// Log session root data for debugging
-  const taskId = args.id ? parseInt(args.id, 10) : null;
+	log.info(
-  if (!taskId) {
+		`Session data in expandTaskDirect: ${JSON.stringify({
-    log.error('Task ID is required');
+			hasSession: !!session,
-    return { 
+			sessionKeys: session ? Object.keys(session) : [],
-      success: false, 
+			roots: session?.roots,
-      error: { 
+			rootsStr: JSON.stringify(session?.roots)
-        code: 'INPUT_VALIDATION_ERROR', 
+		})}`
-        message: 'Task ID is required' 
+	);
-      }, 
-      fromCache: false 
-    };
-  }
 
-  // Process other parameters
+	// Check if tasksJsonPath was provided
-  const numSubtasks = args.num ? parseInt(args.num, 10) : undefined;
+	if (!tasksJsonPath) {
-  const useResearch = args.research === true;
+		log.error('expandTaskDirect called without tasksJsonPath');
-  const additionalContext = args.prompt || '';
+		return {
-  const force = args.force === true;
+			success: false,
+			error: {
+				code: 'MISSING_ARGUMENT',
+				message: 'tasksJsonPath is required'
+			},
+			fromCache: false
+		};
+	}
 
-  try {
+	// Use provided path
-    log.info(`Expanding task ${taskId} into ${numSubtasks || 'default'} subtasks. Research: ${useResearch}, Force: ${force}`);
+	const tasksPath = tasksJsonPath;
 
-    // Read tasks data
+	log.info(`[expandTaskDirect] Using tasksPath: ${tasksPath}`);
-    const data = readJSON(tasksPath);
-    if (!data || !data.tasks) {
-      return { 
-        success: false, 
-        error: { 
-          code: 'INVALID_TASKS_FILE', 
-          message: `No valid tasks found in ${tasksPath}` 
-        }, 
-        fromCache: false
-      };
-    }
 
-    // Find the specific task
+	// Validate task ID
-    const task = data.tasks.find(t => t.id === taskId);
+	const taskId = id ? parseInt(id, 10) : null;
+	if (!taskId) {
+		log.error('Task ID is required');
+		return {
+			success: false,
+			error: {
+				code: 'INPUT_VALIDATION_ERROR',
+				message: 'Task ID is required'
+			},
+			fromCache: false
+		};
+	}
 
-    if (!task) {
+	// Process other parameters
-      return { 
+	const numSubtasks = num ? parseInt(num, 10) : undefined;
-        success: false, 
+	const useResearch = research === true;
-        error: { 
+	const additionalContext = prompt || '';
-          code: 'TASK_NOT_FOUND', 
+	const forceFlag = force === true;
-          message: `Task with ID ${taskId} not found` 
-        }, 
-        fromCache: false
-      };
-    }
 
-    // Check if task is completed
+	// Initialize AI client if needed (for expandTask function)
-    if (task.status === 'done' || task.status === 'completed') {
+	try {
-      return { 
+		// This ensures the AI client is available by checking it
-        success: false, 
+		if (useResearch) {
-        error: { 
+			log.info('Verifying AI client for research-backed expansion');
-          code: 'TASK_COMPLETED', 
+			await getAnthropicClientForMCP(session, log);
-          message: `Task ${taskId} is already marked as ${task.status} and cannot be expanded` 
+		}
-        }, 
+	} catch (error) {
-        fromCache: false
+		log.error(`Failed to initialize AI client: ${error.message}`);
-      };
+		return {
-    }
+			success: false,
+			error: {
+				code: 'AI_CLIENT_ERROR',
+				message: `Cannot initialize AI client: ${error.message}`
+			},
+			fromCache: false
+		};
+	}
 
-    // Check for existing subtasks
+	try {
-    const hasExistingSubtasks = task.subtasks && task.subtasks.length > 0;
+		log.info(
+			`[expandTaskDirect] Expanding task ${taskId} into ${numSubtasks || 'default'} subtasks. Research: ${useResearch}`
+		);
 
-    // Keep a copy of the task before modification
+		// Read tasks data
-    const originalTask = JSON.parse(JSON.stringify(task));
+		log.info(`[expandTaskDirect] Attempting to read JSON from: ${tasksPath}`);
+		const data = readJSON(tasksPath);
+		log.info(
+			`[expandTaskDirect] Result of readJSON: ${data ? 'Data read successfully' : 'readJSON returned null or undefined'}`
+		);
 
-    // Tracking subtasks count before expansion
+		if (!data || !data.tasks) {
-    const subtasksCountBefore = task.subtasks ? task.subtasks.length : 0;
+			log.error(
+				`[expandTaskDirect] readJSON failed or returned invalid data for path: ${tasksPath}`
+			);
+			return {
+				success: false,
+				error: {
+					code: 'INVALID_TASKS_FILE',
+					message: `No valid tasks found in ${tasksPath}. readJSON returned: ${JSON.stringify(data)}`
+				},
+				fromCache: false
+			};
+		}
 
-    // Create a backup of the tasks.json file
+		// Find the specific task
-    const backupPath = path.join(path.dirname(tasksPath), 'tasks.json.bak');
+		log.info(`[expandTaskDirect] Searching for task ID ${taskId} in data`);
-    fs.copyFileSync(tasksPath, backupPath);
+		const task = data.tasks.find((t) => t.id === taskId);
+		log.info(`[expandTaskDirect] Task found: ${task ? 'Yes' : 'No'}`);
 
-    // Directly modify the data instead of calling the CLI function
+		if (!task) {
-    if (!task.subtasks) {
+			return {
-      task.subtasks = [];
+				success: false,
-    }
+				error: {
+					code: 'TASK_NOT_FOUND',
+					message: `Task with ID ${taskId} not found`
+				},
+				fromCache: false
+			};
+		}
 
-    // Save tasks.json with potentially empty subtasks array
+		// Check if task is completed
-    writeJSON(tasksPath, data);
+		if (task.status === 'done' || task.status === 'completed') {
+			return {
+				success: false,
+				error: {
+					code: 'TASK_COMPLETED',
+					message: `Task ${taskId} is already marked as ${task.status} and cannot be expanded`
+				},
+				fromCache: false
+			};
+		}
 
-    // Process the request
+		// Check for existing subtasks and force flag
-    try {
+		const hasExistingSubtasks = task.subtasks && task.subtasks.length > 0;
-      // Enable silent mode to prevent console logs from interfering with JSON response
+		if (hasExistingSubtasks && !forceFlag) {
-      enableSilentMode();
+			log.info(
+				`Task ${taskId} already has ${task.subtasks.length} subtasks. Use --force to overwrite.`
+			);
+			return {
+				success: true,
+				data: {
+					message: `Task ${taskId} already has subtasks. Expansion skipped.`,
+					task,
+					subtasksAdded: 0,
+					hasExistingSubtasks
+				},
+				fromCache: false
+			};
+		}
 
-      // Call expandTask
+		// If force flag is set, clear existing subtasks
-      const result = await expandTask(taskId, numSubtasks, useResearch, additionalContext);
+		if (hasExistingSubtasks && forceFlag) {
+			log.info(
+				`Force flag set. Clearing existing subtasks for task ${taskId}.`
+			);
+			task.subtasks = [];
+		}
 
-      // Restore normal logging
+		// Keep a copy of the task before modification
-      disableSilentMode();
+		const originalTask = JSON.parse(JSON.stringify(task));
 
-      // Read the updated data
+		// Tracking subtasks count before expansion
-      const updatedData = readJSON(tasksPath);
+		const subtasksCountBefore = task.subtasks ? task.subtasks.length : 0;
-      const updatedTask = updatedData.tasks.find(t => t.id === taskId);
 
-      // Calculate how many subtasks were added
+		// Create a backup of the tasks.json file
-      const subtasksAdded = updatedTask.subtasks ? 
+		const backupPath = path.join(path.dirname(tasksPath), 'tasks.json.bak');
-        updatedTask.subtasks.length - subtasksCountBefore : 0;
+		fs.copyFileSync(tasksPath, backupPath);
 
-      // Return the result
+		// Directly modify the data instead of calling the CLI function
-      log.info(`Successfully expanded task ${taskId} with ${subtasksAdded} new subtasks`);
+		if (!task.subtasks) {
-      return { 
+			task.subtasks = [];
-        success: true, 
+		}
-        data: { 
-          task: updatedTask,
-          subtasksAdded,
-          hasExistingSubtasks
-        }, 
-        fromCache: false 
-      };
-    } catch (error) {
-      // Make sure to restore normal logging even if there's an error
-      disableSilentMode();
 
-      log.error(`Error expanding task: ${error.message}`);
+		// Save tasks.json with potentially empty subtasks array
-      return { 
+		writeJSON(tasksPath, data);
-        success: false, 
+
-        error: { 
+		// Process the request
-          code: 'CORE_FUNCTION_ERROR', 
+		try {
-          message: error.message || 'Failed to expand task' 
+			// Enable silent mode to prevent console logs from interfering with JSON response
-        }, 
+			enableSilentMode();
-        fromCache: false 
+
-      };
+			// Call expandTask with session context to ensure AI client is properly initialized
-    }
+			const result = await expandTask(
-  } catch (error) {
+				tasksPath,
-    log.error(`Error expanding task: ${error.message}`);
+				taskId,
-    return { 
+				numSubtasks,
-      success: false, 
+				useResearch,
-      error: { 
+				additionalContext,
-        code: 'CORE_FUNCTION_ERROR', 
+				{ mcpLog: log, session } // Only pass mcpLog and session, NOT reportProgress
-        message: error.message || 'Failed to expand task' 
+			);
-      }, 
+
-      fromCache: false 
+			// Restore normal logging
-    };
+			disableSilentMode();
-  }
+
+			// Read the updated data
+			const updatedData = readJSON(tasksPath);
+			const updatedTask = updatedData.tasks.find((t) => t.id === taskId);
+
+			// Calculate how many subtasks were added
+			const subtasksAdded = updatedTask.subtasks
+				? updatedTask.subtasks.length - subtasksCountBefore
+				: 0;
+
+			// Return the result
+			log.info(
+				`Successfully expanded task ${taskId} with ${subtasksAdded} new subtasks`
+			);
+			return {
+				success: true,
+				data: {
+					task: updatedTask,
+					subtasksAdded,
+					hasExistingSubtasks
+				},
+				fromCache: false
+			};
+		} catch (error) {
+			// Make sure to restore normal logging even if there's an error
+			disableSilentMode();
+
+			log.error(`Error expanding task: ${error.message}`);
+			return {
+				success: false,
+				error: {
+					code: 'CORE_FUNCTION_ERROR',
+					message: error.message || 'Failed to expand task'
+				},
+				fromCache: false
+			};
+		}
+	} catch (error) {
+		log.error(`Error expanding task: ${error.message}`);
+		return {
+			success: false,
+			error: {
+				code: 'CORE_FUNCTION_ERROR',
+				message: error.message || 'Failed to expand task'
+			},
+			fromCache: false
+		};
+	}
 }

mcp-server/src/core/direct-functions/fix-dependencies.js

@@ -3,63 +3,78 @@
  */
 
 import { fixDependenciesCommand } from '../../../../scripts/modules/dependency-manager.js';
-import { findTasksJsonPath } from '../utils/path-utils.js';
+import {
-import { enableSilentMode, disableSilentMode } from '../../../../scripts/modules/utils.js';
+	enableSilentMode,
+	disableSilentMode
+} from '../../../../scripts/modules/utils.js';
 import fs from 'fs';
 
 /**
  * Fix invalid dependencies in tasks.json automatically
  * @param {Object} args - Function arguments
- * @param {string} [args.file] - Path to the tasks file
+ * @param {string} args.tasksJsonPath - Explicit path to the tasks.json file.
- * @param {string} [args.projectRoot] - Project root directory
  * @param {Object} log - Logger object
  * @returns {Promise<{success: boolean, data?: Object, error?: {code: string, message: string}}>}
  */
 export async function fixDependenciesDirect(args, log) {
-  try {
+	// Destructure expected args
-    log.info(`Fixing invalid dependencies in tasks...`);
+	const { tasksJsonPath } = args;
+	try {
+		log.info(`Fixing invalid dependencies in tasks: ${tasksJsonPath}`);
 
-    // Find the tasks.json path
+		// Check if tasksJsonPath was provided
-    const tasksPath = findTasksJsonPath(args, log);
+		if (!tasksJsonPath) {
+			log.error('fixDependenciesDirect called without tasksJsonPath');
+			return {
+				success: false,
+				error: {
+					code: 'MISSING_ARGUMENT',
+					message: 'tasksJsonPath is required'
+				}
+			};
+		}
 
-    // Verify the file exists
+		// Use provided path
-    if (!fs.existsSync(tasksPath)) {
+		const tasksPath = tasksJsonPath;
-      return {
-        success: false,
-        error: {
-          code: 'FILE_NOT_FOUND',
-          message: `Tasks file not found at ${tasksPath}`
-        }
-      };
-    }
 
-    // Enable silent mode to prevent console logs from interfering with JSON response
+		// Verify the file exists
-    enableSilentMode();
+		if (!fs.existsSync(tasksPath)) {
+			return {
+				success: false,
+				error: {
+					code: 'FILE_NOT_FOUND',
+					message: `Tasks file not found at ${tasksPath}`
+				}
+			};
+		}
 
-    // Call the original command function
+		// Enable silent mode to prevent console logs from interfering with JSON response
-    await fixDependenciesCommand(tasksPath);
+		enableSilentMode();
 
-    // Restore normal logging
+		// Call the original command function using the provided path
-    disableSilentMode();
+		await fixDependenciesCommand(tasksPath);
 
-    return {
+		// Restore normal logging
-      success: true,
+		disableSilentMode();
-      data: {
-        message: 'Dependencies fixed successfully',
-        tasksPath
-      }
-    };
-  } catch (error) {
-    // Make sure to restore normal logging even if there's an error
-    disableSilentMode();
 
-    log.error(`Error fixing dependencies: ${error.message}`);
+		return {
-    return {
+			success: true,
-      success: false,
+			data: {
-      error: {
+				message: 'Dependencies fixed successfully',
-        code: 'FIX_DEPENDENCIES_ERROR',
+				tasksPath
-        message: error.message
+			}
-      }
+		};
-    };
+	} catch (error) {
-  }
+		// Make sure to restore normal logging even if there's an error
+		disableSilentMode();
+
+		log.error(`Error fixing dependencies: ${error.message}`);
+		return {
+			success: false,
+			error: {
+				code: 'FIX_DEPENDENCIES_ERROR',
+				message: error.message
+			}
+		};
+	}
 }

mcp-server/src/core/direct-functions/generate-task-files.js

@@ -4,84 +4,97 @@
  */
 
 import { generateTaskFiles } from '../../../../scripts/modules/task-manager.js';
-import { enableSilentMode, disableSilentMode } from '../../../../scripts/modules/utils.js';
+import {
-import { findTasksJsonPath } from '../utils/path-utils.js';
+	enableSilentMode,
+	disableSilentMode
+} from '../../../../scripts/modules/utils.js';
 import path from 'path';
 
 /**
  * Direct function wrapper for generateTaskFiles with error handling.
  *
- * @param {Object} args - Command arguments containing file and output path options.
+ * @param {Object} args - Command arguments containing tasksJsonPath and outputDir.
  * @param {Object} log - Logger object.
  * @returns {Promise<Object>} - Result object with success status and data/error information.
  */
 export async function generateTaskFilesDirect(args, log) {
-  try {
+	// Destructure expected args
-    log.info(`Generating task files with args: ${JSON.stringify(args)}`);
+	const { tasksJsonPath, outputDir } = args;
+	try {
+		log.info(`Generating task files with args: ${JSON.stringify(args)}`);
 
-    // Get tasks file path
+		// Check if paths were provided
-    let tasksPath;
+		if (!tasksJsonPath) {
-    try {
+			const errorMessage = 'tasksJsonPath is required but was not provided.';
-      tasksPath = findTasksJsonPath(args, log);
+			log.error(errorMessage);
-    } catch (error) {
+			return {
-      log.error(`Error finding tasks file: ${error.message}`);
+				success: false,
-      return { 
+				error: { code: 'MISSING_ARGUMENT', message: errorMessage },
-        success: false, 
+				fromCache: false
-        error: { code: 'TASKS_FILE_ERROR', message: error.message },
+			};
-        fromCache: false 
+		}
-      };
+		if (!outputDir) {
-    }
+			const errorMessage = 'outputDir is required but was not provided.';
+			log.error(errorMessage);
+			return {
+				success: false,
+				error: { code: 'MISSING_ARGUMENT', message: errorMessage },
+				fromCache: false
+			};
+		}
 
-    // Get output directory (defaults to the same directory as the tasks file)
+		// Use the provided paths
-    let outputDir = args.output;
+		const tasksPath = tasksJsonPath;
-    if (!outputDir) {
+		const resolvedOutputDir = outputDir;
-      outputDir = path.dirname(tasksPath);
-    }
 
-    log.info(`Generating task files from ${tasksPath} to ${outputDir}`);
+		log.info(`Generating task files from ${tasksPath} to ${resolvedOutputDir}`);
 
-    // Execute core generateTaskFiles function in a separate try/catch
+		// Execute core generateTaskFiles function in a separate try/catch
-    try {
+		try {
-      // Enable silent mode to prevent logs from being written to stdout
+			// Enable silent mode to prevent logs from being written to stdout
-      enableSilentMode();
+			enableSilentMode();
 
-      // The function is synchronous despite being awaited elsewhere
+			// The function is synchronous despite being awaited elsewhere
-      generateTaskFiles(tasksPath, outputDir);
+			generateTaskFiles(tasksPath, resolvedOutputDir);
 
-      // Restore normal logging after task generation
+			// Restore normal logging after task generation
-      disableSilentMode();
+			disableSilentMode();
-    } catch (genError) {
+		} catch (genError) {
-      // Make sure to restore normal logging even if there's an error
+			// Make sure to restore normal logging even if there's an error
-      disableSilentMode();
+			disableSilentMode();
 
-      log.error(`Error in generateTaskFiles: ${genError.message}`);
+			log.error(`Error in generateTaskFiles: ${genError.message}`);
-      return { 
+			return {
-        success: false, 
+				success: false,
-        error: { code: 'GENERATE_FILES_ERROR', message: genError.message },
+				error: { code: 'GENERATE_FILES_ERROR', message: genError.message },
-        fromCache: false 
+				fromCache: false
-      };
+			};
-    }
+		}
 
-    // Return success with file paths
+		// Return success with file paths
-    return {
+		return {
-      success: true,
+			success: true,
-      data: {
+			data: {
-        message: `Successfully generated task files`,
+				message: `Successfully generated task files`,
-        tasksPath,
+				tasksPath: tasksPath,
-        outputDir,
+				outputDir: resolvedOutputDir,
-        taskFiles: 'Individual task files have been generated in the output directory'
+				taskFiles:
-      },
+					'Individual task files have been generated in the output directory'
-      fromCache: false // This operation always modifies state and should never be cached
+			},
-    };
+			fromCache: false // This operation always modifies state and should never be cached
-  } catch (error) {
+		};
-    // Make sure to restore normal logging if an outer error occurs
+	} catch (error) {
-    disableSilentMode();
+		// Make sure to restore normal logging if an outer error occurs
+		disableSilentMode();
 
-    log.error(`Error generating task files: ${error.message}`);
+		log.error(`Error generating task files: ${error.message}`);
-    return { 
+		return {
-      success: false, 
+			success: false,
-      error: { code: 'GENERATE_TASKS_ERROR', message: error.message || 'Unknown error generating task files' },
+			error: {
-      fromCache: false 
+				code: 'GENERATE_TASKS_ERROR',
-    };
+				message: error.message || 'Unknown error generating task files'
-  }
+			},
+			fromCache: false
+		};
+	}
 }

mcp-server/src/core/direct-functions/initialize-project-direct.js

@@ -0,0 +1,138 @@
+import { initializeProject } from '../../../../scripts/init.js'; // Import core function and its logger if needed separately
+import {
+	enableSilentMode,
+	disableSilentMode
+	// isSilentMode // Not used directly here
+} from '../../../../scripts/modules/utils.js';
+import { getProjectRootFromSession } from '../../tools/utils.js'; // Adjust path if necessary
+import os from 'os'; // Import os module for home directory check
+
+/**
+ * Direct function wrapper for initializing a project.
+ * Derives target directory from session, sets CWD, and calls core init logic.
+ * @param {object} args - Arguments containing project details and options (projectName, projectDescription, yes, etc.)
+ * @param {object} log - The FastMCP logger instance.
+ * @param {object} context - The context object, must contain { session }.
+ * @returns {Promise<{success: boolean, data?: any, error?: {code: string, message: string}}>} - Standard result object.
+ */
+export async function initializeProjectDirect(args, log, context = {}) {
+	const { session } = context;
+	const homeDir = os.homedir();
+	let targetDirectory = null;
+
+	log.info(
+		`CONTEXT received in direct function: ${context ? JSON.stringify(Object.keys(context)) : 'MISSING or Falsy'}`
+	);
+	log.info(
+		`SESSION extracted in direct function: ${session ? 'Exists' : 'MISSING or Falsy'}`
+	);
+	log.info(`Args received in direct function: ${JSON.stringify(args)}`);
+
+	// --- Determine Target Directory ---
+	// 1. Prioritize projectRoot passed directly in args
+	// Ensure it's not null, '/', or the home directory
+	if (
+		args.projectRoot &&
+		args.projectRoot !== '/' &&
+		args.projectRoot !== homeDir
+	) {
+		log.info(`Using projectRoot directly from args: ${args.projectRoot}`);
+		targetDirectory = args.projectRoot;
+	} else {
+		// 2. If args.projectRoot is missing or invalid, THEN try session (as a fallback)
+		log.warn(
+			`args.projectRoot ('${args.projectRoot}') is missing or invalid. Attempting to derive from session.`
+		);
+		const sessionDerivedPath = getProjectRootFromSession(session, log);
+		// Validate the session-derived path as well
+		if (
+			sessionDerivedPath &&
+			sessionDerivedPath !== '/' &&
+			sessionDerivedPath !== homeDir
+		) {
+			log.info(
+				`Using project root derived from session: ${sessionDerivedPath}`
+			);
+			targetDirectory = sessionDerivedPath;
+		} else {
+			log.error(
+				`Could not determine a valid project root. args.projectRoot='${args.projectRoot}', sessionDerivedPath='${sessionDerivedPath}'`
+			);
+		}
+	}
+
+	// 3. Validate the final targetDirectory
+	if (!targetDirectory) {
+		// This error now covers cases where neither args.projectRoot nor session provided a valid path
+		return {
+			success: false,
+			error: {
+				code: 'INVALID_TARGET_DIRECTORY',
+				message: `Cannot initialize project: Could not determine a valid target directory. Please ensure a workspace/folder is open or specify projectRoot.`,
+				details: `Attempted args.projectRoot: ${args.projectRoot}`
+			},
+			fromCache: false
+		};
+	}
+
+	// --- Proceed with validated targetDirectory ---
+	log.info(`Validated target directory for initialization: ${targetDirectory}`);
+
+	const originalCwd = process.cwd();
+	let resultData;
+	let success = false;
+	let errorResult = null;
+
+	log.info(
+		`Temporarily changing CWD to ${targetDirectory} for initialization.`
+	);
+	process.chdir(targetDirectory); // Change CWD to the *validated* targetDirectory
+
+	enableSilentMode(); // Enable silent mode BEFORE calling the core function
+	try {
+		// Always force yes: true when called via MCP to avoid interactive prompts
+		const options = {
+			name: args.projectName,
+			description: args.projectDescription,
+			version: args.projectVersion,
+			author: args.authorName,
+			skipInstall: args.skipInstall,
+			aliases: args.addAliases,
+			yes: true // Force yes mode
+		};
+
+		log.info(`Initializing project with options: ${JSON.stringify(options)}`);
+		const result = await initializeProject(options); // Call core logic
+
+		// Format success result for handleApiResult
+		resultData = {
+			message: 'Project initialized successfully.',
+			next_step:
+				'Now that the project is initialized, the next step is to create the tasks by parsing a PRD. This will create the tasks folder and the initial task files (tasks folder will be created when parse-prd is run). The parse-prd tool will require a prd.txt file as input (typically found in the project root directory, scripts/ directory). You can create a prd.txt file by asking the user about their idea, and then using the scripts/example_prd.txt file as a template to genrate a prd.txt file in scripts/. You may skip all of this if the user already has a prd.txt file. You can THEN use the parse-prd tool to create the tasks. So: step 1 after initialization is to create a prd.txt file in scripts/prd.txt or confirm the user already has one. Step 2 is to use the parse-prd tool to create the tasks. Do not bother looking for tasks after initialization, just use the parse-prd tool to create the tasks after creating a prd.txt from which to parse the tasks. You do NOT need to reinitialize the project to parse-prd.',
+			...result // Include details returned by initializeProject
+		};
+		success = true;
+		log.info(
+			`Project initialization completed successfully in ${targetDirectory}.`
+		);
+	} catch (error) {
+		log.error(`Core initializeProject failed: ${error.message}`);
+		errorResult = {
+			code: 'INITIALIZATION_FAILED',
+			message: `Core project initialization failed: ${error.message}`,
+			details: error.stack
+		};
+		success = false;
+	} finally {
+		disableSilentMode(); // ALWAYS disable silent mode in finally
+		log.info(`Restoring original CWD: ${originalCwd}`);
+		process.chdir(originalCwd); // Change back to original CWD
+	}
+
+	// Return in format expected by handleApiResult
+	if (success) {
+		return { success: true, data: resultData, fromCache: false };
+	} else {
+		return { success: false, error: errorResult, fromCache: false };
+	}
+}

mcp-server/src/core/direct-functions/list-tasks.js

@@ -5,79 +5,108 @@
 
 import { listTasks } from '../../../../scripts/modules/task-manager.js';
 import { getCachedOrExecute } from '../../tools/utils.js';
-import { findTasksJsonPath } from '../utils/path-utils.js';
+import {
-import { enableSilentMode, disableSilentMode } from '../../../../scripts/modules/utils.js';
+	enableSilentMode,
+	disableSilentMode
+} from '../../../../scripts/modules/utils.js';
 
 /**
  * Direct function wrapper for listTasks with error handling and caching.
  *
- * @param {Object} args - Command arguments (projectRoot is expected to be resolved).
+ * @param {Object} args - Command arguments (now expecting tasksJsonPath explicitly).
  * @param {Object} log - Logger object.
  * @returns {Promise<Object>} - Task list result { success: boolean, data?: any, error?: { code: string, message: string }, fromCache: boolean }.
  */
 export async function listTasksDirect(args, log) {
-  let tasksPath;
+	// Destructure the explicit tasksJsonPath from args
-  try {
+	const { tasksJsonPath, status, withSubtasks } = args;
-    // Find the tasks path first - needed for cache key and execution
-    tasksPath = findTasksJsonPath(args, log);
-  } catch (error) {
-    if (error.code === 'TASKS_FILE_NOT_FOUND') {
-      log.error(`Tasks file not found: ${error.message}`);
-      // Return the error structure expected by the calling tool/handler
-      return { success: false, error: { code: error.code, message: error.message }, fromCache: false };
-    }
-    log.error(`Unexpected error finding tasks file: ${error.message}`);
-    // Re-throw for outer catch or return structured error
-     return { success: false, error: { code: 'FIND_TASKS_PATH_ERROR', message: error.message }, fromCache: false };
-  }
 
-  // Generate cache key *after* finding tasksPath
+	if (!tasksJsonPath) {
-  const statusFilter = args.status || 'all';
+		log.error('listTasksDirect called without tasksJsonPath');
-  const withSubtasks = args.withSubtasks || false;
+		return {
-  const cacheKey = `listTasks:${tasksPath}:${statusFilter}:${withSubtasks}`;
+			success: false,
+			error: {
+				code: 'MISSING_ARGUMENT',
+				message: 'tasksJsonPath is required'
+			},
+			fromCache: false
+		};
+	}
 
-  // Define the action function to be executed on cache miss
+	// Use the explicit tasksJsonPath for cache key
-  const coreListTasksAction = async () => {
+	const statusFilter = status || 'all';
-    try {
+	const withSubtasksFilter = withSubtasks || false;
-      // Enable silent mode to prevent console logs from interfering with JSON response
+	const cacheKey = `listTasks:${tasksJsonPath}:${statusFilter}:${withSubtasksFilter}`;
-      enableSilentMode();
 
-      log.info(`Executing core listTasks function for path: ${tasksPath}, filter: ${statusFilter}, subtasks: ${withSubtasks}`);
+	// Define the action function to be executed on cache miss
-      const resultData = listTasks(tasksPath, statusFilter, withSubtasks, 'json');
+	const coreListTasksAction = async () => {
+		try {
+			// Enable silent mode to prevent console logs from interfering with JSON response
+			enableSilentMode();
 
-      if (!resultData || !resultData.tasks) {
+			log.info(
-        log.error('Invalid or empty response from listTasks core function');
+				`Executing core listTasks function for path: ${tasksJsonPath}, filter: ${statusFilter}, subtasks: ${withSubtasksFilter}`
-        return { success: false, error: { code: 'INVALID_CORE_RESPONSE', message: 'Invalid or empty response from listTasks core function' } };
+			);
-      }
+			// Pass the explicit tasksJsonPath to the core function
-      log.info(`Core listTasks function retrieved ${resultData.tasks.length} tasks`);
+			const resultData = listTasks(
+				tasksJsonPath,
+				statusFilter,
+				withSubtasksFilter,
+				'json'
+			);
 
-      // Restore normal logging
+			if (!resultData || !resultData.tasks) {
-      disableSilentMode();
+				log.error('Invalid or empty response from listTasks core function');
+				return {
+					success: false,
+					error: {
+						code: 'INVALID_CORE_RESPONSE',
+						message: 'Invalid or empty response from listTasks core function'
+					}
+				};
+			}
+			log.info(
+				`Core listTasks function retrieved ${resultData.tasks.length} tasks`
+			);
 
-      return { success: true, data: resultData };
+			// Restore normal logging
+			disableSilentMode();
 
-    } catch (error) {
+			return { success: true, data: resultData };
-      // Make sure to restore normal logging even if there's an error
+		} catch (error) {
-      disableSilentMode();
+			// Make sure to restore normal logging even if there's an error
+			disableSilentMode();
 
-      log.error(`Core listTasks function failed: ${error.message}`);
+			log.error(`Core listTasks function failed: ${error.message}`);
-      return { success: false, error: { code: 'LIST_TASKS_CORE_ERROR', message: error.message || 'Failed to list tasks' } };
+			return {
-    }
+				success: false,
-  };
+				error: {
+					code: 'LIST_TASKS_CORE_ERROR',
+					message: error.message || 'Failed to list tasks'
+				}
+			};
+		}
+	};
 
-  // Use the caching utility
+	// Use the caching utility
-  try {
+	try {
-      const result = await getCachedOrExecute({
+		const result = await getCachedOrExecute({
-          cacheKey,
+			cacheKey,
-          actionFn: coreListTasksAction,
+			actionFn: coreListTasksAction,
-          log
+			log
-      });
+		});
-      log.info(`listTasksDirect completed. From cache: ${result.fromCache}`);
+		log.info(`listTasksDirect completed. From cache: ${result.fromCache}`);
-      return result; // Returns { success, data/error, fromCache }
+		return result; // Returns { success, data/error, fromCache }
-  } catch(error) {
+	} catch (error) {
-      // Catch unexpected errors from getCachedOrExecute itself (though unlikely)
+		// Catch unexpected errors from getCachedOrExecute itself (though unlikely)
-      log.error(`Unexpected error during getCachedOrExecute for listTasks: ${error.message}`);
+		log.error(
-      console.error(error.stack);
+			`Unexpected error during getCachedOrExecute for listTasks: ${error.message}`
-      return { success: false, error: { code: 'CACHE_UTIL_ERROR', message: error.message }, fromCache: false };
+		);
-  }
+		console.error(error.stack);
+		return {
+			success: false,
+			error: { code: 'CACHE_UTIL_ERROR', message: error.message },
+			fromCache: false
+		};
+	}
 }

mcp-server/src/core/direct-functions/next-task.js

@@ -6,117 +6,127 @@
 import { findNextTask } from '../../../../scripts/modules/task-manager.js';
 import { readJSON } from '../../../../scripts/modules/utils.js';
 import { getCachedOrExecute } from '../../tools/utils.js';
-import { findTasksJsonPath } from '../utils/path-utils.js';
+import {
-import { enableSilentMode, disableSilentMode } from '../../../../scripts/modules/utils.js';
+	enableSilentMode,
+	disableSilentMode
+} from '../../../../scripts/modules/utils.js';
 
 /**
  * Direct function wrapper for finding the next task to work on with error handling and caching.
  *
  * @param {Object} args - Command arguments
+ * @param {string} args.tasksJsonPath - Explicit path to the tasks.json file.
  * @param {Object} log - Logger object
  * @returns {Promise<Object>} - Next task result { success: boolean, data?: any, error?: { code: string, message: string }, fromCache: boolean }
  */
 export async function nextTaskDirect(args, log) {
-  let tasksPath;
+	// Destructure expected args
-  try {
+	const { tasksJsonPath } = args;
-    // Find the tasks path first - needed for cache key and execution
-    tasksPath = findTasksJsonPath(args, log);
-  } catch (error) {
-    log.error(`Tasks file not found: ${error.message}`);
-    return { 
-      success: false, 
-      error: { 
-        code: 'FILE_NOT_FOUND_ERROR', 
-        message: error.message 
-      }, 
-      fromCache: false 
-    };
-  }
 
-  // Generate cache key using task path
+	if (!tasksJsonPath) {
-  const cacheKey = `nextTask:${tasksPath}`;
+		log.error('nextTaskDirect called without tasksJsonPath');
+		return {
+			success: false,
+			error: {
+				code: 'MISSING_ARGUMENT',
+				message: 'tasksJsonPath is required'
+			},
+			fromCache: false
+		};
+	}
 
-  // Define the action function to be executed on cache miss
+	// Generate cache key using the provided task path
-  const coreNextTaskAction = async () => {
+	const cacheKey = `nextTask:${tasksJsonPath}`;
-    try {
-      // Enable silent mode to prevent console logs from interfering with JSON response
-      enableSilentMode();
 
-      log.info(`Finding next task from ${tasksPath}`);
+	// Define the action function to be executed on cache miss
+	const coreNextTaskAction = async () => {
+		try {
+			// Enable silent mode to prevent console logs from interfering with JSON response
+			enableSilentMode();
 
-      // Read tasks data
+			log.info(`Finding next task from ${tasksJsonPath}`);
-      const data = readJSON(tasksPath);
-      if (!data || !data.tasks) {
-        return { 
-          success: false, 
-          error: { 
-            code: 'INVALID_TASKS_FILE', 
-            message: `No valid tasks found in ${tasksPath}` 
-          } 
-        };
-      }
 
-      // Find the next task
+			// Read tasks data using the provided path
-      const nextTask = findNextTask(data.tasks);
+			const data = readJSON(tasksJsonPath);
+			if (!data || !data.tasks) {
+				disableSilentMode(); // Disable before return
+				return {
+					success: false,
+					error: {
+						code: 'INVALID_TASKS_FILE',
+						message: `No valid tasks found in ${tasksJsonPath}`
+					}
+				};
+			}
 
-      if (!nextTask) {
+			// Find the next task
-        log.info('No eligible next task found. All tasks are either completed or have unsatisfied dependencies');
+			const nextTask = findNextTask(data.tasks);
-        return { 
-          success: true, 
-          data: { 
-            message: 'No eligible next task found. All tasks are either completed or have unsatisfied dependencies',
-            nextTask: null,
-            allTasks: data.tasks 
-          } 
-        };
-      }
 
-      // Restore normal logging
+			if (!nextTask) {
-      disableSilentMode();
+				log.info(
+					'No eligible next task found. All tasks are either completed or have unsatisfied dependencies'
+				);
+				return {
+					success: true,
+					data: {
+						message:
+							'No eligible next task found. All tasks are either completed or have unsatisfied dependencies',
+						nextTask: null,
+						allTasks: data.tasks
+					}
+				};
+			}
 
-      // Return the next task data with the full tasks array for reference
+			// Restore normal logging
-      log.info(`Successfully found next task ${nextTask.id}: ${nextTask.title}`);
+			disableSilentMode();
-      return { 
-        success: true, 
-        data: { 
-          nextTask, 
-          allTasks: data.tasks 
-        } 
-      };
-    } catch (error) {
-      // Make sure to restore normal logging even if there's an error
-      disableSilentMode();
 
-      log.error(`Error finding next task: ${error.message}`);
+			// Return the next task data with the full tasks array for reference
-      return { 
+			log.info(
-        success: false, 
+				`Successfully found next task ${nextTask.id}: ${nextTask.title}`
-        error: { 
+			);
-          code: 'CORE_FUNCTION_ERROR', 
+			return {
-          message: error.message || 'Failed to find next task' 
+				success: true,
-        } 
+				data: {
-      };
+					nextTask,
-    }
+					allTasks: data.tasks
-  };
+				}
+			};
+		} catch (error) {
+			// Make sure to restore normal logging even if there's an error
+			disableSilentMode();
 
-  // Use the caching utility
+			log.error(`Error finding next task: ${error.message}`);
-  try {
+			return {
-    const result = await getCachedOrExecute({
+				success: false,
-      cacheKey,
+				error: {
-      actionFn: coreNextTaskAction,
+					code: 'CORE_FUNCTION_ERROR',
-      log
+					message: error.message || 'Failed to find next task'
-    });
+				}
-    log.info(`nextTaskDirect completed. From cache: ${result.fromCache}`);
+			};
-    return result; // Returns { success, data/error, fromCache }
+		}
-  } catch (error) {
+	};
-    // Catch unexpected errors from getCachedOrExecute itself
+
-    log.error(`Unexpected error during getCachedOrExecute for nextTask: ${error.message}`);
+	// Use the caching utility
-    return { 
+	try {
-      success: false, 
+		const result = await getCachedOrExecute({
-      error: { 
+			cacheKey,
-        code: 'UNEXPECTED_ERROR', 
+			actionFn: coreNextTaskAction,
-        message: error.message 
+			log
-      }, 
+		});
-      fromCache: false 
+		log.info(`nextTaskDirect completed. From cache: ${result.fromCache}`);
-    };
+		return result; // Returns { success, data/error, fromCache }
-  }
+	} catch (error) {
+		// Catch unexpected errors from getCachedOrExecute itself
+		log.error(
+			`Unexpected error during getCachedOrExecute for nextTask: ${error.message}`
+		);
+		return {
+			success: false,
+			error: {
+				code: 'UNEXPECTED_ERROR',
+				message: error.message
+			},
+			fromCache: false
+		};
+	}
 }

mcp-server/src/core/direct-functions/parse-prd.js

@@ -5,110 +5,206 @@
 
 import path from 'path';
 import fs from 'fs';
+import os from 'os'; // Import os module for home directory check
 import { parsePRD } from '../../../../scripts/modules/task-manager.js';
 import { findTasksJsonPath } from '../utils/path-utils.js';
-import { enableSilentMode, disableSilentMode } from '../../../../scripts/modules/utils.js';
+import {
+	enableSilentMode,
+	disableSilentMode
+} from '../../../../scripts/modules/utils.js';
+import {
+	getAnthropicClientForMCP,
+	getModelConfig
+} from '../utils/ai-client-utils.js';
 
 /**
  * Direct function wrapper for parsing PRD documents and generating tasks.
  *
  * @param {Object} args - Command arguments containing input, numTasks or tasks, and output options.
  * @param {Object} log - Logger object.
+ * @param {Object} context - Context object containing session data.
  * @returns {Promise<Object>} - Result object with success status and data/error information.
  */
-export async function parsePRDDirect(args, log) {
+export async function parsePRDDirect(args, log, context = {}) {
-  try {
+	const { session } = context; // Only extract session, not reportProgress
-    log.info(`Parsing PRD document with args: ${JSON.stringify(args)}`);
 
-    // Check required parameters
+	try {
-    if (!args.input) {
+		log.info(`Parsing PRD document with args: ${JSON.stringify(args)}`);
-      const errorMessage = 'No input file specified. Please provide an input PRD document path.';
-      log.error(errorMessage);
-      return { 
-        success: false, 
-        error: { code: 'MISSING_INPUT_FILE', message: errorMessage },
-        fromCache: false 
-      };
-    }
 
-    // Resolve input path (relative to project root if provided)
+		// Initialize AI client for PRD parsing
-    const projectRoot = args.projectRoot || process.cwd();
+		let aiClient;
-    const inputPath = path.isAbsolute(args.input) ? args.input : path.resolve(projectRoot, args.input);
+		try {
+			aiClient = getAnthropicClientForMCP(session, log);
+		} catch (error) {
+			log.error(`Failed to initialize AI client: ${error.message}`);
+			return {
+				success: false,
+				error: {
+					code: 'AI_CLIENT_ERROR',
+					message: `Cannot initialize AI client: ${error.message}`
+				},
+				fromCache: false
+			};
+		}
 
-    // Determine output path
+		// Validate required parameters
-    let outputPath;
+		if (!args.projectRoot) {
-    if (args.output) {
+			const errorMessage = 'Project root is required for parsePRDDirect';
-      outputPath = path.isAbsolute(args.output) ? args.output : path.resolve(projectRoot, args.output);
+			log.error(errorMessage);
-    } else {
+			return {
-      // Default to tasks/tasks.json in the project root
+				success: false,
-      outputPath = path.resolve(projectRoot, 'tasks', 'tasks.json');
+				error: { code: 'MISSING_PROJECT_ROOT', message: errorMessage },
-    }
+				fromCache: false
+			};
+		}
 
-    // Verify input file exists
+		if (!args.input) {
-    if (!fs.existsSync(inputPath)) {
+			const errorMessage = 'Input file path is required for parsePRDDirect';
-      const errorMessage = `Input file not found: ${inputPath}`;
+			log.error(errorMessage);
-      log.error(errorMessage);
+			return {
-      return { 
+				success: false,
-        success: false, 
+				error: { code: 'MISSING_INPUT_PATH', message: errorMessage },
-        error: { code: 'INPUT_FILE_NOT_FOUND', message: errorMessage },
+				fromCache: false
-        fromCache: false 
+			};
-      };
+		}
-    }
 
-    // Parse number of tasks - handle both string and number values
+		if (!args.output) {
-    let numTasks = 10; // Default
+			const errorMessage = 'Output file path is required for parsePRDDirect';
-    if (args.numTasks) {
+			log.error(errorMessage);
-      numTasks = typeof args.numTasks === 'string' ? parseInt(args.numTasks, 10) : args.numTasks;
+			return {
-      if (isNaN(numTasks)) {
+				success: false,
-        numTasks = 10; // Fallback to default if parsing fails
+				error: { code: 'MISSING_OUTPUT_PATH', message: errorMessage },
-        log.warn(`Invalid numTasks value: ${args.numTasks}. Using default: 10`);
+				fromCache: false
-      }
+			};
-    }
+		}
 
-    log.info(`Preparing to parse PRD from ${inputPath} and output to ${outputPath} with ${numTasks} tasks`);
+		// Resolve input path (expecting absolute path or path relative to project root)
+		const projectRoot = args.projectRoot;
+		const inputPath = path.isAbsolute(args.input)
+			? args.input
+			: path.resolve(projectRoot, args.input);
 
-    // Enable silent mode to prevent console logs from interfering with JSON response
+		// Verify input file exists
-    enableSilentMode();
+		if (!fs.existsSync(inputPath)) {
+			const errorMessage = `Input file not found: ${inputPath}`;
+			log.error(errorMessage);
+			return {
+				success: false,
+				error: {
+					code: 'INPUT_FILE_NOT_FOUND',
+					message: errorMessage,
+					details: `Checked path: ${inputPath}\nProject root: ${projectRoot}\nInput argument: ${args.input}`
+				},
+				fromCache: false
+			};
+		}
 
-    // Execute core parsePRD function (which is not async but we'll await it to maintain consistency)
+		// Resolve output path (expecting absolute path or path relative to project root)
-    await parsePRD(inputPath, outputPath, numTasks);
+		const outputPath = path.isAbsolute(args.output)
+			? args.output
+			: path.resolve(projectRoot, args.output);
 
-    // Restore normal logging
+		// Ensure output directory exists
-    disableSilentMode();
+		const outputDir = path.dirname(outputPath);
+		if (!fs.existsSync(outputDir)) {
+			log.info(`Creating output directory: ${outputDir}`);
+			fs.mkdirSync(outputDir, { recursive: true });
+		}
 
-    // Since parsePRD doesn't return a value but writes to a file, we'll read the result
+		// Parse number of tasks - handle both string and number values
-    // to return it to the caller
+		let numTasks = 10; // Default
-    if (fs.existsSync(outputPath)) {
+		if (args.numTasks) {
-      const tasksData = JSON.parse(fs.readFileSync(outputPath, 'utf8'));
+			numTasks =
-      log.info(`Successfully parsed PRD and generated ${tasksData.tasks?.length || 0} tasks`);
+				typeof args.numTasks === 'string'
+					? parseInt(args.numTasks, 10)
+					: args.numTasks;
+			if (isNaN(numTasks)) {
+				numTasks = 10; // Fallback to default if parsing fails
+				log.warn(`Invalid numTasks value: ${args.numTasks}. Using default: 10`);
+			}
+		}
 
-      return {
+		log.info(
-        success: true,
+			`Preparing to parse PRD from ${inputPath} and output to ${outputPath} with ${numTasks} tasks`
-        data: {
+		);
-          message: `Successfully generated ${tasksData.tasks?.length || 0} tasks from PRD`,
-          taskCount: tasksData.tasks?.length || 0,
-          outputPath
-        },
-        fromCache: false // This operation always modifies state and should never be cached
-      };
-    } else {
-      const errorMessage = `Tasks file was not created at ${outputPath}`;
-      log.error(errorMessage);
-      return { 
-        success: false, 
-        error: { code: 'OUTPUT_FILE_NOT_CREATED', message: errorMessage },
-        fromCache: false 
-      };
-    }
-  } catch (error) {
-    // Make sure to restore normal logging even if there's an error
-    disableSilentMode();
 
-    log.error(`Error parsing PRD: ${error.message}`);
+		// Create the logger wrapper for proper logging in the core function
-    return { 
+		const logWrapper = {
-      success: false, 
+			info: (message, ...args) => log.info(message, ...args),
-      error: { code: 'PARSE_PRD_ERROR', message: error.message || 'Unknown error parsing PRD' },
+			warn: (message, ...args) => log.warn(message, ...args),
-      fromCache: false 
+			error: (message, ...args) => log.error(message, ...args),
-    };
+			debug: (message, ...args) => log.debug && log.debug(message, ...args),
-  }
+			success: (message, ...args) => log.info(message, ...args) // Map success to info
+		};
+
+		// Get model config from session
+		const modelConfig = getModelConfig(session);
+
+		// Enable silent mode to prevent console logs from interfering with JSON response
+		enableSilentMode();
+		try {
+			// Make sure the output directory exists
+			const outputDir = path.dirname(outputPath);
+			if (!fs.existsSync(outputDir)) {
+				log.info(`Creating output directory: ${outputDir}`);
+				fs.mkdirSync(outputDir, { recursive: true });
+			}
+
+			// Execute core parsePRD function with AI client
+			await parsePRD(
+				inputPath,
+				outputPath,
+				numTasks,
+				{
+					mcpLog: logWrapper,
+					session
+				},
+				aiClient,
+				modelConfig
+			);
+
+			// Since parsePRD doesn't return a value but writes to a file, we'll read the result
+			// to return it to the caller
+			if (fs.existsSync(outputPath)) {
+				const tasksData = JSON.parse(fs.readFileSync(outputPath, 'utf8'));
+				log.info(
+					`Successfully parsed PRD and generated ${tasksData.tasks?.length || 0} tasks`
+				);
+
+				return {
+					success: true,
+					data: {
+						message: `Successfully generated ${tasksData.tasks?.length || 0} tasks from PRD`,
+						taskCount: tasksData.tasks?.length || 0,
+						outputPath
+					},
+					fromCache: false // This operation always modifies state and should never be cached
+				};
+			} else {
+				const errorMessage = `Tasks file was not created at ${outputPath}`;
+				log.error(errorMessage);
+				return {
+					success: false,
+					error: { code: 'OUTPUT_FILE_NOT_CREATED', message: errorMessage },
+					fromCache: false
+				};
+			}
+		} finally {
+			// Always restore normal logging
+			disableSilentMode();
+		}
+	} catch (error) {
+		// Make sure to restore normal logging even if there's an error
+		disableSilentMode();
+
+		log.error(`Error parsing PRD: ${error.message}`);
+		return {
+			success: false,
+			error: {
+				code: 'PARSE_PRD_ERROR',
+				message: error.message || 'Unknown error parsing PRD'
+			},
+			fromCache: false
+		};
+	}
 }

mcp-server/src/core/direct-functions/remove-dependency.js

@@ -3,81 +3,102 @@
  */
 
 import { removeDependency } from '../../../../scripts/modules/dependency-manager.js';
-import { findTasksJsonPath } from '../utils/path-utils.js';
+import {
-import { enableSilentMode, disableSilentMode } from '../../../../scripts/modules/utils.js';
+	enableSilentMode,
+	disableSilentMode
+} from '../../../../scripts/modules/utils.js';
 
 /**
  * Remove a dependency from a task
  * @param {Object} args - Function arguments
+ * @param {string} args.tasksJsonPath - Explicit path to the tasks.json file.
  * @param {string|number} args.id - Task ID to remove dependency from
  * @param {string|number} args.dependsOn - Task ID to remove as a dependency
- * @param {string} [args.file] - Path to the tasks file
- * @param {string} [args.projectRoot] - Project root directory
  * @param {Object} log - Logger object
  * @returns {Promise<{success: boolean, data?: Object, error?: {code: string, message: string}}>}
  */
 export async function removeDependencyDirect(args, log) {
-  try {
+	// Destructure expected args
-    log.info(`Removing dependency with args: ${JSON.stringify(args)}`);
+	const { tasksJsonPath, id, dependsOn } = args;
+	try {
+		log.info(`Removing dependency with args: ${JSON.stringify(args)}`);
 
-    // Validate required parameters
+		// Check if tasksJsonPath was provided
-    if (!args.id) {
+		if (!tasksJsonPath) {
-      return {
+			log.error('removeDependencyDirect called without tasksJsonPath');
-        success: false,
+			return {
-        error: {
+				success: false,
-          code: 'INPUT_VALIDATION_ERROR',
+				error: {
-          message: 'Task ID (id) is required'
+					code: 'MISSING_ARGUMENT',
-        }
+					message: 'tasksJsonPath is required'
-      };
+				}
-    }
+			};
+		}
 
-    if (!args.dependsOn) {
+		// Validate required parameters
-      return {
+		if (!id) {
-        success: false,
+			return {
-        error: {
+				success: false,
-          code: 'INPUT_VALIDATION_ERROR',
+				error: {
-          message: 'Dependency ID (dependsOn) is required'
+					code: 'INPUT_VALIDATION_ERROR',
-        }
+					message: 'Task ID (id) is required'
-      };
+				}
-    }
+			};
+		}
 
-    // Find the tasks.json path
+		if (!dependsOn) {
-    const tasksPath = findTasksJsonPath(args, log);
+			return {
+				success: false,
+				error: {
+					code: 'INPUT_VALIDATION_ERROR',
+					message: 'Dependency ID (dependsOn) is required'
+				}
+			};
+		}
 
-    // Format IDs for the core function
+		// Use provided path
-    const taskId = args.id.includes && args.id.includes('.') ? args.id : parseInt(args.id, 10);
+		const tasksPath = tasksJsonPath;
-    const dependencyId = args.dependsOn.includes && args.dependsOn.includes('.') ? args.dependsOn : parseInt(args.dependsOn, 10);
 
-    log.info(`Removing dependency: task ${taskId} no longer depends on ${dependencyId}`);
+		// Format IDs for the core function
+		const taskId =
+			id && id.includes && id.includes('.') ? id : parseInt(id, 10);
+		const dependencyId =
+			dependsOn && dependsOn.includes && dependsOn.includes('.')
+				? dependsOn
+				: parseInt(dependsOn, 10);
 
-    // Enable silent mode to prevent console logs from interfering with JSON response
+		log.info(
-    enableSilentMode();
+			`Removing dependency: task ${taskId} no longer depends on ${dependencyId}`
+		);
 
-    // Call the core function
+		// Enable silent mode to prevent console logs from interfering with JSON response
-    await removeDependency(tasksPath, taskId, dependencyId);
+		enableSilentMode();
 
-    // Restore normal logging
+		// Call the core function using the provided tasksPath
-    disableSilentMode();
+		await removeDependency(tasksPath, taskId, dependencyId);
 
-    return {
+		// Restore normal logging
-      success: true,
+		disableSilentMode();
-      data: {
-        message: `Successfully removed dependency: Task ${taskId} no longer depends on ${dependencyId}`,
-        taskId: taskId,
-        dependencyId: dependencyId
-      }
-    };
-  } catch (error) {
-    // Make sure to restore normal logging even if there's an error
-    disableSilentMode();
 
-    log.error(`Error in removeDependencyDirect: ${error.message}`);
+		return {
-    return {
+			success: true,
-      success: false,
+			data: {
-      error: {
+				message: `Successfully removed dependency: Task ${taskId} no longer depends on ${dependencyId}`,
-        code: 'CORE_FUNCTION_ERROR',
+				taskId: taskId,
-        message: error.message
+				dependencyId: dependencyId
-      }
+			}
-    };
+		};
-  }
+	} catch (error) {
+		// Make sure to restore normal logging even if there's an error
+		disableSilentMode();
+
+		log.error(`Error in removeDependencyDirect: ${error.message}`);
+		return {
+			success: false,
+			error: {
+				code: 'CORE_FUNCTION_ERROR',
+				message: error.message
+			}
+		};
+	}
 }

mcp-server/src/core/direct-functions/remove-subtask.js

@@ -3,93 +3,120 @@
  */
 
 import { removeSubtask } from '../../../../scripts/modules/task-manager.js';
-import { findTasksJsonPath } from '../utils/path-utils.js';
+import {
-import { enableSilentMode, disableSilentMode } from '../../../../scripts/modules/utils.js';
+	enableSilentMode,
+	disableSilentMode
+} from '../../../../scripts/modules/utils.js';
 
 /**
  * Remove a subtask from its parent task
  * @param {Object} args - Function arguments
+ * @param {string} args.tasksJsonPath - Explicit path to the tasks.json file.
  * @param {string} args.id - Subtask ID in format "parentId.subtaskId" (required)
  * @param {boolean} [args.convert] - Whether to convert the subtask to a standalone task
- * @param {string} [args.file] - Path to the tasks file
  * @param {boolean} [args.skipGenerate] - Skip regenerating task files
- * @param {string} [args.projectRoot] - Project root directory
  * @param {Object} log - Logger object
  * @returns {Promise<{success: boolean, data?: Object, error?: {code: string, message: string}}>}
  */
 export async function removeSubtaskDirect(args, log) {
-  try {
+	// Destructure expected args
-    // Enable silent mode to prevent console logs from interfering with JSON response
+	const { tasksJsonPath, id, convert, skipGenerate } = args;
-    enableSilentMode();
+	try {
+		// Enable silent mode to prevent console logs from interfering with JSON response
+		enableSilentMode();
 
-    log.info(`Removing subtask with args: ${JSON.stringify(args)}`);
+		log.info(`Removing subtask with args: ${JSON.stringify(args)}`);
 
-    if (!args.id) {
+		// Check if tasksJsonPath was provided
-      return {
+		if (!tasksJsonPath) {
-        success: false,
+			log.error('removeSubtaskDirect called without tasksJsonPath');
-        error: {
+			disableSilentMode(); // Disable before returning
-          code: 'INPUT_VALIDATION_ERROR',
+			return {
-          message: 'Subtask ID is required and must be in format "parentId.subtaskId"'
+				success: false,
-        }
+				error: {
-      };
+					code: 'MISSING_ARGUMENT',
-    }
+					message: 'tasksJsonPath is required'
+				}
+			};
+		}
 
-    // Validate subtask ID format
+		if (!id) {
-    if (!args.id.includes('.')) {
+			disableSilentMode(); // Disable before returning
-      return {
+			return {
-        success: false,
+				success: false,
-        error: {
+				error: {
-          code: 'INPUT_VALIDATION_ERROR',
+					code: 'INPUT_VALIDATION_ERROR',
-          message: `Invalid subtask ID format: ${args.id}. Expected format: "parentId.subtaskId"`
+					message:
-        }
+						'Subtask ID is required and must be in format "parentId.subtaskId"'
-      };
+				}
-    }
+			};
+		}
 
-    // Find the tasks.json path
+		// Validate subtask ID format
-    const tasksPath = findTasksJsonPath(args, log);
+		if (!id.includes('.')) {
+			disableSilentMode(); // Disable before returning
+			return {
+				success: false,
+				error: {
+					code: 'INPUT_VALIDATION_ERROR',
+					message: `Invalid subtask ID format: ${id}. Expected format: "parentId.subtaskId"`
+				}
+			};
+		}
 
-    // Convert convertToTask to a boolean
+		// Use provided path
-    const convertToTask = args.convert === true;
+		const tasksPath = tasksJsonPath;
 
-    // Determine if we should generate files
+		// Convert convertToTask to a boolean
-    const generateFiles = !args.skipGenerate;
+		const convertToTask = convert === true;
 
-    log.info(`Removing subtask ${args.id} (convertToTask: ${convertToTask}, generateFiles: ${generateFiles})`);
+		// Determine if we should generate files
+		const generateFiles = !skipGenerate;
 
-    const result = await removeSubtask(tasksPath, args.id, convertToTask, generateFiles);
+		log.info(
+			`Removing subtask ${id} (convertToTask: ${convertToTask}, generateFiles: ${generateFiles})`
+		);
 
-    // Restore normal logging
+		// Use the provided tasksPath
-    disableSilentMode();
+		const result = await removeSubtask(
+			tasksPath,
+			id,
+			convertToTask,
+			generateFiles
+		);
 
-    if (convertToTask && result) {
+		// Restore normal logging
-      // Return info about the converted task
+		disableSilentMode();
-      return {
-        success: true,
-        data: {
-          message: `Subtask ${args.id} successfully converted to task #${result.id}`,
-          task: result
-        }
-      };
-    } else {
-      // Return simple success message for deletion
-      return {
-        success: true,
-        data: {
-          message: `Subtask ${args.id} successfully removed`
-        }
-      };
-    }
-  } catch (error) {
-    // Ensure silent mode is disabled even if an outer error occurs
-    disableSilentMode();
 
-    log.error(`Error in removeSubtaskDirect: ${error.message}`);
+		if (convertToTask && result) {
-    return {
+			// Return info about the converted task
-      success: false,
+			return {
-      error: {
+				success: true,
-        code: 'CORE_FUNCTION_ERROR',
+				data: {
-        message: error.message
+					message: `Subtask ${id} successfully converted to task #${result.id}`,
-      }
+					task: result
-    };
+				}
-  }
+			};
+		} else {
+			// Return simple success message for deletion
+			return {
+				success: true,
+				data: {
+					message: `Subtask ${id} successfully removed`
+				}
+			};
+		}
+	} catch (error) {
+		// Ensure silent mode is disabled even if an outer error occurs
+		disableSilentMode();
+
+		log.error(`Error in removeSubtaskDirect: ${error.message}`);
+		return {
+			success: false,
+			error: {
+				code: 'CORE_FUNCTION_ERROR',
+				message: error.message
+			}
+		};
+	}
 }

mcp-server/src/core/direct-functions/remove-task.js

@@ -4,101 +4,104 @@
  */
 
 import { removeTask } from '../../../../scripts/modules/task-manager.js';
-import { enableSilentMode, disableSilentMode } from '../../../../scripts/modules/utils.js';
+import {
-import { findTasksJsonPath } from '../utils/path-utils.js';
+	enableSilentMode,
+	disableSilentMode
+} from '../../../../scripts/modules/utils.js';
 
 /**
  * Direct function wrapper for removeTask with error handling.
  *
  * @param {Object} args - Command arguments
+ * @param {string} args.tasksJsonPath - Explicit path to the tasks.json file.
+ * @param {string} args.id - The ID of the task or subtask to remove.
  * @param {Object} log - Logger object
  * @returns {Promise<Object>} - Remove task result { success: boolean, data?: any, error?: { code: string, message: string }, fromCache: false }
  */
 export async function removeTaskDirect(args, log) {
-  try {
+	// Destructure expected args
-    // Find the tasks path first
+	const { tasksJsonPath, id } = args;
-    let tasksPath;
+	try {
-    try {
+		// Check if tasksJsonPath was provided
-      tasksPath = findTasksJsonPath(args, log);
+		if (!tasksJsonPath) {
-    } catch (error) {
+			log.error('removeTaskDirect called without tasksJsonPath');
-      log.error(`Tasks file not found: ${error.message}`);
+			return {
-      return { 
+				success: false,
-        success: false, 
+				error: {
-        error: { 
+					code: 'MISSING_ARGUMENT',
-          code: 'FILE_NOT_FOUND_ERROR', 
+					message: 'tasksJsonPath is required'
-          message: error.message 
+				},
-        }, 
+				fromCache: false
-        fromCache: false 
+			};
-      };
+		}
-    }
 
-    // Validate task ID parameter
+		// Validate task ID parameter
-    const taskId = args.id;
+		const taskId = id;
-    if (!taskId) {
+		if (!taskId) {
-      log.error('Task ID is required');
+			log.error('Task ID is required');
-      return { 
+			return {
-        success: false, 
+				success: false,
-        error: { 
+				error: {
-          code: 'INPUT_VALIDATION_ERROR', 
+					code: 'INPUT_VALIDATION_ERROR',
-          message: 'Task ID is required' 
+					message: 'Task ID is required'
-        }, 
+				},
-        fromCache: false 
+				fromCache: false
-      };
+			};
-    }
+		}
 
-    // Skip confirmation in the direct function since it's handled by the client
+		// Skip confirmation in the direct function since it's handled by the client
-    log.info(`Removing task with ID: ${taskId} from ${tasksPath}`);
+		log.info(`Removing task with ID: ${taskId} from ${tasksJsonPath}`);
 
-    try {
+		try {
-      // Enable silent mode to prevent console logs from interfering with JSON response
+			// Enable silent mode to prevent console logs from interfering with JSON response
-      enableSilentMode();
+			enableSilentMode();
 
-      // Call the core removeTask function
+			// Call the core removeTask function using the provided path
-      const result = await removeTask(tasksPath, taskId);
+			const result = await removeTask(tasksJsonPath, taskId);
 
-      // Restore normal logging
+			// Restore normal logging
-      disableSilentMode();
+			disableSilentMode();
 
-      log.info(`Successfully removed task: ${taskId}`);
+			log.info(`Successfully removed task: ${taskId}`);
 
-      // Return the result
+			// Return the result
-      return {
+			return {
-        success: true,
+				success: true,
-        data: {
+				data: {
-          message: result.message,
+					message: result.message,
-          taskId: taskId,
+					taskId: taskId,
-          tasksPath: tasksPath,
+					tasksPath: tasksJsonPath,
-          removedTask: result.removedTask
+					removedTask: result.removedTask
-        },
+				},
-        fromCache: false
+				fromCache: false
-      };
+			};
-    } catch (error) {
+		} catch (error) {
-      // Make sure to restore normal logging even if there's an error
+			// Make sure to restore normal logging even if there's an error
-      disableSilentMode();
+			disableSilentMode();
 
-      log.error(`Error removing task: ${error.message}`);
+			log.error(`Error removing task: ${error.message}`);
-      return { 
+			return {
-        success: false, 
+				success: false,
-        error: { 
+				error: {
-          code: error.code || 'REMOVE_TASK_ERROR', 
+					code: error.code || 'REMOVE_TASK_ERROR',
-          message: error.message || 'Failed to remove task' 
+					message: error.message || 'Failed to remove task'
-        }, 
+				},
-        fromCache: false 
+				fromCache: false
-      };
+			};
-    }
+		}
-  } catch (error) {
+	} catch (error) {
-    // Ensure silent mode is disabled even if an outer error occurs
+		// Ensure silent mode is disabled even if an outer error occurs
-    disableSilentMode();
+		disableSilentMode();
 
-    // Catch any unexpected errors
+		// Catch any unexpected errors
-    log.error(`Unexpected error in removeTaskDirect: ${error.message}`);
+		log.error(`Unexpected error in removeTaskDirect: ${error.message}`);
-    return { 
+		return {
-      success: false, 
+			success: false,
-      error: { 
+			error: {
-        code: 'UNEXPECTED_ERROR', 
+				code: 'UNEXPECTED_ERROR',
-        message: error.message 
+				message: error.message
-      }, 
+			},
-      fromCache: false 
+			fromCache: false
-    };
+		};
-  }
+	}
 }

mcp-server/src/core/direct-functions/set-task-status.js

@@ -4,106 +4,116 @@
  */
 
 import { setTaskStatus } from '../../../../scripts/modules/task-manager.js';
-import { findTasksJsonPath } from '../utils/path-utils.js';
+import {
-import { enableSilentMode, disableSilentMode } from '../../../../scripts/modules/utils.js';
+	enableSilentMode,
+	disableSilentMode,
+	isSilentMode
+} from '../../../../scripts/modules/utils.js';
 
 /**
  * Direct function wrapper for setTaskStatus with error handling.
  *
- * @param {Object} args - Command arguments containing id, status and file path options.
+ * @param {Object} args - Command arguments containing id, status and tasksJsonPath.
  * @param {Object} log - Logger object.
  * @returns {Promise<Object>} - Result object with success status and data/error information.
  */
 export async function setTaskStatusDirect(args, log) {
-  try {
+	// Destructure expected args, including the resolved tasksJsonPath
-    log.info(`Setting task status with args: ${JSON.stringify(args)}`);
+	const { tasksJsonPath, id, status } = args;
+	try {
+		log.info(`Setting task status with args: ${JSON.stringify(args)}`);
 
-    // Check required parameters
+		// Check if tasksJsonPath was provided
-    if (!args.id) {
+		if (!tasksJsonPath) {
-      const errorMessage = 'No task ID specified. Please provide a task ID to update.';
+			const errorMessage = 'tasksJsonPath is required but was not provided.';
-      log.error(errorMessage);
+			log.error(errorMessage);
-      return { 
+			return {
-        success: false, 
+				success: false,
-        error: { code: 'MISSING_TASK_ID', message: errorMessage },
+				error: { code: 'MISSING_ARGUMENT', message: errorMessage },
-        fromCache: false 
+				fromCache: false
-      };
+			};
-    }
+		}
 
-    if (!args.status) {
+		// Check required parameters (id and status)
-      const errorMessage = 'No status specified. Please provide a new status value.';
+		if (!id) {
-      log.error(errorMessage);
+			const errorMessage =
-      return { 
+				'No task ID specified. Please provide a task ID to update.';
-        success: false, 
+			log.error(errorMessage);
-        error: { code: 'MISSING_STATUS', message: errorMessage },
+			return {
-        fromCache: false 
+				success: false,
-      };
+				error: { code: 'MISSING_TASK_ID', message: errorMessage },
-    }
+				fromCache: false
+			};
+		}
 
-    // Get tasks file path
+		if (!status) {
-    let tasksPath;
+			const errorMessage =
-    try {
+				'No status specified. Please provide a new status value.';
-      // The enhanced findTasksJsonPath will now search in parent directories if needed
+			log.error(errorMessage);
-      tasksPath = findTasksJsonPath(args, log);
+			return {
-      log.info(`Found tasks file at: ${tasksPath}`);
+				success: false,
-    } catch (error) {
+				error: { code: 'MISSING_STATUS', message: errorMessage },
-      log.error(`Error finding tasks file: ${error.message}`);
+				fromCache: false
-      return { 
+			};
-        success: false, 
+		}
-        error: { 
-          code: 'TASKS_FILE_ERROR', 
-          message: `${error.message}\n\nPlease ensure you are in a Task Master project directory or use the --project-root parameter to specify the path to your project.`
-        },
-        fromCache: false 
-      };
-    }
 
-    // Execute core setTaskStatus function
+		// Use the provided path
-    // We need to handle the arguments correctly - this function expects tasksPath, taskIdInput, newStatus
+		const tasksPath = tasksJsonPath;
-    const taskId = args.id;
-    const newStatus = args.status;
 
-    log.info(`Setting task ${taskId} status to "${newStatus}"`);
+		// Execute core setTaskStatus function
+		const taskId = id;
+		const newStatus = status;
 
-    // Call the core function
+		log.info(`Setting task ${taskId} status to "${newStatus}"`);
-    try {
-      // Enable silent mode to prevent console logs from interfering with JSON response
-      enableSilentMode();
 
-      await setTaskStatus(tasksPath, taskId, newStatus);
+		// Call the core function with proper silent mode handling
+		enableSilentMode(); // Enable silent mode before calling core function
+		try {
+			// Call the core function
+			await setTaskStatus(tasksPath, taskId, newStatus, { mcpLog: log });
 
-      // Restore normal logging
+			log.info(`Successfully set task ${taskId} status to ${newStatus}`);
-      disableSilentMode();
 
-      log.info(`Successfully set task ${taskId} status to ${newStatus}`);
+			// Return success data
+			const result = {
+				success: true,
+				data: {
+					message: `Successfully updated task ${taskId} status to "${newStatus}"`,
+					taskId,
+					status: newStatus,
+					tasksPath: tasksPath // Return the path used
+				},
+				fromCache: false // This operation always modifies state and should never be cached
+			};
+			return result;
+		} catch (error) {
+			log.error(`Error setting task status: ${error.message}`);
+			return {
+				success: false,
+				error: {
+					code: 'SET_STATUS_ERROR',
+					message: error.message || 'Unknown error setting task status'
+				},
+				fromCache: false
+			};
+		} finally {
+			// ALWAYS restore normal logging in finally block
+			disableSilentMode();
+		}
+	} catch (error) {
+		// Ensure silent mode is disabled if there was an uncaught error in the outer try block
+		if (isSilentMode()) {
+			disableSilentMode();
+		}
 
-      // Return success data
+		log.error(`Error setting task status: ${error.message}`);
-      return {
+		return {
-        success: true,
+			success: false,
-        data: {
+			error: {
-          message: `Successfully updated task ${taskId} status to "${newStatus}"`,
+				code: 'SET_STATUS_ERROR',
-          taskId,
+				message: error.message || 'Unknown error setting task status'
-          status: newStatus,
+			},
-          tasksPath
+			fromCache: false
-        },
+		};
-        fromCache: false // This operation always modifies state and should never be cached
+	}
-      };
-    } catch (error) {
-      // Make sure to restore normal logging even if there's an error
-      disableSilentMode();
-      
-      log.error(`Error setting task status: ${error.message}`);
-      return { 
-        success: false, 
-        error: { code: 'SET_STATUS_ERROR', message: error.message || 'Unknown error setting task status' },
-        fromCache: false 
-      };
-    }
-  } catch (error) {
-    log.error(`Error setting task status: ${error.message}`);
-    return { 
-      success: false, 
-      error: { code: 'SET_STATUS_ERROR', message: error.message || 'Unknown error setting task status' },
-      fromCache: false 
-    };
-  }
 }

mcp-server/src/core/direct-functions/show-task.js

@@ -6,131 +6,140 @@
 import { findTaskById } from '../../../../scripts/modules/utils.js';
 import { readJSON } from '../../../../scripts/modules/utils.js';
 import { getCachedOrExecute } from '../../tools/utils.js';
-import { findTasksJsonPath } from '../utils/path-utils.js';
+import {
-import { enableSilentMode, disableSilentMode } from '../../../../scripts/modules/utils.js';
+	enableSilentMode,
+	disableSilentMode
+} from '../../../../scripts/modules/utils.js';
 
 /**
  * Direct function wrapper for showing task details with error handling and caching.
  *
  * @param {Object} args - Command arguments
+ * @param {string} args.tasksJsonPath - Explicit path to the tasks.json file.
+ * @param {string} args.id - The ID of the task or subtask to show.
  * @param {Object} log - Logger object
  * @returns {Promise<Object>} - Task details result { success: boolean, data?: any, error?: { code: string, message: string }, fromCache: boolean }
  */
 export async function showTaskDirect(args, log) {
-  let tasksPath;
+	// Destructure expected args
-  try {
+	const { tasksJsonPath, id } = args;
-    // Find the tasks path first - needed for cache key and execution
-    tasksPath = findTasksJsonPath(args, log);
-  } catch (error) {
-    log.error(`Tasks file not found: ${error.message}`);
-    return { 
-      success: false, 
-      error: { 
-        code: 'FILE_NOT_FOUND_ERROR', 
-        message: error.message 
-      }, 
-      fromCache: false 
-    };
-  }
 
-  // Validate task ID
+	if (!tasksJsonPath) {
-  const taskId = args.id;
+		log.error('showTaskDirect called without tasksJsonPath');
-  if (!taskId) {
+		return {
-    log.error('Task ID is required');
+			success: false,
-    return { 
+			error: {
-      success: false, 
+				code: 'MISSING_ARGUMENT',
-      error: { 
+				message: 'tasksJsonPath is required'
-        code: 'INPUT_VALIDATION_ERROR', 
+			},
-        message: 'Task ID is required' 
+			fromCache: false
-      }, 
+		};
-      fromCache: false 
+	}
-    };
-  }
 
-  // Generate cache key using task path and ID
+	// Validate task ID
-  const cacheKey = `showTask:${tasksPath}:${taskId}`;
+	const taskId = id;
+	if (!taskId) {
+		log.error('Task ID is required');
+		return {
+			success: false,
+			error: {
+				code: 'INPUT_VALIDATION_ERROR',
+				message: 'Task ID is required'
+			},
+			fromCache: false
+		};
+	}
 
-  // Define the action function to be executed on cache miss
+	// Generate cache key using the provided task path and ID
-  const coreShowTaskAction = async () => {
+	const cacheKey = `showTask:${tasksJsonPath}:${taskId}`;
-    try {
-      // Enable silent mode to prevent console logs from interfering with JSON response
-      enableSilentMode();
 
-      log.info(`Retrieving task details for ID: ${taskId} from ${tasksPath}`);
+	// Define the action function to be executed on cache miss
+	const coreShowTaskAction = async () => {
+		try {
+			// Enable silent mode to prevent console logs from interfering with JSON response
+			enableSilentMode();
 
-      // Read tasks data
+			log.info(
-      const data = readJSON(tasksPath);
+				`Retrieving task details for ID: ${taskId} from ${tasksJsonPath}`
-      if (!data || !data.tasks) {
+			);
-        return { 
-          success: false, 
-          error: { 
-            code: 'INVALID_TASKS_FILE', 
-            message: `No valid tasks found in ${tasksPath}` 
-          } 
-        };
-      }
 
-      // Find the specific task
+			// Read tasks data using the provided path
-      const task = findTaskById(data.tasks, taskId);
+			const data = readJSON(tasksJsonPath);
+			if (!data || !data.tasks) {
+				disableSilentMode(); // Disable before returning
+				return {
+					success: false,
+					error: {
+						code: 'INVALID_TASKS_FILE',
+						message: `No valid tasks found in ${tasksJsonPath}`
+					}
+				};
+			}
 
-      if (!task) {
+			// Find the specific task
-        return { 
+			const task = findTaskById(data.tasks, taskId);
-          success: false, 
-          error: { 
-            code: 'TASK_NOT_FOUND', 
-            message: `Task with ID ${taskId} not found` 
-          } 
-        };
-      }
 
-      // Restore normal logging
+			if (!task) {
-      disableSilentMode();
+				disableSilentMode(); // Disable before returning
+				return {
+					success: false,
+					error: {
+						code: 'TASK_NOT_FOUND',
+						message: `Task with ID ${taskId} not found`
+					}
+				};
+			}
 
-      // Return the task data with the full tasks array for reference
+			// Restore normal logging
-      // (needed for formatDependenciesWithStatus function in UI)
+			disableSilentMode();
-      log.info(`Successfully found task ${taskId}`);
-      return { 
-        success: true, 
-        data: { 
-          task, 
-          allTasks: data.tasks 
-        } 
-      };
-    } catch (error) {
-      // Make sure to restore normal logging even if there's an error
-      disableSilentMode();
 
-      log.error(`Error showing task: ${error.message}`);
+			// Return the task data with the full tasks array for reference
-      return { 
+			// (needed for formatDependenciesWithStatus function in UI)
-        success: false, 
+			log.info(`Successfully found task ${taskId}`);
-        error: { 
+			return {
-          code: 'CORE_FUNCTION_ERROR', 
+				success: true,
-          message: error.message || 'Failed to show task details' 
+				data: {
-        } 
+					task,
-      };
+					allTasks: data.tasks
-    }
+				}
-  };
+			};
+		} catch (error) {
+			// Make sure to restore normal logging even if there's an error
+			disableSilentMode();
 
-  // Use the caching utility
+			log.error(`Error showing task: ${error.message}`);
-  try {
+			return {
-    const result = await getCachedOrExecute({
+				success: false,
-      cacheKey,
+				error: {
-      actionFn: coreShowTaskAction,
+					code: 'CORE_FUNCTION_ERROR',
-      log
+					message: error.message || 'Failed to show task details'
-    });
+				}
-    log.info(`showTaskDirect completed. From cache: ${result.fromCache}`);
+			};
-    return result; // Returns { success, data/error, fromCache }
+		}
-  } catch (error) {
+	};
-    // Catch unexpected errors from getCachedOrExecute itself
+
-    disableSilentMode();
+	// Use the caching utility
-    log.error(`Unexpected error during getCachedOrExecute for showTask: ${error.message}`);
+	try {
-    return { 
+		const result = await getCachedOrExecute({
-      success: false, 
+			cacheKey,
-      error: { 
+			actionFn: coreShowTaskAction,
-        code: 'UNEXPECTED_ERROR', 
+			log
-        message: error.message 
+		});
-      }, 
+		log.info(`showTaskDirect completed. From cache: ${result.fromCache}`);
-      fromCache: false 
+		return result; // Returns { success, data/error, fromCache }
-    };
+	} catch (error) {
-  }
+		// Catch unexpected errors from getCachedOrExecute itself
+		disableSilentMode();
+		log.error(
+			`Unexpected error during getCachedOrExecute for showTask: ${error.message}`
+		);
+		return {
+			success: false,
+			error: {
+				code: 'UNEXPECTED_ERROR',
+				message: error.message
+			},
+			fromCache: false
+		};
+	}
 }

mcp-server/src/core/direct-functions/update-subtask-by-id.js

@@ -4,120 +4,191 @@
  */
 
 import { updateSubtaskById } from '../../../../scripts/modules/task-manager.js';
-import { enableSilentMode, disableSilentMode } from '../../../../scripts/modules/utils.js';
+import {
-import { findTasksJsonPath } from '../utils/path-utils.js';
+	enableSilentMode,
+	disableSilentMode
+} from '../../../../scripts/modules/utils.js';
+import {
+	getAnthropicClientForMCP,
+	getPerplexityClientForMCP
+} from '../utils/ai-client-utils.js';
 
 /**
  * Direct function wrapper for updateSubtaskById with error handling.
  *
- * @param {Object} args - Command arguments containing id, prompt, useResearch and file path options.
+ * @param {Object} args - Command arguments containing id, prompt, useResearch and tasksJsonPath.
  * @param {Object} log - Logger object.
+ * @param {Object} context - Context object containing session data.
  * @returns {Promise<Object>} - Result object with success status and data/error information.
  */
-export async function updateSubtaskByIdDirect(args, log) {
+export async function updateSubtaskByIdDirect(args, log, context = {}) {
-  try {
+	const { session } = context; // Only extract session, not reportProgress
-    log.info(`Updating subtask with args: ${JSON.stringify(args)}`);
+	const { tasksJsonPath, id, prompt, research } = args;
 
-    // Check required parameters
+	try {
-    if (!args.id) {
+		log.info(`Updating subtask with args: ${JSON.stringify(args)}`);
-      const errorMessage = 'No subtask ID specified. Please provide a subtask ID to update.';
-      log.error(errorMessage);
-      return { 
-        success: false, 
-        error: { code: 'MISSING_SUBTASK_ID', message: errorMessage },
-        fromCache: false 
-      };
-    }
 
-    if (!args.prompt) {
+		// Check if tasksJsonPath was provided
-      const errorMessage = 'No prompt specified. Please provide a prompt with information to add to the subtask.';
+		if (!tasksJsonPath) {
-      log.error(errorMessage);
+			const errorMessage = 'tasksJsonPath is required but was not provided.';
-      return { 
+			log.error(errorMessage);
-        success: false, 
+			return {
-        error: { code: 'MISSING_PROMPT', message: errorMessage },
+				success: false,
-        fromCache: false 
+				error: { code: 'MISSING_ARGUMENT', message: errorMessage },
-      };
+				fromCache: false
-    }
+			};
+		}
 
-    // Validate subtask ID format
+		// Check required parameters (id and prompt)
-    const subtaskId = args.id;
+		if (!id) {
-    if (typeof subtaskId !== 'string' || !subtaskId.includes('.')) {
+			const errorMessage =
-      const errorMessage = `Invalid subtask ID format: ${subtaskId}. Subtask ID must be in format "parentId.subtaskId" (e.g., "5.2").`;
+				'No subtask ID specified. Please provide a subtask ID to update.';
-      log.error(errorMessage);
+			log.error(errorMessage);
-      return { 
+			return {
-        success: false, 
+				success: false,
-        error: { code: 'INVALID_SUBTASK_ID_FORMAT', message: errorMessage },
+				error: { code: 'MISSING_SUBTASK_ID', message: errorMessage },
-        fromCache: false 
+				fromCache: false
-      };
+			};
-    }
+		}
 
-    // Get tasks file path
+		if (!prompt) {
-    let tasksPath;
+			const errorMessage =
-    try {
+				'No prompt specified. Please provide a prompt with information to add to the subtask.';
-      tasksPath = findTasksJsonPath(args, log);
+			log.error(errorMessage);
-    } catch (error) {
+			return {
-      log.error(`Error finding tasks file: ${error.message}`);
+				success: false,
-      return { 
+				error: { code: 'MISSING_PROMPT', message: errorMessage },
-        success: false, 
+				fromCache: false
-        error: { code: 'TASKS_FILE_ERROR', message: error.message },
+			};
-        fromCache: false 
+		}
-      };
-    }
 
-    // Get research flag
+		// Validate subtask ID format
-    const useResearch = args.research === true;
+		const subtaskId = id;
+		if (typeof subtaskId !== 'string' && typeof subtaskId !== 'number') {
+			const errorMessage = `Invalid subtask ID type: ${typeof subtaskId}. Subtask ID must be a string or number.`;
+			log.error(errorMessage);
+			return {
+				success: false,
+				error: { code: 'INVALID_SUBTASK_ID_TYPE', message: errorMessage },
+				fromCache: false
+			};
+		}
 
-    log.info(`Updating subtask with ID ${subtaskId} with prompt "${args.prompt}" and research: ${useResearch}`);
+		const subtaskIdStr = String(subtaskId);
+		if (!subtaskIdStr.includes('.')) {
+			const errorMessage = `Invalid subtask ID format: ${subtaskIdStr}. Subtask ID must be in format "parentId.subtaskId" (e.g., "5.2").`;
+			log.error(errorMessage);
+			return {
+				success: false,
+				error: { code: 'INVALID_SUBTASK_ID_FORMAT', message: errorMessage },
+				fromCache: false
+			};
+		}
 
-    try {
+		// Use the provided path
-      // Enable silent mode to prevent console logs from interfering with JSON response
+		const tasksPath = tasksJsonPath;
-      enableSilentMode();
 
-      // Execute core updateSubtaskById function
+		// Get research flag
-      const updatedSubtask = await updateSubtaskById(tasksPath, subtaskId, args.prompt, useResearch);
+		const useResearch = research === true;
 
-      // Restore normal logging
+		log.info(
-      disableSilentMode();
+			`Updating subtask with ID ${subtaskIdStr} with prompt "${prompt}" and research: ${useResearch}`
+		);
 
-      // Handle the case where the subtask couldn't be updated (e.g., already marked as done)
+		// Initialize the appropriate AI client based on research flag
-      if (!updatedSubtask) {
+		try {
-        return {
+			if (useResearch) {
-          success: false,
+				// Initialize Perplexity client
-          error: { 
+				await getPerplexityClientForMCP(session);
-            code: 'SUBTASK_UPDATE_FAILED', 
+			} else {
-            message: 'Failed to update subtask. It may be marked as completed, or another error occurred.' 
+				// Initialize Anthropic client
-          },
+				await getAnthropicClientForMCP(session);
-          fromCache: false
+			}
-        };
+		} catch (error) {
-      }
+			log.error(`AI client initialization error: ${error.message}`);
+			return {
+				success: false,
+				error: {
+					code: 'AI_CLIENT_ERROR',
+					message: error.message || 'Failed to initialize AI client'
+				},
+				fromCache: false
+			};
+		}
 
-      // Return the updated subtask information
+		try {
-      return {
+			// Enable silent mode to prevent console logs from interfering with JSON response
-        success: true,
+			enableSilentMode();
-        data: {
-          message: `Successfully updated subtask with ID ${subtaskId}`,
-          subtaskId,
-          parentId: subtaskId.split('.')[0],
-          subtask: updatedSubtask,
-          tasksPath,
-          useResearch
-        },
-        fromCache: false // This operation always modifies state and should never be cached
-      };
-    } catch (error) {
-      // Make sure to restore normal logging even if there's an error
-      disableSilentMode();
-      throw error; // Rethrow to be caught by outer catch block
-    }
-  } catch (error) {
-    // Ensure silent mode is disabled
-    disableSilentMode();
 
-    log.error(`Error updating subtask by ID: ${error.message}`);
+			// Create a logger wrapper object to handle logging without breaking the mcpLog[level] calls
-    return { 
+			// This ensures outputFormat is set to 'json' while still supporting proper logging
-      success: false, 
+			const logWrapper = {
-      error: { code: 'UPDATE_SUBTASK_ERROR', message: error.message || 'Unknown error updating subtask' },
+				info: (message) => log.info(message),
-      fromCache: false 
+				warn: (message) => log.warn(message),
-    };
+				error: (message) => log.error(message),
-  }
+				debug: (message) => log.debug && log.debug(message),
+				success: (message) => log.info(message) // Map success to info if needed
+			};
+
+			// Execute core updateSubtaskById function
+			// Pass both session and logWrapper as mcpLog to ensure outputFormat is 'json'
+			const updatedSubtask = await updateSubtaskById(
+				tasksPath,
+				subtaskIdStr,
+				prompt,
+				useResearch,
+				{
+					session,
+					mcpLog: logWrapper
+				}
+			);
+
+			// Restore normal logging
+			disableSilentMode();
+
+			// Handle the case where the subtask couldn't be updated (e.g., already marked as done)
+			if (!updatedSubtask) {
+				return {
+					success: false,
+					error: {
+						code: 'SUBTASK_UPDATE_FAILED',
+						message:
+							'Failed to update subtask. It may be marked as completed, or another error occurred.'
+					},
+					fromCache: false
+				};
+			}
+
+			// Return the updated subtask information
+			return {
+				success: true,
+				data: {
+					message: `Successfully updated subtask with ID ${subtaskIdStr}`,
+					subtaskId: subtaskIdStr,
+					parentId: subtaskIdStr.split('.')[0],
+					subtask: updatedSubtask,
+					tasksPath,
+					useResearch
+				},
+				fromCache: false // This operation always modifies state and should never be cached
+			};
+		} catch (error) {
+			// Make sure to restore normal logging even if there's an error
+			disableSilentMode();
+			throw error; // Rethrow to be caught by outer catch block
+		}
+	} catch (error) {
+		// Ensure silent mode is disabled
+		disableSilentMode();
+
+		log.error(`Error updating subtask by ID: ${error.message}`);
+		return {
+			success: false,
+			error: {
+				code: 'UPDATE_SUBTASK_ERROR',
+				message: error.message || 'Unknown error updating subtask'
+			},
+			fromCache: false
+		};
+	}
 }

mcp-server/src/core/direct-functions/update-task-by-id.js

@@ -4,112 +4,184 @@
  */
 
 import { updateTaskById } from '../../../../scripts/modules/task-manager.js';
-import { findTasksJsonPath } from '../utils/path-utils.js';
+import {
-import { enableSilentMode, disableSilentMode } from '../../../../scripts/modules/utils.js';
+	enableSilentMode,
+	disableSilentMode
+} from '../../../../scripts/modules/utils.js';
+import {
+	getAnthropicClientForMCP,
+	getPerplexityClientForMCP
+} from '../utils/ai-client-utils.js';
 
 /**
  * Direct function wrapper for updateTaskById with error handling.
  *
- * @param {Object} args - Command arguments containing id, prompt, useResearch and file path options.
+ * @param {Object} args - Command arguments containing id, prompt, useResearch and tasksJsonPath.
  * @param {Object} log - Logger object.
+ * @param {Object} context - Context object containing session data.
  * @returns {Promise<Object>} - Result object with success status and data/error information.
  */
-export async function updateTaskByIdDirect(args, log) {
+export async function updateTaskByIdDirect(args, log, context = {}) {
-  try {
+	const { session } = context; // Only extract session, not reportProgress
-    log.info(`Updating task with args: ${JSON.stringify(args)}`);
+	// Destructure expected args, including the resolved tasksJsonPath
+	const { tasksJsonPath, id, prompt, research } = args;
 
-    // Check required parameters
+	try {
-    if (!args.id) {
+		log.info(`Updating task with args: ${JSON.stringify(args)}`);
-      const errorMessage = 'No task ID specified. Please provide a task ID to update.';
-      log.error(errorMessage);
-      return { 
-        success: false, 
-        error: { code: 'MISSING_TASK_ID', message: errorMessage },
-        fromCache: false 
-      };
-    }
 
-    if (!args.prompt) {
+		// Check if tasksJsonPath was provided
-      const errorMessage = 'No prompt specified. Please provide a prompt with new information for the task update.';
+		if (!tasksJsonPath) {
-      log.error(errorMessage);
+			const errorMessage = 'tasksJsonPath is required but was not provided.';
-      return { 
+			log.error(errorMessage);
-        success: false, 
+			return {
-        error: { code: 'MISSING_PROMPT', message: errorMessage },
+				success: false,
-        fromCache: false 
+				error: { code: 'MISSING_ARGUMENT', message: errorMessage },
-      };
+				fromCache: false
-    }
+			};
+		}
 
-    // Parse taskId - handle both string and number values
+		// Check required parameters (id and prompt)
-    let taskId;
+		if (!id) {
-    if (typeof args.id === 'string') {
+			const errorMessage =
-      // Handle subtask IDs (e.g., "5.2")
+				'No task ID specified. Please provide a task ID to update.';
-      if (args.id.includes('.')) {
+			log.error(errorMessage);
-        taskId = args.id; // Keep as string for subtask IDs
+			return {
-      } else {
+				success: false,
-        // Parse as integer for main task IDs
+				error: { code: 'MISSING_TASK_ID', message: errorMessage },
-        taskId = parseInt(args.id, 10);
+				fromCache: false
-        if (isNaN(taskId)) {
+			};
-          const errorMessage = `Invalid task ID: ${args.id}. Task ID must be a positive integer or subtask ID (e.g., "5.2").`;
+		}
-          log.error(errorMessage);
-          return { 
-            success: false, 
-            error: { code: 'INVALID_TASK_ID', message: errorMessage },
-            fromCache: false 
-          };
-        }
-      }
-    } else {
-      taskId = args.id;
-    }
 
-    // Get tasks file path
+		if (!prompt) {
-    let tasksPath;
+			const errorMessage =
-    try {
+				'No prompt specified. Please provide a prompt with new information for the task update.';
-      tasksPath = findTasksJsonPath(args, log);
+			log.error(errorMessage);
-    } catch (error) {
+			return {
-      log.error(`Error finding tasks file: ${error.message}`);
+				success: false,
-      return { 
+				error: { code: 'MISSING_PROMPT', message: errorMessage },
-        success: false, 
+				fromCache: false
-        error: { code: 'TASKS_FILE_ERROR', message: error.message },
+			};
-        fromCache: false 
+		}
-      };
-    }
 
-    // Get research flag
+		// Parse taskId - handle both string and number values
-    const useResearch = args.research === true;
+		let taskId;
+		if (typeof id === 'string') {
+			// Handle subtask IDs (e.g., "5.2")
+			if (id.includes('.')) {
+				taskId = id; // Keep as string for subtask IDs
+			} else {
+				// Parse as integer for main task IDs
+				taskId = parseInt(id, 10);
+				if (isNaN(taskId)) {
+					const errorMessage = `Invalid task ID: ${id}. Task ID must be a positive integer or subtask ID (e.g., "5.2").`;
+					log.error(errorMessage);
+					return {
+						success: false,
+						error: { code: 'INVALID_TASK_ID', message: errorMessage },
+						fromCache: false
+					};
+				}
+			}
+		} else {
+			taskId = id;
+		}
 
-    log.info(`Updating task with ID ${taskId} with prompt "${args.prompt}" and research: ${useResearch}`);
+		// Use the provided path
+		const tasksPath = tasksJsonPath;
 
-    // Enable silent mode to prevent console logs from interfering with JSON response
+		// Get research flag
-    enableSilentMode();
+		const useResearch = research === true;
 
-    // Execute core updateTaskById function
+		// Initialize appropriate AI client based on research flag
-    await updateTaskById(tasksPath, taskId, args.prompt, useResearch);
+		let aiClient;
+		try {
+			if (useResearch) {
+				log.info('Using Perplexity AI for research-backed task update');
+				aiClient = await getPerplexityClientForMCP(session, log);
+			} else {
+				log.info('Using Claude AI for task update');
+				aiClient = getAnthropicClientForMCP(session, log);
+			}
+		} catch (error) {
+			log.error(`Failed to initialize AI client: ${error.message}`);
+			return {
+				success: false,
+				error: {
+					code: 'AI_CLIENT_ERROR',
+					message: `Cannot initialize AI client: ${error.message}`
+				},
+				fromCache: false
+			};
+		}
 
-    // Restore normal logging
+		log.info(
-    disableSilentMode();
+			`Updating task with ID ${taskId} with prompt "${prompt}" and research: ${useResearch}`
+		);
 
-    // Since updateTaskById doesn't return a value but modifies the tasks file,
+		try {
-    // we'll return a success message
+			// Enable silent mode to prevent console logs from interfering with JSON response
-    return {
+			enableSilentMode();
-      success: true,
-      data: {
-        message: `Successfully updated task with ID ${taskId} based on the prompt`,
-        taskId,
-        tasksPath,
-        useResearch
-      },
-      fromCache: false // This operation always modifies state and should never be cached
-    };
-  } catch (error) {
-    // Make sure to restore normal logging even if there's an error
-    disableSilentMode();
 
-    log.error(`Error updating task by ID: ${error.message}`);
+			// Create a logger wrapper that matches what updateTaskById expects
-    return { 
+			const logWrapper = {
-      success: false, 
+				info: (message) => log.info(message),
-      error: { code: 'UPDATE_TASK_ERROR', message: error.message || 'Unknown error updating task' },
+				warn: (message) => log.warn(message),
-      fromCache: false 
+				error: (message) => log.error(message),
-    };
+				debug: (message) => log.debug && log.debug(message),
-  }
+				success: (message) => log.info(message) // Map success to info since many loggers don't have success
+			};
+
+			// Execute core updateTaskById function with proper parameters
+			await updateTaskById(
+				tasksPath,
+				taskId,
+				prompt,
+				useResearch,
+				{
+					mcpLog: logWrapper, // Use our wrapper object that has the expected method structure
+					session
+				},
+				'json'
+			);
+
+			// Since updateTaskById doesn't return a value but modifies the tasks file,
+			// we'll return a success message
+			return {
+				success: true,
+				data: {
+					message: `Successfully updated task with ID ${taskId} based on the prompt`,
+					taskId,
+					tasksPath: tasksPath, // Return the used path
+					useResearch
+				},
+				fromCache: false // This operation always modifies state and should never be cached
+			};
+		} catch (error) {
+			log.error(`Error updating task by ID: ${error.message}`);
+			return {
+				success: false,
+				error: {
+					code: 'UPDATE_TASK_ERROR',
+					message: error.message || 'Unknown error updating task'
+				},
+				fromCache: false
+			};
+		} finally {
+			// Make sure to restore normal logging even if there's an error
+			disableSilentMode();
+		}
+	} catch (error) {
+		// Ensure silent mode is disabled
+		disableSilentMode();
+
+		log.error(`Error updating task by ID: ${error.message}`);
+		return {
+			success: false,
+			error: {
+				code: 'UPDATE_TASK_ERROR',
+				message: error.message || 'Unknown error updating task'
+			},
+			fromCache: false
+		};
+	}
 }

mcp-server/src/core/direct-functions/update-tasks.js

@@ -4,112 +4,184 @@
  */
 
 import { updateTasks } from '../../../../scripts/modules/task-manager.js';
-import { enableSilentMode, disableSilentMode } from '../../../../scripts/modules/utils.js';
+import {
-import { findTasksJsonPath } from '../utils/path-utils.js';
+	enableSilentMode,
+	disableSilentMode
+} from '../../../../scripts/modules/utils.js';
+import {
+	getAnthropicClientForMCP,
+	getPerplexityClientForMCP
+} from '../utils/ai-client-utils.js';
 
 /**
  * Direct function wrapper for updating tasks based on new context/prompt.
  *
- * @param {Object} args - Command arguments containing fromId, prompt, useResearch and file path options.
+ * @param {Object} args - Command arguments containing fromId, prompt, useResearch and tasksJsonPath.
  * @param {Object} log - Logger object.
+ * @param {Object} context - Context object containing session data.
  * @returns {Promise<Object>} - Result object with success status and data/error information.
  */
-export async function updateTasksDirect(args, log) {
+export async function updateTasksDirect(args, log, context = {}) {
-  try {
+	const { session } = context; // Only extract session, not reportProgress
-    log.info(`Updating tasks with args: ${JSON.stringify(args)}`);
+	const { tasksJsonPath, from, prompt, research } = args;
 
-    // Check required parameters
+	try {
-    if (!args.from) {
+		log.info(`Updating tasks with args: ${JSON.stringify(args)}`);
-      const errorMessage = 'No from ID specified. Please provide a task ID to start updating from.';
-      log.error(errorMessage);
-      return { 
-        success: false, 
-        error: { code: 'MISSING_FROM_ID', message: errorMessage },
-        fromCache: false 
-      };
-    }
 
-    if (!args.prompt) {
+		// Check if tasksJsonPath was provided
-      const errorMessage = 'No prompt specified. Please provide a prompt with new context for task updates.';
+		if (!tasksJsonPath) {
-      log.error(errorMessage);
+			const errorMessage = 'tasksJsonPath is required but was not provided.';
-      return { 
+			log.error(errorMessage);
-        success: false, 
+			return {
-        error: { code: 'MISSING_PROMPT', message: errorMessage },
+				success: false,
-        fromCache: false 
+				error: { code: 'MISSING_ARGUMENT', message: errorMessage },
-      };
+				fromCache: false
-    }
+			};
+		}
 
-    // Parse fromId - handle both string and number values
+		// Check for the common mistake of using 'id' instead of 'from'
-    let fromId;
+		if (args.id !== undefined && from === undefined) {
-    if (typeof args.from === 'string') {
+			const errorMessage =
-      fromId = parseInt(args.from, 10);
+				"You specified 'id' parameter but 'update' requires 'from' parameter. Use 'from' for this tool or use 'update_task' tool if you want to update a single task.";
-      if (isNaN(fromId)) {
+			log.error(errorMessage);
-        const errorMessage = `Invalid from ID: ${args.from}. Task ID must be a positive integer.`;
+			return {
-        log.error(errorMessage);
+				success: false,
-        return { 
+				error: {
-          success: false, 
+					code: 'PARAMETER_MISMATCH',
-          error: { code: 'INVALID_FROM_ID', message: errorMessage },
+					message: errorMessage,
-          fromCache: false 
+					suggestion:
-        };
+						"Use 'from' parameter instead of 'id', or use the 'update_task' tool for single task updates"
-      }
+				},
-    } else {
+				fromCache: false
-      fromId = args.from;
+			};
-    }
+		}
 
-    // Get tasks file path
+		// Check required parameters
-    let tasksPath;
+		if (!from) {
-    try {
+			const errorMessage =
-      tasksPath = findTasksJsonPath(args, log);
+				'No from ID specified. Please provide a task ID to start updating from.';
-    } catch (error) {
+			log.error(errorMessage);
-      log.error(`Error finding tasks file: ${error.message}`);
+			return {
-      return { 
+				success: false,
-        success: false, 
+				error: { code: 'MISSING_FROM_ID', message: errorMessage },
-        error: { code: 'TASKS_FILE_ERROR', message: error.message },
+				fromCache: false
-        fromCache: false 
+			};
-      };
+		}
-    }
 
-    // Get research flag
+		if (!prompt) {
-    const useResearch = args.research === true;
+			const errorMessage =
+				'No prompt specified. Please provide a prompt with new context for task updates.';
+			log.error(errorMessage);
+			return {
+				success: false,
+				error: { code: 'MISSING_PROMPT', message: errorMessage },
+				fromCache: false
+			};
+		}
 
-    log.info(`Updating tasks from ID ${fromId} with prompt "${args.prompt}" and research: ${useResearch}`);
+		// Parse fromId - handle both string and number values
+		let fromId;
+		if (typeof from === 'string') {
+			fromId = parseInt(from, 10);
+			if (isNaN(fromId)) {
+				const errorMessage = `Invalid from ID: ${from}. Task ID must be a positive integer.`;
+				log.error(errorMessage);
+				return {
+					success: false,
+					error: { code: 'INVALID_FROM_ID', message: errorMessage },
+					fromCache: false
+				};
+			}
+		} else {
+			fromId = from;
+		}
 
-    try {
+		// Get research flag
-      // Enable silent mode to prevent console logs from interfering with JSON response
+		const useResearch = research === true;
-      enableSilentMode();
 
-      // Execute core updateTasks function
+		// Initialize appropriate AI client based on research flag
-      await updateTasks(tasksPath, fromId, args.prompt, useResearch);
+		let aiClient;
+		try {
+			if (useResearch) {
+				log.info('Using Perplexity AI for research-backed task updates');
+				aiClient = await getPerplexityClientForMCP(session, log);
+			} else {
+				log.info('Using Claude AI for task updates');
+				aiClient = getAnthropicClientForMCP(session, log);
+			}
+		} catch (error) {
+			log.error(`Failed to initialize AI client: ${error.message}`);
+			return {
+				success: false,
+				error: {
+					code: 'AI_CLIENT_ERROR',
+					message: `Cannot initialize AI client: ${error.message}`
+				},
+				fromCache: false
+			};
+		}
 
-      // Restore normal logging
+		log.info(
-      disableSilentMode();
+			`Updating tasks from ID ${fromId} with prompt "${prompt}" and research: ${useResearch}`
+		);
 
-      // Since updateTasks doesn't return a value but modifies the tasks file,
+		// Create the logger wrapper to ensure compatibility with core functions
-      // we'll return a success message
+		const logWrapper = {
-      return {
+			info: (message, ...args) => log.info(message, ...args),
-        success: true,
+			warn: (message, ...args) => log.warn(message, ...args),
-        data: {
+			error: (message, ...args) => log.error(message, ...args),
-          message: `Successfully updated tasks from ID ${fromId} based on the prompt`,
+			debug: (message, ...args) => log.debug && log.debug(message, ...args), // Handle optional debug
-          fromId,
+			success: (message, ...args) => log.info(message, ...args) // Map success to info if needed
-          tasksPath,
+		};
-          useResearch
-        },
-        fromCache: false // This operation always modifies state and should never be cached
-      };
-    } catch (error) {
-      // Make sure to restore normal logging even if there's an error
-      disableSilentMode();
-      throw error; // Rethrow to be caught by outer catch block
-    }
-  } catch (error) {
-    // Ensure silent mode is disabled
-    disableSilentMode();
 
-    log.error(`Error updating tasks: ${error.message}`);
+		try {
-    return { 
+			// Enable silent mode to prevent console logs from interfering with JSON response
-      success: false, 
+			enableSilentMode();
-      error: { code: 'UPDATE_TASKS_ERROR', message: error.message || 'Unknown error updating tasks' },
+
-      fromCache: false 
+			// Execute core updateTasks function, passing the AI client and session
-    };
+			await updateTasks(tasksJsonPath, fromId, prompt, useResearch, {
-  }
+				mcpLog: logWrapper, // Pass the wrapper instead of the raw log object
+				session
+			});
+
+			// Since updateTasks doesn't return a value but modifies the tasks file,
+			// we'll return a success message
+			return {
+				success: true,
+				data: {
+					message: `Successfully updated tasks from ID ${fromId} based on the prompt`,
+					fromId,
+					tasksPath: tasksJsonPath,
+					useResearch
+				},
+				fromCache: false // This operation always modifies state and should never be cached
+			};
+		} catch (error) {
+			log.error(`Error updating tasks: ${error.message}`);
+			return {
+				success: false,
+				error: {
+					code: 'UPDATE_TASKS_ERROR',
+					message: error.message || 'Unknown error updating tasks'
+				},
+				fromCache: false
+			};
+		} finally {
+			// Make sure to restore normal logging even if there's an error
+			disableSilentMode();
+		}
+	} catch (error) {
+		// Ensure silent mode is disabled
+		disableSilentMode();
+
+		log.error(`Error updating tasks: ${error.message}`);
+		return {
+			success: false,
+			error: {
+				code: 'UPDATE_TASKS_ERROR',
+				message: error.message || 'Unknown error updating tasks'
+			},
+			fromCache: false
+		};
+	}
 }

mcp-server/src/core/direct-functions/validate-dependencies.js

@@ -3,63 +3,78 @@
  */
 
 import { validateDependenciesCommand } from '../../../../scripts/modules/dependency-manager.js';
-import { findTasksJsonPath } from '../utils/path-utils.js';
+import {
-import { enableSilentMode, disableSilentMode } from '../../../../scripts/modules/utils.js';
+	enableSilentMode,
+	disableSilentMode
+} from '../../../../scripts/modules/utils.js';
 import fs from 'fs';
 
 /**
  * Validate dependencies in tasks.json
  * @param {Object} args - Function arguments
- * @param {string} [args.file] - Path to the tasks file
+ * @param {string} args.tasksJsonPath - Explicit path to the tasks.json file.
- * @param {string} [args.projectRoot] - Project root directory
  * @param {Object} log - Logger object
  * @returns {Promise<{success: boolean, data?: Object, error?: {code: string, message: string}}>}
  */
 export async function validateDependenciesDirect(args, log) {
-  try {
+	// Destructure the explicit tasksJsonPath
-    log.info(`Validating dependencies in tasks...`);
+	const { tasksJsonPath } = args;
 
-    // Find the tasks.json path
+	if (!tasksJsonPath) {
-    const tasksPath = findTasksJsonPath(args, log);
+		log.error('validateDependenciesDirect called without tasksJsonPath');
+		return {
+			success: false,
+			error: {
+				code: 'MISSING_ARGUMENT',
+				message: 'tasksJsonPath is required'
+			}
+		};
+	}
 
-    // Verify the file exists
+	try {
-    if (!fs.existsSync(tasksPath)) {
+		log.info(`Validating dependencies in tasks: ${tasksJsonPath}`);
-      return {
-        success: false,
-        error: {
-          code: 'FILE_NOT_FOUND',
-          message: `Tasks file not found at ${tasksPath}`
-        }
-      };
-    }
 
-    // Enable silent mode to prevent console logs from interfering with JSON response
+		// Use the provided tasksJsonPath
-    enableSilentMode();
+		const tasksPath = tasksJsonPath;
 
-    // Call the original command function
+		// Verify the file exists
-    await validateDependenciesCommand(tasksPath);
+		if (!fs.existsSync(tasksPath)) {
+			return {
+				success: false,
+				error: {
+					code: 'FILE_NOT_FOUND',
+					message: `Tasks file not found at ${tasksPath}`
+				}
+			};
+		}
 
-    // Restore normal logging
+		// Enable silent mode to prevent console logs from interfering with JSON response
-    disableSilentMode();
+		enableSilentMode();
 
-    return {
+		// Call the original command function using the provided tasksPath
-      success: true,
+		await validateDependenciesCommand(tasksPath);
-      data: {
-        message: 'Dependencies validated successfully',
-        tasksPath
-      }
-    };
-  } catch (error) {
-    // Make sure to restore normal logging even if there's an error
-    disableSilentMode();
 
-    log.error(`Error validating dependencies: ${error.message}`);
+		// Restore normal logging
-    return {
+		disableSilentMode();
-      success: false,
+
-      error: {
+		return {
-        code: 'VALIDATION_ERROR',
+			success: true,
-        message: error.message
+			data: {
-      }
+				message: 'Dependencies validated successfully',
-    };
+				tasksPath
-  }
+			}
+		};
+	} catch (error) {
+		// Make sure to restore normal logging even if there's an error
+		disableSilentMode();
+
+		log.error(`Error validating dependencies: ${error.message}`);
+		return {
+			success: false,
+			error: {
+				code: 'VALIDATION_ERROR',
+				message: error.message
+			}
+		};
+	}
 }

mcp-server/src/core/task-master-core.js

@@ -28,60 +28,71 @@ import { fixDependenciesDirect } from './direct-functions/fix-dependencies.js';
 import { complexityReportDirect } from './direct-functions/complexity-report.js';
 import { addDependencyDirect } from './direct-functions/add-dependency.js';
 import { removeTaskDirect } from './direct-functions/remove-task.js';
+import { initializeProjectDirect } from './direct-functions/initialize-project-direct.js';
 
 // Re-export utility functions
 export { findTasksJsonPath } from './utils/path-utils.js';
 
+// Re-export AI client utilities
+export {
+	getAnthropicClientForMCP,
+	getPerplexityClientForMCP,
+	getModelConfig,
+	getBestAvailableAIModel,
+	handleClaudeError
+} from './utils/ai-client-utils.js';
+
 // Use Map for potential future enhancements like introspection or dynamic dispatch
 export const directFunctions = new Map([
-  ['listTasksDirect', listTasksDirect],
+	['listTasksDirect', listTasksDirect],
-  ['getCacheStatsDirect', getCacheStatsDirect],
+	['getCacheStatsDirect', getCacheStatsDirect],
-  ['parsePRDDirect', parsePRDDirect],
+	['parsePRDDirect', parsePRDDirect],
-  ['updateTasksDirect', updateTasksDirect],
+	['updateTasksDirect', updateTasksDirect],
-  ['updateTaskByIdDirect', updateTaskByIdDirect],
+	['updateTaskByIdDirect', updateTaskByIdDirect],
-  ['updateSubtaskByIdDirect', updateSubtaskByIdDirect],
+	['updateSubtaskByIdDirect', updateSubtaskByIdDirect],
-  ['generateTaskFilesDirect', generateTaskFilesDirect],
+	['generateTaskFilesDirect', generateTaskFilesDirect],
-  ['setTaskStatusDirect', setTaskStatusDirect],
+	['setTaskStatusDirect', setTaskStatusDirect],
-  ['showTaskDirect', showTaskDirect],
+	['showTaskDirect', showTaskDirect],
-  ['nextTaskDirect', nextTaskDirect],
+	['nextTaskDirect', nextTaskDirect],
-  ['expandTaskDirect', expandTaskDirect],
+	['expandTaskDirect', expandTaskDirect],
-  ['addTaskDirect', addTaskDirect],
+	['addTaskDirect', addTaskDirect],
-  ['addSubtaskDirect', addSubtaskDirect],
+	['addSubtaskDirect', addSubtaskDirect],
-  ['removeSubtaskDirect', removeSubtaskDirect],
+	['removeSubtaskDirect', removeSubtaskDirect],
-  ['analyzeTaskComplexityDirect', analyzeTaskComplexityDirect],
+	['analyzeTaskComplexityDirect', analyzeTaskComplexityDirect],
-  ['clearSubtasksDirect', clearSubtasksDirect],
+	['clearSubtasksDirect', clearSubtasksDirect],
-  ['expandAllTasksDirect', expandAllTasksDirect],
+	['expandAllTasksDirect', expandAllTasksDirect],
-  ['removeDependencyDirect', removeDependencyDirect],
+	['removeDependencyDirect', removeDependencyDirect],
-  ['validateDependenciesDirect', validateDependenciesDirect],
+	['validateDependenciesDirect', validateDependenciesDirect],
-  ['fixDependenciesDirect', fixDependenciesDirect],
+	['fixDependenciesDirect', fixDependenciesDirect],
-  ['complexityReportDirect', complexityReportDirect],
+	['complexityReportDirect', complexityReportDirect],
-  ['addDependencyDirect', addDependencyDirect],
+	['addDependencyDirect', addDependencyDirect],
-  ['removeTaskDirect', removeTaskDirect]
+	['removeTaskDirect', removeTaskDirect]
 ]);
 
 // Re-export all direct function implementations
 export {
-  listTasksDirect,
+	listTasksDirect,
-  getCacheStatsDirect,
+	getCacheStatsDirect,
-  parsePRDDirect,
+	parsePRDDirect,
-  updateTasksDirect,
+	updateTasksDirect,
-  updateTaskByIdDirect,
+	updateTaskByIdDirect,
-  updateSubtaskByIdDirect,
+	updateSubtaskByIdDirect,
-  generateTaskFilesDirect,
+	generateTaskFilesDirect,
-  setTaskStatusDirect,
+	setTaskStatusDirect,
-  showTaskDirect,
+	showTaskDirect,
-  nextTaskDirect,
+	nextTaskDirect,
-  expandTaskDirect,
+	expandTaskDirect,
-  addTaskDirect,
+	addTaskDirect,
-  addSubtaskDirect,
+	addSubtaskDirect,
-  removeSubtaskDirect,
+	removeSubtaskDirect,
-  analyzeTaskComplexityDirect,
+	analyzeTaskComplexityDirect,
-  clearSubtasksDirect,
+	clearSubtasksDirect,
-  expandAllTasksDirect,
+	expandAllTasksDirect,
-  removeDependencyDirect,
+	removeDependencyDirect,
-  validateDependenciesDirect,
+	validateDependenciesDirect,
-  fixDependenciesDirect,
+	fixDependenciesDirect,
-  complexityReportDirect,
+	complexityReportDirect,
-  addDependencyDirect,
+	addDependencyDirect,
-  removeTaskDirect
+	removeTaskDirect,
+	initializeProjectDirect
 };

mcp-server/src/core/utils/ai-client-utils.js

@@ -11,9 +11,9 @@ dotenv.config();
 
 // Default model configuration from CLI environment
 const DEFAULT_MODEL_CONFIG = {
-  model: 'claude-3-7-sonnet-20250219',
+	model: 'claude-3-7-sonnet-20250219',
-  maxTokens: 64000,
+	maxTokens: 64000,
-  temperature: 0.2
+	temperature: 0.2
 };
 
 /**
@@ -24,25 +24,28 @@ const DEFAULT_MODEL_CONFIG = {
  * @throws {Error} If API key is missing
  */
 export function getAnthropicClientForMCP(session, log = console) {
-  try {
+	try {
-    // Extract API key from session.env or fall back to environment variables
+		// Extract API key from session.env or fall back to environment variables
-    const apiKey = session?.env?.ANTHROPIC_API_KEY || process.env.ANTHROPIC_API_KEY;
+		const apiKey =
+			session?.env?.ANTHROPIC_API_KEY || process.env.ANTHROPIC_API_KEY;
 
-    if (!apiKey) {
+		if (!apiKey) {
-      throw new Error('ANTHROPIC_API_KEY not found in session environment or process.env');
+			throw new Error(
-    }
+				'ANTHROPIC_API_KEY not found in session environment or process.env'
+			);
+		}
 
-    // Initialize and return a new Anthropic client
+		// Initialize and return a new Anthropic client
-    return new Anthropic({ 
+		return new Anthropic({
-      apiKey,
+			apiKey,
-      defaultHeaders: {
+			defaultHeaders: {
-        'anthropic-beta': 'output-128k-2025-02-19'  // Include header for increased token limit
+				'anthropic-beta': 'output-128k-2025-02-19' // Include header for increased token limit
-      }
+			}
-    });
+		});
-  } catch (error) {
+	} catch (error) {
-    log.error(`Failed to initialize Anthropic client: ${error.message}`);
+		log.error(`Failed to initialize Anthropic client: ${error.message}`);
-    throw error;
+		throw error;
-  }
+	}
 }
 
 /**
@@ -53,26 +56,29 @@ export function getAnthropicClientForMCP(session, log = console) {
  * @throws {Error} If API key is missing or OpenAI package can't be imported
  */
 export async function getPerplexityClientForMCP(session, log = console) {
-  try {
+	try {
-    // Extract API key from session.env or fall back to environment variables
+		// Extract API key from session.env or fall back to environment variables
-    const apiKey = session?.env?.PERPLEXITY_API_KEY || process.env.PERPLEXITY_API_KEY;
+		const apiKey =
+			session?.env?.PERPLEXITY_API_KEY || process.env.PERPLEXITY_API_KEY;
 
-    if (!apiKey) {
+		if (!apiKey) {
-      throw new Error('PERPLEXITY_API_KEY not found in session environment or process.env');
+			throw new Error(
-    }
+				'PERPLEXITY_API_KEY not found in session environment or process.env'
+			);
+		}
 
-    // Dynamically import OpenAI (it may not be used in all contexts)
+		// Dynamically import OpenAI (it may not be used in all contexts)
-    const { default: OpenAI } = await import('openai');
+		const { default: OpenAI } = await import('openai');
 
-    // Initialize and return a new OpenAI client configured for Perplexity
+		// Initialize and return a new OpenAI client configured for Perplexity
-    return new OpenAI({
+		return new OpenAI({
-      apiKey, 
+			apiKey,
-      baseURL: 'https://api.perplexity.ai'
+			baseURL: 'https://api.perplexity.ai'
-    });
+		});
-  } catch (error) {
+	} catch (error) {
-    log.error(`Failed to initialize Perplexity client: ${error.message}`);
+		log.error(`Failed to initialize Perplexity client: ${error.message}`);
-    throw error;
+		throw error;
-  }
+	}
 }
 
 /**
@@ -82,12 +88,12 @@ export async function getPerplexityClientForMCP(session, log = console) {
  * @returns {Object} Model configuration with model, maxTokens, and temperature
  */
 export function getModelConfig(session, defaults = DEFAULT_MODEL_CONFIG) {
-  // Get values from session or fall back to defaults
+	// Get values from session or fall back to defaults
-  return {
+	return {
-    model: session?.env?.MODEL || defaults.model,
+		model: session?.env?.MODEL || defaults.model,
-    maxTokens: parseInt(session?.env?.MAX_TOKENS || defaults.maxTokens),
+		maxTokens: parseInt(session?.env?.MAX_TOKENS || defaults.maxTokens),
-    temperature: parseFloat(session?.env?.TEMPERATURE || defaults.temperature)
+		temperature: parseFloat(session?.env?.TEMPERATURE || defaults.temperature)
-  };
+	};
 }
 
 /**
@@ -100,59 +106,78 @@ export function getModelConfig(session, defaults = DEFAULT_MODEL_CONFIG) {
  * @returns {Promise<Object>} Selected model info with type and client
  * @throws {Error} If no AI models are available
  */
-export async function getBestAvailableAIModel(session, options = {}, log = console) {
+export async function getBestAvailableAIModel(
-  const { requiresResearch = false, claudeOverloaded = false } = options;
+	session,
+	options = {},
+	log = console
+) {
+	const { requiresResearch = false, claudeOverloaded = false } = options;
 
-  // Test case: When research is needed but no Perplexity, use Claude
+	// Test case: When research is needed but no Perplexity, use Claude
-  if (requiresResearch && 
+	if (
-      !(session?.env?.PERPLEXITY_API_KEY || process.env.PERPLEXITY_API_KEY) && 
+		requiresResearch &&
-      (session?.env?.ANTHROPIC_API_KEY || process.env.ANTHROPIC_API_KEY)) {
+		!(session?.env?.PERPLEXITY_API_KEY || process.env.PERPLEXITY_API_KEY) &&
-    try {
+		(session?.env?.ANTHROPIC_API_KEY || process.env.ANTHROPIC_API_KEY)
-      log.warn('Perplexity not available for research, using Claude');
+	) {
-      const client = getAnthropicClientForMCP(session, log);
+		try {
-      return { type: 'claude', client };
+			log.warn('Perplexity not available for research, using Claude');
-    } catch (error) {
+			const client = getAnthropicClientForMCP(session, log);
-      log.error(`Claude not available: ${error.message}`);
+			return { type: 'claude', client };
-      throw new Error('No AI models available for research');
+		} catch (error) {
-    }
+			log.error(`Claude not available: ${error.message}`);
-  }
+			throw new Error('No AI models available for research');
+		}
+	}
 
-  // Regular path: Perplexity for research when available
+	// Regular path: Perplexity for research when available
-  if (requiresResearch && (session?.env?.PERPLEXITY_API_KEY || process.env.PERPLEXITY_API_KEY)) {
+	if (
-    try {
+		requiresResearch &&
-      const client = await getPerplexityClientForMCP(session, log);
+		(session?.env?.PERPLEXITY_API_KEY || process.env.PERPLEXITY_API_KEY)
-      return { type: 'perplexity', client };
+	) {
-    } catch (error) {
+		try {
-      log.warn(`Perplexity not available: ${error.message}`);
+			const client = await getPerplexityClientForMCP(session, log);
-      // Fall through to Claude as backup
+			return { type: 'perplexity', client };
-    }
+		} catch (error) {
-  }
+			log.warn(`Perplexity not available: ${error.message}`);
+			// Fall through to Claude as backup
+		}
+	}
 
-  // Test case: Claude for overloaded scenario
+	// Test case: Claude for overloaded scenario
-  if (claudeOverloaded && (session?.env?.ANTHROPIC_API_KEY || process.env.ANTHROPIC_API_KEY)) {
+	if (
-    try {
+		claudeOverloaded &&
-      log.warn('Claude is overloaded but no alternatives are available. Proceeding with Claude anyway.');
+		(session?.env?.ANTHROPIC_API_KEY || process.env.ANTHROPIC_API_KEY)
-      const client = getAnthropicClientForMCP(session, log);
+	) {
-      return { type: 'claude', client };
+		try {
-    } catch (error) {
+			log.warn(
-      log.error(`Claude not available despite being overloaded: ${error.message}`);
+				'Claude is overloaded but no alternatives are available. Proceeding with Claude anyway.'
-      throw new Error('No AI models available');
+			);
-    }
+			const client = getAnthropicClientForMCP(session, log);
-  }
+			return { type: 'claude', client };
+		} catch (error) {
+			log.error(
+				`Claude not available despite being overloaded: ${error.message}`
+			);
+			throw new Error('No AI models available');
+		}
+	}
 
-  // Default case: Use Claude when available and not overloaded
+	// Default case: Use Claude when available and not overloaded
-  if (!claudeOverloaded && (session?.env?.ANTHROPIC_API_KEY || process.env.ANTHROPIC_API_KEY)) {
+	if (
-    try {
+		!claudeOverloaded &&
-      const client = getAnthropicClientForMCP(session, log);
+		(session?.env?.ANTHROPIC_API_KEY || process.env.ANTHROPIC_API_KEY)
-      return { type: 'claude', client };
+	) {
-    } catch (error) {
+		try {
-      log.warn(`Claude not available: ${error.message}`);
+			const client = getAnthropicClientForMCP(session, log);
-      // Fall through to error if no other options
+			return { type: 'claude', client };
-    }
+		} catch (error) {
-  }
+			log.warn(`Claude not available: ${error.message}`);
+			// Fall through to error if no other options
+		}
+	}
 
-  // If we got here, no models were successfully initialized
+	// If we got here, no models were successfully initialized
-  throw new Error('No AI models available. Please check your API keys.');
+	throw new Error('No AI models available. Please check your API keys.');
 }
 
 /**
@@ -161,28 +186,28 @@ export async function getBestAvailableAIModel(session, options = {}, log = conso
  * @returns {string} User-friendly error message
  */
 export function handleClaudeError(error) {
-  // Check if it's a structured error response
+	// Check if it's a structured error response
-  if (error.type === 'error' && error.error) {
+	if (error.type === 'error' && error.error) {
-    switch (error.error.type) {
+		switch (error.error.type) {
-      case 'overloaded_error':
+			case 'overloaded_error':
-        return 'Claude is currently experiencing high demand and is overloaded. Please wait a few minutes and try again.';
+				return 'Claude is currently experiencing high demand and is overloaded. Please wait a few minutes and try again.';
-      case 'rate_limit_error':
+			case 'rate_limit_error':
-        return 'You have exceeded the rate limit. Please wait a few minutes before making more requests.';
+				return 'You have exceeded the rate limit. Please wait a few minutes before making more requests.';
-      case 'invalid_request_error':
+			case 'invalid_request_error':
-        return 'There was an issue with the request format. If this persists, please report it as a bug.';
+				return 'There was an issue with the request format. If this persists, please report it as a bug.';
-      default:
+			default:
-        return `Claude API error: ${error.error.message}`;
+				return `Claude API error: ${error.error.message}`;
-    }
+		}
-  }
+	}
 
-  // Check for network/timeout errors
+	// Check for network/timeout errors
-  if (error.message?.toLowerCase().includes('timeout')) {
+	if (error.message?.toLowerCase().includes('timeout')) {
-    return 'The request to Claude timed out. Please try again.';
+		return 'The request to Claude timed out. Please try again.';
-  }
+	}
-  if (error.message?.toLowerCase().includes('network')) {
+	if (error.message?.toLowerCase().includes('network')) {
-    return 'There was a network error connecting to Claude. Please check your internet connection and try again.';
+		return 'There was a network error connecting to Claude. Please check your internet connection and try again.';
-  }
+	}
 
-  // Default error message
+	// Default error message
-  return `Error communicating with Claude: ${error.message}`;
+	return `Error communicating with Claude: ${error.message}`;
 }

mcp-server/src/core/utils/async-manager.js

@@ -1,213 +1,247 @@
 import { v4 as uuidv4 } from 'uuid';
 
 class AsyncOperationManager {
-    constructor() {
+	constructor() {
-        this.operations = new Map(); // Stores active operation state
+		this.operations = new Map(); // Stores active operation state
-        this.completedOperations = new Map(); // Stores completed operations
+		this.completedOperations = new Map(); // Stores completed operations
-        this.maxCompletedOperations = 100; // Maximum number of completed operations to store
+		this.maxCompletedOperations = 100; // Maximum number of completed operations to store
-        this.listeners = new Map(); // For potential future notifications
+		this.listeners = new Map(); // For potential future notifications
-    }
+	}
 
-    /**
+	/**
-     * Adds an operation to be executed asynchronously.
+	 * Adds an operation to be executed asynchronously.
-     * @param {Function} operationFn - The async function to execute (e.g., a Direct function).
+	 * @param {Function} operationFn - The async function to execute (e.g., a Direct function).
-     * @param {Object} args - Arguments to pass to the operationFn.
+	 * @param {Object} args - Arguments to pass to the operationFn.
-     * @param {Object} context - The MCP tool context { log, reportProgress, session }.
+	 * @param {Object} context - The MCP tool context { log, reportProgress, session }.
-     * @returns {string} The unique ID assigned to this operation.
+	 * @returns {string} The unique ID assigned to this operation.
-     */
+	 */
-    addOperation(operationFn, args, context) {
+	addOperation(operationFn, args, context) {
-        const operationId = `op-${uuidv4()}`;
+		const operationId = `op-${uuidv4()}`;
-        const operation = {
+		const operation = {
-            id: operationId,
+			id: operationId,
-            status: 'pending',
+			status: 'pending',
-            startTime: Date.now(),
+			startTime: Date.now(),
-            endTime: null,
+			endTime: null,
-            result: null,
+			result: null,
-            error: null,
+			error: null,
-            // Store necessary parts of context, especially log for background execution
+			// Store necessary parts of context, especially log for background execution
-            log: context.log, 
+			log: context.log,
-            reportProgress: context.reportProgress, // Pass reportProgress through
+			reportProgress: context.reportProgress, // Pass reportProgress through
-            session: context.session // Pass session through if needed by the operationFn
+			session: context.session // Pass session through if needed by the operationFn
-        };
+		};
-        this.operations.set(operationId, operation);
+		this.operations.set(operationId, operation);
-        this.log(operationId, 'info', `Operation added.`);
+		this.log(operationId, 'info', `Operation added.`);
 
-        // Start execution in the background (don't await here)
+		// Start execution in the background (don't await here)
-        this._runOperation(operationId, operationFn, args, context).catch(err => {
+		this._runOperation(operationId, operationFn, args, context).catch((err) => {
-            // Catch unexpected errors during the async execution setup itself
+			// Catch unexpected errors during the async execution setup itself
-             this.log(operationId, 'error', `Critical error starting operation: ${err.message}`, { stack: err.stack });
+			this.log(
-             operation.status = 'failed';
+				operationId,
-             operation.error = { code: 'MANAGER_EXECUTION_ERROR', message: err.message };
+				'error',
-             operation.endTime = Date.now();
+				`Critical error starting operation: ${err.message}`,
+				{ stack: err.stack }
+			);
+			operation.status = 'failed';
+			operation.error = {
+				code: 'MANAGER_EXECUTION_ERROR',
+				message: err.message
+			};
+			operation.endTime = Date.now();
 
-             // Move to completed operations
+			// Move to completed operations
-             this._moveToCompleted(operationId);
+			this._moveToCompleted(operationId);
-        });
+		});
 
-        return operationId;
+		return operationId;
-    }
+	}
 
-    /**
+	/**
-     * Internal function to execute the operation.
+	 * Internal function to execute the operation.
-     * @param {string} operationId - The ID of the operation.
+	 * @param {string} operationId - The ID of the operation.
-     * @param {Function} operationFn - The async function to execute.
+	 * @param {Function} operationFn - The async function to execute.
-     * @param {Object} args - Arguments for the function.
+	 * @param {Object} args - Arguments for the function.
-     * @param {Object} context - The original MCP tool context.
+	 * @param {Object} context - The original MCP tool context.
-     */
+	 */
-    async _runOperation(operationId, operationFn, args, context) {
+	async _runOperation(operationId, operationFn, args, context) {
-        const operation = this.operations.get(operationId);
+		const operation = this.operations.get(operationId);
-        if (!operation) return; // Should not happen
+		if (!operation) return; // Should not happen
 
-        operation.status = 'running';
+		operation.status = 'running';
-        this.log(operationId, 'info', `Operation running.`);
+		this.log(operationId, 'info', `Operation running.`);
-        this.emit('statusChanged', { operationId, status: 'running' });
+		this.emit('statusChanged', { operationId, status: 'running' });
 
-        try {
+		try {
-            // Pass the necessary context parts to the direct function
+			// Pass the necessary context parts to the direct function
-            // The direct function needs to be adapted if it needs reportProgress
+			// The direct function needs to be adapted if it needs reportProgress
-            // We pass the original context's log, plus our wrapped reportProgress
+			// We pass the original context's log, plus our wrapped reportProgress
-            const result = await operationFn(args, operation.log, { 
+			const result = await operationFn(args, operation.log, {
-                reportProgress: (progress) => this._handleProgress(operationId, progress), 
+				reportProgress: (progress) =>
-                mcpLog: operation.log, // Pass log as mcpLog if direct fn expects it
+					this._handleProgress(operationId, progress),
-                session: operation.session 
+				mcpLog: operation.log, // Pass log as mcpLog if direct fn expects it
-            });
+				session: operation.session
+			});
 
-            operation.status = result.success ? 'completed' : 'failed';
+			operation.status = result.success ? 'completed' : 'failed';
-            operation.result = result.success ? result.data : null;
+			operation.result = result.success ? result.data : null;
-            operation.error = result.success ? null : result.error;
+			operation.error = result.success ? null : result.error;
-            this.log(operationId, 'info', `Operation finished with status: ${operation.status}`);
+			this.log(
+				operationId,
+				'info',
+				`Operation finished with status: ${operation.status}`
+			);
+		} catch (error) {
+			this.log(
+				operationId,
+				'error',
+				`Operation failed with error: ${error.message}`,
+				{ stack: error.stack }
+			);
+			operation.status = 'failed';
+			operation.error = {
+				code: 'OPERATION_EXECUTION_ERROR',
+				message: error.message
+			};
+		} finally {
+			operation.endTime = Date.now();
+			this.emit('statusChanged', {
+				operationId,
+				status: operation.status,
+				result: operation.result,
+				error: operation.error
+			});
 
-        } catch (error) {
+			// Move to completed operations if done or failed
-            this.log(operationId, 'error', `Operation failed with error: ${error.message}`, { stack: error.stack });
+			if (operation.status === 'completed' || operation.status === 'failed') {
-            operation.status = 'failed';
+				this._moveToCompleted(operationId);
-            operation.error = { code: 'OPERATION_EXECUTION_ERROR', message: error.message };
+			}
-        } finally {
+		}
-            operation.endTime = Date.now();
+	}
-            this.emit('statusChanged', { operationId, status: operation.status, result: operation.result, error: operation.error });
 
-            // Move to completed operations if done or failed
+	/**
-            if (operation.status === 'completed' || operation.status === 'failed') {
+	 * Move an operation from active operations to completed operations history.
-                this._moveToCompleted(operationId);
+	 * @param {string} operationId - The ID of the operation to move.
-            }
+	 * @private
-        }
+	 */
-    }
+	_moveToCompleted(operationId) {
+		const operation = this.operations.get(operationId);
+		if (!operation) return;
 
-    /**
+		// Store only the necessary data in completed operations
-     * Move an operation from active operations to completed operations history.
+		const completedData = {
-     * @param {string} operationId - The ID of the operation to move.
+			id: operation.id,
-     * @private
+			status: operation.status,
-     */
+			startTime: operation.startTime,
-    _moveToCompleted(operationId) {
+			endTime: operation.endTime,
-        const operation = this.operations.get(operationId);
+			result: operation.result,
-        if (!operation) return;
+			error: operation.error
+		};
 
-        // Store only the necessary data in completed operations
+		this.completedOperations.set(operationId, completedData);
-        const completedData = {
+		this.operations.delete(operationId);
-            id: operation.id,
-            status: operation.status,
-            startTime: operation.startTime,
-            endTime: operation.endTime,
-            result: operation.result,
-            error: operation.error,
-        };
 
-        this.completedOperations.set(operationId, completedData);
+		// Trim completed operations if exceeding maximum
-        this.operations.delete(operationId);
+		if (this.completedOperations.size > this.maxCompletedOperations) {
+			// Get the oldest operation (sorted by endTime)
+			const oldest = [...this.completedOperations.entries()].sort(
+				(a, b) => a[1].endTime - b[1].endTime
+			)[0];
 
-        // Trim completed operations if exceeding maximum
+			if (oldest) {
-        if (this.completedOperations.size > this.maxCompletedOperations) {
+				this.completedOperations.delete(oldest[0]);
-            // Get the oldest operation (sorted by endTime)
+			}
-            const oldest = [...this.completedOperations.entries()]
+		}
-                .sort((a, b) => a[1].endTime - b[1].endTime)[0];
+	}
 
-            if (oldest) {
+	/**
-                this.completedOperations.delete(oldest[0]);
+	 * Handles progress updates from the running operation and forwards them.
-            }
+	 * @param {string} operationId - The ID of the operation reporting progress.
-        }
+	 * @param {Object} progress - The progress object { progress, total? }.
-    }
+	 */
+	_handleProgress(operationId, progress) {
+		const operation = this.operations.get(operationId);
+		if (operation && operation.reportProgress) {
+			try {
+				// Use the reportProgress function captured from the original context
+				operation.reportProgress(progress);
+				this.log(
+					operationId,
+					'debug',
+					`Reported progress: ${JSON.stringify(progress)}`
+				);
+			} catch (err) {
+				this.log(
+					operationId,
+					'warn',
+					`Failed to report progress: ${err.message}`
+				);
+				// Don't stop the operation, just log the reporting failure
+			}
+		}
+	}
 
-    /**
+	/**
-     * Handles progress updates from the running operation and forwards them.
+	 * Retrieves the status and result/error of an operation.
-     * @param {string} operationId - The ID of the operation reporting progress.
+	 * @param {string} operationId - The ID of the operation.
-     * @param {Object} progress - The progress object { progress, total? }.
+	 * @returns {Object | null} The operation details or null if not found.
-     */
+	 */
-    _handleProgress(operationId, progress) {
+	getStatus(operationId) {
-        const operation = this.operations.get(operationId);
+		// First check active operations
-        if (operation && operation.reportProgress) {
+		const operation = this.operations.get(operationId);
-            try {
+		if (operation) {
-                 // Use the reportProgress function captured from the original context
+			return {
-                operation.reportProgress(progress); 
+				id: operation.id,
-                this.log(operationId, 'debug', `Reported progress: ${JSON.stringify(progress)}`);
+				status: operation.status,
-            } catch(err) {
+				startTime: operation.startTime,
-                this.log(operationId, 'warn', `Failed to report progress: ${err.message}`);
+				endTime: operation.endTime,
-                // Don't stop the operation, just log the reporting failure
+				result: operation.result,
-            }
+				error: operation.error
-        }
+			};
-     }
+		}
 
-    /**
+		// Then check completed operations
-     * Retrieves the status and result/error of an operation.
+		const completedOperation = this.completedOperations.get(operationId);
-     * @param {string} operationId - The ID of the operation.
+		if (completedOperation) {
-     * @returns {Object | null} The operation details or null if not found.
+			return completedOperation;
-     */
+		}
-    getStatus(operationId) {
-        // First check active operations
-        const operation = this.operations.get(operationId);
-        if (operation) {
-            return {
-                id: operation.id,
-                status: operation.status,
-                startTime: operation.startTime,
-                endTime: operation.endTime,
-                result: operation.result,
-                error: operation.error,
-            };
-        }
 
-        // Then check completed operations
+		// Operation not found in either active or completed
-        const completedOperation = this.completedOperations.get(operationId);
+		return {
-        if (completedOperation) {
+			error: {
-            return completedOperation;
+				code: 'OPERATION_NOT_FOUND',
-        }
+				message: `Operation ID ${operationId} not found. It may have been completed and removed from history, or the ID may be invalid.`
+			},
+			status: 'not_found'
+		};
+	}
 
-        // Operation not found in either active or completed
+	/**
-        return {
+	 * Internal logging helper to prefix logs with the operation ID.
-            error: {
+	 * @param {string} operationId - The ID of the operation.
-                code: 'OPERATION_NOT_FOUND',
+	 * @param {'info'|'warn'|'error'|'debug'} level - Log level.
-                message: `Operation ID ${operationId} not found. It may have been completed and removed from history, or the ID may be invalid.`
+	 * @param {string} message - Log message.
-            },
+	 * @param {Object} [meta] - Additional metadata.
-            status: 'not_found'
+	 */
-        };
+	log(operationId, level, message, meta = {}) {
-    }
+		const operation = this.operations.get(operationId);
+		// Use the logger instance associated with the operation if available, otherwise console
+		const logger = operation?.log || console;
+		const logFn = logger[level] || logger.log || console.log; // Fallback
+		logFn(`[AsyncOp ${operationId}] ${message}`, meta);
+	}
 
-     /**
+	// --- Basic Event Emitter ---
-     * Internal logging helper to prefix logs with the operation ID.
+	on(eventName, listener) {
-     * @param {string} operationId - The ID of the operation.
+		if (!this.listeners.has(eventName)) {
-     * @param {'info'|'warn'|'error'|'debug'} level - Log level.
+			this.listeners.set(eventName, []);
-     * @param {string} message - Log message.
+		}
-     * @param {Object} [meta] - Additional metadata.
+		this.listeners.get(eventName).push(listener);
-     */
+	}
-    log(operationId, level, message, meta = {}) {
-         const operation = this.operations.get(operationId);
-         // Use the logger instance associated with the operation if available, otherwise console
-         const logger = operation?.log || console;
-         const logFn = logger[level] || logger.log || console.log; // Fallback
-         logFn(`[AsyncOp ${operationId}] ${message}`, meta);
-     }
 
-    // --- Basic Event Emitter ---
+	emit(eventName, data) {
-    on(eventName, listener) {
+		if (this.listeners.has(eventName)) {
-        if (!this.listeners.has(eventName)) {
+			this.listeners.get(eventName).forEach((listener) => listener(data));
-            this.listeners.set(eventName, []);
+		}
-        }
+	}
-        this.listeners.get(eventName).push(listener);
-    }
-
-    emit(eventName, data) {
-        if (this.listeners.has(eventName)) {
-            this.listeners.get(eventName).forEach(listener => listener(data));
-        }
-    }
 }
 
 // Export a singleton instance

mcp-server/src/core/utils/env-utils.js

@@ -6,38 +6,42 @@
  * @returns {Promise<any>} The result of the actionFn.
  */
 export async function withSessionEnv(sessionEnv, actionFn) {
-    if (!sessionEnv || typeof sessionEnv !== 'object' || Object.keys(sessionEnv).length === 0) {
+	if (
-      // If no sessionEnv is provided, just run the action directly
+		!sessionEnv ||
-      return await actionFn();
+		typeof sessionEnv !== 'object' ||
-    }
+		Object.keys(sessionEnv).length === 0
+	) {
+		// If no sessionEnv is provided, just run the action directly
+		return await actionFn();
+	}
 
-    const originalEnv = {};
+	const originalEnv = {};
-    const keysToRestore = [];
+	const keysToRestore = [];
 
-    // Set environment variables from sessionEnv
+	// Set environment variables from sessionEnv
-    for (const key in sessionEnv) {
+	for (const key in sessionEnv) {
-      if (Object.prototype.hasOwnProperty.call(sessionEnv, key)) {
+		if (Object.prototype.hasOwnProperty.call(sessionEnv, key)) {
-        // Store original value if it exists, otherwise mark for deletion
+			// Store original value if it exists, otherwise mark for deletion
-        if (process.env[key] !== undefined) {
+			if (process.env[key] !== undefined) {
-          originalEnv[key] = process.env[key];
+				originalEnv[key] = process.env[key];
-        }
+			}
-        keysToRestore.push(key);
+			keysToRestore.push(key);
-        process.env[key] = sessionEnv[key];
+			process.env[key] = sessionEnv[key];
-      }
+		}
-    }
+	}
 
-    try {
+	try {
-      // Execute the provided action function
+		// Execute the provided action function
-      return await actionFn();
+		return await actionFn();
-    } finally {
+	} finally {
-      // Restore original environment variables
+		// Restore original environment variables
-      for (const key of keysToRestore) {
+		for (const key of keysToRestore) {
-        if (Object.prototype.hasOwnProperty.call(originalEnv, key)) {
+			if (Object.prototype.hasOwnProperty.call(originalEnv, key)) {
-          process.env[key] = originalEnv[key];
+				process.env[key] = originalEnv[key];
-        } else {
+			} else {
-          // If the key didn't exist originally, delete it
+				// If the key didn't exist originally, delete it
-          delete process.env[key];
+				delete process.env[key];
-        }
+			}
-      }
+		}
-    }
+	}
-  } 
+}

mcp-server/src/core/utils/path-utils.js

@@ -18,43 +18,43 @@ export let lastFoundProjectRoot = null;
 
 // Project marker files that indicate a potential project root
 export const PROJECT_MARKERS = [
-  // Task Master specific
+	// Task Master specific
-  'tasks.json',
+	'tasks.json',
-  'tasks/tasks.json',
+	'tasks/tasks.json',
 
-  // Common version control
+	// Common version control
-  '.git',
+	'.git',
-  '.svn',
+	'.svn',
 
-  // Common package files
+	// Common package files
-  'package.json',
+	'package.json',
-  'pyproject.toml',
+	'pyproject.toml',
-  'Gemfile',
+	'Gemfile',
-  'go.mod',
+	'go.mod',
-  'Cargo.toml',
+	'Cargo.toml',
 
-  // Common IDE/editor folders
+	// Common IDE/editor folders
-  '.cursor',
+	'.cursor',
-  '.vscode',
+	'.vscode',
-  '.idea',
+	'.idea',
 
-  // Common dependency directories (check if directory)
+	// Common dependency directories (check if directory)
-  'node_modules',
+	'node_modules',
-  'venv',
+	'venv',
-  '.venv',
+	'.venv',
 
-  // Common config files
+	// Common config files
-  '.env',
+	'.env',
-  '.eslintrc',
+	'.eslintrc',
-  'tsconfig.json',
+	'tsconfig.json',
-  'babel.config.js',
+	'babel.config.js',
-  'jest.config.js',
+	'jest.config.js',
-  'webpack.config.js',
+	'webpack.config.js',
 
-  // Common CI/CD files
+	// Common CI/CD files
-  '.github/workflows',
+	'.github/workflows',
-  '.gitlab-ci.yml',
+	'.gitlab-ci.yml',
-  '.circleci/config.yml'
+	'.circleci/config.yml'
 ];
 
 /**
@@ -63,15 +63,15 @@ export const PROJECT_MARKERS = [
  * @returns {string} - Absolute path to the package installation directory
  */
 export function getPackagePath() {
-  // When running from source, __dirname is the directory containing this file
+	// When running from source, __dirname is the directory containing this file
-  // When running from npm, we need to find the package root
+	// When running from npm, we need to find the package root
-  const thisFilePath = fileURLToPath(import.meta.url);
+	const thisFilePath = fileURLToPath(import.meta.url);
-  const thisFileDir = path.dirname(thisFilePath);
+	const thisFileDir = path.dirname(thisFilePath);
 
-  // Navigate from core/utils up to the package root
+	// Navigate from core/utils up to the package root
-  // In dev: /path/to/task-master/mcp-server/src/core/utils -> /path/to/task-master
+	// In dev: /path/to/task-master/mcp-server/src/core/utils -> /path/to/task-master
-  // In npm: /path/to/node_modules/task-master/mcp-server/src/core/utils -> /path/to/node_modules/task-master
+	// In npm: /path/to/node_modules/task-master/mcp-server/src/core/utils -> /path/to/node_modules/task-master
-  return path.resolve(thisFileDir, '../../../../');
+	return path.resolve(thisFileDir, '../../../../');
 }
 
 /**
@@ -82,62 +82,73 @@ export function getPackagePath() {
  * @throws {Error} - If tasks.json cannot be found.
  */
 export function findTasksJsonPath(args, log) {
-  // PRECEDENCE ORDER for finding tasks.json:
+	// PRECEDENCE ORDER for finding tasks.json:
-  // 1. Explicitly provided `projectRoot` in args (Highest priority, expected in MCP context)
+	// 1. Explicitly provided `projectRoot` in args (Highest priority, expected in MCP context)
-  // 2. Previously found/cached `lastFoundProjectRoot` (primarily for CLI performance)
+	// 2. Previously found/cached `lastFoundProjectRoot` (primarily for CLI performance)
-  // 3. Search upwards from current working directory (`process.cwd()`) - CLI usage
+	// 3. Search upwards from current working directory (`process.cwd()`) - CLI usage
 
-  // 1. If project root is explicitly provided (e.g., from MCP session), use it directly
+	// 1. If project root is explicitly provided (e.g., from MCP session), use it directly
-  if (args.projectRoot) {
+	if (args.projectRoot) {
-    const projectRoot = args.projectRoot;
+		const projectRoot = args.projectRoot;
-    log.info(`Using explicitly provided project root: ${projectRoot}`);
+		log.info(`Using explicitly provided project root: ${projectRoot}`);
-    try {
+		try {
-      // This will throw if tasks.json isn't found within this root
+			// This will throw if tasks.json isn't found within this root
-      return findTasksJsonInDirectory(projectRoot, args.file, log); 
+			return findTasksJsonInDirectory(projectRoot, args.file, log);
-    } catch (error) {
+		} catch (error) {
-      // Include debug info in error
+			// Include debug info in error
-      const debugInfo = {
+			const debugInfo = {
-        projectRoot,
+				projectRoot,
-        currentDir: process.cwd(),
+				currentDir: process.cwd(),
-        serverDir: path.dirname(process.argv[1]),
+				serverDir: path.dirname(process.argv[1]),
-        possibleProjectRoot: path.resolve(path.dirname(process.argv[1]), '../..'),
+				possibleProjectRoot: path.resolve(
-        lastFoundProjectRoot,
+					path.dirname(process.argv[1]),
-        searchedPaths: error.message
+					'../..'
-      };
+				),
+				lastFoundProjectRoot,
+				searchedPaths: error.message
+			};
 
-      error.message = `Tasks file not found in any of the expected locations relative to project root "${projectRoot}" (from session).\nDebug Info: ${JSON.stringify(debugInfo, null, 2)}`;
+			error.message = `Tasks file not found in any of the expected locations relative to project root "${projectRoot}" (from session).\nDebug Info: ${JSON.stringify(debugInfo, null, 2)}`;
-      throw error;
+			throw error;
-    }
+		}
-  }
+	}
 
-  // --- Fallback logic primarily for CLI or when projectRoot isn't passed --- 
+	// --- Fallback logic primarily for CLI or when projectRoot isn't passed ---
 
-  // 2. If we have a last known project root that worked, try it first
+	// 2. If we have a last known project root that worked, try it first
-  if (lastFoundProjectRoot) {
+	if (lastFoundProjectRoot) {
-    log.info(`Trying last known project root: ${lastFoundProjectRoot}`);
+		log.info(`Trying last known project root: ${lastFoundProjectRoot}`);
-    try {
+		try {
-      // Use the cached root
+			// Use the cached root
-      const tasksPath = findTasksJsonInDirectory(lastFoundProjectRoot, args.file, log); 
+			const tasksPath = findTasksJsonInDirectory(
-      return tasksPath; // Return if found in cached root
+				lastFoundProjectRoot,
-    } catch (error) {
+				args.file,
-      log.info(`Task file not found in last known project root, continuing search.`);
+				log
-      // Continue with search if not found in cache
+			);
-    }
+			return tasksPath; // Return if found in cached root
-  }
+		} catch (error) {
+			log.info(
+				`Task file not found in last known project root, continuing search.`
+			);
+			// Continue with search if not found in cache
+		}
+	}
 
-  // 3. Start search from current directory (most common CLI scenario)
+	// 3. Start search from current directory (most common CLI scenario)
-  const startDir = process.cwd();
+	const startDir = process.cwd();
-  log.info(`Searching for tasks.json starting from current directory: ${startDir}`);
+	log.info(
+		`Searching for tasks.json starting from current directory: ${startDir}`
+	);
 
-  // Try to find tasks.json by walking up the directory tree from cwd
+	// Try to find tasks.json by walking up the directory tree from cwd
-  try {
+	try {
-    // This will throw if not found in the CWD tree
+		// This will throw if not found in the CWD tree
-    return findTasksJsonWithParentSearch(startDir, args.file, log); 
+		return findTasksJsonWithParentSearch(startDir, args.file, log);
-  } catch (error) {
+	} catch (error) {
-    // If all attempts fail, augment and throw the original error from CWD search
+		// If all attempts fail, augment and throw the original error from CWD search
-    error.message = `${error.message}\n\nPossible solutions:\n1. Run the command from your project directory containing tasks.json\n2. Use --project-root=/path/to/project to specify the project location (if using CLI)\n3. Ensure the project root is correctly passed from the client (if using MCP)\n\nCurrent working directory: ${startDir}\nLast known project root: ${lastFoundProjectRoot}\nProject root from args: ${args.projectRoot}`;
+		error.message = `${error.message}\n\nPossible solutions:\n1. Run the command from your project directory containing tasks.json\n2. Use --project-root=/path/to/project to specify the project location (if using CLI)\n3. Ensure the project root is correctly passed from the client (if using MCP)\n\nCurrent working directory: ${startDir}\nLast known project root: ${lastFoundProjectRoot}\nProject root from args: ${args.projectRoot}`;
-    throw error;
+		throw error;
-  }
+	}
 }
 
 /**
@@ -146,11 +157,11 @@ export function findTasksJsonPath(args, log) {
  * @returns {boolean} - True if the directory contains any project markers
  */
 function hasProjectMarkers(dirPath) {
-  return PROJECT_MARKERS.some(marker => {
+	return PROJECT_MARKERS.some((marker) => {
-    const markerPath = path.join(dirPath, marker);
+		const markerPath = path.join(dirPath, marker);
-    // Check if the marker exists as either a file or directory
+		// Check if the marker exists as either a file or directory
-    return fs.existsSync(markerPath);
+		return fs.existsSync(markerPath);
-  });
+	});
 }
 
 /**
@@ -162,35 +173,41 @@ function hasProjectMarkers(dirPath) {
  * @throws {Error} - If tasks.json cannot be found
  */
 function findTasksJsonInDirectory(dirPath, explicitFilePath, log) {
-  const possiblePaths = [];
+	const possiblePaths = [];
 
-  // 1. If a file is explicitly provided relative to dirPath
+	// 1. If a file is explicitly provided relative to dirPath
-  if (explicitFilePath) {
+	if (explicitFilePath) {
-    possiblePaths.push(path.resolve(dirPath, explicitFilePath));
+		possiblePaths.push(path.resolve(dirPath, explicitFilePath));
-  }
+	}
 
-  // 2. Check the standard locations relative to dirPath
+	// 2. Check the standard locations relative to dirPath
-  possiblePaths.push(
+	possiblePaths.push(
-    path.join(dirPath, 'tasks.json'),
+		path.join(dirPath, 'tasks.json'),
-    path.join(dirPath, 'tasks', 'tasks.json')
+		path.join(dirPath, 'tasks', 'tasks.json')
-  );
+	);
 
-  log.info(`Checking potential task file paths: ${possiblePaths.join(', ')}`);
+	log.info(`Checking potential task file paths: ${possiblePaths.join(', ')}`);
 
-  // Find the first existing path
+	// Find the first existing path
-  for (const p of possiblePaths) {
+	for (const p of possiblePaths) {
-    if (fs.existsSync(p)) {
+		log.info(`Checking if exists: ${p}`);
-      log.info(`Found tasks file at: ${p}`);
+		const exists = fs.existsSync(p);
-      // Store the project root for future use
+		log.info(`Path ${p} exists: ${exists}`);
-      lastFoundProjectRoot = dirPath;
-      return p;
-    }
-  }
 
-  // If no file was found, throw an error
+		if (exists) {
-  const error = new Error(`Tasks file not found in any of the expected locations relative to ${dirPath}: ${possiblePaths.join(', ')}`);
+			log.info(`Found tasks file at: ${p}`);
-  error.code = 'TASKS_FILE_NOT_FOUND';
+			// Store the project root for future use
-  throw error;
+			lastFoundProjectRoot = dirPath;
+			return p;
+		}
+	}
+
+	// If no file was found, throw an error
+	const error = new Error(
+		`Tasks file not found in any of the expected locations relative to ${dirPath}: ${possiblePaths.join(', ')}`
+	);
+	error.code = 'TASKS_FILE_NOT_FOUND';
+	throw error;
 }
 
 /**
@@ -203,66 +220,174 @@ function findTasksJsonInDirectory(dirPath, explicitFilePath, log) {
  * @throws {Error} - If tasks.json cannot be found in any parent directory
  */
 function findTasksJsonWithParentSearch(startDir, explicitFilePath, log) {
-  let currentDir = startDir;
+	let currentDir = startDir;
-  const rootDir = path.parse(currentDir).root;
+	const rootDir = path.parse(currentDir).root;
 
-  // Keep traversing up until we hit the root directory
+	// Keep traversing up until we hit the root directory
-  while (currentDir !== rootDir) {
+	while (currentDir !== rootDir) {
-    // First check for tasks.json directly
+		// First check for tasks.json directly
-    try {
+		try {
-      return findTasksJsonInDirectory(currentDir, explicitFilePath, log);
+			return findTasksJsonInDirectory(currentDir, explicitFilePath, log);
-    } catch (error) {
+		} catch (error) {
-      // If tasks.json not found but the directory has project markers,
+			// If tasks.json not found but the directory has project markers,
-      // log it as a potential project root (helpful for debugging)
+			// log it as a potential project root (helpful for debugging)
-      if (hasProjectMarkers(currentDir)) {
+			if (hasProjectMarkers(currentDir)) {
-        log.info(`Found project markers in ${currentDir}, but no tasks.json`);
+				log.info(`Found project markers in ${currentDir}, but no tasks.json`);
-      }
+			}
 
-      // Move up to parent directory
+			// Move up to parent directory
-      const parentDir = path.dirname(currentDir);
+			const parentDir = path.dirname(currentDir);
 
-      // Check if we've reached the root
+			// Check if we've reached the root
-      if (parentDir === currentDir) {
+			if (parentDir === currentDir) {
-        break;
+				break;
-      }
+			}
 
-      log.info(`Tasks file not found in ${currentDir}, searching in parent directory: ${parentDir}`);
+			log.info(
-      currentDir = parentDir;
+				`Tasks file not found in ${currentDir}, searching in parent directory: ${parentDir}`
-    }
+			);
-  }
+			currentDir = parentDir;
+		}
+	}
 
-  // If we've searched all the way to the root and found nothing
+	// If we've searched all the way to the root and found nothing
-  const error = new Error(`Tasks file not found in ${startDir} or any parent directory.`);
+	const error = new Error(
-  error.code = 'TASKS_FILE_NOT_FOUND';
+		`Tasks file not found in ${startDir} or any parent directory.`
-  throw error;
+	);
+	error.code = 'TASKS_FILE_NOT_FOUND';
+	throw error;
 }
 
 // Note: findTasksWithNpmConsideration is not used by findTasksJsonPath and might be legacy or used elsewhere.
 // If confirmed unused, it could potentially be removed in a separate cleanup.
 function findTasksWithNpmConsideration(startDir, log) {
-  // First try our recursive parent search from cwd
+	// First try our recursive parent search from cwd
-  try {
+	try {
-    return findTasksJsonWithParentSearch(startDir, null, log);
+		return findTasksJsonWithParentSearch(startDir, null, log);
-  } catch (error) {
+	} catch (error) {
-    // If that fails, try looking relative to the executable location
+		// If that fails, try looking relative to the executable location
-    const execPath = process.argv[1];
+		const execPath = process.argv[1];
-    const execDir = path.dirname(execPath);
+		const execDir = path.dirname(execPath);
-    log.info(`Looking for tasks file relative to executable at: ${execDir}`);
+		log.info(`Looking for tasks file relative to executable at: ${execDir}`);
 
-    try {
+		try {
-      return findTasksJsonWithParentSearch(execDir, null, log);
+			return findTasksJsonWithParentSearch(execDir, null, log);
-    } catch (secondError) {
+		} catch (secondError) {
-      // If that also fails, check standard locations in user's home directory
+			// If that also fails, check standard locations in user's home directory
-      const homeDir = os.homedir();
+			const homeDir = os.homedir();
-      log.info(`Looking for tasks file in home directory: ${homeDir}`);
+			log.info(`Looking for tasks file in home directory: ${homeDir}`);
 
-      try {
+			try {
-        // Check standard locations in home dir
+				// Check standard locations in home dir
-        return findTasksJsonInDirectory(path.join(homeDir, '.task-master'), null, log);
+				return findTasksJsonInDirectory(
-      } catch (thirdError) {
+					path.join(homeDir, '.task-master'),
-        // If all approaches fail, throw the original error
+					null,
-        throw error;
+					log
-      }
+				);
-    }
+			} catch (thirdError) {
-  }
+				// If all approaches fail, throw the original error
+				throw error;
+			}
+		}
+	}
+}
+
+/**
+ * Finds potential PRD document files based on common naming patterns
+ * @param {string} projectRoot - The project root directory
+ * @param {string|null} explicitPath - Optional explicit path provided by the user
+ * @param {Object} log - Logger object
+ * @returns {string|null} - The path to the first found PRD file, or null if none found
+ */
+export function findPRDDocumentPath(projectRoot, explicitPath, log) {
+	// If explicit path is provided, check if it exists
+	if (explicitPath) {
+		const fullPath = path.isAbsolute(explicitPath)
+			? explicitPath
+			: path.resolve(projectRoot, explicitPath);
+
+		if (fs.existsSync(fullPath)) {
+			log.info(`Using provided PRD document path: ${fullPath}`);
+			return fullPath;
+		} else {
+			log.warn(
+				`Provided PRD document path not found: ${fullPath}, will search for alternatives`
+			);
+		}
+	}
+
+	// Common locations and file patterns for PRD documents
+	const commonLocations = [
+		'', // Project root
+		'scripts/'
+	];
+
+	const commonFileNames = ['PRD.md', 'prd.md', 'PRD.txt', 'prd.txt'];
+
+	// Check all possible combinations
+	for (const location of commonLocations) {
+		for (const fileName of commonFileNames) {
+			const potentialPath = path.join(projectRoot, location, fileName);
+			if (fs.existsSync(potentialPath)) {
+				log.info(`Found PRD document at: ${potentialPath}`);
+				return potentialPath;
+			}
+		}
+	}
+
+	log.warn(`No PRD document found in common locations within ${projectRoot}`);
+	return null;
+}
+
+/**
+ * Resolves the tasks output directory path
+ * @param {string} projectRoot - The project root directory
+ * @param {string|null} explicitPath - Optional explicit output path provided by the user
+ * @param {Object} log - Logger object
+ * @returns {string} - The resolved tasks directory path
+ */
+export function resolveTasksOutputPath(projectRoot, explicitPath, log) {
+	// If explicit path is provided, use it
+	if (explicitPath) {
+		const outputPath = path.isAbsolute(explicitPath)
+			? explicitPath
+			: path.resolve(projectRoot, explicitPath);
+
+		log.info(`Using provided tasks output path: ${outputPath}`);
+		return outputPath;
+	}
+
+	// Default output path: tasks/tasks.json in the project root
+	const defaultPath = path.resolve(projectRoot, 'tasks', 'tasks.json');
+	log.info(`Using default tasks output path: ${defaultPath}`);
+
+	// Ensure the directory exists
+	const outputDir = path.dirname(defaultPath);
+	if (!fs.existsSync(outputDir)) {
+		log.info(`Creating tasks directory: ${outputDir}`);
+		fs.mkdirSync(outputDir, { recursive: true });
+	}
+
+	return defaultPath;
+}
+
+/**
+ * Resolves various file paths needed for MCP operations based on project root
+ * @param {string} projectRoot - The project root directory
+ * @param {Object} args - Command arguments that may contain explicit paths
+ * @param {Object} log - Logger object
+ * @returns {Object} - An object containing resolved paths
+ */
+export function resolveProjectPaths(projectRoot, args, log) {
+	const prdPath = findPRDDocumentPath(projectRoot, args.input, log);
+	const tasksJsonPath = resolveTasksOutputPath(projectRoot, args.output, log);
+
+	// You can add more path resolutions here as needed
+
+	return {
+		projectRoot,
+		prdPath,
+		tasksJsonPath
+		// Add additional path properties as needed
+	};
 }

mcp-server/src/index.js

@@ -1,10 +1,10 @@
-import { FastMCP } from "fastmcp";
+import { FastMCP } from 'fastmcp';
-import path from "path";
+import path from 'path';
-import dotenv from "dotenv";
+import dotenv from 'dotenv';
-import { fileURLToPath } from "url";
+import { fileURLToPath } from 'url';
-import fs from "fs";
+import fs from 'fs';
-import logger from "./logger.js";
+import logger from './logger.js';
-import { registerTaskMasterTools } from "./tools/index.js";
+import { registerTaskMasterTools } from './tools/index.js';
 import { asyncOperationManager } from './core/utils/async-manager.js';
 
 // Load environment variables
@@ -18,73 +18,74 @@ const __dirname = path.dirname(__filename);
  * Main MCP server class that integrates with Task Master
  */
 class TaskMasterMCPServer {
-  constructor() {
+	constructor() {
-    // Get version from package.json using synchronous fs
+		// Get version from package.json using synchronous fs
-    const packagePath = path.join(__dirname, "../../package.json");
+		const packagePath = path.join(__dirname, '../../package.json');
-    const packageJson = JSON.parse(fs.readFileSync(packagePath, "utf8"));
+		const packageJson = JSON.parse(fs.readFileSync(packagePath, 'utf8'));
 
-    this.options = {
+		this.options = {
-      name: "Task Master MCP Server",
+			name: 'Task Master MCP Server',
-      version: packageJson.version,
+			version: packageJson.version
-    };
+		};
 
-    this.server = new FastMCP(this.options);
+		this.server = new FastMCP(this.options);
-    this.initialized = false;
+		this.initialized = false;
 
-    this.server.addResource({});
+		this.server.addResource({});
 
-    this.server.addResourceTemplate({});
+		this.server.addResourceTemplate({});
 
-    // Make the manager accessible (e.g., pass it to tool registration)
+		// Make the manager accessible (e.g., pass it to tool registration)
-    this.asyncManager = asyncOperationManager;
+		this.asyncManager = asyncOperationManager;
 
-    // Bind methods
+		// Bind methods
-    this.init = this.init.bind(this);
+		this.init = this.init.bind(this);
-    this.start = this.start.bind(this);
+		this.start = this.start.bind(this);
-    this.stop = this.stop.bind(this);
+		this.stop = this.stop.bind(this);
 
-    // Setup logging
+		// Setup logging
-    this.logger = logger;
+		this.logger = logger;
-  }
+	}
 
-  /**
+	/**
-   * Initialize the MCP server with necessary tools and routes
+	 * Initialize the MCP server with necessary tools and routes
-   */
+	 */
-  async init() {
+	async init() {
-    if (this.initialized) return;
+		if (this.initialized) return;
 
-    // Pass the manager instance to the tool registration function
+		// Pass the manager instance to the tool registration function
-    registerTaskMasterTools(this.server, this.asyncManager);
+		registerTaskMasterTools(this.server, this.asyncManager);
 
-    this.initialized = true;
+		this.initialized = true;
 
-    return this;
+		return this;
-  }
+	}
 
-  /**
+	/**
-   * Start the MCP server
+	 * Start the MCP server
-   */
+	 */
-  async start() {
+	async start() {
-    if (!this.initialized) {
+		if (!this.initialized) {
-      await this.init();
+			await this.init();
-    }
+		}
 
-    // Start the FastMCP server
+		// Start the FastMCP server with increased timeout
-    await this.server.start({
+		await this.server.start({
-      transportType: "stdio",
+			transportType: 'stdio',
-    });
+			timeout: 120000 // 2 minutes timeout (in milliseconds)
+		});
 
-    return this;
+		return this;
-  }
+	}
 
-  /**
+	/**
-   * Stop the MCP server
+	 * Stop the MCP server
-   */
+	 */
-  async stop() {
+	async stop() {
-    if (this.server) {
+		if (this.server) {
-      await this.server.stop();
+			await this.server.stop();
-    }
+		}
-  }
+	}
 }
 
 // Export the manager from here as well, if needed elsewhere

mcp-server/src/logger.js

@@ -1,18 +1,19 @@
-import chalk from "chalk";
+import chalk from 'chalk';
+import { isSilentMode } from '../../scripts/modules/utils.js';
 
 // Define log levels
 const LOG_LEVELS = {
-  debug: 0,
+	debug: 0,
-  info: 1,
+	info: 1,
-  warn: 2,
+	warn: 2,
-  error: 3,
+	error: 3,
-  success: 4,
+	success: 4
 };
 
 // Get log level from environment or default to info
 const LOG_LEVEL = process.env.LOG_LEVEL
-  ? LOG_LEVELS[process.env.LOG_LEVEL.toLowerCase()] ?? LOG_LEVELS.info
+	? (LOG_LEVELS[process.env.LOG_LEVEL.toLowerCase()] ?? LOG_LEVELS.info)
-  : LOG_LEVELS.info;
+	: LOG_LEVELS.info;
 
 /**
  * Logs a message with the specified level
@@ -20,51 +21,66 @@ const LOG_LEVEL = process.env.LOG_LEVEL
  * @param  {...any} args - Arguments to log
  */
 function log(level, ...args) {
-  // Use text prefixes instead of emojis
+	// Skip logging if silent mode is enabled
-  const prefixes = {
+	if (isSilentMode()) {
-    debug: chalk.gray("[DEBUG]"),
+		return;
-    info: chalk.blue("[INFO]"),
+	}
-    warn: chalk.yellow("[WARN]"),
-    error: chalk.red("[ERROR]"),
-    success: chalk.green("[SUCCESS]"),
-  };
 
-  if (LOG_LEVELS[level] !== undefined && LOG_LEVELS[level] >= LOG_LEVEL) {
+	// Use text prefixes instead of emojis
-    const prefix = prefixes[level] || "";
+	const prefixes = {
-    let coloredArgs = args;
+		debug: chalk.gray('[DEBUG]'),
+		info: chalk.blue('[INFO]'),
+		warn: chalk.yellow('[WARN]'),
+		error: chalk.red('[ERROR]'),
+		success: chalk.green('[SUCCESS]')
+	};
 
-    try {
+	if (LOG_LEVELS[level] !== undefined && LOG_LEVELS[level] >= LOG_LEVEL) {
-      switch(level) {
+		const prefix = prefixes[level] || '';
-        case "error":
+		let coloredArgs = args;
-          coloredArgs = args.map(arg => typeof arg === 'string' ? chalk.red(arg) : arg);
-          break;
-        case "warn":
-          coloredArgs = args.map(arg => typeof arg === 'string' ? chalk.yellow(arg) : arg);
-          break;
-        case "success":
-          coloredArgs = args.map(arg => typeof arg === 'string' ? chalk.green(arg) : arg);
-          break;
-        case "info":
-          coloredArgs = args.map(arg => typeof arg === 'string' ? chalk.blue(arg) : arg);
-          break;
-        case "debug":
-          coloredArgs = args.map(arg => typeof arg === 'string' ? chalk.gray(arg) : arg);
-          break;
-        // default: use original args (no color)
-      }
-    } catch (colorError) {
-      // Fallback if chalk fails on an argument
-      // Use console.error here for internal logger errors, separate from normal logging
-      console.error("Internal Logger Error applying chalk color:", colorError);
-      coloredArgs = args;
-    }
 
-    // Revert to console.log - FastMCP's context logger (context.log)
+		try {
-    // is responsible for directing logs correctly (e.g., to stderr)
+			switch (level) {
-    // during tool execution without upsetting the client connection.
+				case 'error':
-    // Logs outside of tool execution (like startup) will go to stdout.
+					coloredArgs = args.map((arg) =>
-    console.log(prefix, ...coloredArgs);
+						typeof arg === 'string' ? chalk.red(arg) : arg
-  }
+					);
+					break;
+				case 'warn':
+					coloredArgs = args.map((arg) =>
+						typeof arg === 'string' ? chalk.yellow(arg) : arg
+					);
+					break;
+				case 'success':
+					coloredArgs = args.map((arg) =>
+						typeof arg === 'string' ? chalk.green(arg) : arg
+					);
+					break;
+				case 'info':
+					coloredArgs = args.map((arg) =>
+						typeof arg === 'string' ? chalk.blue(arg) : arg
+					);
+					break;
+				case 'debug':
+					coloredArgs = args.map((arg) =>
+						typeof arg === 'string' ? chalk.gray(arg) : arg
+					);
+					break;
+				// default: use original args (no color)
+			}
+		} catch (colorError) {
+			// Fallback if chalk fails on an argument
+			// Use console.error here for internal logger errors, separate from normal logging
+			console.error('Internal Logger Error applying chalk color:', colorError);
+			coloredArgs = args;
+		}
+
+		// Revert to console.log - FastMCP's context logger (context.log)
+		// is responsible for directing logs correctly (e.g., to stderr)
+		// during tool execution without upsetting the client connection.
+		// Logs outside of tool execution (like startup) will go to stdout.
+		console.log(prefix, ...coloredArgs);
+	}
 }
 
 /**
@@ -72,16 +88,19 @@ function log(level, ...args) {
  * @returns {Object} Logger object with info, error, debug, warn, and success methods
  */
 export function createLogger() {
-  const createLogMethod = (level) => (...args) => log(level, ...args);
+	const createLogMethod =
+		(level) =>
+		(...args) =>
+			log(level, ...args);
 
-  return {
+	return {
-    debug: createLogMethod("debug"),
+		debug: createLogMethod('debug'),
-    info: createLogMethod("info"),
+		info: createLogMethod('info'),
-    warn: createLogMethod("warn"),
+		warn: createLogMethod('warn'),
-    error: createLogMethod("error"),
+		error: createLogMethod('error'),
-    success: createLogMethod("success"),
+		success: createLogMethod('success'),
-    log: log, // Also expose the raw log function
+		log: log // Also expose the raw log function
-  };
+	};
 }
 
 // Export a default logger instance

mcp-server/src/logger.js (lines 31-41)

@@ -1 +0,0 @@
- 

mcp-server/src/tools/add-dependency.js

@@ -3,63 +3,95 @@
  * Tool for adding a dependency to a task
  */
 
-import { z } from "zod";
+import { z } from 'zod';
 import {
-  handleApiResult,
+	handleApiResult,
-  createErrorResponse,
+	createErrorResponse,
-  getProjectRootFromSession
+	getProjectRootFromSession
-} from "./utils.js";
+} from './utils.js';
-import { addDependencyDirect } from "../core/task-master-core.js";
+import { addDependencyDirect } from '../core/task-master-core.js';
+import { findTasksJsonPath } from '../core/utils/path-utils.js';
 
 /**
  * Register the addDependency tool with the MCP server
  * @param {Object} server - FastMCP server instance
  */
 export function registerAddDependencyTool(server) {
-  server.addTool({
+	server.addTool({
-    name: "add_dependency",
+		name: 'add_dependency',
-    description: "Add a dependency relationship between two tasks",
+		description: 'Add a dependency relationship between two tasks',
-    parameters: z.object({
+		parameters: z.object({
-      id: z.string().describe("ID of task that will depend on another task"),
+			id: z.string().describe('ID of task that will depend on another task'),
-      dependsOn: z.string().describe("ID of task that will become a dependency"),
+			dependsOn: z
-      file: z.string().optional().describe("Path to the tasks file (default: tasks/tasks.json)"),
+				.string()
-      projectRoot: z.string().optional().describe("Root directory of the project (default: current working directory)")
+				.describe('ID of task that will become a dependency'),
-    }),
+			file: z
-    execute: async (args, { log, session, reportProgress }) => {
+				.string()
-      try {
+				.optional()
-        log.info(`Adding dependency for task ${args.id} to depend on ${args.dependsOn}`);
+				.describe(
-        reportProgress({ progress: 0 });
+					'Absolute path to the tasks file (default: tasks/tasks.json)'
+				),
+			projectRoot: z
+				.string()
+				.describe('The directory of the project. Must be an absolute path.')
+		}),
+		execute: async (args, { log, session }) => {
+			try {
+				log.info(
+					`Adding dependency for task ${args.id} to depend on ${args.dependsOn}`
+				);
 
-        // Get project root using the utility function
+				// Get project root from args or session
-        let rootFolder = getProjectRootFromSession(session, log);
+				const rootFolder =
+					args.projectRoot || getProjectRootFromSession(session, log);
 
-        // Fallback to args.projectRoot if session didn't provide one
+				// Ensure project root was determined
-        if (!rootFolder && args.projectRoot) {
+				if (!rootFolder) {
-          rootFolder = args.projectRoot;
+					return createErrorResponse(
-          log.info(`Using project root from args as fallback: ${rootFolder}`);
+						'Could not determine project root. Please provide it explicitly or ensure your session contains valid root information.'
-        }
+					);
+				}
 
-        // Call the direct function with the resolved rootFolder
+				// Resolve the path to tasks.json
-        const result = await addDependencyDirect({
+				let tasksJsonPath;
-          projectRoot: rootFolder,
+				try {
-          ...args
+					tasksJsonPath = findTasksJsonPath(
-        }, log, { reportProgress, mcpLog: log, session});
+						{ projectRoot: rootFolder, file: args.file },
+						log
+					);
+				} catch (error) {
+					log.error(`Error finding tasks.json: ${error.message}`);
+					return createErrorResponse(
+						`Failed to find tasks.json: ${error.message}`
+					);
+				}
 
-        reportProgress({ progress: 100 });
+				// Call the direct function with the resolved path
+				const result = await addDependencyDirect(
+					{
+						// Pass the explicitly resolved path
+						tasksJsonPath: tasksJsonPath,
+						// Pass other relevant args
+						id: args.id,
+						dependsOn: args.dependsOn
+					},
+					log
+					// Remove context object
+				);
 
-        // Log result
+				// Log result
-        if (result.success) {
+				if (result.success) {
-          log.info(`Successfully added dependency: ${result.data.message}`);
+					log.info(`Successfully added dependency: ${result.data.message}`);
-        } else {
+				} else {
-          log.error(`Failed to add dependency: ${result.error.message}`);
+					log.error(`Failed to add dependency: ${result.error.message}`);
-        }
+				}
 
-        // Use handleApiResult to format the response
+				// Use handleApiResult to format the response
-        return handleApiResult(result, log, 'Error adding dependency');
+				return handleApiResult(result, log, 'Error adding dependency');
-      } catch (error) {
+			} catch (error) {
-        log.error(`Error in addDependency tool: ${error.message}`);
+				log.error(`Error in addDependency tool: ${error.message}`);
-        return createErrorResponse(error.message);
+				return createErrorResponse(error.message);
-      }
+			}
-    },
+		}
-  });
+	});
 }

mcp-server/src/tools/add-subtask.js

@@ -3,61 +3,116 @@
  * Tool for adding subtasks to existing tasks
  */
 
-import { z } from "zod";
+import { z } from 'zod';
 import {
-  handleApiResult,
+	handleApiResult,
-  createErrorResponse,
+	createErrorResponse,
-  getProjectRootFromSession
+	getProjectRootFromSession
-} from "./utils.js";
+} from './utils.js';
-import { addSubtaskDirect } from "../core/task-master-core.js";
+import { addSubtaskDirect } from '../core/task-master-core.js';
+import { findTasksJsonPath } from '../core/utils/path-utils.js';
 
 /**
  * Register the addSubtask tool with the MCP server
  * @param {Object} server - FastMCP server instance
  */
 export function registerAddSubtaskTool(server) {
-  server.addTool({
+	server.addTool({
-    name: "add_subtask",
+		name: 'add_subtask',
-    description: "Add a subtask to an existing task",
+		description: 'Add a subtask to an existing task',
-    parameters: z.object({
+		parameters: z.object({
-      id: z.string().describe("Parent task ID (required)"),
+			id: z.string().describe('Parent task ID (required)'),
-      taskId: z.string().optional().describe("Existing task ID to convert to subtask"),
+			taskId: z
-      title: z.string().optional().describe("Title for the new subtask (when creating a new subtask)"),
+				.string()
-      description: z.string().optional().describe("Description for the new subtask"),
+				.optional()
-      details: z.string().optional().describe("Implementation details for the new subtask"),
+				.describe('Existing task ID to convert to subtask'),
-      status: z.string().optional().describe("Status for the new subtask (default: 'pending')"),
+			title: z
-      dependencies: z.string().optional().describe("Comma-separated list of dependency IDs for the new subtask"),
+				.string()
-      file: z.string().optional().describe("Path to the tasks file (default: tasks/tasks.json)"),
+				.optional()
-      skipGenerate: z.boolean().optional().describe("Skip regenerating task files"),
+				.describe('Title for the new subtask (when creating a new subtask)'),
-      projectRoot: z.string().optional().describe("Root directory of the project (default: current working directory)")
+			description: z
-    }),
+				.string()
-    execute: async (args, { log, session, reportProgress }) => {
+				.optional()
-      try {
+				.describe('Description for the new subtask'),
-        log.info(`Adding subtask with args: ${JSON.stringify(args)}`);
+			details: z
+				.string()
+				.optional()
+				.describe('Implementation details for the new subtask'),
+			status: z
+				.string()
+				.optional()
+				.describe("Status for the new subtask (default: 'pending')"),
+			dependencies: z
+				.string()
+				.optional()
+				.describe('Comma-separated list of dependency IDs for the new subtask'),
+			file: z
+				.string()
+				.optional()
+				.describe(
+					'Absolute path to the tasks file (default: tasks/tasks.json)'
+				),
+			skipGenerate: z
+				.boolean()
+				.optional()
+				.describe('Skip regenerating task files'),
+			projectRoot: z
+				.string()
+				.describe('The directory of the project. Must be an absolute path.')
+		}),
+		execute: async (args, { log, session }) => {
+			try {
+				log.info(`Adding subtask with args: ${JSON.stringify(args)}`);
 
-        let rootFolder = getProjectRootFromSession(session, log);
+				// Get project root from args or session
+				const rootFolder =
+					args.projectRoot || getProjectRootFromSession(session, log);
 
-        if (!rootFolder && args.projectRoot) {
+				if (!rootFolder) {
-          rootFolder = args.projectRoot;
+					return createErrorResponse(
-          log.info(`Using project root from args as fallback: ${rootFolder}`);
+						'Could not determine project root. Please provide it explicitly or ensure your session contains valid root information.'
-        }
+					);
+				}
 
-        const result = await addSubtaskDirect({
+				let tasksJsonPath;
-          projectRoot: rootFolder,
+				try {
-          ...args
+					tasksJsonPath = findTasksJsonPath(
-        }, log, { reportProgress, mcpLog: log, session});
+						{ projectRoot: rootFolder, file: args.file },
+						log
+					);
+				} catch (error) {
+					log.error(`Error finding tasks.json: ${error.message}`);
+					return createErrorResponse(
+						`Failed to find tasks.json: ${error.message}`
+					);
+				}
 
-        if (result.success) {
+				const result = await addSubtaskDirect(
-          log.info(`Subtask added successfully: ${result.data.message}`);
+					{
-        } else {
+						tasksJsonPath: tasksJsonPath,
-          log.error(`Failed to add subtask: ${result.error.message}`);
+						id: args.id,
-        }
+						taskId: args.taskId,
+						title: args.title,
+						description: args.description,
+						details: args.details,
+						status: args.status,
+						dependencies: args.dependencies,
+						skipGenerate: args.skipGenerate
+					},
+					log
+				);
 
-        return handleApiResult(result, log, 'Error adding subtask');
+				if (result.success) {
-      } catch (error) {
+					log.info(`Subtask added successfully: ${result.data.message}`);
-        log.error(`Error in addSubtask tool: ${error.message}`);
+				} else {
-        return createErrorResponse(error.message);
+					log.error(`Failed to add subtask: ${result.error.message}`);
-      }
+				}
-    },
+
-  });
+				return handleApiResult(result, log, 'Error adding subtask');
+			} catch (error) {
+				log.error(`Error in addSubtask tool: ${error.message}`);
+				return createErrorResponse(error.message);
+			}
+		}
+	});
 }

mcp-server/src/tools/add-task.js

@@ -3,64 +3,118 @@
  * Tool to add a new task using AI
  */
 
-import { z } from "zod";
+import { z } from 'zod';
 import {
-  handleApiResult,
+	createErrorResponse,
-  createErrorResponse,
+	createContentResponse,
-  createContentResponse,
+	getProjectRootFromSession,
-  getProjectRootFromSession
+	executeTaskMasterCommand,
-} from "./utils.js";
+	handleApiResult
-import { addTaskDirect } from "../core/task-master-core.js";
+} from './utils.js';
+import { addTaskDirect } from '../core/task-master-core.js';
+import { findTasksJsonPath } from '../core/utils/path-utils.js';
 
 /**
- * Register the add-task tool with the MCP server
+ * Register the addTask tool with the MCP server
  * @param {Object} server - FastMCP server instance
- * @param {AsyncOperationManager} asyncManager - The async operation manager instance.
  */
-export function registerAddTaskTool(server, asyncManager) {
+export function registerAddTaskTool(server) {
-  server.addTool({
+	server.addTool({
-    name: "add_task",
+		name: 'add_task',
-    description: "Starts adding a new task using AI in the background.",
+		description: 'Add a new task using AI',
-    parameters: z.object({
+		parameters: z.object({
-      prompt: z.string().describe("Description of the task to add"),
+			prompt: z
-      dependencies: z.string().optional().describe("Comma-separated list of task IDs this task depends on"),
+				.string()
-      priority: z.string().optional().describe("Task priority (high, medium, low)"),
+				.optional()
-      file: z.string().optional().describe("Path to the tasks file"),
+				.describe(
-      projectRoot: z.string().optional().describe("Root directory of the project (default: current working directory)")
+					'Description of the task to add (required if not using manual fields)'
-    }),
+				),
-    execute: async (args, context) => {
+			title: z
-      const { log, reportProgress, session } = context;
+				.string()
-      try {
+				.optional()
-        log.info(`MCP add_task request received with prompt: \"${args.prompt}\"`);
+				.describe('Task title (for manual task creation)'),
+			description: z
+				.string()
+				.optional()
+				.describe('Task description (for manual task creation)'),
+			details: z
+				.string()
+				.optional()
+				.describe('Implementation details (for manual task creation)'),
+			testStrategy: z
+				.string()
+				.optional()
+				.describe('Test strategy (for manual task creation)'),
+			dependencies: z
+				.string()
+				.optional()
+				.describe('Comma-separated list of task IDs this task depends on'),
+			priority: z
+				.string()
+				.optional()
+				.describe('Task priority (high, medium, low)'),
+			file: z
+				.string()
+				.optional()
+				.describe('Path to the tasks file (default: tasks/tasks.json)'),
+			projectRoot: z
+				.string()
+				.describe('The directory of the project. Must be an absolute path.'),
+			research: z
+				.boolean()
+				.optional()
+				.describe('Whether to use research capabilities for task creation')
+		}),
+		execute: async (args, { log, session }) => {
+			try {
+				log.info(`Starting add-task with args: ${JSON.stringify(args)}`);
 
-        if (!args.prompt) {
+				// Get project root from args or session
-          return createErrorResponse("Prompt is required for add_task.", "VALIDATION_ERROR");
+				const rootFolder =
-        }
+					args.projectRoot || getProjectRootFromSession(session, log);
 
-        let rootFolder = getProjectRootFromSession(session, log);
+				// Ensure project root was determined
-        if (!rootFolder && args.projectRoot) {
+				if (!rootFolder) {
-          rootFolder = args.projectRoot;
+					return createErrorResponse(
-          log.info(`Using project root from args as fallback: ${rootFolder}`);
+						'Could not determine project root. Please provide it explicitly or ensure your session contains valid root information.'
-        }
+					);
+				}
 
-        const directArgs = {
+				// Resolve the path to tasks.json
-          projectRoot: rootFolder,
+				let tasksJsonPath;
-          ...args
+				try {
-        };
+					tasksJsonPath = findTasksJsonPath(
+						{ projectRoot: rootFolder, file: args.file },
+						log
+					);
+				} catch (error) {
+					log.error(`Error finding tasks.json: ${error.message}`);
+					return createErrorResponse(
+						`Failed to find tasks.json: ${error.message}`
+					);
+				}
 
-        const operationId = asyncManager.addOperation(addTaskDirect, directArgs, context);
+				// Call the direct function
+				const result = await addTaskDirect(
+					{
+						// Pass the explicitly resolved path
+						tasksJsonPath: tasksJsonPath,
+						// Pass other relevant args
+						prompt: args.prompt,
+						dependencies: args.dependencies,
+						priority: args.priority,
+						research: args.research
+					},
+					log,
+					{ session }
+				);
 
-        log.info(`Started background operation for add_task. Operation ID: ${operationId}`);
+				// Return the result
-
+				return handleApiResult(result, log);
-        return createContentResponse({
+			} catch (error) {
-          message: "Add task operation started successfully.",
+				log.error(`Error in add-task tool: ${error.message}`);
-          operationId: operationId 
+				return createErrorResponse(error.message);
-        });
+			}
-
+		}
-      } catch (error) {
+	});
-        log.error(`Error initiating add_task operation: ${error.message}`, { stack: error.stack });
-        return createErrorResponse(`Failed to start add task operation: ${error.message}`, "ADD_TASK_INIT_ERROR");
-      }
-    }
-  });
 }

mcp-server/src/tools/analyze.js

@@ -3,61 +3,121 @@
  * Tool for analyzing task complexity and generating recommendations
  */
 
-import { z } from "zod";
+import { z } from 'zod';
 import {
-  handleApiResult,
+	handleApiResult,
-  createErrorResponse,
+	createErrorResponse,
-  getProjectRootFromSession
+	getProjectRootFromSession
-} from "./utils.js";
+} from './utils.js';
-import { analyzeTaskComplexityDirect } from "../core/task-master-core.js";
+import { analyzeTaskComplexityDirect } from '../core/task-master-core.js';
+import { findTasksJsonPath } from '../core/utils/path-utils.js';
+import path from 'path';
 
 /**
  * Register the analyze tool with the MCP server
  * @param {Object} server - FastMCP server instance
  */
 export function registerAnalyzeTool(server) {
-  server.addTool({
+	server.addTool({
-    name: "analyze_project_complexity",
+		name: 'analyze_project_complexity',
-    description: "Analyze task complexity and generate expansion recommendations",
+		description:
-    parameters: z.object({
+			'Analyze task complexity and generate expansion recommendations',
-      output: z.string().optional().describe("Output file path for the report (default: scripts/task-complexity-report.json)"),
+		parameters: z.object({
-      model: z.string().optional().describe("LLM model to use for analysis (defaults to configured model)"),
+			output: z
-      threshold: z.union([z.number(), z.string()]).optional().describe("Minimum complexity score to recommend expansion (1-10) (default: 5)"),
+				.string()
-      file: z.string().optional().describe("Path to the tasks file (default: tasks/tasks.json)"),
+				.optional()
-      research: z.boolean().optional().describe("Use Perplexity AI for research-backed complexity analysis"),
+				.describe(
-      projectRoot: z.string().optional().describe("Root directory of the project (default: current working directory)")
+					'Output file path for the report (default: scripts/task-complexity-report.json)'
-    }),
+				),
-    execute: async (args, { log, session, reportProgress }) => {
+			model: z
-      try {
+				.string()
-        log.info(`Analyzing task complexity with args: ${JSON.stringify(args)}`);
+				.optional()
-        // await reportProgress({ progress: 0 });
+				.describe(
+					'LLM model to use for analysis (defaults to configured model)'
+				),
+			threshold: z.coerce
+				.number()
+				.min(1)
+				.max(10)
+				.optional()
+				.describe(
+					'Minimum complexity score to recommend expansion (1-10) (default: 5)'
+				),
+			file: z
+				.string()
+				.optional()
+				.describe(
+					'Absolute path to the tasks file (default: tasks/tasks.json)'
+				),
+			research: z
+				.boolean()
+				.optional()
+				.describe('Use Perplexity AI for research-backed complexity analysis'),
+			projectRoot: z
+				.string()
+				.describe('The directory of the project. Must be an absolute path.')
+		}),
+		execute: async (args, { log, session }) => {
+			try {
+				log.info(
+					`Analyzing task complexity with args: ${JSON.stringify(args)}`
+				);
 
-        let rootFolder = getProjectRootFromSession(session, log);
+				// Get project root from args or session
+				const rootFolder =
+					args.projectRoot || getProjectRootFromSession(session, log);
 
-        if (!rootFolder && args.projectRoot) {
+				if (!rootFolder) {
-          rootFolder = args.projectRoot;
+					return createErrorResponse(
-          log.info(`Using project root from args as fallback: ${rootFolder}`);
+						'Could not determine project root. Please provide it explicitly or ensure your session contains valid root information.'
-        }
+					);
+				}
 
-        const result = await analyzeTaskComplexityDirect({
+				let tasksJsonPath;
-          projectRoot: rootFolder,
+				try {
-          ...args
+					tasksJsonPath = findTasksJsonPath(
-        }, log/*, { reportProgress, mcpLog: log, session}*/);
+						{ projectRoot: rootFolder, file: args.file },
+						log
+					);
+				} catch (error) {
+					log.error(`Error finding tasks.json: ${error.message}`);
+					return createErrorResponse(
+						`Failed to find tasks.json: ${error.message}`
+					);
+				}
 
-        // await reportProgress({ progress: 100 });
+				const outputPath = args.output
+					? path.resolve(rootFolder, args.output)
+					: path.resolve(rootFolder, 'scripts', 'task-complexity-report.json');
 
-        if (result.success) {
+				const result = await analyzeTaskComplexityDirect(
-          log.info(`Task complexity analysis complete: ${result.data.message}`);
+					{
-          log.info(`Report summary: ${JSON.stringify(result.data.reportSummary)}`);
+						tasksJsonPath: tasksJsonPath,
-        } else {
+						outputPath: outputPath,
-          log.error(`Failed to analyze task complexity: ${result.error.message}`);
+						model: args.model,
-        }
+						threshold: args.threshold,
+						research: args.research
+					},
+					log,
+					{ session }
+				);
 
-        return handleApiResult(result, log, 'Error analyzing task complexity');
+				if (result.success) {
-      } catch (error) {
+					log.info(`Task complexity analysis complete: ${result.data.message}`);
-        log.error(`Error in analyze tool: ${error.message}`);
+					log.info(
-        return createErrorResponse(error.message);
+						`Report summary: ${JSON.stringify(result.data.reportSummary)}`
-      }
+					);
-    },
+				} else {
-  });
+					log.error(
+						`Failed to analyze task complexity: ${result.error.message}`
+					);
+				}
+
+				return handleApiResult(result, log, 'Error analyzing task complexity');
+			} catch (error) {
+				log.error(`Error in analyze tool: ${error.message}`);
+				return createErrorResponse(error.message);
+			}
+		}
+	});
 }

mcp-server/src/tools/clear-subtasks.js

@@ -3,61 +3,96 @@
  * Tool for clearing subtasks from parent tasks
  */
 
-import { z } from "zod";
+import { z } from 'zod';
 import {
-  handleApiResult,
+	handleApiResult,
-  createErrorResponse,
+	createErrorResponse,
-  getProjectRootFromSession
+	getProjectRootFromSession
-} from "./utils.js";
+} from './utils.js';
-import { clearSubtasksDirect } from "../core/task-master-core.js";
+import { clearSubtasksDirect } from '../core/task-master-core.js';
+import { findTasksJsonPath } from '../core/utils/path-utils.js';
 
 /**
  * Register the clearSubtasks tool with the MCP server
  * @param {Object} server - FastMCP server instance
  */
 export function registerClearSubtasksTool(server) {
-  server.addTool({
+	server.addTool({
-    name: "clear_subtasks",
+		name: 'clear_subtasks',
-    description: "Clear subtasks from specified tasks",
+		description: 'Clear subtasks from specified tasks',
-    parameters: z.object({
+		parameters: z
-      id: z.string().optional().describe("Task IDs (comma-separated) to clear subtasks from"),
+			.object({
-      all: z.boolean().optional().describe("Clear subtasks from all tasks"),
+				id: z
-      file: z.string().optional().describe("Path to the tasks file (default: tasks/tasks.json)"),
+					.string()
-      projectRoot: z.string().optional().describe("Root directory of the project (default: current working directory)")
+					.optional()
-    }).refine(data => data.id || data.all, {
+					.describe('Task IDs (comma-separated) to clear subtasks from'),
-      message: "Either 'id' or 'all' parameter must be provided",
+				all: z.boolean().optional().describe('Clear subtasks from all tasks'),
-      path: ["id", "all"]
+				file: z
-    }),
+					.string()
-    execute: async (args, { log, session, reportProgress }) => {
+					.optional()
-      try {
+					.describe(
-        log.info(`Clearing subtasks with args: ${JSON.stringify(args)}`);
+						'Absolute path to the tasks file (default: tasks/tasks.json)'
-        await reportProgress({ progress: 0 });
+					),
+				projectRoot: z
+					.string()
+					.describe('The directory of the project. Must be an absolute path.')
+			})
+			.refine((data) => data.id || data.all, {
+				message: "Either 'id' or 'all' parameter must be provided",
+				path: ['id', 'all']
+			}),
+		execute: async (args, { log, session }) => {
+			try {
+				log.info(`Clearing subtasks with args: ${JSON.stringify(args)}`);
 
-        let rootFolder = getProjectRootFromSession(session, log);
+				// Get project root from args or session
+				const rootFolder =
+					args.projectRoot || getProjectRootFromSession(session, log);
 
-        if (!rootFolder && args.projectRoot) {
+				// Ensure project root was determined
-          rootFolder = args.projectRoot;
+				if (!rootFolder) {
-          log.info(`Using project root from args as fallback: ${rootFolder}`);
+					return createErrorResponse(
-        }
+						'Could not determine project root. Please provide it explicitly or ensure your session contains valid root information.'
+					);
+				}
 
-        const result = await clearSubtasksDirect({
+				// Resolve the path to tasks.json
-          projectRoot: rootFolder,
+				let tasksJsonPath;
-          ...args
+				try {
-        }, log, { reportProgress, mcpLog: log, session});
+					tasksJsonPath = findTasksJsonPath(
+						{ projectRoot: rootFolder, file: args.file },
+						log
+					);
+				} catch (error) {
+					log.error(`Error finding tasks.json: ${error.message}`);
+					return createErrorResponse(
+						`Failed to find tasks.json: ${error.message}`
+					);
+				}
 
-        reportProgress({ progress: 100 });
+				const result = await clearSubtasksDirect(
+					{
+						// Pass the explicitly resolved path
+						tasksJsonPath: tasksJsonPath,
+						// Pass other relevant args
+						id: args.id,
+						all: args.all
+					},
+					log
+					// Remove context object as clearSubtasksDirect likely doesn't need session/reportProgress
+				);
 
-        if (result.success) {
+				if (result.success) {
-          log.info(`Subtasks cleared successfully: ${result.data.message}`);
+					log.info(`Subtasks cleared successfully: ${result.data.message}`);
-        } else {
+				} else {
-          log.error(`Failed to clear subtasks: ${result.error.message}`);
+					log.error(`Failed to clear subtasks: ${result.error.message}`);
-        }
+				}
 
-        return handleApiResult(result, log, 'Error clearing subtasks');
+				return handleApiResult(result, log, 'Error clearing subtasks');
-      } catch (error) {
+			} catch (error) {
-        log.error(`Error in clearSubtasks tool: ${error.message}`);
+				log.error(`Error in clearSubtasks tool: ${error.message}`);
-        return createErrorResponse(error.message);
+				return createErrorResponse(error.message);
-      }
+			}
-    },
+		}
-  });
+	});
 }

mcp-server/src/tools/complexity-report.js

@@ -3,56 +3,87 @@
  * Tool for displaying the complexity analysis report
  */
 
-import { z } from "zod";
+import { z } from 'zod';
 import {
-  handleApiResult,
+	handleApiResult,
-  createErrorResponse,
+	createErrorResponse,
-  getProjectRootFromSession
+	getProjectRootFromSession
-} from "./utils.js";
+} from './utils.js';
-import { complexityReportDirect } from "../core/task-master-core.js";
+import { complexityReportDirect } from '../core/task-master-core.js';
+import path from 'path';
 
 /**
  * Register the complexityReport tool with the MCP server
  * @param {Object} server - FastMCP server instance
  */
 export function registerComplexityReportTool(server) {
-  server.addTool({
+	server.addTool({
-    name: "complexity_report",
+		name: 'complexity_report',
-    description: "Display the complexity analysis report in a readable format",
+		description: 'Display the complexity analysis report in a readable format',
-    parameters: z.object({
+		parameters: z.object({
-      file: z.string().optional().describe("Path to the report file (default: scripts/task-complexity-report.json)"),
+			file: z
-      projectRoot: z.string().optional().describe("Root directory of the project (default: current working directory)")
+				.string()
-    }),
+				.optional()
-    execute: async (args, { log, session, reportProgress }) => {
+				.describe(
-      try {
+					'Path to the report file (default: scripts/task-complexity-report.json)'
-        log.info(`Getting complexity report with args: ${JSON.stringify(args)}`);
+				),
-        // await reportProgress({ progress: 0 });
+			projectRoot: z
+				.string()
+				.describe('The directory of the project. Must be an absolute path.')
+		}),
+		execute: async (args, { log, session }) => {
+			try {
+				log.info(
+					`Getting complexity report with args: ${JSON.stringify(args)}`
+				);
 
-        let rootFolder = getProjectRootFromSession(session, log);
+				// Get project root from args or session
+				const rootFolder =
+					args.projectRoot || getProjectRootFromSession(session, log);
 
-        if (!rootFolder && args.projectRoot) {
+				// Ensure project root was determined
-          rootFolder = args.projectRoot;
+				if (!rootFolder) {
-          log.info(`Using project root from args as fallback: ${rootFolder}`);
+					return createErrorResponse(
-        }
+						'Could not determine project root. Please provide it explicitly or ensure your session contains valid root information.'
+					);
+				}
 
-        const result = await complexityReportDirect({
+				// Resolve the path to the complexity report file
-          projectRoot: rootFolder,
+				// Default to scripts/task-complexity-report.json relative to root
-          ...args
+				const reportPath = args.file
-        }, log/*, { reportProgress, mcpLog: log, session}*/);
+					? path.resolve(rootFolder, args.file)
+					: path.resolve(rootFolder, 'scripts', 'task-complexity-report.json');
 
-        // await reportProgress({ progress: 100 });
+				const result = await complexityReportDirect(
+					{
+						// Pass the explicitly resolved path
+						reportPath: reportPath
+						// No other args specific to this tool
+					},
+					log
+				);
 
-        if (result.success) {
+				if (result.success) {
-          log.info(`Successfully retrieved complexity report${result.fromCache ? ' (from cache)' : ''}`);
+					log.info(
-        } else {
+						`Successfully retrieved complexity report${result.fromCache ? ' (from cache)' : ''}`
-          log.error(`Failed to retrieve complexity report: ${result.error.message}`);
+					);
-        }
+				} else {
+					log.error(
+						`Failed to retrieve complexity report: ${result.error.message}`
+					);
+				}
 
-        return handleApiResult(result, log, 'Error retrieving complexity report');
+				return handleApiResult(
-      } catch (error) {
+					result,
-        log.error(`Error in complexity-report tool: ${error.message}`);
+					log,
-        return createErrorResponse(`Failed to retrieve complexity report: ${error.message}`);
+					'Error retrieving complexity report'
-      }
+				);
-    },
+			} catch (error) {
-  });
+				log.error(`Error in complexity-report tool: ${error.message}`);
+				return createErrorResponse(
+					`Failed to retrieve complexity report: ${error.message}`
+				);
+			}
+		}
+	});
 }

mcp-server/src/tools/expand-all.js

@@ -3,60 +3,110 @@
  * Tool for expanding all pending tasks with subtasks
  */
 
-import { z } from "zod";
+import { z } from 'zod';
 import {
-  handleApiResult,
+	handleApiResult,
-  createErrorResponse,
+	createErrorResponse,
-  getProjectRootFromSession
+	getProjectRootFromSession
-} from "./utils.js";
+} from './utils.js';
-import { expandAllTasksDirect } from "../core/task-master-core.js";
+import { expandAllTasksDirect } from '../core/task-master-core.js';
+import { findTasksJsonPath } from '../core/utils/path-utils.js';
 
 /**
  * Register the expandAll tool with the MCP server
  * @param {Object} server - FastMCP server instance
  */
 export function registerExpandAllTool(server) {
-  server.addTool({
+	server.addTool({
-    name: "expand_all",
+		name: 'expand_all',
-    description: "Expand all pending tasks into subtasks",
+		description: 'Expand all pending tasks into subtasks',
-    parameters: z.object({
+		parameters: z.object({
-      num: z.union([z.number(), z.string()]).optional().describe("Number of subtasks to generate for each task"),
+			num: z
-      research: z.boolean().optional().describe("Enable Perplexity AI for research-backed subtask generation"),
+				.string()
-      prompt: z.string().optional().describe("Additional context to guide subtask generation"),
+				.optional()
-      force: z.boolean().optional().describe("Force regeneration of subtasks for tasks that already have them"),
+				.describe('Number of subtasks to generate for each task'),
-      file: z.string().optional().describe("Path to the tasks file (default: tasks/tasks.json)"),
+			research: z
-      projectRoot: z.string().optional().describe("Root directory of the project (default: current working directory)")
+				.boolean()
-    }),
+				.optional()
-    execute: async (args, { log, session, reportProgress }) => {
+				.describe(
-      try {
+					'Enable Perplexity AI for research-backed subtask generation'
-        log.info(`Expanding all tasks with args: ${JSON.stringify(args)}`);
+				),
-        // await reportProgress({ progress: 0 });
+			prompt: z
+				.string()
+				.optional()
+				.describe('Additional context to guide subtask generation'),
+			force: z
+				.boolean()
+				.optional()
+				.describe(
+					'Force regeneration of subtasks for tasks that already have them'
+				),
+			file: z
+				.string()
+				.optional()
+				.describe(
+					'Absolute path to the tasks file (default: tasks/tasks.json)'
+				),
+			projectRoot: z
+				.string()
+				.describe('The directory of the project. Must be an absolute path.')
+		}),
+		execute: async (args, { log, session }) => {
+			try {
+				log.info(`Expanding all tasks with args: ${JSON.stringify(args)}`);
 
-        let rootFolder = getProjectRootFromSession(session, log);
+				// Get project root from args or session
+				const rootFolder =
+					args.projectRoot || getProjectRootFromSession(session, log);
 
-        if (!rootFolder && args.projectRoot) {
+				// Ensure project root was determined
-          rootFolder = args.projectRoot;
+				if (!rootFolder) {
-          log.info(`Using project root from args as fallback: ${rootFolder}`);
+					return createErrorResponse(
-        }
+						'Could not determine project root. Please provide it explicitly or ensure your session contains valid root information.'
+					);
+				}
 
-        const result = await expandAllTasksDirect({
+				// Resolve the path to tasks.json
-          projectRoot: rootFolder,
+				let tasksJsonPath;
-          ...args
+				try {
-        }, log/*, { reportProgress, mcpLog: log, session}*/);
+					tasksJsonPath = findTasksJsonPath(
+						{ projectRoot: rootFolder, file: args.file },
+						log
+					);
+				} catch (error) {
+					log.error(`Error finding tasks.json: ${error.message}`);
+					return createErrorResponse(
+						`Failed to find tasks.json: ${error.message}`
+					);
+				}
 
-        // await reportProgress({ progress: 100 });
+				const result = await expandAllTasksDirect(
+					{
+						// Pass the explicitly resolved path
+						tasksJsonPath: tasksJsonPath,
+						// Pass other relevant args
+						num: args.num,
+						research: args.research,
+						prompt: args.prompt,
+						force: args.force
+					},
+					log,
+					{ session }
+				);
 
-        if (result.success) {
+				if (result.success) {
-          log.info(`Successfully expanded all tasks: ${result.data.message}`);
+					log.info(`Successfully expanded all tasks: ${result.data.message}`);
-        } else {
+				} else {
-          log.error(`Failed to expand all tasks: ${result.error?.message || 'Unknown error'}`);
+					log.error(
-        }
+						`Failed to expand all tasks: ${result.error?.message || 'Unknown error'}`
+					);
+				}
 
-        return handleApiResult(result, log, 'Error expanding all tasks');
+				return handleApiResult(result, log, 'Error expanding all tasks');
-      } catch (error) {
+			} catch (error) {
-        log.error(`Error in expand-all tool: ${error.message}`);
+				log.error(`Error in expand-all tool: ${error.message}`);
-        return createErrorResponse(error.message);
+				return createErrorResponse(error.message);
-      }
+			}
-    },
+		}
-  });
+	});
 }

mcp-server/src/tools/expand-task.js

@@ -3,66 +3,96 @@
  * Tool to expand a task into subtasks
  */
 
-import { z } from "zod";
+import { z } from 'zod';
 import {
-  handleApiResult,
+	handleApiResult,
-  createErrorResponse,
+	createErrorResponse,
-  getProjectRootFromSession
+	getProjectRootFromSession
-} from "./utils.js";
+} from './utils.js';
-import { expandTaskDirect } from "../core/task-master-core.js";
+import { expandTaskDirect } from '../core/task-master-core.js';
+import { findTasksJsonPath } from '../core/utils/path-utils.js';
+import fs from 'fs';
+import path from 'path';
 
 /**
  * Register the expand-task tool with the MCP server
  * @param {Object} server - FastMCP server instance
  */
 export function registerExpandTaskTool(server) {
-  server.addTool({
+	server.addTool({
-    name: "expand_task",
+		name: 'expand_task',
-    description: "Expand a task into subtasks for detailed implementation",
+		description: 'Expand a task into subtasks for detailed implementation',
-    parameters: z.object({
+		parameters: z.object({
-      id: z.string().describe("ID of task to expand"),
+			id: z.string().describe('ID of task to expand'),
-      num: z.union([z.number(), z.string()]).optional().describe("Number of subtasks to generate"),
+			num: z.string().optional().describe('Number of subtasks to generate'),
-      research: z.boolean().optional().describe("Use Perplexity AI for research-backed generation"),
+			research: z
-      prompt: z.string().optional().describe("Additional context for subtask generation"),
+				.boolean()
-      force: z.boolean().optional().describe("Force regeneration even for tasks that already have subtasks"),
+				.optional()
-      file: z.string().optional().describe("Path to the tasks file"),
+				.describe('Use Perplexity AI for research-backed generation'),
-      projectRoot: z
+			prompt: z
-        .string()
+				.string()
-        .optional()
+				.optional()
-        .describe(
+				.describe('Additional context for subtask generation'),
-          "Root directory of the project (default: current working directory)"
+			file: z.string().optional().describe('Absolute path to the tasks file'),
-        ),
+			projectRoot: z
-    }),
+				.string()
-    execute: async (args, { log, session, reportProgress }) => {
+				.describe('The directory of the project. Must be an absolute path.'),
-      try {
+			force: z.boolean().optional().describe('Force the expansion')
-        log.info(`Expanding task with args: ${JSON.stringify(args)}`);
+		}),
-        // await reportProgress({ progress: 0 });
+		execute: async (args, { log, session }) => {
+			try {
+				log.info(`Starting expand-task with args: ${JSON.stringify(args)}`);
 
-        let rootFolder = getProjectRootFromSession(session, log);
+				// Get project root from args or session
+				const rootFolder =
+					args.projectRoot || getProjectRootFromSession(session, log);
 
-        if (!rootFolder && args.projectRoot) {
+				// Ensure project root was determined
-          rootFolder = args.projectRoot;
+				if (!rootFolder) {
-          log.info(`Using project root from args as fallback: ${rootFolder}`);
+					return createErrorResponse(
-        }
+						'Could not determine project root. Please provide it explicitly or ensure your session contains valid root information.'
+					);
+				}
 
-        const result = await expandTaskDirect({
+				log.info(`Project root resolved to: ${rootFolder}`);
-          projectRoot: rootFolder,
-          ...args
-        }, log/*, { reportProgress, mcpLog: log, session}*/);
 
-        // await reportProgress({ progress: 100 });
+				// Resolve the path to tasks.json using the utility
+				let tasksJsonPath;
+				try {
+					tasksJsonPath = findTasksJsonPath(
+						{ projectRoot: rootFolder, file: args.file },
+						log
+					);
+				} catch (error) {
+					log.error(`Error finding tasks.json: ${error.message}`);
+					return createErrorResponse(
+						`Failed to find tasks.json: ${error.message}`
+					);
+				}
 
-        if (result.success) {
+				// Call direct function with only session in the context, not reportProgress
-          log.info(`Successfully expanded task with ID ${args.id}`);
+				// Use the pattern recommended in the MCP guidelines
-        } else {
+				const result = await expandTaskDirect(
-          log.error(`Failed to expand task: ${result.error?.message || 'Unknown error'}`);
+					{
-        }
+						// Pass the explicitly resolved path
+						tasksJsonPath: tasksJsonPath,
+						// Pass other relevant args
+						id: args.id,
+						num: args.num,
+						research: args.research,
+						prompt: args.prompt,
+						force: args.force // Need to add force to parameters
+					},
+					log,
+					{ session }
+				); // Only pass session, NOT reportProgress
 
-        return handleApiResult(result, log, 'Error expanding task');
+				// Return the result
-      } catch (error) {
+				return handleApiResult(result, log, 'Error expanding task');
-        log.error(`Error in expand task tool: ${error.message}`);
+			} catch (error) {
-        return createErrorResponse(error.message);
+				log.error(`Error in expand task tool: ${error.message}`);
-      }
+				return createErrorResponse(error.message);
-    },
+			}
-  });
+		}
+	});
 }

mcp-server/src/tools/fix-dependencies.js

@@ -3,56 +3,74 @@
  * Tool for automatically fixing invalid task dependencies
  */
 
-import { z } from "zod";
+import { z } from 'zod';
 import {
-  handleApiResult,
+	handleApiResult,
-  createErrorResponse,
+	createErrorResponse,
-  getProjectRootFromSession
+	getProjectRootFromSession
-} from "./utils.js";
+} from './utils.js';
-import { fixDependenciesDirect } from "../core/task-master-core.js";
+import { fixDependenciesDirect } from '../core/task-master-core.js';
+import { findTasksJsonPath } from '../core/utils/path-utils.js';
 
 /**
  * Register the fixDependencies tool with the MCP server
  * @param {Object} server - FastMCP server instance
  */
 export function registerFixDependenciesTool(server) {
-  server.addTool({
+	server.addTool({
-    name: "fix_dependencies",
+		name: 'fix_dependencies',
-    description: "Fix invalid dependencies in tasks automatically",
+		description: 'Fix invalid dependencies in tasks automatically',
-    parameters: z.object({
+		parameters: z.object({
-      file: z.string().optional().describe("Path to the tasks file"),
+			file: z.string().optional().describe('Absolute path to the tasks file'),
-      projectRoot: z.string().optional().describe("Root directory of the project (default: current working directory)")
+			projectRoot: z
-    }),
+				.string()
-    execute: async (args, { log, session, reportProgress }) => {
+				.describe('The directory of the project. Must be an absolute path.')
-      try {
+		}),
-        log.info(`Fixing dependencies with args: ${JSON.stringify(args)}`);
+		execute: async (args, { log, session }) => {
-        await reportProgress({ progress: 0 });
+			try {
+				log.info(`Fixing dependencies with args: ${JSON.stringify(args)}`);
 
-        let rootFolder = getProjectRootFromSession(session, log);
+				// Get project root from args or session
+				const rootFolder =
+					args.projectRoot || getProjectRootFromSession(session, log);
 
-        if (!rootFolder && args.projectRoot) {
+				if (!rootFolder) {
-          rootFolder = args.projectRoot;
+					return createErrorResponse(
-          log.info(`Using project root from args as fallback: ${rootFolder}`);
+						'Could not determine project root. Please provide it explicitly or ensure your session contains valid root information.'
-        }
+					);
+				}
 
-        const result = await fixDependenciesDirect({
+				let tasksJsonPath;
-          projectRoot: rootFolder,
+				try {
-          ...args
+					tasksJsonPath = findTasksJsonPath(
-        }, log, { reportProgress, mcpLog: log, session});
+						{ projectRoot: rootFolder, file: args.file },
+						log
+					);
+				} catch (error) {
+					log.error(`Error finding tasks.json: ${error.message}`);
+					return createErrorResponse(
+						`Failed to find tasks.json: ${error.message}`
+					);
+				}
 
-        await reportProgress({ progress: 100 });
+				const result = await fixDependenciesDirect(
+					{
+						tasksJsonPath: tasksJsonPath
+					},
+					log
+				);
 
-        if (result.success) {
+				if (result.success) {
-          log.info(`Successfully fixed dependencies: ${result.data.message}`);
+					log.info(`Successfully fixed dependencies: ${result.data.message}`);
-        } else {
+				} else {
-          log.error(`Failed to fix dependencies: ${result.error.message}`);
+					log.error(`Failed to fix dependencies: ${result.error.message}`);
-        }
+				}
 
-        return handleApiResult(result, log, 'Error fixing dependencies');
+				return handleApiResult(result, log, 'Error fixing dependencies');
-      } catch (error) {
+			} catch (error) {
-        log.error(`Error in fixDependencies tool: ${error.message}`);
+				log.error(`Error in fixDependencies tool: ${error.message}`);
-        return createErrorResponse(error.message);
+				return createErrorResponse(error.message);
-      }
+			}
-    }
+		}
-  });
+	});
 }

mcp-server/src/tools/generate.js

@@ -3,62 +3,92 @@
  * Tool to generate individual task files from tasks.json
  */
 
-import { z } from "zod";
+import { z } from 'zod';
 import {
-  handleApiResult,
+	handleApiResult,
-  createErrorResponse,
+	createErrorResponse,
-  getProjectRootFromSession
+	getProjectRootFromSession
-} from "./utils.js";
+} from './utils.js';
-import { generateTaskFilesDirect } from "../core/task-master-core.js";
+import { generateTaskFilesDirect } from '../core/task-master-core.js';
+import { findTasksJsonPath } from '../core/utils/path-utils.js';
+import path from 'path';
 
 /**
  * Register the generate tool with the MCP server
  * @param {Object} server - FastMCP server instance
  */
 export function registerGenerateTool(server) {
-  server.addTool({
+	server.addTool({
-    name: "generate",
+		name: 'generate',
-    description: "Generates individual task files in tasks/ directory based on tasks.json",
+		description:
-    parameters: z.object({
+			'Generates individual task files in tasks/ directory based on tasks.json',
-      file: z.string().optional().describe("Path to the tasks file"),
+		parameters: z.object({
-      output: z.string().optional().describe("Output directory (default: same directory as tasks file)"),
+			file: z.string().optional().describe('Absolute path to the tasks file'),
-      projectRoot: z
+			output: z
-        .string()
+				.string()
-        .optional()
+				.optional()
-        .describe(
+				.describe('Output directory (default: same directory as tasks file)'),
-          "Root directory of the project (default: current working directory)"
+			projectRoot: z
-        ),
+				.string()
-    }),
+				.describe('The directory of the project. Must be an absolute path.')
-    execute: async (args, { log, session, reportProgress }) => {
+		}),
-      try {
+		execute: async (args, { log, session }) => {
-        log.info(`Generating task files with args: ${JSON.stringify(args)}`);
+			try {
-        // await reportProgress({ progress: 0 });
+				log.info(`Generating task files with args: ${JSON.stringify(args)}`);
 
-        let rootFolder = getProjectRootFromSession(session, log);
+				// Get project root from args or session
+				const rootFolder =
+					args.projectRoot || getProjectRootFromSession(session, log);
 
-        if (!rootFolder && args.projectRoot) {
+				// Ensure project root was determined
-          rootFolder = args.projectRoot;
+				if (!rootFolder) {
-          log.info(`Using project root from args as fallback: ${rootFolder}`);
+					return createErrorResponse(
-        }
+						'Could not determine project root. Please provide it explicitly or ensure your session contains valid root information.'
+					);
+				}
 
-        const result = await generateTaskFilesDirect({
+				// Resolve the path to tasks.json
-          projectRoot: rootFolder,
+				let tasksJsonPath;
-          ...args
+				try {
-        }, log/*, { reportProgress, mcpLog: log, session}*/);
+					tasksJsonPath = findTasksJsonPath(
+						{ projectRoot: rootFolder, file: args.file },
+						log
+					);
+				} catch (error) {
+					log.error(`Error finding tasks.json: ${error.message}`);
+					return createErrorResponse(
+						`Failed to find tasks.json: ${error.message}`
+					);
+				}
 
-        // await reportProgress({ progress: 100 });
+				// Determine output directory: use explicit arg or default to tasks.json directory
+				const outputDir = args.output
+					? path.resolve(rootFolder, args.output) // Resolve relative to root if needed
+					: path.dirname(tasksJsonPath);
 
-        if (result.success) {
+				const result = await generateTaskFilesDirect(
-          log.info(`Successfully generated task files: ${result.data.message}`);
+					{
-        } else {
+						// Pass the explicitly resolved paths
-          log.error(`Failed to generate task files: ${result.error?.message || 'Unknown error'}`);
+						tasksJsonPath: tasksJsonPath,
-        }
+						outputDir: outputDir
+						// No other args specific to this tool
+					},
+					log
+				);
 
-        return handleApiResult(result, log, 'Error generating task files');
+				if (result.success) {
-      } catch (error) {
+					log.info(`Successfully generated task files: ${result.data.message}`);
-        log.error(`Error in generate tool: ${error.message}`);
+				} else {
-        return createErrorResponse(error.message);
+					log.error(
-      }
+						`Failed to generate task files: ${result.error?.message || 'Unknown error'}`
-    },
+					);
-  });
+				}
+
+				return handleApiResult(result, log, 'Error generating task files');
+			} catch (error) {
+				log.error(`Error in generate tool: ${error.message}`);
+				return createErrorResponse(error.message);
+			}
+		}
+	});
 }

mcp-server/src/tools/get-operation-status.js

@@ -8,35 +8,40 @@ import { createErrorResponse, createContentResponse } from './utils.js'; // Assu
  * @param {AsyncOperationManager} asyncManager - The async operation manager.
  */
 export function registerGetOperationStatusTool(server, asyncManager) {
-    server.addTool({
+	server.addTool({
-        name: 'get_operation_status',
+		name: 'get_operation_status',
-        description: 'Retrieves the status and result/error of a background operation.',
+		description:
-        parameters: z.object({
+			'Retrieves the status and result/error of a background operation.',
-            operationId: z.string().describe('The ID of the operation to check.'),
+		parameters: z.object({
-        }),
+			operationId: z.string().describe('The ID of the operation to check.')
-        execute: async (args, { log }) => {
+		}),
-            try {
+		execute: async (args, { log }) => {
-                const { operationId } = args;
+			try {
-                log.info(`Checking status for operation ID: ${operationId}`);
+				const { operationId } = args;
+				log.info(`Checking status for operation ID: ${operationId}`);
 
-                const status = asyncManager.getStatus(operationId);
+				const status = asyncManager.getStatus(operationId);
 
-                // Status will now always return an object, but it might have status='not_found'
+				// Status will now always return an object, but it might have status='not_found'
-                if (status.status === 'not_found') {
+				if (status.status === 'not_found') {
-                    log.warn(`Operation ID not found: ${operationId}`);
+					log.warn(`Operation ID not found: ${operationId}`);
-                    return createErrorResponse(
+					return createErrorResponse(
-                        status.error?.message || `Operation ID not found: ${operationId}`, 
+						status.error?.message || `Operation ID not found: ${operationId}`,
-                        status.error?.code || 'OPERATION_NOT_FOUND'
+						status.error?.code || 'OPERATION_NOT_FOUND'
-                    );
+					);
-                }
+				}
 
-                log.info(`Status for ${operationId}: ${status.status}`);
+				log.info(`Status for ${operationId}: ${status.status}`);
-                return createContentResponse(status);
+				return createContentResponse(status);
-
+			} catch (error) {
-            } catch (error) {
+				log.error(`Error in get_operation_status tool: ${error.message}`, {
-                log.error(`Error in get_operation_status tool: ${error.message}`, { stack: error.stack });
+					stack: error.stack
-                return createErrorResponse(`Failed to get operation status: ${error.message}`, 'GET_STATUS_ERROR');
+				});
-            }
+				return createErrorResponse(
-        },
+					`Failed to get operation status: ${error.message}`,
-    });
+					'GET_STATUS_ERROR'
+				);
+			}
+		}
+	});
 }

mcp-server/src/tools/get-task.js

@@ -3,13 +3,14 @@
  * Tool to get task details by ID
  */
 
-import { z } from "zod";
+import { z } from 'zod';
 import {
-  handleApiResult,
+	handleApiResult,
-  createErrorResponse,
+	createErrorResponse,
-  getProjectRootFromSession
+	getProjectRootFromSession
-} from "./utils.js";
+} from './utils.js';
-import { showTaskDirect } from "../core/task-master-core.js";
+import { showTaskDirect } from '../core/task-master-core.js';
+import { findTasksJsonPath } from '../core/utils/path-utils.js';
 
 /**
  * Custom processor function that removes allTasks from the response
@@ -17,16 +18,16 @@ import { showTaskDirect } from "../core/task-master-core.js";
  * @returns {Object} - The processed data with allTasks removed
  */
 function processTaskResponse(data) {
-  if (!data) return data;
+	if (!data) return data;
 
-  // If we have the expected structure with task and allTasks
+	// If we have the expected structure with task and allTasks
-  if (data.task) {
+	if (data.task) {
-    // Return only the task object, removing the allTasks array
+		// Return only the task object, removing the allTasks array
-    return data.task;
+		return data.task;
-  }
+	}
 
-  // If structure is unexpected, return as is
+	// If structure is unexpected, return as is
-  return data;
+	return data;
 }
 
 /**
@@ -34,59 +35,89 @@ function processTaskResponse(data) {
  * @param {Object} server - FastMCP server instance
  */
 export function registerShowTaskTool(server) {
-  server.addTool({
+	server.addTool({
-    name: "get_task",
+		name: 'get_task',
-    description: "Get detailed information about a specific task",
+		description: 'Get detailed information about a specific task',
-    parameters: z.object({
+		parameters: z.object({
-      id: z.string().describe("Task ID to get"),
+			id: z.string().describe('Task ID to get'),
-      file: z.string().optional().describe("Path to the tasks file"),
+			file: z.string().optional().describe('Absolute path to the tasks file'),
-      projectRoot: z
+			projectRoot: z
-        .string()
+				.string()
-        .optional()
+				.describe('The directory of the project. Must be an absolute path.')
-        .describe(
+		}),
-          "Root directory of the project (default: current working directory)"
+		execute: async (args, { log, session }) => {
-        ),
+			// Log the session right at the start of execute
-    }),
+			log.info(
-    execute: async (args, { log, session, reportProgress }) => {
+				`Session object received in execute: ${JSON.stringify(session)}`
-      // Log the session right at the start of execute
+			); // Use JSON.stringify for better visibility
-      log.info(`Session object received in execute: ${JSON.stringify(session)}`); // Use JSON.stringify for better visibility
 
-      try {
+			try {
-        log.info(`Getting task details for ID: ${args.id}`);
+				log.info(`Getting task details for ID: ${args.id}`);
 
-        log.info(`Session object received in execute: ${JSON.stringify(session)}`); // Use JSON.stringify for better visibility
+				log.info(
+					`Session object received in execute: ${JSON.stringify(session)}`
+				); // Use JSON.stringify for better visibility
 
-        let rootFolder = getProjectRootFromSession(session, log);
+				// Get project root from args or session
+				const rootFolder =
+					args.projectRoot || getProjectRootFromSession(session, log);
 
-        if (!rootFolder && args.projectRoot) {
+				// Ensure project root was determined
-          rootFolder = args.projectRoot;
+				if (!rootFolder) {
-          log.info(`Using project root from args as fallback: ${rootFolder}`);
+					return createErrorResponse(
-        } else if (!rootFolder) {
+						'Could not determine project root. Please provide it explicitly or ensure your session contains valid root information.'
-          // Ensure we always have *some* root, even if session failed and args didn't provide one
+					);
-          rootFolder = process.cwd();
+				}
-          log.warn(`Session and args failed to provide root, using CWD: ${rootFolder}`);
-        }
 
-        log.info(`Attempting to use project root: ${rootFolder}`); // Log the final resolved root
+				log.info(`Attempting to use project root: ${rootFolder}`); // Log the final resolved root
 
-        log.info(`Root folder: ${rootFolder}`); // Log the final resolved root
+				log.info(`Root folder: ${rootFolder}`); // Log the final resolved root
-        const result = await showTaskDirect({
-          projectRoot: rootFolder,
-          ...args
-        }, log);
 
-        if (result.success) {
+				// Resolve the path to tasks.json
-          log.info(`Successfully retrieved task details for ID: ${args.id}${result.fromCache ? ' (from cache)' : ''}`);
+				let tasksJsonPath;
-        } else {
+				try {
-          log.error(`Failed to get task: ${result.error.message}`);
+					tasksJsonPath = findTasksJsonPath(
-        }
+						{ projectRoot: rootFolder, file: args.file },
+						log
+					);
+				} catch (error) {
+					log.error(`Error finding tasks.json: ${error.message}`);
+					return createErrorResponse(
+						`Failed to find tasks.json: ${error.message}`
+					);
+				}
 
-        // Use our custom processor function to remove allTasks from the response
+				log.info(`Attempting to use tasks file path: ${tasksJsonPath}`);
-        return handleApiResult(result, log, 'Error retrieving task details', processTaskResponse);
+
-      } catch (error) {
+				const result = await showTaskDirect(
-        log.error(`Error in get-task tool: ${error.message}\n${error.stack}`); // Add stack trace
+					{
-        return createErrorResponse(`Failed to get task: ${error.message}`);
+						// Pass the explicitly resolved path
-      }
+						tasksJsonPath: tasksJsonPath,
-    },
+						// Pass other relevant args
-  });
+						id: args.id
+					},
+					log
+				);
+
+				if (result.success) {
+					log.info(
+						`Successfully retrieved task details for ID: ${args.id}${result.fromCache ? ' (from cache)' : ''}`
+					);
+				} else {
+					log.error(`Failed to get task: ${result.error.message}`);
+				}
+
+				// Use our custom processor function to remove allTasks from the response
+				return handleApiResult(
+					result,
+					log,
+					'Error retrieving task details',
+					processTaskResponse
+				);
+			} catch (error) {
+				log.error(`Error in get-task tool: ${error.message}\n${error.stack}`); // Add stack trace
+				return createErrorResponse(`Failed to get task: ${error.message}`);
+			}
+		}
+	});
 }

mcp-server/src/tools/get-tasks.js

@@ -3,63 +3,94 @@
  * Tool to get all tasks from Task Master
  */
 
-import { z } from "zod";
+import { z } from 'zod';
 import {
-  createErrorResponse,
+	createErrorResponse,
-  handleApiResult,
+	handleApiResult,
-  getProjectRootFromSession
+	getProjectRootFromSession
-} from "./utils.js";
+} from './utils.js';
-import { listTasksDirect } from "../core/task-master-core.js";
+import { listTasksDirect } from '../core/task-master-core.js';
+import { findTasksJsonPath } from '../core/utils/path-utils.js';
 
 /**
  * Register the getTasks tool with the MCP server
  * @param {Object} server - FastMCP server instance
  */
 export function registerListTasksTool(server) {
-  server.addTool({
+	server.addTool({
-    name: "get_tasks",
+		name: 'get_tasks',
-    description: "Get all tasks from Task Master, optionally filtering by status and including subtasks.",
+		description:
-    parameters: z.object({
+			'Get all tasks from Task Master, optionally filtering by status and including subtasks.',
-      status: z.string().optional().describe("Filter tasks by status (e.g., 'pending', 'done')"),
+		parameters: z.object({
-      withSubtasks: z
+			status: z
-        .boolean()
+				.string()
-        .optional()
+				.optional()
-        .describe("Include subtasks nested within their parent tasks in the response"),
+				.describe("Filter tasks by status (e.g., 'pending', 'done')"),
-      file: z.string().optional().describe("Path to the tasks file (relative to project root or absolute)"),
+			withSubtasks: z
-      projectRoot: z
+				.boolean()
-        .string()
+				.optional()
-        .optional()
+				.describe(
-        .describe(
+					'Include subtasks nested within their parent tasks in the response'
-          "Root directory of the project (default: automatically detected from session or CWD)"
+				),
-        ),
+			file: z
-    }),
+				.string()
-    execute: async (args, { log, session, reportProgress }) => {
+				.optional()
-      try {
+				.describe(
-        log.info(`Getting tasks with filters: ${JSON.stringify(args)}`);
+					'Path to the tasks file (relative to project root or absolute)'
-        // await reportProgress({ progress: 0 });
+				),
+			projectRoot: z
+				.string()
+				.describe('The directory of the project. Must be an absolute path.')
+		}),
+		execute: async (args, { log, session }) => {
+			try {
+				log.info(`Getting tasks with filters: ${JSON.stringify(args)}`);
 
-        let rootFolder = getProjectRootFromSession(session, log);
+				// Get project root from args or session
+				const rootFolder =
+					args.projectRoot || getProjectRootFromSession(session, log);
 
-        if (!rootFolder && args.projectRoot) {
+				// Ensure project root was determined
-          rootFolder = args.projectRoot;
+				if (!rootFolder) {
-          log.info(`Using project root from args as fallback: ${rootFolder}`);
+					return createErrorResponse(
-        }
+						'Could not determine project root. Please provide it explicitly or ensure your session contains valid root information.'
+					);
+				}
 
-        const result = await listTasksDirect({
+				// Resolve the path to tasks.json
-          projectRoot: rootFolder,
+				let tasksJsonPath;
-          ...args
+				try {
-        }, log/*, { reportProgress, mcpLog: log, session}*/);
+					tasksJsonPath = findTasksJsonPath(
+						{ projectRoot: rootFolder, file: args.file },
+						log
+					);
+				} catch (error) {
+					log.error(`Error finding tasks.json: ${error.message}`);
+					// Use the error message from findTasksJsonPath for better context
+					return createErrorResponse(
+						`Failed to find tasks.json: ${error.message}`
+					);
+				}
 
-        // await reportProgress({ progress: 100 });
+				const result = await listTasksDirect(
+					{
+						tasksJsonPath: tasksJsonPath,
+						status: args.status,
+						withSubtasks: args.withSubtasks
+					},
+					log
+				);
 
-        log.info(`Retrieved ${result.success ? (result.data?.tasks?.length || 0) : 0} tasks${result.fromCache ? ' (from cache)' : ''}`);
+				log.info(
-        return handleApiResult(result, log, 'Error getting tasks');
+					`Retrieved ${result.success ? result.data?.tasks?.length || 0 : 0} tasks${result.fromCache ? ' (from cache)' : ''}`
-      } catch (error) {
+				);
-        log.error(`Error getting tasks: ${error.message}`);
+				return handleApiResult(result, log, 'Error getting tasks');
-        return createErrorResponse(error.message);
+			} catch (error) {
-      }
+				log.error(`Error getting tasks: ${error.message}`);
-    },
+				return createErrorResponse(error.message);
-  });
+			}
+		}
+	});
 }
 
 // We no longer need the formatTasksResponse function as we're returning raw JSON data

mcp-server/src/tools/index.js

@@ -3,32 +3,31 @@
  * Export all Task Master CLI tools for MCP server
  */
 
-import { registerListTasksTool } from "./get-tasks.js";
+import { registerListTasksTool } from './get-tasks.js';
-import logger from "../logger.js";
+import logger from '../logger.js';
-import { registerSetTaskStatusTool } from "./set-task-status.js";
+import { registerSetTaskStatusTool } from './set-task-status.js';
-import { registerParsePRDTool } from "./parse-prd.js";
+import { registerParsePRDTool } from './parse-prd.js';
-import { registerUpdateTool } from "./update.js";
+import { registerUpdateTool } from './update.js';
-import { registerUpdateTaskTool } from "./update-task.js";
+import { registerUpdateTaskTool } from './update-task.js';
-import { registerUpdateSubtaskTool } from "./update-subtask.js";
+import { registerUpdateSubtaskTool } from './update-subtask.js';
-import { registerGenerateTool } from "./generate.js";
+import { registerGenerateTool } from './generate.js';
-import { registerShowTaskTool } from "./get-task.js";
+import { registerShowTaskTool } from './get-task.js';
-import { registerNextTaskTool } from "./next-task.js";
+import { registerNextTaskTool } from './next-task.js';
-import { registerExpandTaskTool } from "./expand-task.js";
+import { registerExpandTaskTool } from './expand-task.js';
-import { registerAddTaskTool } from "./add-task.js";
+import { registerAddTaskTool } from './add-task.js';
-import { registerAddSubtaskTool } from "./add-subtask.js";
+import { registerAddSubtaskTool } from './add-subtask.js';
-import { registerRemoveSubtaskTool } from "./remove-subtask.js";
+import { registerRemoveSubtaskTool } from './remove-subtask.js';
-import { registerAnalyzeTool } from "./analyze.js";
+import { registerAnalyzeTool } from './analyze.js';
-import { registerClearSubtasksTool } from "./clear-subtasks.js";
+import { registerClearSubtasksTool } from './clear-subtasks.js';
-import { registerExpandAllTool } from "./expand-all.js";
+import { registerExpandAllTool } from './expand-all.js';
-import { registerRemoveDependencyTool } from "./remove-dependency.js";
+import { registerRemoveDependencyTool } from './remove-dependency.js';
-import { registerValidateDependenciesTool } from "./validate-dependencies.js";
+import { registerValidateDependenciesTool } from './validate-dependencies.js';
-import { registerFixDependenciesTool } from "./fix-dependencies.js";
+import { registerFixDependenciesTool } from './fix-dependencies.js';
-import { registerComplexityReportTool } from "./complexity-report.js";
+import { registerComplexityReportTool } from './complexity-report.js';
-import { registerAddDependencyTool } from "./add-dependency.js";
+import { registerAddDependencyTool } from './add-dependency.js';
 import { registerRemoveTaskTool } from './remove-task.js';
 import { registerInitializeProjectTool } from './initialize-project.js';
 import { asyncOperationManager } from '../core/utils/async-manager.js';
-import { registerGetOperationStatusTool } from './get-operation-status.js';
 
 /**
  * Register all Task Master tools with the MCP server
@@ -36,40 +35,37 @@ import { registerGetOperationStatusTool } from './get-operation-status.js';
  * @param {asyncOperationManager} asyncManager - The async operation manager instance
  */
 export function registerTaskMasterTools(server, asyncManager) {
-  try {
+	try {
-    // Register each tool
+		// Register each tool
-    registerListTasksTool(server);
+		registerListTasksTool(server);
-    registerSetTaskStatusTool(server);
+		registerSetTaskStatusTool(server);
-    registerParsePRDTool(server);
+		registerParsePRDTool(server);
-    registerUpdateTool(server);
+		registerUpdateTool(server);
-    registerUpdateTaskTool(server);
+		registerUpdateTaskTool(server);
-    registerUpdateSubtaskTool(server);
+		registerUpdateSubtaskTool(server);
-    registerGenerateTool(server);
+		registerGenerateTool(server);
-    registerShowTaskTool(server);
+		registerShowTaskTool(server);
-    registerNextTaskTool(server);
+		registerNextTaskTool(server);
-    registerExpandTaskTool(server);
+		registerExpandTaskTool(server);
-    registerAddTaskTool(server, asyncManager);
+		registerAddTaskTool(server, asyncManager);
-    registerAddSubtaskTool(server);
+		registerAddSubtaskTool(server);
-    registerRemoveSubtaskTool(server);
+		registerRemoveSubtaskTool(server);
-    registerAnalyzeTool(server);
+		registerAnalyzeTool(server);
-    registerClearSubtasksTool(server);
+		registerClearSubtasksTool(server);
-    registerExpandAllTool(server);
+		registerExpandAllTool(server);
-    registerRemoveDependencyTool(server);
+		registerRemoveDependencyTool(server);
-    registerValidateDependenciesTool(server);
+		registerValidateDependenciesTool(server);
-    registerFixDependenciesTool(server);
+		registerFixDependenciesTool(server);
-    registerComplexityReportTool(server);
+		registerComplexityReportTool(server);
-    registerAddDependencyTool(server);
+		registerAddDependencyTool(server);
-    registerRemoveTaskTool(server);
+		registerRemoveTaskTool(server);
-    registerInitializeProjectTool(server);
+		registerInitializeProjectTool(server);
-    registerGetOperationStatusTool(server, asyncManager);
+	} catch (error) {
-  } catch (error) {
+		logger.error(`Error registering Task Master tools: ${error.message}`);
-    logger.error(`Error registering Task Master tools: ${error.message}`);
+		throw error;
-    throw error;
+	}
-  }
-
-  logger.info('Registered Task Master MCP tools');
 }
 
 export default {
-  registerTaskMasterTools,
+	registerTaskMasterTools
 };

mcp-server/src/tools/initialize-project.js

@@ -1,62 +1,94 @@
-import { z } from "zod";
+import { z } from 'zod';
-import { execSync } from 'child_process';
+import {
-import { createContentResponse, createErrorResponse } from "./utils.js"; // Only need response creators
+	createContentResponse,
+	createErrorResponse,
+	handleApiResult
+} from './utils.js';
+import { initializeProjectDirect } from '../core/task-master-core.js';
 
 export function registerInitializeProjectTool(server) {
-  server.addTool({
+	server.addTool({
-    name: "initialize_project", // snake_case for tool name
+		name: 'initialize_project',
-    description: "Initializes a new Task Master project structure in the current working directory by running 'task-master init'.",
+		description:
-    parameters: z.object({
+			"Initializes a new Task Master project structure by calling the core initialization logic. Derives target directory from client session. If project details (name, description, author) are not provided, prompts the user or skips if 'yes' flag is true. DO NOT run without parameters.",
-      projectName: z.string().optional().describe("The name for the new project."),
+		parameters: z.object({
-      projectDescription: z.string().optional().describe("A brief description for the project."),
+			projectName: z
-      projectVersion: z.string().optional().describe("The initial version for the project (e.g., '0.1.0')."),
+				.string()
-      authorName: z.string().optional().describe("The author's name."),
+				.optional()
-      skipInstall: z.boolean().optional().default(false).describe("Skip installing dependencies automatically."),
+				.describe(
-      addAliases: z.boolean().optional().default(false).describe("Add shell aliases (tm, taskmaster) to shell config file."),
+					'The name for the new project. If not provided, prompt the user for it.'
-      yes: z.boolean().optional().default(false).describe("Skip prompts and use default values or provided arguments."),
+				),
-      // projectRoot is not needed here as 'init' works on the current directory
+			projectDescription: z
-    }),
+				.string()
-    execute: async (args, { log }) => { // Destructure context to get log
+				.optional()
-      try {
+				.describe(
-        log.info(`Executing initialize_project with args: ${JSON.stringify(args)}`);
+					'A brief description for the project. If not provided, prompt the user for it.'
+				),
+			projectVersion: z
+				.string()
+				.optional()
+				.describe(
+					"The initial version for the project (e.g., '0.1.0'). User input not needed unless user requests to override."
+				),
+			authorName: z
+				.string()
+				.optional()
+				.describe(
+					"The author's name. User input not needed unless user requests to override."
+				),
+			skipInstall: z
+				.boolean()
+				.optional()
+				.default(false)
+				.describe(
+					'Skip installing dependencies automatically. Never do this unless you are sure the project is already installed.'
+				),
+			addAliases: z
+				.boolean()
+				.optional()
+				.default(false)
+				.describe(
+					'Add shell aliases (tm, taskmaster) to shell config file. User input not needed.'
+				),
+			yes: z
+				.boolean()
+				.optional()
+				.default(false)
+				.describe(
+					"Skip prompts and use default values or provided arguments. Use true if you wish to skip details like the project name, etc. If the project information required for the initialization is not available or provided by the user, prompt if the user wishes to provide them (name, description, author) or skip them. If the user wishes to skip, set the 'yes' flag to true and do not set any other parameters."
+				),
+			projectRoot: z
+				.string()
+				.describe(
+					'The root directory for the project. ALWAYS SET THIS TO THE PROJECT ROOT DIRECTORY. IF NOT SET, THE TOOL WILL NOT WORK.'
+				)
+		}),
+		execute: async (args, context) => {
+			const { log } = context;
+			const session = context.session;
 
-        // Construct the command arguments carefully
+			log.info(
-        // Using npx ensures it uses the locally installed version if available, or fetches it
+				'>>> Full Context Received by Tool:',
-        let command = 'npx task-master init';
+				JSON.stringify(context, null, 2)
-        const cliArgs = [];
+			);
-        if (args.projectName) cliArgs.push(`--name "${args.projectName.replace(/"/g, '\\"')}"`); // Escape quotes
+			log.info(`Context received in tool function: ${context}`);
-        if (args.projectDescription) cliArgs.push(`--description "${args.projectDescription.replace(/"/g, '\\"')}"`);
+			log.info(
-        if (args.projectVersion) cliArgs.push(`--version "${args.projectVersion.replace(/"/g, '\\"')}"`);
+				`Session received in tool function: ${session ? session : 'undefined'}`
-        if (args.authorName) cliArgs.push(`--author "${args.authorName.replace(/"/g, '\\"')}"`);
+			);
-        if (args.skipInstall) cliArgs.push('--skip-install');
-        if (args.addAliases) cliArgs.push('--aliases');
-        if (args.yes) cliArgs.push('--yes');
 
-        command += ' ' + cliArgs.join(' ');
+			try {
+				log.info(
+					`Executing initialize_project tool with args: ${JSON.stringify(args)}`
+				);
 
-        log.info(`Constructed command: ${command}`);
+				const result = await initializeProjectDirect(args, log, { session });
 
-        // Execute the command in the current working directory of the server process
+				return handleApiResult(result, log, 'Initialization failed');
-        // Capture stdout/stderr. Use a reasonable timeout (e.g., 5 minutes)
+			} catch (error) {
-        const output = execSync(command, { encoding: 'utf8', stdio: 'pipe', timeout: 300000 });
+				const errorMessage = `Project initialization tool failed: ${error.message || 'Unknown error'}`;
-
+				log.error(errorMessage, error);
-        log.info(`Initialization output:\n${output}`);
+				return createErrorResponse(errorMessage, { details: error.stack });
-
+			}
-        // Return a standard success response manually
+		}
-        return createContentResponse(
+	});
-             "Project initialized successfully.",
-             { output: output } // Include output in the data payload
-        );
-
-      } catch (error) {
-        // Catch errors from execSync or timeouts
-        const errorMessage = `Project initialization failed: ${error.message}`;
-        const errorDetails = error.stderr?.toString() || error.stdout?.toString() || error.message; // Provide stderr/stdout if available
-        log.error(`${errorMessage}\nDetails: ${errorDetails}`);
-
-        // Return a standard error response manually
-        return createErrorResponse(errorMessage, { details: errorDetails });
-      }
-    }
-  });
 }

mcp-server/src/tools/next-task.js

@@ -3,61 +3,83 @@
  * Tool to find the next task to work on
  */
 
-import { z } from "zod";
+import { z } from 'zod';
 import {
-  handleApiResult,
+	handleApiResult,
-  createErrorResponse,
+	createErrorResponse,
-  getProjectRootFromSession
+	getProjectRootFromSession
-} from "./utils.js";
+} from './utils.js';
-import { nextTaskDirect } from "../core/task-master-core.js";
+import { nextTaskDirect } from '../core/task-master-core.js';
+import { findTasksJsonPath } from '../core/utils/path-utils.js';
 
 /**
  * Register the next-task tool with the MCP server
  * @param {Object} server - FastMCP server instance
  */
 export function registerNextTaskTool(server) {
-  server.addTool({
+	server.addTool({
-    name: "next_task",
+		name: 'next_task',
-    description: "Find the next task to work on based on dependencies and status",
+		description:
-    parameters: z.object({
+			'Find the next task to work on based on dependencies and status',
-      file: z.string().optional().describe("Path to the tasks file"),
+		parameters: z.object({
-      projectRoot: z
+			file: z.string().optional().describe('Absolute path to the tasks file'),
-        .string()
+			projectRoot: z
-        .optional()
+				.string()
-        .describe(
+				.describe('The directory of the project. Must be an absolute path.')
-          "Root directory of the project (default: current working directory)"
+		}),
-        ),
+		execute: async (args, { log, session }) => {
-    }),
+			try {
-    execute: async (args, { log, session, reportProgress }) => {
+				log.info(`Finding next task with args: ${JSON.stringify(args)}`);
-      try {
-        log.info(`Finding next task with args: ${JSON.stringify(args)}`);
-        // await reportProgress({ progress: 0 });
 
-        let rootFolder = getProjectRootFromSession(session, log);
+				// Get project root from args or session
+				const rootFolder =
+					args.projectRoot || getProjectRootFromSession(session, log);
 
-        if (!rootFolder && args.projectRoot) {
+				// Ensure project root was determined
-          rootFolder = args.projectRoot;
+				if (!rootFolder) {
-          log.info(`Using project root from args as fallback: ${rootFolder}`);
+					return createErrorResponse(
-        }
+						'Could not determine project root. Please provide it explicitly or ensure your session contains valid root information.'
+					);
+				}
 
-        const result = await nextTaskDirect({
+				// Resolve the path to tasks.json
-          projectRoot: rootFolder,
+				let tasksJsonPath;
-          ...args
+				try {
-        }, log/*, { reportProgress, mcpLog: log, session}*/);
+					tasksJsonPath = findTasksJsonPath(
+						{ projectRoot: rootFolder, file: args.file },
+						log
+					);
+				} catch (error) {
+					log.error(`Error finding tasks.json: ${error.message}`);
+					return createErrorResponse(
+						`Failed to find tasks.json: ${error.message}`
+					);
+				}
 
-        // await reportProgress({ progress: 100 });
+				const result = await nextTaskDirect(
+					{
+						// Pass the explicitly resolved path
+						tasksJsonPath: tasksJsonPath
+						// No other args specific to this tool
+					},
+					log
+				);
 
-        if (result.success) {
+				if (result.success) {
-          log.info(`Successfully found next task: ${result.data?.task?.id || 'No available tasks'}`);
+					log.info(
-        } else {
+						`Successfully found next task: ${result.data?.task?.id || 'No available tasks'}`
-          log.error(`Failed to find next task: ${result.error?.message || 'Unknown error'}`);
+					);
-        }
+				} else {
+					log.error(
+						`Failed to find next task: ${result.error?.message || 'Unknown error'}`
+					);
+				}
 
-        return handleApiResult(result, log, 'Error finding next task');
+				return handleApiResult(result, log, 'Error finding next task');
-      } catch (error) {
+			} catch (error) {
-        log.error(`Error in nextTask tool: ${error.message}`);
+				log.error(`Error in nextTask tool: ${error.message}`);
-        return createErrorResponse(error.message);
+				return createErrorResponse(error.message);
-      }
+			}
-    },
+		}
-  });
+	});
 }

mcp-server/src/tools/parse-prd.js

@@ -3,63 +3,108 @@
  * Tool to parse PRD document and generate tasks
  */
 
-import { z } from "zod";
+import { z } from 'zod';
 import {
-  handleApiResult,
+	getProjectRootFromSession,
-  createErrorResponse,
+	handleApiResult,
-  getProjectRootFromSession
+	createErrorResponse
-} from "./utils.js";
+} from './utils.js';
-import { parsePRDDirect } from "../core/task-master-core.js";
+import { parsePRDDirect } from '../core/task-master-core.js';
+import {
+	resolveProjectPaths,
+	findPRDDocumentPath,
+	resolveTasksOutputPath
+} from '../core/utils/path-utils.js';
 
 /**
  * Register the parsePRD tool with the MCP server
  * @param {Object} server - FastMCP server instance
  */
 export function registerParsePRDTool(server) {
-  server.addTool({
+	server.addTool({
-    name: "parse_prd",
+		name: 'parse_prd',
-    description: "Parse a Product Requirements Document (PRD) or text file to automatically generate initial tasks.",
+		description:
-    parameters: z.object({
+			"Parse a Product Requirements Document (PRD) text file to automatically generate initial tasks. Reinitializing the project is not necessary to run this tool. It is recommended to run parse-prd after initializing the project and creating/importing a prd.txt file in the project root's scripts/ directory.",
-      input: z.string().default("tasks/tasks.json").describe("Path to the PRD document file (relative to project root or absolute)"),
+		parameters: z.object({
-      numTasks: z.string().optional().describe("Approximate number of top-level tasks to generate (default: 10)"),
+			input: z
-      output: z.string().optional().describe("Output path for tasks.json file (relative to project root or absolute, default: tasks/tasks.json)"),
+				.string()
-      force: z.boolean().optional().describe("Allow overwriting an existing tasks.json file."),
+				.optional()
-      projectRoot: z
+				.default('scripts/prd.txt')
-        .string()
+				.describe('Absolute path to the PRD document file (.txt, .md, etc.)'),
-        .optional()
+			numTasks: z
-        .describe(
+				.string()
-          "Root directory of the project (default: automatically detected from session or CWD)"
+				.optional()
-        ),
+				.describe(
-    }),
+					'Approximate number of top-level tasks to generate (default: 10). As the agent, if you have enough information, ensure to enter a number of tasks that would logically scale with project complexity. Avoid entering numbers above 50 due to context window limitations.'
-    execute: async (args, { log, session, reportProgress }) => {
+				),
-      try {
+			output: z
-        log.info(`Parsing PRD with args: ${JSON.stringify(args)}`);
+				.string()
+				.optional()
+				.describe(
+					'Output path for tasks.json file (default: tasks/tasks.json)'
+				),
+			force: z
+				.boolean()
+				.optional()
+				.describe('Allow overwriting an existing tasks.json file.'),
+			projectRoot: z
+				.string()
+				.describe('The directory of the project. Must be absolute path.')
+		}),
+		execute: async (args, { log, session }) => {
+			try {
+				log.info(`Parsing PRD with args: ${JSON.stringify(args)}`);
 
-        let rootFolder = getProjectRootFromSession(session, log);
+				// Get project root from args or session
+				const rootFolder =
+					args.projectRoot || getProjectRootFromSession(session, log);
 
-        if (!rootFolder && args.projectRoot) {
+				if (!rootFolder) {
-          rootFolder = args.projectRoot;
+					return createErrorResponse(
-          log.info(`Using project root from args as fallback: ${rootFolder}`);
+						'Could not determine project root. Please provide it explicitly or ensure your session contains valid root information.'
-        }
+					);
+				}
 
-        const result = await parsePRDDirect({
+				// Resolve input (PRD) and output (tasks.json) paths using the utility
-          projectRoot: rootFolder,
+				const { projectRoot, prdPath, tasksJsonPath } = resolveProjectPaths(
-          ...args
+					rootFolder,
-        }, log/*, { reportProgress, mcpLog: log, session}*/);
+					args,
+					log
+				);
 
-        // await reportProgress({ progress: 100 });
+				// Check if PRD path was found (resolveProjectPaths returns null if not found and not provided)
+				if (!prdPath) {
+					return createErrorResponse(
+						'No PRD document found or provided. Please ensure a PRD file exists (e.g., PRD.md) or provide a valid input file path.'
+					);
+				}
 
-        if (result.success) {
+				// Call the direct function with fully resolved paths
-          log.info(`Successfully parsed PRD: ${result.data.message}`);
+				const result = await parsePRDDirect(
-        } else {
+					{
-          log.error(`Failed to parse PRD: ${result.error?.message || 'Unknown error'}`);
+						projectRoot: projectRoot,
-        }
+						input: prdPath,
+						output: tasksJsonPath,
+						numTasks: args.numTasks,
+						force: args.force
+					},
+					log,
+					{ session }
+				);
 
-        return handleApiResult(result, log, 'Error parsing PRD');
+				if (result.success) {
-      } catch (error) {
+					log.info(`Successfully parsed PRD: ${result.data.message}`);
-        log.error(`Error in parse-prd tool: ${error.message}`);
+				} else {
-        return createErrorResponse(error.message);
+					log.error(
-      }
+						`Failed to parse PRD: ${result.error?.message || 'Unknown error'}`
-    },
+					);
-  });
+				}
+
+				return handleApiResult(result, log, 'Error parsing PRD');
+			} catch (error) {
+				log.error(`Error in parse-prd tool: ${error.message}`);
+				return createErrorResponse(error.message);
+			}
+		}
+	});
 }