eyaltoledano
bug: MCP Integration Issues: Some Commands Work While Others Fail with Tag/Path Errors
Description
I'm experiencing inconsistent behavior with the task-master MCP server integration in Cascade. Some commands work properly (like viewing and updating tasks), but others (notably task creation) fail with errors related to paths being interpreted as tags.
Environment Operating System: macOS Task Master Version: 0.17.0 MCP Client: Cascade Project Structure: Nx monorepo for software documentation Working Commands The following task-master MCP commands work correctly:
mcp10_get_task - Successfully retrieves task details
mcp10_set_task_status - Successfully updates task status
mcp10_next_task - Successfully finds next task to work on
mcp10_use_tag - Successfully switches to the specified tag
mcp10_complexity_report - Successfully retrieves complexity report
Failing Commands The following commands consistently fail:
mcp10_add_task - Fails with tag/path errors
mcp10_analyze_project_complexity - Fails with API errors
Error Messages
When trying to add a task:
Error: Tag "/Users/username/Documents/gitProjects/[project-folder]" not found. Version: 0.17.0 Name: task-master-ai Current Tag: master When specifying a file path:
Error: tasksJsonPath is required Version: 0.17.0 Name: task-master-ai Current Tag: master Configuration Details MCP Configuration (.cursor/mcp.json)
json
{
"mcpServers": {
"task-master-ai": {
"command": "npx",
"args": [
"-y",
"--package=task-master-ai",
"task-master-ai"
],
"env": {
"ANTHROPIC_API_KEY": "[REDACTED]",
"PERPLEXITY_API_KEY": "PERPLEXITY_API_KEY_HERE",
"OPENAI_API_KEY": "OPENAI_API_KEY_HERE",
"GOOGLE_API_KEY": "[REDACTED]",
"XAI_API_KEY": "XAI_API_KEY_HERE",
"OPENROUTER_API_KEY": "OPENROUTER_API_KEY_HERE",
"MISTRAL_API_KEY": "MISTRAL_API_KEY_HERE",
"AZURE_OPENAI_API_KEY": "AZURE_OPENAI_API_KEY_HERE",
"OLLAMA_API_KEY": "OLLAMA_API_KEY_HERE"
}
}
}
}
Task Master Config (.taskmaster/config.json)
json
{
"models": {
"main": {
"provider": "anthropic",
"modelId": "claude-3-7-sonnet-20250219",
"maxTokens": 120000,
"temperature": 0.2
},
"research": {
"provider": "perplexity",
"modelId": "sonar",
"maxTokens": 8700,
"temperature": 0.1
},
"fallback": {
"provider": "anthropic",
"modelId": "claude-3-5-sonnet-20241022",
"maxTokens": 120000,
"temperature": 0.1
}
},
"global": {
"logLevel": "info",
"debug": false,
"defaultSubtasks": 5,
"defaultPriority": "medium"
}
}
State Information (.taskmaster/state.json)
json
{
"currentTag": "master",
"lastSwitched": "2025-06-15T17:13:09.746Z",
"branchTagMapping": {},
"migrationNoticeShown": true
}
Project Structure The project follows the correct structure as documented:
.taskmaster/ directory exists
config.json
is properly formatted
tasks/
directory contains 54+ task files and tasks.json
docs/ contains the PRD file
state.json
shows "master" as the current tag
Steps to Reproduce Ensure task-master-ai is installed globally with npm i -g task-master-ai Configure .cursor/mcp.json with the correct MCP server setup Initialize the project with task-master init (already completed) Try to use mcp10_get_task to access a task - this works correctly Try to use mcp10_add_task with the same projectRoot parameter - this fails with the tag error Expected Behavior All task-master MCP commands should work consistently, especially since they share the same parameter structure. The projectRoot parameter should be properly interpreted for all commands, not just some of them.
Attempted Solutions Reinstalled task-master-ai globally Reinitialized the project Explicitly set the tag using mcp10_use_tag Tried specifying file parameter instead of projectRoot Verified configuration files match documentation Additional Notes The mcp10_use_tag command works successfully and confirms that the tag "master" exists, yet the mcp10_add_task command fails with a "tag not found" error for the same project path. This suggests inconsistent parameter handling between different MCP commands.
The CLI version of task-master appears to work correctly, but the MCP integration has this inconsistency.
Error Messages When trying to add a task:
Error: Tag "/Users/username/Documents/gitProjects/[project-folder]" not found. Version: 0.17.0 Name: task-master-ai Current Tag: master
When specifying a file path:
At mention Error: tasksJsonPath is required Version: 0.17.0 Name: task-master-ai
Configuration Details MCP Configuration (.cursor/mcp.json)
json
At mention
{
"mcpServers": {
"task-master-ai": {
"command": "npx",
"args": [
"-y",
"--package=task-master-ai",
"task-master-ai"
],
"env": {
"ANTHROPIC_API_KEY": "[REDACTED]",
"PERPLEXITY_API_KEY": "PERPLEXITY_API_KEY_HERE",
"OPENAI_API_KEY": "OPENAI_API_KEY_HERE",
"GOOGLE_API_KEY": "[REDACTED]",
"XAI_API_KEY": "XAI_API_KEY_HERE",
"OPENROUTER_API_KEY": "OPENROUTER_API_KEY_HERE",
"MISTRAL_API_KEY": "MISTRAL_API_KEY_HERE",
"AZURE_OPENAI_API_KEY": "AZURE_OPENAI_API_KEY_HERE",
"OLLAMA_API_KEY": "OLLAMA_API_KEY_HERE"
}
}
}
}
Task Master Config (.taskmaster/config.json)
At mention
{
"models": {
"main": {
"provider": "anthropic",
"modelId": "claude-3-7-sonnet-20250219",
"maxTokens": 120000,
"temperature": 0.2
},
"research": {
"provider": "perplexity",
"modelId": "sonar",
"maxTokens": 8700,
"temperature": 0.1
},
"fallback": {
"provider": "anthropic",
"modelId": "claude-3-5-sonnet-20241022",
"maxTokens": 120000,
"temperature": 0.1
}
},
"global": {
"logLevel": "info",
"debug": false,
"defaultSubtasks": 5,
"defaultPriority": "medium"
}
}
State Information (.taskmaster/state.json)
json
At mention
{
"currentTag": "master",
"lastSwitched": "2025-06-15T17:13:09.746Z",
"branchTagMapping": {},
"migrationNoticeShown": true
}
Project Structure The project follows the correct structure as documented:
.taskmaster/ directory exists
config.json
is properly formatted
tasks/
directory contains 54+ task files and tasks.json
docs/ contains the PRD file
state.json
shows "master" as the current tag
Current Tag: master
Steps to Reproduce
- Ensure task-master-ai is installed globally with npm i -g task-master-ai
- Configure .cursor/mcp.json with the correct MCP server setup
- Initialize the project with task-master init (already completed)
- Try to use mcp10_get_task to access a task - this works correctly 5.Try to use mcp10_add_task with the same projectRoot parameter - this fails with the tag error
Expected Behavior
All task-master MCP commands should work consistently, especially since they share the same parameter structure. The projectRoot parameter should be properly interpreted for all commands, not just some of them.
Attempted Solutions
- Reinstalled task-master-ai globally
- Reinitialized the project
- Explicitly set the tag using mcp10_use_tag
- Tried specifying file parameter instead of projectRoot
- Verified configuration files match documentation
Additional Notes
The mcp10_use_tag command works successfully and confirms that the tag "master" exists, yet the mcp10_add_task command fails with a "tag not found" error for the same project path. This suggests inconsistent parameter handling between different MCP commands.
The CLI version of task-master appears to work correctly, but the MCP integration has this inconsistency.
Environment
Operating System: macOS Task Master Version: 0.17.0 MCP Client: Cascade Project Structure: Nx monorepo for software documentation
@szarkowicz this issue is very detailed, thank you, but seems a little bit all over the place, mind modifying it to truly understand your issue ?
I have a same issue.
Error: Tag "{my project root directory}" not found. Version: 0.17.0 Name: task-master-ai Current Tag: master
There seems to be an issue in how commands handle the projectRoot parameter. Commands like get_task, set_task_status, and next_task work correctly, but add_task fails with the error message
Key Points What works: Viewing tasks, updating task status, and viewing the next task What fails: Creating new tasks with add_task Error pattern: The system incorrectly tries to interpret the project path as a tag name Configuration: Task-master is properly installed and initialized (version 0.17.0) Verification: Using use_tag confirms the "master" tag exists, yet add_task still fails with "tag not found"
Hopefully this helps clarify.
Please let me know if you need more information.
Thank You
add_task will be resolved in 0.17.1, releasing shortly, gotta fix some more bugs we run into and we will release that
I'm still getting this with 0.17.1:
⏺ task-master-ai:add_task (MCP)(projectRoot: "/Users/graemef/Development/foo", prompt: "Implement type safety improvements for WebSocket transport layer as documented in
packages/eventsourcing/websocket-transport/TYPE_SAFETY_IMPROVEMENTS.md. This includes: 1) Adding branded types for WebSocket URLs to ensure compile-time validation, 2) Implementing phantom types for state-dependent
operations to prevent invalid method calls, 3) Creating branded types for message size validation, 4) Adding compile-time state machine type safety, and 5) Implementing resource-safe connection management with
guaranteed cleanup. Follow Effect library patterns using pipe() and immutable state management. Start with branded types for URLs and messages, then incrementally add phantom types and state machine safety.",
priority: "medium", title: "Implement WebSocket transport type safety improvements", description: "Enhance the WebSocket transport layer with stronger compile-time type safety to shift validation from runtime to
compile time", details: "The WebSocket transport layer currently relies heavily on runtime validation. This task involves implementing the type safety improvements documented in TYPE_SAFETY_IMPROVEMENTS.md to catch
more errors at compile time and reduce the test surface area. Key improvements include branded types, phantom types for state-dependent operations, and compile-time state machine validation.", testStrategy: "1)
Ensure existing WebSocket tests continue to pass during refactoring, 2) Add type-level tests to verify compile-time constraints, 3) Remove tests that become unnecessary due to compile-time guarantees, 4) Test that
invalid operations are prevented at the type level")
⎿ Error: Tag "/Users/graemef/Development/foo" not found.
Version: 0.17.1
Name: task-master-ai
Current Tag: master
In this instance Claude Code then tried to initialize the project, and tried adding again with a tag and a dependency and that also failed, then it finally tried using the Research tool and it worked.
I'm encountering the same issue.
This bug is caused by a mismatch between the CLI and MCP server in how the tag argument is handled in addTask().
In the MCP server, the following call passes projectRoot as the final argument to addTask(), which is actually meant to be a tag string:
https://github.com/eyaltoledano/claude-task-master/blob/8852831807d6fdbe14271372da32a8e8ab9d7e70/mcp-server/src/core/direct-functions/add-task.js#L129
https://github.com/eyaltoledano/claude-task-master/blob/8852831807d6fdbe14271372da32a8e8ab9d7e70/mcp-server/src/core/direct-functions/add-task.js#L114-L130
But addTask() defines the last parameter as tag:
https://github.com/eyaltoledano/claude-task-master/blob/8852831807d6fdbe14271372da32a8e8ab9d7e70/scripts/modules/task-manager/add-task.js#L92-L102
Passing projectRoot here causes the system to interpret it as a tag, leading to errors like:
Tag "/path/to/project" not found.
I suggest passing null instead to allow addTask() to fall back to context.tag or getCurrentTag().
This issue clearly illustrates the risk of using positional parameters across modules that evolve independently—like the CLI and MCP server. The fact that projectRoot silently matched the tag parameter slot without any immediate type or semantic validation makes this especially hard to catch until runtime.
Had addTask() used a named parameter object (i.e., the RORO pattern—Receive an Object, Return an Object), this kind of silent mismatch would have been impossible. The intent behind each argument would be explicit, and passing unexpected properties like projectRoot would either fail fast or be clearly visible in code review.
RORO helps even with TypeScript, where types don’t prevent argument order errors. Since the project seems to be preparing for TS, adopting RORO early can smooth the transition.
While I understand this change may be larger in scope, I believe applying the RORO pattern to shared internal APIs like addTask() would significantly improve long-term safety, especially as more features, tools and entry points are added.
@mataide we released 0.19, any chance you're having a better experience with it ?
We plan on adding even more fixes regarding this in 0.20