README - task-orchestrator by hrishirc

Task Orchestrator

A Model Context Protocol (MCP) server for task orchestration and management. This tool helps break down goals into manageable tasks and track their progress.

How to use

Ideally, the LLM should be able to understand when this MCP tool should be used. But as a sample prompt, something like this can possibly work

"Create a new development goal for me. The goal is to 'Implement user authentication' and it's for the 'my-web-app' repository."

LEMME KNOW of any issues you face by creating a new issue in the 'Discussions' tab at the top.

Features

Create and manage goals
Break down goals into hierarchical tasks
Track task completion status
Support for subtasks and dependency management between parent task and subtasks
Persistent storage using LokiDB

Roadmap

Complex task/goal inter-dependency orchestration
Goal deletion
Completion dispositions
UI for visualization of progress

API Reference

Task ID Naming Convention

Task IDs use a dot-notation (e.g., "1", "1.1", "1.1.1") where each segment represents a level in the hierarchy.

For each new goal, top-level task IDs start with "1" and increment sequentially (e.g., "1", "2", "3").
Subtasks have IDs formed by appending a new segment to their parent's ID (e.g., "1.1" is a subtask of "1").
The combination of goalId and taskId is guaranteed to be unique.

Tools

The server provides the following tools (based on build/index.js):

create_goal

Create a new goal

Parameters:

{
  description: string;  // The goal description
  repoName: string;     // The repository name associated with this goal
}

Sample Input:

{
  "description": "Implement user authentication",
  "repoName": "example/auth-service"
}

Returns: { goalId: number }

add_tasks

Add multiple tasks to a goal. Tasks can be provided in a hierarchical structure. For tasks that are children of existing tasks, use the parentId field. The operation is transactional: either all tasks in the batch succeed, or the entire operation fails.

Parameters:

{
  goalId: number; // ID of the goal to add tasks to (number)
  tasks: Array<{
    title: string; // Title of the task (string)
    description: string; // Detailed description of the task (string)
    parentId?: string | null; // Optional parent task ID for tasks that are children of *existing* tasks. Do not use for new subtasks defined hierarchically within this batch.
    subtasks?: Array<any>; // An array of nested subtask objects to be created under this task.
  }>;
}

Sample Input:

{
  "goalId": 1,
  "tasks": [
    {
      "title": "Design database schema",
      "description": "Define tables for users, roles, and permissions",
      "subtasks": [
        {
          "title": "Create ERD",
          "description": "Draw entity-relationship diagram"
        }
      ]
    },
    {
      "title": "Implement user registration",
      "description": "Create API endpoint for new user signup",
      "parentId": "1"
    }
  ]
}

Returns: HierarchicalTaskResponse[]. HierarchicalTaskResponse objects are simplified and do not include createdAt, updatedAt, or parentId.

remove_tasks
- Soft-delete multiple tasks from a goal. Tasks are marked as deleted but remain in the system. By default, a parent task with subtasks cannot be soft-deleted without explicitly deleting its children. Soft-deleted tasks are excluded by default from get_tasks results unless includeDeletedTasks is set to true.
- Parameters:
```
{
  goalId: number; // ID of the goal to remove tasks from
  taskIds: string[]; // IDs of the tasks to remove (array of strings). Task IDs use dot-notation (e.g., "1", "1.1").
  deleteChildren?: boolean; // Whether to delete child tasks along with the parent (boolean). Defaults to false. If false, attempting to delete a parent task with existing subtasks will throw an error.
}
```
- Sample Input (without deleting children):
```
{
  "goalId": 1,
  "taskIds": ["2", "3"]
}
```
- Sample Input (with deleting children):
```
{
  "goalId": 1,
  "taskIds": ["1"],
  "deleteChildren": true
}
```
- Returns: { removedTasks: TaskResponse[], completedParents: TaskResponse[] }. TaskResponse objects are simplified and do not include createdAt, updatedAt, or parentId.

get_tasks

Get tasks for a goal. Task IDs use a dot-notation (e.g., "1", "1.1", "1.1.1"). When includeSubtasks is specified, responses will return hierarchical task objects. Otherwise, simplified task objects without createdAt, updatedAt, or parentId will be returned.

Parameters:

{
  goalId: number; // ID of the goal to get tasks for (number)
  taskIds?: string[]; // Optional: IDs of tasks to fetch (array of strings). If null or empty, all tasks for the goal will be fetched.
  includeSubtasks?: "none" | "first-level" | "recursive"; // Level of subtasks to include: "none" (only top-level tasks), "first-level" (top-level tasks and their direct children), or "recursive" (all nested subtasks). Defaults to "none".
  includeDeletedTasks?: boolean; // Whether to include soft-deleted tasks in the results (boolean). Defaults to false.
}

Sample Input:

{
  "goalId": 1,
  "includeSubtasks": "recursive",
  "includeDeletedTasks": true
}

Returns: TaskResponse[]. TaskResponse objects are simplified and do not include createdAt, updatedAt, or parentId.

complete_task_status

Mark tasks as complete. By default, a parent task cannot be marked complete if it has incomplete child tasks.

Parameters:

{
  goalId: number; // ID of the goal containing the tasks
  taskIds: string[]; // IDs of the tasks to update (array of strings). Task IDs use dot-notation (e.g., "1", "1.1").
  completeChildren?: boolean; // Whether to complete all child tasks recursively (boolean). Defaults to false. If false, a task can only be completed if all its subtasks are already complete.
}

Sample Input (without completing children):

{
  "goalId": 1,
  "taskIds": ["1", "2"]
}

Sample Input (with completing children):

{
  "goalId": 1,
  "taskIds": ["1"],
  "completeChildren": true
}

Returns: TaskResponse[]. TaskResponse objects are simplified and do not include createdAt, updatedAt, or parentId.

Usage Examples

Creating a Goal and Tasks

// Create a new goal. Its top-level tasks will start with ID "1".
const goal = await callTool('create_goal', {
  description: 'Implement user authentication',
  repoName: 'user/repo'
});

// Add a top-level task
const task1 = await callTool('add_tasks', {
  goalId: goal.goalId,
  tasks: [
    {
      title: 'Set up authentication middleware',
      description: 'Implement JWT-based authentication'
    }
  ]
});
// task1.addedTasks[0].id will be "1"

// Add a subtask to the previously created task "1"
const task2 = await callTool('add_tasks', {
  goalId: goal.goalId,
  tasks: [
    {
      title: 'Create login endpoint',
      description: 'Implement POST /auth/login',
      parentId: "1"  // ParentId must refer to an *already existing* task ID
    }
  ]
});
// task2.addedTasks[0].id will be "1.1"

Managing Task Status

// Mark a parent task as complete, which will also complete its children
await callTool('complete_task_status', {
  goalId: 1,
  taskIds: ["1"],
  completeChildren: true
});

// Get all tasks including subtasks recursively
const allTasks = await callTool('get_tasks', {
  goalId: 1,
  includeSubtasks: "recursive"
});

Removing Tasks

// Attempt to remove a parent task without deleting children (will fail if it has subtasks)
try {
  await callTool('remove_tasks', {
    goalId: 1,
    taskIds: ["1"]
  });
} catch (error) {
  console.error(error.message); // Expected to throw an error if subtasks exist
}

// Remove a parent task and its children
await callTool('remove_tasks', {
  goalId: 1,
  taskIds: ["1"],
  deleteChildren: true
});

Development

Prerequisites

Node.js 18+
pnpm

Setup

Install dependencies:
```
pnpm install
```
Build the project:
```
pnpm build
```
Run tests:
```
pnpm test
```

Project Structure

src/ - Source code
- index.ts - Main server implementation
- storage.ts - Data persistence layer
- types.ts - TypeScript type definitions
- prompts.ts - AI prompt templates
- __tests__/ - Test files

License

MIT