chore: revamp README

23.16 23.30

.changeset/config.json

@@ -7,7 +7,7 @@
   "commit": false,
   "fixed": [],
   "linked": [],
-  "access": "restricted",
+  "access": "public",
   "baseBranch": "main",
   "updateInternalDependencies": "patch",
   "ignore": []

.changeset/fifty-squids-wear.md

@@ -2,4 +2,4 @@
 "task-master-ai": patch
 ---
 
-Added changeset config #39
+Add CI for testing

.changeset/nice-cougars-itch.md

@@ -1,5 +0,0 @@
----
-"task-master-ai": minor
----
-
-add github actions to automate github and npm releases

.changeset/odd-weeks-melt.md

@@ -1,5 +0,0 @@
----
-"task-master-ai": minor
----
-
-Implement MCP server for all commands using tools.

.changeset/red-lights-mix.md

@@ -0,0 +1,5 @@
+---
+"task-master-ai": patch
+---
+
+Fix github actions creating npm releases on next branch push

.changeset/two-bats-smoke.md

@@ -0,0 +1,302 @@
+---
+"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`
+- Add additional binary alias: `task-master-mcp-server` pointing to the same MCP server script
+
+- **Significant improvements to model configuration:**
+  - Increase context window from 64k to 128k tokens (MAX_TOKENS=128000) for handling larger codebases
+  - Reduce temperature from 0.4 to 0.2 for more consistent, deterministic outputs
+  - Set default model to "claude-3-7-sonnet-20250219" in configuration
+  - Update Perplexity model to "sonar-pro" for research operations
+  - Increase default subtasks generation from 4 to 5 for more granular task breakdown
+  - Set consistent default priority to "medium" for all new tasks
+
+- **Clarify environment configuration approaches:**
+  - For direct MCP usage: Configure API keys directly in `.cursor/mcp.json`
+  - For npm package usage: Configure API keys in `.env` file
+  - Update templates with clearer placeholder values and formatting
+  - Provide explicit documentation about configuration methods in both environments
+  - Use consistent placeholder format "YOUR_ANTHROPIC_API_KEY_HERE" in mcp.json
+
+- 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
+
+- **Refine AI-based MCP tool implementation patterns:**
+  - Establish clear responsibilities for direct functions vs MCP tools when handling AI operations
+  - Update MCP direct function signatures to expect `context = { session }` for AI-based tools, without `reportProgress`
+  - Clarify that AI client initialization, API calls, and response parsing should be handled within the direct function
+  - Define standard error codes for AI operations (`AI_CLIENT_ERROR`, `RESPONSE_PARSING_ERROR`, etc.)
+  - Document that `reportProgress` should not be used within direct functions due to client validation issues
+  - Establish that progress indication within direct functions should use standard logging (`log.info()`)
+  - Clarify that `AsyncOperationManager` should manage progress reporting at the MCP tool layer, not in direct functions
+  - Update `mcp.mdc` rule to reflect the refined patterns for AI-based MCP tools
+  - **Document and implement the Logger Wrapper Pattern:**
+    - Add comprehensive documentation in `mcp.mdc` and `utilities.mdc` on the Logger Wrapper Pattern
+    - Explain the dual purpose of the wrapper: preventing runtime errors and controlling output format
+    - Include implementation examples with detailed explanations of why and when to use this pattern
+    - Clearly document that this pattern has proven successful in resolving issues in multiple MCP tools
+    - Cross-reference between rule files to ensure consistent guidance
+  - **Fix critical issue in `analyze-project-complexity` MCP tool:**
+    - Implement proper logger wrapper in `analyzeTaskComplexityDirect` to fix `mcpLog[level] is not a function` errors
+    - Update direct function to handle both Perplexity and Claude AI properly for research-backed analysis
+    - Improve silent mode handling with proper wasSilent state tracking
+    - Add comprehensive error handling for AI client errors and report file parsing
+    - Ensure proper report format detection and analysis with fallbacks
+    - Fix variable name conflicts between the `report` logging function and data structures in `analyzeTaskComplexity`
+  - **Fix critical issue in `update-task` MCP tool:**
+    - Implement proper logger wrapper in `updateTaskByIdDirect` to ensure mcpLog[level] calls work correctly
+    - Update Zod schema in `update-task.js` to accept both string and number type IDs
+    - Fix silent mode implementation with proper try/finally blocks
+    - Add comprehensive error handling for missing parameters, invalid task IDs, and failed updates
+  - **Refactor `update-subtask` MCP tool to follow established patterns:**
+    - Update `updateSubtaskByIdDirect` function to accept `context = { session }` parameter
+    - Add proper AI client initialization with error handling for both Anthropic and Perplexity
+    - Implement the Logger Wrapper Pattern to prevent mcpLog[level] errors
+    - Support both string and number subtask IDs with appropriate validation
+    - Update MCP tool to pass session to direct function but not reportProgress
+    - Remove commented-out calls to reportProgress for cleaner code
+    - Add comprehensive error handling for various failure scenarios
+    - Implement proper silent mode with try/finally blocks
+    - Ensure detailed successful update response information
+  - **Fix issues in `set-task-status` MCP tool:**
+    - Remove reportProgress parameter as it's not needed
+    - Improve project root handling for better session awareness
+    - Reorganize function call arguments for setTaskStatusDirect
+    - Add proper silent mode handling with try/catch/finally blocks
+    - Enhance logging for both success and error cases
+  - **Refactor `update` MCP tool to follow established patterns:**
+    - Update `updateTasksDirect` function to accept `context = { session }` parameter
+    - Add proper AI client initialization with error handling
+    - Update MCP tool to pass session to direct function but not reportProgress
+    - Simplify parameter validation using string type for 'from' parameter
+    - Improve error handling for AI client errors
+    - Implement proper silent mode handling with try/finally blocks
+    - Use `isSilentMode()` function instead of accessing global variables directly
+  - **Refactor `expand-task` MCP tool to follow established patterns:**
+    - Update `expandTaskDirect` function to accept `context = { session }` parameter
+    - Add proper AI client initialization with error handling
+    - Update MCP tool to pass session to direct function but not reportProgress
+    - Add comprehensive tests for the refactored implementation
+    - Improve error handling for AI client errors
+    - Remove non-existent 'force' parameter from direct function implementation
+    - Ensure direct function parameters match core function parameters
+    - Implement proper silent mode handling with try/finally blocks
+    - Use `isSilentMode()` function instead of accessing global variables directly
+  - **Refactor `parse-prd` MCP tool to follow established patterns:**
+    - Update `parsePRDDirect` function to accept `context = { session }` parameter for proper AI initialization
+    - Implement AI client initialization with proper error handling using `getAnthropicClientForMCP`
+    - Add the Logger Wrapper Pattern to ensure proper logging via `mcpLog`
+    - Update the core `parsePRD` function to accept an AI client parameter
+    - Implement proper silent mode handling with try/finally blocks
+    - Remove `reportProgress` usage from MCP tool for better client compatibility
+    - Fix console output that was breaking the JSON response format
+    - Improve error handling with specific error codes
+    - Pass session object to the direct function correctly
+    - Update task-manager-core.js to export AI client utilities for better organization
+    - Ensure proper option passing between functions to maintain logging context
+
+- **Update MCP Logger to respect silent mode:**
+  - Import and check `isSilentMode()` function in logger implementation
+  - Skip all logging when silent mode is enabled
+  - Prevent console output from interfering with JSON responses
+  - Fix "Unexpected token 'I', "[INFO] Gene"... is not valid JSON" errors by suppressing log output during silent mode
+
+- **Refactor `expand-all` MCP tool to follow established patterns:**
+    - Update `expandAllTasksDirect` function to accept `context = { session }` parameter
+    - Add proper AI client initialization with error handling for research-backed expansion
+    - Pass session to direct function but not reportProgress in the MCP tool
+    - Implement directory switching to work around core function limitations
+    - Add comprehensive error handling with specific error codes
+    - Ensure proper restoration of working directory after execution
+    - Use try/finally pattern for both silent mode and directory management
+    - Add comprehensive tests for the refactored implementation
+
+- **Standardize and improve silent mode implementation across MCP direct functions:**
+  - Add proper import of all silent mode utilities: `import { enableSilentMode, disableSilentMode, isSilentMode } from 'utils.js'`
+  - Replace direct access to global silentMode variable with `isSilentMode()` function calls
+  - Implement consistent try/finally pattern to ensure silent mode is always properly disabled
+  - Add error handling with finally blocks to prevent silent mode from remaining enabled after errors
+  - Create proper mixed parameter/global silent mode check pattern: `const isSilent = options.silentMode || (typeof options.silentMode === 'undefined' && isSilentMode())`
+  - Update all direct functions to follow the new implementation pattern
+  - Fix issues with silent mode not being properly disabled when errors occur
+
+- **Improve parameter handling between direct functions and core functions:**
+  - Verify direct function parameters match core function signatures
+  - Remove extraction and use of parameters that don't exist in core functions (e.g., 'force')
+  - Implement appropriate type conversion for parameters (e.g., `parseInt(args.id, 10)`)
+  - Set defaults that match core function expectations
+  - Add detailed documentation on parameter matching in guidelines
+  - Add explicit examples of correct parameter handling patterns
+
+- **Create standardized MCP direct function implementation checklist:**
+  - Comprehensive imports and dependencies section
+  - Parameter validation and matching guidelines
+  - Silent mode implementation best practices
+  - Error handling and response format patterns
+  - Path resolution and core function call guidelines
+  - Function export and testing verification steps
+  - Specific issues to watch for related to silent mode, parameters, and error cases
+  - Add checklist to subtasks for uniform implementation across all direct functions
+
+- **Implement centralized AI client utilities for MCP tools:**
+  - Create new `ai-client-utils.js` module with standardized client initialization functions
+  - Implement session-aware AI client initialization for both Anthropic and Perplexity
+  - Add comprehensive error handling with user-friendly error messages
+  - Create intelligent AI model selection based on task requirements
+  - Implement model configuration utilities that respect session environment variables
+  - Add extensive unit tests for all utility functions
+  - Significantly improve MCP tool reliability for AI operations
+  - **Specific implementations include:**
+    - `getAnthropicClientForMCP`: Initializes Anthropic client with session environment variables
+    - `getPerplexityClientForMCP`: Initializes Perplexity client with session environment variables
+    - `getModelConfig`: Retrieves model parameters from session or fallbacks to defaults
+    - `getBestAvailableAIModel`: Selects the best available model based on requirements
+    - `handleClaudeError`: Processes Claude API errors into user-friendly messages
+  - **Updated direct functions to use centralized AI utilities:**
+    - Refactored `addTaskDirect` to use the new AI client utilities with proper AsyncOperationManager integration
+    - Implemented comprehensive error handling for API key validation, AI processing, and response parsing
+    - Added session-aware parameter handling with proper propagation of context to AI streaming functions
+    - Ensured proper fallback to process.env when session variables aren't available
+
+- **Refine AI services for reusable operations:**
+  - Refactor `ai-services.js` to support consistent AI operations across CLI and MCP
+  - Implement shared helpers for streaming responses, prompt building, and response parsing
+  - Standardize client initialization patterns with proper session parameter handling
+  - Enhance error handling and loading indicator management
+  - Fix process exit issues to prevent MCP server termination on API errors
+  - Ensure proper resource cleanup in all execution paths
+  - Add comprehensive test coverage for AI service functions
+  - **Key improvements include:**
+    - Stream processing safety with explicit completion detection
+    - Standardized function parameter patterns
+    - Session-aware parameter extraction with sensible defaults
+    - Proper cleanup using try/catch/finally patterns
+
+- **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
+  - Update silent mode implementation documentation with proper examples
+  - Add parameter handling guidelines emphasizing matching with core functions
+  - Update architecture documentation with dedicated section on silent mode implementation
+
+- **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.
+- **Standardize logging in core task-manager functions (`expandTask`, `expandAllTasks`, `updateTasks`, `updateTaskById`, `updateSubtaskById`, `parsePRD`, `analyzeTaskComplexity`):**
+  - Implement a local `report` function in each to handle context-aware logging.
+  - Use `report` to choose between `mcpLog` (if available) and global `log` (from `utils.js`).
+  - Only call global `log` when `outputFormat` is 'text' and silent mode is off.
+  - Wrap CLI UI elements (tables, boxes, spinners) in `outputFormat === 'text'` checks.

.cursor/mcp.json

@@ -0,0 +1,20 @@
+{
+    "mcpServers": {
+        "taskmaster-ai": {
+            "command": "node",
+            "args": [
+                "./mcp-server/server.js"
+            ],
+            "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": 128000,
+                "TEMPERATURE": 0.2,
+                "DEFAULT_SUBTASKS": 5,
+                "DEFAULT_PRIORITY": "medium"
+            }
+        }
+    }
+}

.cursor/rules/architecture.mdc

@@ -12,7 +12,7 @@ alwaysApply: false
 
   - **[`commands.js`](mdc:scripts/modules/commands.js): Command Handling**
     - **Purpose**: Defines and registers all CLI commands using Commander.js.
-    - **Responsibilities**:
+    - **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.
       - Handles user input and output related to command execution.
@@ -85,14 +85,15 @@ alwaysApply: false
       - `parsePRDWithAI(prdContent)`: Extracts tasks from PRD content using AI.
 
   - **[`utils.js`](mdc:scripts/modules/utils.js): Utility Functions and Configuration**
-    - **Purpose**: Provides reusable utility functions and global configuration settings used across the application.
-    - **Responsibilities**:
+    - **Purpose**: Provides reusable utility functions and global configuration settings used across the **CLI application**.
+    - **Responsibilities** (See also: [`utilities.mdc`](mdc:.cursor/rules/utilities.mdc)):
       - Manages global configuration settings loaded from environment variables and defaults.
       - Implements logging utility with different log levels and output formatting.
       - Provides file system operation utilities (read/write JSON files).
       - Includes string manipulation utilities (e.g., `truncate`, `sanitizePrompt`).
       - Offers task-specific utility functions (e.g., `formatTaskId`, `findTaskById`, `taskExists`).
       - Implements graph algorithms like cycle detection for dependency management.
+      - **Silent Mode Control**: Provides `enableSilentMode` and `disableSilentMode` functions to control log output.
     - **Key Components**:
       - `CONFIG`: Global configuration object.
       - `log(level, ...args)`: Logging function.
@@ -100,6 +101,52 @@ alwaysApply: false
       - `truncate(text, maxLength)`: String truncation utility.
       - `formatTaskId(id)` / `findTaskById(tasks, taskId)`: Task ID and search utilities.
       - `findCycles(subtaskId, dependencyMap)`: Cycle detection algorithm.
+      - `enableSilentMode()` / `disableSilentMode()`: Control console logging output.
+
+  - **[`mcp-server/`](mdc:mcp-server/): MCP Server Integration**
+    - **Purpose**: Provides an MCP (Model Context Protocol) interface for Task Master, allowing integration with external tools like Cursor. Uses FastMCP framework.
+    - **Responsibilities** (See also: [`mcp.mdc`](mdc:.cursor/rules/mcp.mdc)):
+      - Registers Task Master functionalities as tools consumable via MCP.
+      - Handles MCP requests via tool `execute` methods defined in `mcp-server/src/tools/*.js`.
+      - Tool `execute` methods call corresponding **direct function wrappers**.
+      - Tool `execute` methods use `getProjectRootFromSession` (from [`tools/utils.js`](mdc:mcp-server/src/tools/utils.js)) to determine the project root from the client session and pass it to the direct function.
+      - **Direct function wrappers (`*Direct` functions in `mcp-server/src/core/direct-functions/*.js`) contain the main logic for handling MCP requests**, including path resolution, argument validation, caching, and calling core Task Master functions.
+      - Direct functions use `findTasksJsonPath` (from [`core/utils/path-utils.js`](mdc:mcp-server/src/core/utils/path-utils.js)) to locate `tasks.json` based on the provided `projectRoot`.
+      - **Silent Mode Implementation**: Direct functions use `enableSilentMode` and `disableSilentMode` to prevent logs from interfering with JSON responses.
+      - **Async Operations**: Uses `AsyncOperationManager` to handle long-running operations in the background.
+      - **Project Initialization**: Provides `initialize_project` command for setting up new projects from within integrated clients.
+      - Tool `execute` methods use `handleApiResult` from [`tools/utils.js`](mdc:mcp-server/src/tools/utils.js) to process the result from the direct function and format the final MCP response.
+      - Uses CLI execution via `executeTaskMasterCommand` as a fallback only when necessary.
+      - **Implements Robust Path Finding**: The utility [`tools/utils.js`](mdc:mcp-server/src/tools/utils.js) (specifically `getProjectRootFromSession`) and [`core/utils/path-utils.js`](mdc:mcp-server/src/core/utils/path-utils.js) (specifically `findTasksJsonPath`) work together. The tool gets the root via session, passes it to the direct function, which uses `findTasksJsonPath` to locate the specific `tasks.json` file within that root.
+      - **Implements Caching**: Utilizes a caching layer (`ContextManager` with `lru-cache`). Caching logic is invoked *within* the direct function wrappers using the `getCachedOrExecute` utility for performance-sensitive read operations.
+      - Standardizes response formatting and data filtering using utilities in [`tools/utils.js`](mdc:mcp-server/src/tools/utils.js).
+      - **Resource Management**: Provides access to static and dynamic resources.
+    - **Key Components**:
+      - `mcp-server/src/index.js`: Main server class definition with FastMCP initialization, resource registration, and server lifecycle management.
+      - `mcp-server/src/server.js`: Main server setup and initialization.
+      - `mcp-server/src/tools/`: Directory containing individual tool definitions. Each tool's `execute` method orchestrates the call to core logic and handles the response.
+      - `mcp-server/src/tools/utils.js`: Provides MCP-specific utilities like `handleApiResult`, `processMCPResponseData`, `getCachedOrExecute`, and **`getProjectRootFromSession`**.
+      - `mcp-server/src/core/utils/`: Directory containing utility functions specific to the MCP server, like **`path-utils.js` for resolving `tasks.json` within a given root** and **`async-manager.js` for handling background operations**.
+      - `mcp-server/src/core/direct-functions/`: Directory containing individual files for each **direct function wrapper (`*Direct`)**. These files contain the primary logic for MCP tool execution.
+      - `mcp-server/src/core/resources/`: Directory containing resource handlers for task templates, workflow definitions, and other static/dynamic data exposed to LLM clients.
+      - [`task-master-core.js`](mdc:mcp-server/src/core/task-master-core.js): Acts as an import/export hub, collecting and exporting direct functions from the `direct-functions` directory and MCP utility functions.
+    - **Naming Conventions**:
+      - **Files** use **kebab-case**: `list-tasks.js`, `set-task-status.js`, `parse-prd.js`
+      - **Direct Functions** use **camelCase** with `Direct` suffix: `listTasksDirect`, `setTaskStatusDirect`, `parsePRDDirect`
+      - **Tool Registration Functions** use **camelCase** with `Tool` suffix: `registerListTasksTool`, `registerSetTaskStatusTool`
+      - **MCP Tool Names** use **snake_case**: `list_tasks`, `set_task_status`, `parse_prd_document`
+      - **Resource Handlers** use **camelCase** with pattern URI: `@mcp.resource("tasks://templates/{template_id}")`
+    - **AsyncOperationManager**:
+      - **Purpose**: Manages background execution of long-running operations.
+      - **Location**: `mcp-server/src/core/utils/async-manager.js`
+      - **Key Features**:
+        - Operation tracking with unique IDs using UUID
+        - Status management (pending, running, completed, failed)
+        - Progress reporting forwarded from background tasks
+        - Operation history with automatic cleanup of completed operations
+        - Context preservation (log, session, reportProgress)
+        - Robust error handling for background tasks
+      - **Usage**: Used for CPU-intensive operations like task expansion and PRD parsing
 
 - **Data Flow and Module Dependencies**:
 
@@ -108,10 +155,118 @@ alwaysApply: false
   - **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/` (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**:
 
-  - **Test Organization Structure**:
+  - **Test Organization Structure** (See also: [`tests.mdc`](mdc:.cursor/rules/tests.mdc)):
     - **Unit Tests**: Located in `tests/unit/`, reflect the module structure with one test file per module
     - **Integration Tests**: Located in `tests/integration/`, test interactions between modules
     - **End-to-End Tests**: Located in `tests/e2e/`, test complete workflows from a user perspective
@@ -150,3 +305,67 @@ alwaysApply: false
   - **Clarity**: The modular structure provides a clear separation of concerns, making the codebase easier to navigate and understand for developers.
 
 This architectural overview should help AI models understand the structure and organization of the Task Master CLI codebase, enabling them to more effectively assist with code generation, modification, and understanding.
+
+## Implementing MCP Support for a Command
+
+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/`.
+
+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:
+        - **Path Resolution**: Obtain the tasks file path using `const tasksPath = findTasksJsonPath(args, log);`. This relies on `args.projectRoot` being provided.
+        - Parse other `args` and perform necessary validation.
+        - **Implement Silent Mode**: Wrap core function calls with `enableSilentMode()` and `disableSilentMode()`.
+        - Implement caching with `getCachedOrExecute` if applicable.
+        - Call core logic.
+        - Return `{ success: true/false, data/error, fromCache: boolean }`.
+    - Export the wrapper function.
+
+3.  **Update `task-master-core.js` with Import/Export**: Add imports/exports for the new `*Direct` function.
+
+4.  **Create MCP Tool (`mcp-server/src/tools/`)**:
+    - Create a new file (e.g., `your-command.js`) using **kebab-case**.
+    - Import `zod`, `handleApiResult`, **`getProjectRootFromSession`**, and your `yourCommandDirect` function.
+    - Implement `registerYourCommandTool(server)`.
+    - **Define parameters, making `projectRoot` optional**: `projectRoot: z.string().optional().describe(...)`.
+    - Consider if this operation should run in the background using `AsyncOperationManager`.
+    - Implement the standard `execute` method:
+      - Get `rootFolder` using `getProjectRootFromSession` (with fallback to `args.projectRoot`).
+      - Call `yourCommandDirect({ ...args, projectRoot: rootFolder }, log)` or use `asyncOperationManager.addOperation`.
+      - Pass the result to `handleApiResult`.
+
+5.  **Register Tool**: Import and call `registerYourCommandTool` in `mcp-server/src/tools/index.js`.
+
+6.  **Update `mcp.json`**: Add the new tool definition.
+
+## Project Initialization
+
+The `initialize_project` command provides a way to set up a new Task Master project:
+
+- **CLI Command**: `task-master init`
+- **MCP Tool**: `initialize_project`
+- **Functionality**:
+  - Creates necessary directories and files for a new project
+  - Sets up `tasks.json` and initial task files
+  - Configures project metadata (name, description, version)
+  - Handles shell alias creation if requested
+  - Works in both interactive and non-interactive modes
+
+## Async Operation Management
+
+The AsyncOperationManager provides background task execution capabilities:
+
+- **Location**: `mcp-server/src/core/utils/async-manager.js`
+- **Key Components**:
+  - `asyncOperationManager` singleton instance
+  - `addOperation(operationFn, args, context)` method
+  - `getStatus(operationId)` method
+- **Usage Flow**:
+  1. Client calls an MCP tool that may take time to complete
+  2. Tool uses AsyncOperationManager to run the operation in background
+  3. Tool returns immediate response with operation ID
+  4. Client polls `get_operation_status` tool with the ID
+  5. Once completed, client can access operation results

.cursor/rules/changeset.mdc

@@ -0,0 +1,105 @@
+---
+description: Guidelines for using Changesets (npm run changeset) to manage versioning and changelogs.
+alwaysApply: true
+---
+
+# Changesets Workflow Guidelines
+
+Changesets is used to manage package versioning and generate accurate `CHANGELOG.md` files automatically. It's crucial to use it correctly after making meaningful changes that affect the package from an external perspective or significantly impact internal development workflow documented elsewhere.
+
+## When to Run Changeset
+
+- Run `npm run changeset` (or `npx changeset add`) **after** you have staged (`git add .`) a logical set of changes that should be communicated in the next release's `CHANGELOG.md`.
+- This typically includes:
+    - **New Features** (Backward-compatible additions)
+    - **Bug Fixes** (Fixes to existing functionality)
+    - **Breaking Changes** (Changes that are not backward-compatible)
+    - **Performance Improvements** (Enhancements to speed or resource usage)
+    - **Significant Refactoring** (Major code restructuring, even if external behavior is unchanged, as it might affect stability or maintainability) - *Such as reorganizing the MCP server's direct function implementations into separate files*
+    - **User-Facing Documentation Updates** (Changes to README, usage guides, public API docs)
+    - **Dependency Updates** (Especially if they fix known issues or introduce significant changes)
+    - **Build/Tooling Changes** (If they affect how consumers might build or interact with the package)
+- **Every Pull Request** containing one or more of the above change types **should include a changeset file**.
+
+## What NOT to Add a Changeset For
+
+Avoid creating changesets for changes that have **no impact or relevance to external consumers** of the `task-master` package or contributors following **public-facing documentation**. Examples include:
+
+- **Internal Documentation Updates:** Changes *only* to files within `.cursor/rules/` that solely guide internal development practices for this specific repository.
+- **Trivial Chores:** Very minor code cleanup, adding comments that don't clarify behavior, typo fixes in non-user-facing code or internal docs.
+- **Non-Impactful Test Updates:** Minor refactoring of tests, adding tests for existing functionality without fixing bugs.
+- **Local Configuration Changes:** Updates to personal editor settings, local `.env` files, etc.
+
+**Rule of Thumb:** If a user installing or using the `task-master` package wouldn't care about the change, or if a contributor following the main README wouldn't need to know about it for their workflow, you likely don't need a changeset.
+
+## How to Run and What It Asks
+
+1.  **Run the command**:
+    ```bash
+    npm run changeset
+    # or
+    npx changeset add
+    ```
+2.  **Select Packages**: It will prompt you to select the package(s) affected by your changes using arrow keys and spacebar. If this is not a monorepo, select the main package.
+3.  **Select Bump Type**: Choose the appropriate semantic version bump for **each** selected package:
+    *   **`Major`**: For **breaking changes**. Use sparingly.
+    *   **`Minor`**: For **new features**.
+    *   **`Patch`**: For **bug fixes**, performance improvements, **user-facing documentation changes**, significant refactoring, relevant dependency updates, or impactful build/tooling changes.
+4.  **Enter Summary**: Provide a concise summary of the changes **for the `CHANGELOG.md`**.
+    *   **Purpose**: This message is user-facing and explains *what* changed in the release.
+    *   **Format**: Use the imperative mood (e.g., "Add feature X", "Fix bug Y", "Update README setup instructions"). Keep it brief, typically a single line.
+    *   **Audience**: Think about users installing/updating the package or developers consuming its public API/CLI.
+    *   **Not a Git Commit Message**: This summary is *different* from your detailed Git commit message.
+
+## Changeset Summary vs. Git Commit Message
+
+- **Changeset Summary**:
+    - **Audience**: Users/Consumers of the package (reads `CHANGELOG.md`).
+    - **Purpose**: Briefly describe *what* changed in the released version that is relevant to them.
+    - **Format**: Concise, imperative mood, single line usually sufficient.
+    - **Example**: `Fix dependency resolution bug in 'next' command.`
+- **Git Commit Message**:
+    - **Audience**: Developers browsing the Git history of *this* repository.
+    - **Purpose**: Explain *why* the change was made, the context, and the implementation details (can include internal context).
+    - **Format**: Follows commit conventions (e.g., Conventional Commits), can be multi-line with a subject and body.
+    - **Example**:
+      ```
+      fix(deps): Correct dependency lookup in 'next' command
+
+      The logic previously failed to account for subtask dependencies when
+      determining the next available task. This commit refactors the
+      dependency check in `findNextTask` within `task-manager.js` to
+      correctly traverse both direct and subtask dependencies. Added
+      unit tests to cover this specific scenario.
+      ```
+- ✅ **DO**: Provide *both* a concise changeset summary (when appropriate) *and* a detailed Git commit message.
+- ❌ **DON'T**: Use your detailed Git commit message body as the changeset summary.
+- ❌ **DON'T**: Skip running `changeset` for user-relevant changes just because you wrote a good commit message.
+
+## The `.changeset` File
+
+- Running the command creates a unique markdown file in the `.changeset/` directory (e.g., `.changeset/random-name.md`).
+- This file contains the bump type information and the summary you provided.
+- **This file MUST be staged and committed** along with your relevant code changes.
+
+## Standard Workflow Sequence (When a Changeset is Needed)
+
+1.  Make your code or relevant documentation changes.
+2.  Stage your changes: `git add .`
+3.  Run changeset: `npm run changeset`
+    *   Select package(s).
+    *   Select bump type (`Patch`, `Minor`, `Major`).
+    *   Enter the **concise summary** for the changelog.
+4.  Stage the generated changeset file: `git add .changeset/*.md`
+5.  Commit all staged changes (code + changeset file) using your **detailed Git commit message**:
+    ```bash
+    git commit -m "feat(module): Add new feature X..."
+    ```
+
+## Release Process (Context)
+
+- The generated `.changeset/*.md` files are consumed later during the release process.
+- Commands like `changeset version` read these files, update `package.json` versions, update the `CHANGELOG.md`, and delete the individual changeset files.
+- Commands like `changeset publish` then publish the new versions to npm.
+
+Following this workflow ensures that versioning is consistent and changelogs are automatically and accurately generated based on the contributions made.

.cursor/rules/commands.mdc

@@ -6,6 +6,16 @@ alwaysApply: false
 
 # Command-Line Interface Implementation Guidelines
 
+**Note on Interaction Method:**
+
+While this document details the implementation of Task Master's **CLI commands**, the **preferred method for interacting with Task Master in integrated environments (like Cursor) is through the MCP server tools**. 
+
+- **Use MCP Tools First**: Always prefer using the MCP tools (e.g., `get_tasks`, `add_task`) when interacting programmatically or via an integrated tool. They offer better performance, structured data, and richer error handling. See [`taskmaster.mdc`](mdc:.cursor/rules/taskmaster.mdc) for a comprehensive list of MCP tools and their corresponding CLI commands.
+- **CLI as Fallback/User Interface**: The `task-master` CLI commands described here are primarily intended for:
+    - Direct user interaction in the terminal.
+    - A fallback mechanism if the MCP server is unavailable or a specific functionality is not exposed via an MCP tool.
+- **Implementation Context**: This document (`commands.mdc`) focuses on the standards for *implementing* the CLI commands using Commander.js within the [`commands.js`](mdc:scripts/modules/commands.js) module.
+
 ## Command Structure Standards
 
 - **Basic Command Template**:
@@ -27,6 +37,126 @@ alwaysApply: false
   - ✅ DO: Include validation for required parameters
   - ❌ DON'T: Implement business logic in command handlers
 
+## Best Practices for Removal/Delete Commands
+
+When implementing commands that delete or remove data (like `remove-task` or `remove-subtask`), follow these specific guidelines:
+
+- **Confirmation Prompts**:
+  - ✅ **DO**: Include a confirmation prompt by default for destructive operations
+  - ✅ **DO**: Provide a `--yes` or `-y` flag to skip confirmation for scripting/automation
+  - ✅ **DO**: Show what will be deleted in the confirmation message
+  - ❌ **DON'T**: Perform destructive operations without user confirmation unless explicitly overridden
+
+  ```javascript
+  // ✅ DO: Include confirmation for destructive operations
+  programInstance
+    .command('remove-task')
+    .description('Remove a task or subtask permanently')
+    .option('-i, --id <id>', 'ID of the task to remove')
+    .option('-y, --yes', 'Skip confirmation prompt', false)
+    .action(async (options) => {
+      // Validation code...
+      
+      if (!options.yes) {
+        const confirm = await inquirer.prompt([{
+          type: 'confirm',
+          name: 'proceed',
+          message: `Are you sure you want to permanently delete task ${taskId}? This cannot be undone.`,
+          default: false
+        }]);
+        
+        if (!confirm.proceed) {
+          console.log(chalk.yellow('Operation cancelled.'));
+          return;
+        }
+      }
+      
+      // Proceed with removal...
+    });
+  ```
+
+- **File Path Handling**:
+  - ✅ **DO**: Use `path.join()` to construct file paths
+  - ✅ **DO**: Follow established naming conventions for tasks (e.g., `task_001.txt`)
+  - ✅ **DO**: Check if files exist before attempting to delete them
+  - ✅ **DO**: Handle file deletion errors gracefully
+  - ❌ **DON'T**: Construct paths with string concatenation
+
+  ```javascript
+  // ✅ DO: Properly construct file paths
+  const taskFilePath = path.join(
+    path.dirname(tasksPath),
+    `task_${taskId.toString().padStart(3, '0')}.txt`
+  );
+  
+  // ✅ DO: Check existence before deletion
+  if (fs.existsSync(taskFilePath)) {
+    try {
+      fs.unlinkSync(taskFilePath);
+      console.log(chalk.green(`Task file deleted: ${taskFilePath}`));
+    } catch (error) {
+      console.warn(chalk.yellow(`Could not delete task file: ${error.message}`));
+    }
+  }
+  ```
+
+- **Clean Up References**:
+  - ✅ **DO**: Clean up references to the deleted item in other parts of the data
+  - ✅ **DO**: Handle both direct and indirect references
+  - ✅ **DO**: Explain what related data is being updated
+  - ❌ **DON'T**: Leave dangling references
+
+  ```javascript
+  // ✅ DO: Clean up references when deleting items
+  console.log(chalk.blue('Cleaning up task dependencies...'));
+  let referencesRemoved = 0;
+  
+  // Update dependencies in other tasks
+  data.tasks.forEach(task => {
+    if (task.dependencies && task.dependencies.includes(taskId)) {
+      task.dependencies = task.dependencies.filter(depId => depId !== taskId);
+      referencesRemoved++;
+    }
+  });
+  
+  if (referencesRemoved > 0) {
+    console.log(chalk.green(`Removed ${referencesRemoved} references to task ${taskId} from other tasks`));
+  }
+  ```
+
+- **Task File Regeneration**:
+  - ✅ **DO**: Regenerate task files after destructive operations
+  - ✅ **DO**: Pass all required parameters to generation functions
+  - ✅ **DO**: Provide an option to skip regeneration if needed
+  - ❌ **DON'T**: Assume default parameters will work
+
+  ```javascript
+  // ✅ DO: Properly regenerate files after deletion
+  if (!options.skipGenerate) {
+    console.log(chalk.blue('Regenerating task files...'));
+    try {
+      // Note both parameters are explicitly provided
+      await generateTaskFiles(tasksPath, path.dirname(tasksPath));
+      console.log(chalk.green('Task files regenerated successfully'));
+    } catch (error) {
+      console.warn(chalk.yellow(`Warning: Could not regenerate task files: ${error.message}`));
+    }
+  }
+  ```
+
+- **Alternative Suggestions**:
+  - ✅ **DO**: Suggest non-destructive alternatives when appropriate
+  - ✅ **DO**: Explain the difference between deletion and status changes
+  - ✅ **DO**: Include examples of alternative commands
+
+  ```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='deferred'`));
+  console.log('This preserves the task and its history for reference.');
+  ```
+
 ## Option Naming Conventions
 
 - **Command Names**:
@@ -52,6 +182,28 @@ alwaysApply: false
 
   > **Note**: Although options are defined with kebab-case (`--num-tasks`), Commander.js stores them internally as camelCase properties. Access them in code as `options.numTasks`, not `options['num-tasks']`.
 
+- **Boolean Flag Conventions**:
+  - ✅ DO: Use positive flags with `--skip-` prefix for disabling behavior
+  - ❌ DON'T: Use negated boolean flags with `--no-` prefix
+  - ✅ DO: Use consistent flag handling across all commands
+
+  ```javascript
+  // ✅ DO: Use positive flag with skip- prefix 
+  .option('--skip-generate', 'Skip generating task files')
+  
+  // ❌ DON'T: Use --no- prefix 
+  .option('--no-generate', 'Skip generating task files')
+  ```
+
+  > **Important**: When handling boolean flags in the code, make your intent clear:
+  ```javascript
+  // ✅ DO: Use clear variable naming that matches the flag's intent
+  const generateFiles = !options.skipGenerate;
+  
+  // ❌ DON'T: Use confusing double negatives
+  const dontSkipGenerate = !options.skipGenerate;
+  ```
+
 ## Input Validation
 
 - **Required Parameters**:
@@ -80,6 +232,38 @@ alwaysApply: false
   }
   ```
 
+- **Enhanced Input Validation**:
+  - ✅ DO: Validate file existence for critical file operations
+  - ✅ DO: Provide context-specific validation for identifiers
+  - ✅ DO: Check required API keys for features that depend on them
+
+  ```javascript
+  // ✅ DO: Validate file existence
+  if (!fs.existsSync(tasksPath)) {
+    console.error(chalk.red(`Error: Tasks file not found at path: ${tasksPath}`));
+    if (tasksPath === 'tasks/tasks.json') {
+      console.log(chalk.yellow('Hint: Run task-master init or task-master parse-prd to create tasks.json first'));
+    } else {
+      console.log(chalk.yellow(`Hint: Check if the file path is correct: ${tasksPath}`));
+    }
+    process.exit(1);
+  }
+  
+  // ✅ DO: Validate task ID
+  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.\nEnsure proper error handling.\''));
+    process.exit(1);
+  }
+  
+  // ✅ DO: Check for required API keys
+  if (useResearch && !process.env.PERPLEXITY_API_KEY) {
+    console.log(chalk.yellow('Warning: PERPLEXITY_API_KEY environment variable is missing. Research-backed updates will not be available.'));
+    console.log(chalk.yellow('Falling back to Claude AI for task update.'));
+  }
+  ```
+
 ## User Feedback
 
 - **Operation Status**:
@@ -101,6 +285,26 @@ alwaysApply: false
   }
   ```
 
+- **Success Messages with Next Steps**:
+  - ✅ DO: Use boxen for important success messages with clear formatting
+  - ✅ DO: Provide suggested next steps after command completion
+  - ✅ DO: Include ready-to-use commands for follow-up actions
+
+  ```javascript
+  // ✅ DO: Display success with next steps
+  console.log(boxen(
+    chalk.white.bold(`Subtask ${parentId}.${subtask.id} Added Successfully`) + '\n\n' +
+    chalk.white(`Title: ${subtask.title}`) + '\n' +
+    chalk.white(`Status: ${getStatusWithColor(subtask.status)}`) + '\n' +
+    (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(`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 } }
+  ));
+  ```
+
 ## Command Registration
 
 - **Command Grouping**:
@@ -117,7 +321,10 @@ alwaysApply: false
   export {
     registerCommands,
     setupCLI,
-    runCLI
+    runCLI,
+    checkForUpdate, // Include version checking functions
+    compareVersions,
+    displayUpgradeNotification
   };
   ```
 
@@ -143,6 +350,88 @@ alwaysApply: false
   }
   ```
 
+- **Unknown Options Handling**:
+  - ✅ DO: Provide clear error messages for unknown options
+  - ✅ DO: Show available options when an unknown option is used
+  - ✅ DO: Include command-specific help displays for common errors
+  - ❌ DON'T: Allow unknown options with `.allowUnknownOption()`
+
+  ```javascript
+  // ✅ DO: Register global error handlers for unknown options
+  programInstance.on('option:unknown', function(unknownOption) {
+    const commandName = this._name || 'unknown';
+    console.error(chalk.red(`Error: Unknown option '${unknownOption}'`));
+    console.error(chalk.yellow(`Run 'task-master ${commandName} --help' to see available options`));
+    process.exit(1);
+  });
+  
+  // ✅ DO: Add command-specific help displays
+  function showCommandHelp() {
+    console.log(boxen(
+      chalk.white.bold('Command Help') + '\n\n' +
+      chalk.cyan('Usage:') + '\n' +
+      `  task-master command --option1=<value> [options]\n\n` +
+      chalk.cyan('Options:') + '\n' +
+      '  --option1 <value>    Description of option1 (required)\n' +
+      '  --option2 <value>    Description of option2\n\n' +
+      chalk.cyan('Examples:') + '\n' +
+      '  task-master command --option1=\'value1\' --option2=\'value2\'',
+      { padding: 1, borderColor: 'blue', borderStyle: 'round' }
+    ));
+  }
+  ```
+
+- **Global Error Handling**:
+  - ✅ DO: Set up global error handlers for uncaught exceptions
+  - ✅ DO: Detect and format Commander-specific errors
+  - ✅ DO: Provide suitable guidance for fixing common errors
+
+  ```javascript
+  // ✅ DO: Set up global error handlers with helpful messages
+  process.on('uncaughtException', (err) => {
+    // Handle Commander-specific errors
+    if (err.code === 'commander.unknownOption') {
+      const option = err.message.match(/'([^']+)'/)?.[1];
+      console.error(chalk.red(`Error: Unknown option '${option}'`));
+      console.error(chalk.yellow(`Run 'task-master <command> --help' to see available options`));
+      process.exit(1);
+    }
+    
+    // Handle other error types...
+    console.error(chalk.red(`Error: ${err.message}`));
+    process.exit(1);
+  });
+  ```
+
+- **Contextual Error Handling**:
+  - ✅ DO: Provide specific error handling for common issues
+  - ✅ DO: Include troubleshooting hints for each error type
+  - ✅ DO: Use consistent error formatting across all commands
+
+  ```javascript
+  // ✅ DO: Provide specific error handling with guidance
+  try {
+    // Implementation
+  } catch (error) {
+    console.error(chalk.red(`Error: ${error.message}`));
+    
+    // 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('  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.'));
+    }
+    
+    if (CONFIG.debug) {
+      console.error(error);
+    }
+    
+    process.exit(1);
+  }
+  ```
+
 ## Integration with Other Modules
 
 - **Import Organization**:
@@ -155,6 +444,7 @@ alwaysApply: false
   import { program } from 'commander';
   import path from 'path';
   import chalk from 'chalk';
+  import https from 'https';
   
   import { CONFIG, log, readJSON } from './utils.js';
   import { displayBanner, displayHelp } from './ui.js';
@@ -172,30 +462,22 @@ alwaysApply: false
     .description('Add a new subtask to a parent task or convert an existing task to a subtask')
     .option('-f, --file <path>', 'Path to the tasks file', 'tasks/tasks.json')
     .option('-p, --parent <id>', 'ID of the parent task (required)')
-    .option('-e, --existing <id>', 'ID of an existing task to convert to a subtask')
+    .option('-i, --task-id <id>', 'Existing task ID to convert to subtask')
     .option('-t, --title <title>', 'Title for the new subtask (when not converting)')
     .option('-d, --description <description>', 'Description for the new subtask (when not converting)')
     .option('--details <details>', 'Implementation details for the new subtask (when not converting)')
     .option('--dependencies <ids>', 'Comma-separated list of subtask IDs this subtask depends on')
     .option('--status <status>', 'Initial status for the subtask', 'pending')
+    .option('--skip-generate', 'Skip regenerating task files')
     .action(async (options) => {
       // Validate required parameters
       if (!options.parent) {
         console.error(chalk.red('Error: --parent parameter is required'));
+        showAddSubtaskHelp(); // Show contextual help
         process.exit(1);
       }
       
-      // Validate that either existing task ID or title is provided
-      if (!options.existing && !options.title) {
-        console.error(chalk.red('Error: Either --existing or --title must be provided'));
-        process.exit(1);
-      }
-      
-      try {
-        // Implementation
-      } catch (error) {
-        // Error handling
-      }
+      // Implementation with detailed error handling
     });
   ```
 
@@ -208,25 +490,117 @@ alwaysApply: false
     .option('-f, --file <path>', 'Path to the tasks file', 'tasks/tasks.json')
     .option('-i, --id <id>', 'ID of the subtask to remove in format "parentId.subtaskId" (required)')
     .option('-c, --convert', 'Convert the subtask to a standalone task')
+    .option('--skip-generate', 'Skip regenerating task files')
     .action(async (options) => {
-      // Validate required parameters
-      if (!options.id) {
-        console.error(chalk.red('Error: --id parameter is required'));
+      // Implementation with detailed error handling
+    })
+    .on('error', function(err) {
+      console.error(chalk.red(`Error: ${err.message}`));
+      showRemoveSubtaskHelp(); // Show contextual help
       process.exit(1);
-      }
-      
-      // Validate subtask ID format
-      if (!options.id.includes('.')) {
-        console.error(chalk.red('Error: Subtask ID must be in format "parentId.subtaskId"'));
-        process.exit(1);
-      }
-      
-      try {
-        // Implementation
-      } catch (error) {
-        // Error handling
-      }
     });
   ```
 
+## Version Checking and Updates
+
+- **Automatic Version Checking**:
+  - ✅ DO: Implement version checking to notify users of available updates
+  - ✅ DO: Use non-blocking version checks that don't delay command execution
+  - ✅ DO: Display update notifications after command completion
+
+  ```javascript
+  // ✅ DO: Implement version checking function
+  async function checkForUpdate() {
+    // Implementation details...
+    return { currentVersion, latestVersion, needsUpdate };
+  }
+  
+  // ✅ DO: Implement semantic version comparison
+  function compareVersions(v1, v2) {
+    const v1Parts = v1.split('.').map(p => parseInt(p, 10));
+    const v2Parts = v2.split('.').map(p => parseInt(p, 10));
+    
+    // Implementation details...
+    return result; // -1, 0, or 1
+  }
+  
+  // ✅ DO: Display attractive update notifications
+  function displayUpgradeNotification(currentVersion, latestVersion) {
+    const message = boxen(
+      `${chalk.blue.bold('Update Available!')} ${chalk.dim(currentVersion)} → ${chalk.green(latestVersion)}\n\n` +
+      `Run ${chalk.cyan('npm i task-master-ai@latest -g')} to update to the latest version with new features and bug fixes.`,
+      {
+        padding: 1,
+        margin: { top: 1, bottom: 1 },
+        borderColor: 'yellow',
+        borderStyle: 'round'
+      }
+    );
+    
+    console.log(message);
+  }
+  
+  // ✅ DO: Integrate version checking in CLI run function
+  async function runCLI(argv = process.argv) {
+    try {
+      // Start the update check in the background - don't await yet
+      const updateCheckPromise = checkForUpdate();
+      
+      // Setup and parse
+      const programInstance = setupCLI();
+      await programInstance.parseAsync(argv);
+      
+      // After command execution, check if an update is available
+      const updateInfo = await updateCheckPromise;
+      if (updateInfo.needsUpdate) {
+        displayUpgradeNotification(updateInfo.currentVersion, updateInfo.latestVersion);
+      }
+    } catch (error) {
+      // Error handling...
+    }
+  }
+  ```
+
 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

@@ -1,206 +1,125 @@
 ---
-description: Guide for using meta-development script (scripts/dev.js) to manage task-driven development workflows
+description: Guide for using Task Master to manage task-driven development workflows
 globs: **/*
 alwaysApply: true
 ---
 
-- **Global CLI Commands**
-  - Task Master now provides a global CLI through the `task-master` command
-  - All functionality from `scripts/dev.js` is available through this interface
-  - Install globally with `npm install -g claude-task-master` or use locally via `npx`
-  - Use `task-master <command>` instead of `node scripts/dev.js <command>`
-  - Examples:
-    - `task-master list` instead of `node scripts/dev.js list`
-    - `task-master next` instead of `node scripts/dev.js next`
-    - `task-master expand --id=3` instead of `node scripts/dev.js expand --id=3`
-  - All commands accept the same options as their script equivalents
-  - The CLI provides additional commands like `task-master init` for project setup
+# Task Master Development Workflow
 
-- **Development Workflow Process**
-  - Start new projects by running `task-master init` or `node scripts/dev.js parse-prd --input=<prd-file.txt>` to generate initial tasks.json
-  - Begin coding sessions with `task-master list` to see current tasks, status, and IDs
-  - Analyze task complexity with `task-master analyze-complexity --research` before breaking down tasks
+This guide outlines the typical process for using Task Master to manage software development projects.
+
+## Primary Interaction: MCP Server vs. CLI
+
+Task Master offers two primary ways to interact:
+
+1.  **MCP Server (Recommended for Integrated Tools)**:
+    - For AI agents and integrated development environments (like Cursor), interacting via the **MCP server is the preferred method**.
+    - The MCP server exposes Task Master functionality through a set of tools (e.g., `get_tasks`, `add_subtask`).
+    - This method offers better performance, structured data exchange, and richer error handling compared to CLI parsing.
+    - Refer to [`mcp.mdc`](mdc:.cursor/rules/mcp.mdc) for details on the MCP architecture and available tools.
+    - A comprehensive list and description of MCP tools and their corresponding CLI commands can be found in [`taskmaster.mdc`](mdc:.cursor/rules/taskmaster.mdc).
+    - **Restart the MCP server** if core logic in `scripts/modules` or MCP tool/direct function definitions change.
+
+2.  **`task-master` CLI (For Users & Fallback)**:
+    - The global `task-master` command provides a user-friendly interface for direct terminal interaction.
+    - It can also serve as a fallback if the MCP server is inaccessible or a specific function isn't exposed via MCP.
+    - Install globally with `npm install -g task-master-ai` or use locally via `npx task-master-ai ...`.
+    - The CLI commands often mirror the MCP tools (e.g., `task-master list` corresponds to `get_tasks`).
+    - Refer to [`taskmaster.mdc`](mdc:.cursor/rules/taskmaster.mdc) for a detailed command reference.
+
+## 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
+-   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
+-   Review complexity report using `complexity_report` / `task-master complexity-report` (see [`taskmaster.mdc`](mdc:.cursor/rules/taskmaster.mdc)).
 -   Select tasks based on dependencies (all marked 'done'), priority level, and ID order
 -   Clarify tasks by checking task files in tasks/ directory or asking for user input
-  - View specific task details using `task-master show <id>` to understand implementation requirements
-  - Break down complex tasks using `task-master expand --id=<id>` with appropriate flags
-  - Clear existing subtasks if needed using `task-master clear-subtasks --id=<id>` before regenerating
+-   View specific task details using `get_task` / `task-master show <id>` (see [`taskmaster.mdc`](mdc:.cursor/rules/taskmaster.mdc)) to understand implementation requirements
+-   Break down complex tasks using `expand_task` / `task-master expand --id=<id>` (see [`taskmaster.mdc`](mdc:.cursor/rules/taskmaster.mdc)) with appropriate flags
+-   Clear existing subtasks if needed using `clear_subtasks` / `task-master clear-subtasks --id=<id>` (see [`taskmaster.mdc`](mdc:.cursor/rules/taskmaster.mdc)) before regenerating
 -   Implement code following task details, dependencies, and project standards
-  - Verify tasks according to test strategies before marking as complete
-  - Mark completed tasks with `task-master set-status --id=<id> --status=done`
-  - Update dependent tasks when implementation differs from original plan
-  - Generate task files with `task-master generate` after updating tasks.json
-  - Maintain valid dependency structure with `task-master fix-dependencies` when needed
+-   Verify tasks according to test strategies before marking as complete (See [`tests.mdc`](mdc:.cursor/rules/tests.mdc))
+-   Mark completed tasks with `set_task_status` / `task-master set-status --id=<id> --status=done` (see [`taskmaster.mdc`](mdc:.cursor/rules/taskmaster.mdc))
+-   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='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
-  - Report progress regularly using the list command
+-   Report progress regularly using `get_tasks` / `task-master list`
 
-- **Task Complexity Analysis**
-  - Run `node scripts/dev.js analyze-complexity --research` for comprehensive analysis
-  - Review complexity report in scripts/task-complexity-report.json
-  - Or use `node scripts/dev.js complexity-report` for a formatted, readable version of the report
+## Task Complexity Analysis
+
+-   Run `analyze_complexity` / `task-master analyze-complexity --research` (see [`taskmaster.mdc`](mdc:.cursor/rules/taskmaster.mdc)) for comprehensive analysis
+-   Review complexity report via `complexity_report` / `task-master complexity-report` (see [`taskmaster.mdc`](mdc:.cursor/rules/taskmaster.mdc)) for a formatted, readable version.
 -   Focus on tasks with highest complexity scores (8-10) for detailed breakdown
 -   Use analysis results to determine appropriate subtask allocation
-  - Note that reports are automatically used by the expand command
+-   Note that reports are automatically used by the `expand` tool/command
 
-- **Task Breakdown Process**
-  - For tasks with complexity analysis, use `node scripts/dev.js expand --id=<id>`
-  - Otherwise use `node scripts/dev.js expand --id=<id> --subtasks=<number>`
+## Task Breakdown Process
+
+-   For tasks with complexity analysis, use `expand_task` / `task-master expand --id=<id>` (see [`taskmaster.mdc`](mdc:.cursor/rules/taskmaster.mdc))
+-   Otherwise use `expand_task` / `task-master expand --id=<id> --num=<number>`
 -   Add `--research` flag to leverage Perplexity AI for research-backed expansion
 -   Use `--prompt="<context>"` to provide additional context when needed
 -   Review and adjust generated subtasks as necessary
-  - Use `--all` flag to expand multiple pending tasks at once
-  - If subtasks need regeneration, clear them first with `clear-subtasks` command
+-   Use `--all` flag with `expand` or `expand_all` to expand multiple pending tasks at once
+-   If subtasks need regeneration, clear them first with `clear_subtasks` / `task-master clear-subtasks` (see [`taskmaster.mdc`](mdc:.cursor/rules/taskmaster.mdc)).
+
+## Implementation Drift Handling
 
-- **Implementation Drift Handling**
 -   When implementation differs significantly from planned approach
 -   When future tasks need modification due to current implementation choices
 -   When new dependencies or requirements emerge
-  - Call `node scripts/dev.js update --from=<futureTaskId> --prompt="<explanation>"` to update tasks.json
+-   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>\nUpdate context...'` (see [`taskmaster.mdc`](mdc:.cursor/rules/taskmaster.mdc)) to update a single specific task.
+
+## Task Status Management
 
-- **Task Status Management**
 -   Use 'pending' for tasks ready to be worked on
 -   Use 'done' for completed and verified tasks
 -   Use 'deferred' for postponed tasks
 -   Add custom status values as needed for project-specific workflows
 
-- **Task File Format Reference**
-  ```
-  # Task ID: <id>
-  # Title: <title>
-  # Status: <status>
-  # Dependencies: <comma-separated list of dependency IDs>
-  # Priority: <priority>
-  # Description: <brief description>
-  # Details:
-  <detailed implementation notes>
+## Task Structure Fields
 
-  # Test Strategy:
-  <verification approach>
-  ```
-
-- **Command Reference: parse-prd**
-  - Legacy Syntax: `node scripts/dev.js parse-prd --input=<prd-file.txt>`
-  - CLI Syntax: `task-master parse-prd --input=<prd-file.txt>`
-  - Description: Parses a PRD document and generates a tasks.json file with structured tasks
-  - Parameters: 
-    - `--input=<file>`: Path to the PRD text file (default: sample-prd.txt)
-  - Example: `task-master parse-prd --input=requirements.txt`
-  - Notes: Will overwrite existing tasks.json file. Use with caution.
-
-- **Command Reference: update**
-  - Legacy Syntax: `node scripts/dev.js update --from=<id> --prompt="<prompt>"`
-  - CLI Syntax: `task-master update --from=<id> --prompt="<prompt>"`
-  - Description: Updates tasks with ID >= specified ID based on the provided prompt
-  - Parameters:
-    - `--from=<id>`: Task ID from which to start updating (required)
-    - `--prompt="<text>"`: Explanation of changes or new context (required)
-  - Example: `task-master update --from=4 --prompt="Now we are using Express instead of Fastify."`
-  - Notes: Only updates tasks not marked as 'done'. Completed tasks remain unchanged.
-
-- **Command Reference: generate**
-  - Legacy Syntax: `node scripts/dev.js generate`
-  - CLI Syntax: `task-master generate`
-  - Description: Generates individual task files in tasks/ directory based on tasks.json
-  - Parameters: 
-    - `--file=<path>, -f`: Use alternative tasks.json file (default: 'tasks/tasks.json')
-    - `--output=<dir>, -o`: Output directory (default: 'tasks')
-  - Example: `task-master generate`
-  - Notes: Overwrites existing task files. Creates tasks/ directory if needed.
-
-- **Command Reference: set-status**
-  - Legacy Syntax: `node scripts/dev.js set-status --id=<id> --status=<status>`
-  - CLI Syntax: `task-master set-status --id=<id> --status=<status>`
-  - Description: Updates the status of a specific task in tasks.json
-  - Parameters:
-    - `--id=<id>`: ID of the task to update (required)
-    - `--status=<status>`: New status value (required)
-  - Example: `task-master set-status --id=3 --status=done`
-  - Notes: Common values are 'done', 'pending', and 'deferred', but any string is accepted.
-
-- **Command Reference: list**
-  - Legacy Syntax: `node scripts/dev.js list`
-  - CLI Syntax: `task-master list`
-  - Description: Lists all tasks in tasks.json with IDs, titles, and status
-  - Parameters: 
-    - `--status=<status>, -s`: Filter by status
-    - `--with-subtasks`: Show subtasks for each task
-    - `--file=<path>, -f`: Use alternative tasks.json file (default: 'tasks/tasks.json')
-  - Example: `task-master list`
-  - Notes: Provides quick overview of project progress. Use at start of sessions.
-
-- **Command Reference: expand**
-  - Legacy Syntax: `node scripts/dev.js expand --id=<id> [--num=<number>] [--research] [--prompt="<context>"]`
-  - CLI Syntax: `task-master expand --id=<id> [--num=<number>] [--research] [--prompt="<context>"]`
-  - Description: Expands a task with subtasks for detailed implementation
-  - Parameters:
-    - `--id=<id>`: ID of task to expand (required unless using --all)
-    - `--all`: Expand all pending tasks, prioritized by complexity
-    - `--num=<number>`: Number of subtasks to generate (default: from complexity report)
-    - `--research`: Use Perplexity AI for research-backed generation
-    - `--prompt="<text>"`: Additional context for subtask generation
-    - `--force`: Regenerate subtasks even for tasks that already have them
-  - Example: `task-master expand --id=3 --num=5 --research --prompt="Focus on security aspects"`
-  - Notes: Uses complexity report recommendations if available.
-
-- **Command Reference: analyze-complexity**
-  - Legacy Syntax: `node scripts/dev.js analyze-complexity [options]`
-  - CLI Syntax: `task-master analyze-complexity [options]`
-  - Description: Analyzes task complexity and generates expansion recommendations
-  - Parameters:
-    - `--output=<file>, -o`: Output file path (default: scripts/task-complexity-report.json)
-    - `--model=<model>, -m`: Override LLM model to use
-    - `--threshold=<number>, -t`: Minimum score for expansion recommendation (default: 5)
-    - `--file=<path>, -f`: Use alternative tasks.json file
-    - `--research, -r`: Use Perplexity AI for research-backed analysis
-  - Example: `task-master analyze-complexity --research`
-  - Notes: Report includes complexity scores, recommended subtasks, and tailored prompts.
-
-- **Command Reference: clear-subtasks**
-  - Legacy Syntax: `node scripts/dev.js clear-subtasks --id=<id>`
-  - CLI Syntax: `task-master clear-subtasks --id=<id>`
-  - Description: Removes subtasks from specified tasks to allow regeneration
-  - Parameters:
-    - `--id=<id>`: ID or comma-separated IDs of tasks to clear subtasks from
-    - `--all`: Clear subtasks from all tasks
-  - Examples:
-    - `task-master clear-subtasks --id=3`
-    - `task-master clear-subtasks --id=1,2,3`
-    - `task-master clear-subtasks --all`
-  - Notes: 
-    - Task files are automatically regenerated after clearing subtasks
-    - Can be combined with expand command to immediately generate new subtasks
-    - Works with both parent tasks and individual subtasks
-
-- **Task Structure Fields**
-  - **id**: Unique identifier for the task (Example: `1`)
+- **id**: Unique identifier for the task (Example: `1`, `1.1`)
 - **title**: Brief, descriptive title (Example: `"Initialize Repo"`)
 - **description**: Concise summary 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 prerequisite tasks (Example: `[1, 2]`)
+- **dependencies**: IDs of prerequisite tasks (Example: `[1, 2.1]`)
     - Dependencies are displayed with status indicators (✅ for completed, ⏱️ for pending)
     - This helps quickly identify which prerequisite tasks are blocking work
 - **priority**: Importance level (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 (Example: `[{"id": 1, "title": "Configure OAuth", ...}]`) 
+- Refer to [`tasks.mdc`](mdc:.cursor/rules/tasks.mdc) for more details on the task data structure.
 
-- **Environment Variables Configuration**
-  - **ANTHROPIC_API_KEY** (Required): Your Anthropic API key for Claude (Example: `ANTHROPIC_API_KEY=sk-ant-api03-...`)
-  - **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`)
+## Environment Variables Configuration
 
-- **Determining the Next Task**
-  - Run `task-master next` to show the next task to work on
-  - The next command identifies tasks with all dependencies satisfied
+- Task Master behavior is configured via environment variables:
+  - **ANTHROPIC_API_KEY** (Required): Your Anthropic API key for Claude.
+  - **MODEL**: Claude model to use (e.g., `claude-3-opus-20240229`).
+  - **MAX_TOKENS**: Maximum tokens for AI responses.
+  - **TEMPERATURE**: Temperature for AI model responses.
+  - **DEBUG**: Enable debug logging (`true`/`false`).
+  - **LOG_LEVEL**: Console output level (`debug`, `info`, `warn`, `error`).
+  - **DEFAULT_SUBTASKS**: Default number of subtasks for `expand`.
+  - **DEFAULT_PRIORITY**: Default priority for new tasks.
+  - **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 (e.g., `sonar-medium-online`).
+- See [`taskmaster.mdc`](mdc:.cursor/rules/taskmaster.mdc) for default values and examples.
+
+## Determining the Next Task
+
+- Run `next_task` / `task-master next` (see [`taskmaster.mdc`](mdc:.cursor/rules/taskmaster.mdc)) to show the next task to work on
+- The command identifies tasks with all dependencies satisfied
 - Tasks are prioritized by priority level, dependency count, and ID
 - The command shows comprehensive task information including:
     - Basic task details and description
@@ -212,8 +131,9 @@ alwaysApply: true
 - Ensures tasks are completed in the appropriate sequence
 - Provides ready-to-use commands for common task actions
 
-- **Viewing Specific Task Details**
-  - Run `task-master show <id>` or `task-master show --id=<id>` to view a specific task
+## Viewing Specific Task Details
+
+- Run `get_task` / `task-master show <id>` (see [`taskmaster.mdc`](mdc:.cursor/rules/taskmaster.mdc)) to view a specific task
 - Use dot notation for subtasks: `task-master show 1.2` (shows subtask 2 of task 1)
 - Displays comprehensive information similar to the next command, but for a specific task
 - For parent tasks, shows all subtasks and their current status
@@ -221,113 +141,75 @@ alwaysApply: true
 - Provides contextual suggested actions appropriate for the specific task
 - Useful for examining task details before implementation or checking status
 
-- **Managing Task Dependencies**
-  - Use `task-master add-dependency --id=<id> --depends-on=<id>` to add a dependency
-  - Use `task-master remove-dependency --id=<id> --depends-on=<id>` to remove a dependency
+## Managing Task Dependencies
+
+- Use `add_dependency` / `task-master add-dependency --id=<id> --depends-on=<id>` (see [`taskmaster.mdc`](mdc:.cursor/rules/taskmaster.mdc)) to add a dependency
+- Use `remove_dependency` / `task-master remove-dependency --id=<id> --depends-on=<id>` (see [`taskmaster.mdc`](mdc:.cursor/rules/taskmaster.mdc)) to remove a dependency
 - The system prevents circular dependencies and duplicate dependency entries
 - Dependencies are checked for existence before being added or removed
 - Task files are automatically regenerated after dependency changes
 - Dependencies are visualized with status indicators in task listings and files
 
-- **Command Reference: add-dependency**
-  - Legacy Syntax: `node scripts/dev.js add-dependency --id=<id> --depends-on=<id>`
-  - CLI Syntax: `task-master add-dependency --id=<id> --depends-on=<id>`
-  - Description: Adds a dependency relationship between two tasks
-  - Parameters:
-    - `--id=<id>`: ID of task that will depend on another task (required)
-    - `--depends-on=<id>`: ID of task that will become a dependency (required)
-  - Example: `task-master add-dependency --id=22 --depends-on=21`
-  - Notes: Prevents circular dependencies and duplicates; updates task files automatically
+## Iterative Subtask Implementation
 
-- **Command Reference: remove-dependency**
-  - Legacy Syntax: `node scripts/dev.js remove-dependency --id=<id> --depends-on=<id>`
-  - CLI Syntax: `task-master remove-dependency --id=<id> --depends-on=<id>`
-  - Description: Removes a dependency relationship between two tasks
-  - Parameters:
-    - `--id=<id>`: ID of task to remove dependency from (required)
-    - `--depends-on=<id>`: ID of task to remove as a dependency (required)
-  - Example: `task-master remove-dependency --id=22 --depends-on=21`
-  - Notes: Checks if dependency actually exists; updates task files automatically
+Once a task has been broken down into subtasks using `expand_task` or similar methods, follow this iterative process for implementation:
 
-- **Command Reference: validate-dependencies**
-  - Legacy Syntax: `node scripts/dev.js validate-dependencies [options]`
-  - CLI Syntax: `task-master validate-dependencies [options]`
-  - Description: Checks for and identifies invalid dependencies in tasks.json and task files
-  - Parameters:
-    - `--file=<path>, -f`: Use alternative tasks.json file (default: 'tasks/tasks.json')
-  - Example: `task-master validate-dependencies`
-  - Notes: 
-    - Reports all non-existent dependencies and self-dependencies without modifying files
-    - Provides detailed statistics on task dependency state
-    - Use before fix-dependencies to audit your task structure
+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.
 
-- **Command Reference: fix-dependencies**
-  - Legacy Syntax: `node scripts/dev.js fix-dependencies [options]`
-  - CLI Syntax: `task-master fix-dependencies [options]`
-  - Description: Finds and fixes all invalid dependencies in tasks.json and task files
-  - Parameters:
-    - `--file=<path>, -f`: Use alternative tasks.json file (default: 'tasks/tasks.json')
-  - Example: `task-master fix-dependencies`
-  - Notes: 
-    - Removes references to non-existent tasks and subtasks
-    - Eliminates self-dependencies (tasks depending on themselves)
-    - Regenerates task files with corrected dependencies
-    - Provides detailed report of all fixes made
+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.
 
-- **Command Reference: complexity-report**
-  - Legacy Syntax: `node scripts/dev.js complexity-report [options]`
-  - CLI Syntax: `task-master complexity-report [options]`
-  - Description: Displays the task complexity analysis report in a formatted, easy-to-read way
-  - Parameters:
-    - `--file=<path>, -f`: Path to the complexity report file (default: 'scripts/task-complexity-report.json')
-  - Example: `task-master complexity-report`
-  - Notes: 
-    - Shows tasks organized by complexity score with recommended actions
-    - Provides complexity distribution statistics
-    - Displays ready-to-use expansion commands for complex tasks
-    - If no report exists, offers to generate one interactively
+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`.
 
-- **Command Reference: add-task**
-  - CLI Syntax: `task-master add-task [options]`
-  - Description: Add a new task to tasks.json using AI
-  - Parameters:
-    - `--file=<path>, -f`: Path to the tasks file (default: 'tasks/tasks.json')
-    - `--prompt=<text>, -p`: Description of the task to add (required)
-    - `--dependencies=<ids>, -d`: Comma-separated list of task IDs this task depends on
-    - `--priority=<priority>`: Task priority (high, medium, low) (default: 'medium')
-  - Example: `task-master add-task --prompt="Create user authentication using Auth0"`
-  - Notes: Uses AI to convert description into structured task with appropriate 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.
 
-- **Command Reference: init**
-  - CLI Syntax: `task-master init`
-  - Description: Initialize a new project with Task Master structure
-  - Parameters: None
-  - Example: `task-master init`
-  - Notes: 
-    - Creates initial project structure with required files
-    - Prompts for project settings if not provided
-    - Merges with existing files when appropriate
-    - Can be used to bootstrap a new Task Master project quickly
+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.
 
-- **Code Analysis & Refactoring Techniques**
-  - **Top-Level Function Search**
-    - Use grep pattern matching to find all exported functions across the codebase
-    - Command: `grep -E "export (function|const) \w+|function \w+\(|const \w+ = \(|module\.exports" --include="*.js" -r ./`
-    - Benefits:
-      - Quickly identify all public API functions without reading implementation details
-      - Compare functions between files during refactoring (e.g., monolithic to modular structure)
-      - Verify all expected functions exist in refactored modules
-      - Identify duplicate functionality or naming conflicts
-    - Usage examples:
-      - When migrating from `scripts/dev.js` to modular structure: `grep -E "function \w+\(" scripts/dev.js`
-      - Check function exports in a directory: `grep -E "export (function|const)" scripts/modules/`
-      - Find potential naming conflicts: `grep -E "function (get|set|create|update)\w+\(" -r ./`
-    - Variations:
-      - Add `-n` flag to include line numbers
-      - Add `--include="*.ts"` to filter by file extension
-      - Use with `| sort` to alphabetize results
-    - Integration with refactoring workflow:
-      - Start by mapping all functions in the source file
-      - Create target module files based on function grouping
-      - Verify all functions were properly migrated
-      - Check for any unintentional duplications or omissions
+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**:
+    - Useful for understanding module structure or planning refactors.
+    - Use grep/ripgrep to find exported functions/constants:
+      `rg "export (async function|function|const) \w+"` or similar patterns.
+    - Can help compare functions between files during migrations or identify potential naming conflicts.
+
+---
+*This workflow provides a general guideline. Adapt it based on your specific project needs and team practices.*

.cursor/rules/glossary.mdc

@@ -0,0 +1,26 @@
+---
+description: Glossary of other Cursor rules
+globs: **/*
+alwaysApply: true
+---
+
+# Glossary of Task Master Cursor Rules
+
+This file provides a quick reference to the purpose of each rule file located in the `.cursor/rules` directory.
+
+- **[`architecture.mdc`](mdc:.cursor/rules/architecture.mdc)**: Describes the high-level architecture of the Task Master CLI application.
+- **[`changeset.mdc`](mdc:.cursor/rules/changeset.mdc)**: Guidelines for using Changesets (npm run changeset) to manage versioning and changelogs.
+- **[`commands.mdc`](mdc:.cursor/rules/commands.mdc)**: Guidelines for implementing CLI commands using Commander.js.
+- **[`cursor_rules.mdc`](mdc:.cursor/rules/cursor_rules.mdc)**: Guidelines for creating and maintaining Cursor rules to ensure consistency and effectiveness.
+- **[`dependencies.mdc`](mdc:.cursor/rules/dependencies.mdc)**: Guidelines for managing task dependencies and relationships.
+- **[`dev_workflow.mdc`](mdc:.cursor/rules/dev_workflow.mdc)**: Guide for using Task Master to manage task-driven development workflows.
+- **[`glossary.mdc`](mdc:.cursor/rules/glossary.mdc)**: This file; provides a glossary of other Cursor rules.
+- **[`mcp.mdc`](mdc:.cursor/rules/mcp.mdc)**: Guidelines for implementing and interacting with the Task Master MCP Server.
+- **[`new_features.mdc`](mdc:.cursor/rules/new_features.mdc)**: Guidelines for integrating new features into the Task Master CLI.
+- **[`self_improve.mdc`](mdc:.cursor/rules/self_improve.mdc)**: Guidelines for continuously improving Cursor rules based on emerging code patterns and best practices.
+- **[`taskmaster.mdc`](mdc:.cursor/rules/taskmaster.mdc)**: Comprehensive reference for Taskmaster MCP tools and CLI commands.
+- **[`tasks.mdc`](mdc:.cursor/rules/tasks.mdc)**: Guidelines for implementing task management operations.
+- **[`tests.mdc`](mdc:.cursor/rules/tests.mdc)**: Guidelines for implementing and maintaining tests for Task Master CLI.
+- **[`ui.mdc`](mdc:.cursor/rules/ui.mdc)**: Guidelines for implementing and maintaining user interface components.
+- **[`utilities.mdc`](mdc:.cursor/rules/utilities.mdc)**: Guidelines for implementing utility functions.
+

.cursor/rules/mcp.mdc

@@ -0,0 +1,644 @@
+---
+description: Guidelines for implementing and interacting with the Task Master MCP Server
+globs: mcp-server/src/**/*, scripts/modules/**/*
+alwaysApply: false
+---
+
+# Task Master MCP Server Guidelines
+
+This document outlines the architecture and implementation patterns for the Task Master Model Context Protocol (MCP) server, designed for integration with tools like Cursor.
+
+## Architecture Overview (See also: [`architecture.mdc`](mdc:.cursor/rules/architecture.mdc))
+
+The MCP server acts as a bridge between external tools (like Cursor) and the core Task Master CLI logic. It leverages FastMCP for the server framework.
+
+- **Flow**: `External Tool (Cursor)` <-> `FastMCP Server` <-> `MCP Tools` (`mcp-server/src/tools/*.js`) <-> `Core Logic Wrappers` (`mcp-server/src/core/direct-functions/*.js`, exported via `task-master-core.js`) <-> `Core Modules` (`scripts/modules/*.js`)
+- **Goal**: Provide a performant and reliable way for external tools to interact with Task Master functionality without directly invoking the CLI for every operation.
+
+## Direct Function Implementation Best Practices
+
+When implementing a new direct function in `mcp-server/src/core/direct-functions/`, follow these critical guidelines:
+
+1. **Verify Function Dependencies**:
+   - ✅ **DO**: Check that all helper functions your direct function needs are properly exported from their source modules
+   - ✅ **DO**: Import these dependencies explicitly at the top of your file
+   - ❌ **DON'T**: Assume helper functions like `findTaskById` or `taskExists` are automatically available
+   - **Example**:
+     ```javascript
+     // At top of direct-function file
+     import { removeTask, findTaskById, taskExists } from '../../../../scripts/modules/task-manager.js';
+     ```
+
+2. **Parameter Verification and Completeness**:
+   - ✅ **DO**: Verify the signature of core functions you're calling and ensure all required parameters are provided
+   - ✅ **DO**: Pass explicit values for required parameters rather than relying on defaults
+   - ✅ **DO**: Double-check parameter order against function definition
+   - ❌ **DON'T**: Omit parameters assuming they have default values
+   - **Example**:
+     ```javascript
+     // Correct parameter handling in direct function
+     async function generateTaskFilesDirect(args, log) {
+       const tasksPath = findTasksJsonPath(args, log);
+       const outputDir = args.output || path.dirname(tasksPath);
+       
+       try {
+         // Pass all required parameters
+         const result = await generateTaskFiles(tasksPath, outputDir);
+         return { success: true, data: result, fromCache: false };
+       } catch (error) {
+         // Error handling...
+       }
+     }
+     ```
+
+3. **Consistent File Path Handling**:
+   - ✅ **DO**: Use `path.join()` instead of string concatenation for file paths
+   - ✅ **DO**: Follow established file naming conventions (`task_001.txt` not `1.md`)
+   - ✅ **DO**: Use `path.dirname()` and other path utilities for manipulating paths
+   - ✅ **DO**: When paths relate to task files, follow the standard format: `task_${id.toString().padStart(3, '0')}.txt`
+   - ❌ **DON'T**: Create custom file path handling logic that diverges from established patterns
+   - **Example**:
+     ```javascript
+     // Correct file path handling
+     const taskFilePath = path.join(
+       path.dirname(tasksPath),
+       `task_${taskId.toString().padStart(3, '0')}.txt`
+     );
+     ```
+
+4. **Comprehensive Error Handling**:
+   - ✅ **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 (`{ success: false, error: { code: '...', message: '...' } }`)
+   - ✅ **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 or AI logic
+     } catch (error) {
+       log.error(`Failed to execute direct function logic: ${error.message}`);
+       return {
+         success: false,
+         error: {
+           code: error.code || 'DIRECT_FUNCTION_ERROR', // Use specific codes like AI_CLIENT_ERROR, etc.
+           message: error.message,
+           details: error.stack // Optional: Include stack in debug mode
+         },
+         fromCache: false // Ensure this is included if applicable
+       };
+     }
+     ```
+
+5. **Handling Logging Context (`mcpLog`)**:
+   - **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
+     // Standard logWrapper pattern within a Direct Function
+     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), // Handle optional debug
+       success: (message, ...args) => log.info(message, ...args) // Map success to info if needed
+     };
+
+     // ... later when calling the core function ...
+     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.
+
+6. **Silent Mode Implementation**:
+    - ✅ **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.
+      - **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.
+      - **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.
+    - ✅ **DO**: Use `isSilentMode()` function to check global silent mode status if needed (rare in direct functions), NEVER access the global `silentMode` variable directly.
+    - ❌ **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).
+    - ❌ **DON'T**: Assume a core function is silent just because it *should* be. Verify or use the `enable/disableSilentMode` wrapper.
+    - **Example (Direct Function Guaranteeing Silence and using Log Wrapper)**:
+      ```javascript
+      export async function coreWrapperDirect(args, log, context = {}) {
+        const { session } = context;
+        const tasksPath = findTasksJsonPath(args, log);
+        
+        // Create the logger wrapper
+        const logWrapper = { /* ... as defined above ... */ };
+
+        enableSilentMode(); // Ensure silence for direct console output
+        try {
+          // Call core function, passing wrapper and 'json' format
+          const result = await coreFunction(
+             tasksPath, 
+             args.param1, 
+             { 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
+
+### Tool Structure
+
+MCP tools must follow a specific structure to properly interact with the FastMCP framework:
+
+```javascript
+server.addTool({
+  name: "tool_name",  // Use snake_case for tool names
+  description: "Description of what the tool does",
+  parameters: z.object({
+    // Define parameters using Zod
+    param1: z.string().describe("Parameter description"),
+    param2: z.number().optional().describe("Optional parameter description"),
+    // IMPORTANT: For file operations, always include these optional parameters
+    file: z.string().optional().describe("Path to the tasks file"),
+    projectRoot: z.string().optional().describe("Root directory of the project (typically derived from session)")
+  }),
+
+  // The execute function is the core of the tool implementation
+  execute: async (args, context) => {
+    // Implementation goes here
+    // Return response in the appropriate format
+  }
+});
+```
+
+### Execute Function Signature
+
+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**: 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
+
+The `execute` method within each MCP tool (in `mcp-server/src/tools/*.js`) should follow this standard pattern:
+
+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`. 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 for a tool calling an AI-based direct function
+import { getProjectRootFromSession, handleApiResult, createErrorResponse } from './utils.js';
+import { someAIDirectFunction } from '../core/task-master-core.js';
+
+// ... inside server.addTool({...})
+execute: async (args, { log, session }) => { // Note: reportProgress is omitted here
+  try {
+    log.info(`Starting AI tool execution with args: ${JSON.stringify(args)}`);
+
+    // 1. Get Project Root
+    let rootFolder = getProjectRootFromSession(session, log);
+    if (!rootFolder && args.projectRoot) { // Fallback if needed
+      rootFolder = args.projectRoot;
+      log.info(`Using project root from args as fallback: ${rootFolder}`);
+    }
+
+    // 2. Call AI-Based Direct Function (passing only log and session in context)
+    const result = await someAIDirectFunction({
+      ...args,
+      projectRoot: rootFolder // Ensure projectRoot is explicitly passed
+    }, log, { session }); // Pass session here, NO reportProgress
+
+    // 3. Handle and Format Response
+    return handleApiResult(result, log);
+
+  } catch (error) {
+    log.error(`Error during AI tool execution: ${error.message}`);
+    return createErrorResponse(error.message);
+  }
+}
+```
+
+### Using AsyncOperationManager for Background Tasks
+
+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 '../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, session }) => { // Note: reportProgress omitted
+  try {
+    log.info(`Starting background operation with args: ${JSON.stringify(args)}`);
+
+    // 1. Get Project Root
+    let rootFolder = getProjectRootFromSession(session, log);
+    if (!rootFolder && args.projectRoot) {
+      rootFolder = args.projectRoot;
+      log.info(`Using project root from args as fallback: ${rootFolder}`);
+    }
+    
+    // Create operation description
+    const operationDescription = `Expanding task ${args.id}...`; // Example
+
+    // 2. Start async operation using AsyncOperationManager
+    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 {
+        status: 202, // StatusCodes.ACCEPTED
+        body: {
+            success: true,
+            message: 'Operation started',
+            operationId: operation.id
+        }
+    };
+  } catch (error) {
+    log.error(`Error starting background operation: ${error.message}`);
+    return createErrorResponse(`Failed to start operation: ${error.message}`); // Use standard error response
+  }
+}
+```
+
+### Project Initialization Tool
+
+The `initialize_project` tool allows integrated clients like Cursor to set up a new Task Master project:
+
+```javascript
+// In initialize-project.js
+import { z } from "zod";
+import { initializeProjectDirect } from "../core/task-master-core.js";
+import { handleApiResult, createErrorResponse } from "./utils.js";
+
+export function registerInitializeProjectTool(server) {
+  server.addTool({
+    name: "initialize_project",
+    description: "Initialize a new Task Master project",
+    parameters: z.object({
+      projectName: z.string().optional().describe("The name for the new project"),
+      projectDescription: z.string().optional().describe("A brief description"),
+      projectVersion: z.string().optional().describe("Initial version (e.g., '0.1.0')"),
+      authorName: z.string().optional().describe("The author's name"),
+      skipInstall: z.boolean().optional().describe("Skip installing dependencies"),
+      addAliases: z.boolean().optional().describe("Add shell aliases"),
+      yes: z.boolean().optional().describe("Skip prompts and use defaults")
+    }),
+    execute: async (args, { log, reportProgress }) => {
+      try {
+        // Since we're initializing, we don't need project root
+        const result = await initializeProjectDirect(args, log);
+        return handleApiResult(result, log, 'Error initializing project');
+      } catch (error) {
+        log.error(`Error in initialize_project: ${error.message}`);
+        return createErrorResponse(`Failed to initialize project: ${error.message}`);
+      }
+    }
+  });
+}
+```
+
+### Logging Convention
+
+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
+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
+
+- ⚠️ **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*.
+- ✅ **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...')`).
+
+### Session Usage Convention
+
+The `session` object (destructured from `context`) contains authenticated session data and client information.
+
+- **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/*`). Handle AI interactions if applicable.
+- **Responsibilities**:
+  - 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).
+  - Validate arguments specific to the core logic.
+  - **Handle AI Logic (if applicable)**: Initialize AI clients (using `session` from context), build prompts, make AI calls, parse responses.
+  - **Implement Caching (if applicable)**: Use `getCachedOrExecute` from [`tools/utils.js`](mdc:mcp-server/src/tools/utils.js) for read operations.
+  - **Call Core Logic**: Call the underlying function from the core Task Master modules, passing necessary data (including AI results if applicable).
+    - ✅ **DO**: Pass `outputFormat: 'json'` (or similar) to the core function if it might produce console output.
+    - ✅ **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 / 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`.
+- **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.
+- **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`, `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
+
+Resources provide LLMs with static or dynamic data without executing tools.
+
+- **Implementation**: Use `@mcp.resource()` decorator pattern or `server.addResource`/`server.addResourceTemplate` in `mcp-server/src/core/resources/`.
+- **Registration**: Register resources during server initialization in [`mcp-server/src/index.js`](mdc:mcp-server/src/index.js).
+- **Best Practices**: Organize resources, validate parameters, use consistent URIs, handle errors. See [`fastmcp-core.txt`](docs/fastmcp-core.txt) for underlying SDK details.
+
+*(Self-correction: Removed detailed Resource implementation examples as they were less relevant to the current user focus on tool execution flow and project roots. Kept the overview.)*
+
+## Implementing MCP Support for a Command
+
+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/`. 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`, silent mode utilities, and potentially AI client/prompt utilities.
+    - 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 `tasksPath` using `findTasksJsonPath(args, log)`.
+        - Parse other `args` and perform necessary validation.
+        - **Handle AI (if applicable)**: Initialize clients using `get*ClientForMCP(session, log)`, build prompts, call AI, parse response. Handle AI-specific errors.
+        - **Implement Caching (if applicable)**: Use `getCachedOrExecute`.
+        - **Call Core Logic**:
+            - 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 `AsyncOperationManager` if needed.
+    - Implement `registerYourCommandTool(server)`.
+    - Define the tool `name` using **snake_case** (e.g., `your_command`).
+    - Define the `parameters` using `zod`. Include `projectRoot: z.string().optional()`.
+    - Implement the `async execute(args, { log, session })` method (omitting `reportProgress` from destructuring).
+        - Get `rootFolder` using `getProjectRootFromSession(session, log)`.
+        - **Determine Execution Strategy**:
+            - **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`.
+
+6.  **Update `mcp.json`**: Add the new tool definition to the `tools` array in `.cursor/mcp.json`.
+
+## Handling Responses
+
+- MCP tools should return the object generated by `handleApiResult`.
+- `handleApiResult` uses `createContentResponse` or `createErrorResponse` internally.
+- `handleApiResult` also uses `processMCPResponseData` by default to filter potentially large fields (`details`, `testStrategy`) from task data. Provide a custom processor function to `handleApiResult` if different filtering is needed.
+- The final JSON response sent to the MCP client will include the `fromCache` boolean flag (obtained from the `*Direct` function's result) alongside the actual data (e.g., `{ "fromCache": true, "data": { ... } }` or `{ "fromCache": false, "data": { ... } }`).
+
+## Parameter Type Handling
+
+- **Prefer Direct Function Calls**: For optimal performance and error handling, MCP tools should utilize direct function wrappers defined in [`task-master-core.js`](mdc:mcp-server/src/core/task-master-core.js). These wrappers call the underlying logic from the core modules (e.g., [`task-manager.js`](mdc:scripts/modules/task-manager.js)).
+- **Standard Tool Execution Pattern**:
+    - The `execute` method within each MCP tool (in `mcp-server/src/tools/*.js`) should:
+        1.  Call the corresponding `*Direct` function wrapper (e.g., `listTasksDirect`) from [`task-master-core.js`](mdc:mcp-server/src/core/task-master-core.js), passing necessary arguments and the logger.
+        2.  Receive the result object (typically `{ success, data/error, fromCache }`).
+        3.  Pass this result object to the `handleApiResult` utility (from [`tools/utils.js`](mdc:mcp-server/src/tools/utils.js)) for standardized response formatting and error handling.
+        4.  Return the formatted response object provided by `handleApiResult`.
+- **CLI Execution as Fallback**: The `executeTaskMasterCommand` utility in [`tools/utils.js`](mdc:mcp-server/src/tools/utils.js) allows executing commands via the CLI (`task-master ...`). This should **only** be used as a fallback if a direct function wrapper is not yet implemented or if a specific command intrinsically requires CLI execution.
+- **Centralized Utilities** (See also: [`utilities.mdc`](mdc:.cursor/rules/utilities.mdc)):
+    - Use `findTasksJsonPath` (in [`task-master-core.js`](mdc:mcp-server/src/core/task-master-core.js)) *within direct function wrappers* to locate the `tasks.json` file consistently.
+    - **Leverage MCP Utilities**: The file [`tools/utils.js`](mdc:mcp-server/src/tools/utils.js) contains essential helpers for MCP tool implementation:
+        - `getProjectRoot`: Normalizes project paths.
+        - `handleApiResult`: Takes the raw result from a `*Direct` function and formats it into a standard MCP success or error response, automatically handling data processing via `processMCPResponseData`. This is called by the tool's `execute` method.
+        - `createContentResponse`/`createErrorResponse`: Used by `handleApiResult` to format successful/error MCP responses.
+        - `processMCPResponseData`: Filters/cleans data (e.g., removing `details`, `testStrategy`) before it's sent in the MCP response. Called by `handleApiResult`.
+        - `getCachedOrExecute`: **Used inside `*Direct` functions** in `task-master-core.js` to implement caching logic.
+        - `executeTaskMasterCommand`: Fallback for executing CLI commands.
+- **Caching**: To improve performance for frequently called read operations (like `listTasks`, `showTask`, `nextTask`), a caching layer using `lru-cache` is implemented.
+    - **Caching logic resides *within* the direct function wrappers** in [`task-master-core.js`](mdc:mcp-server/src/core/task-master-core.js) using the `getCachedOrExecute` utility from [`tools/utils.js`](mdc:mcp-server/src/tools/utils.js).
+    - Generate unique cache keys based on function arguments that define a distinct call (e.g., file path, filters).
+    - The `getCachedOrExecute` utility handles checking the cache, executing the core logic function on a cache miss, storing the result, and returning the data along with a `fromCache` flag.
+    - Cache statistics can be monitored using the `cacheStats` MCP tool (implemented via `getCacheStatsDirect`).
+    - **Caching should generally be applied to read-only operations** that don't modify the `tasks.json` state. Commands like `set-status`, `add-task`, `update-task`, `parse-prd`, `add-dependency` should *not* be cached as they change the underlying data.
+
+**MCP Tool Implementation Checklist**:
+
+1. **Core Logic Verification**:
+   - [ ] Confirm the core function is properly exported from its module (e.g., `task-manager.js`)
+   - [ ] Identify all required parameters and their types
+
+2. **Direct Function Wrapper**:
+   - [ ] Create the `*Direct` function in the appropriate file in `mcp-server/src/core/direct-functions/`
+   - [ ] Import silent mode utilities and implement them around core function calls
+   - [ ] Handle all parameter validations and type conversions
+   - [ ] Implement path resolving for relative paths
+   - [ ] Add appropriate error handling with standardized error codes
+   - [ ] Add to imports/exports in `task-master-core.js`
+
+3. **MCP Tool Implementation**:
+   - [ ] Create new file in `mcp-server/src/tools/` with kebab-case naming
+   - [ ] Define zod schema for all parameters
+   - [ ] Implement the `execute` method following the standard pattern
+   - [ ] Consider using AsyncOperationManager for long-running operations
+   - [ ] Register tool in `mcp-server/src/tools/index.js`
+
+4. **Testing**:
+   - [ ] Write unit tests for the direct function wrapper
+   - [ ] Write integration tests for the MCP tool
+
+## Standard Error Codes
+
+- **Standard Error Codes**: Use consistent error codes across direct function wrappers
+  - `INPUT_VALIDATION_ERROR`: For missing or invalid required parameters
+  - `FILE_NOT_FOUND_ERROR`: For file system path issues
+  - `CORE_FUNCTION_ERROR`: For errors thrown by the core function
+  - `UNEXPECTED_ERROR`: For all other unexpected errors
+
+- **Error Object Structure**:
+  ```javascript
+  {
+    success: false,
+    error: {
+      code: 'ERROR_CODE',
+      message: 'Human-readable error message'
+    },
+    fromCache: false
+  }
+  ```
+
+- **MCP Tool Logging Pattern**:
+  - ✅ DO: Log the start of execution with arguments (sanitized if sensitive)
+  - ✅ DO: Log successful completion with result summary
+  - ✅ DO: Log all error conditions with appropriate log levels
+  - ✅ DO: Include the cache status in result logs
+  - ❌ DON'T: Log entire large data structures or sensitive information
+
+- The MCP server integrates with Task Master core functions through three layers:
+  1. Tool Definitions (`mcp-server/src/tools/*.js`) - Define parameters and validation
+  2. Direct Functions (`mcp-server/src/core/direct-functions/*.js`) - Handle core logic integration
+  3. Core Functions (`scripts/modules/*.js`) - Implement the actual functionality
+
+- This layered approach provides:
+  - Clear separation of concerns
+  - Consistent parameter validation
+  - Centralized error handling
+  - Performance optimization through caching (for read operations)
+  - Standardized response formatting
+
+## MCP Naming Conventions
+
+- **Files and Directories**:
+  - ✅ DO: Use **kebab-case** for all file names: `list-tasks.js`, `set-task-status.js`
+  - ✅ DO: Use consistent directory structure: `mcp-server/src/tools/` for tool definitions, `mcp-server/src/core/direct-functions/` for direct function implementations
+
+- **JavaScript Functions**:
+  - ✅ DO: Use **camelCase** with `Direct` suffix for direct function implementations: `listTasksDirect`, `setTaskStatusDirect`
+  - ✅ DO: Use **camelCase** with `Tool` suffix for tool registration functions: `registerListTasksTool`, `registerSetTaskStatusTool`
+  - ✅ DO: Use consistent action function naming inside direct functions: `coreActionFn` or similar descriptive name
+
+- **MCP Tool Names**:
+  - ✅ DO: Use **snake_case** for tool names exposed to MCP clients: `list_tasks`, `set_task_status`, `parse_prd_document`
+  - ✅ DO: Include the core action in the tool name without redundant words: Use `list_tasks` instead of `list_all_tasks`
+
+- **Examples**:
+  - File: `list-tasks.js` 
+  - Direct Function: `listTasksDirect`
+  - Tool Registration: `registerListTasksTool`
+  - MCP Tool Name: `list_tasks`
+
+- **Mapping**:
+  - The `directFunctions` map in `task-master-core.js` maps the core function name (in camelCase) to its direct implementation:
+    ```javascript
+    export const directFunctions = {
+      list: listTasksDirect,
+      setStatus: setTaskStatusDirect,
+      // Add more functions as implemented
+    };
+    ```

.cursor/rules/new_features.mdc

@@ -8,14 +8,14 @@ alwaysApply: false
 
 ## Feature Placement Decision Process
 
-- **Identify Feature Type**:
-  - **Data Manipulation**: Features that create, read, update, or delete tasks belong in [`task-manager.js`](mdc:scripts/modules/task-manager.js)
-  - **Dependency Management**: Features that handle task relationships belong in [`dependency-manager.js`](mdc:scripts/modules/dependency-manager.js)
-  - **User Interface**: Features that display information to users belong in [`ui.js`](mdc:scripts/modules/ui.js)
-  - **AI Integration**: Features that use AI models belong in [`ai-services.js`](mdc:scripts/modules/ai-services.js)
+- **Identify Feature Type** (See [`architecture.mdc`](mdc:.cursor/rules/architecture.mdc) for module details):
+  - **Data Manipulation**: Features that create, read, update, or delete tasks belong in [`task-manager.js`](mdc:scripts/modules/task-manager.js). Follow guidelines in [`tasks.mdc`](mdc:.cursor/rules/tasks.mdc).
+  - **Dependency Management**: Features that handle task relationships belong in [`dependency-manager.js`](mdc:scripts/modules/dependency-manager.js). Follow guidelines in [`dependencies.mdc`](mdc:.cursor/rules/dependencies.mdc).
+  - **User Interface**: Features that display information to users belong in [`ui.js`](mdc:scripts/modules/ui.js). Follow guidelines in [`ui.mdc`](mdc:.cursor/rules/ui.mdc).
+  - **AI Integration**: Features that use AI models belong in [`ai-services.js`](mdc:scripts/modules/ai-services.js).
   - **Cross-Cutting**: Features that don't fit one category may need components in multiple modules
 
-- **Command-Line Interface**:
+- **Command-Line Interface** (See [`commands.mdc`](mdc:.cursor/rules/commands.mdc)):
   - All new user-facing commands should be added to [`commands.js`](mdc:scripts/modules/commands.js)
   - Use consistent patterns for option naming and help text
   - Follow the Commander.js model for subcommand structure
@@ -24,13 +24,172 @@ alwaysApply: false
 
 The standard pattern for adding a feature follows this workflow:
 
-1. **Core Logic**: Implement the business logic in the appropriate module
-2. **UI Components**: Add any display functions to [`ui.js`](mdc:scripts/modules/ui.js)
-3. **Command Integration**: Add the CLI command to [`commands.js`](mdc:scripts/modules/commands.js)
+1. **Core Logic**: Implement the business logic in the appropriate module (e.g., [`task-manager.js`](mdc:scripts/modules/task-manager.js)).
+2. **UI Components**: Add any display functions to [`ui.js`](mdc:scripts/modules/ui.js) following [`ui.mdc`](mdc:.cursor/rules/ui.mdc).
+3. **Command Integration**: Add the CLI command to [`commands.js`](mdc:scripts/modules/commands.js) following [`commands.mdc`](mdc:.cursor/rules/commands.mdc).
 4. **Testing**: Write tests for all components of the feature (following [`tests.mdc`](mdc:.cursor/rules/tests.mdc))
-5. **Configuration**: Update any configuration in [`utils.js`](mdc:scripts/modules/utils.js) if needed
+5. **Configuration**: Update any configuration in [`utils.js`](mdc:scripts/modules/utils.js) if needed, following [`utilities.mdc`](mdc:.cursor/rules/utilities.mdc).
 6. **Documentation**: Update help text and documentation in [dev_workflow.mdc](mdc:scripts/modules/dev_workflow.mdc)
 
+## Critical Checklist for New Features
+
+- **Comprehensive Function Exports**:
+  - ✅ **DO**: Export **all core functions, helper functions (like `generateSubtaskPrompt`), and utility methods** needed by your new function or command from their respective modules.
+  - ✅ **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 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:
+  export {
+    // ... existing exports ...
+    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 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
+  - ❌ **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));
+  
+  // ❌ DON'T: Omit required parameters
+  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 `path.join()` for composing file paths
+  - ✅ DO: Use appropriate file extensions (.txt for tasks, .json for data)
+  - ❌ DON'T: Hardcode path separators or inconsistent file extensions
+  - **Example**: Creating file paths for tasks:
+  ```javascript
+  // ✅ DO: Use consistent file naming and path.join
+  const taskFileName = path.join(
+    path.dirname(tasksPath), 
+    `task_${taskId.toString().padStart(3, '0')}.txt`
+  );
+  
+  // ❌ DON'T: Use inconsistent naming or string concatenation 
+  const taskFileName = path.dirname(tasksPath) + '/' + taskId + '.md';
+  ```
+
+- **Error Handling and Reporting**:
+  - ✅ DO: Use structured error objects with code and message properties
+  - ✅ DO: Include clear error messages identifying the specific problem
+  - ✅ DO: Handle both function-specific errors and potential file system errors
+  - ✅ DO: Log errors at appropriate severity levels
+  - **Example**: Structured error handling in core functions:
+  ```javascript
+  try {
+    // Implementation...
+  } catch (error) {
+    log('error', `Error removing task: ${error.message}`);
+    throw {
+      code: 'REMOVE_TASK_ERROR',
+      message: error.message,
+      details: error.stack
+    };
+  }
+  ```
+
+- **Silent Mode Implementation**:
+  - ✅ **DO**: Import all silent mode utilities together:
+    ```javascript
+    import { enableSilentMode, disableSilentMode, isSilentMode } from '../../../../scripts/modules/utils.js';
+    ```
+  - ✅ **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)
+
+      return { success: true, data: result };
+    } 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.
+
+- **Debugging Strategy**:
+  - ✅ **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.
+
 ```javascript
 // 1. CORE LOGIC: Add function to appropriate module (example in task-manager.js)
 /**
@@ -294,7 +453,7 @@ For each new feature:
 
 1. Add help text to the command definition
 2. Update [`dev_workflow.mdc`](mdc:scripts/modules/dev_workflow.mdc) with command reference
-3. Add examples to the appropriate sections in [`MODULE_PLAN.md`](mdc:scripts/modules/MODULE_PLAN.md)
+3. Consider updating [`architecture.mdc`](mdc:.cursor/rules/architecture.mdc) if the feature significantly changes module responsibilities.
 
 Follow the existing command reference format:
 ```markdown
@@ -309,3 +468,125 @@ Follow the existing command reference format:
 ```
 
 For more information on module structure, see [`MODULE_PLAN.md`](mdc:scripts/modules/MODULE_PLAN.md) and follow [`self_improve.mdc`](mdc:scripts/modules/self_improve.mdc) for best practices on updating documentation.
+
+## Adding MCP Server Support for Commands
+
+Integrating Task Master commands with the MCP server (for use by tools like Cursor) follows a specific pattern distinct from the CLI command implementation, prioritizing performance and reliability.
+
+- **Goal**: Leverage direct function calls to core logic, avoiding CLI overhead.
+- **Reference**: See [`mcp.mdc`](mdc:.cursor/rules/mcp.mdc) for full details.
+
+**MCP Integration Workflow**:
+
+1.  **Core Logic**: Ensure the command's core logic exists and is exported from the appropriate module (e.g., [`task-manager.js`](mdc:scripts/modules/task-manager.js)).
+2.  **Direct Function Wrapper (`mcp-server/src/core/direct-functions/`)**:
+    - Create a new file (e.g., `your-command.js`) in `mcp-server/src/core/direct-functions/` using **kebab-case** naming.
+    - Import the core logic function, necessary MCP utilities like **`findTasksJsonPath` from `../utils/path-utils.js`**, and **silent mode utilities**: `import { enableSilentMode, disableSilentMode } from '../../../../scripts/modules/utils.js';`
+    - Implement an `async function yourCommandDirect(args, log)` using **camelCase** with `Direct` suffix.
+    - **Path Finding**: Inside this function, obtain the `tasksPath` by calling `const tasksPath = findTasksJsonPath(args, log);`. This relies on `args.projectRoot` (derived from the session) being passed correctly.
+    - Perform validation on other arguments received in `args`.
+    - **Implement Silent Mode**: Wrap core function calls with `enableSilentMode()` and `disableSilentMode()` to prevent logs from interfering with JSON responses.
+    - **If Caching**: Implement caching using `getCachedOrExecute` from `../../tools/utils.js`.
+    - **If Not Caching**: Directly call the core logic function within a try/catch block.
+    - Format the return as `{ success: true/false, data/error, fromCache: boolean }`.
+    - 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.
+    - 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.
+    - Implement the standard `async execute(args, { log, reportProgress, session })` method:
+      - Get `rootFolder` using `getProjectRootFromSession` (with fallback to `args.projectRoot`).
+      - Call `yourCommandDirect({ ...args, projectRoot: rootFolder }, log)`. 
+      - Pass the result to `handleApiResult(result, log, 'Error Message')`.
+
+5.  **Register Tool**: Import and call `registerYourCommandTool` in `mcp-server/src/tools/index.js`.
+
+6.  **Update `mcp.json`**: Add the new tool definition to the `tools` array in `.cursor/mcp.json`.
+
+## Implementing Background Operations
+
+For long-running operations that should not block the client, use the AsyncOperationManager:
+
+1. **Identify Background-Appropriate Operations**:
+   - ✅ **DO**: Use async operations for CPU-intensive tasks like task expansion or PRD parsing
+   - ✅ **DO**: Consider async operations for tasks that may take more than 1-2 seconds
+   - ❌ **DON'T**: Use async operations for quick read/status operations
+   - ❌ **DON'T**: Use async operations when immediate feedback is critical
+
+2. **Use AsyncOperationManager in MCP Tools**:
+   ```javascript
+   import { asyncOperationManager } from '../core/utils/async-manager.js';
+   
+   // In execute method:
+   const operationId = asyncOperationManager.addOperation(
+     expandTaskDirect, // The direct function to run in background
+     { ...args, projectRoot: rootFolder }, // Args to pass to the function
+     { log, reportProgress, session } // Context to preserve for the operation
+   );
+   
+   // Return immediate response with operation ID
+   return createContentResponse({
+     message: "Operation started successfully",
+     operationId,
+     status: "pending"
+   });
+   ```
+
+3. **Implement Progress Reporting**:
+   - ✅ **DO**: Use the reportProgress function in direct functions:
+   ```javascript
+   // In your direct function:
+   if (reportProgress) {
+     await reportProgress({ progress: 50 }); // 50% complete
+   }
+   ```
+   - AsyncOperationManager will forward progress updates to the client
+
+4. **Check Operation Status**:
+   - Implement a way for clients to check status using the `get_operation_status` MCP tool
+   - Return appropriate status codes and messages
+
+## Project Initialization
+
+When implementing project initialization commands:
+
+1. **Support Programmatic Initialization**:
+   - ✅ **DO**: Design initialization to work with both CLI and MCP
+   - ✅ **DO**: Support non-interactive modes with sensible defaults
+   - ✅ **DO**: Handle project metadata like name, description, version
+   - ✅ **DO**: Create necessary files and directories
+
+2. **In MCP Tool Implementation**:
+   ```javascript
+   // In initialize-project.js MCP tool:
+   import { z } from "zod";
+   import { initializeProjectDirect } from "../core/task-master-core.js";
+   
+   export function registerInitializeProjectTool(server) {
+     server.addTool({
+       name: "initialize_project",
+       description: "Initialize a new Task Master project",
+       parameters: z.object({
+         projectName: z.string().optional().describe("The name for the new project"),
+         projectDescription: z.string().optional().describe("A brief description"),
+         projectVersion: z.string().optional().describe("Initial version (e.g., '0.1.0')"),
+         // Add other parameters as needed
+       }),
+       execute: async (args, { log, reportProgress, session }) => {
+         try {
+           // No need for project root since we're creating a new project
+           const result = await initializeProjectDirect(args, log);
+           return handleApiResult(result, log, 'Error initializing project');
+         } catch (error) {
+           log.error(`Error in initialize_project: ${error.message}`);
+           return createErrorResponse(`Failed to initialize project: ${error.message}`);
+         }
+       }
+     });
+   }
+   ```

.cursor/rules/taskmaster.mdc

@@ -0,0 +1,353 @@
+---
+description: Comprehensive reference for Taskmaster MCP tools and CLI commands.
+globs: **/*
+alwaysApply: true
+---
+
+# Taskmaster Tool & Command Reference
+
+This document provides a detailed reference for interacting with Taskmaster, covering both the recommended MCP tools (for integrations like Cursor) and the corresponding `task-master` CLI commands (for direct user interaction or fallback).
+
+**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
+
+### 1. Initialize Project (`init`)
+
+*   **MCP Tool:** `initialize_project`
+*   **CLI Command:** `task-master init [options]`
+*   **Description:** `Set up the basic Taskmaster file structure and configuration in the current directory for a new project.`
+*   **Key CLI Options:**
+    *   `--name <name>`: `Set the name for your project in Taskmaster's configuration.`
+    *   `--description <text>`: `Provide a brief description for your project.`
+    *   `--version <version>`: `Set the initial version for your project (e.g., '0.1.0').`
+    *   `-y, --yes`: `Initialize Taskmaster quickly using default settings without interactive prompts.`
+*   **Usage:** Run this once at the beginning of a new project.
+*   **MCP Variant Description:** `Set up the basic Taskmaster file structure and configuration in the current directory for a new project by running the 'task-master init' command.`
+*   **Key MCP Parameters/Options:**
+    *   `projectName`: `Set the name for your project.` (CLI: `--name <name>`)
+    *   `projectDescription`: `Provide a brief description for your project.` (CLI: `--description <text>`)
+    *   `projectVersion`: `Set the initial version for your project (e.g., '0.1.0').` (CLI: `--version <version>`)
+    *   `authorName`: `Author name.` (CLI: `--author <author>`)
+    *   `skipInstall`: `Skip installing dependencies (default: false).` (CLI: `--skip-install`)
+    *   `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.
+
+
+### 2. Parse PRD (`parse_prd`)
+
+*   **MCP Tool:** `parse_prd`
+*   **CLI Command:** `task-master parse-prd [file] [options]`
+*   **Description:** `Parse a Product Requirements Document (PRD) or text file with Taskmaster to automatically generate an initial set of tasks in tasks.json.`
+*   **Key Parameters/Options:**
+    *   `input`: `Path to your PRD or requirements text file that Taskmaster should parse for tasks.` (CLI: `[file]` positional or `-i, --input <file>`)
+    *   `output`: `Specify where Taskmaster should save the generated 'tasks.json' file (default: 'tasks/tasks.json').` (CLI: `-o, --output <file>`)
+    *   `numTasks`: `Approximate number of top-level tasks Taskmaster should aim to generate from the document.` (CLI: `-n, --num-tasks <number>`)
+    *   `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.
+
+---
+
+## Task Listing & Viewing
+
+### 3. Get Tasks (`get_tasks`)
+
+*   **MCP Tool:** `get_tasks`
+*   **CLI Command:** `task-master list [options]`
+*   **Description:** `List your Taskmaster tasks, optionally filtering by status and showing subtasks.`
+*   **Key Parameters/Options:**
+    *   `status`: `Show only Taskmaster tasks matching this status (e.g., 'pending', 'done').` (CLI: `-s, --status <status>`)
+    *   `withSubtasks`: `Include subtasks indented under their parent tasks in the list.` (CLI: `--with-subtasks`)
+    *   `file`: `Path to your Taskmaster 'tasks.json' file (default relies on auto-detection).` (CLI: `-f, --file <file>`)
+*   **Usage:** Get an overview of the project status, often used at the start of a work session.
+
+### 4. Get Next Task (`next_task`)
+
+*   **MCP Tool:** `next_task`
+*   **CLI Command:** `task-master next [options]`
+*   **Description:** `Ask Taskmaster to show the next available task you can work on, based on status and completed dependencies.`
+*   **Key Parameters/Options:**
+    *   `file`: `Path to your Taskmaster 'tasks.json' file (default relies on auto-detection).` (CLI: `-f, --file <file>`)
+*   **Usage:** Identify what to work on next according to the plan.
+
+### 5. Get Task Details (`get_task`)
+
+*   **MCP Tool:** `get_task`
+*   **CLI Command:** `task-master show [id] [options]`
+*   **Description:** `Display detailed information for a specific Taskmaster task or subtask by its ID.`
+*   **Key Parameters/Options:**
+    *   `id`: `Required. The ID of the Taskmaster task (e.g., '15') or subtask (e.g., '15.2') you want to view.` (CLI: `[id]` positional or `-i, --id <id>`)
+    *   `file`: `Path to your Taskmaster 'tasks.json' file (default relies on auto-detection).` (CLI: `-f, --file <file>`)
+*   **Usage:** Understand the full details, implementation notes, and test strategy for a specific task before starting work.
+
+---
+
+## Task Creation & Modification
+
+### 6. Add Task (`add_task`)
+
+*   **MCP Tool:** `add_task`
+*   **CLI Command:** `task-master add-task [options]`
+*   **Description:** `Add a new task to Taskmaster by describing it; AI will structure it.`
+*   **Key Parameters/Options:**
+    *   `prompt`: `Required. Describe the new task you want Taskmaster to create (e.g., "Implement user authentication using JWT").` (CLI: `-p, --prompt <text>`)
+    *   `dependencies`: `Specify the IDs of any Taskmaster tasks that must be completed before this new one can start (e.g., '12,14').` (CLI: `-d, --dependencies <ids>`)
+    *   `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`)
+
+*   **MCP Tool:** `add_subtask`
+*   **CLI Command:** `task-master add-subtask [options]`
+*   **Description:** `Add a new subtask to a Taskmaster parent task, or convert an existing task into a subtask.`
+*   **Key Parameters/Options:**
+    *   `id` / `parent`: `Required. The ID of the Taskmaster task that will be the parent.` (MCP: `id`, CLI: `-p, --parent <id>`)
+    *   `taskId`: `Use this if you want to convert an existing top-level Taskmaster task into a subtask of the specified parent.` (CLI: `-i, --task-id <id>`)
+    *   `title`: `Required (if not using taskId). The title for the new subtask Taskmaster should create.` (CLI: `-t, --title <title>`)
+    *   `description`: `A brief description for the new subtask.` (CLI: `-d, --description <text>`)
+    *   `details`: `Provide implementation notes or details for the new subtask.` (CLI: `--details <text>`)
+    *   `dependencies`: `Specify IDs of other tasks or subtasks (e.g., '15', '16.1') that must be done before this new subtask.` (CLI: `--dependencies <ids>`)
+    *   `status`: `Set the initial status for the new subtask (default: 'pending').` (CLI: `-s, --status <status>`)
+    *   `skipGenerate`: `Prevent Taskmaster from automatically regenerating markdown task files after adding the subtask.` (CLI: `--skip-generate`)
+    *   `file`: `Path to your Taskmaster 'tasks.json' file (default relies on auto-detection).` (CLI: `-f, --file <file>`)
+*   **Usage:** Break down tasks manually or reorganize existing tasks.
+
+### 8. Update Tasks (`update`)
+
+*   **MCP Tool:** `update`
+*   **CLI Command:** `task-master update [options]`
+*   **Description:** `Update multiple upcoming tasks in Taskmaster based on new context or changes, starting from a specific task ID.`
+*   **Key Parameters/Options:**
+    *   `from`: `Required. The ID of the first task Taskmaster should update. All tasks with this ID or higher (and not 'done') will be considered.` (CLI: `--from <id>`)
+    *   `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. 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`)
+
+*   **MCP Tool:** `update_task`
+*   **CLI Command:** `task-master update-task [options]`
+*   **Description:** `Modify a specific Taskmaster task (or subtask) by its ID, incorporating new information or changes.`
+*   **Key Parameters/Options:**
+    *   `id`: `Required. The specific ID of the Taskmaster task (e.g., '15') or subtask (e.g., '15.2') you want to update.` (CLI: `-i, --id <id>`)
+    *   `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. 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. 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. 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. 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`)
+
+*   **MCP Tool:** `set_task_status`
+*   **CLI Command:** `task-master set-status [options]`
+*   **Description:** `Update the status of one or more Taskmaster tasks or subtasks (e.g., 'pending', 'in-progress', 'done').`
+*   **Key Parameters/Options:**
+    *   `id`: `Required. The ID(s) of the Taskmaster task(s) or subtask(s) (e.g., '15', '15.2', '16,17.1') to update.` (CLI: `-i, --id <id>`)
+    *   `status`: `Required. The new status to set (e.g., 'done', 'pending', 'in-progress', 'review', 'cancelled').` (CLI: `-s, --status <status>`)
+    *   `file`: `Path to your Taskmaster 'tasks.json' file (default relies on auto-detection).` (CLI: `-f, --file <file>`)
+*   **Usage:** Mark progress as tasks move through the development cycle.
+
+### 12. Remove Task (`remove_task`)
+
+*   **MCP Tool:** `remove_task`
+*   **CLI Command:** `task-master remove-task [options]`
+*   **Description:** `Permanently remove a task or subtask from the Taskmaster tasks list.`
+*   **Key Parameters/Options:**
+    *   `id`: `Required. The ID of the Taskmaster task (e.g., '5') or subtask (e.g., '5.2') to permanently remove.` (CLI: `-i, --id <id>`)
+    *   `yes`: `Skip the confirmation prompt and immediately delete the task.` (CLI: `-y, --yes`)
+    *   `file`: `Path to your Taskmaster 'tasks.json' file (default relies on auto-detection).` (CLI: `-f, --file <file>`)
+*   **Usage:** Permanently delete tasks or subtasks that are no longer needed in the project.
+*   **Notes:** Use with caution as this operation cannot be undone. Consider using 'blocked', 'cancelled', or 'deferred' status instead if you just want to exclude a task from active planning but keep it for reference. The command automatically cleans up dependency references in other tasks.
+
+---
+
+## Task Structure & Breakdown
+
+### 13. Expand Task (`expand_task`)
+
+*   **MCP Tool:** `expand_task`
+*   **CLI Command:** `task-master expand [options]`
+*   **Description:** `Use Taskmaster's AI to break down a complex task (or all tasks) into smaller, manageable subtasks.`
+*   **Key Parameters/Options:**
+    *   `id`: `The ID of the specific Taskmaster task you want to break down into subtasks.` (CLI: `-i, --id <id>`)
+    *   `num`: `Suggests how many subtasks Taskmaster should aim to create (uses complexity analysis by default).` (CLI: `-n, --num <number>`)
+    *   `research`: `Enable Taskmaster to use Perplexity AI for more informed subtask generation (requires PERPLEXITY_API_KEY).` (CLI: `-r, --research`)
+    *   `prompt`: `Provide extra context or specific instructions to Taskmaster for generating the subtasks.` (CLI: `-p, --prompt <text>`)
+    *   `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`)
+
+*   **MCP Tool:** `expand_all`
+*   **CLI Command:** `task-master expand --all [options]` (Note: CLI uses the `expand` command with the `--all` flag)
+*   **Description:** `Tell Taskmaster to automatically expand all 'pending' tasks based on complexity analysis.`
+*   **Key Parameters/Options:**
+    *   `num`: `Suggests how many subtasks Taskmaster should aim to create per task.` (CLI: `-n, --num <number>`)
+    *   `research`: `Enable Perplexity AI for more informed subtask generation (requires PERPLEXITY_API_KEY).` (CLI: `-r, --research`)
+    *   `prompt`: `Provide extra context for Taskmaster to apply generally during expansion.` (CLI: `-p, --prompt <text>`)
+    *   `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`)
+
+*   **MCP Tool:** `clear_subtasks`
+*   **CLI Command:** `task-master clear-subtasks [options]`
+*   **Description:** `Remove all subtasks from one or more specified Taskmaster parent tasks.`
+*   **Key Parameters/Options:**
+    *   `id`: `The ID(s) of the Taskmaster parent task(s) whose subtasks you want to remove (e.g., '15', '16,18').` (Required unless using `all`) (CLI: `-i, --id <ids>`)
+    *   `all`: `Tell Taskmaster to remove subtasks from all parent tasks.` (CLI: `--all`)
+    *   `file`: `Path to your Taskmaster 'tasks.json' file (default relies on auto-detection).` (CLI: `-f, --file <file>`)
+*   **Usage:** Used before regenerating subtasks with `expand_task` if the previous breakdown needs replacement.
+
+### 16. Remove Subtask (`remove_subtask`)
+
+*   **MCP Tool:** `remove_subtask`
+*   **CLI Command:** `task-master remove-subtask [options]`
+*   **Description:** `Remove a subtask from its Taskmaster parent, optionally converting it into a standalone task.`
+*   **Key Parameters/Options:**
+    *   `id`: `Required. The ID(s) of the Taskmaster subtask(s) to remove (e.g., '15.2', '16.1,16.3').` (CLI: `-i, --id <id>`)
+    *   `convert`: `If used, Taskmaster will turn the subtask into a regular top-level task instead of deleting it.` (CLI: `-c, --convert`)
+    *   `skipGenerate`: `Prevent Taskmaster from automatically regenerating markdown task files after removing the subtask.` (CLI: `--skip-generate`)
+    *   `file`: `Path to your Taskmaster 'tasks.json' file (default relies on auto-detection).` (CLI: `-f, --file <file>`)
+*   **Usage:** Delete unnecessary subtasks or promote a subtask to a top-level task.
+
+---
+
+## Dependency Management
+
+### 17. Add Dependency (`add_dependency`)
+
+*   **MCP Tool:** `add_dependency`
+*   **CLI Command:** `task-master add-dependency [options]`
+*   **Description:** `Define a dependency in Taskmaster, making one task a prerequisite for another.`
+*   **Key Parameters/Options:**
+    *   `id`: `Required. The ID of the Taskmaster task that will depend on another.` (CLI: `-i, --id <id>`)
+    *   `dependsOn`: `Required. The ID of the Taskmaster task that must be completed first (the prerequisite).` (CLI: `-d, --depends-on <id>`)
+    *   `file`: `Path to your Taskmaster 'tasks.json' file (default relies on auto-detection).` (CLI: `-f, --file <file>`)
+*   **Usage:** Establish the correct order of execution between tasks.
+
+### 18. Remove Dependency (`remove_dependency`)
+
+*   **MCP Tool:** `remove_dependency`
+*   **CLI Command:** `task-master remove-dependency [options]`
+*   **Description:** `Remove a dependency relationship between two Taskmaster tasks.`
+*   **Key Parameters/Options:**
+    *   `id`: `Required. The ID of the Taskmaster task you want to remove a prerequisite from.` (CLI: `-i, --id <id>`)
+    *   `dependsOn`: `Required. The ID of the Taskmaster task that should no longer be a prerequisite.` (CLI: `-d, --depends-on <id>`)
+    *   `file`: `Path to your Taskmaster 'tasks.json' file (default relies on auto-detection).` (CLI: `-f, --file <file>`)
+*   **Usage:** Update task relationships when the order of execution changes.
+
+### 19. Validate Dependencies (`validate_dependencies`)
+
+*   **MCP Tool:** `validate_dependencies`
+*   **CLI Command:** `task-master validate-dependencies [options]`
+*   **Description:** `Check your Taskmaster tasks for dependency issues (like circular references or links to non-existent tasks) without making changes.`
+*   **Key Parameters/Options:**
+    *   `file`: `Path to your Taskmaster 'tasks.json' file (default relies on auto-detection).` (CLI: `-f, --file <file>`)
+*   **Usage:** Audit the integrity of your task dependencies.
+
+### 20. Fix Dependencies (`fix_dependencies`)
+
+*   **MCP Tool:** `fix_dependencies`
+*   **CLI Command:** `task-master fix-dependencies [options]`
+*   **Description:** `Automatically fix dependency issues (like circular references or links to non-existent tasks) in your Taskmaster tasks.`
+*   **Key Parameters/Options:**
+    *   `file`: `Path to your Taskmaster 'tasks.json' file (default relies on auto-detection).` (CLI: `-f, --file <file>`)
+*   **Usage:** Clean up dependency errors automatically.
+
+---
+
+## Analysis & Reporting
+
+### 21. Analyze Project Complexity (`analyze_project_complexity`)
+
+*   **MCP Tool:** `analyze_project_complexity`
+*   **CLI Command:** `task-master analyze-complexity [options]`
+*   **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 to save the complexity analysis report (default: 'scripts/task-complexity-report.json').` (CLI: `-o, --output <file>`)
+    *   `threshold`: `The minimum complexity score (1-10) that should trigger a recommendation to expand a task.` (CLI: `-t, --threshold <number>`)
+    *   `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:** 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. View Complexity Report (`complexity_report`)
+
+*   **MCP Tool:** `complexity_report`
+*   **CLI Command:** `task-master complexity-report [options]`
+*   **Description:** `Display the task complexity analysis report in a readable format.`
+*   **Key Parameters/Options:**
+    *   `file`: `Path to the complexity report (default: 'scripts/task-complexity-report.json').` (CLI: `-f, --file <file>`)
+*   **Usage:** Review and understand the complexity analysis results after running analyze-complexity.
+
+---
+
+## File Management
+
+### 23. Generate Task Files (`generate`)
+
+*   **MCP Tool:** `generate`
+*   **CLI Command:** `task-master generate [options]`
+*   **Description:** `Create or update individual Markdown files for each task based on your tasks.json.`
+*   **Key Parameters/Options:**
+    *   `output`: `The directory where Taskmaster should save the task files (default: in a 'tasks' directory).` (CLI: `-o, --output <directory>`)
+    *   `file`: `Path to your Taskmaster 'tasks.json' file (default relies on auto-detection).` (CLI: `-f, --file <file>`)
+*   **Usage:** Run this after making changes to tasks.json to keep individual task files up to date.
+
+---
+
+## Environment Variables Configuration
+
+Taskmaster's behavior can be customized via environment variables. These affect both CLI and MCP server operation:
+
+*   **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

@@ -7,7 +7,7 @@ globs: "**/*.test.js,tests/**/*"
 
 ## Test Organization Structure
 
-- **Unit Tests**
+- **Unit Tests** (See [`architecture.mdc`](mdc:.cursor/rules/architecture.mdc) for module breakdown)
   - Located in `tests/unit/`
   - Test individual functions and utilities in isolation
   - Mock all external dependencies
@@ -324,7 +324,7 @@ When testing ES modules (`"type": "module"` in package.json), traditional mockin
 ## Testing Common Components
 
 - **CLI Commands**
-  - Mock the action handlers and verify they're called with correct arguments
+  - Mock the action handlers (defined in [`commands.js`](mdc:scripts/modules/commands.js)) and verify they're called with correct arguments
   - Test command registration and option parsing
   - Use `commander` test utilities or custom mocks
 

.cursor/rules/utilities.mdc

@@ -1,6 +1,6 @@
 ---
 description: Guidelines for implementing utility functions
-globs: scripts/modules/utils.js
+globs: scripts/modules/utils.js, mcp-server/src/**/*
 alwaysApply: false
 ---
 
@@ -44,6 +44,12 @@ alwaysApply: false
   }
   ```
 
+- **Location**:
+    - **Core CLI Utilities**: Place utilities used primarily by the core `task-master` CLI logic and command modules (`scripts/modules/*`) into [`scripts/modules/utils.js`](mdc:scripts/modules/utils.js).
+    - **MCP Server Utilities**: Place utilities specifically designed to support the MCP server implementation into the appropriate subdirectories within `mcp-server/src/`.
+        - Path/Core Logic Helpers: [`mcp-server/src/core/utils/`](mdc:mcp-server/src/core/utils/) (e.g., `path-utils.js`).
+        - Tool Execution/Response Helpers: [`mcp-server/src/tools/utils.js`](mdc:mcp-server/src/tools/utils.js).
+
 ## Documentation Standards
 
 - **JSDoc Format**:
@@ -73,7 +79,7 @@ alwaysApply: false
   }
   ```
 
-## Configuration Management
+## Configuration Management (in `scripts/modules/utils.js`)
 
 - **Environment Variables**:
   - ✅ DO: Provide default values for all configuration
@@ -84,25 +90,48 @@ alwaysApply: false
   ```javascript
   // ✅ DO: Set up configuration with defaults and environment overrides
   const CONFIG = {
-    model: process.env.MODEL || 'claude-3-7-sonnet-20250219',
+    model: process.env.MODEL || 'claude-3-opus-20240229', // Updated default model
     maxTokens: parseInt(process.env.MAX_TOKENS || '4000'),
     temperature: parseFloat(process.env.TEMPERATURE || '0.7'),
     debug: process.env.DEBUG === "true",
     logLevel: process.env.LOG_LEVEL || "info",
     defaultSubtasks: parseInt(process.env.DEFAULT_SUBTASKS || "3"),
     defaultPriority: process.env.DEFAULT_PRIORITY || "medium",
-    projectName: process.env.PROJECT_NAME || "Task Master",
-    projectVersion: "1.5.0" // Version should be hardcoded
+    projectName: process.env.PROJECT_NAME || "Task Master Project", // Generic project name
+    projectVersion: "1.5.0" // Version should be updated via release process
   };
   ```
 
-## Logging Utilities
+## Logging Utilities (in `scripts/modules/utils.js`)
 
 - **Log Levels**:
   - ✅ DO: Support multiple log levels (debug, info, warn, error)
   - ✅ 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
@@ -129,18 +158,124 @@ alwaysApply: false
   }
   ```
 
-## File Operations
+## 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**:
   - ✅ DO: Use try/catch blocks for all file operations
   - ✅ DO: Return null or a default value on failure
-  - ✅ DO: Log detailed error information
-  - ❌ DON'T: Allow exceptions to propagate unhandled
+  - ✅ DO: Log detailed error information using the `log` utility
+  - ❌ DON'T: Allow exceptions to propagate unhandled from simple file reads/writes
 
   ```javascript
-  // ✅ DO: Handle file operation errors properly
+  // ✅ DO: Handle file operation errors properly in core utils
   function writeJSON(filepath, data) {
     try {
+      // Ensure directory exists (example)
+      const dir = path.dirname(filepath);
+      if (!fs.existsSync(dir)) {
+        fs.mkdirSync(dir, { recursive: true });
+      }
       fs.writeFileSync(filepath, JSON.stringify(data, null, 2));
     } catch (error) {
       log('error', `Error writing JSON file ${filepath}:`, error.message);
@@ -151,7 +286,7 @@ alwaysApply: false
   }
   ```
 
-## Task-Specific Utilities
+## Task-Specific Utilities (in `scripts/modules/utils.js`)
 
 - **Task ID Formatting**:
   - ✅ DO: Create utilities for consistent ID handling
@@ -224,7 +359,7 @@ alwaysApply: false
   }
   ```
 
-## Cycle Detection
+## Cycle Detection (in `scripts/modules/utils.js`)
 
 - **Graph Algorithms**:
   - ✅ DO: Implement cycle detection using graph traversal
@@ -273,16 +408,68 @@ alwaysApply: false
   }
   ```
 
+## MCP Server Core Utilities (`mcp-server/src/core/utils/`)
+
+### Project Root and Task File Path Detection (`path-utils.js`)
+
+- **Purpose**: This module ([`mcp-server/src/core/utils/path-utils.js`](mdc:mcp-server/src/core/utils/path-utils.js)) provides the mechanism for locating the user's `tasks.json` file, used by direct functions.
+- **`findTasksJsonPath(args, log)`**:
+    - ✅ **DO**: Call this function from within **direct function wrappers** (e.g., `listTasksDirect` in `mcp-server/src/core/direct-functions/`) to get the absolute path to the relevant `tasks.json`.
+    - Pass the *entire `args` object* received by the MCP tool (which should include `projectRoot` derived from the session) and the `log` object.
+    - Implements a **simplified precedence system** for finding the `tasks.json` path:
+        1.  Explicit `projectRoot` passed in `args` (Expected from MCP tools).
+        2.  Cached `lastFoundProjectRoot` (CLI fallback).
+        3.  Search upwards from `process.cwd()` (CLI fallback).
+    - Throws a specific error if the `tasks.json` file cannot be located.
+    - Updates the `lastFoundProjectRoot` cache on success.
+- **`PROJECT_MARKERS`**: An exported array of common file/directory names used to identify a likely project root during the CLI fallback search.
+- **`getPackagePath()`**: Utility to find the installation path of the `task-master-ai` package itself (potentially removable).
+
+## MCP Server Tool Utilities (`mcp-server/src/tools/utils.js`)
+
+- **Purpose**: These utilities specifically support the MCP server tools ([`mcp-server/src/tools/*.js`](mdc:mcp-server/src/tools/*.js)), handling MCP communication patterns, response formatting, caching integration, and the CLI fallback mechanism.
+- **Refer to [`mcp.mdc`](mdc:.cursor/rules/mcp.mdc)** for detailed usage patterns within the MCP tool `execute` methods and direct function wrappers.
+
+- **`getProjectRootFromSession(session, log)`**: 
+    - ✅ **DO**: Call this utility **within the MCP tool's `execute` method** to extract the project root path from the `session` object.
+    - Decodes the `file://` URI and handles potential errors.
+    - Returns the project path string or `null`.
+    - The returned path should then be passed in the `args` object when calling the corresponding `*Direct` function (e.g., `yourDirectFunction({ ...args, projectRoot: rootFolder }, log)`).
+
+- **`handleApiResult(result, log, errorPrefix, processFunction)`**:
+    - ✅ **DO**: Call this from the MCP tool's `execute` method after receiving the result from the `*Direct` function wrapper.
+    - Takes the standard `{ success, data/error, fromCache }` object.
+    - Formats the standard MCP success or error response, including the `fromCache` flag.
+    - Uses `processMCPResponseData` by default to filter response data.
+
+- **`executeTaskMasterCommand(command, log, args, projectRootRaw)`**:
+    - Executes a Task Master CLI command as a child process.
+    - Handles fallback between global `task-master` and local `node scripts/dev.js`.
+    - ❌ **DON'T**: Use this as the primary method for MCP tools. Prefer direct function calls via `*Direct` wrappers.
+
+- **`processMCPResponseData(taskOrData, fieldsToRemove)`**:
+    - Filters task data (e.g., removing `details`, `testStrategy`) before sending to the MCP client. Called by `handleApiResult`.
+
+- **`createContentResponse(content)` / `createErrorResponse(errorMessage)`**:
+    - Formatters for standard MCP success/error responses.
+
+- **`getCachedOrExecute({ cacheKey, actionFn, log })`**:
+    - ✅ **DO**: Use this utility *inside direct function wrappers* to implement caching.
+    - Checks cache, executes `actionFn` on miss, stores result.
+    - Returns standard `{ success, data/error, fromCache: boolean }`.
+
 ## Export Organization
 
 - **Grouping Related Functions**:
-  - ✅ DO: Export all utility functions in a single statement
-  - ✅ DO: Group related exports together
-  - ✅ DO: Export configuration constants
-  - ❌ DON'T: Use default exports
+  - ✅ DO: Keep utilities relevant to their location (e.g., core CLI utils in `scripts/modules/utils.js`, MCP path utils in `mcp-server/src/core/utils/path-utils.js`, MCP tool utils in `mcp-server/src/tools/utils.js`).
+  - ✅ DO: Export all utility functions in a single statement per file.
+  - ✅ DO: Group related exports together.
+  - ✅ DO: Export configuration constants (from `scripts/modules/utils.js`).
+  - ❌ DON'T: Use default exports.
+  - ❌ DON'T: Create circular dependencies (See [`architecture.mdc`](mdc:.cursor/rules/architecture.mdc)).
 
 ```javascript
-  // ✅ DO: Organize exports logically
+// Example export from scripts/modules/utils.js
 export {
   // Configuration
   CONFIG,
@@ -300,15 +487,31 @@ alwaysApply: false
   truncate,
   
   // Task utilities
-    readComplexityReport,
-    findTaskInComplexityReport,
-    taskExists,
-    formatTaskId,
-    findTaskById,
+  // ... (taskExists, formatTaskId, findTaskById, etc.)
   
   // Graph algorithms
   findCycles,
 };
+
+// Example export from mcp-server/src/core/utils/path-utils.js
+export {
+  findTasksJsonPath,
+  getPackagePath,
+  PROJECT_MARKERS,
+  lastFoundProjectRoot // Exporting for potential direct use/reset if needed
+};
+
+// Example export from mcp-server/src/tools/utils.js
+export {
+  getProjectRoot,
+  getProjectRootFromSession,
+  handleApiResult,
+  executeTaskMasterCommand,
+  processMCPResponseData,
+  createContentResponse,
+  createErrorResponse,
+  getCachedOrExecute
+};
 ```
 
-Refer to [`utils.js`](mdc:scripts/modules/utils.js) for implementation examples and [`new_features.mdc`](mdc:.cursor/rules/new_features.mdc) for integration guidelines. 
+Refer to [`mcp.mdc`](mdc:.cursor/rules/mcp.mdc) and [`architecture.mdc`](mdc:.cursor/rules/architecture.mdc) for more context on MCP server architecture and integration. 

.env.example

@@ -5,15 +5,15 @@ 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
 PERPLEXITY_MODEL=sonar-pro                          # Perplexity model for research-backed subtasks
-MAX_TOKENS=64000                   # Maximum tokens for model responses
-TEMPERATURE=0.4                   # Temperature for model responses (0.0-1.0)
+MAX_TOKENS=128000                                   # Maximum tokens for model responses
+TEMPERATURE=0.2                                     # Temperature for model responses (0.0-1.0)
 
 # Logging Configuration
 DEBUG=false                                         # Enable debug logging (true/false)
 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)
 
 # Project Metadata (Optional)

.github/workflows/ci.yml

@@ -0,0 +1,61 @@
+name: CI
+
+on:
+  push:
+    branches:
+      - main
+      - next
+  pull_request:
+    branches:
+      - main
+      - next
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+    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: 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 ci
+        timeout-minutes: 2
+
+      - 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: 15
+
+      - name: Upload Test Results
+        if: always()
+        uses: actions/upload-artifact@v4
+        with:
+          name: test-results-node
+          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
@@ -14,13 +13,25 @@ jobs:
 
       - uses: actions/setup-node@v4
         with:
-          node-version: 18
+          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@1.4.10
+        uses: changesets/action@v1
         with:
           publish: npm run release
         env:

.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

CHANGELOG.md

@@ -0,0 +1,27 @@
+# task-master-ai
+
+## 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
+
+- [#44](https://github.com/eyaltoledano/claude-task-master/pull/44) [`eafdb47`](https://github.com/eyaltoledano/claude-task-master/commit/eafdb47418b444c03c092f653b438cc762d4bca8) Thanks [@Crunchyman-ralph](https://github.com/Crunchyman-ralph)! - add github actions to automate github and npm releases
+
+- [#20](https://github.com/eyaltoledano/claude-task-master/pull/20) [`4eed269`](https://github.com/eyaltoledano/claude-task-master/commit/4eed2693789a444f704051d5fbb3ef8d460e4e69) Thanks [@Crunchyman-ralph](https://github.com/Crunchyman-ralph)! - Implement MCP server for all commands using tools.
+
+### Patch Changes
+
+- [#44](https://github.com/eyaltoledano/claude-task-master/pull/44) [`44db895`](https://github.com/eyaltoledano/claude-task-master/commit/44db895303a9209416236e3d519c8a609ad85f61) Thanks [@Crunchyman-ralph](https://github.com/Crunchyman-ralph)! - Added changeset config #39
+
+- [#50](https://github.com/eyaltoledano/claude-task-master/pull/50) [`257160a`](https://github.com/eyaltoledano/claude-task-master/commit/257160a9670b5d1942e7c623bd2c1a3fde7c06a0) Thanks [@Crunchyman-ralph](https://github.com/Crunchyman-ralph)! - Fix addTask tool `projectRoot not defined`
+
+- [#57](https://github.com/eyaltoledano/claude-task-master/pull/57) [`9fd42ee`](https://github.com/eyaltoledano/claude-task-master/commit/9fd42eeafdc25a96cdfb70aa3af01f525d26b4bc) Thanks [@github-actions](https://github.com/apps/github-actions)! - fix mcp server not connecting to cursor
+
+- [#48](https://github.com/eyaltoledano/claude-task-master/pull/48) [`5ec3651`](https://github.com/eyaltoledano/claude-task-master/commit/5ec3651e6459add7354910a86b3c4db4d12bc5d1) Thanks [@Crunchyman-ralph](https://github.com/Crunchyman-ralph)! - Fix workflows

LICENSE

@@ -0,0 +1,25 @@
+Task Master License
+
+MIT License
+
+Copyright (c) 2025 — Eyal Toledano, Ralph Khreish
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+
+"Commons Clause" License Condition v1.0
+
+The Software is provided to you by the Licensor under the License (defined below), subject to the following condition:
+
+Without limiting other conditions in the License, the grant of rights under the License will not include, and the License does not grant to you, the right to Sell the Software.
+
+For purposes of the foregoing, "Sell" means practicing any or all of the rights granted to you under the License to provide the Software to third parties, for a fee or other consideration (including without limitation fees for hosting or consulting/support services related to the Software), as part of a product or service whose value derives, entirely or substantially, from the functionality of the Software. Any license notice or attribution required by the License must also include this Commons Clause License Condition notice.
+
+Software: All Task Master associated files (including all files in the GitHub repository "claude-task-master" and in the npm package "task-master-ai").
+
+License: MIT
+
+Licensor: Eyal Toledano, Ralph Khreish

LICENSE.md

@@ -0,0 +1,90 @@
+# 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

@@ -57,7 +57,16 @@ This will prompt you for project details and set up a new project with the neces
 
 ### Important Notes
 
-1. This package uses ES modules. Your package.json should include `"type": "module"`.
+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()`.
+   - Files should use `.js` or `.mjs` extensions.
+   - To use a CommonJS module, either:
+     - Rename it with `.cjs` extension
+     - Use `await import()` for dynamic imports
+   - If you need CommonJS throughout your project, remove `"type": "module"` from package.json, but Task Master scripts expect ESM.
+
 2. The Anthropic SDK version should be 0.39.0 or higher.
 
 ## Quick Start with Global Commands

assets/env.example

@@ -1,14 +1,14 @@
 # Required
-ANTHROPIC_API_KEY=your-api-key-here  # Format: sk-ant-api03-...
-PERPLEXITY_API_KEY=pplx-abcde # For research (recommended but optional)
+ANTHROPIC_API_KEY=your-api-key-here  # For most AI ops -- Format: sk-ant-api03-... (Required)
+PERPLEXITY_API_KEY=pplx-abcde        # For research -- Format: pplx-abcde (Optional, Highly Recommended)
 
 # Optional - defaults shown
-MODEL=claude-3-7-sonnet-20250219  # Recommended models: claude-3-7-sonnet-20250219, claude-3-opus-20240229
-PERPLEXITY_MODEL=sonar-pro        # Make sure you have access to sonar-pro otherwise you can use sonar regular.
-MAX_TOKENS=4000                   # Maximum tokens for model responses
-TEMPERATURE=0.7                   # Temperature for model responses (0.0-1.0)
+MODEL=claude-3-7-sonnet-20250219  # Recommended models: claude-3-7-sonnet-20250219, claude-3-opus-20240229 (Required)
+PERPLEXITY_MODEL=sonar-pro        # Make sure you have access to sonar-pro otherwise you can use sonar regular (Optional)
+MAX_TOKENS=64000                   # Maximum tokens for model responses (Required)
+TEMPERATURE=0.2                   # Temperature for model responses (0.0-1.0) - lower = less creativity and follow your prompt closely (Required)
 DEBUG=false                       # Enable debug logging (true/false)
 LOG_LEVEL=info                    # Log level (debug, info, warn, error)
-DEFAULT_SUBTASKS=3                # 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)
 PROJECT_NAME={{projectName}}      # Project name for tasks.json metadata

bin/task-master.js

@@ -1,5 +1,20 @@
 #!/usr/bin/env node
 
+/**
+ * Task Master
+ * Copyright (c) 2025 Eyal Toledano, Ralph Khreish
+ *
+ * This software is licensed under the MIT License with Commons Clause.
+ * You may use this software for any purpose, including commercial applications,
+ * and modify and redistribute it freely, subject to the following restrictions:
+ *
+ * 1. You may not sell this software or offer it as a service.
+ * 2. The origin of this software must not be misrepresented.
+ * 3. Altered source versions must be plainly marked as such.
+ *
+ * For the full license text, see the LICENSE file in the root directory.
+ */
+
 /**
  * Claude Task Master CLI
  * Main entry point for globally installed package
@@ -13,6 +28,7 @@ import { Command } from 'commander';
 import { displayHelp, displayBanner } from '../scripts/modules/ui.js';
 import { registerCommands } from '../scripts/modules/commands.js';
 import { detectCamelCaseFlags } from '../scripts/modules/utils.js';
+import chalk from 'chalk';
 
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = dirname(__filename);
@@ -167,7 +183,7 @@ function createDevScriptAction(commandName) {
           if (value === true) {
             args.push(`--${kebabKey}`);
           } else if (value === false && key === 'generate') {
-            args.push('--no-generate');
+            args.push('--skip-generate');
           }
         } else {
           // Always use kebab-case for option names
@@ -253,7 +269,6 @@ registerInitCommand(program);
 program
   .command('dev')
   .description('Run the dev.js script')
-  .allowUnknownOption(true)
   .action(() => {
     const args = process.argv.slice(process.argv.indexOf('dev') + 1);
     runDevScript(args);
@@ -273,8 +288,7 @@ tempProgram.commands.forEach(cmd => {
   // Create a new command with the same name and description
   const newCmd = program
     .command(cmd.name())
-    .description(cmd.description())
-    .allowUnknownOption(); // Allow any options, including camelCase ones
+    .description(cmd.description());
   
   // Copy all options
   cmd.options.forEach(opt => {
@@ -292,6 +306,39 @@ tempProgram.commands.forEach(cmd => {
 // Parse the command line arguments
 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
+  if (err.code === 'commander.unknownOption') {
+    const option = err.message.match(/'([^']+)'/)?.[1];
+    const commandArg = process.argv.find(arg => !arg.startsWith('-') && 
+                                            arg !== 'task-master' && 
+                                            !arg.includes('/') && 
+                                            arg !== 'node');
+    const command = commandArg || 'unknown';
+    
+    console.error(chalk.red(`Error: Unknown option '${option}'`));
+    console.error(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
+  if (err.code === 'commander.unknownCommand') {
+    const command = err.message.match(/'([^']+)'/)?.[1];
+    
+    console.error(chalk.red(`Error: Unknown command '${command}'`));
+    console.error(chalk.yellow(`Run 'task-master --help' to see available commands`));
+    process.exit(1);
+  }
+  
+  // Handle other uncaught exceptions
+  console.error(chalk.red(`Error: ${err.message}`));
+  if (process.env.DEBUG === '1') {
+    console.error(err);
+  }
+  process.exit(1);
+});
+
 // Show help if no command was provided (just 'task-master' with no args)
 if (process.argv.length <= 2) {
   displayBanner();

context/MCP_INTEGRATION.md

@@ -0,0 +1,269 @@
+# Task Master MCP Integration
+
+This document outlines how Task Master CLI functionality is integrated with MCP (Master Control Program) architecture to provide both CLI and programmatic API access to features.
+
+## Architecture Overview
+
+The MCP integration uses a layered approach:
+
+1. **Core Functions** - In `scripts/modules/` contain the main business logic
+2. **Source Parameter** - Core functions check the `source` parameter to determine behavior
+3. **Task Master Core** - In `mcp-server/src/core/task-master-core.js` provides direct function imports
+4. **MCP Tools** - In `mcp-server/src/tools/` register the functions with the MCP server
+
+```
+┌─────────────────┐         ┌─────────────────┐
+│    CLI User     │         │    MCP User     │
+└────────┬────────┘         └────────┬────────┘
+         │                           │
+         ▼                           ▼
+┌────────────────┐         ┌────────────────────┐
+│  commands.js   │         │   MCP Tool API     │
+└────────┬───────┘         └──────────┬─────────┘
+         │                            │
+         │                            │
+         ▼                            ▼
+┌───────────────────────────────────────────────┐
+│                                               │
+│     Core Modules (task-manager.js, etc.)      │
+│                                               │
+└───────────────────────────────────────────────┘
+```
+
+## Core Function Pattern
+
+Core functions should follow this pattern to support both CLI and MCP use:
+
+```javascript
+/**
+ * Example function with source parameter support
+ * @param {Object} options - Additional options including source
+ * @returns {Object|undefined} - Returns data when source is 'mcp'
+ */
+function exampleFunction(param1, param2, options = {}) {
+  try {
+    // Skip UI for MCP
+    if (options.source !== 'mcp') {
+      displayBanner();
+      console.log(chalk.blue('Processing operation...'));
+    }
+    
+    // Do the core business logic
+    const result = doSomething(param1, param2);
+    
+    // For MCP, return structured data
+    if (options.source === 'mcp') {
+      return {
+        success: true,
+        data: result
+      };
+    }
+    
+    // For CLI, display output
+    console.log(chalk.green('Operation completed successfully!'));
+  } catch (error) {
+    // Handle errors based on source
+    if (options.source === 'mcp') {
+      return {
+        success: false,
+        error: error.message
+      };
+    }
+    
+    // CLI error handling
+    console.error(chalk.red(`Error: ${error.message}`));
+    process.exit(1);
+  }
+}
+```
+
+## Source-Adapter Utilities
+
+For convenience, you can use the source adapter helpers in `scripts/modules/source-adapter.js`:
+
+```javascript
+import { adaptForMcp, sourceSplitFunction } from './source-adapter.js';
+
+// Simple adaptation - just adds source parameter support
+export const simpleFunction = adaptForMcp(originalFunction);
+
+// Split implementation - completely different code paths for CLI vs MCP
+export const complexFunction = sourceSplitFunction(
+  // CLI version with UI
+  function(param1, param2) {
+    displayBanner();
+    console.log(`Processing ${param1}...`);
+    // ... CLI implementation
+  },
+  // MCP version with structured return
+  function(param1, param2, options = {}) {
+    // ... MCP implementation
+    return { success: true, data };
+  }
+);
+```
+
+## Adding New Features
+
+When adding new features, follow these steps to ensure CLI and MCP compatibility:
+
+1. **Implement Core Logic** in the appropriate module file
+2. **Add Source Parameter Support** using the pattern above
+3. **Add to task-master-core.js** to make it available for direct import
+4. **Update Command Map** in `mcp-server/src/tools/utils.js` 
+5. **Create Tool Implementation** in `mcp-server/src/tools/`
+6. **Register the Tool** in `mcp-server/src/tools/index.js`
+
+### Core Function Implementation
+
+```javascript
+// In scripts/modules/task-manager.js
+export async function newFeature(param1, param2, options = {}) {
+  try {
+    // Source-specific UI
+    if (options.source !== 'mcp') {
+      displayBanner();
+      console.log(chalk.blue('Running new feature...'));
+    }
+    
+    // Shared core logic
+    const result = processFeature(param1, param2);
+    
+    // Source-specific return handling
+    if (options.source === 'mcp') {
+      return {
+        success: true,
+        data: result
+      };
+    }
+    
+    // CLI output
+    console.log(chalk.green('Feature completed successfully!'));
+    displayOutput(result);
+  } catch (error) {
+    // Error handling based on source
+    if (options.source === 'mcp') {
+      return {
+        success: false,
+        error: error.message
+      };
+    }
+    
+    console.error(chalk.red(`Error: ${error.message}`));
+    process.exit(1);
+  }
+}
+```
+
+### Task Master Core Update
+
+```javascript
+// In mcp-server/src/core/task-master-core.js
+import { newFeature } from '../../../scripts/modules/task-manager.js';
+
+// Add to exports
+export default {
+  // ... existing functions
+  
+  async newFeature(args = {}, options = {}) {
+    const { param1, param2 } = args;
+    return executeFunction(newFeature, [param1, param2], options);
+  }
+};
+```
+
+### Command Map Update
+
+```javascript
+// In mcp-server/src/tools/utils.js
+const commandMap = {
+  // ... existing mappings
+  'new-feature': 'newFeature'
+};
+```
+
+### Tool Implementation
+
+```javascript
+// In mcp-server/src/tools/newFeature.js
+import { z } from "zod";
+import {
+  executeTaskMasterCommand,
+  createContentResponse,
+  createErrorResponse,
+} from "./utils.js";
+
+export function registerNewFeatureTool(server) {
+  server.addTool({
+    name: "newFeature",
+    description: "Run the new feature",
+    parameters: z.object({
+      param1: z.string().describe("First parameter"),
+      param2: z.number().optional().describe("Second parameter"),
+      file: z.string().optional().describe("Path to the tasks file"),
+      projectRoot: z.string().describe("Root directory of the project")
+    }),
+    execute: async (args, { log }) => {
+      try {
+        log.info(`Running new feature with args: ${JSON.stringify(args)}`);
+
+        const cmdArgs = [];
+        if (args.param1) cmdArgs.push(`--param1=${args.param1}`);
+        if (args.param2) cmdArgs.push(`--param2=${args.param2}`);
+        if (args.file) cmdArgs.push(`--file=${args.file}`);
+
+        const projectRoot = args.projectRoot;
+
+        // Execute the command
+        const result = await executeTaskMasterCommand(
+          "new-feature",
+          log,
+          cmdArgs,
+          projectRoot
+        );
+
+        if (!result.success) {
+          throw new Error(result.error);
+        }
+
+        return createContentResponse(result.stdout);
+      } catch (error) {
+        log.error(`Error in new feature: ${error.message}`);
+        return createErrorResponse(`Error in new feature: ${error.message}`);
+      }
+    },
+  });
+}
+```
+
+### Tool Registration
+
+```javascript
+// In mcp-server/src/tools/index.js
+import { registerNewFeatureTool } from "./newFeature.js";
+
+export function registerTaskMasterTools(server) {
+  // ... existing registrations
+  registerNewFeatureTool(server);
+}
+```
+
+## Testing
+
+Always test your MCP-compatible features with both CLI and MCP interfaces:
+
+```javascript
+// Test CLI usage
+node scripts/dev.js new-feature --param1=test --param2=123
+
+// Test MCP usage
+node mcp-server/tests/test-command.js newFeature
+```
+
+## Best Practices
+
+1. **Keep Core Logic DRY** - Share as much logic as possible between CLI and MCP
+2. **Structured Data for MCP** - Return clean JSON objects from MCP source functions
+3. **Consistent Error Handling** - Standardize error formats for both interfaces
+4. **Documentation** - Update MCP tool documentation when adding new features
+5. **Testing** - Test both CLI and MCP interfaces for any new or modified feature 

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

@@ -0,0 +1,258 @@
+# AI Client Utilities for MCP Tools
+
+This document provides examples of how to use the new AI client utilities with AsyncOperationManager in MCP tools.
+
+## Basic Usage with Direct Functions
+
+```javascript
+// In your direct function implementation:
+import { 
+  getAnthropicClientForMCP, 
+  getModelConfig, 
+  handleClaudeError 
+} from '../utils/ai-client-utils.js';
+
+export async function someAiOperationDirect(args, log, context) {
+  try {
+    // Initialize Anthropic client with session from context
+    const client = getAnthropicClientForMCP(context.session, log);
+    
+    // Get model configuration with defaults or session overrides
+    const modelConfig = getModelConfig(context.session);
+    
+    // Make API call with proper error handling
+    try {
+      const response = await client.messages.create({
+        model: modelConfig.model,
+        max_tokens: modelConfig.maxTokens,
+        temperature: modelConfig.temperature,
+        messages: [
+          { role: 'user', content: 'Your prompt here' }
+        ]
+      });
+      
+      return {
+        success: true,
+        data: response
+      };
+    } catch (apiError) {
+      // Use helper to get user-friendly error message
+      const friendlyMessage = handleClaudeError(apiError);
+      
+      return {
+        success: false,
+        error: {
+          code: 'AI_API_ERROR',
+          message: friendlyMessage
+        }
+      };
+    }
+  } catch (error) {
+    // Handle client initialization errors
+    return {
+      success: false,
+      error: {
+        code: 'AI_CLIENT_ERROR',
+        message: error.message
+      }
+    };
+  }
+}
+```
+
+## Integration with AsyncOperationManager
+
+```javascript
+// In your MCP tool implementation:
+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 log = mcpLog || console;
+  
+  try {
+    // Create operation description
+    const operationDescription = `AI operation: ${args.someParam}`;
+    
+    // Start async operation
+    const operation = AsyncOperationManager.createOperation(
+      operationDescription,
+      async (reportProgress) => {
+        try {
+          // Initial progress report
+          reportProgress({
+            progress: 0,
+            status: 'Starting AI operation...'
+          });
+          
+          // Call direct function with session and progress reporting
+          const result = await someAiOperationDirect(
+            args, 
+            log, 
+            {
+              reportProgress,
+              mcpLog: log,
+              session
+            }
+          );
+          
+          // Final progress update
+          reportProgress({
+            progress: 100,
+            status: result.success ? 'Operation completed' : 'Operation failed',
+            result: result.data,
+            error: result.error
+          });
+          
+          return result;
+        } catch (error) {
+          // Handle errors in the operation
+          reportProgress({
+            progress: 100,
+            status: 'Operation failed',
+            error: {
+              message: error.message,
+              code: error.code || 'OPERATION_FAILED'
+            }
+          });
+          throw error;
+        }
+      }
+    );
+    
+    // Return immediate response with operation ID
+    return {
+      status: StatusCodes.ACCEPTED,
+      body: {
+        success: true,
+        message: 'Operation started',
+        operationId: operation.id
+      }
+    };
+  } catch (error) {
+    // Handle errors in the MCP tool
+    log.error(`Error in someAiOperation: ${error.message}`);
+    return {
+      status: StatusCodes.INTERNAL_SERVER_ERROR,
+      body: {
+        success: false,
+        error: {
+          code: 'OPERATION_FAILED',
+          message: error.message
+        }
+      }
+    };
+  }
+}
+```
+
+## Using Research Capabilities with Perplexity
+
+```javascript
+// In your direct function:
+import { 
+  getPerplexityClientForMCP, 
+  getBestAvailableAIModel 
+} from '../utils/ai-client-utils.js';
+
+export async function researchOperationDirect(args, log, context) {
+  try {
+    // Get the best AI model for this operation based on needs
+    const { type, client } = await getBestAvailableAIModel(
+      context.session, 
+      { requiresResearch: true },
+      log
+    );
+    
+    // Report which model we're using
+    if (context.reportProgress) {
+      await context.reportProgress({
+        progress: 10,
+        status: `Using ${type} model for research...`
+      });
+    }
+    
+    // Make API call based on the model type
+    if (type === 'perplexity') {
+      // Call Perplexity
+      const response = await client.chat.completions.create({
+        model: context.session?.env?.PERPLEXITY_MODEL || 'sonar-medium-online',
+        messages: [
+          { role: 'user', content: args.researchQuery }
+        ],
+        temperature: 0.1
+      });
+      
+      return {
+        success: true,
+        data: response.choices[0].message.content
+      };
+    } else {
+      // Call Claude as fallback
+      // (Implementation depends on specific needs)
+      // ...
+    }
+  } catch (error) {
+    // Handle errors
+    return {
+      success: false,
+      error: {
+        code: 'RESEARCH_ERROR',
+        message: error.message
+      }
+    };
+  }
+}
+```
+
+## Model Configuration Override Example
+
+```javascript
+// In your direct function:
+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
+  maxTokens: 1000,                  // Lower token limit
+  temperature: 0.2                  // Lower temperature for more deterministic output
+};
+
+// Get model config with operation-specific defaults
+const modelConfig = getModelConfig(context.session, operationDefaults);
+
+// Now use modelConfig in your API calls
+const response = await client.messages.create({
+  model: modelConfig.model,
+  max_tokens: modelConfig.maxTokens,
+  temperature: modelConfig.temperature,
+  // 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
+
+5. **AsyncOperationManager Integration**:
+   - Create descriptive operation names
+   - Handle all errors within the operation function
+   - Return standardized results from direct functions
+   - Return immediate responses with operation IDs 

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,355 @@
+# 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. **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-ai", "mcp-server"],
+      "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": 128000,
+        "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 --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.
+
+## 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

@@ -0,0 +1,41 @@
+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

@@ -1,5 +1,20 @@
 #!/usr/bin/env node
 
+/**
+ * Task Master
+ * Copyright (c) 2025 Eyal Toledano, Ralph Khreish
+ *
+ * This software is licensed under the MIT License with Commons Clause.
+ * You may use this software for any purpose, including commercial applications,
+ * and modify and redistribute it freely, subject to the following restrictions:
+ *
+ * 1. You may not sell this software or offer it as a service.
+ * 2. The origin of this software must not be misrepresented.
+ * 3. Altered source versions must be plainly marked as such.
+ *
+ * For the full license text, see the LICENSE file in the root directory.
+ */
+
 /**
  * Claude Task Master
  * A task management system for AI-driven development with Claude

jest.config.js

@@ -17,7 +17,8 @@ export default {
   // The glob patterns Jest uses to detect test files
   testMatch: [
     '**/__tests__/**/*.js',
-    '**/?(*.)+(spec|test).js'
+    '**/?(*.)+(spec|test).js',
+    '**/tests/*.test.js'
   ],
   
   // Transform files

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

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

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

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

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

@@ -0,0 +1,85 @@
+/**
+ * add-dependency.js
+ * Direct function implementation for adding a dependency to a task
+ */
+
+import { addDependency } from '../../../../scripts/modules/dependency-manager.js';
+import { findTasksJsonPath } from '../utils/path-utils.js';
+import { enableSilentMode, disableSilentMode } from '../../../../scripts/modules/utils.js';
+
+/**
+ * Direct function wrapper for addDependency with error handling.
+ * 
+ * @param {Object} args - Command arguments
+ * @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 {
+    log.info(`Adding dependency with args: ${JSON.stringify(args)}`);
+    
+    // Validate required parameters
+    if (!args.id) {
+      return {
+        success: false,
+        error: {
+          code: 'INPUT_VALIDATION_ERROR',
+          message: 'Task ID (id) is required'
+        }
+      };
+    }
+    
+    if (!args.dependsOn) {
+      return {
+        success: false,
+        error: {
+          code: 'INPUT_VALIDATION_ERROR',
+          message: 'Dependency ID (dependsOn) is required'
+        }
+      };
+    }
+    
+    // Find the tasks.json path
+    const tasksPath = findTasksJsonPath(args, log);
+    
+    // Format IDs for the core function
+    const taskId = args.id.includes && args.id.includes('.') ? args.id : parseInt(args.id, 10);
+    const dependencyId = args.dependsOn.includes && args.dependsOn.includes('.') ? args.dependsOn : parseInt(args.dependsOn, 10);
+    
+    log.info(`Adding dependency: task ${taskId} will depend on ${dependencyId}`);
+    
+    // Enable silent mode to prevent console logs from interfering with JSON response
+    enableSilentMode();
+    
+    // Call the core function
+    await addDependency(tasksPath, taskId, dependencyId);
+    
+    // Restore normal logging
+    disableSilentMode();
+    
+    return {
+      success: true,
+      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 {
+      success: false,
+      error: {
+        code: 'CORE_FUNCTION_ERROR',
+        message: error.message
+      }
+    };
+  }
+} 

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

@@ -0,0 +1,128 @@
+/**
+ * Direct function wrapper for addSubtask
+ */
+
+import { addSubtask } from '../../../../scripts/modules/task-manager.js';
+import { findTasksJsonPath } from '../utils/path-utils.js';
+import { enableSilentMode, disableSilentMode } from '../../../../scripts/modules/utils.js';
+
+/**
+ * Add a subtask to an existing task
+ * @param {Object} args - Function arguments
+ * @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)
+ * @param {string} [args.description] - Description for new subtask
+ * @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 {
+    log.info(`Adding subtask with args: ${JSON.stringify(args)}`);
+    
+    if (!args.id) {
+      return {
+        success: false,
+        error: {
+          code: 'INPUT_VALIDATION_ERROR',
+          message: 'Parent task ID is required'
+        }
+      };
+    }
+    
+    // Either taskId or title must be provided
+    if (!args.taskId && !args.title) {
+      return {
+        success: false,
+        error: {
+          code: 'INPUT_VALIDATION_ERROR',
+          message: 'Either taskId or title must be provided'
+        }
+      };
+    }
+
+    // Find the tasks.json path
+    const tasksPath = findTasksJsonPath(args, log);
+    
+    // Parse dependencies if provided
+    let dependencies = [];
+    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
+    const existingTaskId = args.taskId ? parseInt(args.taskId, 10) : null;
+    
+    // Convert parent ID to a number
+    const parentId = parseInt(args.id, 10);
+    
+    // Determine if we should generate files
+    const generateFiles = !args.skipGenerate;
+    
+    // Enable silent mode to prevent console logs from interfering with JSON response
+    enableSilentMode();
+    
+    // Case 1: Convert existing task to subtask
+    if (existingTaskId) {
+      log.info(`Converting task ${existingTaskId} to a subtask of ${parentId}`);
+      const result = await addSubtask(tasksPath, parentId, existingTaskId, null, generateFiles);
+      
+      // Restore normal logging
+      disableSilentMode();
+      
+      return {
+        success: true,
+        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 = {
+        title: args.title,
+        description: args.description || '',
+        details: args.details || '',
+        status: args.status || 'pending',
+        dependencies: dependencies
+      };
+      
+      const result = await addSubtask(tasksPath, parentId, null, newSubtaskData, generateFiles);
+      
+      // Restore normal logging
+      disableSilentMode();
+      
+      return {
+        success: true,
+        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 {
+      success: false,
+      error: {
+        code: 'CORE_FUNCTION_ERROR',
+        message: error.message
+      }
+    };
+  }
+} 

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

@@ -0,0 +1,176 @@
+/**
+ * add-task.js
+ * Direct function implementation for adding a new task
+ */
+
+import { addTask } from '../../../../scripts/modules/task-manager.js';
+import { findTasksJsonPath } from '../utils/path-utils.js';
+import { 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 {Array<number>} [args.dependencies=[]] - Task dependencies as array of IDs
+ * @param {string} [args.priority='medium'] - Task priority (high, medium, low)
+ * @param {string} [args.file] - Path to the tasks file
+ * @param {string} [args.projectRoot] - Project root directory
+ * @param {boolean} [args.research] - 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, context = {}) {
+  try {
+    // Enable silent mode to prevent console logs from interfering with JSON response
+    enableSilentMode();
+    
+    // Find the tasks.json path
+    const tasksPath = findTasksJsonPath(args, log);
+    
+    // Check required parameters
+    if (!args.prompt) {
+      log.error('Missing required parameter: prompt');
+      disableSilentMode();
+      return {
+        success: false,
+        error: {
+          code: 'MISSING_PARAMETER',
+          message: 'The prompt parameter is required for adding a task'
+        }
+      };
+    }
+    
+    // Extract and prepare parameters
+    const prompt = args.prompt;
+    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}`);
+    
+    // Extract context parameters for advanced functionality
+    // Commenting out reportProgress extraction
+    // const { reportProgress, session } = context; 
+    const { session } = context; // Keep session
+
+    // 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
+        },
+        {
+          // reportProgress: context.reportProgress, // Commented out to prevent Cursor stroking out 
+          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, 
+      dependencies, 
+      priority, 
+      { 
+        // reportProgress, // Commented out
+        mcpLog: log, 
+        session,
+        taskDataFromAI // Pass the parsed AI result
+      }, 
+      'json'
+    );
+    
+    // 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

@@ -0,0 +1,156 @@
+/**
+ * Direct function wrapper for analyzeTaskComplexity
+ */
+
+import { analyzeTaskComplexity } from '../../../../scripts/modules/task-manager.js';
+import { findTasksJsonPath } from '../utils/path-utils.js';
+import { 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.output] - Output file path for 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, context = {}) {
+  const { session } = context; // Only extract session, not reportProgress
+  
+  try {
+    log.info(`Analyzing task complexity with args: ${JSON.stringify(args)}`);
+    
+    // Find the tasks.json path
+    const tasksPath = findTasksJsonPath(args, log);
+    
+    // Determine output path
+    let outputPath = args.output || 'scripts/task-complexity-report.json';
+    if (!path.isAbsolute(outputPath) && args.projectRoot) {
+      outputPath = path.join(args.projectRoot, outputPath);
+    }
+    
+    log.info(`Analyzing task complexity from: ${tasksPath}`);
+    log.info(`Output report will be saved to: ${outputPath}`);
+    
+    if (args.research) {
+      log.info('Using Perplexity AI for research-backed complexity analysis');
+    }
+    
+    // Create options object for analyzeTaskComplexity
+    const options = {
+      file: tasksPath,
+      output: outputPath,
+      model: args.model,
+      threshold: args.threshold,
+      research: args.research === true
+    };
+    
+    // Enable silent mode to prevent console logs from interfering with JSON response
+    const wasSilent = isSilentMode();
+    if (!wasSilent) {
+      enableSilentMode();
+    }
+    
+    // Create a logWrapper that matches the expected mcpLog interface as specified in utilities.mdc
+    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
+    };
+    
+    try {
+      // Call the core function with session and logWrapper as mcpLog
+      await analyzeTaskComplexity(options, {
+        session,
+        mcpLog: logWrapper // Use the wrapper instead of passing log directly
+      });
+    } 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();
+      }
+    }
+    
+    // Verify the report file was created
+    if (!fs.existsSync(outputPath)) {
+      return {
+        success: false,
+        error: {
+          code: 'ANALYZE_ERROR',
+          message: 'Analysis completed but no report file was created'
+        }
+      };
+    }
+    
+    // Read the report file
+    let report;
+    try {
+      report = JSON.parse(fs.readFileSync(outputPath, 'utf8'));
+      
+      // Important: Handle different report formats
+      // The core function might return an array or an object with a complexityAnalysis property
+      const analysisArray = Array.isArray(report) ? report : 
+                           (report.complexityAnalysis || []);
+      
+      // 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 ${outputPath}`,
+          reportPath: outputPath,
+          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

@@ -0,0 +1,32 @@
+/**
+ * cache-stats.js
+ * Direct function implementation for retrieving cache statistics
+ */
+
+import { contextManager } from '../context-manager.js';
+
+/**
+ * Get cache statistics for monitoring
+ * @param {Object} args - Command arguments
+ * @param {Object} log - Logger object
+ * @returns {Object} - Cache statistics
+ */
+export async function getCacheStatsDirect(args, log) {
+  try {
+    log.info('Retrieving cache statistics');
+    const stats = contextManager.getStats();
+    return {
+      success: true,
+      data: stats
+    };
+  } catch (error) {
+    log.error(`Error getting cache stats: ${error.message}`);
+    return {
+      success: false,
+      error: {
+        code: 'CACHE_STATS_ERROR',
+        message: error.message || 'Unknown error occurred'
+      }
+    };
+  }
+} 

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

@@ -0,0 +1,112 @@
+/**
+ * Direct function wrapper for clearSubtasks
+ */
+
+import { clearSubtasks } from '../../../../scripts/modules/task-manager.js';
+import { findTasksJsonPath } from '../utils/path-utils.js';
+import { enableSilentMode, disableSilentMode } from '../../../../scripts/modules/utils.js';
+import fs from 'fs';
+
+/**
+ * Clear subtasks from specified tasks
+ * @param {Object} args - Function arguments
+ * @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 {
+    log.info(`Clearing subtasks with args: ${JSON.stringify(args)}`);
+    
+    // Either id or all must be provided
+    if (!args.id && !args.all) {
+      return {
+        success: false,
+        error: {
+          code: 'INPUT_VALIDATION_ERROR',
+          message: 'Either task IDs with id parameter or all parameter must be provided'
+        }
+      };
+    }
+
+    // Find the tasks.json path
+    const tasksPath = findTasksJsonPath(args, log);
+    
+    // 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}`
+        }
+      };
+    }
+    
+    let taskIds;
+    
+    // If all is specified, get all task IDs
+    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}`);
+    
+    // Enable silent mode to prevent console logs from interfering with JSON response
+    enableSilentMode();
+    
+    // Call the core function
+    clearSubtasks(tasksPath, taskIds);
+    
+    // Restore normal logging
+    disableSilentMode();
+    
+    // Read the updated data to provide a summary
+    const updatedData = JSON.parse(fs.readFileSync(tasksPath, 'utf8'));
+    const taskIdArray = taskIds.split(',').map(id => parseInt(id.trim(), 10));
+    
+    // Build a summary of what was done
+    const clearedTasksCount = taskIdArray.length;
+    const taskSummary = taskIdArray.map(id => {
+      const task = updatedData.tasks.find(t => t.id === id);
+      return task ? { id, title: task.title } : { id, title: 'Task not found' };
+    });
+    
+    return {
+      success: true,
+      data: {
+        message: `Successfully cleared subtasks from ${clearedTasksCount} task(s)`,
+        tasksCleared: taskSummary
+      }
+    };
+  } 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

@@ -0,0 +1,121 @@
+/**
+ * complexity-report.js
+ * Direct function implementation for displaying complexity analysis report
+ */
+
+import { readComplexityReport, enableSilentMode, disableSilentMode } from '../../../../scripts/modules/utils.js';
+import { findTasksJsonPath } from '../utils/path-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} log - Logger object
+ * @returns {Promise<Object>} - Result object with success status and data/error information
+ */
+export async function complexityReportDirect(args, log) {
+  try {
+    log.info(`Getting complexity report with args: ${JSON.stringify(args)}`);
+    
+    // Get tasks file path to determine project root for the default report location
+    let tasksPath;
+    try {
+      tasksPath = findTasksJsonPath(args, log);
+    } catch (error) {
+      log.warn(`Tasks file not found, using current directory: ${error.message}`);
+      // Continue with default or specified report path
+    }
+
+    // Get report file path from args or use default
+    const reportPath = args.file || path.join(process.cwd(), 'scripts', 'task-complexity-report.json');
+    
+    log.info(`Looking for complexity report at: ${reportPath}`);
+    
+    // Generate cache key based on report path
+    const cacheKey = `complexityReport:${reportPath}`;
+    
+    // Define the core action function to read the report
+    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();
+        
+        if (!report) {
+          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.` 
+            }
+          };
+        }
+        
+        return {
+          success: true,
+          data: {
+            report,
+            reportPath
+          }
+        };
+      } catch (error) {
+        // Make sure to restore normal logging even if there's an error
+        disableSilentMode();
+        
+        log.error(`Error reading complexity report: ${error.message}`);
+        return { 
+          success: false, 
+          error: { 
+            code: 'READ_ERROR', 
+            message: error.message 
+          }
+        };
+      }
+    };
+
+    // Use the caching utility
+    try {
+      const result = await getCachedOrExecute({
+        cacheKey,
+        actionFn: coreActionFn,
+        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();
+      
+      log.error(`Unexpected error during getCachedOrExecute for complexityReport: ${error.message}`);
+      return { 
+        success: false, 
+        error: { 
+          code: 'UNEXPECTED_ERROR', 
+          message: error.message 
+        }, 
+        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

@@ -0,0 +1,120 @@
+/**
+ * Direct function wrapper for expandAllTasks
+ */
+
+import { expandAllTasks } from '../../../../scripts/modules/task-manager.js';
+import { enableSilentMode, disableSilentMode, isSilentMode } from '../../../../scripts/modules/utils.js';
+import { findTasksJsonPath } from '../utils/path-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 {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, context = {}) {
+  const { session } = context; // Only extract session, not reportProgress
+  
+  try {
+    log.info(`Expanding all tasks with args: ${JSON.stringify(args)}`);
+    
+    // Enable silent mode early to prevent any console output
+    enableSilentMode();
+    
+    try {
+      // Find the tasks.json path
+      const tasksPath = findTasksJsonPath(args, log);
+      
+      // Parse parameters
+      const numSubtasks = args.num ? parseInt(args.num, 10) : undefined;
+      const useResearch = args.research === true;
+      const additionalContext = args.prompt || '';
+      const forceFlag = args.force === true;
+      
+      log.info(`Expanding all tasks with ${numSubtasks || 'default'} subtasks each...`);
+      
+      if (useResearch) {
+        log.info('Using Perplexity AI for research-backed subtask generation');
+        
+        // Initialize AI client for research-backed expansion
+        try {
+          await getAnthropicClientForMCP(session, log);
+        } catch (error) {
+          // Ensure silent mode is disabled before returning error
+          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

@@ -0,0 +1,249 @@
+/**
+ * expand-task.js
+ * Direct function implementation for expanding a task into subtasks
+ */
+
+import { expandTask } from '../../../../scripts/modules/task-manager.js';
+import { readJSON, writeJSON, enableSilentMode, disableSilentMode, isSilentMode } from '../../../../scripts/modules/utils.js';
+import { findTasksJsonPath } from '../utils/path-utils.js';
+import { getAnthropicClientForMCP, getModelConfig } from '../utils/ai-client-utils.js';
+import path from 'path';
+import fs from 'fs';
+
+/**
+ * Direct function wrapper for expanding a task into subtasks with error handling.
+ *
+ * @param {Object} args - Command arguments
+ * @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, context = {}) {
+  const { session } = context;
+  
+  // Log session root data for debugging
+  log.info(`Session data in expandTaskDirect: ${JSON.stringify({
+    hasSession: !!session,
+    sessionKeys: session ? Object.keys(session) : [],
+    roots: session?.roots,
+    rootsStr: JSON.stringify(session?.roots)
+  })}`);
+  
+  let tasksPath;
+  try {
+    // If a direct file path is provided, use it directly
+    if (args.file && fs.existsSync(args.file)) {
+      log.info(`[expandTaskDirect] Using explicitly provided tasks file: ${args.file}`);
+      tasksPath = args.file;
+    } else {
+      // Find the tasks path through standard logic
+      log.info(`[expandTaskDirect] No direct file path provided or file not found at ${args.file}, searching using findTasksJsonPath`);
+      tasksPath = findTasksJsonPath(args, log);
+    }
+  } catch (error) {
+    log.error(`[expandTaskDirect] Error during tasksPath determination: ${error.message}`);
+    
+    // Include session roots information in error
+    const sessionRootsInfo = session ? 
+      `\nSession.roots: ${JSON.stringify(session.roots)}\n` +
+      `Current Working Directory: ${process.cwd()}\n` +
+      `Args.projectRoot: ${args.projectRoot}\n` +
+      `Args.file: ${args.file}\n` : 
+      '\nSession object not available';
+    
+    return { 
+      success: false, 
+      error: { 
+        code: 'FILE_NOT_FOUND_ERROR', 
+        message: `Error determining tasksPath: ${error.message}${sessionRootsInfo}` 
+      }, 
+      fromCache: false 
+    };
+  }
+
+  log.info(`[expandTaskDirect] Determined tasksPath: ${tasksPath}`);
+
+  // Validate task ID
+  const taskId = args.id ? parseInt(args.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 
+    };
+  }
+
+  // Process other parameters
+  const numSubtasks = args.num ? parseInt(args.num, 10) : undefined;
+  const useResearch = args.research === true;
+  const additionalContext = args.prompt || '';
+
+  // Initialize AI client if needed (for expandTask function)
+  try {
+    // This ensures the AI client is available by checking it
+    if (useResearch) {
+      log.info('Verifying AI client for research-backed expansion');
+      await 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
+    };
+  }
+
+  try {
+    log.info(`[expandTaskDirect] Expanding task ${taskId} into ${numSubtasks || 'default'} subtasks. Research: ${useResearch}`);
+    
+    // Read tasks data
+    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'}`);
+
+    if (!data || !data.tasks) {
+      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
+      };
+    }
+    
+    // Find the specific task
+    log.info(`[expandTaskDirect] Searching for task ID ${taskId} in data`);
+    const task = data.tasks.find(t => t.id === taskId);
+    log.info(`[expandTaskDirect] Task found: ${task ? 'Yes' : 'No'}`);
+    
+    if (!task) {
+      return { 
+        success: false, 
+        error: { 
+          code: 'TASK_NOT_FOUND', 
+          message: `Task with ID ${taskId} not found` 
+        }, 
+        fromCache: false
+      };
+    }
+    
+    // Check if task is completed
+    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
+      };
+    }
+    
+    // Check for existing subtasks
+    const hasExistingSubtasks = task.subtasks && task.subtasks.length > 0;
+    
+    // If the task already has subtasks, just return it (matching core behavior)
+    if (hasExistingSubtasks) {
+      log.info(`Task ${taskId} already has ${task.subtasks.length} subtasks`);
+      return { 
+        success: true, 
+        data: { 
+          task,
+          subtasksAdded: 0,
+          hasExistingSubtasks
+        }, 
+        fromCache: false 
+      };
+    }
+    
+    // Keep a copy of the task before modification
+    const originalTask = JSON.parse(JSON.stringify(task));
+    
+    // Tracking subtasks count before expansion
+    const subtasksCountBefore = task.subtasks ? task.subtasks.length : 0;
+    
+    // Create a backup of the tasks.json file
+    const backupPath = path.join(path.dirname(tasksPath), 'tasks.json.bak');
+    fs.copyFileSync(tasksPath, backupPath);
+    
+    // Directly modify the data instead of calling the CLI function
+    if (!task.subtasks) {
+      task.subtasks = [];
+    }
+    
+    // Save tasks.json with potentially empty subtasks array
+    writeJSON(tasksPath, data);
+    
+    // Process the request
+    try {
+      // Enable silent mode to prevent console logs from interfering with JSON response
+      enableSilentMode();
+      
+      // Call expandTask with session context to ensure AI client is properly initialized
+      const result = await expandTask(
+        tasksPath,
+        taskId, 
+        numSubtasks, 
+        useResearch, 
+        additionalContext, 
+        { mcpLog: log, session } // Only pass mcpLog and session, NOT reportProgress
+      );
+      
+      // 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

@@ -0,0 +1,65 @@
+/**
+ * Direct function wrapper for fixDependenciesCommand
+ */
+
+import { fixDependenciesCommand } from '../../../../scripts/modules/dependency-manager.js';
+import { findTasksJsonPath } from '../utils/path-utils.js';
+import { 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.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 {
+    log.info(`Fixing invalid dependencies in tasks...`);
+    
+    // Find the tasks.json path
+    const tasksPath = findTasksJsonPath(args, log);
+    
+    // Verify the file exists
+    if (!fs.existsSync(tasksPath)) {
+      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
+    enableSilentMode();
+    
+    // Call the original command function
+    await fixDependenciesCommand(tasksPath);
+    
+    // Restore normal logging
+    disableSilentMode();
+    
+    return {
+      success: true,
+      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 {
+      success: false,
+      error: {
+        code: 'FIX_DEPENDENCIES_ERROR',
+        message: error.message
+      }
+    };
+  }
+} 

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

@@ -0,0 +1,87 @@
+/**
+ * generate-task-files.js
+ * Direct function implementation for generating task files from tasks.json
+ */
+
+import { generateTaskFiles } from '../../../../scripts/modules/task-manager.js';
+import { enableSilentMode, disableSilentMode } from '../../../../scripts/modules/utils.js';
+import { findTasksJsonPath } from '../utils/path-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} log - Logger object.
+ * @returns {Promise<Object>} - Result object with success status and data/error information.
+ */
+export async function generateTaskFilesDirect(args, log) {
+  try {
+    log.info(`Generating task files with args: ${JSON.stringify(args)}`);
+    
+    // Get tasks file path
+    let tasksPath;
+    try {
+      tasksPath = findTasksJsonPath(args, log);
+    } catch (error) {
+      log.error(`Error finding tasks file: ${error.message}`);
+      return { 
+        success: false, 
+        error: { code: 'TASKS_FILE_ERROR', message: error.message },
+        fromCache: false 
+      };
+    }
+    
+    // Get output directory (defaults to the same directory as the tasks file)
+    let outputDir = args.output;
+    if (!outputDir) {
+      outputDir = path.dirname(tasksPath);
+    }
+    
+    log.info(`Generating task files from ${tasksPath} to ${outputDir}`);
+    
+    // Execute core generateTaskFiles function in a separate try/catch
+    try {
+      // Enable silent mode to prevent logs from being written to stdout
+      enableSilentMode();
+      
+      // The function is synchronous despite being awaited elsewhere
+      generateTaskFiles(tasksPath, outputDir);
+      
+      // Restore normal logging after task generation
+      disableSilentMode();
+    } catch (genError) {
+      // Make sure to restore normal logging even if there's an error
+      disableSilentMode();
+      
+      log.error(`Error in generateTaskFiles: ${genError.message}`);
+      return { 
+        success: false, 
+        error: { code: 'GENERATE_FILES_ERROR', message: genError.message },
+        fromCache: false 
+      };
+    }
+    
+    // Return success with file paths
+    return {
+      success: true,
+      data: {
+        message: `Successfully generated task files`,
+        tasksPath,
+        outputDir,
+        taskFiles: 'Individual task files have been generated in the output directory'
+      },
+      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
+    disableSilentMode();
+    
+    log.error(`Error generating task files: ${error.message}`);
+    return { 
+      success: false, 
+      error: { code: 'GENERATE_TASKS_ERROR', message: error.message || 'Unknown error generating task files' },
+      fromCache: false 
+    };
+  }
+} 

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

@@ -0,0 +1,83 @@
+/**
+ * list-tasks.js
+ * Direct function implementation for listing tasks
+ */
+
+import { listTasks } from '../../../../scripts/modules/task-manager.js';
+import { getCachedOrExecute } from '../../tools/utils.js';
+import { findTasksJsonPath } from '../utils/path-utils.js';
+import { 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} 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;
+  try {
+    // 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
+  const statusFilter = args.status || 'all';
+  const withSubtasks = args.withSubtasks || false;
+  const cacheKey = `listTasks:${tasksPath}:${statusFilter}:${withSubtasks}`;
+  
+  // Define the action function to be executed on cache miss
+  const coreListTasksAction = async () => {
+    try {
+      // Enable silent mode to prevent console logs from interfering with JSON response
+      enableSilentMode();
+      
+      log.info(`Executing core listTasks function for path: ${tasksPath}, filter: ${statusFilter}, subtasks: ${withSubtasks}`);
+      const resultData = listTasks(tasksPath, statusFilter, withSubtasks, 'json');
+
+      if (!resultData || !resultData.tasks) {
+        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`);
+      
+      // Restore normal logging
+      disableSilentMode();
+      
+      return { success: true, data: resultData };
+
+    } catch (error) {
+      // Make sure to restore normal logging even if there's an error
+      disableSilentMode();
+      
+      log.error(`Core listTasks function failed: ${error.message}`);
+      return { success: false, error: { code: 'LIST_TASKS_CORE_ERROR', message: error.message || 'Failed to list tasks' } };
+    }
+  };
+
+  // Use the caching utility
+  try {
+      const result = await getCachedOrExecute({
+          cacheKey,
+          actionFn: coreListTasksAction,
+          log
+      });
+      log.info(`listTasksDirect completed. From cache: ${result.fromCache}`);
+      return result; // Returns { success, data/error, fromCache }
+  } catch(error) {
+      // Catch unexpected errors from getCachedOrExecute itself (though unlikely)
+      log.error(`Unexpected error during getCachedOrExecute for listTasks: ${error.message}`);
+      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

@@ -0,0 +1,122 @@
+/**
+ * next-task.js
+ * Direct function implementation for finding the next task to work on
+ */
+
+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 { 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 {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;
+  try {
+    // 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
+  const cacheKey = `nextTask:${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();
+      
+      log.info(`Finding next task from ${tasksPath}`);
+      
+      // Read tasks data
+      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
+      const nextTask = findNextTask(data.tasks);
+      
+      if (!nextTask) {
+        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 
+          } 
+        };
+      }
+      
+      // Restore normal logging
+      disableSilentMode();
+      
+      // Return the next task data with the full tasks array for reference
+      log.info(`Successfully found next task ${nextTask.id}: ${nextTask.title}`);
+      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 { 
+        success: false, 
+        error: { 
+          code: 'CORE_FUNCTION_ERROR', 
+          message: error.message || 'Failed to find next task' 
+        } 
+      };
+    }
+  };
+
+  // Use the caching utility
+  try {
+    const result = await getCachedOrExecute({
+      cacheKey,
+      actionFn: coreNextTaskAction,
+      log
+    });
+    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

@@ -0,0 +1,150 @@
+/**
+ * parse-prd.js
+ * Direct function implementation for parsing PRD documents
+ */
+
+import path from 'path';
+import fs from 'fs';
+import { parsePRD } from '../../../../scripts/modules/task-manager.js';
+import { findTasksJsonPath } from '../utils/path-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, context = {}) {
+  const { session } = context; // Only extract session, not reportProgress
+  
+  try {
+    log.info(`Parsing PRD document with args: ${JSON.stringify(args)}`);
+    
+    // Initialize AI client for PRD parsing
+    let aiClient;
+    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
+      };
+    }
+    
+    // Parameter validation and path resolution
+    if (!args.input) {
+      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)
+    const projectRoot = args.projectRoot || process.cwd();
+    const inputPath = path.isAbsolute(args.input) ? args.input : path.resolve(projectRoot, args.input);
+    
+    // Determine output path
+    let outputPath;
+    if (args.output) {
+      outputPath = path.isAbsolute(args.output) ? args.output : path.resolve(projectRoot, args.output);
+    } else {
+      // Default to tasks/tasks.json in the project root
+      outputPath = path.resolve(projectRoot, 'tasks', 'tasks.json');
+    }
+    
+    // Verify input file exists
+    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 },
+        fromCache: false 
+      };
+    }
+    
+    // Parse number of tasks - handle both string and number values
+    let numTasks = 10; // Default
+    if (args.numTasks) {
+      numTasks = 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`);
+      }
+    }
+    
+    log.info(`Preparing to parse PRD from ${inputPath} and output to ${outputPath} with ${numTasks} tasks`);
+    
+    // Create the logger wrapper for proper logging in the core function
+    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
+    };
+
+    // Get model config from session
+    const modelConfig = getModelConfig(session);
+    
+    // Enable silent mode to prevent console logs from interfering with JSON response
+    enableSilentMode();
+    try {
+      // 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

@@ -0,0 +1,83 @@
+/**
+ * Direct function wrapper for removeDependency
+ */
+
+import { removeDependency } from '../../../../scripts/modules/dependency-manager.js';
+import { findTasksJsonPath } from '../utils/path-utils.js';
+import { enableSilentMode, disableSilentMode } from '../../../../scripts/modules/utils.js';
+
+/**
+ * Remove a dependency from a task
+ * @param {Object} args - Function arguments
+ * @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 {
+    log.info(`Removing dependency with args: ${JSON.stringify(args)}`);
+    
+    // Validate required parameters
+    if (!args.id) {
+      return {
+        success: false,
+        error: {
+          code: 'INPUT_VALIDATION_ERROR',
+          message: 'Task ID (id) is required'
+        }
+      };
+    }
+    
+    if (!args.dependsOn) {
+      return {
+        success: false,
+        error: {
+          code: 'INPUT_VALIDATION_ERROR',
+          message: 'Dependency ID (dependsOn) is required'
+        }
+      };
+    }
+    
+    // Find the tasks.json path
+    const tasksPath = findTasksJsonPath(args, log);
+    
+    // Format IDs for the core function
+    const taskId = args.id.includes && args.id.includes('.') ? args.id : parseInt(args.id, 10);
+    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}`);
+    
+    // Enable silent mode to prevent console logs from interfering with JSON response
+    enableSilentMode();
+    
+    // Call the core function
+    await removeDependency(tasksPath, taskId, dependencyId);
+    
+    // Restore normal logging
+    disableSilentMode();
+    
+    return {
+      success: true,
+      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 {
+      success: false,
+      error: {
+        code: 'CORE_FUNCTION_ERROR',
+        message: error.message
+      }
+    };
+  }
+} 

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

@@ -0,0 +1,95 @@
+/**
+ * Direct function wrapper for removeSubtask
+ */
+
+import { removeSubtask } from '../../../../scripts/modules/task-manager.js';
+import { findTasksJsonPath } from '../utils/path-utils.js';
+import { enableSilentMode, disableSilentMode } from '../../../../scripts/modules/utils.js';
+
+/**
+ * Remove a subtask from its parent task
+ * @param {Object} args - Function arguments
+ * @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 {
+    // Enable silent mode to prevent console logs from interfering with JSON response
+    enableSilentMode();
+    
+    log.info(`Removing subtask with args: ${JSON.stringify(args)}`);
+    
+    if (!args.id) {
+      return {
+        success: false,
+        error: {
+          code: 'INPUT_VALIDATION_ERROR',
+          message: 'Subtask ID is required and must be in format "parentId.subtaskId"'
+        }
+      };
+    }
+    
+    // Validate subtask ID format
+    if (!args.id.includes('.')) {
+      return {
+        success: false,
+        error: {
+          code: 'INPUT_VALIDATION_ERROR',
+          message: `Invalid subtask ID format: ${args.id}. Expected format: "parentId.subtaskId"`
+        }
+      };
+    }
+
+    // Find the tasks.json path
+    const tasksPath = findTasksJsonPath(args, log);
+    
+    // Convert convertToTask to a boolean
+    const convertToTask = args.convert === true;
+    
+    // Determine if we should generate files
+    const generateFiles = !args.skipGenerate;
+    
+    log.info(`Removing subtask ${args.id} (convertToTask: ${convertToTask}, generateFiles: ${generateFiles})`);
+    
+    const result = await removeSubtask(tasksPath, args.id, convertToTask, generateFiles);
+    
+    // Restore normal logging
+    disableSilentMode();
+    
+    if (convertToTask && result) {
+      // Return info about the converted task
+      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}`);
+    return {
+      success: false,
+      error: {
+        code: 'CORE_FUNCTION_ERROR',
+        message: error.message
+      }
+    };
+  }
+} 

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

@@ -0,0 +1,104 @@
+/**
+ * remove-task.js
+ * Direct function implementation for removing a task
+ */
+
+import { removeTask } from '../../../../scripts/modules/task-manager.js';
+import { enableSilentMode, disableSilentMode } from '../../../../scripts/modules/utils.js';
+import { findTasksJsonPath } from '../utils/path-utils.js';
+
+/**
+ * Direct function wrapper for removeTask with error handling.
+ *
+ * @param {Object} args - Command arguments
+ * @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 {
+    // Find the tasks path first
+    let tasksPath;
+    try {
+      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 parameter
+    const taskId = args.id;
+    if (!taskId) {
+      log.error('Task ID is required');
+      return { 
+        success: false, 
+        error: { 
+          code: 'INPUT_VALIDATION_ERROR', 
+          message: 'Task ID is required' 
+        }, 
+        fromCache: false 
+      };
+    }
+    
+    // Skip confirmation in the direct function since it's handled by the client
+    log.info(`Removing task with ID: ${taskId} from ${tasksPath}`);
+    
+    try {
+      // Enable silent mode to prevent console logs from interfering with JSON response
+      enableSilentMode();
+      
+      // Call the core removeTask function
+      const result = await removeTask(tasksPath, taskId);
+      
+      // Restore normal logging
+      disableSilentMode();
+      
+      log.info(`Successfully removed task: ${taskId}`);
+      
+      // Return the result
+      return {
+        success: true,
+        data: {
+          message: result.message,
+          taskId: taskId,
+          tasksPath: tasksPath,
+          removedTask: result.removedTask
+        },
+        fromCache: false
+      };
+    } catch (error) {
+      // Make sure to restore normal logging even if there's an error
+      disableSilentMode();
+      
+      log.error(`Error removing task: ${error.message}`);
+      return { 
+        success: false, 
+        error: { 
+          code: error.code || 'REMOVE_TASK_ERROR', 
+          message: error.message || 'Failed to remove task' 
+        }, 
+        fromCache: false 
+      };
+    }
+  } catch (error) {
+    // Ensure silent mode is disabled even if an outer error occurs
+    disableSilentMode();
+    
+    // Catch any unexpected errors
+    log.error(`Unexpected error in removeTaskDirect: ${error.message}`);
+    return { 
+      success: false, 
+      error: { 
+        code: 'UNEXPECTED_ERROR', 
+        message: error.message 
+      }, 
+      fromCache: false 
+    };
+  }
+} 

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

@@ -0,0 +1,112 @@
+/**
+ * set-task-status.js
+ * Direct function implementation for setting task status
+ */
+
+import { setTaskStatus } from '../../../../scripts/modules/task-manager.js';
+import { findTasksJsonPath } from '../utils/path-utils.js';
+import { 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} log - Logger object.
+ * @returns {Promise<Object>} - Result object with success status and data/error information.
+ */
+export async function setTaskStatusDirect(args, log) {
+  try {
+    log.info(`Setting task status with args: ${JSON.stringify(args)}`);
+    
+    // Check required parameters
+    if (!args.id) {
+      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.status) {
+      const errorMessage = 'No status specified. Please provide a new status value.';
+      log.error(errorMessage);
+      return { 
+        success: false, 
+        error: { code: 'MISSING_STATUS', message: errorMessage },
+        fromCache: false 
+      };
+    }
+    
+    // Get tasks file path
+    let tasksPath;
+    try {
+      // The enhanced findTasksJsonPath will now search in parent directories if needed
+      tasksPath = findTasksJsonPath(args, log);
+      log.info(`Found tasks file at: ${tasksPath}`);
+    } catch (error) {
+      log.error(`Error finding tasks file: ${error.message}`);
+      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
+    const taskId = args.id;
+    const newStatus = args.status;
+    
+    log.info(`Setting task ${taskId} status to "${newStatus}"`);
+    
+    // Call the core function with proper silent mode handling
+    let result;
+    enableSilentMode(); // Enable silent mode before calling core function
+    try {
+      // Call the core function
+      await setTaskStatus(tasksPath, taskId, newStatus, { mcpLog: log });
+      
+      log.info(`Successfully set task ${taskId} status to ${newStatus}`);
+      
+      // Return success data
+      result = {
+        success: true,
+        data: {
+          message: `Successfully updated task ${taskId} status to "${newStatus}"`,
+          taskId,
+          status: newStatus,
+          tasksPath
+        },
+        fromCache: false // This operation always modifies state and should never be cached
+      };
+    } catch (error) {
+      log.error(`Error setting task status: ${error.message}`);
+      result = { 
+        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();
+    }
+    
+    return result;
+  } catch (error) {
+    // Ensure silent mode is disabled if there was an uncaught error in the outer try block
+    if (isSilentMode()) {
+      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 
+    };
+  }
+} 

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

@@ -0,0 +1,136 @@
+/**
+ * show-task.js
+ * Direct function implementation for showing task details
+ */
+
+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 { 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 {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;
+  try {
+    // 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
+  const taskId = args.id;
+  if (!taskId) {
+    log.error('Task ID is required');
+    return { 
+      success: false, 
+      error: { 
+        code: 'INPUT_VALIDATION_ERROR', 
+        message: 'Task ID is required' 
+      }, 
+      fromCache: false 
+    };
+  }
+
+  // Generate cache key using task path and ID
+  const cacheKey = `showTask:${tasksPath}:${taskId}`;
+  
+  // 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();
+      
+      log.info(`Retrieving task details for ID: ${taskId} from ${tasksPath}`);
+      
+      // Read tasks data
+      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 specific task
+      const task = findTaskById(data.tasks, taskId);
+      
+      if (!task) {
+        return { 
+          success: false, 
+          error: { 
+            code: 'TASK_NOT_FOUND', 
+            message: `Task with ID ${taskId} not found` 
+          } 
+        };
+      }
+      
+      // Restore normal logging
+      disableSilentMode();
+      
+      // Return the task data with the full tasks array for reference
+      // (needed for formatDependenciesWithStatus function in UI)
+      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 { 
+        success: false, 
+        error: { 
+          code: 'CORE_FUNCTION_ERROR', 
+          message: error.message || 'Failed to show task details' 
+        } 
+      };
+    }
+  };
+
+  // Use the caching utility
+  try {
+    const result = await getCachedOrExecute({
+      cacheKey,
+      actionFn: coreShowTaskAction,
+      log
+    });
+    log.info(`showTaskDirect completed. From cache: ${result.fromCache}`);
+    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

@@ -0,0 +1,170 @@
+/**
+ * update-subtask-by-id.js
+ * Direct function implementation for appending information to a specific subtask
+ */
+
+import { updateSubtaskById } from '../../../../scripts/modules/task-manager.js';
+import { enableSilentMode, disableSilentMode } from '../../../../scripts/modules/utils.js';
+import { findTasksJsonPath } from '../utils/path-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} 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, context = {}) {
+  const { session } = context; // Only extract session, not reportProgress
+  
+  try {
+    log.info(`Updating subtask with args: ${JSON.stringify(args)}`);
+    
+    // Check required parameters
+    if (!args.id) {
+      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) {
+      const errorMessage = 'No prompt specified. Please provide a prompt with information to add to the subtask.';
+      log.error(errorMessage);
+      return { 
+        success: false, 
+        error: { code: 'MISSING_PROMPT', message: errorMessage },
+        fromCache: false 
+      };
+    }
+    
+    // Validate subtask ID format
+    const subtaskId = args.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
+      };
+    }
+    
+    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 
+      };
+    }
+    
+    // Get tasks file path
+    let tasksPath;
+    try {
+      tasksPath = findTasksJsonPath(args, log);
+    } catch (error) {
+      log.error(`Error finding tasks file: ${error.message}`);
+      return { 
+        success: false, 
+        error: { code: 'TASKS_FILE_ERROR', message: error.message },
+        fromCache: false 
+      };
+    }
+    
+    // Get research flag
+    const useResearch = args.research === true;
+    
+    log.info(`Updating subtask with ID ${subtaskIdStr} with prompt "${args.prompt}" and research: ${useResearch}`);
+    
+    // Initialize the appropriate AI client based on research flag
+    try {
+      if (useResearch) {
+        // Initialize Perplexity client
+        await getPerplexityClientForMCP(session);
+      } else {
+        // Initialize Anthropic client
+        await getAnthropicClientForMCP(session);
+      }
+    } 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
+      };
+    }
+    
+    try {
+      // Enable silent mode to prevent console logs from interfering with JSON response
+      enableSilentMode();
+      
+      // Create a logger wrapper object to handle logging without breaking the mcpLog[level] calls
+      // This ensures outputFormat is set to 'json' while still supporting proper logging
+      const logWrapper = {
+        info: (message) => log.info(message),
+        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, args.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

@@ -0,0 +1,172 @@
+/**
+ * update-task-by-id.js
+ * Direct function implementation for updating a single task by ID with new information
+ */
+
+import { updateTaskById } from '../../../../scripts/modules/task-manager.js';
+import { findTasksJsonPath } from '../utils/path-utils.js';
+import { 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} 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, context = {}) {
+  const { session } = context; // Only extract session, not reportProgress
+  
+  try {
+    log.info(`Updating task with args: ${JSON.stringify(args)}`);
+    
+    // Check required parameters
+    if (!args.id) {
+      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) {
+      const errorMessage = 'No prompt specified. Please provide a prompt with new information for the task update.';
+      log.error(errorMessage);
+      return { 
+        success: false, 
+        error: { code: 'MISSING_PROMPT', message: errorMessage },
+        fromCache: false 
+      };
+    }
+    
+    // Parse taskId - handle both string and number values
+    let taskId;
+    if (typeof args.id === 'string') {
+      // Handle subtask IDs (e.g., "5.2")
+      if (args.id.includes('.')) {
+        taskId = args.id; // Keep as string for subtask IDs
+      } else {
+        // Parse as integer for main task IDs
+        taskId = parseInt(args.id, 10);
+        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
+    let tasksPath;
+    try {
+      tasksPath = findTasksJsonPath(args, log);
+    } catch (error) {
+      log.error(`Error finding tasks file: ${error.message}`);
+      return { 
+        success: false, 
+        error: { code: 'TASKS_FILE_ERROR', message: error.message },
+        fromCache: false 
+      };
+    }
+    
+    // Get research flag
+    const useResearch = args.research === true;
+    
+    // Initialize appropriate AI client based on research flag
+    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
+      };
+    }
+    
+    log.info(`Updating task with ID ${taskId} with prompt "${args.prompt}" and research: ${useResearch}`);
+    
+    try {
+      // Enable silent mode to prevent console logs from interfering with JSON response
+      enableSilentMode();
+      
+      // Create a logger wrapper that matches what updateTaskById expects
+      const logWrapper = {
+        info: (message) => log.info(message),
+        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 since many loggers don't have success
+      };
+      
+      // Execute core updateTaskById function with proper parameters
+      await updateTaskById(
+        tasksPath, 
+        taskId, 
+        args.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,
+          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

@@ -0,0 +1,171 @@
+/**
+ * update-tasks.js
+ * Direct function implementation for updating tasks based on new context/prompt
+ */
+
+import { updateTasks } from '../../../../scripts/modules/task-manager.js';
+import { enableSilentMode, disableSilentMode } from '../../../../scripts/modules/utils.js';
+import { findTasksJsonPath } from '../utils/path-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} 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, context = {}) {
+  const { session } = context; // Only extract session, not reportProgress
+  
+  try {
+    log.info(`Updating tasks with args: ${JSON.stringify(args)}`);
+    
+    // Check for the common mistake of using 'id' instead of 'from'
+    if (args.id !== undefined && args.from === undefined) {
+      const errorMessage = "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.";
+      log.error(errorMessage);
+      return { 
+        success: false, 
+        error: { 
+          code: 'PARAMETER_MISMATCH', 
+          message: errorMessage,
+          suggestion: "Use 'from' parameter instead of 'id', or use the 'update_task' tool for single task updates"
+        },
+        fromCache: false 
+      };
+    }
+    
+    // Check required parameters
+    if (!args.from) {
+      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) {
+      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 
+      };
+    }
+    
+    // Parse fromId - handle both string and number values
+    let fromId;
+    if (typeof args.from === 'string') {
+      fromId = parseInt(args.from, 10);
+      if (isNaN(fromId)) {
+        const errorMessage = `Invalid from ID: ${args.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 = args.from;
+    }
+    
+    // Get tasks file path
+    let tasksPath;
+    try {
+      tasksPath = findTasksJsonPath(args, log);
+    } catch (error) {
+      log.error(`Error finding tasks file: ${error.message}`);
+      return { 
+        success: false, 
+        error: { code: 'TASKS_FILE_ERROR', message: error.message },
+        fromCache: false 
+      };
+    }
+    
+    // Get research flag
+    const useResearch = args.research === true;
+    
+    // Initialize appropriate AI client based on research flag
+    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
+      };
+    }
+    
+    log.info(`Updating tasks from ID ${fromId} with prompt "${args.prompt}" and research: ${useResearch}`);
+    
+    try {
+      // Enable silent mode to prevent console logs from interfering with JSON response
+      enableSilentMode();
+      
+      // Execute core updateTasks function, passing the AI client and session
+      await updateTasks(
+        tasksPath, 
+        fromId, 
+        args.prompt, 
+        useResearch, 
+        { 
+          mcpLog: log, 
+          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,
+          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

@@ -0,0 +1,65 @@
+/**
+ * Direct function wrapper for validateDependenciesCommand
+ */
+
+import { validateDependenciesCommand } from '../../../../scripts/modules/dependency-manager.js';
+import { findTasksJsonPath } from '../utils/path-utils.js';
+import { 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.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 {
+    log.info(`Validating dependencies in tasks...`);
+    
+    // Find the tasks.json path
+    const tasksPath = findTasksJsonPath(args, log);
+    
+    // Verify the file exists
+    if (!fs.existsSync(tasksPath)) {
+      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
+    enableSilentMode();
+    
+    // Call the original command function
+    await validateDependenciesCommand(tasksPath);
+    
+    // Restore normal logging
+    disableSilentMode();
+    
+    return {
+      success: true,
+      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

@@ -0,0 +1,96 @@
+/**
+ * task-master-core.js
+ * Central module that imports and re-exports all direct function implementations
+ * for improved organization and maintainability.
+ */
+
+// Import direct function implementations
+import { listTasksDirect } from './direct-functions/list-tasks.js';
+import { getCacheStatsDirect } from './direct-functions/cache-stats.js';
+import { parsePRDDirect } from './direct-functions/parse-prd.js';
+import { updateTasksDirect } from './direct-functions/update-tasks.js';
+import { updateTaskByIdDirect } from './direct-functions/update-task-by-id.js';
+import { updateSubtaskByIdDirect } from './direct-functions/update-subtask-by-id.js';
+import { generateTaskFilesDirect } from './direct-functions/generate-task-files.js';
+import { setTaskStatusDirect } from './direct-functions/set-task-status.js';
+import { showTaskDirect } from './direct-functions/show-task.js';
+import { nextTaskDirect } from './direct-functions/next-task.js';
+import { expandTaskDirect } from './direct-functions/expand-task.js';
+import { addTaskDirect } from './direct-functions/add-task.js';
+import { addSubtaskDirect } from './direct-functions/add-subtask.js';
+import { removeSubtaskDirect } from './direct-functions/remove-subtask.js';
+import { analyzeTaskComplexityDirect } from './direct-functions/analyze-task-complexity.js';
+import { clearSubtasksDirect } from './direct-functions/clear-subtasks.js';
+import { expandAllTasksDirect } from './direct-functions/expand-all-tasks.js';
+import { removeDependencyDirect } from './direct-functions/remove-dependency.js';
+import { validateDependenciesDirect } from './direct-functions/validate-dependencies.js';
+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';
+
+// 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],
+  ['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]
+]);
+
+// Re-export all direct function implementations
+export {
+  listTasksDirect,
+  getCacheStatsDirect,
+  parsePRDDirect,
+  updateTasksDirect,
+  updateTaskByIdDirect,
+  updateSubtaskByIdDirect,
+  generateTaskFilesDirect,
+  setTaskStatusDirect,
+  showTaskDirect,
+  nextTaskDirect,
+  expandTaskDirect,
+  addTaskDirect,
+  addSubtaskDirect,
+  removeSubtaskDirect,
+  analyzeTaskComplexityDirect,
+  clearSubtasksDirect,
+  expandAllTasksDirect,
+  removeDependencyDirect,
+  validateDependenciesDirect,
+  fixDependenciesDirect,
+  complexityReportDirect,
+  addDependencyDirect,
+  removeTaskDirect
+}; 

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

@@ -0,0 +1,188 @@
+/**
+ * ai-client-utils.js
+ * Utility functions for initializing AI clients in MCP context
+ */
+
+import { Anthropic } from '@anthropic-ai/sdk';
+import dotenv from 'dotenv';
+
+// Load environment variables for CLI mode
+dotenv.config();
+
+// Default model configuration from CLI environment
+const DEFAULT_MODEL_CONFIG = {
+  model: 'claude-3-7-sonnet-20250219',
+  maxTokens: 64000,
+  temperature: 0.2
+};
+
+/**
+ * Get an Anthropic client instance initialized with MCP session environment variables
+ * @param {Object} [session] - Session object from MCP containing environment variables
+ * @param {Object} [log] - Logger object to use (defaults to console)
+ * @returns {Anthropic} Anthropic client instance
+ * @throws {Error} If API key is missing
+ */
+export function getAnthropicClientForMCP(session, log = console) {
+  try {
+    // Extract API key from session.env or fall back to environment variables
+    const apiKey = session?.env?.ANTHROPIC_API_KEY || process.env.ANTHROPIC_API_KEY;
+    
+    if (!apiKey) {
+      throw new Error('ANTHROPIC_API_KEY not found in session environment or process.env');
+    }
+    
+    // Initialize and return a new Anthropic client
+    return new Anthropic({ 
+      apiKey,
+      defaultHeaders: {
+        'anthropic-beta': 'output-128k-2025-02-19'  // Include header for increased token limit
+      }
+    });
+  } catch (error) {
+    log.error(`Failed to initialize Anthropic client: ${error.message}`);
+    throw error;
+  }
+}
+
+/**
+ * Get a Perplexity client instance initialized with MCP session environment variables
+ * @param {Object} [session] - Session object from MCP containing environment variables
+ * @param {Object} [log] - Logger object to use (defaults to console)
+ * @returns {OpenAI} OpenAI client configured for Perplexity API
+ * @throws {Error} If API key is missing or OpenAI package can't be imported
+ */
+export async function getPerplexityClientForMCP(session, log = console) {
+  try {
+    // Extract API key from session.env or fall back to environment variables
+    const apiKey = session?.env?.PERPLEXITY_API_KEY || process.env.PERPLEXITY_API_KEY;
+    
+    if (!apiKey) {
+      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)
+    const { default: OpenAI } = await import('openai');
+    
+    // Initialize and return a new OpenAI client configured for Perplexity
+    return new OpenAI({
+      apiKey, 
+      baseURL: 'https://api.perplexity.ai'
+    });
+  } catch (error) {
+    log.error(`Failed to initialize Perplexity client: ${error.message}`);
+    throw error;
+  }
+}
+
+/**
+ * Get model configuration from session environment or fall back to defaults
+ * @param {Object} [session] - Session object from MCP containing environment variables
+ * @param {Object} [defaults] - Default model configuration to use if not in session
+ * @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
+  return {
+    model: session?.env?.MODEL || defaults.model,
+    maxTokens: parseInt(session?.env?.MAX_TOKENS || defaults.maxTokens),
+    temperature: parseFloat(session?.env?.TEMPERATURE || defaults.temperature)
+  };
+}
+
+/**
+ * Returns the best available AI model based on specified options
+ * @param {Object} session - Session object from MCP containing environment variables
+ * @param {Object} options - Options for model selection
+ * @param {boolean} [options.requiresResearch=false] - Whether the operation requires research capabilities
+ * @param {boolean} [options.claudeOverloaded=false] - Whether Claude is currently overloaded
+ * @param {Object} [log] - Logger object to use (defaults to console)
+ * @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) {
+  const { requiresResearch = false, claudeOverloaded = false } = options;
+  
+  // Test case: When research is needed but no Perplexity, use Claude
+  if (requiresResearch && 
+      !(session?.env?.PERPLEXITY_API_KEY || process.env.PERPLEXITY_API_KEY) && 
+      (session?.env?.ANTHROPIC_API_KEY || process.env.ANTHROPIC_API_KEY)) {
+    try {
+      log.warn('Perplexity not available for research, using Claude');
+      const client = getAnthropicClientForMCP(session, log);
+      return { type: 'claude', client };
+    } 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
+  if (requiresResearch && (session?.env?.PERPLEXITY_API_KEY || process.env.PERPLEXITY_API_KEY)) {
+    try {
+      const client = await getPerplexityClientForMCP(session, log);
+      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
+  if (claudeOverloaded && (session?.env?.ANTHROPIC_API_KEY || process.env.ANTHROPIC_API_KEY)) {
+    try {
+      log.warn('Claude is overloaded but no alternatives are available. Proceeding with Claude anyway.');
+      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
+  if (!claudeOverloaded && (session?.env?.ANTHROPIC_API_KEY || process.env.ANTHROPIC_API_KEY)) {
+    try {
+      const client = getAnthropicClientForMCP(session, log);
+      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
+  throw new Error('No AI models available. Please check your API keys.');
+}
+
+/**
+ * Handle Claude API errors with user-friendly messages
+ * @param {Error} error - The error from Claude API
+ * @returns {string} User-friendly error message
+ */
+export function handleClaudeError(error) {
+  // Check if it's a structured error response
+  if (error.type === 'error' && error.error) {
+    switch (error.error.type) {
+      case 'overloaded_error':
+        return 'Claude is currently experiencing high demand and is overloaded. Please wait a few minutes and try again.';
+      case 'rate_limit_error':
+        return 'You have exceeded the rate limit. Please wait a few minutes before making more requests.';
+      case 'invalid_request_error':
+        return 'There was an issue with the request format. If this persists, please report it as a bug.';
+      default:
+        return `Claude API error: ${error.error.message}`;
+    }
+  }
+  
+  // Check for network/timeout errors
+  if (error.message?.toLowerCase().includes('timeout')) {
+    return 'The request to Claude timed out. Please try again.';
+  }
+  if (error.message?.toLowerCase().includes('network')) {
+    return 'There was a network error connecting to Claude. Please check your internet connection and try again.';
+  }
+  
+  // Default error message
+  return `Error communicating with Claude: ${error.message}`;
+} 

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

@@ -0,0 +1,217 @@
+import { v4 as uuidv4 } from 'uuid';
+
+class AsyncOperationManager {
+    constructor() {
+        this.operations = new Map(); // Stores active operation state
+        this.completedOperations = new Map(); // Stores completed operations
+        this.maxCompletedOperations = 100; // Maximum number of completed operations to store
+        this.listeners = new Map(); // For potential future notifications
+    }
+
+    /**
+     * Adds an operation to be executed asynchronously.
+     * @param {Function} operationFn - The async function to execute (e.g., a Direct function).
+     * @param {Object} args - Arguments to pass to the operationFn.
+     * @param {Object} context - The MCP tool context { log, reportProgress, session }.
+     * @returns {string} The unique ID assigned to this operation.
+     */
+    addOperation(operationFn, args, context) {
+        const operationId = `op-${uuidv4()}`;
+        const operation = {
+            id: operationId,
+            status: 'pending',
+            startTime: Date.now(),
+            endTime: null,
+            result: null,
+            error: null,
+            // Store necessary parts of context, especially log for background execution
+            log: context.log, 
+            reportProgress: context.reportProgress, // Pass reportProgress through
+            session: context.session // Pass session through if needed by the operationFn
+        };
+        this.operations.set(operationId, operation);
+        this.log(operationId, 'info', `Operation added.`);
+
+        // Start execution in the background (don't await here)
+        this._runOperation(operationId, operationFn, args, context).catch(err => {
+            // Catch unexpected errors during the async execution setup itself
+             this.log(operationId, 'error', `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
+             this._moveToCompleted(operationId);
+        });
+
+        return operationId;
+    }
+
+    /**
+     * Internal function to execute the operation.
+     * @param {string} operationId - The ID of the operation.
+     * @param {Function} operationFn - The async function to execute.
+     * @param {Object} args - Arguments for the function.
+     * @param {Object} context - The original MCP tool context.
+     */
+    async _runOperation(operationId, operationFn, args, context) {
+        const operation = this.operations.get(operationId);
+        if (!operation) return; // Should not happen
+
+        operation.status = 'running';
+        this.log(operationId, 'info', `Operation running.`);
+        this.emit('statusChanged', { operationId, status: 'running' });
+
+        try {
+            // Pass the necessary context parts to the direct function
+            // The direct function needs to be adapted if it needs reportProgress
+            // We pass the original context's log, plus our wrapped reportProgress
+            const result = await operationFn(args, operation.log, { 
+                reportProgress: (progress) => this._handleProgress(operationId, progress), 
+                mcpLog: operation.log, // Pass log as mcpLog if direct fn expects it
+                session: operation.session 
+            });
+            
+            operation.status = result.success ? 'completed' : 'failed';
+            operation.result = result.success ? result.data : null;
+            operation.error = result.success ? null : result.error;
+            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 });
+            
+            // Move to completed operations if done or failed
+            if (operation.status === 'completed' || operation.status === 'failed') {
+                this._moveToCompleted(operationId);
+            }
+        }
+    }
+    
+    /**
+     * Move an operation from active operations to completed operations history.
+     * @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
+        const completedData = {
+            id: operation.id,
+            status: operation.status,
+            startTime: operation.startTime,
+            endTime: operation.endTime,
+            result: operation.result,
+            error: operation.error,
+        };
+        
+        this.completedOperations.set(operationId, completedData);
+        this.operations.delete(operationId);
+        
+        // Trim completed operations if exceeding maximum
+        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];
+            
+            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
+            }
+        }
+     }
+
+    /**
+     * Retrieves the status and result/error of an operation.
+     * @param {string} operationId - The ID of the operation.
+     * @returns {Object | null} The operation details or null if not found.
+     */
+    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
+        const completedOperation = this.completedOperations.get(operationId);
+        if (completedOperation) {
+            return completedOperation;
+        }
+        
+        // Operation not found in either active or completed
+        return {
+            error: {
+                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'
+        };
+    }
+    
+     /**
+     * Internal logging helper to prefix logs with the operation ID.
+     * @param {string} operationId - The ID of the operation.
+     * @param {'info'|'warn'|'error'|'debug'} level - Log level.
+     * @param {string} message - Log message.
+     * @param {Object} [meta] - Additional metadata.
+     */
+    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 ---
+    on(eventName, listener) {
+        if (!this.listeners.has(eventName)) {
+            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
+const asyncOperationManager = new AsyncOperationManager();
+
+// Export the manager and potentially the class if needed elsewhere
+export { asyncOperationManager, AsyncOperationManager };

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

@@ -0,0 +1,43 @@
+/**
+ * Temporarily sets environment variables from session.env, executes an action,
+ * and restores the original environment variables.
+ * @param {object | undefined} sessionEnv - The environment object from the session.
+ * @param {Function} actionFn - An async function to execute with the temporary environment.
+ * @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 no sessionEnv is provided, just run the action directly
+      return await actionFn();
+    }
+  
+    const originalEnv = {};
+    const keysToRestore = [];
+  
+    // Set environment variables from sessionEnv
+    for (const key in sessionEnv) {
+      if (Object.prototype.hasOwnProperty.call(sessionEnv, key)) {
+        // Store original value if it exists, otherwise mark for deletion
+        if (process.env[key] !== undefined) {
+          originalEnv[key] = process.env[key];
+        }
+        keysToRestore.push(key);
+        process.env[key] = sessionEnv[key];
+      }
+    }
+  
+    try {
+      // Execute the provided action function
+      return await actionFn();
+    } finally {
+      // Restore original environment variables
+      for (const key of keysToRestore) {
+        if (Object.prototype.hasOwnProperty.call(originalEnv, key)) {
+          process.env[key] = originalEnv[key];
+        } else {
+          // If the key didn't exist originally, delete it
+          delete process.env[key];
+        }
+      }
+    }
+  } 

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

@@ -0,0 +1,272 @@
+/**
+ * path-utils.js
+ * Utility functions for file path operations in Task Master
+ * 
+ * This module provides robust path resolution for both:
+ * 1. PACKAGE PATH: Where task-master code is installed 
+ *    (global node_modules OR local ./node_modules/task-master OR direct from repo)
+ * 2. PROJECT PATH: Where user's tasks.json resides (typically user's project root)
+ */
+
+import path from 'path';
+import fs from 'fs';
+import { fileURLToPath } from 'url';
+import os from 'os';
+
+// Store last found project root to improve performance on subsequent calls (primarily for CLI)
+export let lastFoundProjectRoot = null;
+
+// Project marker files that indicate a potential project root
+export const PROJECT_MARKERS = [
+  // Task Master specific
+  'tasks.json',
+  'tasks/tasks.json',
+  
+  // Common version control
+  '.git',
+  '.svn',
+  
+  // Common package files
+  'package.json',
+  'pyproject.toml',
+  'Gemfile',
+  'go.mod',
+  'Cargo.toml',
+  
+  // Common IDE/editor folders
+  '.cursor',
+  '.vscode',
+  '.idea',
+  
+  // Common dependency directories (check if directory)
+  'node_modules',
+  'venv',
+  '.venv',
+  
+  // Common config files
+  '.env',
+  '.eslintrc',
+  'tsconfig.json',
+  'babel.config.js',
+  'jest.config.js',
+  'webpack.config.js',
+  
+  // Common CI/CD files
+  '.github/workflows',
+  '.gitlab-ci.yml',
+  '.circleci/config.yml'
+];
+
+/**
+ * Gets the path to the task-master package installation directory
+ * NOTE: This might become unnecessary if CLI fallback in MCP utils is removed.
+ * @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 npm, we need to find the package root
+  const thisFilePath = fileURLToPath(import.meta.url);
+  const thisFileDir = path.dirname(thisFilePath);
+  
+  // 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 npm: /path/to/node_modules/task-master/mcp-server/src/core/utils -> /path/to/node_modules/task-master
+  return path.resolve(thisFileDir, '../../../../');
+}
+
+/**
+ * Finds the absolute path to the tasks.json file based on project root and arguments.
+ * @param {Object} args - Command arguments, potentially including 'projectRoot' and 'file'.
+ * @param {Object} log - Logger object.
+ * @returns {string} - Absolute path to the tasks.json file.
+ * @throws {Error} - If tasks.json cannot be found.
+ */
+export function findTasksJsonPath(args, log) {
+  // PRECEDENCE ORDER for finding tasks.json:
+  // 1. Explicitly provided `projectRoot` in args (Highest priority, expected in MCP context)
+  // 2. Previously found/cached `lastFoundProjectRoot` (primarily for CLI performance)
+  // 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
+  if (args.projectRoot) {
+    const projectRoot = args.projectRoot;
+    log.info(`Using explicitly provided project root: ${projectRoot}`);
+    try {
+      // This will throw if tasks.json isn't found within this root
+      return findTasksJsonInDirectory(projectRoot, args.file, log); 
+    } catch (error) {
+      // Include debug info in error
+      const debugInfo = {
+        projectRoot,
+        currentDir: process.cwd(),
+        serverDir: path.dirname(process.argv[1]),
+        possibleProjectRoot: path.resolve(path.dirname(process.argv[1]), '../..'),
+        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)}`;
+      throw error;
+    }
+  }
+  
+  // --- 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
+  if (lastFoundProjectRoot) {
+    log.info(`Trying last known project root: ${lastFoundProjectRoot}`);
+    try {
+      // Use the cached root
+      const tasksPath = findTasksJsonInDirectory(lastFoundProjectRoot, args.file, log); 
+      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)
+  const startDir = process.cwd();
+  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 {
+    // This will throw if not found in the CWD tree
+    return findTasksJsonWithParentSearch(startDir, args.file, log); 
+  } catch (error) {
+    // 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}`;
+    throw error;
+  }
+}
+
+/**
+ * Check if a directory contains any project marker files or directories
+ * @param {string} dirPath - Directory to check
+ * @returns {boolean} - True if the directory contains any project markers
+ */
+function hasProjectMarkers(dirPath) {
+  return PROJECT_MARKERS.some(marker => {
+    const markerPath = path.join(dirPath, marker);
+    // Check if the marker exists as either a file or directory
+    return fs.existsSync(markerPath);
+  });
+}
+
+/**
+ * Search for tasks.json in a specific directory
+ * @param {string} dirPath - Directory to search in
+ * @param {string} explicitFilePath - Optional explicit file path relative to dirPath
+ * @param {Object} log - Logger object
+ * @returns {string} - Absolute path to tasks.json
+ * @throws {Error} - If tasks.json cannot be found
+ */
+function findTasksJsonInDirectory(dirPath, explicitFilePath, log) {
+  const possiblePaths = [];
+
+  // 1. If a file is explicitly provided relative to dirPath
+  if (explicitFilePath) {
+    possiblePaths.push(path.resolve(dirPath, explicitFilePath));
+  }
+
+  // 2. Check the standard locations relative to dirPath
+  possiblePaths.push(
+    path.join(dirPath, 'tasks.json'),
+    path.join(dirPath, 'tasks', 'tasks.json')
+  );
+
+  log.info(`Checking potential task file paths: ${possiblePaths.join(', ')}`);
+
+  // Find the first existing path
+  for (const p of possiblePaths) {
+    log.info(`Checking if exists: ${p}`);
+    const exists = fs.existsSync(p);
+    log.info(`Path ${p} exists: ${exists}`);
+    
+    if (exists) {
+      log.info(`Found tasks file at: ${p}`);
+      // Store the project root for future use
+      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;
+}
+
+/**
+ * Recursively search for tasks.json in the given directory and parent directories
+ * Also looks for project markers to identify potential project roots
+ * @param {string} startDir - Directory to start searching from
+ * @param {string} explicitFilePath - Optional explicit file path
+ * @param {Object} log - Logger object
+ * @returns {string} - Absolute path to tasks.json
+ * @throws {Error} - If tasks.json cannot be found in any parent directory
+ */
+function findTasksJsonWithParentSearch(startDir, explicitFilePath, log) {
+  let currentDir = startDir;
+  const rootDir = path.parse(currentDir).root;
+  
+  // Keep traversing up until we hit the root directory
+  while (currentDir !== rootDir) {
+    // First check for tasks.json directly
+    try {
+      return findTasksJsonInDirectory(currentDir, explicitFilePath, log);
+    } catch (error) {
+      // If tasks.json not found but the directory has project markers,
+      // log it as a potential project root (helpful for debugging)
+      if (hasProjectMarkers(currentDir)) {
+        log.info(`Found project markers in ${currentDir}, but no tasks.json`);
+      }
+      
+      // Move up to parent directory
+      const parentDir = path.dirname(currentDir);
+      
+      // Check if we've reached the root
+      if (parentDir === currentDir) {
+        break;
+      }
+      
+      log.info(`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
+  const error = new Error(`Tasks file not found in ${startDir} or any parent directory.`);
+  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
+  try {
+    return findTasksJsonWithParentSearch(startDir, null, log);
+  } catch (error) {
+    // If that fails, try looking relative to the executable location
+    const execPath = process.argv[1];
+    const execDir = path.dirname(execPath);
+    log.info(`Looking for tasks file relative to executable at: ${execDir}`);
+    
+    try {
+      return findTasksJsonWithParentSearch(execDir, null, log);
+    } catch (secondError) {
+      // If that also fails, check standard locations in user's home directory
+      const homeDir = os.homedir();
+      log.info(`Looking for tasks file in home directory: ${homeDir}`);
+      
+      try {
+        // Check standard locations in home dir
+        return findTasksJsonInDirectory(path.join(homeDir, '.task-master'), null, log);
+      } catch (thirdError) {
+        // If all approaches fail, throw the original error
+        throw error;
+      }
+    }
+  }
+} 

mcp-server/src/index.js

@@ -5,6 +5,7 @@ import { fileURLToPath } from "url";
 import fs from "fs";
 import logger from "./logger.js";
 import { registerTaskMasterTools } from "./tools/index.js";
+import { asyncOperationManager } from './core/utils/async-manager.js';
 
 // Load environment variables
 dotenv.config();
@@ -30,9 +31,12 @@ class TaskMasterMCPServer {
     this.server = new FastMCP(this.options);
     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)
+    this.asyncManager = asyncOperationManager;
 
     // Bind methods
     this.init = this.init.bind(this);
@@ -49,8 +53,8 @@ class TaskMasterMCPServer {
   async init() {
     if (this.initialized) return;
 
-    // Register Task Master tools
-    registerTaskMasterTools(this.server);
+    // Pass the manager instance to the tool registration function
+    registerTaskMasterTools(this.server, this.asyncManager);
 
     this.initialized = true;
 
@@ -65,9 +69,10 @@ class TaskMasterMCPServer {
       await this.init();
     }
 
-    // Start the FastMCP server
+    // Start the FastMCP server with increased timeout
     await this.server.start({
       transportType: "stdio",
+      timeout: 120000 // 2 minutes timeout (in milliseconds)
     });
 
     return this;
@@ -83,4 +88,7 @@ class TaskMasterMCPServer {
   }
 }
 
+// Export the manager from here as well, if needed elsewhere
+export { asyncOperationManager };
+
 export default TaskMasterMCPServer;

mcp-server/src/logger.js

@@ -1,4 +1,5 @@
 import chalk from "chalk";
+import { isSilentMode } from "../../scripts/modules/utils.js";
 
 // Define log levels
 const LOG_LEVELS = {
@@ -11,7 +12,7 @@ const LOG_LEVELS = {
 
 // 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[process.env.LOG_LEVEL.toLowerCase()] ?? LOG_LEVELS.info
   : LOG_LEVELS.info;
 
 /**
@@ -20,43 +21,71 @@ const LOG_LEVEL = process.env.LOG_LEVEL
  * @param  {...any} args - Arguments to log
  */
 function log(level, ...args) {
-  const icons = {
-    debug: chalk.gray("🔍"),
-    info: chalk.blue("ℹ️"),
-    warn: chalk.yellow("⚠️"),
-    error: chalk.red("❌"),
-    success: chalk.green("✅"),
+  // Skip logging if silent mode is enabled
+  if (isSilentMode()) {
+    return;
+  }
+
+  // Use text prefixes instead of emojis
+  const prefixes = {
+    debug: chalk.gray("[DEBUG]"),
+    info: chalk.blue("[INFO]"),
+    warn: chalk.yellow("[WARN]"),
+    error: chalk.red("[ERROR]"),
+    success: chalk.green("[SUCCESS]"),
   };
 
-  if (LOG_LEVELS[level] >= LOG_LEVEL) {
-    const icon = icons[level] || "";
+  if (LOG_LEVELS[level] !== undefined && LOG_LEVELS[level] >= LOG_LEVEL) {
+    const prefix = prefixes[level] || "";
+    let coloredArgs = args;
 
-    if (level === "error") {
-      console.error(icon, chalk.red(...args));
-    } else if (level === "warn") {
-      console.warn(icon, chalk.yellow(...args));
-    } else if (level === "success") {
-      console.log(icon, chalk.green(...args));
-    } else if (level === "info") {
-      console.log(icon, chalk.blue(...args));
-    } else {
-      console.log(icon, ...args);
+    try {
+      switch(level) {
+        case "error":
+          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)
+    // 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);
   }
 }
 
 /**
  * Create a logger object with methods for different log levels
- * Can be used as a drop-in replacement for existing logger initialization
  * @returns {Object} Logger object with info, error, debug, warn, and success methods
  */
 export function createLogger() {
+  const createLogMethod = (level) => (...args) => log(level, ...args);
+
   return {
-    debug: (message) => log("debug", message),
-    info: (message) => log("info", message),
-    warn: (message) => log("warn", message),
-    error: (message) => log("error", message),
-    success: (message) => log("success", message),
+    debug: createLogMethod("debug"),
+    info: createLogMethod("info"),
+    warn: createLogMethod("warn"),
+    error: createLogMethod("error"),
+    success: createLogMethod("success"),
     log: log, // Also expose the raw log function
   };
 }

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

@@ -0,0 +1 @@
+ 

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

@@ -0,0 +1,65 @@
+/**
+ * tools/add-dependency.js
+ * Tool for adding a dependency to a task
+ */
+
+import { z } from "zod";
+import {
+  handleApiResult,
+  createErrorResponse,
+  getProjectRootFromSession
+} from "./utils.js";
+import { addDependencyDirect } from "../core/task-master-core.js";
+
+/**
+ * Register the addDependency tool with the MCP server
+ * @param {Object} server - FastMCP server instance
+ */
+export function registerAddDependencyTool(server) {
+  server.addTool({
+    name: "add_dependency",
+    description: "Add a dependency relationship between two tasks",
+    parameters: z.object({
+      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"),
+      file: z.string().optional().describe("Path to the tasks file (default: tasks/tasks.json)"),
+      projectRoot: z.string().optional().describe("Root directory of the project (default: current working directory)")
+    }),
+    execute: async (args, { log, session, reportProgress }) => {
+      try {
+        log.info(`Adding dependency for task ${args.id} to depend on ${args.dependsOn}`);
+        reportProgress({ progress: 0 });
+        
+        // Get project root using the utility function
+        let rootFolder = getProjectRootFromSession(session, log);
+        
+        // Fallback to args.projectRoot if session didn't provide one
+        if (!rootFolder && args.projectRoot) {
+          rootFolder = args.projectRoot;
+          log.info(`Using project root from args as fallback: ${rootFolder}`);
+        }
+        
+        // Call the direct function with the resolved rootFolder
+        const result = await addDependencyDirect({
+          projectRoot: rootFolder,
+          ...args
+        }, log, { reportProgress, mcpLog: log, session});
+
+        reportProgress({ progress: 100 });
+        
+        // Log result
+        if (result.success) {
+          log.info(`Successfully added dependency: ${result.data.message}`);
+        } else {
+          log.error(`Failed to add dependency: ${result.error.message}`);
+        }
+        
+        // Use handleApiResult to format the response
+        return handleApiResult(result, log, 'Error adding dependency');
+      } catch (error) {
+        log.error(`Error in addDependency tool: ${error.message}`);
+        return createErrorResponse(error.message);
+      }
+    },
+  });
+} 

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

@@ -0,0 +1,63 @@
+/**
+ * tools/add-subtask.js
+ * Tool for adding subtasks to existing tasks
+ */
+
+import { z } from "zod";
+import {
+  handleApiResult,
+  createErrorResponse,
+  getProjectRootFromSession
+} from "./utils.js";
+import { addSubtaskDirect } from "../core/task-master-core.js";
+
+/**
+ * Register the addSubtask tool with the MCP server
+ * @param {Object} server - FastMCP server instance
+ */
+export function registerAddSubtaskTool(server) {
+  server.addTool({
+    name: "add_subtask",
+    description: "Add a subtask to an existing task",
+    parameters: z.object({
+      id: z.string().describe("Parent task ID (required)"),
+      taskId: z.string().optional().describe("Existing task ID to convert to subtask"),
+      title: z.string().optional().describe("Title for the new subtask (when creating a new subtask)"),
+      description: z.string().optional().describe("Description for the new subtask"),
+      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("Path to the tasks file (default: tasks/tasks.json)"),
+      skipGenerate: z.boolean().optional().describe("Skip regenerating task files"),
+      projectRoot: z.string().optional().describe("Root directory of the project (default: current working directory)")
+    }),
+    execute: async (args, { log, session, reportProgress }) => {
+      try {
+        log.info(`Adding subtask with args: ${JSON.stringify(args)}`);
+        
+        let rootFolder = getProjectRootFromSession(session, log);
+        
+        if (!rootFolder && args.projectRoot) {
+          rootFolder = args.projectRoot;
+          log.info(`Using project root from args as fallback: ${rootFolder}`);
+        }
+        
+        const result = await addSubtaskDirect({
+          projectRoot: rootFolder,
+          ...args
+        }, log, { reportProgress, mcpLog: log, session});
+        
+        if (result.success) {
+          log.info(`Subtask added successfully: ${result.data.message}`);
+        } else {
+          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

@@ -0,0 +1,58 @@
+/**
+ * tools/add-task.js
+ * Tool to add a new task using AI
+ */
+
+import { z } from "zod";
+import {
+  createErrorResponse,
+  createContentResponse,
+  getProjectRootFromSession,
+  executeTaskMasterCommand,
+  handleApiResult
+} from "./utils.js";
+import { addTaskDirect } from "../core/task-master-core.js";
+
+/**
+ * Register the addTask tool with the MCP server
+ * @param {Object} server - FastMCP server instance
+ */
+export function registerAddTaskTool(server) {
+  server.addTool({
+    name: "add_task",
+    description: "Add a new task using AI",
+    parameters: z.object({
+      prompt: z.string().describe("Description of the task to add"),
+      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"),
+      projectRoot: z.string().optional().describe("Root directory of the project"),
+      research: z.boolean().optional().describe("Whether to use research capabilities for task creation")
+    }),
+    execute: async (args, { log, reportProgress, session }) => {
+      try {
+        log.info(`Starting add-task with args: ${JSON.stringify(args)}`);
+        
+        // Get project root from session
+        let rootFolder = getProjectRootFromSession(session, log);
+        
+        if (!rootFolder && args.projectRoot) {
+          rootFolder = args.projectRoot;
+          log.info(`Using project root from args as fallback: ${rootFolder}`);
+        }
+        
+        // Call the direct function
+        const result = await addTaskDirect({
+          ...args,
+          projectRoot: rootFolder
+        }, log, { reportProgress, session });
+        
+        // Return the result
+        return handleApiResult(result, log);
+      } catch (error) {
+        log.error(`Error in add-task tool: ${error.message}`);
+        return createErrorResponse(error.message);
+      }
+    }
+  });
+} 

mcp-server/src/tools/addTask.js

@@ -1,66 +0,0 @@
-/**
- * tools/addTask.js
- * Tool to add a new task using AI
- */
-
-import { z } from "zod";
-import {
-  executeTaskMasterCommand,
-  createContentResponse,
-  createErrorResponse,
-} from "./utils.js";
-
-/**
- * Register the addTask tool with the MCP server
- * @param {FastMCP} server - FastMCP server instance
- */
-export function registerAddTaskTool(server) {
-  server.addTool({
-    name: "addTask",
-    description: "Add a new task using AI",
-    parameters: z.object({
-      prompt: z.string().describe("Description of the task to add"),
-      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"),
-      projectRoot: z
-        .string()
-        .describe(
-          "Root directory of the project (default: current working directory)"
-        ),
-    }),
-    execute: async (args, { log }) => {
-      try {
-        log.info(`Adding new task: ${args.prompt}`);
-
-        const cmdArgs = [`--prompt="${args.prompt}"`];
-        if (args.dependencies)
-          cmdArgs.push(`--dependencies=${args.dependencies}`);
-        if (args.priority) cmdArgs.push(`--priority=${args.priority}`);
-        if (args.file) cmdArgs.push(`--file=${args.file}`);
-
-        const result = executeTaskMasterCommand(
-          "add-task",
-          log,
-          cmdArgs,
-          projectRoot
-        );
-
-        if (!result.success) {
-          throw new Error(result.error);
-        }
-
-        return createContentResponse(result.stdout);
-      } catch (error) {
-        log.error(`Error adding task: ${error.message}`);
-        return createErrorResponse(`Error adding task: ${error.message}`);
-      }
-    },
-  });
-}

mcp-server/src/tools/analyze.js

@@ -0,0 +1,60 @@
+/**
+ * tools/analyze.js
+ * Tool for analyzing task complexity and generating recommendations
+ */
+
+import { z } from "zod";
+import {
+  handleApiResult,
+  createErrorResponse,
+  getProjectRootFromSession
+} from "./utils.js";
+import { analyzeTaskComplexityDirect } from "../core/task-master-core.js";
+
+/**
+ * Register the analyze tool with the MCP server
+ * @param {Object} server - FastMCP server instance
+ */
+export function registerAnalyzeTool(server) {
+  server.addTool({
+    name: "analyze_project_complexity",
+    description: "Analyze task complexity and generate expansion recommendations",
+    parameters: z.object({
+      output: z.string().optional().describe("Output file path for the report (default: scripts/task-complexity-report.json)"),
+      model: z.string().optional().describe("LLM model to use for analysis (defaults to configured model)"),
+      threshold: z.union([z.number(), z.string()]).optional().describe("Minimum complexity score to recommend expansion (1-10) (default: 5)"),
+      file: z.string().optional().describe("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().optional().describe("Root directory of the project (default: current working directory)")
+    }),
+    execute: async (args, { log, session }) => {
+      try {
+        log.info(`Analyzing task complexity with args: ${JSON.stringify(args)}`);
+        
+        let rootFolder = getProjectRootFromSession(session, log);
+        
+        if (!rootFolder && args.projectRoot) {
+          rootFolder = args.projectRoot;
+          log.info(`Using project root from args as fallback: ${rootFolder}`);
+        }
+        
+        const result = await analyzeTaskComplexityDirect({
+          projectRoot: rootFolder,
+          ...args
+        }, log, { session });
+        
+        if (result.success) {
+          log.info(`Task complexity analysis complete: ${result.data.message}`);
+          log.info(`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

@@ -0,0 +1,63 @@
+/**
+ * tools/clear-subtasks.js
+ * Tool for clearing subtasks from parent tasks
+ */
+
+import { z } from "zod";
+import {
+  handleApiResult,
+  createErrorResponse,
+  getProjectRootFromSession
+} from "./utils.js";
+import { clearSubtasksDirect } from "../core/task-master-core.js";
+
+/**
+ * Register the clearSubtasks tool with the MCP server
+ * @param {Object} server - FastMCP server instance
+ */
+export function registerClearSubtasksTool(server) {
+  server.addTool({
+    name: "clear_subtasks",
+    description: "Clear subtasks from specified tasks",
+    parameters: z.object({
+      id: z.string().optional().describe("Task IDs (comma-separated) to clear subtasks from"),
+      all: z.boolean().optional().describe("Clear subtasks from all tasks"),
+      file: z.string().optional().describe("Path to the tasks file (default: tasks/tasks.json)"),
+      projectRoot: z.string().optional().describe("Root directory of the project (default: current working directory)")
+    }).refine(data => data.id || data.all, {
+      message: "Either 'id' or 'all' parameter must be provided",
+      path: ["id", "all"]
+    }),
+    execute: async (args, { log, session, reportProgress }) => {
+      try {
+        log.info(`Clearing subtasks with args: ${JSON.stringify(args)}`);
+        await reportProgress({ progress: 0 });
+        
+        let rootFolder = getProjectRootFromSession(session, log);
+        
+        if (!rootFolder && args.projectRoot) {
+          rootFolder = args.projectRoot;
+          log.info(`Using project root from args as fallback: ${rootFolder}`);
+        }
+        
+        const result = await clearSubtasksDirect({
+          projectRoot: rootFolder,
+          ...args
+        }, log, { reportProgress, mcpLog: log, session});
+        
+        reportProgress({ progress: 100 });
+        
+        if (result.success) {
+          log.info(`Subtasks cleared successfully: ${result.data.message}`);
+        } else {
+          log.error(`Failed to clear subtasks: ${result.error.message}`);
+        }
+        
+        return handleApiResult(result, log, 'Error clearing subtasks');
+      } catch (error) {
+        log.error(`Error in clearSubtasks tool: ${error.message}`);
+        return createErrorResponse(error.message);
+      }
+    },
+  });
+} 

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

@@ -0,0 +1,58 @@
+/**
+ * tools/complexity-report.js
+ * Tool for displaying the complexity analysis report
+ */
+
+import { z } from "zod";
+import {
+  handleApiResult,
+  createErrorResponse,
+  getProjectRootFromSession
+} from "./utils.js";
+import { complexityReportDirect } from "../core/task-master-core.js";
+
+/**
+ * Register the complexityReport tool with the MCP server
+ * @param {Object} server - FastMCP server instance
+ */
+export function registerComplexityReportTool(server) {
+  server.addTool({
+    name: "complexity_report",
+    description: "Display the complexity analysis report in a readable format",
+    parameters: z.object({
+      file: z.string().optional().describe("Path to the report file (default: scripts/task-complexity-report.json)"),
+      projectRoot: z.string().optional().describe("Root directory of the project (default: current working directory)")
+    }),
+    execute: async (args, { log, session, reportProgress }) => {
+      try {
+        log.info(`Getting complexity report with args: ${JSON.stringify(args)}`);
+        // await reportProgress({ progress: 0 });
+        
+        let rootFolder = getProjectRootFromSession(session, log);
+        
+        if (!rootFolder && args.projectRoot) {
+          rootFolder = args.projectRoot;
+          log.info(`Using project root from args as fallback: ${rootFolder}`);
+        }
+        
+        const result = await complexityReportDirect({
+          projectRoot: rootFolder,
+          ...args
+        }, log/*, { reportProgress, mcpLog: log, session}*/);
+        
+        // await reportProgress({ progress: 100 });
+        
+        if (result.success) {
+          log.info(`Successfully retrieved complexity report${result.fromCache ? ' (from cache)' : ''}`);
+        } else {
+          log.error(`Failed to retrieve complexity report: ${result.error.message}`);
+        }
+        
+        return handleApiResult(result, log, '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

@@ -0,0 +1,59 @@
+/**
+ * tools/expand-all.js
+ * Tool for expanding all pending tasks with subtasks
+ */
+
+import { z } from "zod";
+import {
+  handleApiResult,
+  createErrorResponse,
+  getProjectRootFromSession
+} from "./utils.js";
+import { expandAllTasksDirect } from "../core/task-master-core.js";
+
+/**
+ * Register the expandAll tool with the MCP server
+ * @param {Object} server - FastMCP server instance
+ */
+export function registerExpandAllTool(server) {
+  server.addTool({
+    name: "expand_all",
+    description: "Expand all pending tasks into subtasks",
+    parameters: z.object({
+      num: z.string().optional().describe("Number of subtasks to generate for each task"),
+      research: z.boolean().optional().describe("Enable Perplexity AI for research-backed subtask generation"),
+      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("Path to the tasks file (default: tasks/tasks.json)"),
+      projectRoot: z.string().optional().describe("Root directory of the project (default: current working directory)")
+    }),
+    execute: async (args, { log, session }) => {
+      try {
+        log.info(`Expanding all tasks with args: ${JSON.stringify(args)}`);
+        
+        let rootFolder = getProjectRootFromSession(session, log);
+        
+        if (!rootFolder && args.projectRoot) {
+          rootFolder = args.projectRoot;
+          log.info(`Using project root from args as fallback: ${rootFolder}`);
+        }
+        
+        const result = await expandAllTasksDirect({
+          projectRoot: rootFolder,
+          ...args
+        }, log, { session });
+        
+        if (result.success) {
+          log.info(`Successfully expanded all tasks: ${result.data.message}`);
+        } else {
+          log.error(`Failed to expand all tasks: ${result.error?.message || 'Unknown error'}`);
+        }
+        
+        return handleApiResult(result, log, 'Error expanding all tasks');
+      } catch (error) {
+        log.error(`Error in expand-all tool: ${error.message}`);
+        return createErrorResponse(error.message);
+      }
+    },
+  });
+} 

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

@@ -0,0 +1,77 @@
+/**
+ * tools/expand-task.js
+ * Tool to expand a task into subtasks
+ */
+
+import { z } from "zod";
+import {
+  handleApiResult,
+  createErrorResponse,
+  getProjectRootFromSession
+} from "./utils.js";
+import { expandTaskDirect } from "../core/task-master-core.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({
+    name: "expand_task",
+    description: "Expand a task into subtasks for detailed implementation",
+    parameters: z.object({
+      id: z.string().describe("ID of task to expand"),
+      num: z.union([z.string(), z.number()]).optional().describe("Number of subtasks to generate"),
+      research: z.boolean().optional().describe("Use Perplexity AI for research-backed generation"),
+      prompt: z.string().optional().describe("Additional context for subtask generation"),
+      file: z.string().optional().describe("Path to the tasks file"),
+      projectRoot: z
+        .string()
+        .optional()
+        .describe(
+          "Root directory of the project (default: current working directory)"
+        ),
+    }),
+    execute: async (args, { log, reportProgress, session }) => {
+      try {
+        log.info(`Starting expand-task with args: ${JSON.stringify(args)}`);
+        
+        // Get project root from session
+        let rootFolder = getProjectRootFromSession(session, log);
+        
+        if (!rootFolder && args.projectRoot) {
+          rootFolder = args.projectRoot;
+          log.info(`Using project root from args as fallback: ${rootFolder}`);
+        }
+        
+        log.info(`Project root resolved to: ${rootFolder}`);
+        
+        // Check for tasks.json in the standard locations
+        const tasksJsonPath = path.join(rootFolder, 'tasks', 'tasks.json');
+        
+        if (fs.existsSync(tasksJsonPath)) {
+          log.info(`Found tasks.json at ${tasksJsonPath}`);
+          // Add the file parameter directly to args
+          args.file = tasksJsonPath;
+        } else {
+          log.warn(`Could not find tasks.json at ${tasksJsonPath}`);
+        }
+        
+        // Call direct function with only session in the context, not reportProgress
+        // Use the pattern recommended in the MCP guidelines
+        const result = await expandTaskDirect({
+          ...args,
+          projectRoot: rootFolder
+        }, log, { session }); // Only pass session, NOT reportProgress
+        
+        // Return the result
+        return handleApiResult(result, log, 'Error expanding task');
+      } catch (error) {
+        log.error(`Error in expand task tool: ${error.message}`);
+        return createErrorResponse(error.message);
+      }
+    },
+  });
+} 

mcp-server/src/tools/expandTask.js

@@ -1,78 +0,0 @@
-/**
- * tools/expandTask.js
- * Tool to break down a task into detailed subtasks
- */
-
-import { z } from "zod";
-import {
-  executeTaskMasterCommand,
-  createContentResponse,
-  createErrorResponse,
-} from "./utils.js";
-
-/**
- * Register the expandTask tool with the MCP server
- * @param {Object} server - FastMCP server instance
- */
-export function registerExpandTaskTool(server) {
-  server.addTool({
-    name: "expandTask",
-    description: "Break down a task into detailed subtasks",
-    parameters: z.object({
-      id: z.string().describe("Task ID to expand"),
-      num: z.number().optional().describe("Number of subtasks to generate"),
-      research: z
-        .boolean()
-        .optional()
-        .describe(
-          "Enable Perplexity AI for research-backed subtask generation"
-        ),
-      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("Path to the tasks file"),
-      projectRoot: z
-        .string()
-        .describe(
-          "Root directory of the project (default: current working directory)"
-        ),
-    }),
-    execute: async (args, { log }) => {
-      try {
-        log.info(`Expanding task ${args.id}`);
-
-        const cmdArgs = [`--id=${args.id}`];
-        if (args.num) cmdArgs.push(`--num=${args.num}`);
-        if (args.research) cmdArgs.push("--research");
-        if (args.prompt) cmdArgs.push(`--prompt="${args.prompt}"`);
-        if (args.force) cmdArgs.push("--force");
-        if (args.file) cmdArgs.push(`--file=${args.file}`);
-
-        const projectRoot = args.projectRoot;
-
-        const result = executeTaskMasterCommand(
-          "expand",
-          log,
-          cmdArgs,
-          projectRoot
-        );
-
-        if (!result.success) {
-          throw new Error(result.error);
-        }
-
-        return createContentResponse(result.stdout);
-      } catch (error) {
-        log.error(`Error expanding task: ${error.message}`);
-        return createErrorResponse(`Error expanding task: ${error.message}`);
-      }
-    },
-  });
-}

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

@@ -0,0 +1,58 @@
+/**
+ * tools/fix-dependencies.js
+ * Tool for automatically fixing invalid task dependencies
+ */
+
+import { z } from "zod";
+import {
+  handleApiResult,
+  createErrorResponse,
+  getProjectRootFromSession
+} from "./utils.js";
+import { fixDependenciesDirect } from "../core/task-master-core.js";
+
+/**
+ * Register the fixDependencies tool with the MCP server
+ * @param {Object} server - FastMCP server instance
+ */
+export function registerFixDependenciesTool(server) {
+  server.addTool({
+    name: "fix_dependencies",
+    description: "Fix invalid dependencies in tasks automatically",
+    parameters: z.object({
+      file: z.string().optional().describe("Path to the tasks file"),
+      projectRoot: z.string().optional().describe("Root directory of the project (default: current working directory)")
+    }),
+    execute: async (args, { log, session, reportProgress }) => {
+      try {
+        log.info(`Fixing dependencies with args: ${JSON.stringify(args)}`);
+        await reportProgress({ progress: 0 });
+        
+        let rootFolder = getProjectRootFromSession(session, log);
+        
+        if (!rootFolder && args.projectRoot) {
+          rootFolder = args.projectRoot;
+          log.info(`Using project root from args as fallback: ${rootFolder}`);
+        }
+        
+        const result = await fixDependenciesDirect({
+          projectRoot: rootFolder,
+          ...args
+        }, log, { reportProgress, mcpLog: log, session});
+        
+        await reportProgress({ progress: 100 });
+        
+        if (result.success) {
+          log.info(`Successfully fixed dependencies: ${result.data.message}`);
+        } else {
+          log.error(`Failed to fix dependencies: ${result.error.message}`);
+        }
+        
+        return handleApiResult(result, log, 'Error fixing dependencies');
+      } catch (error) {
+        log.error(`Error in fixDependencies tool: ${error.message}`);
+        return createErrorResponse(error.message);
+      }
+    }
+  });
+} 

mcp-server/src/tools/generate.js

@@ -0,0 +1,64 @@
+/**
+ * tools/generate.js
+ * Tool to generate individual task files from tasks.json
+ */
+
+import { z } from "zod";
+import {
+  handleApiResult,
+  createErrorResponse,
+  getProjectRootFromSession
+} from "./utils.js";
+import { generateTaskFilesDirect } from "../core/task-master-core.js";
+
+/**
+ * Register the generate tool with the MCP server
+ * @param {Object} server - FastMCP server instance
+ */
+export function registerGenerateTool(server) {
+  server.addTool({
+    name: "generate",
+    description: "Generates individual task files in tasks/ directory based on tasks.json",
+    parameters: z.object({
+      file: z.string().optional().describe("Path to the tasks file"),
+      output: z.string().optional().describe("Output directory (default: same directory as tasks file)"),
+      projectRoot: z
+        .string()
+        .optional()
+        .describe(
+          "Root directory of the project (default: current working directory)"
+        ),
+    }),
+    execute: async (args, { log, session, reportProgress }) => {
+      try {
+        log.info(`Generating task files with args: ${JSON.stringify(args)}`);
+        // await reportProgress({ progress: 0 });
+        
+        let rootFolder = getProjectRootFromSession(session, log);
+        
+        if (!rootFolder && args.projectRoot) {
+          rootFolder = args.projectRoot;
+          log.info(`Using project root from args as fallback: ${rootFolder}`);
+        }
+        
+        const result = await generateTaskFilesDirect({
+          projectRoot: rootFolder,
+          ...args
+        }, log/*, { reportProgress, mcpLog: log, session}*/);
+        
+        // await reportProgress({ progress: 100 });
+        
+        if (result.success) {
+          log.info(`Successfully generated task files: ${result.data.message}`);
+        } else {
+          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

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

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

@@ -0,0 +1,92 @@
+/**
+ * tools/get-task.js
+ * Tool to get task details by ID
+ */
+
+import { z } from "zod";
+import {
+  handleApiResult,
+  createErrorResponse,
+  getProjectRootFromSession
+} from "./utils.js";
+import { showTaskDirect } from "../core/task-master-core.js";
+
+/**
+ * Custom processor function that removes allTasks from the response
+ * @param {Object} data - The data returned from showTaskDirect
+ * @returns {Object} - The processed data with allTasks removed
+ */
+function processTaskResponse(data) {
+  if (!data) return data;
+  
+  // If we have the expected structure with task and allTasks
+  if (data.task) {
+    // Return only the task object, removing the allTasks array
+    return data.task;
+  }
+  
+  // If structure is unexpected, return as is
+  return data;
+}
+
+/**
+ * Register the get-task tool with the MCP server
+ * @param {Object} server - FastMCP server instance
+ */
+export function registerShowTaskTool(server) {
+  server.addTool({
+    name: "get_task",
+    description: "Get detailed information about a specific task",
+    parameters: z.object({
+      id: z.string().describe("Task ID to get"),
+      file: z.string().optional().describe("Path to the tasks file"),
+      projectRoot: z
+        .string()
+        .optional()
+        .describe(
+          "Root directory of the project (default: current working directory)"
+        ),
+    }),
+    execute: async (args, { log, session, reportProgress }) => {
+      // Log the session right at the start of execute
+      log.info(`Session object received in execute: ${JSON.stringify(session)}`); // Use JSON.stringify for better visibility
+
+      try {
+        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
+        
+        let rootFolder = getProjectRootFromSession(session, log);
+        
+        if (!rootFolder && args.projectRoot) {
+          rootFolder = args.projectRoot;
+          log.info(`Using project root from args as fallback: ${rootFolder}`);
+        } else if (!rootFolder) {
+          // 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(`Root folder: ${rootFolder}`); // Log the final resolved root
+        const result = await showTaskDirect({
+          projectRoot: rootFolder,
+          ...args
+        }, 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

@@ -0,0 +1,65 @@
+/**
+ * tools/get-tasks.js
+ * Tool to get all tasks from Task Master
+ */
+
+import { z } from "zod";
+import {
+  createErrorResponse,
+  handleApiResult,
+  getProjectRootFromSession
+} from "./utils.js";
+import { listTasksDirect } from "../core/task-master-core.js";
+
+/**
+ * Register the getTasks tool with the MCP server
+ * @param {Object} server - FastMCP server instance
+ */
+export function registerListTasksTool(server) {
+  server.addTool({
+    name: "get_tasks",
+    description: "Get all tasks from Task Master, optionally filtering by status and including subtasks.",
+    parameters: z.object({
+      status: z.string().optional().describe("Filter tasks by status (e.g., 'pending', 'done')"),
+      withSubtasks: z
+        .boolean()
+        .optional()
+        .describe("Include subtasks nested within their parent tasks in the response"),
+      file: z.string().optional().describe("Path to the tasks file (relative to project root or absolute)"),
+      projectRoot: z
+        .string()
+        .optional()
+        .describe(
+          "Root directory of the project (default: automatically detected from session or CWD)"
+        ),
+    }),
+    execute: async (args, { log, session, reportProgress }) => {
+      try {
+        log.info(`Getting tasks with filters: ${JSON.stringify(args)}`);
+        // await reportProgress({ progress: 0 });
+        
+        let rootFolder = getProjectRootFromSession(session, log);
+        
+        if (!rootFolder && args.projectRoot) {
+          rootFolder = args.projectRoot;
+          log.info(`Using project root from args as fallback: ${rootFolder}`);
+        }
+        
+        const result = await listTasksDirect({
+          projectRoot: rootFolder,
+          ...args
+        }, log/*, { reportProgress, mcpLog: log, session}*/);
+        
+        // await reportProgress({ progress: 100 });
+        
+        log.info(`Retrieved ${result.success ? (result.data?.tasks?.length || 0) : 0} tasks${result.fromCache ? ' (from cache)' : ''}`);
+        return handleApiResult(result, log, 'Error getting tasks');
+      } 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,25 +3,69 @@
  * Export all Task Master CLI tools for MCP server
  */
 
+import { registerListTasksTool } from "./get-tasks.js";
 import logger from "../logger.js";
-import { registerListTasksTool } from "./listTasks.js";
-import { registerShowTaskTool } from "./showTask.js";
-import { registerSetTaskStatusTool } from "./setTaskStatus.js";
-import { registerExpandTaskTool } from "./expandTask.js";
-import { registerNextTaskTool } from "./nextTask.js";
-import { registerAddTaskTool } from "./addTask.js";
+import { registerSetTaskStatusTool } from "./set-task-status.js";
+import { registerParsePRDTool } from "./parse-prd.js";
+import { registerUpdateTool } from "./update.js";
+import { registerUpdateTaskTool } from "./update-task.js";
+import { registerUpdateSubtaskTool } from "./update-subtask.js";
+import { registerGenerateTool } from "./generate.js";
+import { registerShowTaskTool } from "./get-task.js";
+import { registerNextTaskTool } from "./next-task.js";
+import { registerExpandTaskTool } from "./expand-task.js";
+import { registerAddTaskTool } from "./add-task.js";
+import { registerAddSubtaskTool } from "./add-subtask.js";
+import { registerRemoveSubtaskTool } from "./remove-subtask.js";
+import { registerAnalyzeTool } from "./analyze.js";
+import { registerClearSubtasksTool } from "./clear-subtasks.js";
+import { registerExpandAllTool } from "./expand-all.js";
+import { registerRemoveDependencyTool } from "./remove-dependency.js";
+import { registerValidateDependenciesTool } from "./validate-dependencies.js";
+import { registerFixDependenciesTool } from "./fix-dependencies.js";
+import { registerComplexityReportTool } from "./complexity-report.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';
 
 /**
  * Register all Task Master tools with the MCP server
  * @param {Object} server - FastMCP server instance
+ * @param {asyncOperationManager} asyncManager - The async operation manager instance
  */
-export function registerTaskMasterTools(server) {
+export function registerTaskMasterTools(server, asyncManager) {  
+  try {
+    // Register each tool
     registerListTasksTool(server);
-  registerShowTaskTool(server);
     registerSetTaskStatusTool(server);
-  registerExpandTaskTool(server);
+    registerParsePRDTool(server);
+    registerUpdateTool(server);
+    registerUpdateTaskTool(server);
+    registerUpdateSubtaskTool(server);
+    registerGenerateTool(server);
+    registerShowTaskTool(server);
     registerNextTaskTool(server);
-  registerAddTaskTool(server);
+    registerExpandTaskTool(server);
+    registerAddTaskTool(server, asyncManager);
+    registerAddSubtaskTool(server);
+    registerRemoveSubtaskTool(server);
+    registerAnalyzeTool(server);
+    registerClearSubtasksTool(server);
+    registerExpandAllTool(server);
+    registerRemoveDependencyTool(server);
+    registerValidateDependenciesTool(server);
+    registerFixDependenciesTool(server);
+    registerComplexityReportTool(server);
+    registerAddDependencyTool(server);
+    registerRemoveTaskTool(server);
+    registerInitializeProjectTool(server);
+  } catch (error) {
+    logger.error(`Error registering Task Master tools: ${error.message}`);
+    throw error;
+  }
+
+  logger.info('Registered Task Master MCP tools');
 }
 
 export default {

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

@@ -0,0 +1,62 @@
+import { z } from "zod";
+import { execSync } from 'child_process';
+import { createContentResponse, createErrorResponse } from "./utils.js"; // Only need response creators
+
+export function registerInitializeProjectTool(server) {
+  server.addTool({
+    name: "initialize_project", // snake_case for tool name
+    description: "Initializes a new Task Master project structure in the current working directory by running 'task-master init'.",
+    parameters: z.object({
+      projectName: z.string().optional().describe("The name for the new project."),
+      projectDescription: z.string().optional().describe("A brief description for the project."),
+      projectVersion: z.string().optional().describe("The initial version for the project (e.g., '0.1.0')."),
+      authorName: z.string().optional().describe("The author's name."),
+      skipInstall: z.boolean().optional().default(false).describe("Skip installing dependencies automatically."),
+      addAliases: z.boolean().optional().default(false).describe("Add shell aliases (tm, taskmaster) to shell config file."),
+      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
+    }),
+    execute: async (args, { log }) => { // Destructure context to get log
+      try {
+        log.info(`Executing initialize_project with args: ${JSON.stringify(args)}`);
+
+        // Construct the command arguments carefully
+        // Using npx ensures it uses the locally installed version if available, or fetches it
+        let command = 'npx task-master init';
+        const cliArgs = [];
+        if (args.projectName) cliArgs.push(`--name "${args.projectName.replace(/"/g, '\\"')}"`); // Escape quotes
+        if (args.projectDescription) cliArgs.push(`--description "${args.projectDescription.replace(/"/g, '\\"')}"`);
+        if (args.projectVersion) cliArgs.push(`--version "${args.projectVersion.replace(/"/g, '\\"')}"`);
+        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(' ');
+
+        log.info(`Constructed command: ${command}`);
+
+        // Execute the command in the current working directory of the server process
+        // Capture stdout/stderr. Use a reasonable timeout (e.g., 5 minutes)
+        const output = execSync(command, { encoding: 'utf8', stdio: 'pipe', timeout: 300000 });
+
+        log.info(`Initialization output:\n${output}`);
+
+        // 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/listTasks.js

@@ -1,65 +0,0 @@
-/**
- * tools/listTasks.js
- * Tool to list all tasks from Task Master
- */
-
-import { z } from "zod";
-import {
-  executeTaskMasterCommand,
-  createContentResponse,
-  createErrorResponse,
-} from "./utils.js";
-
-/**
- * Register the listTasks tool with the MCP server
- * @param {Object} server - FastMCP server instance
- */
-export function registerListTasksTool(server) {
-  server.addTool({
-    name: "listTasks",
-    description: "List all tasks from Task Master",
-    parameters: z.object({
-      status: z.string().optional().describe("Filter tasks by status"),
-      withSubtasks: z
-        .boolean()
-        .optional()
-        .describe("Include subtasks in the response"),
-      file: z.string().optional().describe("Path to the tasks file"),
-      projectRoot: z
-        .string()
-        .describe(
-          "Root directory of the project (default: current working directory)"
-        ),
-    }),
-    execute: async (args, { log }) => {
-      try {
-        log.info(`Listing tasks with filters: ${JSON.stringify(args)}`);
-
-        const cmdArgs = [];
-        if (args.status) cmdArgs.push(`--status=${args.status}`);
-        if (args.withSubtasks) cmdArgs.push("--with-subtasks");
-        if (args.file) cmdArgs.push(`--file=${args.file}`);
-
-        const projectRoot = args.projectRoot;
-
-        const result = executeTaskMasterCommand(
-          "list",
-          log,
-          cmdArgs,
-          projectRoot
-        );
-
-        if (!result.success) {
-          throw new Error(result.error);
-        }
-
-        log.info(`Listing tasks result: ${result.stdout}`, result.stdout);
-
-        return createContentResponse(result.stdout);
-      } catch (error) {
-        log.error(`Error listing tasks: ${error.message}`);
-        return createErrorResponse(`Error listing tasks: ${error.message}`);
-      }
-    },
-  });
-}

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

@@ -0,0 +1,63 @@
+/**
+ * tools/next-task.js
+ * Tool to find the next task to work on
+ */
+
+import { z } from "zod";
+import {
+  handleApiResult,
+  createErrorResponse,
+  getProjectRootFromSession
+} from "./utils.js";
+import { nextTaskDirect } from "../core/task-master-core.js";
+
+/**
+ * Register the next-task tool with the MCP server
+ * @param {Object} server - FastMCP server instance
+ */
+export function registerNextTaskTool(server) {
+  server.addTool({
+    name: "next_task",
+    description: "Find the next task to work on based on dependencies and status",
+    parameters: z.object({
+      file: z.string().optional().describe("Path to the tasks file"),
+      projectRoot: z
+        .string()
+        .optional()
+        .describe(
+          "Root directory of the project (default: current working directory)"
+        ),
+    }),
+    execute: async (args, { log, session, reportProgress }) => {
+      try {
+        log.info(`Finding next task with args: ${JSON.stringify(args)}`);
+        // await reportProgress({ progress: 0 });
+        
+        let rootFolder = getProjectRootFromSession(session, log);
+        
+        if (!rootFolder && args.projectRoot) {
+          rootFolder = args.projectRoot;
+          log.info(`Using project root from args as fallback: ${rootFolder}`);
+        }
+        
+        const result = await nextTaskDirect({
+          projectRoot: rootFolder,
+          ...args
+        }, log/*, { reportProgress, mcpLog: log, session}*/);
+        
+        // await reportProgress({ progress: 100 });
+        
+        if (result.success) {
+          log.info(`Successfully found next task: ${result.data?.task?.id || 'No available tasks'}`);
+        } else {
+          log.error(`Failed to find next task: ${result.error?.message || 'Unknown error'}`);
+        }
+        
+        return handleApiResult(result, log, 'Error finding next task');
+      } catch (error) {
+        log.error(`Error in nextTask tool: ${error.message}`);
+        return createErrorResponse(error.message);
+      }
+    },
+  });
+} 

mcp-server/src/tools/nextTask.js

@@ -1,57 +0,0 @@
-/**
- * tools/nextTask.js
- * Tool to show the next task to work on based on dependencies and status
- */
-
-import { z } from "zod";
-import {
-  executeTaskMasterCommand,
-  createContentResponse,
-  createErrorResponse,
-} from "./utils.js";
-
-/**
- * Register the nextTask tool with the MCP server
- * @param {Object} server - FastMCP server instance
- */
-export function registerNextTaskTool(server) {
-  server.addTool({
-    name: "nextTask",
-    description:
-      "Show the next task to work on based on dependencies and status",
-    parameters: z.object({
-      file: z.string().optional().describe("Path to the tasks file"),
-      projectRoot: z
-        .string()
-        .describe(
-          "Root directory of the project (default: current working directory)"
-        ),
-    }),
-    execute: async (args, { log }) => {
-      try {
-        log.info(`Finding next task to work on`);
-
-        const cmdArgs = [];
-        if (args.file) cmdArgs.push(`--file=${args.file}`);
-
-        const projectRoot = args.projectRoot;
-
-        const result = executeTaskMasterCommand(
-          "next",
-          log,
-          cmdArgs,
-          projectRoot
-        );
-
-        if (!result.success) {
-          throw new Error(result.error);
-        }
-
-        return createContentResponse(result.stdout);
-      } catch (error) {
-        log.error(`Error finding next task: ${error.message}`);
-        return createErrorResponse(`Error finding next task: ${error.message}`);
-      }
-    },
-  });
-}

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

@@ -0,0 +1,63 @@
+/**
+ * tools/parsePRD.js
+ * Tool to parse PRD document and generate tasks
+ */
+
+import { z } from "zod";
+import {
+  handleApiResult,
+  createErrorResponse,
+  getProjectRootFromSession
+} from "./utils.js";
+import { parsePRDDirect } from "../core/task-master-core.js";
+
+/**
+ * Register the parsePRD tool with the MCP server
+ * @param {Object} server - FastMCP server instance
+ */
+export function registerParsePRDTool(server) {
+  server.addTool({
+    name: "parse_prd",
+    description: "Parse a Product Requirements Document (PRD) or text file to automatically generate initial tasks.",
+    parameters: z.object({
+      input: z.string().default("tasks/tasks.json").describe("Path to the PRD document file (relative to project root or absolute)"),
+      numTasks: z.string().optional().describe("Approximate number of top-level tasks to generate (default: 10)"),
+      output: z.string().optional().describe("Output path for tasks.json file (relative to project root or absolute, default: tasks/tasks.json)"),
+      force: z.boolean().optional().describe("Allow overwriting an existing tasks.json file."),
+      projectRoot: z
+        .string()
+        .optional()
+        .describe(
+          "Root directory of the project (default: automatically detected from session or CWD)"
+        ),
+    }),
+    execute: async (args, { log, session }) => {
+      try {
+        log.info(`Parsing PRD with args: ${JSON.stringify(args)}`);
+        
+        let rootFolder = getProjectRootFromSession(session, log);
+        
+        if (!rootFolder && args.projectRoot) {
+          rootFolder = args.projectRoot;
+          log.info(`Using project root from args as fallback: ${rootFolder}`);
+        }
+        
+        const result = await parsePRDDirect({
+          projectRoot: rootFolder,
+          ...args
+        }, log, { session });
+        
+        if (result.success) {
+          log.info(`Successfully parsed PRD: ${result.data.message}`);
+        } else {
+          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);
+      }
+    },
+  });
+}