Home/Getting Started/MCP Server

MCP Server

GridCraft ships an MCP (Model Context Protocol) server — an AI authoring aid. Connect it to any MCP-capable assistant (Claude Code, VS Code / Copilot, Cursor, Claude Desktop), run the create-grid prompt, answer a short interview, and get back ready-to-paste Angular code for a working grid. It also exposes the library's docs, the theme engine, and canonical examples as tools the AI can call.

AI authoring aid. Published as @gridcraft/mcp on npm — not part of the @gridcraft/angular package and never touches the library's runtime code or public API. It runs straight from TypeScript source via tsx — no build step.

How it works

An MCP server can't draw its own UI, so the "ask me questions" experience is delivered as an MCP prompt: its text instructs the host AI to interview you using its own question UI, then call the scaffold_grid tool with your answers. The result is a component .ts + .html that follows the library's conventions (standalone, OnPush, signals).

Invoking prompts

Each AI client uses a different syntax to call MCP prompts. After connecting the server (see below), use the syntax for your client — all four prompts follow the same pattern:

# Claude Code
/mcp__gridcraft__create-grid
/mcp__gridcraft__quick-start
/mcp__gridcraft__theme-grid
/mcp__gridcraft__upgrade-grid

# Cursor
/gridcraft:create-grid
/gridcraft:quick-start
/gridcraft:theme-grid
/gridcraft:upgrade-grid

# VS Code / Copilot  (type in the chat panel)
mcp.gridcraft.create-grid
mcp.gridcraft.quick-start
mcp.gridcraft.theme-grid
mcp.gridcraft.upgrade-grid

Prompts

Four guided workflows are registered — the headline entry points for AI-assisted authoring:

PromptWhat it doesOptional argument
create-grid Full interview — entity & columns, data source, features, layout, theme — then calls scaffold_grid and presents ready-to-paste .ts + .html. description — free-text grid idea; pre-fills every answer it can infer.
quick-start Fast path: detects version, shows the install snippet, asks only the essentials (columns + data source + must-have features), then generates immediately. Working code in under 5 messages. context — optional hint, e.g. "a products table with sorting".
theme-grid Theme-only flow: interviews for seed colours, calls derive_theme, and returns a full WCAG-checked GridThemeTokens set ready to bind to [themeTokens]. brand — accent / mode hint, e.g. "violet, dark mode".
upgrade-grid Version-by-version migration plan driven by CHANGELOG.md — detects current version, fetches changelog entries between from and to, highlights breaking changes, and produces an ordered checklist. from / to — version range (auto-detected if omitted).

Tools

14 tools the assistant calls during (or independently of) a prompt:

ToolPurpose
scaffold_gridGenerate a component .ts + .html (+ optional theme SCSS) from a structured spec. Runs config validation and surfaces warnings in Notes.
validate_configCheck a GridSpec for incompatible feature combinations (grouping+auto-height, live+virtual-paging, rowDrag+grouping, etc.) before generating code.
search_docsKeyword search across the 8 deep-reference docs. Default output is condensed (code blocks / tables stripped) to save tokens; pass format: "full" for complete excerpts.
get_docFull text of one doc section (00-overview … 07-workflow). Supports format: "condensed".
list_featuresThe feature matrix — what the grid supports and how to enable each capability.
list_themesBuilt-in themes plus their complete token sets.
get_theme_tokensThe themeable-token registry — every --gc-* var, its group / type / bounds.
derive_themeExpand seed colours into a full, coherent token set — the same derivation the Theme Builder runs.
list_examples / get_exampleCanonical demo code for a feature (e.g. sorting, grouping, live-stream).
detect_versionDetect the GridCraft and Angular version — checks active override → consumer package.json → library own version.
set_versionPin the active version for this session (persisted to ~/.gridcraft-mcp/config.json). Affects scaffold annotations and the upgrade prompt.
list_versionsAll versions recorded in CHANGELOG.md, newest first.
list_changesChangelog entries between two versions — drives the upgrade-grid migration prompt.

Resources

14 read-only resources the AI can attach to its context: gridcraft://docs/{00-overview…07-workflow} (8), gridcraft://themes/registry, gridcraft://themes/base/{default|dark}, gridcraft://api/public, gridcraft://changelog, and gridcraft://version. All knowledge is read at runtime from live source files — never duplicated, never out of sync.

Connecting a client

Add the server once — then use it from any AI client.

claude mcp add gridcraft -- npx gridcraft-mcp

Version & migration

detect_version reads the consumer's package.json for @gridcraft/angular (falling back to the library's own version when working inside the repo). set_version pins an override for the session. The upgrade-grid prompt chains these together with list_changes to produce a step-by-step migration plan from CHANGELOG.md.

# Claude Code
/mcp__gridcraft__upgrade-grid

# Cursor
/gridcraft:upgrade-grid

# VS Code / Copilot
mcp.gridcraft.upgrade-grid

Quick-start

The fastest path to working code — no long interview:

# Claude Code
/mcp__gridcraft__quick-start a products table with price and stock columns

# Cursor
/gridcraft:quick-start a products table with price and stock columns

# VS Code / Copilot
mcp.gridcraft.quick-start a products table with price and stock columns

Full interview in action

Invoke the create-grid prompt for the full guided experience:

# Claude Code
/mcp__gridcraft__create-grid an invoices table with a status filter,
  multi-select, CSV export, and a dark theme

# Cursor
/gridcraft:create-grid an invoices table with a status filter,
  multi-select, CSV export, and a dark theme

# VS Code / Copilot
mcp.gridcraft.create-grid an invoices table with a status filter,
  multi-select, CSV export, and a dark theme
AI: A few questions to build your grid —
  1. What's the row entity, and which columns? (key, label, type)
  2. Static in-memory data or an HTTP endpoint?
  3. Which features: selection, grouping, filtering, expansion,
     export, live updates, …?
  4. Layout — height, scroll mode, page size, row height?
  5. Theme — a built-in ("default" / "dark") or seed colours?

You: Invoice { id, customer, amount, status, dueDate } from
     /api/invoices. Multi-select, a status filter, CSV export,
     paging at 25/page, dark theme.

AI: → calls scaffold_grid → returns invoices.ts + invoices.html

What you get back

A trimmed example of the generated component for the invoices grid above:

import { ChangeDetectionStrategy, Component } from '@angular/core';
import { GridcraftComponent, GridColumn, GridConfig, GridDataSource } from '@gridcraft/angular';

interface Invoice {
  id: number; customer: string; amount: number;
  status: string; dueDate: string;
}

@Component({
  selector: 'app-invoices',
  standalone: true,
  changeDetection: ChangeDetectionStrategy.OnPush,
  imports: [GridcraftComponent],
  templateUrl: './invoices.html',
})
export class InvoicesComponent {
  readonly columns: GridColumn<Invoice>[] = [
    { key: 'id',       name: 'ID',       prop: 'id',       width: 80, sortable: true },
    { key: 'customer', name: 'Customer', prop: 'customer', sortable: true,
      filter: { type: 'text' } },
    { key: 'amount',   name: 'Amount',   prop: 'amount',   sortable: true },
    { key: 'status',   name: 'Status',   prop: 'status',
      filter: { type: 'select', options: [/* … */] } },
    { key: 'dueDate',  name: 'Due',      prop: 'dueDate',  sortable: true },
  ];

  readonly config: GridConfig<Invoice> = {
    scrollMode: 'paging',
    pageSize: 25,
    theme: 'dark',
    filterMode: 'row',
    rowSelection: { mode: 'multi' },
    export: { formats: ['csv'] },
  };

  readonly dataSource: GridDataSource<Invoice> = { /* HTTP fetchRows(...) */ };
}
<gridcraft
  [columns]="columns"
  [dataSource]="dataSource"
  [config]="config"
  (selectionChange)="onSelection($event)"
/>

Verifying

Browse and call every tool, resource, and prompt interactively with the official inspector:

npx @modelcontextprotocol/inspector npx gridcraft-mcp