Learning Hour MCP

Instructions

Implementation Reference

• src/LearningHourGenerator.ts:410-443 (handler)

  Core handler function that generates code examples using Anthropic Claude API. Builds a detailed prompt, calls the API, extracts JSON response, validates, and returns structured CodeExample.

  async generateCodeExample(topic: string, language: string = 'java'): Promise<CodeExample> {
    const prompt = this.buildCodeExamplePrompt(topic, language);
  
    try {
      const message = await this.client.messages.create({
        model: this.model,
        max_tokens: 4000,
        messages: [{
          role: 'user',
          content: prompt
        }]
      });
  
      const textContent = message.content.find(block => block.type === 'text');
      if (!textContent || textContent.type !== 'text') {
        throw new Error('No text content in response');
      }
      const content = textContent.text;
      logger.error('Raw response:', content.substring(0, 200) + '...');
  
      // Try to extract JSON from the response
      const jsonMatch = content.match(/\{[\s\S]*\}$/);
      if (!jsonMatch) {
        throw new Error('No valid JSON found in response');
      }
  
      const exampleData = JSON.parse(jsonMatch[0]);
      this.validateCodeExample(exampleData);
  
      return exampleData;
    } catch (error) {
      throw new Error(`Failed to generate code example: ${error instanceof Error ? error.message : String(error)}`);
    }
  }

• src/index.ts:292-313 (handler)

  MCP server wrapper handler: validates input schema, delegates to LearningHourGenerator, formats MCP response.

  private async generateCodeExample(args: any) {
    const input = GenerateCodeExampleInputSchema.parse(args);
  
    try {
      const exampleData = await this.generator.generateCodeExample(input.topic, input.language);
  
      return {
        content: [
          {
            type: "text",
            text: `✅ Code examples generated for: ${input.topic} (${input.language})`,
          },
          {
            type: "text",
            text: JSON.stringify(exampleData, null, 2),
          },
        ],
      };
    } catch (error) {
      throw new Error(`Failed to generate code example: ${error instanceof Error ? error.message : String(error)}`);
    }
  }

• src/index.ts:116-134 (registration)

  Tool registration in MCP server's listTools handler, including name, description, and input schema.

  {
    name: "generate_code_example",
    description: "Generate detailed before/after code examples for a learning topic",
    inputSchema: {
      type: "object",
      properties: {
        topic: {
          type: "string",
          description: "The learning topic (e.g., 'Feature Envy', 'DRY Principle')",
        },
        language: {
          type: "string",
          description: "Programming language for examples (default: javascript)",
          default: "javascript"
        },
      },
      required: ["topic"],
    },
  },

• src/index.ts:25-28 (schema)

  Zod schema for input validation in the wrapper handler.

  const GenerateCodeExampleInputSchema = z.object({
    topic: z.string().min(1, "Topic is required"),
    language: z.string().optional().default("javascript"),
  });

• src/LearningHourGenerator.ts:294-443 (helper)

  Helper function that constructs the detailed prompt template sent to Anthropic for code generation.

    private buildCodeExamplePrompt(topic: string, language: string): string {
      return `Create a comprehensive, production-like code example for a Learning Hour on "${topic}" in ${language}.
  
  CONTEXT: This example will be used in the Concrete phase of a Learning Hour where participants practice refactoring through hands-on coding. The example must feel realistic and connect to actual problems developers face.
  
  LEARNING HOUR PHILOSOPHY: We practice in a safe environment to build muscle memory for technical excellence. Small, incremental improvements with tests give us confidence to refactor production code.
  
  REQUIREMENTS:
  1. Create a REALISTIC scenario that developers would encounter in production codebases
  2. Show MULTIPLE refactoring steps (3-5 steps), not just before/after
  3. Include SPECIFIC code smells being addressed at each step
  4. Provide TEST CODE alongside production code
  5. Add FACILITATION notes for Technical Coaches
  6. Demonstrate INCREMENTAL improvements - each step should be small and safe
  7. Connect to broader TECHNICAL EXCELLENCE principles
  
  IMPORTANT: Return ONLY valid JSON with no additional text or markdown formatting.
  
  {
    "topic": "${topic}",
    "language": "${language}",
    "context": "Brief description of the realistic scenario (e.g., 'E-commerce checkout system calculating discounts and taxes')",
    "problemStatement": "What specific problem does this code exhibit that makes it a good Learning Hour example?",
    "learningHourConnection": "How does practicing with this example build skills that transfer to participants' daily work?",
    "refactoringSteps": [
      {
        "stepNumber": 1,
        "description": "Extract Method - Isolate discount calculation logic",
        "code": "// Production code for this step\\nclass OrderProcessor {\\n    // Show the code after this specific refactoring\\n}",
        "testCode": "// Test code that validates this step\\n@Test\\nvoid shouldCalculateDiscountCorrectly() {\\n    // Test implementation\\n}",
        "codeSmells": ["Long Method", "Feature Envy", "Comments explaining complex logic"],
        "improvements": ["Single Responsibility", "Improved testability", "Self-documenting code"],
        "facilitationTip": "Ask pairs: 'What makes this method easier to test now? How would you test the edge cases?'"
      },
      {
        "stepNumber": 2,
        "description": "Replace Conditional with Polymorphism - Different discount strategies",
        "code": "// Code after introducing strategy pattern\\ninterface DiscountStrategy {\\n    // etc.\\n}",
        "testCode": "// Tests for the new abstraction\\n@Test\\nvoid shouldApplyPercentageDiscount() {\\n    // Test implementation\\n}",
        "codeSmells": ["Switch statements", "Type checking", "Duplicate logic"],
        "improvements": ["Open/Closed Principle", "Strategy Pattern", "Easier to extend"],
        "facilitationTip": "Pause here and ask: 'What new discount types could we add without changing existing code?'"
      },
      {
        "stepNumber": 3,
        "description": "Introduce Parameter Object - Group related parameters",
        "code": "// Code with new parameter object\\nclass DiscountContext {\\n    // Grouped parameters\\n}",
        "testCode": "// Tests showing improved clarity\\n@Test\\nvoid shouldCreateDiscountContextWithValidData() {\\n    // Test implementation\\n}",
        "codeSmells": ["Long Parameter List", "Data Clumps", "Primitive Obsession"],
        "improvements": ["Cohesion", "Domain modeling", "Validation in one place"],
        "facilitationTip": "Discuss: 'How does grouping these parameters reveal domain concepts we were missing?'"
      }
    ],
    "additionalExercises": [
      "Add a new discount type (e.g., loyalty program) using the refactored structure",
      "Extract validation logic into a separate validator class",
      "Implement a composite pattern for combining multiple discounts"
    ],
    "facilitationNotes": {
      "timeAllocation": "5 min initial code review, 15 min pair refactoring, 5 min group discussion",
      "commonMistakes": [
        "Trying to refactor everything at once instead of small steps",
        "Forgetting to run tests between each refactoring",
        "Getting stuck on naming - encourage 'good enough' names that can be improved later"
      ],
      "discussionPoints": [
        "Which refactoring step had the biggest impact on code clarity?",
        "How do these patterns apply to your current codebase?",
        "What prevented us from writing it this way initially?"
      ],
      "pairProgrammingTips": [
        "Enforce role switching every 5 minutes using a timer",
        "Navigator should focus on the current refactoring step, not jump ahead",
        "Encourage thinking out loud to share mental models",
        "Celebrate each green test as progress"
      ]
    }
  }
  
  CRITICAL DETAILS:
  - Each refactoring step must compile and pass tests independently
  - Code should be substantial enough to feel real (not toy examples)
  - Include ${language}-specific idioms and best practices
  - Test code should demonstrate TDD thinking
  - Code smells should be specific and recognizable
  - Facilitation tips should encourage participant engagement
  - The progression should tell a story of incremental improvement`;
    }
  
    async generateSessionContent(topic: string, style: string = 'slide'): Promise<SessionContent> {
      const prompt = this.buildSessionPrompt(topic, style);
  
      try {
        const message = await this.client.messages.create({
          model: this.model,
          max_tokens: 3000,
          messages: [{
            role: 'user',
            content: prompt
          }]
        });
  
        const textContent = message.content.find(block => block.type === 'text');
        if (!textContent || textContent.type !== 'text') {
          throw new Error('No text content in response');
        }
        const content = textContent.text;
        const sessionData = JSON.parse(content);
        this.validateSessionContent(sessionData);
  
        return sessionData;
      } catch (error) {
        throw new Error(`Failed to generate session: ${error instanceof Error ? error.message : String(error)}`);
      }
    }
  
    async generateCodeExample(topic: string, language: string = 'java'): Promise<CodeExample> {
      const prompt = this.buildCodeExamplePrompt(topic, language);
  
      try {
        const message = await this.client.messages.create({
          model: this.model,
          max_tokens: 4000,
          messages: [{
            role: 'user',
            content: prompt
          }]
        });
  
        const textContent = message.content.find(block => block.type === 'text');
        if (!textContent || textContent.type !== 'text') {
          throw new Error('No text content in response');
        }
        const content = textContent.text;
        logger.error('Raw response:', content.substring(0, 200) + '...');
  
        // Try to extract JSON from the response
        const jsonMatch = content.match(/\{[\s\S]*\}$/);
        if (!jsonMatch) {
          throw new Error('No valid JSON found in response');
        }
  
        const exampleData = JSON.parse(jsonMatch[0]);
        this.validateCodeExample(exampleData);
  
        return exampleData;
      } catch (error) {
        throw new Error(`Failed to generate code example: ${error instanceof Error ? error.message : String(error)}`);
      }
    }