task-orchestrator-mcp

Instructions

Implementation Reference

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

  Core handler function implementing the startTask tool logic: loads tasks, validates parameters and execution order, aggregates criteria and constraints from hierarchy, handles leaf node resets and execution path auto-starting, updates parent statuses, generates response message 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:320-372 (registration)

  Registers the "startTask" MCP tool with the server, providing description, Zod input schema for task ID, and error-handling wrapper that calls the core startTask function and returns JSON response.
  // Register startTask tool 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 definition for the startTask tool: requires a single 'id' parameter of type string.
  inputSchema: { id: z.string().describe("Task ID"), }, },
• src/task.ts:869-889 (helper)

  Helper function to validate startTask parameters: checks ID format, task existence, and prevents starting already in_progress or done tasks.
  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 }