task-orchestrator-mcp

Instructions

Implementation Reference

• src/task.ts:492-548 (handler)

  Core handler function that orchestrates task creation: validates parameters, loads existing tasks, creates hierarchical task structure (including subtasks), inserts at correct position, persists changes, and returns created task with message.
  export function createTask(params: { completion_criteria?: string[] constraints?: string[] description?: string insertIndex?: number name: string parentId?: string tasks?: TaskInput[] }): { message?: string; task: Task } { const { completion_criteria, constraints, description = "", insertIndex, name, parentId, tasks: subtasks, } = params // Validate basic parameters validateCreateTaskBasicParams({ completion_criteria, constraints, insertIndex, name, }) // Validate subtasks validateSubtasks(subtasks) // Load and validate parent task const allTasks = readTasks() const parentTask = validateAndFindParentTask(parentId, allTasks) // Create new task object const newTask = createTaskObject( { completion_criteria, constraints, description, name, }, subtasks, ) // Insert task into hierarchy insertTaskIntoHierarchy(newTask, parentTask, allTasks, insertIndex) // Save to storage writeTasks(allTasks) // Generate response message const message = generateCreationMessage(newTask, parentId) return { message, task: newTask } }
• src/tools.ts:29-115 (registration)

  Registers the 'createTask' tool with the MCP server, defining detailed description, Zod input schema for validation, and a wrapper handler that calls the core createTask function with error handling and JSON response formatting.
  // Register createTask tool server.registerTool( "createTask", { description: "Create a new task with optional parent and index positioning.\n\n" + "This tool initiates a new workflow for handling user requests. To manage tasks, you MUST always run this tool first. The workflow is as follows:\n" + "1. Create tasks with the provided name and optional description. Tasks are organized in a hierarchical structure where subtasks can be created by specifying parentId.\n" + "2. Tasks are ordered by their position in the parent's tasks array. Use insertIndex to specify position (defaults to end).\n" + "3. After task creation, you MUST call the `startTask` tool to begin processing the task.\n" + "4. When the task is completed, call the `completeTask` tool with the task ID and resolution details.\n" + "5. If the following task is assigned, execute it by calling the `startTask` tool again.\n" + "6. Repeat this cycle until all tasks are completed.", inputSchema: { completion_criteria: z .array(z.string()) .describe("Completion criteria for the task (optional)") .optional(), constraints: z .array(z.string()) .describe("Constraints for task execution (optional)") .optional(), description: z .string() .describe("Task description (optional)") .optional(), insertIndex: z .number() .describe( "Index position within parent's tasks array (optional, defaults to end of array)", ) .optional(), name: z.string().describe("Task name (required)"), parentId: z .string() .describe("Parent task ID for hierarchical organization (optional)") .optional(), tasks: z .array(TaskInputSchema) .describe("Array of subtasks to create simultaneously (optional)") .optional(), }, }, (args) => { try { const result = createTask( args as { completion_criteria?: string[] constraints?: string[] description?: string insertIndex?: number name: string parentId?: string tasks?: TaskInput[] }, ) return { content: [ { text: JSON.stringify(result, null, 2), type: "text", }, ], } } catch (error) { return { content: [ { text: JSON.stringify( { error: { code: "TASK_CREATION_ERROR", message: error instanceof Error ? error.message : "Unknown error", }, }, null, 2, ), type: "text", }, ], isError: true, } } }, )
• src/tools.ts:42-70 (schema)

  Zod schema defining the input parameters for createTask tool, including hierarchical subtasks support via recursive TaskInputSchema.
  inputSchema: { completion_criteria: z .array(z.string()) .describe("Completion criteria for the task (optional)") .optional(), constraints: z .array(z.string()) .describe("Constraints for task execution (optional)") .optional(), description: z .string() .describe("Task description (optional)") .optional(), insertIndex: z .number() .describe( "Index position within parent's tasks array (optional, defaults to end of array)", ) .optional(), name: z.string().describe("Task name (required)"), parentId: z .string() .describe("Parent task ID for hierarchical organization (optional)") .optional(), tasks: z .array(TaskInputSchema) .describe("Array of subtasks to create simultaneously (optional)") .optional(), },
• src/task.ts:212-248 (helper)

  Helper function for basic parameter validation used within createTask, checking name, arrays of strings for criteria/constraints, and numeric insertIndex.
  function validateCreateTaskBasicParams(params: { completion_criteria?: string[] constraints?: string[] insertIndex?: number name: string }): void { const { completion_criteria, constraints, insertIndex, name } = params if (!name || typeof name !== "string" || name.trim() === "") { throw new Error("Task name is required and must be a non-empty string") } // Validate completion_criteria if provided if (completion_criteria !== undefined) { if (!Array.isArray(completion_criteria)) { throw new Error("Completion criteria must be an array") } if (completion_criteria.some((criteria) => typeof criteria !== "string")) { throw new Error("All completion criteria must be strings") } } // Validate constraints if provided if (constraints !== undefined) { if (!Array.isArray(constraints)) { throw new Error("Constraints must be an array") } if (constraints.some((constraint) => typeof constraint !== "string")) { throw new Error("All constraints must be strings") } } // Validate insertIndex if provided if (insertIndex !== undefined && typeof insertIndex !== "number") { throw new Error("Insert index must be a number") } }