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")
    }
  }