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
  }