An AI-powered task-management system you can drop into Cursor, Lovable, Windsurf, Roo, and others.
JavaScript aicursorcursor-aicursorailovablelovable-devroocodetask-managertaskstasks-listwindsurfwindsurf-ai
feat(mcp): major MCP server improvements and documentation overhaul
Eyal Toledano3af469b35f3c
diff --git a/.changeset/two-bats-smoke.md b/.changeset/two-bats-smoke.mdindex 9d87411c..c47f0621 100644--- a/.changeset/two-bats-smoke.md+++ b/.changeset/two-bats-smoke.md@@ -55,6 +55,19 @@- 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)++- 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+ - 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+- 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 percentagediff --git a/.cursor/rules/architecture.mdc b/.cursor/rules/architecture.mdcindex 3916d771..576eb33b 100644--- a/.cursor/rules/architecture.mdc+++ b/.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`.\ No newline at end of file+6. **Update `mcp.json`**: Add the new tool definition.\ No newline at end of filediff --git a/.cursor/rules/dev_workflow.mdc b/.cursor/rules/dev_workflow.mdcindex f5b9ea17..d2b66a09 100644--- a/.cursor/rules/dev_workflow.mdc+++ b/.cursor/rules/dev_workflow.mdc@@ -1,345 +1,162 @@----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 workflowsglobs: **/*alwaysApply: true----- **Global CLI Commands**- - Task Master now provides a global CLI through the `task-master` command (See [`commands.mdc`](mdc:.cursor/rules/commands.mdc) for details)- - 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`- - `task-master next`- - `task-master expand --id=3`- - All commands accept the same options as their script equivalents- - The CLI (`task-master`) is the **primary** way for users to interact with the application.--- **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- - 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- - 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- - Respect dependency chains and task priorities when selecting work- - **MCP Server**: For integrations (like Cursor), interact via the MCP server which prefers direct function calls. Restart the MCP server if core logic in `scripts/modules` changes. See [`mcp.mdc`](mdc:.cursor/rules/mcp.mdc).- - Report progress regularly using the list command--- **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- - 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--- **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>`- - 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 (See Command Reference below)--- **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--- **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>-- # Test Strategy:- <verification approach>- ```--- **Command Reference: parse-prd**- - 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**- - 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: update-task**- - CLI Syntax: `task-master update-task --id=<id> --prompt="<prompt>"`- - Description: Updates a single task by ID with new information- - Parameters:- - `--id=<id>`: ID of the task to update (required)- - `--prompt="<text>"`: New information or context to update the task (required)- - `--research`: Use Perplexity AI for research-backed updates- - Example: `task-master update-task --id=5 --prompt="Use JWT for authentication instead of sessions."`- - Notes: Only updates tasks not marked as 'done'. Preserves completed subtasks.--- **Command Reference: update-subtask**- - CLI Syntax: `task-master update-subtask --id=<id> --prompt="<prompt>"`- - Description: Appends additional information to a specific subtask without replacing existing content- - Parameters:- - `--id=<id>`: ID of the subtask to update in format "parentId.subtaskId" (required)- - `--prompt="<text>"`: Information to add to the subtask (required)- - `--research`: Use Perplexity AI for research-backed updates- - Example: `task-master update-subtask --id=5.2 --prompt="Add details about API rate limiting."`- - Notes:- - Appends new information to subtask details with timestamp- - Does not replace existing content, only adds to it- - Uses XML-like tags to clearly mark added information- - Will not update subtasks marked as 'done' or 'completed'--- **Command Reference: 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**- - 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**- - 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**- - 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**- - 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**- - 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`)- - **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]`)+# Task Master Development Workflow++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 `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 (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="..."` (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 `get_tasks` / `task-master list`++## 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` tool/command++## 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 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++- When implementation differs significantly from planned approach+- When future tasks need modification due to current implementation choices+- When new dependencies or requirements emerge+- Use `update` / `task-master update --from=<futureTaskId> --prompt="<explanation>"` (see [`taskmaster.mdc`](mdc:.cursor/rules/taskmaster.mdc)) to update multiple future tasks.+- Use `update_task` / `task-master update-task --id=<taskId> --prompt="<explanation>"` (see [`taskmaster.mdc`](mdc:.cursor/rules/taskmaster.mdc)) to update a single specific task.++## 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 Structure Fields++- **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.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", ...}]`)--- **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`)--- **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- - Tasks are prioritized by priority level, dependency count, and ID- - The command shows comprehensive task information including:+- **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++- 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- Implementation details- Subtasks (if they exist)- Contextual suggested actions- - Recommended before starting any new development work- - Respects your project's dependency structure- - 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- - 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- - For subtasks, shows parent task information and relationship- - 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- - 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**- - 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+- Recommended before starting any new development work+- Respects your project's dependency structure+- Ensures tasks are completed in the appropriate sequence+- Provides ready-to-use commands for common task actions++## 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+- For subtasks, shows parent task information and relationship+- Provides contextual suggested actions appropriate for the specific task+- Useful for examining task details before implementation or checking status++## 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++## 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.-- **Command Reference: remove-dependency**- - 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--- **Command Reference: validate-dependencies**- - 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--- **Command Reference: fix-dependencies**- - 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--- **Command Reference: complexity-report**- - 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--- **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--- **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--- **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\ No newline at end of file+---+*This workflow provides a general guideline. Adapt it based on your specific project needs and team practices.*\ No newline at end of filediff --git a/.cursor/rules/glossary.mdc b/.cursor/rules/glossary.mdcindex 60db9ba6..a8a48041 100644--- a/.cursor/rules/glossary.mdc+++ b/.cursor/rules/glossary.mdc@@ -9,14 +9,16 @@ alwaysApply: trueThis 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 meta-development script (`scripts/dev.js`) and the `task-master` CLI to manage task-driven development workflows.+- **[`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.diff --git a/.cursor/rules/mcp.mdc b/.cursor/rules/mcp.mdcindex fce827e8..a06fc102 100644--- a/.cursor/rules/mcp.mdc+++ b/.cursor/rules/mcp.mdc@@ -12,34 +12,36 @@ This document outlines the architecture and implementation patterns for the TaskThe 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/task-master-core.js`) <-> `Core Modules` (`scripts/modules/*.js`)+- **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.## Key Principles-- **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)).+- **Prefer Direct Function Calls**: For optimal performance and error handling, MCP tools should utilize direct function wrappers (exported via [`task-master-core.js`](mdc:mcp-server/src/core/task-master-core.js), implemented in [`mcp-server/src/core/direct-functions/`](mdc:mcp-server/src/core/direct-functions/)). 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 }`).+ 1. Call the corresponding `*Direct` function wrapper (e.g., `listTasksDirect`), passing the *entire* `args` object received from the tool invocation and the `log` object.+ 2. Receive the result object (typically `{ success, data/error, fromCache }`) from the `*Direct` function.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.+- **Robust Project Root Handling**:+ - **Tool Definition**: Any MCP tool that needs to locate the project's `tasks.json` *must* define the `projectRoot` parameter in its `zod` schema as **optional**: `projectRoot: z.string().optional().describe(...)`. This allows clients to optionally specify a root, but doesn't require it.+ - **Path Resolution Utility**: The `findTasksJsonPath` utility (in [`core/utils/path-utils.js`](mdc:mcp-server/src/core/utils/path-utils.js)) handles the actual detection of the project root and `tasks.json` path using a hierarchical approach (env var, explicit arg, cache, cwd search, package fallback).+ - **Direct Function Usage**: The `*Direct` function wrapper (in `mcp-server/src/core/direct-functions/`) is responsible for getting the correct path by calling `const tasksPath = findTasksJsonPath(args, log);`. It passes the *entire `args` object* received by the tool (which may or may not contain `projectRoot` or `file` properties) and the `log` object. `findTasksJsonPath` will use the values within `args` according to its precedence rules.- **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.+ - `getCachedOrExecute`: **Used inside `*Direct` functions** 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).+- **Caching**: To improve performance for frequently called read operations (like `get_tasks`, `get_task`, `next_task`), a caching layer using `lru-cache` is implemented.+ - **Caching logic resides *within* the direct function wrappers** 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.+ - Cache statistics can be monitored using the `cache_stats` MCP tool.+ - **Caching should generally be applied to read-only operations** that don't modify the `tasks.json` state. Commands like `set_task_status`, `add_task`, `update_task`, `parse_prd`, `add_dependency` should *not* be cached as they change the underlying data.## Resources and Resource Templates@@ -208,31 +210,25 @@ Follow these steps to add MCP support for an existing Task Master command (see [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 using **kebab-case** for file naming.- - 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.+ - Import necessary core functions from Task Master modules.+ - Import utilities: **`findTasksJsonPath` from `../utils/path-utils.js`** and `getCachedOrExecute` from `../../tools/utils.js` if needed.- Implement `async function yourCommandDirect(args, log)` using **camelCase** with `Direct` suffix:- - 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.+ - **Path Resolution**: Obtain the tasks file path using `const tasksPath = findTasksJsonPath(args, log);`. This handles project root detection automatically.+ - Parse other `args` and perform necessary validation.+ - **If Caching**: Implement caching using `getCachedOrExecute` as described above.+ - **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 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**: 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 `z` for schema definition.- - Import `handleApiResult` from `./utils.js`.- - Import the `yourCommandDirect` wrapper function from `../core/task-master-core.js`.- - Implement `registerYourCommandTool(server)` using **camelCase** with `Tool` suffix.+ - Import `zod`, `handleApiResult`, `createErrorResponse`, and your `yourCommandDirect` function.+ - Implement `registerYourCommandTool(server)`.- Define the tool `name` using **snake_case** (e.g., `your_command`).+ - Define the `parameters` using `zod`. **Crucially, if the tool needs project context, include `projectRoot: z.string().optional().describe(...)` and potentially `file: z.string().optional().describe(...)`**. Make `projectRoot` optional.+ - Implement the standard `async execute(args, log)` method: call `yourCommandDirect(args, log)` and pass the result to `handleApiResult(result, log, 'Error Message')`.5. **Register Tool**: Import and call `registerYourCommandTool` in `mcp-server/src/tools/index.js`.diff --git a/.cursor/rules/new_features.mdc b/.cursor/rules/new_features.mdcindex 8346df65..3dc02f81 100644--- a/.cursor/rules/new_features.mdc+++ b/.cursor/rules/new_features.mdc@@ -320,51 +320,60 @@ Integrating Task Master commands with the MCP server (for use by tools like Curs**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 (`task-master-core.js`)**:- - Create an `async function yourCommandDirect(args, log)` in [`task-master-core.js`](mdc:mcp-server/src/core/task-master-core.js).- - This function imports and calls the core logic function.- - It handles argument parsing, path resolution (e.g., using `findTasksJsonPath`), and validation specific to the direct call.+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 and necessary MCP utilities like **`findTasksJsonPath` from `../utils/path-utils.js`** and potentially `getCachedOrExecute` from `../../tools/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);`. Pass the *entire `args` object* received by the tool and the `log` object.+ - Perform validation on other arguments received in `args`.- **Implement Caching (if applicable)**:- - **Use Case**: Apply caching primarily for read-only operations that benefit from repeated calls (e.g., `listTasks`, `showTask`, `nextTask`). Avoid caching for operations that modify state (`setTaskStatus`, `addTask`, `parsePRD`, `updateTask`, `addDependency`, etc.).- - **Implementation**: Inside the `yourCommandDirect` function, use the `getCachedOrExecute` utility (imported from `../tools/utils.js`).+ - **Use Case**: Apply caching primarily for read-only operations that benefit from repeated calls (e.g., `get_tasks`, `get_task`, `next_task`). Avoid caching for operations that modify state (`set_task_status`, `add_task`, `parse_prd`, `update_task`, `add_dependency`, etc.).+ - **Implementation**: Use the `getCachedOrExecute` utility (imported from `../../tools/utils.js`).- Generate a unique `cacheKey` based on relevant arguments (e.g., file path, filters).- Define an `async` function `coreActionFn` that wraps the actual call to the core logic and returns `{ success: true/false, data/error }`.- Call `await getCachedOrExecute({ cacheKey, actionFn: coreActionFn, log });`.- - The `yourCommandDirect` function must return a standard object: `{ success: true/false, data/error, fromCache: boolean }`. For non-cached operations, `fromCache` should be `false`.- - Export the function and add it to the `directFunctions` map in `task-master-core.js`.-3. **MCP Tool File (`mcp-server/src/tools/`)**:- - Create a new file (e.g., `yourCommand.js`).+ - **If Not Caching**: Directly call the core logic function within a try/catch block.+ - Handle errors and return a standard object: `{ success: true/false, data/error, fromCache: boolean }`. (For non-cached operations, `fromCache` is `false`).+ - Export the function.+3. **Export from `task-master-core.js`**: Import your new `*Direct` function into [`task-master-core.js`](mdc:mcp-server/src/core/task-master-core.js), re-export it, and add it to the `directFunctions` map.+4. **MCP Tool File (`mcp-server/src/tools/`)**:+ - Create a new file (e.g., `your-command.js`) using **kebab-case** naming.- Import `zod` (for schema), `handleApiResult`, `createErrorResponse` from `./utils.js`, and your `yourCommandDirect` function from `../core/task-master-core.js`.- - Implement `registerYourCommandTool(server)` which calls `server.addTool`.- - Define the tool's `name`, `description`, and `parameters` using `zod`.- - Define the `async execute(args, log)` method. **This is the standard pattern**:+ - Implement `registerYourCommandTool(server)` using **camelCase** with `Tool` suffix, which calls `server.addTool`.+ - Define the tool's `name` using **snake_case** (e.g., `your_command`), `description`, and `parameters` using `zod`. **Crucially, define `projectRoot` as optional**: `projectRoot: z.string().optional().describe(...)`. Include `file: z.string().optional().describe(...)` if applicable.+ - Define the standard `async execute(args, log)` method:```javascript- // In mcp-server/src/tools/yourCommand.js+ // In mcp-server/src/tools/your-command.jsimport { z } from "zod";import { handleApiResult, createErrorResponse } from "./utils.js";- import { yourCommandDirect } from "../core/task-master-core.js";+ import { yourCommandDirect } from "../core/task-master-core.js"; // Adjust path as neededexport function registerYourCommandTool(server) {server.addTool({- name: "yourCommand",+ name: "your_command", // snake_casedescription: "Description of your command.",- parameters: z.object({ /* zod schema, include projectRoot, file if needed */ }),+ parameters: z.object({+ /* zod schema */+ projectRoot: z.string().optional().describe("Optional project root path"),+ file: z.string().optional().describe("Optional tasks file path relative to project root"),+ /* other parameters */+ }),async execute(args, log) {try {- log.info(`Executing Your Command with args: ${JSON.stringify(args)}`);+ log.info(`Executing your_command with args: ${JSON.stringify(args)}`);// 1. Call the direct function wrapperconst result = await yourCommandDirect(args, log);// 2. Pass the result to handleApiResult for formatting- return handleApiResult(result, log, 'Error during Your Command');+ return handleApiResult(result, log, 'Error executing your_command'); // Provide a default error message} catch (error) {- // Catch unexpected errors from the direct call itself- log.error(`Unexpected error in tool execute: ${error.message}`);+ // Catch unexpected errors from the direct call or handleApiResult itself+ log.error(`Unexpected error in your_command tool execute: ${error.message}`);return createErrorResponse(`Tool execution failed: ${error.message}`);}}});}```-4. **Register in Tool Index**: Import and call `registerYourCommandTool` in [`mcp-server/src/tools/index.js`](mdc:mcp-server/src/tools/index.js).-5. **Update `mcp.json`**: Add the tool definition to `.cursor/mcp.json`.+5. **Register in Tool Index**: Import and call `registerYourCommandTool` in [`mcp-server/src/tools/index.js`](mdc:mcp-server/src/tools/index.js).+6. **Update `mcp.json`**: Add the tool definition (name, description, parameters) to `.cursor/mcp.json`.diff --git a/.cursor/rules/taskmaster.mdc b/.cursor/rules/taskmaster.mdcnew file mode 100644index 00000000..9d6a9db1--- /dev/null+++ b/.cursor/rules/taskmaster.mdc@@ -0,0 +1,298 @@+---+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.++---++## Initialization & Setup++### 1. Initialize Project (`init`)++* **MCP Tool:** N/A (Note: MCP equivalent is not currently practical, this is a CLI only action)+* **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.++### 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.++---++## 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.++### 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.++### 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.++### 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.`+* **Key Parameters/Options:**+ * `id`: `Required. The specific ID of the Taskmaster subtask (e.g., '15.2') you want to add information to.` (CLI: `-i, --id <id>`)+ * `prompt`: `Required. Provide the information or notes Taskmaster should append to the subtask's details.` (CLI: `-p, --prompt <text>`)+ * `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.++### 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.++---++## Task Structure & Breakdown++### 12. 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.++### 13. 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.++### 14. 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.++### 15. 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++### 16. 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.++### 17. 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.++### 18. 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.++### 19. 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++### 20. Analyze Complexity (`analyze_complexity`)++* **MCP Tool:** `analyze_complexity`+* **CLI Command:** `task-master analyze-complexity [options]`+* **Description:** `Let Taskmaster analyze the complexity of your tasks and generate a report with recommendations for which ones need breaking down.`+* **Key Parameters/Options:**+ * `output`: `Where Taskmaster should save the JSON complexity analysis report (default: 'scripts/task-complexity-report.json').` (CLI: `-o, --output <file>`)+ * `threshold`: `The minimum complexity score (1-10) for Taskmaster to recommend expanding a task.` (CLI: `-t, --threshold <number>`)+ * `research`: `Enable Taskmaster to use Perplexity AI for more informed complexity analysis (requires PERPLEXITY_API_KEY).` (CLI: `-r, --research`)+ * `file`: `Path to your Taskmaster 'tasks.json' file (default relies on auto-detection).` (CLI: `-f, --file <file>`)+* **Usage:** Identify which tasks are likely too large and need further breakdown before implementation.++### 21. Complexity Report (`complexity_report`)++* **MCP Tool:** `complexity_report`+* **CLI Command:** `task-master complexity-report [options]`+* **Description:** `Display the Taskmaster task complexity analysis report generated by 'analyze-complexity'.`+* **Key Parameters/Options:**+ * `file`: `Path to the JSON complexity report file (default: 'scripts/task-complexity-report.json').` (CLI: `-f, --file <file>`)+* **Usage:** View the formatted results of the complexity analysis to guide task expansion.++---++## File Generation++### 22. Generate Task Files (`generate`)++* **MCP Tool:** `generate`+* **CLI Command:** `task-master generate [options]`+* **Description:** `Generate individual markdown files for each task and subtask defined in your Taskmaster 'tasks.json'.`+* **Key Parameters/Options:**+ * `file`: `Path to your Taskmaster 'tasks.json' file containing the task data (default relies on auto-detection).` (CLI: `-f, --file <file>`)+ * `output`: `The directory where Taskmaster should save the generated markdown task files (default: 'tasks').` (CLI: `-o, --output <dir>`)+* **Usage:** Create/update the individual `.md` files in the `tasks/` directory, useful for tracking changes in git or viewing tasks individually.++---++## Configuration & Metadata++- **Environment Variables**: Taskmaster relies on environment variables for configuration (API keys, model preferences, default settings). See [`dev_workflow.mdc`](mdc:.cursor/rules/dev_workflow.mdc) or the project README for a list.+- **`tasks.json`**: The core data file containing the array of tasks and their details. See [`tasks.mdc`](mdc:.cursor/rules/tasks.mdc).+- **`task_xxx.md` files**: Individual markdown files generated by the `generate` command/tool, reflecting the content of `tasks.json`.diff --git a/.cursor/rules/utilities.mdc b/.cursor/rules/utilities.mdcindex 6d3c54fb..d9e37256 100644--- a/.cursor/rules/utilities.mdc+++ b/.cursor/rules/utilities.mdc@@ -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,19 +90,19 @@ alwaysApply: false```javascript// ✅ DO: Set up configuration with defaults and environment overridesconst CONFIG = {- model: process.env.MODEL || 'claude-3-7-sonnet-20250219',+ model: process.env.MODEL || 'claude-3-opus-20240229', // Updated default modelmaxTokens: 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)@@ -129,18 +135,23 @@ alwaysApply: false}```-## File Operations+## 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 utilsfunction 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 +162,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 +235,7 @@ alwaysApply: false}```-## Cycle Detection+## Cycle Detection (in `scripts/modules/utils.js`)- **Graph Algorithms**:- ✅ DO: Implement cycle detection using graph traversal@@ -273,101 +284,110 @@ alwaysApply: false}```-## MCP Server Utilities (`mcp-server/src/tools/utils.js`)+## MCP Server Core Utilities (`mcp-server/src/core/utils/`)++### Project Root and Task File Path Detection (`path-utils.js`)-- **Purpose**: These utilities specifically support the MCP server tools, handling communication patterns and data formatting for MCP clients. Refer to [`mcp.mdc`](mdc:.cursor/rules/mcp.mdc) for usage patterns.+- **Purpose**: This module (`mcp-server/src/core/utils/path-utils.js`) provides the **primary mechanism for locating the user's project root and `tasks.json` file**, specifically for the MCP server context.+- **`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 and the `log` object.+ - Implements a **hierarchical precedence system** for finding the project:+ 1. `TASK_MASTER_PROJECT_ROOT` environment variable.+ 2. Explicit `projectRoot` passed in `args`.+ 3. Cached `lastFoundProjectRoot` from a previous successful search.+ 4. Search upwards from `process.cwd()` for `tasks.json` or project markers (like `.git`, `package.json`).+ 5. Fallback to checking the Taskmaster package directory (for development).+ - 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 search.+- **`getPackagePath()`**: Utility to find the installation path of the `task-master-ai` package itself.--(See also: [`tests.mdc`](mdc:.cursor/rules/tests.mdc) for testing these utilities)+## MCP Server Tool Utilities (`mcp-server/src/tools/utils.js`)++- **Purpose**: These utilities specifically support the MCP server tools (`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.- **`getProjectRoot(projectRootRaw, log)`**:- - Normalizes a potentially relative project root path into an absolute path.- - Defaults to `process.cwd()` if `projectRootRaw` is not provided.- - Can be used within `*Direct` functions if needed, although often the `projectRoot` argument is passed through.+ - Primarily a helper for `executeTaskMasterCommand` or other specific cases where only the root is needed, *not* the full `tasks.json` path.+ - Normalizes a potentially relative path and applies defaults.+ - ❌ **DON'T**: Use this as the primary way to find `tasks.json`. Use `findTasksJsonPath` from `path-utils.js` for that purpose within direct functions.- **`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 returned by direct function wrappers.- - Checks the `success` flag.- - If successful, processes the `result.data` using the provided `processFunction` (defaults to `processMCPResponseData` for filtering).- - Includes the `result.fromCache` flag in the final payload.- - Returns a formatted MCP response object using `createContentResponse` or `createErrorResponse`.+ - ✅ **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 command using `child_process.spawnSync`.- - Tries the global `task-master` command first, then falls back to `node scripts/dev.js`.- - Handles project root normalization internally.- - Returns `{ success, stdout, stderr }` or `{ success: false, error }`.- - ❌ **DON'T**: Use this as the primary method for MCP tools. Prefer direct function calls via `*Direct` wrappers. Use only as a fallback.--- **`processMCPResponseData(taskOrData, fieldsToRemove = ['details', 'testStrategy'])`**:- - Filters task data before sending it to the MCP client. Called by `handleApiResult` by default.- - By default, removes the `details` and `testStrategy` fields from task objects and their subtasks to reduce payload size.- - Can handle single task objects or data structures containing tasks.+ - 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.-- **`createContentResponse(content)`**:- - Used by `handleApiResult` to format successful MCP responses.- - Wraps the `content` (which includes the `fromCache` flag and processed `data`) in the standard FastMCP `{ content: [{ type: "text", text: ... }] }` structure, stringifying the payload object.+- **`processMCPResponseData(taskOrData, fieldsToRemove)`**:+ - Filters task data (e.g., removing `details`, `testStrategy`) before sending to the MCP client. Called by `handleApiResult`.-- **`createErrorResponse(errorMessage)`**:- - Used by `handleApiResult` or directly in the tool's `execute` catch block to format error responses for MCP.- - Wraps the `errorMessage` in the standard FastMCP error structure.+- **`createContentResponse(content)` / `createErrorResponse(errorMessage)`**:+ - Formatters for standard MCP success/error responses.- **`getCachedOrExecute({ cacheKey, actionFn, log })`**:- - ✅ **DO**: Use this utility *inside direct function wrappers* (like `listTasksDirect` in `task-master-core.js`) to implement caching for MCP operations.- - **Use Case**: Primarily for read-only operations (e.g., `list`, `show`, `next`). Avoid for operations modifying data.- - Checks the `ContextManager` cache using `cacheKey`.- - If HIT: returns the cached result directly (which should be `{ success, data/error }`), adding `fromCache: true`.- - If MISS: executes the provided `actionFn` (an async function returning `{ success, data/error }`).- - If `actionFn` succeeds, its result is stored in the cache.- - Returns the result (cached or fresh) wrapped in the standard structure `{ success, data/error, fromCache: boolean }`.+ - ✅ **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: Keep utilities relevant to their location (e.g., core utils in `scripts/modules/utils.js`, MCP utils in `mcp-server/src/tools/utils.js`).+ - ✅ 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.+ - ✅ DO: Export configuration constants (from `scripts/modules/utils.js`).- ❌ DON'T: Use default exports.- - ❌ DON'T: Create circular dependencies between utility files or between utilities and the modules that use them (See [`architecture.mdc`](mdc:.cursor/rules/architecture.mdc)).-- ```javascript- // ✅ DO: Organize exports logically- export {- // Configuration- CONFIG,- LOG_LEVELS,-- // Logging- log,-- // File operations- readJSON,- writeJSON,-- // String manipulation- sanitizePrompt,- truncate,-- // Task utilities- readComplexityReport,- findTaskInComplexityReport,- taskExists,- formatTaskId,- findTaskById,-- // Graph algorithms- findCycles,- };- ```--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. Use [`commands.mdc`](mdc:.cursor/rules/commands.mdc) for CLI integration details.--## MCP Server Utilities Structure--- **Core Utilities** (`mcp-server/src/core/utils/path-utils.js`):- - Contains path-related utilities like `findTasksJsonPath` that are used by direct function implementations.- - These are imported by direct function files in the `direct-functions/` directory.--- **MCP Tool Utilities** (`mcp-server/src/tools/utils.js`):- - Contains utilities related to MCP response handling and caching.\ No newline at end of file+ - ❌ DON'T: Create circular dependencies (See [`architecture.mdc`](mdc:.cursor/rules/architecture.mdc)).++```javascript+// Example export from scripts/modules/utils.js+export {+ // Configuration+ CONFIG,+ LOG_LEVELS,++ // Logging+ log,++ // File operations+ readJSON,+ writeJSON,++ // String manipulation+ sanitizePrompt,+ truncate,++ // Task utilities+ // ... (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,+ handleApiResult,+ executeTaskMasterCommand,+ processMCPResponseData,+ createContentResponse,+ createErrorResponse,+ getCachedOrExecute+};+```++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.\ No newline at end of filediff --git a/scripts/init.js b/scripts/init.jsindex ef5cfef6..31432c89 100755--- a/scripts/init.js+++ b/scripts/init.js@@ -212,6 +212,9 @@ function copyTemplateFile(templateName, targetPath, replacements = {}) {case 'dev_workflow.mdc':sourcePath = path.join(__dirname, '..', '.cursor', 'rules', 'dev_workflow.mdc');break;+ case 'taskmaster.mdc':+ sourcePath = path.join(__dirname, '..', '.cursor', 'rules', 'taskmaster.mdc');+ break;case 'cursor_rules.mdc':sourcePath = path.join(__dirname, '..', '.cursor', 'rules', 'cursor_rules.mdc');break;@@ -584,6 +587,9 @@ function createProjectStructure(projectName, projectDescription, projectVersion,// Copy dev_workflow.mdccopyTemplateFile('dev_workflow.mdc', path.join(targetDir, '.cursor', 'rules', 'dev_workflow.mdc'));++ // Copy taskmaster.mdc+ copyTemplateFile('taskmaster.mdc', path.join(targetDir, '.cursor', 'rules', 'taskmaster.mdc'));// Copy cursor_rules.mdccopyTemplateFile('cursor_rules.mdc', path.join(targetDir, '.cursor', 'rules', 'cursor_rules.mdc'));diff --git a/scripts/prepare-package.js b/scripts/prepare-package.jsindex 095f9ed5..1ae09407 100755--- a/scripts/prepare-package.js+++ b/scripts/prepare-package.js@@ -129,6 +129,7 @@ function preparePackage() {'assets/example_prd.txt','assets/scripts_README.md','.cursor/rules/dev_workflow.mdc',+ '.cursor/rules/taskmaster.mdc','.cursor/rules/cursor_rules.mdc','.cursor/rules/self_improve.mdc'];diff --git a/tasks/task_023.txt b/tasks/task_023.txtindex c75d2fe7..6bf46c3b 100644--- a/tasks/task_023.txt+++ b/tasks/task_023.txt@@ -1201,7 +1201,7 @@ const debugMode = config.env.get('DEBUG_MODE', false); // With a default valueThis method provides a consistent way to access environment variables defined in the mcp.json configuration file within your FastMCP project in a JavaScript environment.</info added on 2025-04-01T01:57:49.848Z>-## 46. adjust rules so it prioritizes mcp commands over script [pending]+## 46. adjust rules so it prioritizes mcp commands over script [done]### Dependencies: None### Description:### Details:diff --git a/tasks/tasks.json b/tasks/tasks.jsonindex 697668d0..818f83b3 100644--- a/tasks/tasks.json+++ b/tasks/tasks.json@@ -1777,7 +1777,7 @@"title": "adjust rules so it prioritizes mcp commands over script","description": "","details": "",- "status": "pending",+ "status": "done","dependencies": [],"parentTaskId": 23}