@aithr-ai/mcp-server 1.1.7 → 1.2.0

package/index.js

@@ -61,6 +61,12 @@
  * - aether_orchestra_resume: Resume execution
  * - aether_complete_orchestra: Mark complete, generate summary
  * - aether_edit_orchestra: Edit plan without restarting (add/remove/split tasks)
+ * - aether_create_contract: Generate Source of Truth contract before coding
+ *
+ * Workflow Enforcement (v1.2.0):
+ * - aether_orchestra_validate: Check workflow state, prevent skipped steps
+ * - aether_orchestra_checkpoint: Quality gate between phases
+ * - aether_orchestra_guide: Smart guidance on next action to take
  */
 
 const readline = require('readline');
@@ -1099,6 +1105,85 @@ class MCPServer {
           required: ['sessionId', 'action'],
         },
       },
+      {
+        name: 'aether_create_contract',
+        description: 'Generate a Source of Truth contract for the orchestra session. This defines ALL types, schemas, API endpoints, and components BEFORE any code is written. CRITICAL: Run this AFTER setting the plan but BEFORE executing tasks. The contract ensures all agents work from the same definitions and prevents inconsistencies.',
+        inputSchema: {
+          type: 'object',
+          properties: {
+            sessionId: {
+              type: 'string',
+              description: 'Orchestra session ID',
+            },
+            requirements: {
+              type: 'string',
+              description: 'Full project requirements (PRD, feature description, etc.). Be comprehensive - the contract will define everything upfront.',
+            },
+            existingCodeSummary: {
+              type: 'string',
+              description: 'Optional: Summary of existing codebase patterns (auth system, ORM, styling framework) if brownfield project.',
+            },
+          },
+          required: ['sessionId', 'requirements'],
+        },
+      },
+      {
+        name: 'aether_orchestra_validate',
+        description: 'Validate orchestra session state and return required next steps. CALL THIS BEFORE taking any action to ensure you are following the correct workflow. Returns errors if prerequisites are missing and provides the exact tool to call next.',
+        inputSchema: {
+          type: 'object',
+          properties: {
+            sessionId: {
+              type: 'string',
+              description: 'Orchestra session ID (optional - uses latest if not provided)',
+            },
+            intendedAction: {
+              type: 'string',
+              enum: ['execute_task', 'approve', 'complete', 'any'],
+              description: 'What you intend to do next. Validation will check if prerequisites are met.',
+            },
+          },
+        },
+      },
+      {
+        name: 'aether_orchestra_checkpoint',
+        description: 'Create a quality checkpoint to validate phase completion before proceeding. Checks that all tasks in the phase are complete, artifacts exist, and contract compliance is verified. Returns blockers if validation fails.',
+        inputSchema: {
+          type: 'object',
+          properties: {
+            sessionId: {
+              type: 'string',
+              description: 'Orchestra session ID',
+            },
+            phaseNumber: {
+              type: 'number',
+              description: 'Phase number to validate (optional - validates current phase if not provided)',
+            },
+            validateContract: {
+              type: 'boolean',
+              description: 'Check artifacts for contract compliance (default: true)',
+            },
+            autoAdvance: {
+              type: 'boolean',
+              description: 'Automatically advance to next phase if checkpoint passes (default: false)',
+            },
+          },
+          required: ['sessionId'],
+        },
+      },
+      {
+        name: 'aether_orchestra_guide',
+        description: 'Get intelligent guidance on what to do next in the orchestra workflow. Returns the exact tool to call, required parameters, and explanation. USE THIS when you are unsure what step comes next.',
+        inputSchema: {
+          type: 'object',
+          properties: {
+            sessionId: {
+              type: 'string',
+              description: 'Orchestra session ID (optional - uses latest if not provided)',
+            },
+          },
+        },
+      },
     ];
   }
 
@@ -1277,6 +1362,18 @@ class MCPServer {
         case 'aether_edit_orchestra':
           result = await this.editOrchestra(args);
           break;
+        case 'aether_create_contract':
+          result = await this.createContract(args);
+          break;
+        case 'aether_orchestra_validate':
+          result = await this.orchestraValidate(args);
+          break;
+        case 'aether_orchestra_checkpoint':
+          result = await this.orchestraCheckpoint(args);
+          break;
+        case 'aether_orchestra_guide':
+          result = await this.orchestraGuide(args);
+          break;
         default:
           return this.errorResponse(id, -32602, `Unknown tool: ${name}`);
       }
@@ -3467,6 +3564,63 @@ class MCPServer {
     }
   }
 
+  async createContract(args) {
+    const projectId = config.projectId;
+
+    if (!projectId) {
+      return { error: 'No project ID configured. Set AETHER_PROJECT_ID environment variable.' };
+    }
+
+    const { sessionId, requirements, existingCodeSummary } = args;
+
+    if (!sessionId || !requirements) {
+      return { error: 'sessionId and requirements are required' };
+    }
+
+    try {
+      const data = await this.mcpApiCall(
+        `/mcp/projects/${projectId}/orchestra/contract`,
+        'POST',
+        {
+          sessionId,
+          requirements,
+          existingCodeSummary,
+        }
+      );
+
+      if (!data.success) {
+        return {
+          success: false,
+          error: data.error || 'Failed to generate contract',
+        };
+      }
+
+      // Summarize what was generated
+      const contract = data.contract || {};
+      const summary = {
+        types: Object.keys(contract.types?.entities || {}).length,
+        tables: Object.keys(contract.schema?.tables || {}).length,
+        endpoints: Object.keys(contract.api?.endpoints || {}).length,
+        components: Object.keys(contract.components?.components || {}).length,
+      };
+
+      return {
+        success: true,
+        sessionId,
+        contractVersion: data.contractVersion || 1,
+        summary: {
+          ...summary,
+          total: summary.types + summary.tables + summary.endpoints + summary.components,
+        },
+        tokensUsed: data.tokensUsed || 0,
+        message: `Contract generated with ${summary.types} types, ${summary.tables} tables, ${summary.endpoints} endpoints, ${summary.components} components`,
+        hint: 'The contract is now stored in the session. All agents will receive relevant contract sections when executing tasks. Use aether_orchestra_approve to begin execution.',
+      };
+    } catch (e) {
+      return { success: false, error: e.message };
+    }
+  }
+
   async editOrchestra(args) {
     const projectId = config.projectId;
 
@@ -3575,6 +3729,380 @@ class MCPServer {
     }
   }
 
+  /**
+   * Validate orchestra session state and ensure correct workflow
+   */
+  async orchestraValidate(args) {
+    const projectId = config.projectId;
+
+    if (!projectId) {
+      return { error: 'No project ID configured. Set AETHER_PROJECT_ID environment variable.' };
+    }
+
+    const { sessionId, intendedAction } = args;
+
+    try {
+      // Get current session status
+      const data = await this.mcpApiCall(
+        `/mcp/projects/${projectId}/orchestra`,
+        'POST',
+        {
+          action: 'status',
+          sessionId: sessionId || undefined,
+        }
+      );
+
+      if (!data || data.error) {
+        return {
+          valid: false,
+          error: data?.error || 'No orchestra session found',
+          nextStep: {
+            tool: 'aether_start_orchestra',
+            reason: 'Start a new orchestra session first',
+          },
+        };
+      }
+
+      const session = data;
+      const status = session.status;
+      const hasContract = !!session.contract || session.contractVersion > 0;
+      const hasPlan = session.totalTasks > 0;
+
+      // Define the workflow state machine
+      const workflow = {
+        planning: {
+          required: [],
+          missing: !hasPlan ? ['Plan not set'] : [],
+          nextTool: !hasPlan ? 'aether_set_orchestra_plan' : 'aether_create_contract',
+          nextReason: !hasPlan
+            ? 'Set the development plan with phases and tasks'
+            : 'Generate Source of Truth contract before executing',
+        },
+        awaiting_approval: {
+          required: ['plan'],
+          missing: !hasContract ? ['Contract not generated (RECOMMENDED)'] : [],
+          nextTool: hasContract ? 'aether_orchestra_approve' : 'aether_create_contract',
+          nextReason: hasContract
+            ? 'Approve the plan to begin execution'
+            : 'Generate contract for consistent types/schemas across agents (recommended but optional)',
+          canSkipContract: true,
+        },
+        running: {
+          required: ['plan', 'approval'],
+          missing: [],
+          nextTool: 'aether_orchestra_next',
+          nextReason: 'Get next ready tasks to execute',
+        },
+        paused: {
+          required: [],
+          missing: [],
+          nextTool: 'aether_orchestra_resume',
+          nextReason: 'Resume execution to continue',
+        },
+        completed: {
+          required: [],
+          missing: [],
+          nextTool: 'aether_start_orchestra',
+          nextReason: 'Session complete. Start a new session if needed.',
+        },
+      };
+
+      const currentState = workflow[status] || workflow.planning;
+
+      // Validate intended action
+      let actionValid = true;
+      let actionError = null;
+
+      if (intendedAction) {
+        switch (intendedAction) {
+          case 'execute_task':
+            if (status !== 'running') {
+              actionValid = false;
+              actionError = `Cannot execute tasks in "${status}" state. Session must be "running".`;
+            }
+            break;
+          case 'approve':
+            if (status !== 'awaiting_approval' && status !== 'planning') {
+              actionValid = false;
+              actionError = `Cannot approve in "${status}" state. Session must be "awaiting_approval".`;
+            }
+            if (!hasPlan) {
+              actionValid = false;
+              actionError = 'Cannot approve without a plan. Call aether_set_orchestra_plan first.';
+            }
+            break;
+          case 'complete':
+            if (status === 'completed') {
+              actionValid = false;
+              actionError = 'Session is already completed.';
+            }
+            break;
+        }
+      }
+
+      return {
+        valid: actionValid && currentState.missing.length === 0,
+        sessionId: session.sessionId,
+        status,
+        hasPlan,
+        hasContract,
+        totalTasks: session.totalTasks || 0,
+        completedTasks: session.completedTasks || 0,
+        warnings: currentState.missing,
+        intendedAction: intendedAction || 'any',
+        actionValid,
+        actionError,
+        nextStep: {
+          tool: currentState.nextTool,
+          reason: currentState.nextReason,
+          canSkip: currentState.canSkipContract || false,
+        },
+        workflow: `
+📋 ORCHESTRA WORKFLOW:
+1. aether_start_orchestra        → Creates session (status: planning)
+2. aether_set_orchestra_plan     → Defines phases/tasks (status: awaiting_approval)
+3. aether_create_contract        → Generates type contracts [RECOMMENDED]
+4. aether_orchestra_approve      → Begins execution (status: running)
+5. aether_orchestra_next         → Get ready tasks
+6. aether_trigger_generation     → Execute task
+7. aether_report_to_orchestrator → Report completion
+8. Repeat 5-7 until done
+9. aether_complete_orchestra     → Finalize session
+
+Current position: Step ${this.getWorkflowStep(status, hasPlan, hasContract)}
+        `.trim(),
+      };
+    } catch (e) {
+      return { valid: false, error: e.message };
+    }
+  }
+
+  getWorkflowStep(status, hasPlan, hasContract) {
+    if (status === 'planning' && !hasPlan) return '1-2 (need plan)';
+    if (status === 'planning' && hasPlan) return '2-3 (plan set, need contract)';
+    if (status === 'awaiting_approval' && !hasContract) return '3 (awaiting contract)';
+    if (status === 'awaiting_approval' && hasContract) return '4 (ready to approve)';
+    if (status === 'running') return '5-8 (executing tasks)';
+    if (status === 'paused') return '5-8 (paused)';
+    if (status === 'completed') return '9 (done)';
+    return '?';
+  }
+
+  /**
+   * Quality checkpoint between phases
+   */
+  async orchestraCheckpoint(args) {
+    const projectId = config.projectId;
+
+    if (!projectId) {
+      return { error: 'No project ID configured. Set AETHER_PROJECT_ID environment variable.' };
+    }
+
+    const { sessionId, phaseNumber, validateContract, autoAdvance } = args;
+
+    if (!sessionId) {
+      return { error: 'sessionId is required' };
+    }
+
+    try {
+      const data = await this.mcpApiCall(
+        `/mcp/projects/${projectId}/orchestra/checkpoint`,
+        'POST',
+        {
+          sessionId,
+          phaseNumber,
+          validateContract: validateContract !== false,
+          autoAdvance: autoAdvance || false,
+        }
+      );
+
+      return data;
+    } catch (e) {
+      return { success: false, error: e.message };
+    }
+  }
+
+  /**
+   * Smart guidance on what to do next
+   */
+  async orchestraGuide(args) {
+    const projectId = config.projectId;
+
+    if (!projectId) {
+      return { error: 'No project ID configured. Set AETHER_PROJECT_ID environment variable.' };
+    }
+
+    const { sessionId } = args;
+
+    try {
+      // Get session status first
+      const status = await this.mcpApiCall(
+        `/mcp/projects/${projectId}/orchestra`,
+        'POST',
+        {
+          action: 'status',
+          sessionId: sessionId || undefined,
+        }
+      );
+
+      if (!status || status.error) {
+        return {
+          nextTool: 'aether_start_orchestra',
+          parameters: {},
+          explanation: 'No active orchestra session found. Start a new session to begin autonomous development.',
+          example: `aether_start_orchestra({ maxIterations: 100, timeoutMinutes: 480 })`,
+        };
+      }
+
+      const session = status;
+      const sessionStatus = session.status;
+      const hasContract = !!session.contract || session.contractVersion > 0;
+      const hasPlan = session.totalTasks > 0;
+
+      // Determine next action based on state
+      switch (sessionStatus) {
+        case 'planning':
+          if (!hasPlan) {
+            return {
+              nextTool: 'aether_set_orchestra_plan',
+              parameters: {
+                sessionId: session.sessionId,
+                planContent: '<DEVELOPMENT_PLAN.md content>',
+                phases: '<Array of phases with tasks>',
+              },
+              explanation: 'Session created but no plan set. Define the development plan with phases and tasks.',
+              example: `aether_set_orchestra_plan({
+  sessionId: "${session.sessionId}",
+  planContent: "# Development Plan\\n...",
+  phases: [{
+    phaseNumber: 1,
+    title: "Phase 1: Foundation",
+    tasks: [{
+      title: "Create data models",
+      agentId: "architect",
+      contextPrompt: "Design the database schema...",
+      expectedOutput: "Database schema and Drizzle migrations"
+    }]
+  }]
+})`,
+            };
+          }
+          // Has plan but still planning - should set contract
+          return {
+            nextTool: 'aether_create_contract',
+            parameters: {
+              sessionId: session.sessionId,
+              requirements: '<Full project requirements>',
+            },
+            explanation: 'Plan is set. Now generate the Source of Truth contract to ensure consistency across all agents.',
+            example: `aether_create_contract({
+  sessionId: "${session.sessionId}",
+  requirements: "Build a task management app with user auth, projects, and real-time updates..."
+})`,
+            note: 'This step is RECOMMENDED but optional. You can skip to aether_orchestra_approve if needed.',
+          };
+
+        case 'awaiting_approval':
+          if (!hasContract) {
+            return {
+              nextTool: 'aether_create_contract',
+              parameters: {
+                sessionId: session.sessionId,
+                requirements: '<Full project requirements>',
+              },
+              explanation: 'Plan awaiting approval. RECOMMENDED: Generate contract first for type consistency.',
+              alternative: {
+                tool: 'aether_orchestra_approve',
+                note: 'Skip contract and approve directly (not recommended for complex projects)',
+              },
+            };
+          }
+          return {
+            nextTool: 'aether_orchestra_approve',
+            parameters: { sessionId: session.sessionId },
+            explanation: 'Plan and contract ready. Approve to begin autonomous execution.',
+            example: `aether_orchestra_approve({ sessionId: "${session.sessionId}" })`,
+            warning: 'After approval, tasks will execute. Review the plan carefully first.',
+          };
+
+        case 'running':
+          // Check if there are ready tasks
+          if (session.readyTasks > 0) {
+            return {
+              nextTool: 'aether_orchestra_next',
+              parameters: { sessionId: session.sessionId },
+              explanation: `${session.readyTasks} task(s) ready to execute. Get them and trigger generation.`,
+              example: `aether_orchestra_next({ sessionId: "${session.sessionId}", maxTasks: 3 })`,
+              followUp: 'After getting tasks, use aether_trigger_generation with the orchestraContext from each task.',
+            };
+          }
+          // Check for running tasks
+          if (session.runningTasks > 0) {
+            return {
+              nextTool: 'aether_orchestra_status',
+              parameters: { sessionId: session.sessionId, includeReports: true },
+              explanation: `${session.runningTasks} task(s) currently running. Check status and handle any reports.`,
+              example: `aether_orchestra_status({ sessionId: "${session.sessionId}", includeReports: true })`,
+            };
+          }
+          // Check for blocked tasks
+          if (session.blockedTasks > 0) {
+            return {
+              nextTool: 'aether_orchestra_status',
+              parameters: { sessionId: session.sessionId, includeReports: true },
+              explanation: `${session.blockedTasks} task(s) blocked. Review blockers and resolve or edit the plan.`,
+              alternative: {
+                tool: 'aether_edit_orchestra',
+                note: 'Use to modify blocked tasks or add workaround tasks',
+              },
+            };
+          }
+          // All tasks might be complete
+          return {
+            nextTool: 'aether_orchestra_status',
+            parameters: { sessionId: session.sessionId },
+            explanation: 'Check if all tasks are complete. May be ready to finalize.',
+            possibleActions: [
+              { tool: 'aether_complete_orchestra', when: 'All tasks done' },
+              { tool: 'aether_edit_orchestra', when: 'Need to add more tasks' },
+              { tool: 'aether_orchestra_checkpoint', when: 'Validate phase completion' },
+            ],
+          };
+
+        case 'paused':
+          return {
+            nextTool: 'aether_orchestra_resume',
+            parameters: { sessionId: session.sessionId },
+            explanation: 'Session is paused. Resume to continue execution.',
+            alternative: {
+              tool: 'aether_orchestra_status',
+              note: 'Review status before resuming',
+            },
+          };
+
+        case 'completed':
+          return {
+            nextTool: 'aether_start_orchestra',
+            parameters: {},
+            explanation: 'Session completed. Start a new session for more development work.',
+            summary: {
+              completedTasks: session.completedTasks,
+              completedAt: session.completedAt,
+            },
+          };
+
+        default:
+          return {
+            nextTool: 'aether_orchestra_status',
+            parameters: { sessionId: session.sessionId },
+            explanation: `Unknown session status: ${sessionStatus}. Check status for details.`,
+          };
+      }
+    } catch (e) {
+      return { error: e.message };
+    }
+  }
+
   async run() {
     const rl = readline.createInterface({
       input: process.stdin,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aithr-ai/mcp-server",
-  "version": "1.1.7",
+  "version": "1.2.0",
   "description": "MCP server to connect Claude Code to Aether canvas - AI-powered team workspace for software development",
   "main": "index.js",
   "bin": {