Learning Hour MCP

Instructions

Implementation Reference

• src/index.ts:39-42 (schema)

  Zod input validation schema for the create_miro_board tool.

  const CreateMiroBoardInputSchema = z.object({
    sessionContent: z.any(),
    existingBoardId: z.string().optional(),
  });

• src/index.ts:135-152 (registration)

  Tool metadata registration in ListToolsRequestHandler defining name, description, and input schema.

  {
    name: "create_miro_board",
    description: "Create a new Miro board OR add frames to an existing board. This tool uses the Miro REST API to create boards with frames, sticky notes, text, and code blocks. It can create standalone boards or add content to existing boards.",
    inputSchema: {
      type: "object",
      properties: {
        sessionContent: {
          type: "object",
          description: "Session content from generate_session output",
        },
        existingBoardId: {
          type: "string",
          description: "Optional: ID of an existing Miro board to add frames to. If not provided, creates a new board.",
        },
      },
      required: ["sessionContent"],
    },
  },

• src/index.ts:244-245 (registration)

  Dispatch registration in CallToolRequestHandler switch statement routing to the handler method.

  case "create_miro_board":
    return await this.createMiroBoard(request.params.arguments);

• src/index.ts:315-367 (handler)

  Main handler function that executes the create_miro_board tool logic, handling input validation, Miro integration check, delegation to create or update board, and response formatting.

  private async createMiroBoard(args: any) {
    const input = CreateMiroBoardInputSchema.parse(args);
  
    try {
      if (!this.miroIntegration) {
        throw new Error('Miro integration not initialized. Ensure MIRO_ACCESS_TOKEN is set in the environment.');
      }
  
      let layout;
      if (input.existingBoardId) {
        // Add frames to existing board
        try {
          layout = await this.miroIntegration.addFramesToExistingBoard(input.existingBoardId, input.sessionContent);
        } catch (error) {
          throw new Error(`Failed to add frames to existing board: ${error instanceof Error ? error.message : String(error)}`);
        }
      } else {
        // Create new board
        try {
          layout = await this.miroIntegration.createLearningHourBoard(input.sessionContent);
        } catch (error) {
          throw new Error(`Failed to create new Miro board: ${error instanceof Error ? error.message : String(error)}`);
        }
      }
  
      return {
        content: [
          {
            type: "text",
            text: `✅ Miro board created successfully!`,
          },
          {
            type: "text",
            text: `Board Name: ${input.sessionContent.miroContent.boardTitle}`,
          },
          {
            type: "text",
            text: `Board ID: ${layout.boardId}`,
          },
          {
            type: "text",
            text: `View Link: ${layout.viewLink || 'https://miro.com/app/board/' + layout.boardId}`,
          },
          {
            type: "text",
            text: `\nThe board includes:\n- Overview section with session description\n- Learning objectives\n- 4C activities (Connect, Concept, Concrete, Conclusion)\n- Discussion prompts\n- Key takeaways`,
          },
        ],
      };
    } catch (error) {
      throw new Error(`Failed to create Miro board: ${error instanceof Error ? error.message : String(error)}`);
    }
  }

• src/MiroIntegration.ts:371-396 (helper)

  Key helper method in MiroIntegration class that orchestrates new board creation, content processing, and layout population (slide or vertical).

  async createLearningHourBoard(sessionContent: SessionContent): Promise<LearningHourMiroLayout> {
    // Post-process content to replace placeholders
    const processedContent = this.contentPostProcessor.processSessionContent(sessionContent);
  
    const boardName = processedContent.miroContent.boardTitle;
    const board = await this.createBoard(boardName, processedContent.sessionOverview);
    const style = processedContent.miroContent.style ?? 'slide';
  
    const layout: LearningHourMiroLayout = {
      boardId: board.id,
      viewLink: board.viewLink,
      sections: {
        overview: {} as MiroFrame,
        objectives: [],
        activities: [],
        discussions: [],
        takeaways: []
      }
    };
  
    if (style === 'slide') {
      return await this.createSlideLayout(board.id, processedContent, layout);
    } else {
      return await this.createVerticalLayout(board.id, processedContent, layout);
    }
  }