MCP Server

The @gridstorm/mcp-server package exposes GridStorm's grid, PDF, and AI capabilities as tools that AI agents can invoke through the Model Context Protocol. This lets Claude, GPT, and other AI assistants create grids, sort and filter data, export CSV files, and run aggregations without writing code.

Installation

pnpm add @gridstorm/mcp-server

:::example{title="MCP Server Demo" href="/feature-showcase/"} See GridStorm features in action through the Feature Showcase. The MCP server exposes these same capabilities to AI assistants. :::

Quick Start

import { createMCPServer, handleToolCall, listTools } from '@gridstorm/mcp-server';

// Create the server registry
const server = createMCPServer();

// List all available tools
const tools = listTools(server);
console.log(tools.map(t => t.name));

// Handle a tool call from an AI agent
const result = await handleToolCall(server, 'grid_create', {
  columns: [
    { field: 'name', headerName: 'Name' },
    { field: 'revenue', headerName: 'Revenue' },
  ],
  rowData: [
    { name: 'Acme Corp', revenue: 50000 },
    { name: 'Globex', revenue: 75000 },
    { name: 'Initech', revenue: 30000 },
  ],
});

Server Configuration

interface MCPServerConfig {
  name?: string;      // Server name identifier
  version?: string;   // Server version string
  gridApi?: any;      // External GridApi instance (reserved)
  pdfApi?: any;       // External PdfApi instance (reserved)
}

Grid Tools

These tools are fully functional and operate on in-memory grid engine instances.

grid_create

Create a new data grid with columns and row data.

{
  "columns": [
    { "field": "name", "headerName": "Name", "width": 200 },
    { "field": "price", "headerName": "Price" }
  ],
  "rowData": [
    { "name": "Widget A", "price": 29.99 },
    { "name": "Widget B", "price": 49.99 }
  ],
  "gridId": "my-grid"
}

grid_sort

Apply sorting to a grid by one or more columns.

{
  "sortModel": [
    { "colId": "price", "sort": "desc" }
  ],
  "gridId": "my-grid"
}

grid_filter

Apply filters to grid data.

{
  "filterModel": {
    "price": { "type": "greaterThan", "filter": 30 }
  },
  "gridId": "my-grid"
}

grid_get_data

Get filtered and sorted grid data with pagination.

{
  "pageSize": 50,
  "page": 0,
  "gridId": "my-grid"
}

grid_aggregate

Compute an aggregation function on a column.

{
  "columnId": "revenue",
  "function": "sum",
  "gridId": "my-grid"
}

grid_export_csv

Export grid data to CSV format.

{
  "fileName": "report.csv",
  "columnKeys": ["name", "revenue"],
  "gridId": "my-grid"
}

Multi-Grid Sessions

The MCP server supports multiple simultaneous grid instances identified by gridId. Each tool accepts an optional gridId parameter.

• If gridId is omitted, the 'default' grid is used.
• Creating a grid with an existing gridId destroys the previous instance.
• Maximum 50 grids can exist simultaneously.
• When the limit is reached, the oldest grid is evicted (LRU policy).

// Create two separate grids
await handleToolCall(server, 'grid_create', {
  gridId: 'sales',
  columns: [{ field: 'region' }, { field: 'amount' }],
  rowData: salesData,
});

await handleToolCall(server, 'grid_create', {
  gridId: 'inventory',
  columns: [{ field: 'sku' }, { field: 'stock' }],
  rowData: inventoryData,
});

// Sort each independently
await handleToolCall(server, 'grid_sort', {
  gridId: 'sales',
  sortModel: [{ colId: 'amount', sort: 'desc' }],
});

await handleToolCall(server, 'grid_aggregate', {
  gridId: 'inventory',
  columnId: 'stock',
  function: 'sum',
});

PDF Tools (Planned)

The server defines PDF tool schemas but requires a configured PdfParser backend to function. The following tools return a configuration hint until a parser is provided:

AI Tools (Planned)

AI-powered PDF analysis tools that combine the PDF engine with ML backends:

Tool Response Format

Every tool returns a ToolResult object:

interface ToolResult {
  success: boolean;
  data?: any;     // Tool-specific response data
  error?: string; // Error message if success is false
}

Successful grid operations return contextual data:

{
  "success": true,
  "data": {
    "message": "Grid created",
    "gridId": "sales",
    "columns": 3,
    "rows": 150
  }
}

{
  "success": true,
  "data": {
    "columnId": "revenue",
    "function": "sum",
    "result": 155000,
    "count": 3
  }
}

Usage with Claude

To use the GridStorm MCP server with Claude or another AI assistant, register the tools in your MCP configuration:

import { createMCPServer, handleToolCall } from '@gridstorm/mcp-server';

const server = createMCPServer({ name: 'gridstorm', version: '1.0.0' });

// Register tool definitions with your MCP host
for (const tool of server.tools) {
  mcpHost.registerTool({
    name: tool.name,
    description: tool.description,
    inputSchema: tool.inputSchema,
    handler: (input) => handleToolCall(server, tool.name, input),
  });
}

An AI agent can then perform data analysis tasks conversationally:

1. "Create a grid from this sales data"
2. "Sort by revenue descending"
3. "Filter to only show Q4 results"
4. "What is the average revenue?"
5. "Export the filtered data as CSV"

Next Steps

• PDF Toolkit -- Learn about the PDF engine that powers the planned PDF tools
• Integration Guide -- Add GridStorm to your existing project
• Custom Plugins -- Extend grid and PDF functionality with plugins