GridStack MCP Server

gridstack_update_widget

Modify widget properties like position, size, and behavior in a GridStack dashboard layout to customize its appearance and functionality.

Instructions

Update widget properties

Input Schema

TableJSON Schema

Name	Required	Description	Default
`el`	Yes	Widget selector or ID to update
`opts`	Yes	Properties to update

Implementation Reference

src/tools/index.ts:906-914 (handler)

The main handler function for the 'gridstack_update_widget' tool. It destructures the input parameters and generates the GridStack 'update' code snippet using the shared utility, returning a formatted response.

private async updateWidget(params: UpdateWidgetParams): Promise<string> {
  const { el, opts } = params;

  return this.utils.generateGridStackCode("updateWidget", {
    element: el,
    options: opts,
    code: `grid.update('${String(el)}', ${JSON.stringify(opts, null, 2)});`,
  });
}

src/tools/index.ts:206-233 (schema)

JSON input schema defining the required 'el' (selector/ID) and 'opts' (partial widget properties) for validating tool inputs.

inputSchema: {
  type: "object",
  required: ["el", "opts"],
  properties: {
    el: {
      type: "string",
      description: "Widget selector or ID to update",
    },
    opts: {
      type: "object",
      description: "Properties to update",
      properties: {
        x: { type: "number" },
        y: { type: "number" },
        w: { type: "number" },
        h: { type: "number" },
        minW: { type: "number" },
        maxW: { type: "number" },
        minH: { type: "number" },
        maxH: { type: "number" },
        locked: { type: "boolean" },
        noResize: { type: "boolean" },
        noMove: { type: "boolean" },
        content: { type: "string" },
      },
    },
  },
},

src/tools/index.ts:777-778 (registration)
Switch case in callTool method that registers and dispatches calls to the specific updateWidget handler.
```
case "gridstack_update_widget":
  return this.updateWidget(args as UpdateWidgetParams);
```
src/types.ts:189-192 (schema)
TypeScript type definition for the handler parameters, mirroring the JSON schema.
```
export interface UpdateWidgetParams {
  el: string | HTMLElement;
  opts: Partial<GridStackWidget>;
}
```

src/utils/gridstack-utils.ts:16-496 (helper)

Utility method used by the handler to format the response with code, parameters, description, example, and notes for the update operation.

  generateGridStackCode(operation: string, params: any): string {
    const result: GridStackCodeResult = {
      operation,
      parameters: params,
      code: params.code || "",
      description: this.getOperationDescription(operation),
      example: this.getOperationExample(operation),
      notes: this.getOperationNotes(operation),
    };

    return this.formatResponse(result);
  }

  /**
   * Format GridStack options for display
   */
  formatOptions(options: GridStackOptions): string {
    const formatted = JSON.stringify(options, null, 2);
    return formatted;
  }

  /**
   * Validate widget configuration
   */
  validateWidget(widget: GridStackWidget): {
    valid: boolean;
    errors: string[];
  } {
    const errors: string[] = [];

    // Check required properties for positioning
    if (
      widget.x !== undefined &&
      (widget.x < 0 || !Number.isInteger(widget.x))
    ) {
      errors.push("x position must be a non-negative integer");
    }

    if (
      widget.y !== undefined &&
      (widget.y < 0 || !Number.isInteger(widget.y))
    ) {
      errors.push("y position must be a non-negative integer");
    }

    if (
      widget.w !== undefined &&
      (widget.w <= 0 || !Number.isInteger(widget.w))
    ) {
      errors.push("width must be a positive integer");
    }

    if (
      widget.h !== undefined &&
      (widget.h <= 0 || !Number.isInteger(widget.h))
    ) {
      errors.push("height must be a positive integer");
    }

    // Check min/max constraints
    if (
      widget.minW !== undefined &&
      widget.maxW !== undefined &&
      widget.minW > widget.maxW
    ) {
      errors.push("minW cannot be greater than maxW");
    }

    if (
      widget.minH !== undefined &&
      widget.maxH !== undefined &&
      widget.minH > widget.maxH
    ) {
      errors.push("minH cannot be greater than maxH");
    }

    if (
      widget.w !== undefined &&
      widget.minW !== undefined &&
      widget.w < widget.minW
    ) {
      errors.push("width cannot be less than minW");
    }

    if (
      widget.w !== undefined &&
      widget.maxW !== undefined &&
      widget.w > widget.maxW
    ) {
      errors.push("width cannot be greater than maxW");
    }

    if (
      widget.h !== undefined &&
      widget.minH !== undefined &&
      widget.h < widget.minH
    ) {
      errors.push("height cannot be less than minH");
    }

    if (
      widget.h !== undefined &&
      widget.maxH !== undefined &&
      widget.h > widget.maxH
    ) {
      errors.push("height cannot be greater than maxH");
    }

    return {
      valid: errors.length === 0,
      errors,
    };
  }

  /**
   * Generate CSS selector validation
   */
  validateSelector(selector: string): { valid: boolean; error?: string } {
    if (!selector || typeof selector !== "string") {
      return { valid: false, error: "Selector must be a non-empty string" };
    }

    // Basic CSS selector validation
    try {
      document.querySelector(selector);
      return { valid: true };
    } catch (error) {
      return { valid: false, error: "Invalid CSS selector format" };
    }
  }

  /**
   * Generate responsive breakpoint validation
   */
  validateBreakpoints(breakpoints: any[]): {
    valid: boolean;
    errors: string[];
  } {
    const errors: string[] = [];

    if (!Array.isArray(breakpoints)) {
      errors.push("Breakpoints must be an array");
      return { valid: false, errors };
    }

    breakpoints.forEach((bp, index) => {
      if (typeof bp !== "object" || bp === null) {
        errors.push(`Breakpoint at index ${index} must be an object`);
        return;
      }

      if (typeof bp.w !== "number" || bp.w <= 0) {
        errors.push(
          `Breakpoint at index ${index} must have a positive width (w)`
        );
      }

      if (typeof bp.c !== "number" || bp.c <= 0 || !Number.isInteger(bp.c)) {
        errors.push(
          `Breakpoint at index ${index} must have a positive integer columns (c)`
        );
      }
    });

    // Check for duplicate widths
    const widths = breakpoints
      .map((bp) => bp.w)
      .filter((w) => typeof w === "number");
    const uniqueWidths = new Set(widths);
    if (widths.length !== uniqueWidths.size) {
      errors.push("Breakpoints cannot have duplicate widths");
    }

    return {
      valid: errors.length === 0,
      errors,
    };
  }

  /**
   * Generate HTML template for GridStack
   */
  generateHTMLTemplate(options: GridStackOptions = {}): string {
    const {
      class: className = "",
      column = 12,
      cellHeight = "auto",
      margin = 10,
      children = [],
    } = options;

    const gridClass = `grid-stack${className ? ` ${className}` : ""}`;

    let html = `<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  <title>GridStack Layout</title>
  <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/gridstack@12/dist/gridstack.min.css">
  <style>
    .grid-stack-item-content {
      background-color: #f8f9fa;
      border: 1px solid #dee2e6;
      border-radius: 4px;
      padding: 10px;
    }
  </style>
</head>
<body>
  <div class="${gridClass}">`;

    // Add children widgets
    children.forEach((widget) => {
      const attrs = [
        `gs-x="${widget.x || 0}"`,
        `gs-y="${widget.y || 0}"`,
        `gs-w="${widget.w || 1}"`,
        `gs-h="${widget.h || 1}"`,
      ];

      if (widget.id) attrs.push(`gs-id="${widget.id}"`);
      if (widget.minW) attrs.push(`gs-min-w="${widget.minW}"`);
      if (widget.maxW) attrs.push(`gs-max-w="${widget.maxW}"`);
      if (widget.minH) attrs.push(`gs-min-h="${widget.minH}"`);
      if (widget.maxH) attrs.push(`gs-max-h="${widget.maxH}"`);
      if (widget.locked) attrs.push(`gs-locked="true"`);
      if (widget.noResize) attrs.push(`gs-no-resize="true"`);
      if (widget.noMove) attrs.push(`gs-no-move="true"`);

      html += `
    <div class="grid-stack-item" ${attrs.join(" ")}>
      <div class="grid-stack-item-content">
        ${widget.content || `Widget ${widget.id || "Item"}`}
      </div>
    </div>`;
    });

    html += `
  </div>

  <script src="https://cdn.jsdelivr.net/npm/gridstack@12/dist/gridstack-all.js"></script>
  <script>
    const grid = GridStack.init(${JSON.stringify(options, null, 4)});
  </script>
</body>
</html>`;

    return html;
  }

  /**
   * Generate CSS for GridStack customization
   */
  generateCustomCSS(
    options: {
      cellHeight?: number | string;
      margin?: number | string;
      columns?: number;
      customColors?: {
        background?: string;
        border?: string;
        hover?: string;
      };
    } = {}
  ): string {
    const { cellHeight, margin, columns = 12, customColors } = options;

    let css = `/* GridStack Custom Styles */\n`;

    // Grid container styles
    css += `.grid-stack {\n`;
    if (margin) {
      css += `  margin: ${
        typeof margin === "number" ? `${margin}px` : margin
      };\n`;
    }
    css += `}\n\n`;

    // Cell height
    if (cellHeight) {
      css += `.grid-stack > .grid-stack-item > .grid-stack-item-content {\n`;
      css += `  min-height: ${
        typeof cellHeight === "number" ? `${cellHeight}px` : cellHeight
      };\n`;
      css += `}\n\n`;
    }

    // Custom colors
    if (customColors) {
      css += `.grid-stack-item-content {\n`;
      if (customColors.background) {
        css += `  background-color: ${customColors.background};\n`;
      }
      if (customColors.border) {
        css += `  border-color: ${customColors.border};\n`;
      }
      css += `}\n\n`;

      if (customColors.hover) {
        css += `.grid-stack-item:hover .grid-stack-item-content {\n`;
        css += `  background-color: ${customColors.hover};\n`;
        css += `}\n\n`;
      }
    }

    // Responsive columns
    if (columns !== 12) {
      css += `/* Custom ${columns}-column grid */\n`;
      for (let i = 1; i <= columns; i++) {
        const width = ((100 / columns) * i).toFixed(6);
        css += `.grid-stack > .grid-stack-item[gs-w="${i}"] { width: ${width}%; }\n`;
        css += `.grid-stack > .grid-stack-item[gs-x="${i - 1}"] { left: ${(
          (100 / columns) *
          (i - 1)
        ).toFixed(6)}%; }\n`;
      }
      css += `\n`;
    }

    return css;
  }

  private getOperationDescription(operation: string): string {
    const descriptions: Record<string, string> = {
      init: "Initialize a new GridStack instance with the specified options",
      addWidget: "Add a new widget to the grid at the specified position",
      removeWidget: "Remove a widget from the grid",
      updateWidget: "Update widget properties (position, size, constraints)",
      moveWidget: "Move a widget to a new position",
      resizeWidget: "Resize a widget to new dimensions",
      compact: "Compact the grid layout to remove gaps",
      float: "Enable or disable floating widget mode",
      column: "Change the number of columns in the grid",
      cellHeight: "Update the height of grid cells",
      margin: "Update the margin/gap between grid items",
      batchUpdate: "Enable batch update mode for efficient multiple operations",
      save: "Serialize the current grid layout to JSON",
      load: "Load a grid layout from JSON data",
      enable: "Enable or disable grid interactions",
      destroy: "Destroy the grid instance and clean up",
      getGridItems: "Get all grid items (widgets)",
      setResponsive: "Configure responsive breakpoints",
      willItFit: "Check if a widget will fit at the specified position",
      isAreaEmpty: "Check if a grid area is empty",
      getCellHeight: "Get the current cell height",
      getCellFromPixel: "Convert pixel coordinates to grid cell position",
      addEventListener: "Add an event listener for grid events",
      removeEventListener: "Remove an event listener",
      makeWidget: "Convert an existing DOM element into a grid widget",
      removeAll: "Remove all widgets from the grid",
      getMargin: "Get current margin values",
      getColumn: "Get current number of columns",
      getFloat: "Get current float mode state",
      addGrid: "Create a new grid with options and children (static method)",
    };

    return descriptions[operation] || "GridStack operation";
  }

  private getOperationExample(operation: string): string {
    const examples: Record<string, string> = {
      init: `// Initialize with basic options
const grid = GridStack.init({
  column: 12,
  cellHeight: 'auto',
  margin: 10,
  float: false
});`,
      addWidget: `// Add a widget with content
grid.addWidget({
  x: 0, y: 0, w: 3, h: 2,
  content: '<div>My Widget</div>',
  id: 'widget1'
});`,
      removeWidget: `// Remove widget by selector
grid.removeWidget('#widget1');`,
      updateWidget: `// Update widget properties
grid.update('#widget1', {
  w: 4, h: 3,
  locked: true
});`,
      moveWidget: `// Move widget to new position
grid.move('#widget1', 2, 1);`,
      resizeWidget: `// Resize widget
grid.resize('#widget1', 4, 3);`,
      save: `// Save layout to JSON
const layout = grid.save(true);
localStorage.setItem('layout', JSON.stringify(layout));`,
      load: `// Load layout from JSON
const layout = JSON.parse(localStorage.getItem('layout'));
grid.load(layout);`,
    };

    return examples[operation] || `// ${operation} example`;
  }

  private getOperationNotes(operation: string): string[] {
    const notes: Record<string, string[]> = {
      init: [
        "Grid container must have 'grid-stack' class",
        "Include GridStack CSS and JS files",
        "Options are merged with defaults",
      ],
      addWidget: [
        "Widget will be auto-positioned if x,y not specified",
        "Triggers 'added' event by default",
        "Returns the created DOM element",
      ],
      removeWidget: [
        "Can accept element, selector, or GridStackNode",
        "Set removeDOM=false to keep in DOM",
        "Triggers 'removed' event by default",
      ],
      batchUpdate: [
        "Use before multiple operations for efficiency",
        "Call with false to end batch mode",
        "Only one 'change' event fired at end",
      ],
      save: [
        "Returns array of widget configurations",
        "saveContent=true includes HTML content",
        "saveGridOpt=true includes grid options",
      ],
      load: [
        "Accepts array of widget configs or JSON string",
        "addAndRemove=true syncs with current widgets",
        "Existing widgets not in layout are removed",
      ],
      float: [
        "Float mode allows widgets to move up to fill gaps",
        "Disable for more predictable layouts",
        "Can be toggled at runtime",
      ],
      column: [
        "Changing columns re-layouts existing widgets",
        "CSS must support the new column count",
        "Use 'auto' for nested grids",
      ],
    };

    return notes[operation] || [];
  }

  private formatResponse(result: GridStackCodeResult): string {
    let response = `## GridStack ${result.operation}

${result.description}

### Generated Code:
\`\`\`javascript
${result.code}
\`\`\``;

    if (result.parameters && Object.keys(result.parameters).length > 0) {
      response += `

### Parameters:
\`\`\`json
${JSON.stringify(result.parameters, null, 2)}
\`\`\``;
    }

    if (result.example) {
      response += `

### Example:
\`\`\`javascript
${result.example}
\`\`\``;
    }

    if (result.notes && result.notes.length > 0) {
      response += `

### Notes:
${result.notes.map((note) => `- ${note}`).join("\n")}`;
    }

    return response;
  }

Tool Definition Quality

C2.9/5.0

Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries the full burden of behavioral disclosure. 'Update widget properties' implies a mutation operation, but it doesn't describe what happens during the update (e.g., whether changes are immediate, reversible, or require specific permissions), potential side effects, or error conditions. This leaves significant gaps in understanding the tool's behavior beyond basic parameter requirements.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, efficient sentence ('Update widget properties') that is front-loaded and wastes no words. It directly conveys the core action without unnecessary elaboration, making it easy to parse quickly. Every word earns its place in this minimal but clear phrasing.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the complexity of a mutation tool with no annotations and no output schema, the description is incomplete. It doesn't address behavioral aspects like what the update does to the widget, error handling, or return values. For a tool that modifies state in a system with many sibling operations, more context is needed to ensure safe and correct usage by an agent.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, with clear documentation for both parameters ('el' as widget selector/ID and 'opts' as properties to update). The description adds no additional semantic context beyond what the schema provides, such as examples of valid selectors or property combinations. With high schema coverage, the baseline score of 3 is appropriate, as the schema does the heavy lifting.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description 'Update widget properties' clearly states the verb ('update') and resource ('widget properties'), making the purpose immediately understandable. It distinguishes this from sibling tools like 'gridstack_add_widget' (creation) and 'gridstack_remove_widget' (deletion), though it doesn't explicitly differentiate from similar update tools like 'gridstack_batch_update' or 'gridstack_resize_widget'.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides no guidance on when to use this tool versus alternatives. It doesn't mention prerequisites (e.g., needing an existing widget), exclusions, or compare it to siblings like 'gridstack_batch_update' (for multiple widgets) or 'gridstack_resize_widget' (for specific property updates). Without this context, an agent must infer usage from the tool name and schema alone.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Install Server

Latest Blog Posts

Tool Definition Quality Score (TDQS)
By punkpeye on April 3, 2026.
mcp
The Hackers Who Tracked My Sleep Cycle
By punkpeye on March 26, 2026.
security
Open Source Has a Bot Problem
By punkpeye on March 19, 2026.
open source

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/raghavsharma-simpplr/gridstack-mcp-server'

If you have feedback or need assistance with the MCP directory API, please join our Discord server