excalidraw-mcp-server

Instructions

Implementation Reference

• src/mcp/index.ts:425-442 (handler)

  Main registration and handler for lock_elements tool. Validates input with IdsZ schema, iterates through elementIds, and calls client.updateElement(eid, { locked: true }) for each element. Returns JSON response with lockedCount.
  // --- Tool: lock_elements --- server.tool( 'lock_elements', 'Lock elements to prevent modification', { elementIds: IdsZ }, async ({ elementIds }) => { try { let count = 0; for (const eid of elementIds) { await client.updateElement(eid, { locked: true }); count++; } return { content: [{ type: 'text', text: JSON.stringify({ lockedCount: count }, null, 2) }] }; } catch (err) { return { content: [{ type: 'text', text: `Error: ${(err as Error).message}` }], isError: true }; } } );
• src/mcp/schemas/element.ts:108-115 (schema)

  Input validation schema ElementIdsSchema for lock_elements tool. Requires elementIds as an array of strings (max length LIMITS.MAX_ID_LENGTH), with minimum 1 and maximum LIMITS.MAX_ELEMENT_IDS elements.
  export const ElementIdsSchema = z .object({ elementIds: z .array(z.string().max(LIMITS.MAX_ID_LENGTH)) .min(1) .max(LIMITS.MAX_ELEMENT_IDS), }) .strict();
• src/mcp/canvas-client.ts:67-87 (helper)

  CanvasClient.updateElement method that performs the actual API call to update an element with { locked: true }. Makes PUT request to /api/elements/{id} endpoint with API key authentication.
  async updateElement( id: string, data: Record<string, unknown> ): Promise<ServerElement> { const res = await fetch( `${this.baseUrl}/api/elements/${this.safePath(id)}`, { method: 'PUT', 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 { element?: ServerElement }; return body.element!; }
• src/mcp/apps/canvas-client-adapter.ts:59-78 (helper)

  CanvasClientAdapter.updateElement method for standalone mode. Updates element in the in-memory StandaloneStore by merging data with existing element, preserving id/createdAt, and updating timestamp/version.
  async updateElement( id: string, data: Record<string, unknown> ): Promise<ServerElement> { const existing = await this.store.get(id); if (!existing) throw new Error(`Element ${id} not found`); const updated: ServerElement = { ...existing, ...stripUndefined(data), id: existing.id, createdAt: existing.createdAt, updatedAt: new Date().toISOString(), version: existing.version + 1, }; await this.store.set(id, updated); logger.debug({ id }, 'Element updated'); return updated; }
• src/mcp/tools/lock-elements.ts:1-18 (handler)

  Alternative handler implementation lockElementsTool exported from tools directory but not used in main index.ts. Uses ElementIdsSchema for validation and calls client.updateElement(id, { locked: true }) in a loop, returning { success, lockedCount }.
  import type { CanvasClient } from '../canvas-client.js'; import { ElementIdsSchema } from '../schemas/element.js'; export async function lockElementsTool( args: unknown, client: CanvasClient ) { const { elementIds } = ElementIdsSchema.parse(args); let lockedCount = 0; for (const id of elementIds) { await client.updateElement(id, { locked: true }); lockedCount++; } return { success: true, lockedCount }; }