raghavsharma-simpplr/gridstack-mcp-server

git clone <repository-url>
cd gridstack-mcp-server

yarn install
# or
npm install

yarn build
# or
npm run build

# Build and start the server
yarn build && yarn start

# Development mode with auto-rebuild
yarn dev

{
  "mcpServers": {
    "gridstack": {
      "command": "node",
      "args": ["/path/to/gridstack-mcp-server/dist/index.js"]
    }
  }
}

{
  "mcp.servers": {
    "gridstack": {
      "command": "node",
      "args": ["./dist/index.js"],
      "cwd": "/path/to/gridstack-mcp-server"
    }
  }
}

# List available tools
echo '{"jsonrpc": "2.0", "id": 1, "method": "tools/list"}' | node dist/index.js

# Initialize a grid
echo '{"jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": {"name": "gridstack_init", "arguments": {"options": {"column": 12, "cellHeight": "auto"}}}}' | node dist/index.js

# List resources
echo '{"jsonrpc": "2.0", "id": 1, "method": "resources/list"}' | node dist/index.js

// Initialize a 12-column grid with auto height
const grid = GridStack.init({
  column: 12,
  cellHeight: "auto",
  margin: 10,
  float: false,
});

// Add a widget with specific position and size
grid.addWidget({
  x: 0,
  y: 0,
  w: 3,
  h: 2,
  content: '<div class="my-widget">Content</div>',
  id: "widget1",
});

// Set up responsive breakpoints
grid.setResponsive([
  { w: 768, c: 1 }, // Mobile: 1 column
  { w: 992, c: 6 }, // Tablet: 6 columns
  { w: 1200, c: 12 }, // Desktop: 12 columns
]);

// Save current layout
const layout = grid.save(true);
localStorage.setItem("dashboard-layout", JSON.stringify(layout));

// Load saved layout
const savedLayout = JSON.parse(localStorage.getItem("dashboard-layout"));
grid.load(savedLayout);

# Install Tailwind CSS
npm install -D tailwindcss @tailwindcss/forms @tailwindcss/typography
npx tailwindcss init

// tailwind.config.js
module.exports = {
  content: ["./src/**/*.{html,js,ts,jsx,tsx}"],
  theme: {
    extend: {
      gridTemplateColumns: {
        "gs-1": "repeat(1, minmax(0, 1fr))",
        "gs-2": "repeat(2, minmax(0, 1fr))",
        "gs-3": "repeat(3, minmax(0, 1fr))",
        "gs-4": "repeat(4, minmax(0, 1fr))",
        "gs-5": "repeat(5, minmax(0, 1fr))",
        "gs-6": "repeat(6, minmax(0, 1fr))",
        "gs-7": "repeat(7, minmax(0, 1fr))",
        "gs-8": "repeat(8, minmax(0, 1fr))",
        "gs-9": "repeat(9, minmax(0, 1fr))",
        "gs-10": "repeat(10, minmax(0, 1fr))",
        "gs-11": "repeat(11, minmax(0, 1fr))",
        "gs-12": "repeat(12, minmax(0, 1fr))",
      },
    },
  },
  plugins: [],
};

/* Custom GridStack + Tailwind integration */
.grid-stack {
  @apply relative;
}

.grid-stack-item {
  @apply absolute transition-all duration-200 ease-in-out;
}

.grid-stack-item-content {
  @apply h-full w-full rounded-lg border border-gray-200 bg-white p-4 shadow-sm hover:shadow-md;
}

.grid-stack-item-content.ui-draggable-dragging {
  @apply shadow-lg ring-2 ring-blue-500 ring-opacity-50;
}

.grid-stack-item-content.ui-resizable-resizing {
  @apply shadow-lg ring-2 ring-green-500 ring-opacity-50;
}

/* Responsive grid utilities */
.grid-stack-1 {
  @apply grid-cols-gs-1;
}
.grid-stack-2 {
  @apply grid-cols-gs-2;
}
.grid-stack-3 {
  @apply grid-cols-gs-3;
}
.grid-stack-4 {
  @apply grid-cols-gs-4;
}
.grid-stack-5 {
  @apply grid-cols-gs-5;
}
.grid-stack-6 {
  @apply grid-cols-gs-6;
}
.grid-stack-7 {
  @apply grid-cols-gs-7;
}
.grid-stack-8 {
  @apply grid-cols-gs-8;
}
.grid-stack-9 {
  @apply grid-cols-gs-9;
}
.grid-stack-10 {
  @apply grid-cols-gs-10;
}
.grid-stack-11 {
  @apply grid-cols-gs-11;
}
.grid-stack-12 {
  @apply grid-cols-gs-12;
}

<!-- Modern Dashboard Widget -->
<div class="grid-stack-item" gs-x="0" gs-y="0" gs-w="4" gs-h="3">
  <div
    class="grid-stack-item-content bg-gradient-to-br from-blue-50 to-indigo-100 border-indigo-200"
  >
    <div class="flex items-center justify-between mb-4">
      <h3 class="text-lg font-semibold text-gray-900">Sales Overview</h3>
      <div class="flex space-x-2">
        <button class="p-1 text-gray-400 hover:text-gray-600">
          <svg class="w-4 h-4" fill="currentColor" viewBox="0 0 20 20">
            <path
              d="M10 6a2 2 0 110-4 2 2 0 010 4zM10 12a2 2 0 110-4 2 2 0 010 4zM10 18a2 2 0 110-4 2 2 0 010 4z"
            />
          </svg>
        </button>
      </div>
    </div>
    <div class="space-y-3">
      <div class="flex justify-between items-center">
        <span class="text-sm text-gray-600">This Month</span>
        <span class="text-2xl font-bold text-indigo-600">$24,500</span>
      </div>
      <div class="w-full bg-gray-200 rounded-full h-2">
        <div class="bg-indigo-600 h-2 rounded-full" style="width: 75%"></div>
      </div>
      <p class="text-sm text-green-600">↗ +12% from last month</p>
    </div>
  </div>
</div>

/* Widget.module.css */
.widget {
  background: linear-gradient(135deg, #667eea 0%, #764ba2 100%);
  border-radius: 12px;
  padding: 1.5rem;
  color: white;
  box-shadow: 0 4px 6px rgba(0, 0, 0, 0.1);
  transition: transform 0.2s ease-in-out;
}

.widget:hover {
  transform: translateY(-2px);
  box-shadow: 0 8px 15px rgba(0, 0, 0, 0.2);
}

.widgetHeader {
  display: flex;
  justify-content: space-between;
  align-items: center;
  margin-bottom: 1rem;
  padding-bottom: 0.5rem;
  border-bottom: 1px solid rgba(255, 255, 255, 0.2);
}

.widgetTitle {
  font-size: 1.125rem;
  font-weight: 600;
  margin: 0;
}

.widgetValue {
  font-size: 2rem;
  font-weight: 700;
  margin: 0.5rem 0;
}

.widgetChart {
  flex: 1;
  background: rgba(255, 255, 255, 0.1);
  border-radius: 8px;
  display: flex;
  align-items: center;
  justify-content: center;
  min-height: 120px;
}

// Widget.jsx
import styles from "./Widget.module.css";

const Widget = ({ title, value, change, children }) => {
  return (
    <div className="grid-stack-item" gs-w="3" gs-h="2">
      <div className={`grid-stack-item-content ${styles.widget}`}>
        <div className={styles.widgetHeader}>
          <h3 className={styles.widgetTitle}>{title}</h3>
        </div>
        <div className={styles.widgetValue}>{value}</div>
        {change && <p className={styles.widgetChange}>{change}</p>}
        {children && <div className={styles.widgetChart}>{children}</div>}
      </div>
    </div>
  );
};

// Define custom widget templates
const widgetTemplates = {
  chart: {
    w: 4,
    h: 3,
    content: '<div class="chart-widget">Chart Content</div>',
    minW: 2,
    minH: 2,
  },
  kpi: {
    w: 2,
    h: 2,
    content: '<div class="kpi-widget">KPI Content</div>',
    noResize: true,
  },
};

// Use templates
grid.addWidget(widgetTemplates.chart);

// Listen to grid events
grid.on("change", (event, items) => {
  console.log("Layout changed:", items);
  // Auto-save layout
  localStorage.setItem("layout", JSON.stringify(grid.save()));
});

grid.on("added", (event, items) => {
  console.log("Widget added:", items);
});

grid.on("removed", (event, items) => {
  console.log("Widget removed:", items);
});

// Batch multiple operations
grid.batchUpdate(true);
grid.addWidget(widget1);
grid.addWidget(widget2);
grid.addWidget(widget3);
grid.batchUpdate(false); // Triggers single 'change' event

import { useEffect, useRef, useState } from "react";
import { GridStack } from "gridstack";

export const useGridStack = (options = {}) => {
  const gridRef = useRef(null);
  const [grid, setGrid] = useState(null);

  useEffect(() => {
    if (gridRef.current) {
      const gridInstance = GridStack.init(options, gridRef.current);
      setGrid(gridInstance);

      return () => gridInstance.destroy();
    }
  }, []);

  return { gridRef, grid };
};

// useGridStack.js
import { ref, onMounted, onUnmounted } from "vue";
import { GridStack } from "gridstack";

export function useGridStack(options = {}) {
  const gridRef = ref(null);
  const grid = ref(null);

  onMounted(() => {
    if (gridRef.value) {
      grid.value = GridStack.init(options, gridRef.value);
    }
  });

  onUnmounted(() => {
    grid.value?.destroy();
  });

  return { gridRef, grid };
}

interface GridStackWidget {
  id?: string | number;
  x?: number; // X position (0-based)
  y?: number; // Y position (0-based)
  w?: number; // Width in columns
  h?: number; // Height in rows
  minW?: number; // Minimum width
  maxW?: number; // Maximum width
  minH?: number; // Minimum height
  maxH?: number; // Maximum height
  locked?: boolean; // Lock position/size
  noResize?: boolean; // Disable resizing
  noMove?: boolean; // Disable moving
  content?: string; // HTML content
}

interface GridStackOptions {
  column?: number; // Number of columns (default: 12)
  cellHeight?: number | string; // Cell height ('auto', px, etc.)
  margin?: number | string; // Gap between items
  float?: boolean; // Enable floating widgets
  disableDrag?: boolean; // Disable dragging
  disableResize?: boolean; // Disable resizing
  animate?: boolean; // Enable animations
  acceptWidgets?: boolean; // Accept external widgets
}