diff --git a/.changeset/two-bats-smoke.md b/.changeset/two-bats-smoke.md index 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 percentage diff --git a/.cursor/rules/architecture.mdc b/.cursor/rules/architecture.mdc index 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 file diff --git a/.cursor/rules/dev_workflow.mdc b/.cursor/rules/dev_workflow.mdc index 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 workflows globs: **/* 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 ` instead of `node scripts/dev.js ` - - 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. +# Task Master Development Workflow -- **Development Workflow Process** - - Start new projects by running `task-master init` or `node scripts/dev.js parse-prd --input=` 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 ` to understand implementation requirements - - Break down complex tasks using `task-master expand --id=` with appropriate flags - - Clear existing subtasks if needed using `task-master clear-subtasks --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= --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 +This guide outlines the typical process for using Task Master to manage software development projects. -- **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 +## Primary Interaction: MCP Server vs. CLI -- **Task Breakdown Process** - - For tasks with complexity analysis, use `node scripts/dev.js expand --id=` - - Otherwise use `node scripts/dev.js expand --id= --subtasks=` - - Add `--research` flag to leverage Perplexity AI for research-backed expansion - - Use `--prompt=""` 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) +Task Master offers two primary ways to interact: -- **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= --prompt=""` to update tasks.json +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. -- **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 +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. -- **Task File Format Reference** - ``` - # Task ID: - # Title: - # Status: <status> - # Dependencies: <comma-separated list of dependency IDs> - # Priority: <priority> - # Description: <brief description> - # Details: - <detailed implementation notes> - - # Test Strategy: - <verification approach> - ``` +## Standard Development Workflow Process -- **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. +- 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` -- **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. +## Task Complexity Analysis -- **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. +- 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 -- **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' +## Task Breakdown Process -- **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. +- 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)). -- **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. +## Implementation Drift Handling -- **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. +- 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. -- **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. +## Task Status Management -- **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. +- 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 -- **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 -- **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]`) +- **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", ...}]`) +- **priority**: Importance level (Example: `"high"`, `"medium"`, `"low"`) +- **details**: In-depth implementation instructions (Example: `"Use GitHub client ID/secret, handle callback, set session token."`) +- **testStrategy**: Verification approach (Example: `"Deploy and call endpoint to confirm 'Hello World' response."`) +- **subtasks**: List of smaller, more specific tasks (Example: `[{"id": 1, "title": "Configure OAuth", ...}]`) +- Refer to [`tasks.mdc`](mdc:.cursor/rules/tasks.mdc) for more details on the task data structure. -- **Environment Variables Configuration** - - **ANTHROPIC_API_KEY** (Required): Your Anthropic API key for Claude (Example: `ANTHROPIC_API_KEY=sk-ant-api03-...`) - - **MODEL** (Default: `"claude-3-7-sonnet-20250219"`): Claude model to use (Example: `MODEL=claude-3-opus-20240229`) - - **MAX_TOKENS** (Default: `"4000"`): Maximum tokens for responses (Example: `MAX_TOKENS=8000`) - - **TEMPERATURE** (Default: `"0.7"`): Temperature for model responses (Example: `TEMPERATURE=0.5`) - - **DEBUG** (Default: `"false"`): Enable debug logging (Example: `DEBUG=true`) - - **LOG_LEVEL** (Default: `"info"`): Console output level (Example: `LOG_LEVEL=debug`) - - **DEFAULT_SUBTASKS** (Default: `"3"`): Default subtask count (Example: `DEFAULT_SUBTASKS=5`) - - **DEFAULT_PRIORITY** (Default: `"medium"`): Default priority (Example: `DEFAULT_PRIORITY=high`) - - **PROJECT_NAME** (Default: `"MCP SaaS MVP"`): Project name in metadata (Example: `PROJECT_NAME=My Awesome Project`) - - **PROJECT_VERSION** (Default: `"1.0.0"`): Version in metadata (Example: `PROJECT_VERSION=2.1.0`) - - **PERPLEXITY_API_KEY**: For research-backed features (Example: `PERPLEXITY_API_KEY=pplx-...`) - - **PERPLEXITY_MODEL** (Default: `"sonar-medium-online"`): Perplexity model (Example: `PERPLEXITY_MODEL=sonar-large-online`) +## Environment Variables Configuration -- **Determining the Next Task** - - Run `task-master next` to show the next task to work on - - The next command identifies tasks with all dependencies satisfied - - Tasks are prioritized by priority level, dependency count, and ID - - The command shows comprehensive task information including: +- 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 +- 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 +## Viewing Specific Task Details -- **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 +- 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 -- **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 +## Managing Task Dependencies -- **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 +- Use `add_dependency` / `task-master add-dependency --id=<id> --depends-on=<id>` (see [`taskmaster.mdc`](mdc:.cursor/rules/taskmaster.mdc)) to add a dependency +- Use `remove_dependency` / `task-master remove-dependency --id=<id> --depends-on=<id>` (see [`taskmaster.mdc`](mdc:.cursor/rules/taskmaster.mdc)) to remove a dependency +- The system prevents circular dependencies and duplicate dependency entries +- Dependencies are checked for existence before being added or removed +- Task files are automatically regenerated after dependency changes +- Dependencies are visualized with status indicators in task listings and files -- **Command Reference: 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 +## Code Analysis & Refactoring Techniques -- **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 +- **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: 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 file diff --git a/.cursor/rules/glossary.mdc b/.cursor/rules/glossary.mdc index 60db9ba6..a8a48041 100644 --- a/.cursor/rules/glossary.mdc +++ b/.cursor/rules/glossary.mdc @@ -9,14 +9,16 @@ alwaysApply: true This file provides a quick reference to the purpose of each rule file located in the `.cursor/rules` directory. - **[`architecture.mdc`](mdc:.cursor/rules/architecture.mdc)**: Describes the high-level architecture of the Task Master CLI application. +- **[`changeset.mdc`](mdc:.cursor/rules/changeset.mdc)**: Guidelines for using Changesets (npm run changeset) to manage versioning and changelogs. - **[`commands.mdc`](mdc:.cursor/rules/commands.mdc)**: Guidelines for implementing CLI commands using Commander.js. - **[`cursor_rules.mdc`](mdc:.cursor/rules/cursor_rules.mdc)**: Guidelines for creating and maintaining Cursor rules to ensure consistency and effectiveness. - **[`dependencies.mdc`](mdc:.cursor/rules/dependencies.mdc)**: Guidelines for managing task dependencies and relationships. -- **[`dev_workflow.mdc`](mdc:.cursor/rules/dev_workflow.mdc)**: Guide for using 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.mdc index 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 Task The MCP server acts as a bridge between external tools (like Cursor) and the core Task Master CLI logic. It leverages FastMCP for the server framework. -- **Flow**: `External Tool (Cursor)` <-> `FastMCP Server` <-> `MCP Tools` (`mcp-server/src/tools/*.js`) <-> `Core Logic Wrappers` (`mcp-server/src/core/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.mdc index 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.js import { 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 needed export function registerYourCommandTool(server) { server.addTool({ - name: "yourCommand", + name: "your_command", // snake_case description: "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 wrapper const 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.mdc new file mode 100644 index 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.mdc index 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 overrides const CONFIG = { - model: process.env.MODEL || 'claude-3-7-sonnet-20250219', + model: process.env.MODEL || 'claude-3-opus-20240229', // Updated default model maxTokens: parseInt(process.env.MAX_TOKENS || '4000'), temperature: parseFloat(process.env.TEMPERATURE || '0.7'), debug: process.env.DEBUG === "true", logLevel: process.env.LOG_LEVEL || "info", defaultSubtasks: parseInt(process.env.DEFAULT_SUBTASKS || "3"), defaultPriority: process.env.DEFAULT_PRIORITY || "medium", - projectName: process.env.PROJECT_NAME || "Task Master", - projectVersion: "1.5.0" // Version should be hardcoded + projectName: process.env.PROJECT_NAME || "Task Master Project", // Generic project name + projectVersion: "1.5.0" // Version should be updated via release process }; ``` -## Logging Utilities +## Logging Utilities (in `scripts/modules/utils.js`) - **Log Levels**: - ✅ DO: Support multiple log levels (debug, info, warn, error) @@ -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 utils function writeJSON(filepath, data) { try { + // Ensure directory exists (example) + const dir = path.dirname(filepath); + if (!fs.existsSync(dir)) { + fs.mkdirSync(dir, { recursive: true }); + } fs.writeFileSync(filepath, JSON.stringify(data, null, 2)); } catch (error) { log('error', `Error writing JSON file ${filepath}:`, error.message); @@ -151,7 +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/`) -- **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. +### Project Root and Task File Path Detection (`path-utils.js`) --(See also: [`tests.mdc`](mdc:.cursor/rules/tests.mdc) for testing these utilities) +- **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. + +## 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. + - Executes a Task Master CLI command as a child process. + - Handles fallback between global `task-master` and local `node scripts/dev.js`. + - ❌ **DON'T**: Use this as the primary method for MCP tools. Prefer direct function calls via `*Direct` wrappers. -- **`processMCPResponseData(taskOrData, fieldsToRemove = ['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. +- **`processMCPResponseData(taskOrData, fieldsToRemove)`**: + - Filters task data (e.g., removing `details`, `testStrategy`) before sending to the MCP client. Called by `handleApiResult`. -- **`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. - -- **`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)). + - ❌ DON'T: Create circular dependencies (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, - }; - ``` +```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, +}; -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. +// 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 +}; -## MCP Server Utilities Structure +// Example export from mcp-server/src/tools/utils.js +export { + getProjectRoot, + handleApiResult, + executeTaskMasterCommand, + processMCPResponseData, + createContentResponse, + createErrorResponse, + getCachedOrExecute +}; +``` -- **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 +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 file diff --git a/scripts/init.js b/scripts/init.js index 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.mdc copyTemplateFile('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.mdc copyTemplateFile('cursor_rules.mdc', path.join(targetDir, '.cursor', 'rules', 'cursor_rules.mdc')); diff --git a/scripts/prepare-package.js b/scripts/prepare-package.js index 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.txt index 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 value This 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.json index 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 }