Excalidraw MCP Server

Instructions

Implementation Reference

• src/index.ts:328-341 (registration)

  Registration of the 'group_elements' tool, defining its name, description, and input schema for MCP server capabilities and listing.

  {
    name: 'group_elements',
    description: 'Group multiple elements together',
    inputSchema: {
      type: 'object',
      properties: {
        elementIds: { 
          type: 'array',
          items: { type: 'string' }
        }
      },
      required: ['elementIds']
    }
  },

• src/index.ts:204-206 (schema)

  Zod schema used for input validation in the group_elements handler.

  const ElementIdsSchema = z.object({
    elementIds: z.array(z.string())
  });

• src/index.ts:702-736 (handler)

  Handler for 'group_elements' tool call. Generates a group ID, updates local scene state, fetches current elements from canvas, appends the group ID to their groupIds, updates canvas, and returns result with success count.

  case 'group_elements': {
    const params = ElementIdsSchema.parse(args);
    const { elementIds } = params;
  
    try {
      const groupId = generateId();
      sceneState.groups.set(groupId, elementIds);
  
      // Update elements on canvas with proper error handling
      // Fetch existing groups and append new groupId to preserve multi-group membership
      const updatePromises = elementIds.map(async (id) => {
        const element = await getElementFromCanvas(id);
        const existingGroups = element?.groupIds || [];
        const updatedGroupIds = [...existingGroups, groupId];
        return await updateElementOnCanvas({ id, groupIds: updatedGroupIds });
      });
  
      const results = await Promise.all(updatePromises);
      const successCount = results.filter(result => result).length;
  
      if (successCount === 0) {
        sceneState.groups.delete(groupId); // Rollback local state
        throw new Error('Failed to group any elements: HTTP server unavailable');
      }
  
      logger.info('Grouping elements', { elementIds, groupId, successCount });
  
      const result = { groupId, elementIds, successCount };
      return {
        content: [{ type: 'text', text: JSON.stringify(result, null, 2) }]
      };
    } catch (error) {
      throw new Error(`Failed to group elements: ${(error as Error).message}`);
    }
  }