excalidraw-mcp-server

Instructions

Implementation Reference

• src/mcp/tools/unlock-elements.ts:4-17 (handler)

  Main unlock_elements tool handler: parses args using ElementIdsSchema, iterates through element IDs, calls client.updateElement(id, { locked: false }) for each, and returns success count.

  export async function unlockElementsTool(
    args: unknown,
    client: CanvasClient
  ) {
    const { elementIds } = ElementIdsSchema.parse(args);
    let unlockedCount = 0;
  
    for (const id of elementIds) {
      await client.updateElement(id, { locked: false });
      unlockedCount++;
    }
  
    return { success: true, unlockedCount };
  }

• src/mcp/index.ts:444-461 (registration)

  Tool registration in MCP main server: registers 'unlock_elements' tool with description, schema { elementIds: IdsZ }, and inline async handler that updates elements and returns formatted response.

  // --- Tool: unlock_elements ---
  server.tool(
    'unlock_elements',
    'Unlock elements to allow modification',
    { elementIds: IdsZ },
    async ({ elementIds }) => {
      try {
        let count = 0;
        for (const eid of elementIds) {
          await client.updateElement(eid, { locked: false });
          count++;
        }
        return { content: [{ type: 'text', text: JSON.stringify({ unlockedCount: 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)

  ElementIdsSchema: input validation schema for unlock_elements tool, defines an object with elementIds array (string[], min 1, max MAX_ELEMENT_IDS).

  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/index.ts:571-571 (registration)

  Sandbox server registration: unlock_elements registered with noop handler for capability scanning.

  server.tool('unlock_elements', 'Unlock elements to allow modification', { elementIds: IdsZ }, noop);

• src/mcp/tools/index.ts:10-10 (helper)

  Export of unlockElementsTool from tools module for use in the MCP server.

  export { unlockElementsTool } from './unlock-elements.js';