Taskmaster

Instructions

Implementation Reference

• mcp-server/src/tools/use-tag.js:19-74 (registration)

  Registers the 'use_tag' MCP tool with server.addTool(), including name, description, input schema (parameters), and execute handler that normalizes project root, finds tasks.json path, calls useTagDirect core logic, and handles the API result.

  export function registerUseTagTool(server) {
  	server.addTool({
  		name: 'use_tag',
  		description: 'Switch to a different tag context for task operations',
  		parameters: z.object({
  			name: z.string().describe('Name of the tag to switch to'),
  			file: z
  				.string()
  				.optional()
  				.describe('Path to the tasks file (default: tasks/tasks.json)'),
  			projectRoot: z
  				.string()
  				.describe('The directory of the project. Must be an absolute path.')
  		}),
  		execute: withNormalizedProjectRoot(async (args, { log, session }) => {
  			try {
  				log.info(`Starting use-tag with args: ${JSON.stringify(args)}`);
  
  				// Use args.projectRoot directly (guaranteed by withNormalizedProjectRoot)
  				let tasksJsonPath;
  				try {
  					tasksJsonPath = findTasksPath(
  						{ projectRoot: args.projectRoot, file: args.file },
  						log
  					);
  				} catch (error) {
  					log.error(`Error finding tasks.json: ${error.message}`);
  					return createErrorResponse(
  						`Failed to find tasks.json: ${error.message}`
  					);
  				}
  
  				// Call the direct function
  				const result = await useTagDirect(
  					{
  						tasksJsonPath: tasksJsonPath,
  						name: args.name,
  						projectRoot: args.projectRoot
  					},
  					log,
  					{ session }
  				);
  
  				return handleApiResult({
  					result,
  					log: log,
  					errorPrefix: 'Error switching tag',
  					projectRoot: args.projectRoot
  				});
  			} catch (error) {
  				log.error(`Error in use-tag tool: ${error.message}`);
  				return createErrorResponse(error.message);
  			}
  		})
  	});
  }

• mcp-server/src/core/direct-functions/use-tag.js:24-103 (handler)

  Core handler function useTagDirect that performs parameter validation, enables silent mode for MCP, calls the underlying tag-management useTag function with JSON output, processes the result, handles errors, and returns structured success/error response.

  export async function useTagDirect(args, log, context = {}) {
  	// Destructure expected args
  	const { tasksJsonPath, name, projectRoot } = args;
  	const { session } = context;
  
  	// Enable silent mode to prevent console logs from interfering with JSON response
  	enableSilentMode();
  
  	// Create logger wrapper using the utility
  	const mcpLog = createLogWrapper(log);
  
  	try {
  		// Check if tasksJsonPath was provided
  		if (!tasksJsonPath) {
  			log.error('useTagDirect called without tasksJsonPath');
  			disableSilentMode();
  			return {
  				success: false,
  				error: {
  					code: 'MISSING_ARGUMENT',
  					message: 'tasksJsonPath is required'
  				}
  			};
  		}
  
  		// Check required parameters
  		if (!name || typeof name !== 'string') {
  			log.error('Missing required parameter: name');
  			disableSilentMode();
  			return {
  				success: false,
  				error: {
  					code: 'MISSING_PARAMETER',
  					message: 'Tag name is required and must be a string'
  				}
  			};
  		}
  
  		log.info(`Switching to tag: ${name}`);
  
  		// Call the useTag function
  		const result = await useTag(
  			tasksJsonPath,
  			name,
  			{}, // options (empty for now)
  			{
  				session,
  				mcpLog,
  				projectRoot
  			},
  			'json' // outputFormat - use 'json' to suppress CLI UI
  		);
  
  		// Restore normal logging
  		disableSilentMode();
  
  		return {
  			success: true,
  			data: {
  				tagName: result.currentTag,
  				switched: result.switched,
  				previousTag: result.previousTag,
  				taskCount: result.taskCount,
  				message: `Successfully switched to tag "${result.currentTag}"`
  			}
  		};
  	} catch (error) {
  		// Make sure to restore normal logging even if there's an error
  		disableSilentMode();
  
  		log.error(`Error in useTagDirect: ${error.message}`);
  		return {
  			success: false,
  			error: {
  				code: error.code || 'USE_TAG_ERROR',
  				message: error.message
  			}
  		};
  	}
  }

• mcp-server/src/tools/tool-registry.js:36-91 (registration)

  Central tool registry maps 'use_tag' tool name to its registerUseTagTool function for dynamic server registration.

  import { registerUseTagTool } from './use-tag.js';
  import { registerValidateDependenciesTool } from './validate-dependencies.js';
  
  // Import TypeScript tools from apps/mcp
  import {
  	registerAutopilotAbortTool,
  	registerAutopilotCommitTool,
  	registerAutopilotCompleteTool,
  	registerAutopilotFinalizeTool,
  	registerAutopilotNextTool,
  	registerAutopilotResumeTool,
  	registerAutopilotStartTool,
  	registerAutopilotStatusTool,
  	registerGenerateTool,
  	registerGetTaskTool,
  	registerGetTasksTool,
  	registerSetTaskStatusTool
  } from '@tm/mcp';
  
  /**
   * Comprehensive tool registry mapping tool names to their registration functions
   * Used for dynamic tool registration and validation
   */
  export const toolRegistry = {
  	initialize_project: registerInitializeProjectTool,
  	models: registerModelsTool,
  	rules: registerRulesTool,
  	parse_prd: registerParsePRDTool,
  	'response-language': registerResponseLanguageTool,
  	analyze_project_complexity: registerAnalyzeProjectComplexityTool,
  	expand_task: registerExpandTaskTool,
  	expand_all: registerExpandAllTool,
  	scope_up_task: registerScopeUpTool,
  	scope_down_task: registerScopeDownTool,
  	get_tasks: registerGetTasksTool,
  	get_task: registerGetTaskTool,
  	next_task: registerNextTaskTool,
  	complexity_report: registerComplexityReportTool,
  	set_task_status: registerSetTaskStatusTool,
  	add_task: registerAddTaskTool,
  	add_subtask: registerAddSubtaskTool,
  	update: registerUpdateTool,
  	update_task: registerUpdateTaskTool,
  	update_subtask: registerUpdateSubtaskTool,
  	remove_task: registerRemoveTaskTool,
  	remove_subtask: registerRemoveSubtaskTool,
  	clear_subtasks: registerClearSubtasksTool,
  	move_task: registerMoveTaskTool,
  	add_dependency: registerAddDependencyTool,
  	remove_dependency: registerRemoveDependencyTool,
  	validate_dependencies: registerValidateDependenciesTool,
  	fix_dependencies: registerFixDependenciesTool,
  	list_tags: registerListTagsTool,
  	add_tag: registerAddTagTool,
  	delete_tag: registerDeleteTagTool,
  	use_tag: registerUseTagTool,

• mcp-server/src/tools/use-tag.js:23-32 (schema)

  Input schema using Zod for validating tool parameters: name (string), file (optional string), projectRoot (string). Note: schema is embedded in registration.

  parameters: z.object({
  	name: z.string().describe('Name of the tag to switch to'),
  	file: z
  		.string()
  		.optional()
  		.describe('Path to the tasks file (default: tasks/tasks.json)'),
  	projectRoot: z
  		.string()
  		.describe('The directory of the project. Must be an absolute path.')
  }),