use_tag
Switch task operation contexts by specifying a tag name with Task Master’s tool, enabling focused management of tasks within AI-driven development projects.
Instructions
Switch to a different tag context for task operations
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| file | No | Path to the tasks file (default: tasks/tasks.json) | |
| name | Yes | Name of the tag to switch to | |
| projectRoot | Yes | The directory of the project. Must be an absolute path. |
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); } }) }); }
- 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,
- 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.') }),