create_element

Instructions

Implementation Reference

• src/mcp/index.ts:106-119 (handler)

  MCP tool registration and handler for 'create_element'. This is the main entry point that receives the MCP tool request, extracts the arguments (type, x, y, and other properties), calls client.createElement(), and returns the result in MCP protocol format.

  // --- Tool: create_element ---
  server.tool(
    'create_element',
    'Create a single Excalidraw element on the canvas',
    elementFields,
    async ({ type, x, y, ...rest }) => {
      try {
        const element = await client.createElement({ type, x, y, ...rest });
        return { content: [{ type: 'text', text: JSON.stringify(element, null, 2) }] };
      } catch (err) {
        return { content: [{ type: 'text', text: `Error: ${(err as Error).message}` }], isError: true };
      }
    }
  );

• src/mcp/canvas-client.ts:27-41 (helper)

  CanvasClient.createElement() method that makes an HTTP POST request to the canvas server's /api/elements endpoint. Handles error responses and returns the created ServerElement.

  async createElement(data: Record<string, unknown>): Promise<ServerElement> {
    const res = await fetch(`${this.baseUrl}/api/elements`, {
      method: 'POST',
      headers: this.headers(),
      body: JSON.stringify(data),
    });
  
    if (!res.ok) {
      const body = await res.json().catch(() => ({})) as ApiResponse;
      throw new Error(body.error ?? `Canvas error: ${res.status}`);
    }
  
    const body = await res.json() as ApiResponse<ServerElement> & { element?: ServerElement };
    return body.element ?? body.data!;
  }

• src/mcp/schemas/element.ts:55-93 (schema)

  CreateElementSchema - Zod validation schema for element creation inputs. Defines all allowed fields (type, x, y, width, height, colors, stroke, text, etc.) with their constraints and optional flags.

  export const CreateElementSchema = z
    .object({
      type: ElementTypeSchema,
      x: CoordinateSchema,
      y: CoordinateSchema,
      width: DimensionSchema,
      height: DimensionSchema,
      points: z.array(PointSchema).max(LIMITS.MAX_POINTS).optional(),
      backgroundColor: ColorSchema,
      strokeColor: ColorSchema,
      strokeWidth: z
        .number()
        .min(0)
        .max(LIMITS.MAX_STROKE_WIDTH)
        .finite()
        .optional(),
      roughness: z
        .number()
        .min(0)
        .max(LIMITS.MAX_ROUGHNESS)
        .finite()
        .optional(),
      opacity: z
        .number()
        .min(LIMITS.MIN_OPACITY)
        .max(LIMITS.MAX_OPACITY)
        .finite()
        .optional(),
      text: z.string().max(LIMITS.MAX_TEXT_LENGTH).optional(),
      fontSize: z.number().min(1).max(LIMITS.MAX_FONT_SIZE).finite().optional(),
      fontFamily: z.number().int().min(1).max(4).optional(),
      groupIds: z
        .array(z.string().max(LIMITS.MAX_GROUP_ID_LENGTH))
        .max(LIMITS.MAX_GROUP_IDS)
        .optional(),
      locked: z.boolean().optional(),
      angle: z.number().min(-360).max(360).finite().optional(),
    })
    .strict();

• src/mcp/apps/canvas-client-adapter.ts:16-48 (helper)

  CanvasClientAdapter.createElement() - Alternative implementation for standalone mode (when canvas server is unavailable). Creates elements directly in the in-memory StandaloneStore without making HTTP requests.

  async createElement(data: Record<string, unknown>): Promise<ServerElement> {
    const now = new Date().toISOString();
    const element: ServerElement = {
      id: generateId(),
      type: data.type as ServerElement['type'],
      x: data.x as number,
      y: data.y as number,
      ...(data.width !== undefined && { width: data.width as number }),
      ...(data.height !== undefined && { height: data.height as number }),
      ...(data.points !== undefined && { points: data.points as ServerElement['points'] }),
      ...(data.backgroundColor !== undefined && { backgroundColor: data.backgroundColor as string }),
      ...(data.strokeColor !== undefined && { strokeColor: data.strokeColor as string }),
      ...(data.strokeWidth !== undefined && { strokeWidth: data.strokeWidth as number }),
      ...(data.roughness !== undefined && { roughness: data.roughness as number }),
      ...(data.opacity !== undefined && { opacity: data.opacity as number }),
      ...(data.text !== undefined && { text: data.text as string }),
      ...(data.fontSize !== undefined && { fontSize: data.fontSize as number }),
      ...(data.fontFamily !== undefined && { fontFamily: data.fontFamily as number }),
      ...(data.groupIds !== undefined && { groupIds: data.groupIds as string[] }),
      ...(data.locked !== undefined && { locked: data.locked as boolean }),
      ...(data.angle !== undefined && { angle: data.angle as number }),
      ...(data.fillStyle !== undefined && { fillStyle: data.fillStyle as string }),
      ...(data.strokeStyle !== undefined && { strokeStyle: data.strokeStyle as string }),
      createdAt: now,
      updatedAt: now,
      version: 1,
      source: 'standalone',
    };
  
    await this.store.set(element.id, element);
    logger.debug({ id: element.id, type: element.type }, 'Element created');
    return element;
  }

• src/canvas/routes/elements.ts:109-148 (handler)

  Express.js route handler for POST /api/elements - the server-side implementation that validates input, generates an ID and timestamps, stores the element, and broadcasts the creation via WebSocket.

  router.post('/', async (req, res) => {
    try {
      const result = CreateBodySchema.safeParse(req.body);
      if (!result.success) {
        res.status(400).json({
          success: false,
          error: 'Validation failed',
          details: result.error.issues,
        });
        return;
      }
  
      const now = new Date().toISOString();
      const id = generateId();
      const element: ServerElement = {
        ...result.data,
        id,
        createdAt: now,
        updatedAt: now,
        version: 1,
        source: 'api',
      };
  
      await store.set(id, element);
  
      ws.broadcast({
        type: 'element_created',
        element: element as unknown as Record<string, unknown>,
      });
  
      res.status(201).json({ success: true, element });
    } catch (err) {
      const message = err instanceof Error ? err.message : 'Internal server error';
      logger.error({ err }, 'Failed to create element');
      res.status(message.includes('Maximum element count') ? 409 : 500).json({
        success: false,
        error: message,
      });
    }
  });