GridStack MCP Server

Instructions

Implementation Reference

• src/tools/index.ts:1011-1023 (handler)

  The main handler function for the 'gridstack_load' tool. It destructures the input parameters, prepares the layout data as a JSON string if necessary, constructs the GridStack 'load' method call as a JavaScript string, and delegates to the shared utility to generate the full executable code response.
  private async load(params: LoadGridParams): Promise<string> { const { layout, addAndRemove = true } = params; const layoutData = typeof layout === "string" ? layout : JSON.stringify(layout, null, 2); const codeString = `grid.load(${layoutData}, ${addAndRemove});`; return this.utils.generateGridStackCode("load", { layout: layoutData, addAndRemove, code: codeString, }); }
• src/tools/index.ts:416-442 (schema)

  The input schema definition for the 'gridstack_load' tool, specifying the expected parameters including the required 'layout' (array of widget configs or JSON string) and optional 'addAndRemove' boolean.
  name: "gridstack_load", description: "Load grid layout from JSON", inputSchema: { type: "object", required: ["layout"], properties: { layout: { oneOf: [ { type: "array", items: { type: "object", description: "Widget configuration", }, }, { type: "string" }, ], description: "Layout data (JSON array or string)", }, addAndRemove: { type: "boolean", description: "Add new widgets and remove missing ones", default: true, }, }, }, },
• src/tools/index.ts:807-808 (registration)

  The switch case in the central callTool dispatcher that routes calls to the 'gridstack_load' handler by invoking the load method with typed arguments.
  case "gridstack_load": return this.load(args as LoadGridParams);
• src/tools/index.ts:32-762 (registration)

  The tool is registered by including its definition (name, description, schema) in the listTools() method's return array, which provides the tool list to the MCP protocol.
  return [ // Core Grid Management { name: "gridstack_init", description: "Initialize a new GridStack instance with specified options", inputSchema: { type: "object", properties: { selector: { type: "string", description: "CSS selector for the grid container element", default: ".grid-stack", }, options: { type: "object", description: "GridStack initialization options", properties: { acceptWidgets: { oneOf: [{ type: "boolean" }, { type: "string" }], description: "Accept widgets from other grids or external elements", }, alwaysShowResizeHandle: { type: "boolean", description: "Always show resize handles", }, animate: { type: "boolean", description: "Enable animations", }, auto: { type: "boolean", description: "Auto-position widgets", }, cellHeight: { oneOf: [{ type: "number" }, { type: "string" }], description: "Cell height (px, 'auto', 'initial', CSS units)", }, cellHeightThrottle: { type: "number", description: "Throttle time for cellHeight='auto' (ms)", }, column: { oneOf: [ { type: "number" }, { type: "string", enum: ["auto"] }, ], description: "Number of columns or 'auto' for nested grids", }, disableDrag: { type: "boolean", description: "Disable dragging of widgets", }, disableResize: { type: "boolean", description: "Disable resizing of widgets", }, float: { type: "boolean", description: "Enable floating widgets", }, handle: { type: "string", description: "Draggable handle selector", }, margin: { oneOf: [{ type: "number" }, { type: "string" }], description: "Gap between grid items (px or CSS units)", }, maxRow: { type: "number", description: "Maximum number of rows", }, minRow: { type: "number", description: "Minimum number of rows", }, removable: { oneOf: [{ type: "boolean" }, { type: "string" }], description: "Allow widgets to be removed by dragging out", }, rtl: { type: "boolean", description: "Right-to-left support", }, staticGrid: { type: "boolean", description: "Make grid static (no drag/resize)", }, }, }, }, }, }, // Widget Management { name: "gridstack_add_widget", description: "Add a new widget to the grid", inputSchema: { type: "object", required: ["widget"], properties: { widget: { type: "object", description: "Widget configuration", properties: { id: { oneOf: [{ type: "string" }, { type: "number" }], description: "Unique widget identifier", }, x: { type: "number", description: "X position" }, y: { type: "number", description: "Y position" }, w: { type: "number", description: "Width in columns" }, h: { type: "number", description: "Height in rows" }, minW: { type: "number", description: "Minimum width" }, maxW: { type: "number", description: "Maximum width" }, minH: { type: "number", description: "Minimum height" }, maxH: { type: "number", description: "Maximum height" }, locked: { type: "boolean", description: "Lock widget position/size", }, noResize: { type: "boolean", description: "Disable resizing" }, noMove: { type: "boolean", description: "Disable moving" }, autoPosition: { type: "boolean", description: "Auto-position widget", }, resizeToContent: { type: "boolean", description: "Resize to content", }, content: { type: "string", description: "Widget HTML content" }, }, }, triggerAddEvent: { type: "boolean", description: "Trigger 'added' event", default: true, }, }, }, }, { name: "gridstack_remove_widget", description: "Remove a widget from the grid", inputSchema: { type: "object", required: ["el"], properties: { el: { type: "string", description: "Widget selector or ID to remove", }, removeDOM: { type: "boolean", description: "Remove from DOM as well", default: true, }, triggerEvent: { type: "boolean", description: "Trigger 'removed' event", default: true, }, }, }, }, { name: "gridstack_update_widget", description: "Update widget properties", 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" }, }, }, }, }, }, { name: "gridstack_move_widget", description: "Move a widget to a new position", inputSchema: { type: "object", required: ["el"], properties: { el: { type: "string", description: "Widget selector or ID to move", }, x: { type: "number", description: "New X position", }, y: { type: "number", description: "New Y position", }, }, }, }, { name: "gridstack_resize_widget", description: "Resize a widget", inputSchema: { type: "object", required: ["el"], properties: { el: { type: "string", description: "Widget selector or ID to resize", }, width: { type: "number", description: "New width in columns", }, height: { type: "number", description: "New height in rows", }, }, }, }, // Layout Management { name: "gridstack_compact", description: "Compact the grid layout", inputSchema: { type: "object", properties: { layout: { type: "string", enum: ["moveScale", "move", "scale", "none", "list"], description: "Compact layout type", default: "moveScale", }, doSort: { type: "boolean", description: "Sort widgets before compacting", default: true, }, }, }, }, { name: "gridstack_float", description: "Enable or disable floating widgets", inputSchema: { type: "object", properties: { val: { type: "boolean", description: "Enable floating (true) or disable (false)", }, }, }, }, { name: "gridstack_column", description: "Change the number of columns", inputSchema: { type: "object", required: ["column"], properties: { column: { oneOf: [{ type: "number" }, { type: "string", enum: ["auto"] }], description: "Number of columns or 'auto'", }, layout: { type: "string", enum: ["moveScale", "move", "scale", "none", "list"], description: "How to re-layout widgets", default: "moveScale", }, }, }, }, { name: "gridstack_cell_height", description: "Update cell height", inputSchema: { type: "object", properties: { val: { oneOf: [{ type: "number" }, { type: "string" }], description: "New cell height (px, 'auto', 'initial', CSS units)", }, update: { type: "boolean", description: "Update existing widgets", default: true, }, }, }, }, { name: "gridstack_margin", description: "Update grid margin/gap", inputSchema: { type: "object", required: ["value"], properties: { value: { oneOf: [{ type: "number" }, { type: "string" }], description: "Margin value (px or CSS format)", }, unit: { type: "string", description: "CSS unit (px, em, rem, etc.)", default: "px", }, }, }, }, // Batch Operations { name: "gridstack_batch_update", description: "Enable/disable batch update mode for efficiency", inputSchema: { type: "object", properties: { flag: { type: "boolean", description: "Enable (true) or disable (false) batch mode", default: true, }, }, }, }, // Serialization { name: "gridstack_save", description: "Save grid layout to JSON", inputSchema: { type: "object", properties: { saveContent: { type: "boolean", description: "Include widget content in save", default: true, }, saveGridOpt: { type: "boolean", description: "Include grid options in save", default: false, }, }, }, }, { name: "gridstack_load", description: "Load grid layout from JSON", inputSchema: { type: "object", required: ["layout"], properties: { layout: { oneOf: [ { type: "array", items: { type: "object", description: "Widget configuration", }, }, { type: "string" }, ], description: "Layout data (JSON array or string)", }, addAndRemove: { type: "boolean", description: "Add new widgets and remove missing ones", default: true, }, }, }, }, // Grid State { name: "gridstack_enable", description: "Enable or disable the grid", inputSchema: { type: "object", properties: { doEnable: { type: "boolean", description: "Enable (true) or disable (false) the grid", default: true, }, }, }, }, { name: "gridstack_destroy", description: "Destroy the grid instance", inputSchema: { type: "object", properties: { removeDOM: { type: "boolean", description: "Remove DOM elements", default: false, }, }, }, }, { name: "gridstack_get_grid_items", description: "Get all grid items", inputSchema: { type: "object", properties: { onlyVisible: { type: "boolean", description: "Only return visible items", default: false, }, }, }, }, // Responsive Features { name: "gridstack_set_responsive", description: "Configure responsive breakpoints", inputSchema: { type: "object", required: ["breakpoints"], properties: { breakpoints: { type: "array", items: { type: "object", required: ["w", "c"], properties: { w: { type: "number", description: "Window width breakpoint", }, c: { type: "number", description: "Number of columns at this breakpoint", }, }, }, description: "Array of breakpoint configurations", }, }, }, }, // Utility Functions { name: "gridstack_will_it_fit", description: "Check if a widget will fit at specified position", inputSchema: { type: "object", required: ["widget"], properties: { widget: { type: "object", required: ["x", "y", "w", "h"], properties: { x: { type: "number", description: "X position" }, y: { type: "number", description: "Y position" }, w: { type: "number", description: "Width" }, h: { type: "number", description: "Height" }, id: { oneOf: [{ type: "string" }, { type: "number" }], description: "Widget ID to ignore in collision check", }, }, }, }, }, }, { name: "gridstack_is_area_empty", description: "Check if an area is empty", inputSchema: { type: "object", required: ["x", "y", "w", "h"], properties: { x: { type: "number", description: "X position" }, y: { type: "number", description: "Y position" }, w: { type: "number", description: "Width" }, h: { type: "number", description: "Height" }, }, }, }, { name: "gridstack_get_cell_height", description: "Get current cell height", inputSchema: { type: "object", properties: {}, }, }, { name: "gridstack_get_cell_from_pixel", description: "Convert pixel coordinates to grid cell position", inputSchema: { type: "object", required: ["position"], properties: { position: { type: "object", required: ["top", "left"], properties: { top: { type: "number", description: "Top pixel position" }, left: { type: "number", description: "Left pixel position" }, }, }, useOffset: { type: "boolean", description: "Use offset coordinates", default: false, }, }, }, }, // Event Management { name: "gridstack_on", description: "Add event listener", inputSchema: { type: "object", required: ["eventName", "callback"], properties: { eventName: { type: "string", enum: [ "added", "change", "disable", "drag", "dragstart", "dragstop", "dropped", "enable", "removed", "resize", "resizestart", "resizestop", ], description: "Event name to listen for", }, callback: { type: "string", description: "JavaScript callback function code", }, }, }, }, { name: "gridstack_off", description: "Remove event listener", inputSchema: { type: "object", required: ["eventName"], properties: { eventName: { type: "string", enum: [ "added", "change", "disable", "drag", "dragstart", "dragstop", "dropped", "enable", "removed", "resize", "resizestart", "resizestop", ], description: "Event name to remove listener for", }, }, }, }, // Advanced Features { name: "gridstack_make_widget", description: "Convert an existing DOM element into a grid widget", inputSchema: { type: "object", required: ["el"], properties: { el: { type: "string", description: "Element selector to convert", }, options: { type: "object", description: "Widget options", properties: { x: { type: "number" }, y: { type: "number" }, w: { type: "number" }, h: { type: "number" }, autoPosition: { type: "boolean" }, minW: { type: "number" }, maxW: { type: "number" }, minH: { type: "number" }, maxH: { type: "number" }, locked: { type: "boolean" }, noResize: { type: "boolean" }, noMove: { type: "boolean" }, }, }, }, }, }, { name: "gridstack_remove_all", description: "Remove all widgets from the grid", inputSchema: { type: "object", properties: { removeDOM: { type: "boolean", description: "Remove DOM elements", default: true, }, }, }, }, { name: "gridstack_get_margin", description: "Get current margin values", inputSchema: { type: "object", properties: {}, }, }, { name: "gridstack_get_column", description: "Get current number of columns", inputSchema: { type: "object", properties: {}, }, }, { name: "gridstack_get_float", description: "Get current float state", inputSchema: { type: "object", properties: {}, }, }, { name: "gridstack_add_grid", description: "Create a new grid with options and children (static method)", inputSchema: { type: "object", required: ["parent"], properties: { parent: { type: "string", description: "Parent element selector", }, opt: { type: "object", description: "Grid options including children", properties: { children: { type: "array", items: { type: "object", description: "Child widget configuration", }, description: "Array of child widgets to load", }, }, }, }, }, }, ];
• src/tools/index.ts:1021-1023 (helper)

  Invocation of the shared GridStackUtils helper method generateGridStackCode, which formats the response with documentation, parameters, and the generated JS code for execution.
  code: codeString, }); }