excalidraw-mcp-server

Instructions

Implementation Reference

• src/mcp/tools/group-elements.ts:5-24 (handler)

  Main handler implementation of group_elements tool. Parses input using GroupElementsSchema, generates a new group ID, and iterates through elements to update their groupIds array with the new groupId. Returns success status, groupId, elementIds, and successCount.

  export async function groupElementsTool(
    args: unknown,
    client: CanvasClient
  ) {
    const { elementIds } = GroupElementsSchema.parse(args);
    const groupId = generateId();
    let successCount = 0;
  
    for (const id of elementIds) {
      const element = await client.getElement(id);
      if (!element) continue;
  
      const existingGroupIds = element.groupIds ?? [];
      const updatedGroupIds = [...existingGroupIds, groupId];
      await client.updateElement(id, { groupIds: updatedGroupIds });
      successCount++;
    }
  
    return { success: true, groupId, elementIds, successCount };
  }

• src/mcp/schemas/element.ts:157-164 (schema)

  Zod schema definition for group_elements input validation. Requires an array of elementIds (strings) with minimum 2 elements and maximum MAX_ELEMENT_IDS. Also exports TypeScript type GroupElements.

  export const GroupElementsSchema = z
    .object({
      elementIds: z
        .array(z.string().max(LIMITS.MAX_ID_LENGTH))
        .min(2)
        .max(LIMITS.MAX_ELEMENT_IDS),
    })
    .strict();

• src/mcp/index.ts:239-270 (registration)

  MCP server registration of group_elements tool with full inline handler implementation. Registers tool with name 'group_elements', description, input schema validation, and async handler that wraps the grouping logic.

  // --- Tool: group_elements ---
  server.tool(
    'group_elements',
    'Group multiple elements together',
    { elementIds: z.array(IdZ).min(2).max(LIMITS.MAX_ELEMENT_IDS) },
    async ({ elementIds }) => {
      try {
        const { generateId } = await import('../shared/id.js');
        const groupId = generateId();
        let successCount = 0;
  
        for (const eid of elementIds) {
          const el = await client.getElement(eid);
          if (!el) continue;
          const existingGroups = el.groupIds ?? [];
          await client.updateElement(eid, {
            groupIds: [...existingGroups, groupId],
          });
          successCount++;
        }
  
        return {
          content: [{
            type: 'text',
            text: JSON.stringify({ groupId, elementIds, successCount }, null, 2),
          }],
        };
      } catch (err) {
        return { content: [{ type: 'text', text: `Error: ${(err as Error).message}` }], isError: true };
      }
    }
  );

• src/shared/id.ts:3-5 (helper)

  Helper function to generate random IDs using crypto. Used by group_elements to generate unique group IDs when grouping multiple elements together.

  export function generateId(): string {
    return crypto.randomBytes(16).toString('hex');
  }

• src/mcp/canvas-client.ts:67-87 (handler)

  CanvasClient helper method updateElement used by group_elements handler to update each element's groupIds array. Makes PUT request to update element on the canvas server.

  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!;
  }