@allpepper/task-orchestrator 0.1.0

package/src/tools/get-next-status.ts

@@ -0,0 +1,183 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { z } from 'zod';
+import { createSuccessResponse, createErrorResponse } from './registry';
+import { ProjectStatus, FeatureStatus, TaskStatus } from '../domain/types';
+
+/**
+ * Status transition maps for each container type
+ *
+ * Note: CANCELLED and DEFERRED are intentionally non-terminal statuses.
+ * They allow transitions back to earlier workflow stages (BACKLOG/PENDING for tasks,
+ * PLANNING for projects) to support reinstating cancelled or deferred work.
+ */
+const PROJECT_TRANSITIONS: Record<ProjectStatus, ProjectStatus[]> = {
+  [ProjectStatus.PLANNING]: [ProjectStatus.IN_DEVELOPMENT, ProjectStatus.ON_HOLD, ProjectStatus.CANCELLED],
+  [ProjectStatus.IN_DEVELOPMENT]: [ProjectStatus.COMPLETED, ProjectStatus.ON_HOLD, ProjectStatus.CANCELLED],
+  [ProjectStatus.ON_HOLD]: [ProjectStatus.PLANNING, ProjectStatus.IN_DEVELOPMENT, ProjectStatus.CANCELLED],
+  [ProjectStatus.COMPLETED]: [ProjectStatus.ARCHIVED],
+  [ProjectStatus.CANCELLED]: [ProjectStatus.PLANNING], // Non-terminal: allows reinstating cancelled projects
+  [ProjectStatus.ARCHIVED]: []
+};
+
+const FEATURE_TRANSITIONS: Record<FeatureStatus, FeatureStatus[]> = {
+  [FeatureStatus.DRAFT]: [FeatureStatus.PLANNING],
+  [FeatureStatus.PLANNING]: [FeatureStatus.IN_DEVELOPMENT, FeatureStatus.ON_HOLD],
+  [FeatureStatus.IN_DEVELOPMENT]: [FeatureStatus.TESTING, FeatureStatus.BLOCKED, FeatureStatus.ON_HOLD],
+  [FeatureStatus.TESTING]: [FeatureStatus.VALIDATING, FeatureStatus.IN_DEVELOPMENT],
+  [FeatureStatus.VALIDATING]: [FeatureStatus.PENDING_REVIEW, FeatureStatus.IN_DEVELOPMENT],
+  [FeatureStatus.PENDING_REVIEW]: [FeatureStatus.DEPLOYED, FeatureStatus.IN_DEVELOPMENT],
+  [FeatureStatus.BLOCKED]: [FeatureStatus.IN_DEVELOPMENT, FeatureStatus.ON_HOLD],
+  [FeatureStatus.ON_HOLD]: [FeatureStatus.PLANNING, FeatureStatus.IN_DEVELOPMENT],
+  [FeatureStatus.DEPLOYED]: [FeatureStatus.COMPLETED],
+  [FeatureStatus.COMPLETED]: [FeatureStatus.ARCHIVED],
+  [FeatureStatus.ARCHIVED]: []
+};
+
+const TASK_TRANSITIONS: Record<TaskStatus, TaskStatus[]> = {
+  [TaskStatus.BACKLOG]: [TaskStatus.PENDING],
+  [TaskStatus.PENDING]: [TaskStatus.IN_PROGRESS, TaskStatus.BLOCKED, TaskStatus.ON_HOLD, TaskStatus.CANCELLED, TaskStatus.DEFERRED],
+  [TaskStatus.IN_PROGRESS]: [TaskStatus.IN_REVIEW, TaskStatus.TESTING, TaskStatus.BLOCKED, TaskStatus.ON_HOLD, TaskStatus.COMPLETED],
+  [TaskStatus.IN_REVIEW]: [TaskStatus.CHANGES_REQUESTED, TaskStatus.COMPLETED],
+  [TaskStatus.CHANGES_REQUESTED]: [TaskStatus.IN_PROGRESS],
+  [TaskStatus.TESTING]: [TaskStatus.READY_FOR_QA, TaskStatus.IN_PROGRESS],
+  [TaskStatus.READY_FOR_QA]: [TaskStatus.INVESTIGATING, TaskStatus.DEPLOYED, TaskStatus.COMPLETED],
+  [TaskStatus.INVESTIGATING]: [TaskStatus.IN_PROGRESS, TaskStatus.BLOCKED],
+  [TaskStatus.BLOCKED]: [TaskStatus.PENDING, TaskStatus.IN_PROGRESS],
+  [TaskStatus.ON_HOLD]: [TaskStatus.PENDING, TaskStatus.IN_PROGRESS],
+  [TaskStatus.DEPLOYED]: [TaskStatus.COMPLETED],
+  [TaskStatus.COMPLETED]: [], // Terminal: no transitions allowed
+  [TaskStatus.CANCELLED]: [TaskStatus.BACKLOG, TaskStatus.PENDING], // Non-terminal: allows reinstating cancelled tasks
+  [TaskStatus.DEFERRED]: [TaskStatus.BACKLOG, TaskStatus.PENDING] // Non-terminal: allows resuming deferred tasks
+};
+
+/**
+ * Register the get_next_status MCP tool.
+ *
+ * Returns valid next statuses for a container based on its current status.
+ * Note: CANCELLED and DEFERRED statuses can transition back to earlier stages
+ * (BACKLOG/PENDING for tasks, PLANNING for projects) to support work reinstatement.
+ */
+export function registerGetNextStatusTool(server: McpServer): void {
+  server.tool(
+    'get_next_status',
+    'Get valid next statuses for a container. Returns an array of allowed status transitions based on the container type and current status.',
+    {
+      containerType: z.enum(['project', 'feature', 'task']).describe('Type of container (project, feature, or task)'),
+      currentStatus: z.string().describe('Current status of the container')
+    },
+    async (params: any) => {
+      try {
+        const { containerType, currentStatus } = params;
+        const upperStatus = currentStatus.toUpperCase();
+
+        let allowedTransitions: string[] = [];
+
+        switch (containerType) {
+          case 'project':
+            if (upperStatus in PROJECT_TRANSITIONS) {
+              allowedTransitions = PROJECT_TRANSITIONS[upperStatus as ProjectStatus];
+            } else {
+              return {
+                content: [{
+                  type: 'text' as const,
+                  text: JSON.stringify(
+                    createErrorResponse(
+                      `Invalid project status: ${currentStatus}`,
+                      'VALIDATION_ERROR'
+                    ),
+                    null,
+                    2
+                  )
+                }]
+              };
+            }
+            break;
+
+          case 'feature':
+            if (upperStatus in FEATURE_TRANSITIONS) {
+              allowedTransitions = FEATURE_TRANSITIONS[upperStatus as FeatureStatus];
+            } else {
+              return {
+                content: [{
+                  type: 'text' as const,
+                  text: JSON.stringify(
+                    createErrorResponse(
+                      `Invalid feature status: ${currentStatus}`,
+                      'VALIDATION_ERROR'
+                    ),
+                    null,
+                    2
+                  )
+                }]
+              };
+            }
+            break;
+
+          case 'task':
+            if (upperStatus in TASK_TRANSITIONS) {
+              allowedTransitions = TASK_TRANSITIONS[upperStatus as TaskStatus];
+            } else {
+              return {
+                content: [{
+                  type: 'text' as const,
+                  text: JSON.stringify(
+                    createErrorResponse(
+                      `Invalid task status: ${currentStatus}`,
+                      'VALIDATION_ERROR'
+                    ),
+                    null,
+                    2
+                  )
+                }]
+              };
+            }
+            break;
+
+          default:
+            return {
+              content: [{
+                type: 'text' as const,
+                text: JSON.stringify(
+                  createErrorResponse(
+                    `Invalid container type: ${containerType}`,
+                    'VALIDATION_ERROR'
+                  ),
+                  null,
+                  2
+                )
+              }]
+            };
+        }
+
+        return {
+          content: [{
+            type: 'text' as const,
+            text: JSON.stringify(
+              createSuccessResponse(
+                `Found ${allowedTransitions.length} allowed transition(s) from ${upperStatus}`,
+                {
+                  currentStatus: upperStatus,
+                  allowedTransitions,
+                  isTerminal: allowedTransitions.length === 0
+                }
+              ),
+              null,
+              2
+            )
+          }]
+        };
+      } catch (error: any) {
+        return {
+          content: [{
+            type: 'text' as const,
+            text: JSON.stringify(
+              createErrorResponse('Failed to get next status', error.message),
+              null,
+              2
+            )
+          }]
+        };
+      }
+    }
+  );
+}

package/src/tools/get-next-task.ts

@@ -0,0 +1,75 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { z } from 'zod';
+import { createSuccessResponse, createErrorResponse, optionalUuidSchema } from './registry';
+import { getNextTask } from '../repos/dependencies';
+
+/**
+ * Register the get_next_task MCP tool.
+ *
+ * Recommends the next task to work on by priority and complexity,
+ * excluding blocked tasks.
+ */
+export function registerGetNextTaskTool(server: McpServer): void {
+  server.tool(
+    'get_next_task',
+    'Get the next recommended task to work on. Returns the highest priority PENDING task that has no incomplete blocking dependencies. Tasks are prioritized by priority (HIGH > MEDIUM > LOW), then by complexity (simpler first), then by creation time.',
+    {
+      projectId: optionalUuidSchema.describe('Filter by project ID'),
+      featureId: optionalUuidSchema.describe('Filter by feature ID'),
+      priority: z.string().optional().describe('Filter by priority (HIGH, MEDIUM, LOW)')
+    },
+    async (params: any) => {
+      try {
+        const result = getNextTask({
+          projectId: params.projectId,
+          featureId: params.featureId,
+          priority: params.priority
+        });
+
+        if (!result.success) {
+          return {
+            content: [{
+              type: 'text' as const,
+              text: JSON.stringify(createErrorResponse(result.error, result.code), null, 2)
+            }]
+          };
+        }
+
+        if (result.data === null) {
+          return {
+            content: [{
+              type: 'text' as const,
+              text: JSON.stringify(
+                createSuccessResponse('No available tasks found matching the criteria', null),
+                null,
+                2
+              )
+            }]
+          };
+        }
+
+        return {
+          content: [{
+            type: 'text' as const,
+            text: JSON.stringify(
+              createSuccessResponse('Next task retrieved successfully', result.data),
+              null,
+              2
+            )
+          }]
+        };
+      } catch (error: any) {
+        return {
+          content: [{
+            type: 'text' as const,
+            text: JSON.stringify(
+              createErrorResponse('Failed to get next task', error.message),
+              null,
+              2
+            )
+          }]
+        };
+      }
+    }
+  );
+}

package/src/tools/get-tag-usage.ts

@@ -0,0 +1,54 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { z } from 'zod';
+import { createSuccessResponse, createErrorResponse } from './registry';
+import { getTagUsage } from '../repos/tags';
+
+/**
+ * Register the get_tag_usage MCP tool
+ * Gets all entities that use a specific tag
+ */
+export function registerGetTagUsageTool(server: McpServer): void {
+  server.tool(
+    'get_tag_usage',
+    'Get all entities using a specific tag',
+    {
+      tag: z.string().describe('Tag to search for')
+    },
+    async (params) => {
+      try {
+        const result = getTagUsage(params.tag);
+
+        if (!result.success) {
+          return {
+            content: [{
+              type: 'text' as const,
+              text: JSON.stringify(createErrorResponse(result.error), null, 2)
+            }]
+          };
+        }
+
+        return {
+          content: [{
+            type: 'text' as const,
+            text: JSON.stringify(
+              createSuccessResponse('Tag usage retrieved successfully', result.data),
+              null,
+              2
+            )
+          }]
+        };
+      } catch (error: any) {
+        return {
+          content: [{
+            type: 'text' as const,
+            text: JSON.stringify(
+              createErrorResponse(error.message || 'Failed to get tag usage'),
+              null,
+              2
+            )
+          }]
+        };
+      }
+    }
+  );
+}

package/src/tools/index.ts

@@ -0,0 +1,30 @@
+// Container tools
+export { registerQueryContainerTool } from './query-container';
+export { registerManageContainerTool } from './manage-container';
+
+// Section tools
+export { registerQuerySectionsTool } from './query-sections';
+export { registerManageSectionsTool } from './manage-sections';
+
+// Template tools
+export { registerQueryTemplatesTool } from './query-templates';
+export { registerManageTemplateTool } from './manage-template';
+export { registerApplyTemplateTool } from './apply-template';
+
+// Dependency tools
+export { registerQueryDependenciesTool } from './query-dependencies';
+export { registerManageDependencyTool } from './manage-dependency';
+
+// Tag tools
+export { registerListTagsTool } from './list-tags';
+export { registerGetTagUsageTool } from './get-tag-usage';
+export { registerRenameTagTool } from './rename-tag';
+
+// Workflow tools
+export { registerGetNextTaskTool } from './get-next-task';
+export { registerGetBlockedTasksTool } from './get-blocked-tasks';
+export { registerGetNextStatusTool } from './get-next-status';
+export { registerQueryWorkflowStateTool } from './query-workflow-state';
+
+// Setup tool
+export { registerSetupProjectTool } from './setup-project';

package/src/tools/list-tags.ts

@@ -0,0 +1,56 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { z } from 'zod';
+import { createSuccessResponse, createErrorResponse } from './registry';
+import { listTags } from '../repos/tags';
+
+/**
+ * Register the list_tags MCP tool
+ * Lists all tags with their usage counts, optionally filtered by entity type
+ */
+export function registerListTagsTool(server: McpServer): void {
+  server.tool(
+    'list_tags',
+    'List all tags with usage counts',
+    {
+      entityType: z.string().optional().describe('Filter by entity type (PROJECT, FEATURE, TASK)')
+    },
+    async (params) => {
+      try {
+        const result = listTags(
+          params.entityType ? { entityType: params.entityType } : undefined
+        );
+
+        if (!result.success) {
+          return {
+            content: [{
+              type: 'text' as const,
+              text: JSON.stringify(createErrorResponse(result.error), null, 2)
+            }]
+          };
+        }
+
+        return {
+          content: [{
+            type: 'text' as const,
+            text: JSON.stringify(
+              createSuccessResponse('Tags listed successfully', result.data),
+              null,
+              2
+            )
+          }]
+        };
+      } catch (error: any) {
+        return {
+          content: [{
+            type: 'text' as const,
+            text: JSON.stringify(
+              createErrorResponse(error.message || 'Failed to list tags'),
+              null,
+              2
+            )
+          }]
+        };
+      }
+    }
+  );
+}