capstone_build_status

Instructions

Implementation Reference

• src/tools/capstone-build-status.ts:102-148 (handler)

  The main handler registration for the 'capstone_build_status' tool. Calls server.tool() with name 'capstone_build_status'. Checks for an active build, handles 'shaping' vs 'building' status, and formats the status report with steps, criteria coverage, and quiz performance.

  export function registerCapstoneBuildStatus(server: McpServer, db: Database.Database, userConfig: UserConfig): void {
    server.tool(
      'capstone_build_status',
      'Check your guided capstone build progress \u2014 current step, criteria coverage, and quiz performance.',
      {},
      async () => {
        const userId = userConfig.userId;
        const build = getActiveBuild(db, userId);
  
        if (!build) {
          return {
            content: [{
              type: 'text' as const,
              text: 'No active capstone build found. Use start_capstone_build to begin a guided build.',
            }],
          };
        }
  
        if (build.status === 'shaping') {
          const lines = [
            '=== CAPSTONE BUILD STATUS ===',
            '',
            `Theme: ${build.theme}`,
            'Status: Shaping',
            '',
            'Your theme is being shaped. You can:',
            '  - Confirm it to start building',
            '  - Refine it with a new description',
          ];
          return {
            content: [{ type: 'text' as const, text: lines.join('\n') }],
          };
        }
  
        // Status is 'building'
        const steps = getBuildSteps(db, build.id);
        const quizQuestionIds = collectQuizQuestionIds(steps);
        const quizPerformance = getQuizPerformance(db, userId, quizQuestionIds);
  
        const text = formatBuildingStatus(build.theme, build.currentStep, steps, quizPerformance);
  
        return {
          content: [{ type: 'text' as const, text }],
        };
      }
    );
  }

• src/tools/capstone-build-status.ts:8-12 (schema)

  QuizStats interface used to structure quiz performance data (domainId, total, correct).

  interface QuizStats {
    readonly domainId: number;
    readonly total: number;
    readonly correct: number;
  }

• src/tools/capstone-build-status.ts:14-20 (helper)

  Helper function collectQuizQuestionIds - extracts quiz question IDs from build steps by parsing JSON.

  function collectQuizQuestionIds(steps: readonly CapstoneBuildStep[]): readonly string[] {
    return steps.flatMap(step => {
      if (!step.quizQuestionIds) return [];
      const parsed = JSON.parse(step.quizQuestionIds) as readonly string[];
      return [...parsed];
    });
  }

• src/tools/capstone-build-status.ts:22-39 (helper)

  Helper function getQuizPerformance - queries the answers table to get per-domain quiz performance stats.

  function getQuizPerformance(db: Database.Database, userId: string, questionIds: readonly string[]): readonly QuizStats[] {
    if (questionIds.length === 0) return [];
  
    const placeholders = questionIds.map(() => '?').join(', ');
    const rows = db.prepare(
      `SELECT domainId, COUNT(*) as total, SUM(CASE WHEN isCorrect THEN 1 ELSE 0 END) as correct
       FROM answers
       WHERE userId = ? AND questionId IN (${placeholders})
       GROUP BY domainId
       ORDER BY domainId ASC`
    ).all(userId, ...questionIds) as Array<{ domainId: number; total: number; correct: number }>;
  
    return rows.map(r => ({
      domainId: r.domainId,
      total: r.total,
      correct: r.correct ?? 0,
    }));
  }

• src/tools/index.ts:20-42 (registration)

  Import of registerCapstoneBuildStatus in the central tools registration file.

  import { registerCapstoneBuildStatus } from './capstone-build-status.js';
  import { registerDashboard } from './dashboard.js';
  
  export function registerTools(server: McpServer, db: Database.Database, userConfig: UserConfig): void {
    registerSubmitAnswer(server, db, userConfig);
    registerGetProgress(server, db, userConfig);
    registerGetCurriculum(server, db, userConfig);
    registerGetSectionDetails(server, db, userConfig);
    registerGetPracticeQuestion(server, db, userConfig);
    registerStartAssessment(server, db, userConfig);
    registerGetWeakAreas(server, db, userConfig);
    registerGetStudyPlan(server, db, userConfig);
    registerScaffoldProject(server, db, userConfig);
    registerResetProgress(server, db, userConfig);
    registerStartPracticeExam(server, db, userConfig);
    registerSubmitExamAnswer(server, db, userConfig);
    registerGetExamHistory(server, db, userConfig);
    registerFollowUp(server, db, userConfig);
    registerStartCapstoneBuild(server, db, userConfig);
    registerCapstoneBuildStep(server, db, userConfig);
    registerCapstoneBuildStatus(server, db, userConfig);
    registerDashboard(server, db, userConfig);
  }