complexity_report

Analyze and display task complexity metrics in a clear, readable format to help developers assess and manage their AI-driven project workflows effectively.

Instructions

Display the complexity analysis report in a readable format

Input Schema

TableJSON Schema

Name	Required	Description	Default
`file`	No	Path to the report file (default: .taskmaster/reports/task-complexity-report.json)
`projectRoot`	Yes	The directory of the project. Must be an absolute path.

Implementation Reference

mcp-server/src/core/direct-functions/complexity-report.js:20-116 (handler)

Core handler function that reads the complexity report file using readComplexityReport, handles errors, and returns structured data or error.

export async function complexityReportDirect(args, log) {
	// Destructure expected args
	const { reportPath } = args;
	try {
		log.info(`Getting complexity report with args: ${JSON.stringify(args)}`);

		// Check if reportPath was provided
		if (!reportPath) {
			log.error('complexityReportDirect called without reportPath');
			return {
				success: false,
				error: { code: 'MISSING_ARGUMENT', message: 'reportPath is required' }
			};
		}

		// Use the provided report path
		log.info(`Looking for complexity report at: ${reportPath}`);

		// Generate cache key based on report path
		const cacheKey = `complexityReport:${reportPath}`;

		// Define the core action function to read the report
		const coreActionFn = async () => {
			try {
				// Enable silent mode to prevent console logs from interfering with JSON response
				enableSilentMode();

				const report = readComplexityReport(reportPath);

				// Restore normal logging
				disableSilentMode();

				if (!report) {
					log.warn(`No complexity report found at ${reportPath}`);
					return {
						success: false,
						error: {
							code: 'FILE_NOT_FOUND_ERROR',
							message: `No complexity report found at ${reportPath}. Run 'analyze-complexity' first.`
						}
					};
				}

				return {
					success: true,
					data: {
						report,
						reportPath
					}
				};
			} catch (error) {
				// Make sure to restore normal logging even if there's an error
				disableSilentMode();

				log.error(`Error reading complexity report: ${error.message}`);
				return {
					success: false,
					error: {
						code: 'READ_ERROR',
						message: error.message
					}
				};
			}
		};

		// Use the caching utility
		try {
			const result = await coreActionFn();
			log.info('complexityReportDirect completed');
			return result;
		} catch (error) {
			// Ensure silent mode is disabled
			disableSilentMode();

			log.error(`Unexpected error during complexityReport: ${error.message}`);
			return {
				success: false,
				error: {
					code: 'UNEXPECTED_ERROR',
					message: error.message
				}
			};
		}
	} catch (error) {
		// Ensure silent mode is disabled if an outer error occurs
		disableSilentMode();

		log.error(`Error in complexityReportDirect: ${error.message}`);
		return {
			success: false,
			error: {
				code: 'UNEXPECTED_ERROR',
				message: error.message
			}
		};
	}
}

mcp-server/src/tools/complexity-report.js:25-35 (schema)

Zod schema defining input parameters: optional file path and required projectRoot.

parameters: z.object({
	file: z
		.string()
		.optional()
		.describe(
			`Path to the report file (default: ${COMPLEXITY_REPORT_FILE})`
		),
	projectRoot: z
		.string()
		.describe('The directory of the project. Must be an absolute path.')
}),

mcp-server/src/tools/complexity-report.js:21-88 (registration)

Function that registers the 'complexity_report' tool with the MCP server using server.addTool, including name, description, parameters schema, and execute handler.

export function registerComplexityReportTool(server) {
	server.addTool({
		name: 'complexity_report',
		description: 'Display the complexity analysis report in a readable format',
		parameters: z.object({
			file: z
				.string()
				.optional()
				.describe(
					`Path to the report file (default: ${COMPLEXITY_REPORT_FILE})`
				),
			projectRoot: z
				.string()
				.describe('The directory of the project. Must be an absolute path.')
		}),
		execute: withNormalizedProjectRoot(async (args, { log, session }) => {
			try {
				log.info(
					`Getting complexity report with args: ${JSON.stringify(args)}`
				);

				const resolvedTag = getCurrentTag(args.projectRoot);

				const pathArgs = {
					projectRoot: args.projectRoot,
					complexityReport: args.file,
					tag: resolvedTag
				};

				const reportPath = findComplexityReportPath(pathArgs, log);
				log.info('Reading complexity report from path: ', reportPath);

				if (!reportPath) {
					return createErrorResponse(
						'No complexity report found. Run task-master analyze-complexity first.'
					);
				}

				const result = await complexityReportDirect(
					{
						reportPath: reportPath
					},
					log
				);

				if (result.success) {
					log.info('Successfully retrieved complexity report');
				} else {
					log.error(
						`Failed to retrieve complexity report: ${result.error.message}`
					);
				}

				return handleApiResult({
					result,
					log: log,
					errorPrefix: 'Error retrieving complexity report',
					projectRoot: args.projectRoot
				});
			} catch (error) {
				log.error(`Error in complexity-report tool: ${error.message}`);
				return createErrorResponse(
					`Failed to retrieve complexity report: ${error.message}`
				);
			}
		})
	});
}

mcp-server/src/tools/tool-registry.js:73-73 (registration)
Tool registry mapping 'complexity_report' to its registration function for dynamic tool setup.
```
complexity_report: registerComplexityReportTool,
```

mcp-server/src/core/task-master-core.js:15-116 (helper)

Re-exports the complexityReportDirect function for use across modules.

import { complexityReportDirect } from './direct-functions/complexity-report.js';
import { copyTagDirect } from './direct-functions/copy-tag.js';
import { deleteTagDirect } from './direct-functions/delete-tag.js';
import { expandAllTasksDirect } from './direct-functions/expand-all-tasks.js';
import { expandTaskDirect } from './direct-functions/expand-task.js';
import { fixDependenciesDirect } from './direct-functions/fix-dependencies.js';
import { initializeProjectDirect } from './direct-functions/initialize-project.js';
import { listTagsDirect } from './direct-functions/list-tags.js';
import { modelsDirect } from './direct-functions/models.js';
import { moveTaskCrossTagDirect } from './direct-functions/move-task-cross-tag.js';
import { moveTaskDirect } from './direct-functions/move-task.js';
import { nextTaskDirect } from './direct-functions/next-task.js';
import { parsePRDDirect } from './direct-functions/parse-prd.js';
import { removeDependencyDirect } from './direct-functions/remove-dependency.js';
import { removeSubtaskDirect } from './direct-functions/remove-subtask.js';
import { removeTaskDirect } from './direct-functions/remove-task.js';
import { renameTagDirect } from './direct-functions/rename-tag.js';
import { researchDirect } from './direct-functions/research.js';
import { scopeDownDirect } from './direct-functions/scope-down.js';
import { scopeUpDirect } from './direct-functions/scope-up.js';
import { setTaskStatusDirect } from './direct-functions/set-task-status.js';
import { updateSubtaskByIdDirect } from './direct-functions/update-subtask-by-id.js';
import { updateTaskByIdDirect } from './direct-functions/update-task-by-id.js';
import { updateTasksDirect } from './direct-functions/update-tasks.js';
import { useTagDirect } from './direct-functions/use-tag.js';
import { validateDependenciesDirect } from './direct-functions/validate-dependencies.js';

// Re-export utility functions
export { findTasksPath } from './utils/path-utils.js';

// Use Map for potential future enhancements like introspection or dynamic dispatch
export const directFunctions = new Map([
	['getCacheStatsDirect', getCacheStatsDirect],
	['parsePRDDirect', parsePRDDirect],
	['updateTasksDirect', updateTasksDirect],
	['updateTaskByIdDirect', updateTaskByIdDirect],
	['updateSubtaskByIdDirect', updateSubtaskByIdDirect],
	['setTaskStatusDirect', setTaskStatusDirect],
	['nextTaskDirect', nextTaskDirect],
	['expandTaskDirect', expandTaskDirect],
	['addTaskDirect', addTaskDirect],
	['addSubtaskDirect', addSubtaskDirect],
	['removeSubtaskDirect', removeSubtaskDirect],
	['analyzeTaskComplexityDirect', analyzeTaskComplexityDirect],
	['clearSubtasksDirect', clearSubtasksDirect],
	['expandAllTasksDirect', expandAllTasksDirect],
	['removeDependencyDirect', removeDependencyDirect],
	['validateDependenciesDirect', validateDependenciesDirect],
	['fixDependenciesDirect', fixDependenciesDirect],
	['complexityReportDirect', complexityReportDirect],
	['addDependencyDirect', addDependencyDirect],
	['removeTaskDirect', removeTaskDirect],
	['initializeProjectDirect', initializeProjectDirect],
	['modelsDirect', modelsDirect],
	['moveTaskDirect', moveTaskDirect],
	['moveTaskCrossTagDirect', moveTaskCrossTagDirect],
	['researchDirect', researchDirect],
	['addTagDirect', addTagDirect],
	['deleteTagDirect', deleteTagDirect],
	['listTagsDirect', listTagsDirect],
	['useTagDirect', useTagDirect],
	['renameTagDirect', renameTagDirect],
	['copyTagDirect', copyTagDirect],
	['scopeUpDirect', scopeUpDirect],
	['scopeDownDirect', scopeDownDirect]
]);

// Re-export all direct function implementations
export {
	getCacheStatsDirect,
	parsePRDDirect,
	updateTasksDirect,
	updateTaskByIdDirect,
	updateSubtaskByIdDirect,
	setTaskStatusDirect,
	nextTaskDirect,
	expandTaskDirect,
	addTaskDirect,
	addSubtaskDirect,
	removeSubtaskDirect,
	analyzeTaskComplexityDirect,
	clearSubtasksDirect,
	expandAllTasksDirect,
	removeDependencyDirect,
	validateDependenciesDirect,
	fixDependenciesDirect,
	complexityReportDirect,
	addDependencyDirect,
	removeTaskDirect,
	initializeProjectDirect,
	modelsDirect,
	moveTaskDirect,
	moveTaskCrossTagDirect,
	researchDirect,
	addTagDirect,
	deleteTagDirect,
	listTagsDirect,
	useTagDirect,
	renameTagDirect,
	copyTagDirect,
	scopeUpDirect,
	scopeDownDirect

Taskmaster