- Refactor for more reliable project root detection, particularly when running within integrated environments like Cursor IDE. Includes deriving root from script path and avoiding fallback to '/'.
- Enhance error handling in :
- Add detailed debug information (paths searched, CWD, etc.) to the error message when is not found in the provided project root.
- Improve clarity of error messages and potential solutions.
- Add verbose logging in to trace session object content and the finally resolved project root path, aiding in debugging path-related issues.
- Add default values for and to the example environment configuration.
Updated several Cursor rules documentation files (`mcp.mdc`, `utilities.mdc`, `architecture.mdc`, `new_features.mdc`, `commands.mdc`) to accurately reflect recent refactoring and clarify best practices.
Key documentation updates include:
- Explicitly stating the preference for using MCP tools over CLI commands in integrated environments (`commands.mdc`, `dev_workflow.mdc`).
- Describing the new standard pattern for getting the project root using `getProjectRootFromSession` within MCP tool `execute` methods (`mcp.mdc`, `utilities.mdc`, `architecture.mdc`, `new_features.mdc`).
- Clarifying the simplified role of `findTasksJsonPath` in direct functions (`mcp.mdc`, `utilities.mdc`, `architecture.mdc`, `new_features.mdc`).
- Ensuring proper interlinking between related documentation files.
This commit refactors how the MCP server determines the project root directory, prioritizing the path provided by the client session (e.g., Cursor) for increased reliability and simplification.
Previously, project root discovery relied on a complex chain of fallbacks (environment variables, CWD searching, package path checks) within `findTasksJsonPath`. This could be brittle and less accurate when running within an integrated environment like Cursor.
Key changes:
- **Prioritize Session Roots:** MCP tools (`add-task`, `add-dependency`, etc.) now first attempt to extract the project root URI directly from `session.roots[0].uri`.
- **New Utility `getProjectRootFromSession`:** Added a utility function in `mcp-server/src/tools/utils.js` to encapsulate the logic for extracting and decoding the root URI from the session object.
- **Refactor MCP Tools:** Updated tools (`add-task.js`, `add-dependency.js`) to use `getProjectRootFromSession`.
- **Simplify `findTasksJsonPath`:** Prioritized `args.projectRoot`, removed checks for `TASK_MASTER_PROJECT_ROOT` env var and package directory fallback. Retained CWD search and cache check for CLI compatibility.
- **Fix `reportProgress` Usage:** Corrected parameters in `add-dependency.js`.
This change makes project root determination more robust for the MCP server while preserving discovery mechanisms for the standalone CLI.
- Enhance MCP server robustness and usability:
- Implement smart project root detection with hierarchical fallbacks
- Make projectRoot parameter optional across all MCP tools
- Add comprehensive PROJECT_MARKERS for reliable project detection
- Improve error messages and logging for better debugging
- Split monolithic core into focused direct-function files
- Implement full suite of MCP commands:
- Add task management: update-task, update-subtask, generate
- Add task organization: expand-task, expand-all, clear-subtasks
- Add dependency handling: add/remove/validate/fix dependencies
- Add analysis tools: analyze-complexity, complexity-report
- Rename commands for better API consistency (list-tasks → get-tasks)
- Enhance documentation and developer experience:
- Create and bundle new taskmaster.mdc as comprehensive reference
- Document all tools with natural language patterns and examples
- Clarify project root auto-detection in documentation
- Standardize naming conventions across MCP components
- Add cross-references between related tools and commands
- Improve UI and progress tracking:
- Add color-coded progress bars with status breakdown
- Implement cancelled/deferred task status handling
- Enhance status visualization and counting
- Optimize display for various terminal sizes
This major update significantly improves the robustness and usability
of the MCP server while providing comprehensive documentation for both
users and developers. The changes make Task Master more intuitive to
use programmatically while maintaining full CLI functionality.
- Update all tool definitions to use z.string().optional() for projectRoot
- Fix direct function implementations to use findTasksJsonPath(args, log) pattern
- Enables consistent project root detection without requiring explicit params
- Update changeset to document these improvements
This change ensures MCP tools work properly with the smart project root
detection system, removing the need for explicit projectRoot parameters in
client applications. Improves usability and reduces integration friction.
Overhauls the project root detection system with a hierarchical precedence mechanism that intelligently locates tasks.json and identifies project roots. This improves user experience by reducing the need for explicit path parameters and enhances cross-platform compatibility.
Key Improvements:
- Implement hierarchical precedence for project root detection:
* Environment variable override (TASK_MASTER_PROJECT_ROOT)
* Explicitly provided --project-root parameter
* Cached project root from previous successful operations
* Current directory with project markers
* Parent directory traversal to find tasks.json
* Package directory as fallback
- Create comprehensive PROJECT_MARKERS detection system with 20+ common indicators:
* Task Master specific files (tasks.json, tasks/tasks.json)
* Version control directories (.git, .svn)
* Package manifests (package.json, pyproject.toml, Gemfile, go.mod, Cargo.toml)
* IDE/editor configurations (.cursor, .vscode, .idea)
* Dependency directories (node_modules, venv, .venv)
* Configuration files (.env, tsconfig.json, webpack.config.js)
* CI/CD files (.github/workflows, .gitlab-ci.yml, .circleci/config.yml)
- DRY refactoring of path utilities:
* Centralize path-related functions in core/utils/path-utils.js
* Export PROJECT_MARKERS as a single source of truth
* Add caching via lastFoundProjectRoot for performance optimization
- Enhanced user experience:
* Improve error messages with specific troubleshooting guidance
* Add detailed logging to indicate project root detection source
* Update tool parameter descriptions for better clarity
* Add recursive parent directory searching for tasks.json
Testing:
- Verified in local dev environment
- Added unit tests for the progress bar visualization
- Updated "automatically detected" description in MCP tools
This commit addresses Task #38: Implement robust project root handling for file paths.
- Add cancelled status to UI module for marking tasks cancelled without deletion
- Improve MCP server resource documentation with implementation examples
- Update architecture.mdc with detailed resource management info
- Add comprehensive resource handling guide to mcp.mdc
- Update changeset to reflect new features and documentation
- Mark task 23.6 as cancelled (MCP SDK integration no longer needed)
- Complete task 23.12 (structured logging system)
- Update subtask 23.10 with details on resource and resource template implementation
- Add resource management section to architecture.mdc with proper directory structure
- Create comprehensive resource implementation guide in mcp.mdc with examples and best practices
- Document proper integration of resources in FastMCP server initialization
- Create direct function wrapper in add-task.js with prompt and dependency handling
- Add MCP tool integration for creating new tasks via AI
- Update task-master-core.js to expose addTaskDirect function
- Update changeset to document the new command
- Create direct function wrapper in expand-task.js with error handling
- Add MCP tool integration for breaking down tasks into subtasks
- Update task-master-core.js to expose expandTaskDirect function
- Update changeset to document the new command
- Parameter support for subtask generation options (num, research, prompt, force)
- Create direct function wrapper in next-task.js with error handling and caching
- Add MCP tool integration for finding the next task to work on
- Update task-master-core.js to expose nextTaskDirect function
- Update changeset to document the new command
- Create direct function wrapper in show-task.js with error handling and caching
- Add MCP tool integration for displaying detailed task information
- Update task-master-core.js to expose showTaskDirect function
- Update changeset to document the new command
- Follow kebab-case/camelCase/snake_case naming conventions
Split monolithic task-master-core.js into separate function files within
the mcp-server/src/core/direct-functions/ directory. This change:
- Creates individual files for each direct function implementation
- Moves findTasksJsonPath to a dedicated utils/path-utils.js file
- Converts task-master-core.js to be a simple import/export hub
- Improves maintainability and organization of the codebase
- Reduces potential merge conflicts when multiple developers contribute
- Follows standard module separation patterns
Each function is now in its own self-contained file with clear imports and
focused responsibility, while maintaining the same API endpoints.
The function aimed to abstract the common flow within MCP tool methods (logging, calling direct function, handling result).
However, the established pattern (e.g., in ) involves the method directly calling the function (which handles its own caching via ) and then passing the result to . This pattern is clear, functional, and leverages the core utilities effectively.
Removing the unused simplifies , eliminates a redundant abstraction layer, and clarifies the standard implementation pattern for MCP tools.
* fix: add CI for better control of regressions during PRs
* fix: slight readme improvement
* chore: fix CI
* cleanup
* fix: duplicate workflow trigger
