task-orchestrator-mcp

Instructions

Implementation Reference

• src/task.ts:1515-1561 (handler)

  Core handler function that executes the completeTask tool: validates parameters, marks task as done, auto-completes parents if all subtasks done, generates progress summary and next task recommendation.

  export function completeTask(params: { id: string; resolution: string }): {
    message: string
    next_task_id?: string
    progress_summary: ProgressSummary
  } {
    const { id, resolution } = params
  
    // Validate input parameters
    validateCompleteTaskParams(id, resolution)
  
    // Load tasks and find task to complete
    const tasks = readTasks()
    const taskToComplete = findAndValidateTaskToComplete(id, tasks)
  
    // Validate that task has no incomplete subtasks
    validateNoIncompleteSubtasks(taskToComplete)
  
    // Complete task and handle auto-completion of parents
    const { autoCompletedParents, updatedTask } =
      completeTaskAndAutoCompleteParents(id, resolution, tasks)
  
    // Save changes
    writeTasks(tasks)
  
    // Generate progress summary with updated tasks and changed task IDs
    const changedTaskIds = new Set<string>([
      updatedTask.id,
      ...autoCompletedParents.map((p) => p.id),
    ])
    const progress_summary = generateProgressSummary(tasks, changedTaskIds)
  
    // Find next task to execute
    const nextTask = findNextTask(tasks, updatedTask)
  
    // Generate completion message
    const message = generateCompletionMessage(
      taskToComplete,
      autoCompletedParents,
      nextTask,
    )
  
    return {
      message,
      next_task_id: nextTask?.id,
      progress_summary,
    }
  }

• src/tools.ts:375-419 (registration)

  Registration of the completeTask tool with the MCP server, including description, Zod input schema, and error-handling wrapper that calls the core completeTask function.

  server.registerTool(
    "completeTask",
    {
      description:
        "Complete a task and get the next task to execute.\n" +
        "To start the next task, execute `startTask`.",
      inputSchema: {
        id: z.string().describe("Task ID"),
        resolution: z.string().describe("Task completion resolution/details"),
      },
    },
    (args) => {
      try {
        const result = completeTask(args as { id: string; resolution: string })
        return {
          content: [
            {
              text: JSON.stringify(result, null, 2),
              type: "text",
            },
          ],
        }
      } catch (error) {
        return {
          content: [
            {
              text: JSON.stringify(
                {
                  error: {
                    code: "TASK_COMPLETE_ERROR",
                    message:
                      error instanceof Error ? error.message : "Unknown error",
                  },
                },
                null,
                2,
              ),
              type: "text",
            },
          ],
          isError: true,
        }
      }
    },
  )

• src/tools.ts:381-384 (schema)

  Zod input schema defining parameters for completeTask: task ID (string) and resolution (string).

  inputSchema: {
    id: z.string().describe("Task ID"),
    resolution: z.string().describe("Task completion resolution/details"),
  },

• src/validation.ts:220-235 (helper)

  Helper function to validate completeTask input parameters: ensures id and resolution are non-empty strings.

  export function validateCompleteTaskParams(
    id: string,
    resolution: string,
  ): void {
    if (!id || typeof id !== "string") {
      throw new Error("Task ID is required and must be a string")
    }
  
    if (
      !resolution ||
      typeof resolution !== "string" ||
      resolution.trim() === ""
    ) {
      throw new Error("Resolution is required and must be a non-empty string")
    }
  }