Overseer MCP Server

Instructions

Implementation Reference

• src/tools/plan-project.ts:59-222 (handler)

  The main execution handler for the 'overseer.plan_project' tool. It resolves the repository path, infers or uses provided phases, generates and writes PHASES.md and individual PHASE-*.md files, handling overwrites and errors.
  export async function handlePlanProject( args: { repo_root: string; project_name: string; project_summary?: string; overwrite_existing?: boolean; phases?: Array<{ id: string; name: string; description: string; deliverables?: string[]; done_criteria?: string[]; }>; }, phaseManager: PhaseManager ): Promise<{ success: boolean; message: string; phases_discovered: number; phases_created: number; files_written: string[]; files_updated: string[]; errors: string[]; }> { const errors: string[] = []; const filesWritten: string[] = []; const filesUpdated: string[] = []; try { // Resolve repo path let repoPath = args.repo_root; if (!repoPath.startsWith('/')) { // Relative path - resolve from ~/dev repoPath = join(homedir(), 'dev', repoPath); } repoPath = FSUtils.expandPath(repoPath); // Ensure repo exists FSUtils.ensureDir(repoPath); // Check if PHASES.md exists const phasesPath = join(repoPath, 'PHASES.md'); const phasesExist = FSUtils.fileExists(phasesPath); let phases: Array<{ id: string; name: string; description: string; deliverables?: string[]; done_criteria?: string[]; }> = []; // If phases provided explicitly, use them if (args.phases && args.phases.length > 0) { phases = args.phases; } else { // Infer phases from repo structure const analysis = RepoAnalyzer.analyzeRepo(repoPath, { detect_frameworks: true, detect_infrastructure: true, }); if (analysis.suggested_phases.length > 0) { phases = analysis.suggested_phases.map(p => ({ id: p.id, name: p.name, description: p.description, deliverables: p.deliverables, done_criteria: p.done_criteria, })); } else { // Fallback to default phases phases = [ { id: '01', name: 'foundation', description: 'Project foundation and setup', deliverables: ['Project structure', 'README.md', 'Basic configuration'], done_criteria: ['Project structure is in place', 'README.md exists'], }, ]; } } // Read existing phases if they exist and we're not overwriting let existingPhases: any = null; if (phasesExist && !args.overwrite_existing) { try { const existingContent = FSUtils.readFile(phasesPath); // Try to parse as markdown (we'll use a simple approach for now) // For full parsing, we'd use the RepoHandler existingPhases = { exists: true, content: existingContent }; } catch (error) { errors.push(`Failed to read existing PHASES.md: ${error}`); } } // Generate PHASES.md content const now = new Date().toISOString(); const phasesContent = generatePhasesMarkdown( args.project_name, phases, existingPhases ? now : now, // created_at now, // updated_at existingPhases ? 'updated' : 'created' ); // Write PHASES.md try { FSUtils.writeFile(phasesPath, phasesContent); if (phasesExist) { filesUpdated.push(phasesPath); } else { filesWritten.push(phasesPath); } } catch (error) { errors.push(`Failed to write PHASES.md: ${error}`); } // Generate and write PHASE-XX.md files for (const phase of phases) { const phaseFilePath = join(repoPath, `PHASE-${phase.id.padStart(2, '0')}.md`); const phaseContent = generatePhaseFileContent(phase, args.project_name); try { const phaseExists = FSUtils.fileExists(phaseFilePath); FSUtils.writeFile(phaseFilePath, phaseContent); if (phaseExists) { filesUpdated.push(phaseFilePath); } else { filesWritten.push(phaseFilePath); } } catch (error) { errors.push(`Failed to write ${phaseFilePath}: ${error}`); } } const success = errors.length === 0; const message = success ? `${phasesExist ? 'Updated' : 'Created'} project "${args.project_name}" with ${phases.length} phase(s)` : `Partially ${phasesExist ? 'updated' : 'created'} project with ${errors.length} error(s)`; return { success, message, phases_discovered: phases.length, phases_created: phases.length, files_written: filesWritten, files_updated: filesUpdated, errors, }; } catch (error) { const errorMessage = error instanceof Error ? error.message : String(error); return { success: false, message: `Failed to plan project: ${errorMessage}`, phases_discovered: 0, phases_created: 0, files_written: [], files_updated: [], errors: [errorMessage], }; } }
• src/tools/plan-project.ts:8-56 (schema)

  Tool factory function that returns the Tool object definition, including name, description, and detailed inputSchema for validation.
  export function createPlanProjectTool(phaseManager: PhaseManager): Tool { return { name: 'overseer.plan_project', description: 'Plan a new project by creating phase definitions. Creates PHASES.md and PHASE-*.md files in the repository. Can infer phases from project structure if not provided.', inputSchema: { type: 'object', properties: { repo_root: { type: 'string', description: 'Root path of the repository (absolute path or relative to ~/dev)', }, project_name: { type: 'string', description: 'Name of the project', }, project_summary: { type: 'string', description: 'Summary description of the project', }, overwrite_existing: { type: 'boolean', default: false, description: 'If true, overwrite existing PHASES.md. If false, normalize and merge.', }, phases: { type: 'array', items: { type: 'object', properties: { id: { type: 'string' }, name: { type: 'string' }, description: { type: 'string' }, deliverables: { type: 'array', items: { type: 'string' }, }, done_criteria: { type: 'array', items: { type: 'string' }, }, }, required: ['id', 'name', 'description'], }, description: 'Optional: Explicit phase definitions. If not provided, phases will be inferred.', }, }, required: ['repo_root', 'project_name'], }, };
• src/tools/index.ts:50-51 (registration)

  Tool handler registration in the central dispatcher switch statement within handleToolCall function.
  case 'overseer.plan_project': return await handlePlanProject(args, context.phaseManager);
• src/tools/index.ts:25-25 (registration)

  Registration of the tool in the createTools array for inclusion in the tools list.
  createPlanProjectTool(context.phaseManager),
• src/tools/plan-project.ts:224-284 (helper)

  Helper function to generate the content for PHASES.md file from project phases.
  function generatePhasesMarkdown( projectName: string, phases: Array<{ id: string; name: string; description: string; deliverables?: string[]; done_criteria?: string[]; }>, created_at: string, updated_at: string, action: 'created' | 'updated' ): string { const lines: string[] = []; lines.push(`# Project Phases: ${projectName}`); lines.push(''); lines.push('This document tracks the phases of the project.'); lines.push(''); lines.push('## Metadata'); lines.push(''); lines.push(`- **Created**: ${created_at}`); lines.push(`- **Updated**: ${updated_at}`); lines.push(`- **Total Phases**: ${phases.length}`); lines.push(''); lines.push('## Phases'); lines.push(''); phases.forEach((phase) => { lines.push(`### ${phase.id}. ${phase.name}`); lines.push(''); lines.push(`**Status**: pending`); lines.push(`**Description**: ${phase.description}`); lines.push(''); if (phase.deliverables && phase.deliverables.length > 0) { lines.push('**Deliverables**:'); lines.push(''); phase.deliverables.forEach(deliverable => { lines.push(`- ${deliverable}`); }); lines.push(''); } if (phase.done_criteria && phase.done_criteria.length > 0) { lines.push('**Done Criteria**:'); lines.push(''); phase.done_criteria.forEach(criterion => { lines.push(`- [ ] ${criterion}`); }); lines.push(''); } }); lines.push('---'); lines.push(''); lines.push(`*This file is automatically managed by Overseer MCP.*`); lines.push(`*Last ${action}: ${updated_at}*`); return lines.join('\n'); }