fix: improve docs and command help for analzye-complexity

Co-authored-by: Ralph Khreish <35776126+Crunchyman-ralph@users.noreply.github.com>

.changeset/chore-fix-docs.md

@@ -0,0 +1,5 @@
+---
+"task-master-ai": patch
+---
+
+Improve `analyze-complexity` cli docs and `--research` flag documentation

.changeset/mcp-timeout-configuration.md

@@ -0,0 +1,13 @@
+---
+"task-master-ai": minor
+---
+
+Enhanced Roo Code profile with MCP timeout configuration for improved reliability during long-running AI operations. The Roo profile now automatically configures a 300-second timeout for MCP server operations, preventing timeouts during complex tasks like `parse-prd`, `expand-all`, `analyze-complexity`, and `research` operations. This change also replaces static MCP configuration files with programmatic generation for better maintainability.
+
+**What's New:**
+- 300-second timeout for MCP operations (up from default 60 seconds)
+- Programmatic MCP configuration generation (replaces static asset files)
+- Enhanced reliability for AI-powered operations
+- Consistent with other AI coding assistant profiles
+
+**Migration:** No user action required - existing Roo Code installations will automatically receive the enhanced MCP configuration on next initialization.

.changeset/petite-ideas-grab.md

@@ -0,0 +1,5 @@
+---
+"task-master-ai": patch
+---
+
+Fix Claude Code settings validation for pathToClaudeCodeExecutable

apps/cli/package.json

@@ -9,10 +9,7 @@
 	"exports": {
 		".": "./src/index.ts"
 	},
-	"files": [
+	"files": ["dist", "README.md"],
-		"dist",
-		"README.md"
-	],
 	"scripts": {
 		"typecheck": "tsc --noEmit",
 		"lint": "biome check src",
@@ -45,19 +42,12 @@
 	"engines": {
 		"node": ">=18.0.0"
 	},
-	"keywords": [
+	"keywords": ["task-master", "cli", "task-management", "productivity"],
-		"task-master",
-		"cli",
-		"task-management",
-		"productivity"
-	],
 	"author": "",
 	"license": "MIT",
 	"typesVersions": {
 		"*": {
-			"*": [
+			"*": ["src/*"]
-				"src/*"
-			]
 		}
 	}
 }

apps/docs/capabilities/cli-root-commands.mdx

@@ -156,7 +156,7 @@ sidebarTitle: "CLI Commands"
     # Use an alternative tasks file
     task-master analyze-complexity --file=custom-tasks.json
 
-    # Use Perplexity AI for research-backed complexity analysis
+    # Use your configured research model for research-backed complexity analysis
     task-master analyze-complexity --research
     ```
   </Accordion>

apps/docs/getting-started/quick-start/tasks-quick.mdx

@@ -61,9 +61,25 @@ Task Master can provide a complexity report which can be helpful to read before
 Can you analyze the complexity of our tasks to help me understand which ones need to be broken down further?
 ```
 
+The agent will use the `analyze_project_complexity` MCP tool, or you can run it directly with the CLI command:
+```bash
+task-master analyze-complexity
+```
+
+For more comprehensive analysis using your configured research model, you can use:
+```bash
+task-master analyze-complexity --research
+```
+
+<Tip>
+The `--research` flag uses whatever research model you have configured in `.taskmaster/config.json` (configurable via `task-master models --setup`) for research-backed complexity analysis, providing more informed recommendations.
+</Tip>
+
 You can view the report in a friendly table using:
 ```
 Can you show me the complexity report in a more readable format?
 ```
 
+For more detailed CLI options, see the [Analyze Task Complexity](/docs/capabilities/cli-root-commands#analyze-task-complexity) section.
+
 <Check>Now you are ready to begin [executing tasks](/docs/getting-started/quick-start/execute-quick)</Check>

apps/extension/package.json

@@ -9,17 +9,9 @@
 	"engines": {
 		"vscode": "^1.93.0"
 	},
-	"categories": [
+	"categories": ["AI", "Visualization", "Education", "Other"],
-		"AI",
-		"Visualization",
-		"Education",
-		"Other"
-	],
 	"main": "./dist/extension.js",
-	"activationEvents": [
+	"activationEvents": ["onStartupFinished", "workspaceContains:.taskmaster/**"],
-		"onStartupFinished",
-		"workspaceContains:.taskmaster/**"
-	],
 	"contributes": {
 		"viewsContainers": {
 			"activitybar": [
@@ -147,11 +139,7 @@
 				},
 				"taskmaster.ui.theme": {
 					"type": "string",
-					"enum": [
+					"enum": ["auto", "light", "dark"],
-						"auto",
-						"light",
-						"dark"
-					],
 					"default": "auto",
 					"description": "UI theme preference"
 				},
@@ -212,12 +200,7 @@
 				},
 				"taskmaster.debug.logLevel": {
 					"type": "string",
-					"enum": [
+					"enum": ["error", "warn", "info", "debug"],
-						"error",
-						"warn",
-						"info",
-						"debug"
-					],
 					"default": "info",
 					"description": "Logging level"
 				},

docs/configuration.md

@@ -235,6 +235,60 @@ node scripts/init.js
    - "MCP provider requires session context" → Ensure running in MCP environment
    - See the [MCP Provider Guide](./mcp-provider-guide.md) for detailed troubleshooting
 
+### MCP Timeout Configuration
+
+Long-running AI operations in taskmaster-ai can exceed the default 60-second MCP timeout. Operations like `parse_prd`, `expand_task`, `research`, and `analyze_project_complexity` may take 2-5 minutes to complete.
+
+#### Adding Timeout Configuration
+
+Add a `timeout` parameter to your MCP configuration to extend the timeout limit. The timeout configuration works identically across MCP clients including Cursor, Windsurf, and RooCode:
+
+```json
+{
+  "mcpServers": {
+    "task-master-ai": {
+      "command": "npx",
+      "args": ["-y", "--package=task-master-ai", "task-master-ai"],
+      "timeout": 300,
+      "env": {
+        "ANTHROPIC_API_KEY": "your-anthropic-api-key"
+      }
+    }
+  }
+}
+```
+
+**Configuration Details:**
+- **`timeout: 300`** - Sets timeout to 300 seconds (5 minutes)
+- **Value range**: 1-3600 seconds (1 second to 1 hour)
+- **Recommended**: 300 seconds provides sufficient time for most AI operations
+- **Format**: Integer value in seconds (not milliseconds)
+
+#### Automatic Setup
+
+When adding taskmaster rules for supported editors, the timeout configuration is automatically included:
+
+```bash
+# Automatically includes timeout configuration
+task-master rules add cursor
+task-master rules add roo
+task-master rules add windsurf
+task-master rules add vscode
+```
+
+#### Troubleshooting Timeouts
+
+If you're still experiencing timeout errors:
+
+1. **Verify configuration**: Check that `timeout: 300` is present in your MCP config
+2. **Restart editor**: Restart your editor after making configuration changes
+3. **Increase timeout**: For very complex operations, try `timeout: 600` (10 minutes)
+4. **Check API keys**: Ensure required API keys are properly configured
+
+**Expected behavior:**
+- **Before fix**: Operations fail after 60 seconds with `MCP request timed out after 60000ms`
+- **After fix**: Operations complete successfully within the configured timeout limit
+
 ### Google Vertex AI Configuration
 
 Google Vertex AI is Google Cloud's enterprise AI platform and requires specific configuration:

package-lock.json

@@ -1,12 +1,12 @@
 {
 	"name": "task-master-ai",
-	"version": "0.27.0-rc.2",
+	"version": "0.27.0",
 	"lockfileVersion": 3,
 	"requires": true,
 	"packages": {
 		"": {
 			"name": "task-master-ai",
-			"version": "0.27.0-rc.2",
+			"version": "0.27.0",
 			"license": "MIT WITH Commons-Clause",
 			"workspaces": [
 				"apps/*",
@@ -99,7 +99,7 @@
 		},
 		"apps/cli": {
 			"name": "@tm/cli",
-			"version": "0.27.0-rc.0",
+			"version": "0.27.0",
 			"license": "MIT",
 			"dependencies": {
 				"@tm/core": "*",
@@ -359,13 +359,13 @@
 			}
 		},
 		"apps/docs": {
-			"version": "0.0.2",
+			"version": "0.0.3",
 			"devDependencies": {
 				"mintlify": "^4.2.111"
 			}
 		},
 		"apps/extension": {
-			"version": "0.25.0-rc.0",
+			"version": "0.25.0",
 			"dependencies": {
 				"task-master-ai": "*"
 			},
@@ -31873,7 +31873,7 @@
 		},
 		"packages/build-config": {
 			"name": "@tm/build-config",
-			"version": "1.0.0",
+			"version": "1.0.1",
 			"license": "MIT",
 			"dependencies": {
 				"tsup": "^8.5.0"
@@ -31885,7 +31885,7 @@
 		},
 		"packages/tm-core": {
 			"name": "@tm/core",
-			"version": "0.26.0",
+			"version": "0.26.1",
 			"license": "MIT",
 			"dependencies": {
 				"@supabase/supabase-js": "^2.57.4",

package.json

@@ -9,11 +9,7 @@
 		"task-master-mcp": "dist/mcp-server.js",
 		"task-master-ai": "dist/mcp-server.js"
 	},
-	"workspaces": [
+	"workspaces": ["apps/*", "packages/*", "."],
-		"apps/*",
-		"packages/*",
-		"."
-	],
 	"scripts": {
 		"build": "npm run build:build-config && cross-env NODE_ENV=production tsdown",
 		"dev": "tsdown --watch",
@@ -118,12 +114,7 @@
 	"bugs": {
 		"url": "https://github.com/eyaltoledano/claude-task-master/issues"
 	},
-	"files": [
+	"files": ["dist/**", "README-task-master.md", "README.md", "LICENSE"],
-		"dist/**",
-		"README-task-master.md",
-		"README.md",
-		"LICENSE"
-	],
 	"overrides": {
 		"node-fetch": "^2.6.12",
 		"whatwg-url": "^11.0.0"

packages/build-config/package.json

@@ -12,15 +12,8 @@
 			"import": "./dist/tsdown.base.js"
 		}
 	},
-	"files": [
+	"files": ["dist", "src"],
-		"dist",
+	"keywords": ["build-config", "tsup", "monorepo"],
-		"src"
-	],
-	"keywords": [
-		"build-config",
-		"tsup",
-		"monorepo"
-	],
 	"author": "",
 	"license": "MIT",
 	"scripts": {

packages/tm-core/package.json

@@ -48,18 +48,8 @@
 	"engines": {
 		"node": ">=18.0.0"
 	},
-	"files": [
+	"files": ["src", "README.md", "CHANGELOG.md"],
-		"src",
+	"keywords": ["task-management", "typescript", "ai", "prd", "parser"],
-		"README.md",
-		"CHANGELOG.md"
-	],
-	"keywords": [
-		"task-management",
-		"typescript",
-		"ai",
-		"prd",
-		"parser"
-	],
 	"author": "Task Master AI",
 	"license": "MIT"
 }

scripts/modules/commands.js

@@ -1847,7 +1847,7 @@ function registerCommands(programInstance) {
 		)
 		.option(
 			'-r, --research',
-			'Use Perplexity AI for research-backed complexity analysis'
+			'Use configured research model for research-backed complexity analysis'
 		)
 		.option(
 			'-i, --id <ids>',

scripts/modules/config-manager.js

@@ -310,6 +310,7 @@ function validateProviderModelCombination(providerName, modelId) {
 function validateClaudeCodeSettings(settings) {
 	// Define the base settings schema without commandSpecific first
 	const BaseSettingsSchema = z.object({
+		pathToClaudeCodeExecutable: z.string().optional(),
 		maxTurns: z.number().int().positive().optional(),
 		customSystemPrompt: z.string().optional(),
 		appendSystemPrompt: z.string().optional(),

src/profiles/roo.js

@@ -5,6 +5,40 @@ import { isSilentMode, log } from '../../scripts/modules/utils.js';
 import { createProfile, COMMON_TOOL_MAPPINGS } from './base-profile.js';
 import { ROO_MODES } from '../constants/profiles.js';
 
+// Import the shared MCP configuration helper
+import { formatJSONWithTabs } from '../utils/create-mcp-config.js';
+
+// Roo-specific MCP configuration enhancements
+function enhanceRooMCPConfiguration(mcpPath) {
+	if (!fs.existsSync(mcpPath)) {
+		log('warn', `[Roo] MCP configuration file not found at ${mcpPath}`);
+		return;
+	}
+
+	try {
+		// Read the existing configuration
+		const mcpConfig = JSON.parse(fs.readFileSync(mcpPath, 'utf8'));
+
+		if (mcpConfig.mcpServers && mcpConfig.mcpServers['task-master-ai']) {
+			const server = mcpConfig.mcpServers['task-master-ai'];
+
+			// Add Roo-specific timeout enhancement for long-running AI operations
+			server.timeout = 300;
+
+			// Write the enhanced configuration back
+			fs.writeFileSync(mcpPath, formatJSONWithTabs(mcpConfig) + '\n');
+			log(
+				'debug',
+				`[Roo] Enhanced MCP configuration with timeout at ${mcpPath}`
+			);
+		} else {
+			log('warn', `[Roo] task-master-ai server not found in MCP configuration`);
+		}
+	} catch (error) {
+		log('error', `[Roo] Failed to enhance MCP configuration: ${error.message}`);
+	}
+}
+
 // Lifecycle functions for Roo profile
 function onAddRulesProfile(targetDir, assetsDir) {
 	// Use the provided assets directory to find the roocode directory
@@ -32,6 +66,9 @@ function onAddRulesProfile(targetDir, assetsDir) {
 		}
 	}
 
+	// Note: MCP configuration is now handled by the base profile system
+	// The base profile will call setupMCPConfiguration, and we enhance it in onPostConvert
+
 	for (const mode of ROO_MODES) {
 		const src = path.join(rooModesDir, `rules-${mode}`, `${mode}-rules`);
 		const dest = path.join(targetDir, '.roo', `rules-${mode}`, `${mode}-rules`);
@@ -78,6 +115,15 @@ function onRemoveRulesProfile(targetDir) {
 
 	const rooDir = path.join(targetDir, '.roo');
 	if (fs.existsSync(rooDir)) {
+		// Remove MCP configuration
+		const mcpPath = path.join(rooDir, 'mcp.json');
+		try {
+			fs.rmSync(mcpPath, { force: true });
+			log('debug', `[Roo] Removed MCP configuration from ${mcpPath}`);
+		} catch (err) {
+			log('error', `[Roo] Failed to remove MCP configuration: ${err.message}`);
+		}
+
 		fs.readdirSync(rooDir).forEach((entry) => {
 			if (entry.startsWith('rules-')) {
 				const modeDir = path.join(rooDir, entry);
@@ -101,7 +147,13 @@ function onRemoveRulesProfile(targetDir) {
 }
 
 function onPostConvertRulesProfile(targetDir, assetsDir) {
-	onAddRulesProfile(targetDir, assetsDir);
+	// Enhance the MCP configuration with Roo-specific features after base setup
+	const mcpPath = path.join(targetDir, '.roo', 'mcp.json');
+	try {
+		enhanceRooMCPConfiguration(mcpPath);
+	} catch (err) {
+		log('error', `[Roo] Failed to enhance MCP configuration: ${err.message}`);
+	}
 }
 
 // Create and export roo profile using the base factory
@@ -111,6 +163,7 @@ export const rooProfile = createProfile({
 	url: 'roocode.com',
 	docsUrl: 'docs.roocode.com',
 	toolMappings: COMMON_TOOL_MAPPINGS.ROO_STYLE,
+	mcpConfig: true, // Enable MCP config - we enhance it with Roo-specific features
 	onAdd: onAddRulesProfile,
 	onRemove: onRemoveRulesProfile,
 	onPostConvert: onPostConvertRulesProfile

src/utils/create-mcp-config.js

@@ -262,3 +262,6 @@ export function removeTaskMasterMCPConfiguration(projectRoot, mcpConfigPath) {
 
 	return result;
 }
+
+// Export the formatting function for use by other modules
+export { formatJSONWithTabs };

tests/integration/profiles/roo-init-functionality.test.js

@@ -26,7 +26,7 @@ describe('Roo Profile Initialization Functionality', () => {
 		expect(rooProfile.displayName).toBe('Roo Code');
 		expect(rooProfile.profileDir).toBe('.roo'); // default
 		expect(rooProfile.rulesDir).toBe('.roo/rules'); // default
-		expect(rooProfile.mcpConfig).toBe(true); // default
+		expect(rooProfile.mcpConfig).toBe(true); // now uses standard MCP configuration with Roo enhancements
 	});
 
 	test('roo.js uses custom ROO_STYLE tool mappings', () => {

tests/unit/profiles/mcp-config-validation.test.js

@@ -266,10 +266,10 @@ describe('MCP Configuration Validation', () => {
 			expect(mcpEnabledProfiles).toContain('cursor');
 			expect(mcpEnabledProfiles).toContain('gemini');
 			expect(mcpEnabledProfiles).toContain('opencode');
-			expect(mcpEnabledProfiles).toContain('roo');
 			expect(mcpEnabledProfiles).toContain('vscode');
 			expect(mcpEnabledProfiles).toContain('windsurf');
 			expect(mcpEnabledProfiles).toContain('zed');
+			expect(mcpEnabledProfiles).toContain('roo');
 			expect(mcpEnabledProfiles).not.toContain('cline');
 			expect(mcpEnabledProfiles).not.toContain('codex');
 			expect(mcpEnabledProfiles).not.toContain('trae');
@@ -384,6 +384,7 @@ describe('MCP Configuration Validation', () => {
 			'claude',
 			'cursor',
 			'gemini',
+			'kiro',
 			'opencode',
 			'roo',
 			'windsurf',