get_practice_question

Instructions

Implementation Reference

• src/tools/get-practice-question.ts:41-124 (handler)

  The main handler function `registerGetPracticeQuestion` that registers the 'get_practice_question' tool with the MCP server. It handles question selection logic: loads questions, filters by optional domainId/difficulty, prioritizes overdue reviews then weak areas then new material, formats the question text, elicits a single-select answer, and returns the result along with metadata for the quiz UI widget.

  export function registerGetPracticeQuestion(server: McpServer, db: Database.Database, userConfig: UserConfig): void {
    server.tool(
      'get_practice_question',
      `Get the next practice question. Prioritizes review questions, then weak areas, then new material.
  
  IMPORTANT — present the question using AskUserQuestion:
  - header: "Answer"
  - question: Include the FULL scenario text AND question text from the response
  - options: 4 items with label "A"/"B"/"C"/"D" and description as the option text
  - If the scenario contains code, add a "preview" field on each option showing the code snippet
  Then call submit_answer with the questionId and selected answer. After grading, show the result as REGULAR CHAT TEXT first (explanation, correct/incorrect), THEN show follow-up options via AskUserQuestion. Explanations must be readable in the main chat, not hidden behind cards.
  
  EDGE CASES:
  - "Other": Answer the user's question, then re-present the SAME question via AskUserQuestion.
  - "Skip": Call get_practice_question again for a new question. Never break the flow.`,
      {
        domainId: z.number().optional().describe('Optional domain ID to filter questions (1-5)'),
        difficulty: z.enum(['easy', 'medium', 'hard']).optional().describe('Optional difficulty filter'),
      },
      async ({ domainId, difficulty }) => {
        const userId = userConfig.userId;
        ensureUser(db, userId);
        const answeredIds = getAnsweredQuestionIds(db, userId);
        const overdueReviews = getOverdueReviews(db, userId);
        const weakAreas = getWeakAreas(db, userId);
        let questions = loadQuestions(domainId);
        if (difficulty) {
          questions = questions.filter(q => q.difficulty === difficulty);
        }
        const question = selectNextQuestion(questions, overdueReviews, weakAreas, answeredIds);
        if (!question) {
          return {
            content: [{ type: 'text' as const, text: 'No more questions available for the selected criteria. Try a different domain or difficulty.' }],
          };
        }
  
        const questionText = formatQuestionText(question);
  
        const elicitOptions = OPTION_KEYS.map(key => ({
          value: key,
          title: `${key}. ${question.options[key]}`,
        }));
  
        const selectedAnswer = await elicitSingleSelect(
          server,
          questionText,
          'answer',
          elicitOptions,
        );
  
        if (selectedAnswer) {
          const responseText = [
            questionText,
            '',
            '---',
            '',
            `**Selected answer: ${selectedAnswer}**`,
            '',
            `Use submit_answer with questionId "${question.id}" and answer "${selectedAnswer}" to grade this response.`,
          ].join('\n');
  
          return {
            content: [{ type: 'text' as const, text: responseText }],
            _meta: buildQuizMeta(),
          };
        }
  
        const fallbackText = [
          questionText,
          '',
          '---',
          '',
          `Question ID: ${question.id}`,
          '',
          'Use submit_answer with the question ID and your chosen answer (A, B, C, or D) to check your response.',
        ].join('\n');
  
        return {
          content: [{ type: 'text' as const, text: fallbackText }],
          _meta: buildQuizMeta(),
        };
      }
    );
  }

• src/tools/get-practice-question.ts:14-39 (helper)

  The `formatQuestionText` helper function that formats question data (id, domain, difficulty, task statement, scenario, text, and options A-D) into a nicely formatted Markdown string for display.

  const OPTION_KEYS = ['A', 'B', 'C', 'D'] as const;
  
  function formatQuestionText(question: {
    readonly id: string;
    readonly taskStatement: string;
    readonly domainId: number;
    readonly difficulty: string;
    readonly scenario: string;
    readonly text: string;
    readonly options: { readonly A: string; readonly B: string; readonly C: string; readonly D: string };
  }): string {
    const lines = [
      `**Question ${question.id}** (Domain ${question.domainId} | ${question.difficulty})`,
      '',
      `**Task:** ${question.taskStatement}`,
      '',
      '---',
      '',
      question.scenario,
      '',
      `**${question.text}**`,
      '',
      ...OPTION_KEYS.map(key => `  **${key}.** ${question.options[key]}`),
    ];
    return lines.join('\n');
  }

• src/tools/get-practice-question.ts:56-59 (schema)

  Input schema for the tool: optional `domainId` (number, 1-5) and optional `difficulty` (enum: 'easy', 'medium', 'hard'), validated with Zod.

  {
    domainId: z.number().optional().describe('Optional domain ID to filter questions (1-5)'),
    difficulty: z.enum(['easy', 'medium', 'hard']).optional().describe('Optional difficulty filter'),
  },

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

  Registration of the `registerGetPracticeQuestion` function: imported from './get-practice-question.js' (line 8) and called in the `registerTools` function (line 28) alongside all other tool registrations.

  import { registerGetPracticeQuestion } from './get-practice-question.js';
  import { registerStartAssessment } from './start-assessment.js';
  import { registerGetWeakAreas } from './get-weak-areas.js';
  import { registerGetStudyPlan } from './get-study-plan.js';
  import { registerScaffoldProject } from './scaffold-project.js';
  import { registerResetProgress } from './reset-progress.js';
  import { registerStartPracticeExam } from './start-practice-exam.js';
  import { registerSubmitExamAnswer } from './submit-exam-answer.js';
  import { registerGetExamHistory } from './get-exam-history.js';
  import { registerFollowUp } from './follow-up.js';
  import { registerStartCapstoneBuild } from './start-capstone-build.js';
  import { registerCapstoneBuildStep } from './capstone-build-step.js';
  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);

• src/engine/question-selector.ts:1-27 (helper)

  The `selectNextQuestion` helper used by the tool handler to pick the next question. Prioritizes: (1) overdue reviews sorted by ease factor, (2) weak areas, (3) any unanswered question. Delegates to `findUnansweredForTaskStatement` for matching.

  import type { Question, ReviewScheduleEntry, DomainMastery } from '../types.js';
  
  export function selectNextQuestion(
    allQuestions: readonly Question[], overdueReviews: readonly ReviewScheduleEntry[],
    weakAreas: readonly DomainMastery[], answeredQuestionIds: ReadonlySet<string>,
  ): Question | undefined {
    if (overdueReviews.length > 0) {
      const weakestFirst = [...overdueReviews].sort((a, b) => a.easeFactor - b.easeFactor);
      for (const review of weakestFirst) {
        const question = findUnansweredForTaskStatement(allQuestions, review.taskStatement, answeredQuestionIds);
        if (question) return question;
      }
    }
    if (weakAreas.length > 0) {
      for (const area of weakAreas) {
        const question = findUnansweredForTaskStatement(allQuestions, area.taskStatement, answeredQuestionIds);
        if (question) return question;
      }
    }
    return allQuestions.find((q) => !answeredQuestionIds.has(q.id));
  }
  
  function findUnansweredForTaskStatement(
    questions: readonly Question[], taskStatement: string, answeredIds: ReadonlySet<string>,
  ): Question | undefined {
    return questions.find((q) => q.taskStatement === taskStatement && !answeredIds.has(q.id));
  }