Overseer MCP Server

Instructions

Implementation Reference

• src/tools/check-compliance.ts:34-228 (handler)

  The core handler function implementing the overseer.check_compliance tool logic. It validates the repository against conventions from sentinel.yml, checking directories, key files, PHASES.md, phase-specific structures, and naming.

  export async function handleCheckCompliance(
    args: {
      repo_root: string;
      phase_id?: string;
      strict?: boolean;
    },
    phaseManager: PhaseManager
  ): Promise<{
    success: boolean;
    compliant: boolean;
    phase_id?: string;
    checks: Array<{
      check_type: 'directory' | 'file' | 'convention' | 'phase_structure';
      passed: boolean;
      message: string;
      details?: Record<string, unknown>;
    }>;
    summary: {
      total_checks: number;
      passed: number;
      failed: number;
    };
  }> {
    const checks: Array<{
      check_type: 'directory' | 'file' | 'convention' | 'phase_structure';
      passed: boolean;
      message: string;
      details?: Record<string, unknown>;
    }> = [];
  
    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,
          compliant: false,
          checks: [{
            check_type: 'directory',
            passed: false,
            message: 'Repository directory does not exist',
          }],
          summary: {
            total_checks: 1,
            passed: 0,
            failed: 1,
          },
        };
      }
  
      // Load config to get conventions
      const configLoader = new ConfigLoader();
      const config = configLoader.getConfig();
      const conventions = config.conventions;
  
      // Check PHASES.md exists
      const phasesPath = join(repoPath, conventions.phases_index.file);
      if (FSUtils.fileExists(phasesPath)) {
        checks.push({
          check_type: 'file',
          passed: true,
          message: `${conventions.phases_index.file} exists`,
        });
      } else {
        checks.push({
          check_type: 'file',
          passed: false,
          message: `${conventions.phases_index.file} is missing`,
        });
      }
  
      // Check for common expected directories based on conventions
      const expectedDirs = ['src', 'config', 'docs'];
      for (const dir of expectedDirs) {
        const dirPath = join(repoPath, dir);
        if (FSUtils.dirExists(dirPath)) {
          checks.push({
            check_type: 'directory',
            passed: true,
            message: `${dir}/ directory exists`,
          });
        } else {
          checks.push({
            check_type: 'directory',
            passed: false,
            message: `${dir}/ directory is missing`,
          });
        }
      }
  
      // Check for key files
      const keyFiles = ['README.md', 'package.json', '.gitignore'];
      for (const file of keyFiles) {
        const filePath = join(repoPath, file);
        if (FSUtils.fileExists(filePath)) {
          checks.push({
            check_type: 'file',
            passed: true,
            message: `${file} exists`,
          });
        } else {
          checks.push({
            check_type: 'file',
            passed: false,
            message: `${file} is missing`,
          });
        }
      }
  
      // If phase_id provided, check phase-specific structure
      if (args.phase_id) {
        const phaseId = args.phase_id.padStart(2, '0');
        const phaseFilePath = join(repoPath, `PHASE-${phaseId}.md`);
        
        if (FSUtils.fileExists(phaseFilePath)) {
          const phaseContent = FSUtils.readFile(phaseFilePath);
          
          // Check for required sections
          const requiredSections = ['Description', 'Deliverables', 'Done Criteria', 'Progress'];
          for (const section of requiredSections) {
            if (phaseContent.includes(`## ${section}`)) {
              checks.push({
                check_type: 'phase_structure',
                passed: true,
                message: `PHASE-${phaseId}.md has ${section} section`,
              });
            } else {
              checks.push({
                check_type: 'phase_structure',
                passed: false,
                message: `PHASE-${phaseId}.md missing ${section} section`,
              });
            }
          }
        } else {
          checks.push({
            check_type: 'phase_structure',
            passed: false,
            message: `PHASE-${phaseId}.md file is missing`,
          });
        }
      }
  
      // Check naming conventions
      const repoName = repoPath.split('/').pop() || '';
      const namingConvention = conventions.naming.phase_names; // Use phase_names as proxy for repo naming
      if (namingConvention === 'kebab-case') {
        const isValidKebabCase = /^[a-z0-9]+(-[a-z0-9]+)*$/.test(repoName);
        checks.push({
          check_type: 'convention',
          passed: isValidKebabCase,
          message: `Repository name follows kebab-case convention`,
          details: { repo_name: repoName, expected_format: 'kebab-case' },
        });
      }
  
      // Calculate summary
      const passed = checks.filter(c => c.passed).length;
      const failed = checks.filter(c => !c.passed).length;
      const compliant = args.strict ? failed === 0 : true; // In strict mode, all must pass
  
      return {
        success: true,
        compliant,
        phase_id: args.phase_id,
        checks,
        summary: {
          total_checks: checks.length,
          passed,
          failed,
        },
      };
    } catch (error) {
      const errorMessage = error instanceof Error ? error.message : String(error);
      return {
        success: false,
        compliant: false,
        checks: [{
          check_type: 'convention',
          passed: false,
          message: `Error checking compliance: ${errorMessage}`,
        }],
        summary: {
          total_checks: 1,
          passed: 0,
          failed: 1,
        },
      };
    }
  }

• src/tools/check-compliance.ts:8-32 (schema)

  Defines the tool specification including name, description, and detailed inputSchema for parameters repo_root (required), phase_id (optional), strict (optional boolean).

  export function createCheckComplianceTool(phaseManager: PhaseManager): Tool {
    return {
      name: 'overseer.check_compliance',
      description: 'Validates repository structure against sentinel.yml conventions. Checks for expected directories and key files.',
      inputSchema: {
        type: 'object',
        required: ['repo_root'],
        properties: {
          repo_root: {
            type: 'string',
            description: 'Root path of the repository',
          },
          phase_id: {
            type: 'string',
            description: 'Optional: Specific phase ID to check',
          },
          strict: {
            type: 'boolean',
            default: false,
            description: 'If true, all checks must pass. If false, warns about missing items.',
          },
        },
      },
    };
  }

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

  Tool factory function that registers the overseer.check_compliance tool by calling createCheckComplianceTool and including it in the array of available 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:43-80 (registration)

  Central tool dispatcher that routes calls to 'overseer.check_compliance' to the handleCheckCompliance function with context.

  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}`);
    }
  }