Miro MCP

Instructions

Implementation Reference

• src/tools/createShapeItem.ts:39-79 (handler)

  The handler function that implements the core logic of the 'create-shape-item' tool. It validates inputs, constructs a ShapeCreateRequest object using Miro API models, and calls the MiroClient to create the shape item on the specified board.

  fn: async ({ boardId, data, position, geometry, style }) => {
    try {
      if (!boardId) {
        return ServerResponse.error("Board ID is required");
      }
  
      if (!validShapeTypes.includes(data.type)) {
        return ServerResponse.error("Invalid shape type. Valid types are: " + validShapeTypes.join(", "));
      }
  
      const createRequest = new ShapeCreateRequest();
      
      const shapeData = new ShapeData();
      // Set shape type via property assignment
      (shapeData as any).type = data.type;
      
      if (data.content !== undefined) {
        shapeData.content = data.content;
      }
      
      createRequest.data = shapeData;
      
      const completePosition = {
        ...position,
        origin: position.origin || "center",
        relativeTo: position.relativeTo || "canvas_center"
      };
      
      createRequest.position = completePosition;
      createRequest.geometry = geometry;
      
      if (style) {
        createRequest.style = style as Record<string, any>;
      }
  
      const result = await MiroClient.getApi().createShapeItem(boardId, createRequest);
      return ServerResponse.text(JSON.stringify(result, null, 2));
    } catch (error) {
      return ServerResponse.error(error);
    }
  }

• src/tools/createShapeItem.ts:14-38 (schema)

  Zod-based input schema defining the parameters for the 'create-shape-item' tool: boardId, data (shape type and content), position, geometry, and optional style.

  args: {
    boardId: z.string().describe("Unique identifier (ID) of the board where the shape will be created"),
    data: z.object({
      shape: z.string().describe("Type of the shape (rectangle, circle, triangle, etc.)"),
      content: z.string().optional().nullish().describe("Text content to display inside the shape")
    }).describe("The content and configuration of the shape"),
    position: z.object({
      x: z.number().describe("X coordinate of the shape"),
      y: z.number().describe("Y coordinate of the shape")
    }).describe("Position of the shape on the board"),
    geometry: z.object({
      width: z.number().describe("Width of the shape"),
      height: z.number().describe("Height of the shape"),
      rotation: z.number().optional().nullish().describe("Rotation angle of the shape")
    }).describe("Dimensions of the shape"),
    style: z.object({
      borderColor: z.string().optional().nullish().describe("Color of the shape border (hex format, e.g. #000000)"),
      borderWidth: z.number().optional().nullish().describe("Width of the shape border"),
      borderStyle: z.string().optional().nullish().describe("Style of the shape border (normal, dashed, etc.)"),
      borderOpacity: z.number().optional().nullish().describe("Opacity of the shape border (0-1)"),
      fillColor: z.string().optional().nullish().describe("Fill color of the shape (hex format, e.g. #000000)"),
      fillOpacity: z.number().optional().nullish().describe("Opacity of the shape fill (0-1)"),
      color: z.string().optional().nullish().describe("Color of the text in the shape (hex format, e.g. #000000)")
    }).optional().nullish().describe("Style configuration of the shape")
  },

• src/index.ts:157-157 (registration)

  Registration of the 'create-shape-item' tool using ToolBootstrapper.register() in the main index file.

  .register(createShapeItemTool)

• src/index.ts:57-57 (registration)

  Import of the createShapeItemTool module in the main index file for registration.

  import createShapeItemTool from './tools/createShapeItem.js';