task-orchestrator-mcp

Instructions

Implementation Reference

• src/task.ts:1027-1078 (handler)

  Core handler function for the startTask tool. Loads tasks, validates parameters and execution order, aggregates criteria from hierarchy, handles leaf node resets, starts tasks along execution path, updates parent statuses, generates messages and hierarchy summary.
  export function startTask(id: string): { aggregated_completion_criteria: string[] aggregated_constraints: string[] hierarchy_summary?: string message?: string started_tasks: Task[] task: Task } { // Load tasks and validate parameters const tasks = readTasks() const task = validateStartTaskParams(id, tasks) // Validate execution order - check if all preceding sibling tasks are completed validateExecutionOrder(task, tasks) // Aggregate completion criteria and constraints from hierarchy const { aggregated_completion_criteria, aggregated_constraints } = aggregateCriteriaFromHierarchy(id, tasks) // Process leaf node reset if necessary const resetLeafTasks = processLeafNodeReset(task, tasks) // Start the main task and update parent statuses const { startedTasks, updatedTask } = startMainTaskAndUpdateParents(id, tasks) // Process execution path for nested task starting const { depth, executionPath } = processExecutionPath(id, tasks, startedTasks) // Generate appropriate message const message = generateStartTaskMessage( task, executionPath, depth, resetLeafTasks, ) // Save changes writeTasks(tasks) // Generate hierarchy summary with changed task IDs const changedTaskIds = new Set<string>(startedTasks.map((t) => t.id)) const hierarchySummary = generateHierarchySummary(tasks, changedTaskIds) return { aggregated_completion_criteria, aggregated_constraints, hierarchy_summary: hierarchySummary.table, message, started_tasks: startedTasks, task: updatedTask, } }
• src/tools.ts:321-372 (registration)

  Registers the 'startTask' tool with the MCP server, providing description, input schema, and a thin wrapper handler that calls the core startTask function and formats the response.
  server.registerTool( "startTask", { description: "Start a task (change status to in_progress)\n\n" + "1. Run this tool to start the task. \n" + "2. When the task is complete, call the `completeTask` tool to complete the task.", inputSchema: { id: z.string().describe("Task ID"), }, }, (args) => { try { const result = startTask(args.id) return { content: [ { text: JSON.stringify(result, null, 2), type: "text", }, ], } } catch (error) { const errorMessage = error instanceof Error ? error.message : "Unknown error" const isExecutionOrderError = errorMessage.includes( "Execution order violation", ) return { content: [ { text: JSON.stringify( { error: { code: isExecutionOrderError ? "EXECUTION_ORDER_VIOLATION" : "TASK_START_ERROR", message: errorMessage, }, }, null, 2, ), type: "text", }, ], isError: true, } } }, )
• src/tools.ts:328-331 (schema)

  Zod input schema for the startTask tool, defining the required 'id' parameter as a string.
  inputSchema: { id: z.string().describe("Task ID"), }, },
• src/task.ts:869-889 (helper)

  Helper function to validate the task ID exists, is not completed, and not already in progress before starting.
  function validateStartTaskParams(id: string, tasks: Task[]): Task { if (!id || typeof id !== "string") { throw new Error("Task ID is required and must be a string") } const task = findTaskById(tasks, id) if (!task) { throw new Error(`Task with id '${id}' not found`) } if (task.status === "done") { throw new Error(`Task '${id}' is already completed`) } if (task.status === "in_progress") { throw new Error(`Task '${id}' is already in progress`) } return task }