Create Excalidraw View

Instructions

Implementation Reference

• src/mcp/tools/create-view.ts:51-74 (handler)

  The main handler function handleCreateView that processes create_view tool calls. It accepts elements and optional title, optionally persists elements to store, and returns the diagram data as JSON text content.

  export async function handleCreateView(
    args: CreateViewArgs,
    persistToStore?: (elements: Record<string, unknown>[]) => Promise<void>
  ): Promise<{ content: Array<{ type: 'text'; text: string }> }> {
    const { elements, title } = args;
  
    // Persist elements to the store so other tools can reference them
    if (persistToStore) {
      await persistToStore(elements as unknown as Record<string, unknown>[]);
    }
  
    const result = {
      title: title ?? 'Excalidraw Diagram',
      elementCount: elements.length,
      elements,
    };
  
    return {
      content: [{
        type: 'text' as const,
        text: JSON.stringify(result, null, 2),
      }],
    };
  }

• src/mcp/tools/create-view.ts:14-38 (schema)

  Zod schema definitions for create_view input validation. Includes viewElementSchema for individual elements (with type, coordinates, styling options) and CREATE_VIEW_SCHEMA for the main tool input (elements array, optional title, and background).

  const viewElementSchema = z.object({
    type: z.enum(ELEMENT_TYPES),
    x: CoordZ,
    y: CoordZ,
    width: DimZ,
    height: DimZ,
    points: z.array(PointZ).max(LIMITS.MAX_POINTS).optional(),
    backgroundColor: ColorZ,
    strokeColor: ColorZ,
    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(),
  });
  
  export const CREATE_VIEW_SCHEMA = {
    elements: z.array(viewElementSchema).min(1).max(LIMITS.MAX_BATCH_SIZE),
    title: z.string().max(200).optional(),
    background: ColorZ,
  };

• src/mcp/apps/register.ts:30-55 (registration)

  Registration of the create_view tool using registerAppTool from MCP Apps SDK. Includes tool metadata (title, description, UI resource URI) and wraps handleCreateView with error handling.

  registerAppTool(
    server,
    'create_view',
    {
      title: 'Create Excalidraw View',
      description:
        'Render Excalidraw elements as an interactive inline diagram. ' +
        'Pass an array of elements with type, x, y coordinates and optional styling. ' +
        'The diagram streams in progressively as elements are generated. ' +
        'Use read_me first to see available element types and color palettes.',
      inputSchema: CREATE_VIEW_SCHEMA,
      _meta: {
        ui: { resourceUri: WIDGET_RESOURCE_URI },
      },
    },
    async (args: CreateViewArgs) => {
      try {
        return await handleCreateView(args, opts.persistToStore);
      } catch (err) {
        return {
          content: [{ type: 'text' as const, text: `Error: ${(err as Error).message}` }],
          isError: true,
        };
      }
    }
  );

• src/mcp/tools/create-view.ts:4-12 (helper)

  Helper type validators and constants used in the schema. Defines coordinate, dimension, color, and point validators, plus the ELEMENT_TYPES array enumerating supported shape types.

  const CoordZ = z.number().min(LIMITS.MIN_COORDINATE).max(LIMITS.MAX_COORDINATE).finite();
  const DimZ = z.number().min(0).max(LIMITS.MAX_DIMENSION).finite().optional();
  const ColorZ = z.string().max(LIMITS.MAX_COLOR_LENGTH).optional();
  const PointZ = z.object({ x: CoordZ, y: CoordZ });
  
  const ELEMENT_TYPES = [
    'rectangle', 'ellipse', 'diamond', 'arrow',
    'text', 'line', 'freedraw',
  ] as const;

• src/mcp/tools/create-view.ts:40-40 (schema)

  Type definition for CreateViewArgs inferred from the Zod schema, providing TypeScript type safety for the handler function.

  export type CreateViewArgs = z.infer<z.ZodObject<typeof CREATE_VIEW_SCHEMA>>;