@allpepper/task-orchestrator 0.1.0

package/src/server.ts

@@ -0,0 +1,121 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { WebStandardStreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/webStandardStreamableHttp.js';
+import { runMigrations } from './db/migrate';
+import {
+  registerQueryContainerTool,
+  registerManageContainerTool,
+  registerQuerySectionsTool,
+  registerManageSectionsTool,
+  registerQueryTemplatesTool,
+  registerManageTemplateTool,
+  registerApplyTemplateTool,
+  registerQueryDependenciesTool,
+  registerManageDependencyTool,
+  registerListTagsTool,
+  registerGetTagUsageTool,
+  registerRenameTagTool,
+  registerGetNextTaskTool,
+  registerGetBlockedTasksTool,
+  registerGetNextStatusTool,
+  registerQueryWorkflowStateTool,
+  registerSetupProjectTool,
+} from './tools';
+
+// Initialize database and run migrations
+runMigrations();
+
+// Create MCP server
+const server = new McpServer({
+  name: 'task-orchestrator',
+  version: '2.0.0',
+});
+
+// Register all tools
+registerQueryContainerTool(server);
+registerManageContainerTool(server);
+registerQuerySectionsTool(server);
+registerManageSectionsTool(server);
+registerQueryTemplatesTool(server);
+registerManageTemplateTool(server);
+registerApplyTemplateTool(server);
+registerQueryDependenciesTool(server);
+registerManageDependencyTool(server);
+registerListTagsTool(server);
+registerGetTagUsageTool(server);
+registerRenameTagTool(server);
+registerGetNextTaskTool(server);
+registerGetBlockedTasksTool(server);
+registerGetNextStatusTool(server);
+registerQueryWorkflowStateTool(server);
+registerSetupProjectTool(server);
+
+// Determine transport mode from CLI args or env
+const useHttp = process.argv.includes('--http') || process.env.TRANSPORT === 'http';
+
+if (useHttp) {
+  const port = parseInt(process.env.PORT || '3100', 10);
+
+  // Map of session ID -> transport for stateful sessions
+  const sessions = new Map<string, WebStandardStreamableHTTPServerTransport>();
+
+  Bun.serve({
+    port,
+    fetch: async (req: Request) => {
+      const url = new URL(req.url);
+
+      if (url.pathname !== '/mcp') {
+        return new Response('Not Found', { status: 404 });
+      }
+
+      // Check for existing session
+      const sessionId = req.headers.get('mcp-session-id');
+      if (sessionId && sessions.has(sessionId)) {
+        return sessions.get(sessionId)!.handleRequest(req);
+      }
+
+      // New session — create transport and connect a fresh server instance
+      const transport = new WebStandardStreamableHTTPServerTransport({
+        sessionIdGenerator: () => crypto.randomUUID(),
+        onsessioninitialized: (id) => {
+          sessions.set(id, transport);
+        },
+        onsessionclosed: (id) => {
+          sessions.delete(id);
+        },
+      });
+
+      const sessionServer = new McpServer({
+        name: 'task-orchestrator',
+        version: '2.0.0',
+      });
+
+      registerQueryContainerTool(sessionServer);
+      registerManageContainerTool(sessionServer);
+      registerQuerySectionsTool(sessionServer);
+      registerManageSectionsTool(sessionServer);
+      registerQueryTemplatesTool(sessionServer);
+      registerManageTemplateTool(sessionServer);
+      registerApplyTemplateTool(sessionServer);
+      registerQueryDependenciesTool(sessionServer);
+      registerManageDependencyTool(sessionServer);
+      registerListTagsTool(sessionServer);
+      registerGetTagUsageTool(sessionServer);
+      registerRenameTagTool(sessionServer);
+      registerGetNextTaskTool(sessionServer);
+      registerGetBlockedTasksTool(sessionServer);
+      registerGetNextStatusTool(sessionServer);
+      registerQueryWorkflowStateTool(sessionServer);
+      registerSetupProjectTool(sessionServer);
+
+      await sessionServer.connect(transport);
+      return transport.handleRequest(req);
+    },
+  });
+
+  console.error(`Task Orchestrator MCP listening on http://localhost:${port}/mcp`);
+} else {
+  // Default: stdio transport
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+}

package/src/services/index.ts

@@ -0,0 +1,2 @@
+export * from './status-validator';
+export * from './workflow';

package/src/services/status-validator.ts

@@ -0,0 +1,100 @@
+import { ProjectStatus, FeatureStatus, TaskStatus } from '../domain/types';
+
+// Valid statuses per container type
+const PROJECT_STATUSES = Object.values(ProjectStatus);
+const FEATURE_STATUSES = Object.values(FeatureStatus);
+const TASK_STATUSES = Object.values(TaskStatus);
+
+/**
+ * Status transition maps
+ *
+ * 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<string, string[]> = {
+  PLANNING: ['IN_DEVELOPMENT', 'ON_HOLD', 'CANCELLED'],
+  IN_DEVELOPMENT: ['COMPLETED', 'ON_HOLD', 'CANCELLED'],
+  ON_HOLD: ['PLANNING', 'IN_DEVELOPMENT', 'CANCELLED'],
+  COMPLETED: ['ARCHIVED'],
+  CANCELLED: ['PLANNING'], // Non-terminal: allows reinstating cancelled projects
+  ARCHIVED: [],
+};
+
+const FEATURE_TRANSITIONS: Record<string, string[]> = {
+  DRAFT: ['PLANNING'],
+  PLANNING: ['IN_DEVELOPMENT', 'ON_HOLD'],
+  IN_DEVELOPMENT: ['TESTING', 'BLOCKED', 'ON_HOLD'],
+  TESTING: ['VALIDATING', 'IN_DEVELOPMENT'],
+  VALIDATING: ['PENDING_REVIEW', 'IN_DEVELOPMENT'],
+  PENDING_REVIEW: ['DEPLOYED', 'IN_DEVELOPMENT'],
+  BLOCKED: ['IN_DEVELOPMENT', 'ON_HOLD'],
+  ON_HOLD: ['PLANNING', 'IN_DEVELOPMENT'],
+  DEPLOYED: ['COMPLETED'],
+  COMPLETED: ['ARCHIVED'],
+  ARCHIVED: [],
+};
+
+const TASK_TRANSITIONS: Record<string, string[]> = {
+  BACKLOG: ['PENDING'],
+  PENDING: ['IN_PROGRESS', 'BLOCKED', 'ON_HOLD', 'CANCELLED', 'DEFERRED'],
+  IN_PROGRESS: ['IN_REVIEW', 'TESTING', 'BLOCKED', 'ON_HOLD', 'COMPLETED'],
+  IN_REVIEW: ['CHANGES_REQUESTED', 'COMPLETED'],
+  CHANGES_REQUESTED: ['IN_PROGRESS'],
+  TESTING: ['READY_FOR_QA', 'IN_PROGRESS'],
+  READY_FOR_QA: ['INVESTIGATING', 'DEPLOYED', 'COMPLETED'],
+  INVESTIGATING: ['IN_PROGRESS', 'BLOCKED'],
+  BLOCKED: ['PENDING', 'IN_PROGRESS'],
+  ON_HOLD: ['PENDING', 'IN_PROGRESS'],
+  DEPLOYED: ['COMPLETED'],
+  COMPLETED: [], // Terminal: no transitions allowed
+  CANCELLED: ['BACKLOG', 'PENDING'], // Non-terminal: allows reinstating cancelled tasks
+  DEFERRED: ['BACKLOG', 'PENDING'], // Non-terminal: allows resuming deferred tasks
+};
+
+// Terminal statuses (no transitions out)
+const TERMINAL_STATUSES: Record<string, string[]> = {
+  project: ['ARCHIVED'],
+  feature: ['ARCHIVED'],
+  task: ['COMPLETED'],
+};
+
+export type ContainerType = 'project' | 'feature' | 'task';
+
+export function isValidStatus(containerType: ContainerType, status: string): boolean {
+  switch (containerType) {
+    case 'project': return PROJECT_STATUSES.includes(status as ProjectStatus);
+    case 'feature': return FEATURE_STATUSES.includes(status as FeatureStatus);
+    case 'task': return TASK_STATUSES.includes(status as TaskStatus);
+  }
+}
+
+export function getValidStatuses(containerType: ContainerType): string[] {
+  switch (containerType) {
+    case 'project': return [...PROJECT_STATUSES];
+    case 'feature': return [...FEATURE_STATUSES];
+    case 'task': return [...TASK_STATUSES];
+  }
+}
+
+export function getTransitions(containerType: ContainerType): Record<string, string[]> {
+  switch (containerType) {
+    case 'project': return PROJECT_TRANSITIONS;
+    case 'feature': return FEATURE_TRANSITIONS;
+    case 'task': return TASK_TRANSITIONS;
+  }
+}
+
+export function getAllowedTransitions(containerType: ContainerType, currentStatus: string): string[] {
+  const transitions = getTransitions(containerType);
+  return transitions[currentStatus] || [];
+}
+
+export function isValidTransition(containerType: ContainerType, from: string, to: string): boolean {
+  const allowed = getAllowedTransitions(containerType, from);
+  return allowed.includes(to);
+}
+
+export function isTerminalStatus(containerType: ContainerType, status: string): boolean {
+  return TERMINAL_STATUSES[containerType]?.includes(status) ?? false;
+}

package/src/services/workflow.ts

@@ -0,0 +1,104 @@
+import type { ContainerType } from './status-validator';
+import { getAllowedTransitions, isTerminalStatus, isValidStatus } from './status-validator';
+import { getProject } from '../repos/projects';
+import { getFeature } from '../repos/features';
+import { getTask } from '../repos/tasks';
+import { getDependencies } from '../repos/dependencies';
+import { searchTasks } from '../repos/tasks';
+import type { Result } from '../domain/types';
+import { ok, err } from '../repos/base';
+
+export interface WorkflowState {
+  containerType: ContainerType;
+  id: string;
+  currentStatus: string;
+  allowedTransitions: string[];
+  isTerminal: boolean;
+  cascadeEvents?: string[];
+  blockingDependencies?: Array<{
+    taskId: string;
+    taskTitle: string;
+    status: string;
+  }>;
+}
+
+export function getWorkflowState(containerType: ContainerType, id: string): Result<WorkflowState> {
+  // 1. Get entity
+  let currentStatus: string;
+
+  switch (containerType) {
+    case 'project': {
+      const result = getProject(id);
+      if (!result.success) return err(result.error, result.code);
+      currentStatus = result.data.status;
+      break;
+    }
+    case 'feature': {
+      const result = getFeature(id);
+      if (!result.success) return err(result.error, result.code);
+      currentStatus = result.data.status;
+      break;
+    }
+    case 'task': {
+      const result = getTask(id);
+      if (!result.success) return err(result.error, result.code);
+      currentStatus = result.data.status;
+      break;
+    }
+  }
+
+  // 2. Get allowed transitions
+  const allowedTransitions = getAllowedTransitions(containerType, currentStatus);
+  const isTerminal = isTerminalStatus(containerType, currentStatus);
+
+  // 3. Build state
+  const state: WorkflowState = {
+    containerType,
+    id,
+    currentStatus,
+    allowedTransitions,
+    isTerminal,
+  };
+
+  // 4. For tasks, check blocking dependencies
+  if (containerType === 'task') {
+    const depsResult = getDependencies(id, 'dependents');
+    if (depsResult.success) {
+      const blockers = depsResult.data
+        .filter(d => d.type === 'BLOCKS')
+        .map(d => {
+          const taskResult = getTask(d.fromTaskId);
+          if (taskResult.success) {
+            return {
+              taskId: d.fromTaskId,
+              taskTitle: taskResult.data.title,
+              status: taskResult.data.status,
+            };
+          }
+          return { taskId: d.fromTaskId, taskTitle: 'Unknown', status: 'UNKNOWN' };
+        })
+        .filter(b => b.status !== 'COMPLETED' && b.status !== 'CANCELLED');
+
+      if (blockers.length > 0) {
+        state.blockingDependencies = blockers;
+      }
+    }
+  }
+
+  // 5. Detect cascade events for features/projects
+  if (containerType === 'feature') {
+    const tasksResult = searchTasks({ featureId: id });
+    if (tasksResult.success && tasksResult.data.length > 0) {
+      const events: string[] = [];
+      const allCompleted = tasksResult.data.every(t => t.status === 'COMPLETED' || t.status === 'CANCELLED');
+      const anyStarted = tasksResult.data.some(t => t.status !== 'PENDING' && t.status !== 'BACKLOG');
+
+      if (allCompleted) events.push('all_tasks_complete');
+      if (anyStarted) events.push('first_task_started');
+
+      if (events.length > 0) state.cascadeEvents = events;
+    }
+  }
+
+  return ok(state);
+}

package/src/tools/apply-template.ts

@@ -0,0 +1,129 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { z } from 'zod';
+import { createSuccessResponse, createErrorResponse, uuidSchema } from './registry';
+import { applyTemplate } from '../repos/templates';
+
+/**
+ * Registers the `apply_template` MCP tool.
+ *
+ * Applies a template to an entity (PROJECT, FEATURE, or TASK),
+ * creating sections from the template's section definitions.
+ */
+export function registerApplyTemplateTool(server: McpServer): void {
+  server.tool(
+    'apply_template',
+    'Apply a template to an entity (PROJECT, FEATURE, or TASK), creating sections from the template',
+    {
+      templateId: uuidSchema,
+      entityType: z.enum(['PROJECT', 'FEATURE', 'TASK']),
+      entityId: uuidSchema
+    },
+    async (params: any) => {
+      try {
+        // Validate required parameters
+        if (!params.templateId) {
+          return {
+            content: [{
+              type: 'text' as const,
+              text: JSON.stringify(
+                createErrorResponse('Template ID is required'),
+                null,
+                2
+              )
+            }]
+          };
+        }
+
+        if (!params.entityType) {
+          return {
+            content: [{
+              type: 'text' as const,
+              text: JSON.stringify(
+                createErrorResponse('Entity type is required'),
+                null,
+                2
+              )
+            }]
+          };
+        }
+
+        if (!params.entityId) {
+          return {
+            content: [{
+              type: 'text' as const,
+              text: JSON.stringify(
+                createErrorResponse('Entity ID is required'),
+                null,
+                2
+              )
+            }]
+          };
+        }
+
+        // Validate entity type
+        const validEntityTypes = ['PROJECT', 'FEATURE', 'TASK'];
+        if (!validEntityTypes.includes(params.entityType)) {
+          return {
+            content: [{
+              type: 'text' as const,
+              text: JSON.stringify(
+                createErrorResponse(
+                  `Invalid entity type. Must be one of: ${validEntityTypes.join(', ')}`
+                ),
+                null,
+                2
+              )
+            }]
+          };
+        }
+
+        const result = applyTemplate(
+          params.templateId,
+          params.entityType,
+          params.entityId
+        );
+
+        if (!result.success) {
+          return {
+            content: [{
+              type: 'text' as const,
+              text: JSON.stringify(
+                createErrorResponse(result.error || 'Failed to apply template'),
+                null,
+                2
+              )
+            }]
+          };
+        }
+
+        return {
+          content: [{
+            type: 'text' as const,
+            text: JSON.stringify(
+              createSuccessResponse(
+                `Template applied successfully. Created ${result.data.length} section(s)`,
+                result.data
+              ),
+              null,
+              2
+            )
+          }]
+        };
+      } catch (error: any) {
+        return {
+          content: [{
+            type: 'text' as const,
+            text: JSON.stringify(
+              createErrorResponse(
+                'Internal error',
+                error.message || 'Unknown error occurred'
+              ),
+              null,
+              2
+            )
+          }]
+        };
+      }
+    }
+  );
+}

package/src/tools/get-blocked-tasks.ts

@@ -0,0 +1,63 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { z } from 'zod';
+import { createSuccessResponse, createErrorResponse, optionalUuidSchema } from './registry';
+import { getBlockedTasks } from '../repos/dependencies';
+
+/**
+ * Register the get_blocked_tasks MCP tool.
+ *
+ * Returns all blocked tasks, either with status 'BLOCKED' or tasks
+ * that have incomplete blocking dependencies.
+ */
+export function registerGetBlockedTasksTool(server: McpServer): void {
+  server.tool(
+    'get_blocked_tasks',
+    'Get all blocked tasks. Returns tasks that either have status BLOCKED or have incomplete blocking dependencies (tasks that block them but are not completed). Results are sorted by priority (descending) then creation time (ascending).',
+    {
+      projectId: optionalUuidSchema.describe('Filter by project ID'),
+      featureId: optionalUuidSchema.describe('Filter by feature ID')
+    },
+    async (params: any) => {
+      try {
+        const result = getBlockedTasks({
+          projectId: params.projectId,
+          featureId: params.featureId
+        });
+
+        if (!result.success) {
+          return {
+            content: [{
+              type: 'text' as const,
+              text: JSON.stringify(createErrorResponse(result.error, result.code), null, 2)
+            }]
+          };
+        }
+
+        return {
+          content: [{
+            type: 'text' as const,
+            text: JSON.stringify(
+              createSuccessResponse(
+                `Found ${result.data.length} blocked task(s)`,
+                result.data
+              ),
+              null,
+              2
+            )
+          }]
+        };
+      } catch (error: any) {
+        return {
+          content: [{
+            type: 'text' as const,
+            text: JSON.stringify(
+              createErrorResponse('Failed to get blocked tasks', error.message),
+              null,
+              2
+            )
+          }]
+        };
+      }
+    }
+  );
+}