group_elements
Combine multiple diagram elements into a single group for easier management and manipulation in Excalidraw diagrams.
Instructions
Group multiple elements together
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| elementIds | Yes |
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!; }