Overseer MCP Server

Instructions

Implementation Reference

• src/tools/run-phase.ts:35-236 (handler)

  Main execution handler for overseer.run_phase tool. Processes PHASE-XX.md, checks/completes tasks, creates stubs/TODOs based on aggression_level, updates status and checklists.

  export async function handleRunPhase(
    args: {
      repo_root: string;
      phase_id: string;
      aggression_level?: 'bossmode' | 'normal' | 'conservative';
    },
    phaseManager: PhaseManager
  ): Promise<{
    success: boolean;
    message: string;
    phase_id: string;
    completed_tasks: Array<{
      task: string;
      type: 'deliverable' | 'done_criterion';
      evidence: string;
    }>;
    pending_tasks: Array<{
      task: string;
      type: 'deliverable' | 'done_criterion';
      action_taken: string;
    }>;
    changed_files: string[];
    status: 'in_progress' | 'potentially_complete';
  }> {
    const completedTasks: Array<{ task: string; type: 'deliverable' | 'done_criterion'; evidence: string }> = [];
    const pendingTasks: Array<{ task: string; type: 'deliverable' | 'done_criterion'; action_taken: string }> = [];
    const changedFiles: string[] = [];
  
    try {
      // Resolve repo path
      let repoPath = args.repo_root;
      if (!repoPath.startsWith('/')) {
        repoPath = join(homedir(), 'dev', repoPath);
      }
      repoPath = FSUtils.expandPath(repoPath);
  
      const phaseId = args.phase_id.padStart(2, '0');
      const aggressionLevel = args.aggression_level || 'normal';
  
      // Read PHASES.md using absolute path (handles paths with spaces)
      const repoName = repoPath.split('/').pop() || 'unknown';
      const repoHandler = new RepoHandler();
      const projectPhases = repoHandler.readPhasesIndexFromPath(repoPath);
  
      if (!projectPhases) {
        return {
          success: false,
          message: 'Project not found. Run plan_project first.',
          phase_id: phaseId,
          completed_tasks: [],
          pending_tasks: [],
          changed_files: [],
          status: 'in_progress',
        };
      }
  
      // Find the phase
      const phase = projectPhases.phases.find(p => p.id === phaseId);
      if (!phase) {
        return {
          success: false,
          message: `Phase ${phaseId} not found`,
          phase_id: phaseId,
          completed_tasks: [],
          pending_tasks: [],
          changed_files: [],
          status: 'in_progress',
        };
      }
  
      // Read PHASE-XX.md (handles paths with spaces)
      const phaseFilePath = repoHandler.getPhaseFileByIdFromPath(repoPath, phaseId);
      if (!FSUtils.fileExists(phaseFilePath)) {
        return {
          success: false,
          message: `Phase file PHASE-${phaseId}.md not found`,
          phase_id: phaseId,
          completed_tasks: [],
          pending_tasks: [],
          changed_files: [],
          status: 'in_progress',
        };
      }
  
      let phaseContent = FSUtils.readFile(phaseFilePath);
  
      // Parse deliverables and done_criteria from phase file
      const deliverables: string[] = [];
      const doneCriteria: string[] = [];
  
      // Extract deliverables
      const deliverablesMatch = phaseContent.match(/## Deliverables\s*\n((?:- \[[ x]\] .+\n?)+)/);
      if (deliverablesMatch) {
        const items = deliverablesMatch[1].match(/- \[[ x]\] (.+)/g);
        if (items) {
          items.forEach(item => {
            const text = item.replace(/- \[[ x]\] /, '').trim();
            if (text) deliverables.push(text);
          });
        }
      }
  
      // Extract done criteria
      const doneCriteriaMatch = phaseContent.match(/## Done Criteria\s*\n((?:- \[[ x]\] .+\n?)+)/);
      if (doneCriteriaMatch) {
        const items = doneCriteriaMatch[1].match(/- \[[ x]\] (.+)/g);
        if (items) {
          items.forEach(item => {
            const text = item.replace(/- \[[ x]\] /, '').trim();
            if (text) doneCriteria.push(text);
          });
        }
      }
  
      // Check each deliverable
      for (const deliverable of deliverables) {
        const checked = checkTaskCompletion(deliverable, repoPath, aggressionLevel);
        
        if (checked.completed) {
          completedTasks.push({
            task: deliverable,
            type: 'deliverable',
            evidence: checked.evidence,
          });
          // Update checklist in phase file
          phaseContent = updateChecklistItem(phaseContent, deliverable, true, 'Deliverables');
        } else {
          pendingTasks.push({
            task: deliverable,
            type: 'deliverable',
            action_taken: checked.actionTaken,
          });
          // Create stub/TODO if aggression level allows
          if (aggressionLevel !== 'conservative' && checked.filePath) {
            createStubFile(checked.filePath, deliverable, aggressionLevel);
            changedFiles.push(checked.filePath);
          }
          // Update checklist in phase file
          phaseContent = updateChecklistItem(phaseContent, deliverable, false, 'Deliverables');
        }
      }
  
      // Check each done criterion
      for (const criterion of doneCriteria) {
        const checked = checkTaskCompletion(criterion, repoPath, aggressionLevel);
        
        if (checked.completed) {
          completedTasks.push({
            task: criterion,
            type: 'done_criterion',
            evidence: checked.evidence,
          });
          phaseContent = updateChecklistItem(phaseContent, criterion, true, 'Done Criteria');
        } else {
          pendingTasks.push({
            task: criterion,
            type: 'done_criterion',
            action_taken: checked.actionTaken,
          });
          phaseContent = updateChecklistItem(phaseContent, criterion, false, 'Done Criteria');
        }
      }
  
      // Update phase status to in_progress if not already
      if (phase.status === 'pending') {
        phase.status = 'in_progress';
        phase.started_at = new Date().toISOString();
        repoHandler.writePhasesIndexToPath(repoPath, projectPhases);
        changedFiles.push(join(repoPath, 'PHASES.md'));
      }
  
      // Update phase file
      phaseContent = updatePhaseStatus(phaseContent, 'in_progress');
      FSUtils.writeFile(phaseFilePath, phaseContent);
      changedFiles.push(phaseFilePath);
  
      // Determine overall status
      const allComplete = completedTasks.length === deliverables.length + doneCriteria.length;
      const status = allComplete ? 'potentially_complete' : 'in_progress';
  
      return {
        success: true,
        message: `Phase ${phaseId} execution completed. ${completedTasks.length} tasks complete, ${pendingTasks.length} pending.`,
        phase_id: phaseId,
        completed_tasks: completedTasks,
        pending_tasks: pendingTasks,
        changed_files: changedFiles,
        status,
      };
    } catch (error) {
      const errorMessage = error instanceof Error ? error.message : String(error);
      return {
        success: false,
        message: `Failed to run phase: ${errorMessage}`,
        phase_id: args.phase_id,
        completed_tasks: [],
        pending_tasks: [],
        changed_files: [],
        status: 'in_progress',
      };
    }
  }

• src/tools/run-phase.ts:8-33 (schema)

  Tool schema definition including name, description, and input schema parameters for overseer.run_phase.

  export function createRunPhaseTool(phaseManager: PhaseManager): Tool {
    return {
      name: 'overseer.run_phase',
      description: 'Execute a specific phase of a project. Reads tasks from PHASE-XX.md, checks completion status, and creates TODOs/stubs for incomplete tasks.',
      inputSchema: {
        type: 'object',
        required: ['repo_root', 'phase_id'],
        properties: {
          repo_root: {
            type: 'string',
            description: 'Root path of the repository',
          },
          phase_id: {
            type: 'string',
            description: 'Phase ID (e.g., "01", "02")',
          },
          aggression_level: {
            type: 'string',
            enum: ['bossmode', 'normal', 'conservative'],
            default: 'normal',
            description: 'How aggressively to create files and make changes',
          },
        },
      },
    };
  }

• src/tools/index.ts:22-41 (registration)

  Registration of overseer.run_phase tool via createRunPhaseTool in the tools array returned by createTools.

  export function createTools(context: ToolContext): Tool[] {
    return [
      // Planning tools
      createPlanProjectTool(context.phaseManager),
      createInferPhasesTool(context.configLoader),
      createUpdatePhasesTool(context.phaseManager),
      // Execution tools
      createRunPhaseTool(context.phaseManager),
      createAdvancePhaseTool(context.phaseManager),
      createStatusTool(context.phaseManager),
      // QA tools
      createLintRepoTool(context.configLoader),
      createSyncDocsTool(context.phaseManager),
      createCheckComplianceTool(context.phaseManager),
      // Environment tools
      createEnvMapTool(context.phaseManager),
      createGenerateCiTool(context.phaseManager),
      createSecretsTemplateTool(context.phaseManager),
    ];
  }

• src/tools/index.ts:43-80 (registration)

  Dispatcher in handleToolCall that routes 'overseer.run_phase' calls to the handleRunPhase function.

  export async function handleToolCall(
    name: string,
    args: any,
    context: ToolContext
  ): Promise<any> {
    switch (name) {
      // Planning tools
      case 'overseer.plan_project':
        return await handlePlanProject(args, context.phaseManager);
      case 'overseer.infer_phases':
        return await handleInferPhases(args, context.configLoader);
      case 'overseer.update_phases':
        return await handleUpdatePhases(args, context.phaseManager);
      // Execution tools
      case 'overseer.run_phase':
        return await handleRunPhase(args, context.phaseManager);
      case 'overseer.advance_phase':
        return await handleAdvancePhase(args, context.phaseManager);
      case 'overseer.status':
        return await handleStatus(args, context.phaseManager);
      // QA tools
      case 'overseer.lint_repo':
        return await handleLintRepo(args, context.configLoader);
      case 'overseer.sync_docs':
        return await handleSyncDocs(args, context.phaseManager);
      case 'overseer.check_compliance':
        return await handleCheckCompliance(args, context.phaseManager);
      // Environment tools
      case 'overseer.env_map':
        return await handleEnvMap(args, context.phaseManager);
      case 'overseer.generate_ci':
        return await handleGenerateCi(args, context.phaseManager);
      case 'overseer.secrets_template':
        return await handleSecretsTemplate(args, context.phaseManager);
      default:
        throw new Error(`Unknown tool: ${name}`);
    }
  }

• src/tools/run-phase.ts:236-238 (helper)

  Supporting helper functions for task checking, file stubbing, checklist updates, etc.

  }
  
  function checkTaskCompletion(