GridStack MCP Server

Instructions

Implementation Reference

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

  The primary handler function for the 'gridstack_load' tool. It processes the input parameters, formats the layout data, generates the GridStack.js 'grid.load()' code snippet, and uses the utility to format a complete response with description, example, and notes.

  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:415-442 (registration)

  The tool registration entry in listTools(), including the name, description, and complete input JSON schema for validation.

  {
    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/types.ts:211-214 (schema)

  TypeScript interface defining the expected input parameters, matching the JSON schema, used for type safety in the handler.

  export interface LoadGridParams {
    layout: GridStackWidget[] | string;
    addAndRemove?: boolean;
  }

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

  The helper method that formats the final response for all tools, including documentation, parameters, code example, and notes specific to the 'load' 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;
    }

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

  Core utility method called by all tool handlers to generate standardized markdown responses with operation-specific descriptions, examples, and notes for 'load'.

  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);
  }