Overseer MCP Server

Instructions

Implementation Reference

• src/tools/infer-phases.ts:40-126 (handler)

  The handler function executing the tool's core logic: resolves repo path, analyzes using RepoAnalyzer, formats suggested phases and detected patterns.

  export async function handleInferPhases(
    args: {
      repo_root: string;
      options?: {
        detect_frameworks?: boolean;
        detect_infrastructure?: boolean;
      };
    },
    configLoader: ConfigLoader
  ): Promise<{
    success: boolean;
    suggested_phases: Array<{
      id: string;
      name: string;
      description: string;
      deliverables: string[];
      done_criteria: string[];
      confidence: number;
      reason: string;
      detected_patterns: string[];
    }>;
    detected_frameworks: string[];
    detected_patterns: Array<{
      type: string;
      name: string;
      confidence: number;
      evidence: string[];
    }>;
  }> {
    try {
      // Resolve repo path
      let repoPath = args.repo_root;
      if (!repoPath.startsWith('/')) {
        repoPath = join(homedir(), 'dev', repoPath);
      }
      repoPath = FSUtils.expandPath(repoPath);
  
      if (!FSUtils.dirExists(repoPath)) {
        return {
          success: false,
          suggested_phases: [],
          detected_frameworks: [],
          detected_patterns: [],
        };
      }
  
      // Analyze repository
      const analysis = RepoAnalyzer.analyzeRepo(repoPath, args.options);
  
      // Extract framework names
      const frameworkNames = analysis.patterns
        .filter(p => p.type === 'framework')
        .map(p => p.name);
  
      // Format suggested phases
      const suggestedPhases = analysis.suggested_phases.map(phase => ({
        id: phase.id,
        name: phase.name,
        description: phase.description,
        deliverables: phase.deliverables,
        done_criteria: phase.done_criteria,
        confidence: phase.confidence,
        reason: phase.reason,
        detected_patterns: phase.detected_patterns,
      }));
  
      return {
        success: true,
        suggested_phases: suggestedPhases,
        detected_frameworks: frameworkNames,
        detected_patterns: analysis.patterns.map(p => ({
          type: p.type,
          name: p.name,
          confidence: p.confidence,
          evidence: p.evidence,
        })),
      };
    } catch (error) {
      const errorMessage = error instanceof Error ? error.message : String(error);
      return {
        success: false,
        suggested_phases: [],
        detected_frameworks: [],
        detected_patterns: [],
      };
    }
  }

• src/tools/infer-phases.ts:8-38 (schema)

  Factory function defining the tool's metadata (name, description) and inputSchema for parameter validation.

  export function createInferPhasesTool(configLoader: ConfigLoader): Tool {
    return {
      name: 'overseer.infer_phases',
      description: 'Analyzes an existing repository structure to suggest phase definitions based on detected patterns (files, directories, configs).',
      inputSchema: {
        type: 'object',
        required: ['repo_root'],
        properties: {
          repo_root: {
            type: 'string',
            description: 'Root path of the repository (absolute path or relative to ~/dev)',
          },
          options: {
            type: 'object',
            properties: {
              detect_frameworks: {
                type: 'boolean',
                default: true,
                description: 'Detect framework-specific patterns (Phoenix, Next.js, etc.)',
              },
              detect_infrastructure: {
                type: 'boolean',
                default: true,
                description: 'Detect infrastructure files (Docker, Terraform, K8s)',
              },
            },
          },
        },
      },
    };
  }

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

  Tool registration in createTools: adds the infer_phases tool (via createInferPhasesTool) to the list of available MCP tools.

  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:52-53 (registration)

  Handler dispatch in handleToolCall switch statement: routes 'overseer.infer_phases' calls to the specific handleInferPhases function.

  case 'overseer.infer_phases':
    return await handleInferPhases(args, context.configLoader);

• src/tools/index.ts:8-8 (helper)

  Import statement linking the schema factory and handler from infer-phases.ts module.

  import { createInferPhasesTool, handleInferPhases } from './infer-phases.js';