ungroup_elements

Remove elements from a group in Excalidraw diagrams by specifying the group ID to edit individual components separately.

Instructions

Remove elements from a group by group ID

Input Schema

TableJSON Schema

Name	Required	Description	Default
`groupId`	Yes

Implementation Reference

src/mcp/tools/ungroup-elements.ts:4-29 (handler)

Core handler function ungroupElementsTool that removes elements from a group by filtering all elements, finding those with the specified groupId, and updating each element to remove that groupId from their groupIds array.

export async function ungroupElementsTool(
  args: unknown,
  client: CanvasClient
) {
  const { groupId } = GroupIdSchema.parse(args);
  const allElements = await client.getAllElements();

  const grouped = allElements.filter(
    (el) => el.groupIds && el.groupIds.includes(groupId)
  );

  if (grouped.length === 0) {
    throw new Error(`No elements found with groupId ${groupId}`);
  }

  let ungroupedCount = 0;
  for (const element of grouped) {
    const updatedGroupIds = (element.groupIds ?? []).filter(
      (gid) => gid !== groupId
    );
    await client.updateElement(element.id, { groupIds: updatedGroupIds });
    ungroupedCount++;
  }

  return { success: true, groupId, ungroupedCount };
}

src/mcp/index.ts:272-300 (registration)

MCP tool registration for 'ungroup_elements' with inline schema definition (groupId as string with max length limit) and the handler logic that calls getAllElements, filters by groupId, and updates each element to remove the group.

// --- Tool: ungroup_elements ---
server.tool(
  'ungroup_elements',
  'Remove elements from a group by group ID',
  { groupId: z.string().max(LIMITS.MAX_GROUP_ID_LENGTH) },
  async ({ groupId }) => {
    try {
      const all = await client.getAllElements();
      const inGroup = all.filter(e => e.groupIds?.includes(groupId));
      if (inGroup.length === 0) {
        throw new Error(`No elements found with groupId ${groupId}`);
      }

      for (const el of inGroup) {
        const newGroups = (el.groupIds ?? []).filter(g => g !== groupId);
        await client.updateElement(el.id, { groupIds: newGroups });
      }

      return {
        content: [{
          type: 'text',
          text: JSON.stringify({ groupId, ungroupedCount: inGroup.length }, null, 2),
        }],
      };
    } catch (err) {
      return { content: [{ type: 'text', text: `Error: ${(err as Error).message}` }], isError: true };
    }
  }
);

src/mcp/schemas/element.ts:166-170 (schema)
GroupIdSchema validation schema that defines the input structure with a groupId field as a string with maximum length constraint, used by the ungroup-elements tool handler.
```
export const GroupIdSchema = z
  .object({
    groupId: z.string().max(LIMITS.MAX_GROUP_ID_LENGTH),
  })
  .strict();
```
src/mcp/tools/index.ts:8-8 (registration)
Export statement that makes ungroupElementsTool available from the tools index module.
```
export { ungroupElementsTool } from './ungroup-elements.js';
```

excalidraw-mcp-server