Overseer MCP Server

Instructions

Implementation Reference

• src/tools/advance-phase.ts:29-266 (handler)

  The primary handler function executing the overseer.advance_phase tool logic: checks completion of deliverables and criteria, advances phase status, updates repository files (PHASES.md and PHASE-XX.md).
  export async function handleAdvancePhase( args: { repo_root: string; expected_current_phase: string; }, phaseManager: PhaseManager ): Promise<{ success: boolean; message: string; status: 'advanced' | 'incomplete'; current_phase: { id: string; name: string; status: string; } | null; next_phase: { id: string; name: string; status: string; } | null; missing_items: Array<{ type: 'deliverable' | 'done_criterion'; item: string; reason: string; }>; changes_applied: string[]; }> { const missingItems: Array<{ type: 'deliverable' | 'done_criterion'; item: string; reason: string }> = []; const changesApplied: string[] = []; try { // Resolve repo path let repoPath = args.repo_root; if (!repoPath.startsWith('/')) { repoPath = join(homedir(), 'dev', repoPath); } repoPath = FSUtils.expandPath(repoPath); const expectedPhaseId = args.expected_current_phase.padStart(2, '0'); // 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.', status: 'incomplete', current_phase: null, next_phase: null, missing_items: [], changes_applied: [], }; } // Find the expected phase const currentPhase = projectPhases.phases.find(p => p.id === expectedPhaseId); if (!currentPhase) { return { success: false, message: `Phase ${expectedPhaseId} not found`, status: 'incomplete', current_phase: null, next_phase: null, missing_items: [], changes_applied: [], }; } // Verify this is the current phase if (currentPhase.status !== 'in_progress' && currentPhase.status !== 'active') { return { success: false, message: `Phase ${expectedPhaseId} is not currently active (status: ${currentPhase.status})`, status: 'incomplete', current_phase: { id: currentPhase.id, name: currentPhase.name, status: currentPhase.status, }, next_phase: null, missing_items: [], changes_applied: [], }; } // Read PHASE-XX.md to check deliverables and done criteria (handles paths with spaces) const phaseFilePath = repoHandler.getPhaseFileByIdFromPath(repoPath, expectedPhaseId); if (!FSUtils.fileExists(phaseFilePath)) { return { success: false, message: `Phase file PHASE-${expectedPhaseId}.md not found`, status: 'incomplete', current_phase: { id: currentPhase.id, name: currentPhase.name, status: currentPhase.status, }, next_phase: null, missing_items: [{ type: 'deliverable', item: 'Phase file', reason: 'PHASE-XX.md file missing' }], changes_applied: [], }; } const phaseContent = FSUtils.readFile(phaseFilePath); // Extract deliverables and check completion const deliverablesMatch = phaseContent.match(/## Deliverables\s*\n((?:- \[[ x]\] .+\n?)+)/); if (deliverablesMatch) { const items = deliverablesMatch[1].match(/- \[([ x])\] (.+)/g); if (items) { items.forEach(item => { const checked = item.startsWith('- [x]'); const text = item.replace(/- \[[ x]\] /, '').trim(); if (!checked) { missingItems.push({ type: 'deliverable', item: text, reason: 'Deliverable not marked as complete in checklist', }); } else { // Verify the deliverable actually exists const verification = verifyDeliverableExists(text, repoPath); if (!verification.exists) { missingItems.push({ type: 'deliverable', item: text, reason: verification.reason, }); } } }); } } // Extract done criteria and check completion 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 checked = item.startsWith('- [x]'); const text = item.replace(/- \[[ x]\] /, '').trim(); if (!checked) { missingItems.push({ type: 'done_criterion', item: text, reason: 'Done criterion not marked as complete in checklist', }); } else { // Verify the criterion is actually met const verification = verifyCriterionMet(text, repoPath); if (!verification.met) { missingItems.push({ type: 'done_criterion', item: text, reason: verification.reason, }); } } }); } } // If there are missing items, return incomplete if (missingItems.length > 0) { return { success: true, message: `Phase ${expectedPhaseId} is incomplete. ${missingItems.length} item(s) missing.`, status: 'incomplete', current_phase: { id: currentPhase.id, name: currentPhase.name, status: currentPhase.status, }, next_phase: null, missing_items: missingItems, changes_applied: [], }; } // All items complete - advance the phase // Mark current phase as "locked" (completed) currentPhase.status = 'locked'; currentPhase.completed_at = new Date().toISOString(); changesApplied.push(join(repoPath, 'PHASES.md')); // Update phase file with completion summary const updatedPhaseContent = addCompletionSummary(phaseContent, currentPhase); FSUtils.writeFile(phaseFilePath, updatedPhaseContent); changesApplied.push(phaseFilePath); // Find and activate next phase const currentPhaseIndex = projectPhases.phases.findIndex(p => p.id === expectedPhaseId); let nextPhase = null; if (currentPhaseIndex < projectPhases.phases.length - 1) { nextPhase = projectPhases.phases[currentPhaseIndex + 1]; nextPhase.status = 'in_progress'; nextPhase.started_at = new Date().toISOString(); changesApplied.push(join(repoPath, 'PHASES.md')); } // Write updated PHASES.md using absolute path repoHandler.writePhasesIndexToPath(repoPath, projectPhases); return { success: true, message: `Phase ${expectedPhaseId} advanced successfully. ${nextPhase ? `Next phase ${nextPhase.id} activated.` : 'No more phases.'}`, status: 'advanced', current_phase: { id: currentPhase.id, name: currentPhase.name, status: currentPhase.status, }, next_phase: nextPhase ? { id: nextPhase.id, name: nextPhase.name, status: nextPhase.status, } : null, missing_items: [], changes_applied: changesApplied, }; } catch (error) { const errorMessage = error instanceof Error ? error.message : String(error); return { success: false, message: `Failed to advance phase: ${errorMessage}`, status: 'incomplete', current_phase: null, next_phase: null, missing_items: [], changes_applied: [], }; } }
• src/tools/advance-phase.ts:8-27 (schema)

  Creates the Tool object defining the name, description, and input schema for overseer.advance_phase.
  export function createAdvancePhaseTool(phaseManager: PhaseManager): Tool { return { name: 'overseer.advance_phase', description: 'Advance a phase to the next phase after validating all deliverables are complete. Marks current phase as "locked" and sets next phase as current.', inputSchema: { type: 'object', required: ['repo_root', 'expected_current_phase'], properties: { repo_root: { type: 'string', description: 'Root path of the repository', }, expected_current_phase: { type: 'string', description: 'Phase ID that should currently be active (e.g., "01", "02")', }, }, }, }; }
• src/tools/index.ts:22-41 (registration)

  Registers the advance phase tool in the list of available tools via 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:59-60 (registration)

  Registers the handler for overseer.advance_phase in the tool dispatcher switch statement.
  case 'overseer.advance_phase': return await handleAdvancePhase(args, context.phaseManager);
• src/tools/advance-phase.ts:268-304 (helper)

  Helper function to verify if deliverables (files/directories) actually exist in the repo.
  function verifyDeliverableExists(deliverable: string, repoPath: string): { exists: boolean; reason: string } { // Check for file references const filePattern = /([a-zA-Z0-9_\-./]+\.(md|ts|js|json|yml|yaml|txt|py|java|go|rs|php|rb|ex|exs))/g; const fileMatches = deliverable.match(filePattern); if (fileMatches) { for (const fileRef of fileMatches) { const filePath = join(repoPath, fileRef); if (!FSUtils.fileExists(filePath)) { return { exists: false, reason: `File ${fileRef} does not exist`, }; } } return { exists: true, reason: '' }; } // Check for directory references const dirPattern = /(src|app|lib|tests|docs|config|dist|build)\//; if (dirPattern.test(deliverable)) { const dirMatch = deliverable.match(dirPattern); if (dirMatch) { const dirPath = join(repoPath, dirMatch[1]); if (!FSUtils.dirExists(dirPath)) { return { exists: false, reason: `Directory ${dirMatch[1]}/ does not exist`, }; } } return { exists: true, reason: '' }; } // Generic deliverable - assume exists if we can't verify return { exists: true, reason: '' }; }