feat(mcp): major MCP server improvements and documentation overhaul

- Enhance MCP server robustness and usability:
  - Implement smart project root detection with hierarchical fallbacks
  - Make projectRoot parameter optional across all MCP tools
  - Add comprehensive PROJECT_MARKERS for reliable project detection
  - Improve error messages and logging for better debugging
  - Split monolithic core into focused direct-function files

- Implement full suite of MCP commands:
  - Add task management: update-task, update-subtask, generate
  - Add task organization: expand-task, expand-all, clear-subtasks
  - Add dependency handling: add/remove/validate/fix dependencies
  - Add analysis tools: analyze-complexity, complexity-report
  - Rename commands for better API consistency (list-tasks → get-tasks)

- Enhance documentation and developer experience:
  - Create and bundle new taskmaster.mdc as comprehensive reference
  - Document all tools with natural language patterns and examples
  - Clarify project root auto-detection in documentation
  - Standardize naming conventions across MCP components
  - Add cross-references between related tools and commands

- Improve UI and progress tracking:
  - Add color-coded progress bars with status breakdown
  - Implement cancelled/deferred task status handling
  - Enhance status visualization and counting
  - Optimize display for various terminal sizes

This major update significantly improves the robustness and usability
of the MCP server while providing comprehensive documentation for both
users and developers. The changes make Task Master more intuitive to
use programmatically while maintaining full CLI functionality.

.cursor/rules/architecture.mdc

@@ -85,7 +85,7 @@ 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.
+    - **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.
@@ -106,22 +106,23 @@ alwaysApply: false
     - **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.
-      - Direct function wrappers (`*Direct` functions) contain the main logic, including path resolution and optional caching.
+      - Tool `execute` methods call corresponding **direct function wrappers**.
+      - **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.
       - 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 Caching**: Utilizes a caching layer (`ContextManager` with `lru-cache`). Caching logic is invoked *within* the direct function wrappers (located in [`mcp-server/src/core/direct-functions/`](mdc:mcp-server/src/core/direct-functions/)) using the `getCachedOrExecute` utility for performance-sensitive read operations (e.g., `listTasks`).
+      - **Implements Robust Path Finding**: The utility [`core/utils/path-utils.js`](mdc:mcp-server/src/core/utils/path-utils.js) (specifically `findTasksJsonPath`) is used **within direct functions** to automatically locate the project root and `tasks.json` file, removing the need for mandatory `projectRoot` parameters in MCP calls.
+      - **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 through `addResource()` and `addResourceTemplate()` methods for task templates, workflow definitions, and project metadata. Resources give LLM clients context-rich information without executing tools.
+      - **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/core/utils/`: Directory containing utility functions like `path-utils.js` with `findTasksJsonPath`.
-      - `mcp-server/src/core/direct-functions/`: Directory containing individual files for each direct function wrapper (`*Direct`). These files contain the primary logic, including path resolution, core function calls, and caching.
+      - `mcp-server/src/core/utils/`: Directory containing utility functions specific to the MCP server, like **`path-utils.js` for project root detection**.
+      - `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 utility functions.
-      - `mcp-server/src/tools/utils.js`: Provides utilities like `handleApiResult`, `processMCPResponseData`, and `getCachedOrExecute`.
+      - [`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.
+      - `mcp-server/src/tools/utils.js`: Provides MCP-specific utilities like `handleApiResult`, `processMCPResponseData`, and `getCachedOrExecute`.
     - **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`
@@ -136,7 +137,7 @@ 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`, which then calls direct function wrappers (located in `mcp-server/src/core/direct-functions/` and exported via `task-master-core.js`) or falls back to `executeTaskMasterCommand`. Responses are formatted by `mcp-server/src/tools/utils.js`. See [`mcp.mdc`](mdc:.cursor/rules/mcp.mdc) for details.
+  - **MCP Server Interaction**: External tools interact with the `mcp-server`. MCP Tool `execute` methods call direct function wrappers (in `mcp-server/src/core/direct-functions/`). These wrappers handle path finding (using `path-utils.js`), validation, caching, call the core logic from `scripts/modules/`, and return a standardized result. The final MCP response is formatted by `mcp-server/src/tools/utils.js`. See [`mcp.mdc`](mdc:.cursor/rules/mcp.mdc) for details.
 
 - **Testing Architecture**:
 
@@ -187,32 +188,25 @@ Follow these steps to add MCP support for an existing Task Master command (see [
 1.  **Ensure Core Logic Exists**: Verify the core functionality is implemented and exported from the relevant module in `scripts/modules/`.
 
 2.  **Create Direct Function File in `mcp-server/src/core/direct-functions/`**:
-    - Create a new file (e.g., `your-command.js`) in the `direct-functions` directory.
-    - Import necessary core functions from Task Master modules (e.g., `../../../../scripts/modules/task-manager.js`).
-    - Import utilities: `findTasksJsonPath` from `../utils/path-utils.js` and `getCachedOrExecute` from `../../tools/utils.js` if needed.
+    - Create a new file (e.g., `your-command.js`).
+    - Import necessary core functions and **`findTasksJsonPath` from `../utils/path-utils.js`**.
     - Implement `async function yourCommandDirect(args, log)`:
-        - Parse `args` and determine necessary inputs (e.g., `tasksPath` via `findTasksJsonPath`).
-        - **If Caching**:
-            - Generate a unique `cacheKey` based on arguments defining the operation.
-            - Define an `async` function `coreActionFn` containing the call to the core logic.
-            - Call `const result = await getCachedOrExecute({ cacheKey, actionFn: coreActionFn, log });`.
-        - **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 }`.
+        - **Get `tasksPath` using `findTasksJsonPath(args, log)`**. 
+        - Parse/validate other args.
+        - 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**:
-    - Import your direct function: `import { yourCommandDirect } from './direct-functions/your-command.js';`
-    - Re-export it in the exports section.
-    - Add it to the `directFunctions` map: `yourCommand: yourCommandDirect`.
+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`).
-    - Import `z` for schema definition.
-    - Import `handleApiResult` from `./utils.js`.
-    - Import the `yourCommandDirect` wrapper function from `../core/task-master-core.js`.
-    - Implement `registerYourCommandTool(server)` following the standard pattern.
+    - Import `zod`, `handleApiResult`, and your `yourCommandDirect` function.
+    - Implement `registerYourCommandTool(server)`.
+    - **Define parameters, making `projectRoot` optional**: `projectRoot: z.string().optional().describe(...)`.
+    - Implement the standard `execute` method: Call `yourCommandDirect(args, log)` and pass 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 to the `tools` array in `.cursor/mcp.json`.
+6.  **Update `mcp.json`**: Add the new tool definition.