@gridcraft/mcp
v1.0.0
Published
MCP server — AI authoring aid for GridCraft grids.
Readme
@gridcraft/mcp
An MCP server that helps AI assistants build grids with
@gridcraft/angular. Run one prompt, answer a
short interview, and get back ready-to-paste Angular code that compiles. The assistant can also read
the GridCraft docs pages, their code samples, and the theme engine while it works.
It is a separate package from @gridcraft/angular and never touches the grid's runtime code. A copy of
the docs ships inside the package, so the server works offline and describes the version it was
released with.
Connecting a client
Claude Code
claude mcp add gridcraft -- npx @gridcraft/mcpVS Code / Copilot — .vscode/mcp.json
{
"servers": {
"gridcraft": { "command": "npx", "args": ["@gridcraft/mcp"] }
}
}Cursor — .cursor/mcp.json (project) or ~/.cursor/mcp.json (global)
{
"mcpServers": {
"gridcraft": { "command": "npx", "args": ["@gridcraft/mcp"] }
}
}Claude Desktop — claude_desktop_config.json
{
"mcpServers": {
"gridcraft": { "command": "npx", "args": ["@gridcraft/mcp"] }
}
}Node 18 or later.
Prompts (4)
An MCP server can't draw its own UI, so these prompts instruct the host AI to ask the questions in its own question UI, then call the tools below.
| Prompt | What it does | Argument |
|---|---|---|
| create-grid | Full interview — entity & columns, data source, features, layout, theme — then validate_config and scaffold_grid, and presents the .ts + .html. | description — free-text grid idea; pre-fills every answer it can infer. |
| quick-start | Fast path: shows the install lines, asks only the essentials (columns, data source, must-have features), then generates immediately. | context — optional hint, e.g. "a products table with sorting". |
| theme-grid | Interviews for brand colours, then derives 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 from the package's changelog — breaking changes first, then an ordered checklist. | from / to — version range (detected if omitted). |
How each client invokes a prompt:
| Client | Syntax |
|---|---|
| Claude Code | /mcp__gridcraft__create-grid an invoices table with a status filter |
| Cursor | /gridcraft:create-grid an invoices table with a status filter |
| VS Code / Copilot | mcp.gridcraft.create-grid an invoices table with a status filter |
Tools (14)
| Tool | Purpose |
|---|---|
| scaffold_grid | Generate a component .ts + .html (+ optional theme SCSS) from a structured spec, importing from @gridcraft/angular. Runs validate_config first and lists any warning in its notes. |
| validate_config | Check a spec for options that don't work together — for example managed row drag under a client-side sort. Returns { valid, findings[] }; each finding has a level, a code, a message and a fix. |
| search_docs | Keyword search across the docs pages. Condensed by default; format: "full" for complete excerpts. |
| get_doc | One docs page as markdown, by its path (features/sorting, or just sorting). |
| list_features | Every docs page, grouped by section, with a one-line summary. |
| list_examples / get_example | The code samples of a docs page, exactly as the page shows them. |
| list_themes | The default and dark themes with their complete token sets. |
| get_theme_tokens | The themeable-token registry — every --gc-* variable, its group, type and bounds. |
| derive_theme | Expand seed colours into a full token set, with a contrast report. |
| detect_version | The @gridcraft/angular and Angular versions: an active override, then your package.json, then the version these docs describe (source: "snapshot"). |
| set_version | Pin the version detect_version reports (saved to ~/.gridcraft-mcp/config.json) — the starting point of upgrade-grid. |
| list_versions | Every release in the package's changelog, newest first. |
| list_changes | The changelog entries between two versions. |
scaffold_grid covers the options documented for the grid: columns (sortable, filterable, editable,
pinned), a filter row or popup filters, row selection, row expansion, row drag, CSV export, cell flash on
applyTransaction(), keyboard navigation, infinite or paged scrolling, and the built-in themes
(default, material, dark, hero, hero-dark) or seed colours.
Resources
gridcraft://docs/<page>— one per docs page, e.g.gridcraft://docs/features/sortinggridcraft://themes/registry,gridcraft://themes/base/default,gridcraft://themes/base/darkgridcraft://api/public— the names@gridcraft/angularexports for the features documented heregridcraft://changelog— the package's public changeloggridcraft://version—{ activeVersion, libraryVersion, detected }
Versions and the changelog
The changelog starts at 1.0.0, the first public release, so upgrade-grid has nothing to migrate
yet and says so. Each later release adds an entry under ### Added, Changed, Deprecated, Removed,
Fixed, Security or Breaking (Keep a Changelog).
Verifying a connection
npx @modelcontextprotocol/inspector npx @gridcraft/mcpstdout is the JSON-RPC channel; the server logs only to stderr.
Developing (in the GridCraft repo)
| Command | What it does |
|---|---|
| npm run mcp | Start the server from source on stdio. |
| npm run mcp:knowledge | Rebuild knowledge/ (docs + code samples) from the docs site — run it after changing a docs page. changelog.md there is written by hand. |
| npm run test:mcp | Unit tests (changelog parser, version detection). |
| node mcp-server/scripts/check-packaged.mjs | Pack, install outside the repo, and check every tool, prompt and resource — and that only the public docs are served. |
| node mcp-server/scripts/check-scaffold.mjs | Generate grids with scaffold_grid and compile them with strictTemplates. |
npm pack builds dist/ first (prepack).
