npm - @svgrid/mcp - Versions diffs - 2.6.8 → 3.0.1 - Mend

@svgrid/mcp 2.6.8 → 3.0.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (22) hide show

package/dist/data.js CHANGED Viewed

@@ -3118,7 +3118,7 @@ export const docs = [
         "path": "docs/enterprise/studio/ai-generation.md",
         "title": "AI generation",
         "section": "Studio",
-        "markdown": "# AI generation\r\n\r\nThe `@svgrid/mcp` server exposes Studio to AI coding agents (Claude Code, Cursor,\r\nCodex, ...) through the Model Context Protocol. Ask your agent to build a screen\r\nfor a table and it introspects, scaffolds, and verifies - producing the same code\r\nthe [CLI](./cli.md) and [designer](./designer.md) do.\r\n\r\n![The generated files: schema module, +server.ts API route, and +page.svelte screen, with svgrid:managed markers.](/docs-media/studio-generated-code.png)\r\n\r\n## How it fits together\r\n\r\nThe MCP server makes **no model calls of its own**. It hands your agent a set of\r\ntools; the agent's own model decides when to call them. So the loop is:\r\n\r\n```\r\nyou  ->  your agent (its model)  ->  svgrid MCP tools  ->  files on disk\r\n                    ^                                          |\r\n                    +--------  svelte-check verify  <----------+\r\n```\r\n\r\nYour schema and data stay on your machine; nothing is sent to our servers.\r\n\r\n## Configure the MCP server\r\n\r\nAdd it to your agent's MCP config (the key is passed as an env var, since the\r\nserver runs in a Node process):\r\n\r\n```jsonc\r\n{\r\n  \"mcpServers\": {\r\n    \"svgrid\": {\r\n      \"command\": \"npx\",\r\n      \"args\": [\"@svgrid/mcp\"],\r\n      \"env\": { \"SVGRID_LICENSE_KEY\": \"SVENTERPRISE-...\" }\r\n    }\r\n  }\r\n}\r\n```\r\n\r\nThe same block works across hosts - only the file it lives in differs:\r\n\r\n| Host | Config location |\r\n| --- | --- |\r\n| Claude Code | `.mcp.json` at the project root, or `claude mcp add` |\r\n| Cursor | `.cursor/mcp.json` |\r\n| Windsurf | `~/.codeium/windsurf/mcp_config.json` |\r\n| Codex / other | the host's `mcpServers` config |\r\n\r\nRestart (or reload) the agent so it picks up the server, then confirm the\r\n`svgrid` tools are listed.\r\n\r\n## The tools\r\n\r\nAlongside the read-only knowledge tools (examples, docs, API reference), the\r\nserver exposes two generation tools:\r\n\r\n| Tool | What it does |\r\n| --- | --- |\r\n| `introspect_source` | Infer an `EntitySchema` from a Drizzle schema file (`kind:\"drizzle\"`) or sample JSON rows (`kind:\"json\"`). Returns a **draft** to review. |\r\n| `scaffold_entity` | Generate the SvelteKit files from an `EntitySchema`. The output is **compile-verified** (the generated page is run through the Svelte compiler) before it comes back, and each file carries `svgrid:managed` markers. |\r\n\r\n## Drive the whole project model\r\n\r\nBeyond single screens, the server exposes the full\r\n[project model](./concepts.md#the-project-model) - the same\r\n`studio.config.json` the visual designer edits - as a set of `studio_*` tools.\r\nYour agent can build a complete multi-screen app, or continue editing one the\r\ndesigner produced, and hand it back:\r\n\r\n| Tool | What it does |\r\n| --- | --- |\r\n| `studio_new_project` | Start a new, empty project |\r\n| `studio_load_project` | Load an existing `studio.config.json` to continue editing it |\r\n| `studio_describe_project` | Summarize the current project: entities, screens + block ids, theme, RBAC, auth, deploy |\r\n| `studio_get_config` | Return the project as a `studio.config.json` string - write it to disk and the designer opens it (round-trip) |\r\n| `studio_capabilities` | List what can be added: block kinds, UI component keys, theme presets, source kinds, deploy targets |\r\n| `studio_add_entity` | Add an entity + its default screen, from an `EntitySchema`, a Drizzle source, or sample JSON rows |\r\n| `studio_add_screen` | Add an entity-bound screen (default grid) or a freestanding page |\r\n| `studio_add_block` | Add a data block (grid, chart, kpi, gauge, tree, tabs, accordion, pivot, board, calendar, detail, master-detail, filter, record, lookup, dashboard) to a screen |\r\n| `studio_add_component` | Add a UI component block (button, badge, alert, card, stat, timeline, sparkline, chip, ...) with prop overrides |\r\n| `studio_update_block` | **Configure** an existing block - columns, editing mode, export buttons, grouping, chart dimension/measure, row links, format rules - plus its width, height, and class |\r\n| `studio_remove_block` | Remove a block from a screen |\r\n| `studio_move_block` | Reorder a block within its screen |\r\n| `studio_update_screen` | Rename a screen, change its route or nav entry, or set `renderMode` (`ssr` for an idiomatic `+page.server.ts` load + form actions, `spa` for the client page) |\r\n| `studio_remove_screen` | Remove a screen and its blocks |\r\n| `studio_set_screen_layout` | Switch a screen between `grid`, `stack`, `split`, `dock`, and `canvas` layouts |\r\n| `studio_set_form_layout` | Arrange an entity's [create/edit form](./edit-forms.md): column count + titled sections, or `\"suggest\": true` to have them proposed from the field names |\r\n| `studio_set_field_conditions` | Make a form field [value-driven](./edit-forms.md#fields-that-react-to-the-answers) - shown, required, or locked depending on the other answers |\r\n| `studio_set_entity_source` | Bind an entity to a data source: `sql`, `supabase`, `rest`, `pglite`, or `memory` |\r\n| `studio_set_theme` | Set the theme preset, light/dark mode, and accent color |\r\n| `studio_set_access` | Configure [RBAC](./access-control.md): roles gating screens and create/update/delete actions |\r\n| `studio_set_auth` | Configure the [auth starter](./auth.md): protect, register, user admin, 2FA, email, OAuth (`github` / `google` / `oidc`) |\r\n| `studio_set_data_layer` | Turn the typed Drizzle data layer (schema + repositories + migrations) on or off |\r\n| `studio_set_tenancy` | Turn [multi-tenancy](./access-control.md#multi-tenancy) on/off - scopes every row to the caller's tenant, enforced server-side; `sharedEntities` stay global |\r\n| `studio_set_job` | Schedule a background job (`email` digest or `code`) - emits the guarded `/api/cron` route + the platform schedule; omit `cron` to remove one |\r\n| `studio_set_deploy_target` | Set `auto` / `vercel` / `netlify` / `cloudflare` / `node` - picks the adapter and emits CI/CD config |\r\n| `studio_validate` | Validate the current project; returns errors + warnings |\r\n| `studio_generate_app` | Emit the full runnable SvelteKit app - every file, ready to write and `svelte-check` |\r\n\r\nA prompt that exercises the loop end to end:\r\n\r\n> \"Using the svgrid MCP: new project 'Support desk'. Add a `tickets` entity from\r\n> these sample rows, a dashboard screen with a KPI and a chart over tickets,\r\n> RBAC with an agent role that cannot delete, dark theme, then validate and\r\n> generate the app.\"\r\n\r\n## Step by step\r\n\r\n1. **Point it at a source.** A Drizzle schema file, or a handful of sample rows.\r\n2. **Introspect.** The agent calls `introspect_source` and shows you the drafted\r\n   `EntitySchema` - field names, types, primary key, guessed formats.\r\n3. **Refine (optional).** Correct a type, mark a field hidden or read-only, add\r\n   validation - in chat, or later in the [visual designer](./app-designer.md).\r\n4. **Scaffold.** The agent calls `scaffold_entity`; the files come back already\r\n   run through the Svelte compiler.\r\n5. **Verify.** The agent runs your project's `svelte-check`; if anything fails it\r\n   iterates. This is the loop that keeps AI output trustworthy.\r\n\r\n## Prompts that work\r\n\r\nFrom a Drizzle schema:\r\n\r\n> \"Using the svgrid MCP, build a CRUD screen for the `customers` table in\r\n> `src/lib/db/schema.ts`.\"\r\n\r\nFrom sample data, when there is no schema yet:\r\n\r\n> \"Here are five example rows of our invoices. Use the svgrid MCP to introspect a\r\n> schema, then scaffold a CRUD screen at `/invoices`.\"\r\n>\r\n> ```json\r\n> [{ \"id\": \"INV-1\", \"customer\": \"Acme\", \"amount\": 4200, \"paid\": true, \"due\": \"2026-07-01\" }]\r\n> ```\r\n\r\nRefining before you commit:\r\n\r\n> \"Show me the drafted schema first. Mark `internalNotes` hidden, make `email`\r\n> required, and set `status` to an enum of draft/sent/paid before scaffolding.\"\r\n\r\n## What comes back\r\n\r\n`scaffold_entity` writes three files (the same layout as the CLI and designer):\r\n\r\n```\r\nsrc/lib/customers.schema.ts     # the EntitySchema + row type\r\nsrc/routes/api/customers/+server.ts  # createKitHandlers data endpoint\r\nsrc/routes/customers/+page.svelte    # the grid + edit-panel screen\r\n```\r\n\r\nEach carries `svgrid:managed` markers so a re-generation updates the managed\r\nregions and leaves your hand-written code untouched. See\r\n[code generation](./code-generation.md) for the anatomy of each file.\r\n\r\n## Bring your own key\r\n\r\nThe generator uses **your** agent's model and API key - your schema and data\r\nnever touch our servers. The MCP server itself makes no model calls; it provides\r\nintrospection + scaffolding + verification tools that the host agent drives.\r\n\r\n## Licensing\r\n\r\nGeneration is soft-gated: it runs unlicensed and prepends a one-line commercial\r\nnotice, and the generated app carries the usual watermark until you call\r\n`setLicenseKey()`. Set `SVGRID_LICENSE_KEY` in the MCP config to license it. See\r\n[licensing](../licensing.md#studio-data-app-generator).\r\n\r\n## See also\r\n\r\n- [The Studio CLI](./cli.md) - the deterministic, no-AI path\r\n- [Visual app designer](./app-designer.md) - refine an AI draft by hand before generating\r\n- [Code generation](./code-generation.md) - the anatomy of the emitted files\r\n- [MCP server](../../help/mcp-server.md) - full MCP reference\r\n"
+        "markdown": "# AI generation\r\n\r\nThe `@svgrid/mcp` server exposes Studio to AI coding agents (Claude Code, Cursor,\r\nCodex, ...) through the Model Context Protocol. Ask your agent to build a screen\r\nfor a table and it introspects, scaffolds, and verifies - producing the same code\r\nthe [CLI](./cli.md) and [designer](./designer.md) do.\r\n\r\n![The generated files: schema module, +server.ts API route, and +page.svelte screen, with svgrid:managed markers.](/docs-media/studio-generated-code.png)\r\n\r\n## How it fits together\r\n\r\nThe MCP server makes **no model calls of its own**. It hands your agent a set of\r\ntools; the agent's own model decides when to call them. So the loop is:\r\n\r\n```\r\nyou  ->  your agent (its model)  ->  svgrid MCP tools  ->  files on disk\r\n                    ^                                          |\r\n                    +--------  svelte-check verify  <----------+\r\n```\r\n\r\nYour schema and data stay on your machine; nothing is sent to our servers.\r\n\r\n## Configure the MCP server\r\n\r\nAdd it to your agent's MCP config (the key is passed as an env var, since the\r\nserver runs in a Node process):\r\n\r\n```jsonc\r\n{\r\n  \"mcpServers\": {\r\n    \"svgrid\": {\r\n      \"command\": \"npx\",\r\n      \"args\": [\"@svgrid/mcp\"],\r\n      \"env\": { \"SVGRID_LICENSE_KEY\": \"SVENTERPRISE-...\" }\r\n    }\r\n  }\r\n}\r\n```\r\n\r\nThe same block works across hosts - only the file it lives in differs:\r\n\r\n| Host | Config location |\r\n| --- | --- |\r\n| Claude Code | `.mcp.json` at the project root, or `claude mcp add` |\r\n| Cursor | `.cursor/mcp.json` |\r\n| Windsurf | `~/.codeium/windsurf/mcp_config.json` |\r\n| Codex / other | the host's `mcpServers` config |\r\n\r\nRestart (or reload) the agent so it picks up the server, then confirm the\r\n`svgrid` tools are listed.\r\n\r\n## The tools\r\n\r\nAlongside the read-only knowledge tools (examples, docs, API reference), the\r\nserver exposes two generation tools:\r\n\r\n| Tool | What it does |\r\n| --- | --- |\r\n| `svgrid_scaffold` with `schemaOnly: true` | Infer an `EntitySchema` from a Drizzle schema file (`from:\"drizzle\"`) or sample JSON rows (`from:\"json\"`). Returns a **draft** to review. |\r\n| `svgrid_scaffold` | Generate the SvelteKit files - from a Drizzle schema, sample rows, or an `EntitySchema` you already have, in one call. The output is **compile-verified** (the generated page is run through the Svelte compiler) before it comes back, and each file carries `svgrid:managed` markers. |\r\n\r\n## Drive the whole project model\r\n\r\nBeyond single screens, the server exposes the full\r\n[project model](./concepts.md#the-project-model) - the same\r\n`studio.config.json` the visual designer edits - as four `studio_*` tools.\r\nYour agent can build a complete multi-screen app, or continue editing one the\r\ndesigner produced, and hand it back.\r\n\r\n**They are opt-in.** Set `SVGRID_MCP_STUDIO=1`, or a valid\r\n`SVGRID_LICENSE_KEY`, in the MCP server's env. Tools that need a licence to be\r\nuseful should not cost every other user context on every request.\r\n\r\n| Tool | What it does |\r\n| --- | --- |\r\n| `studio_project` | `new` an empty project, `load` a `studio.config.json`, `describe` the current one (entities, screens, block ids, theme, RBAC, auth, deploy), `config` to get it back as a string for round-tripping, `capabilities` to list the block kinds, UI component keys, theme presets, source kinds and deploy targets this version supports |\r\n| `studio_apply` | A **batch** of model changes applied in order: `add_entity`, `add_screen`, `add_block`, `add_component`, `update_block`, `remove_block`, `move_block`, `update_screen`, `remove_screen` |\r\n| `studio_configure` | Project-wide settings in one call: `theme`, `auth`, `access`, `tenancy`, `data_layer`, `job`, `deploy_target`, `screen_layout`, `form_layout`, `field_conditions`, `entity_source` |\r\n| `studio_build` | `validate` the project (errors + warnings), then `generate` the full runnable SvelteKit app - every file, ready to write and `svelte-check` |\r\n\r\nCall `studio_project` with `action: \"capabilities\"` before applying anything:\r\nit reports exactly what the installed version supports, so the agent uses real\r\nblock kinds and component keys rather than plausible-looking ones.\r\n\r\n`studio_apply` takes a batch on purpose. This was 27 separate tools, one per\r\nmutation, which made a five-screen app twenty-odd round trips and cost every\r\nuser of the free grid ~3,741 tokens of tool definitions on every request. A\r\nwhole screen is now one call:\r\n\r\n```json\r\n{\r\n  \"ops\": [\r\n    { \"op\": \"add_entity\", \"rows\": [{ \"id\": 1, \"subject\": \"Login fails\", \"status\": \"open\" }], \"name\": \"tickets\" },\r\n    { \"op\": \"add_screen\", \"title\": \"Dashboard\" },\r\n    { \"op\": \"add_block\", \"screen\": \"dashboard\", \"kind\": \"kpi\", \"entity\": \"tickets\" },\r\n    { \"op\": \"add_block\", \"screen\": \"dashboard\", \"kind\": \"chart\", \"entity\": \"tickets\" }\r\n  ]\r\n}\r\n```\r\n\r\nIf an op fails, the response says which one and what had already applied, so\r\nthe agent retries the tail rather than the whole batch.\r\n\r\nThe 27 individual tool names still answer, so an existing prompt keeps working\r\n- they are simply no longer advertised.\r\n\r\nA prompt that exercises the loop end to end:\r\n\r\n> \"Using the svgrid MCP: new project 'Support desk'. Add a `tickets` entity from\r\n> these sample rows, a dashboard screen with a KPI and a chart over tickets,\r\n> RBAC with an agent role that cannot delete, dark theme, then validate and\r\n> generate the app.\"\r\n\r\n## Step by step\r\n\r\n1. **Point it at a source.** A Drizzle schema file, or a handful of sample rows.\r\n2. **Introspect.** The agent calls `svgrid_scaffold` with `schemaOnly: true` and shows you the drafted\r\n   `EntitySchema` - field names, types, primary key, guessed formats.\r\n3. **Refine (optional).** Correct a type, mark a field hidden or read-only, add\r\n   validation - in chat, or later in the [visual designer](./app-designer.md).\r\n4. **Scaffold.** The agent calls `svgrid_scaffold` again without `schemaOnly`; the files come back already\r\n   run through the Svelte compiler.\r\n5. **Verify.** The agent runs your project's `svelte-check`; if anything fails it\r\n   iterates. This is the loop that keeps AI output trustworthy.\r\n\r\n## Prompts that work\r\n\r\nFrom a Drizzle schema:\r\n\r\n> \"Using the svgrid MCP, build a CRUD screen for the `customers` table in\r\n> `src/lib/db/schema.ts`.\"\r\n\r\nFrom sample data, when there is no schema yet:\r\n\r\n> \"Here are five example rows of our invoices. Use the svgrid MCP to introspect a\r\n> schema, then scaffold a CRUD screen at `/invoices`.\"\r\n>\r\n> ```json\r\n> [{ \"id\": \"INV-1\", \"customer\": \"Acme\", \"amount\": 4200, \"paid\": true, \"due\": \"2026-07-01\" }]\r\n> ```\r\n\r\nRefining before you commit:\r\n\r\n> \"Show me the drafted schema first. Mark `internalNotes` hidden, make `email`\r\n> required, and set `status` to an enum of draft/sent/paid before scaffolding.\"\r\n\r\n## What comes back\r\n\r\n`svgrid_scaffold` writes three files (the same layout as the CLI and designer):\r\n\r\n```\r\nsrc/lib/customers.schema.ts     # the EntitySchema + row type\r\nsrc/routes/api/customers/+server.ts  # createKitHandlers data endpoint\r\nsrc/routes/customers/+page.svelte    # the grid + edit-panel screen\r\n```\r\n\r\nEach carries `svgrid:managed` markers so a re-generation updates the managed\r\nregions and leaves your hand-written code untouched. See\r\n[code generation](./code-generation.md) for the anatomy of each file.\r\n\r\n## Bring your own key\r\n\r\nThe generator uses **your** agent's model and API key - your schema and data\r\nnever touch our servers. The MCP server itself makes no model calls; it provides\r\nintrospection + scaffolding + verification tools that the host agent drives.\r\n\r\n## Licensing\r\n\r\nGeneration is soft-gated: it runs unlicensed and prepends a one-line commercial\r\nnotice, and the generated app carries the usual watermark until you call\r\n`setLicenseKey()`. Set `SVGRID_LICENSE_KEY` in the MCP config to license it. See\r\n[licensing](../licensing.md#studio-data-app-generator).\r\n\r\n## See also\r\n\r\n- [The Studio CLI](./cli.md) - the deterministic, no-AI path\r\n- [Visual app designer](./app-designer.md) - refine an AI draft by hand before generating\r\n- [Code generation](./code-generation.md) - the anatomy of the emitted files\r\n- [MCP server](../../help/mcp-server.md) - full MCP reference\r\n"
     },
     {
         "slug": "enterprise/studio/api",
@@ -3517,7 +3517,7 @@ export const docs = [
         "path": "docs/help/ai-toolkit.md",
         "title": "AI Toolkit",
         "section": "Help",
-        "markdown": "# AI Toolkit\r\n\r\nEverything SvGrid ships for building with language models, in one place.\r\nThe toolkit spans two axes: **AI inside your running app** (helpers your\r\nusers invoke - natural-language filter, smart fill, summarise, classify)\r\nand **AI inside your editor** (the MCP server + grounding files that make\r\nClaude, Cursor, and friends write correct SvGrid code).\r\n\r\nNothing here bundles a model. SvGrid is **model-agnostic and\r\nbring-your-own-key**: you register one adapter and keep full control of\r\nmodel choice, routing, and what data leaves the browser.\r\n\r\n<div data-docs-demo=\"51-ai-assistant\" data-height=\"560\"></div>\r\n\r\n## The two surfaces\r\n\r\n| | AI in your app (runtime) | AI in your editor (build time) |\r\n| --- | --- | --- |\r\n| **Who invokes it** | your end users | you and your coding agent |\r\n| **What it does** | filter / fill / summarise / classify / export the live grid | scaffold columns, generate CRUD screens, answer API questions |\r\n| **Package** | `@svgrid/enterprise` (`api.ai.*`) | `@svgrid/mcp`, grounding files |\r\n| **Needs a model key** | yes - the one you register | no - your agent brings its own |\r\n| **Deep dive** | [AI assistant](./ai.md) | [MCP server](./mcp-server.md) · [LLM grounding](./llm-grounding.md) |\r\n\r\nMost teams use both: the MCP server to write the grid, the in-grid\r\nhelpers to power features inside it.\r\n\r\n## How it works\r\n\r\nThe grid never calls a model directly. Every runtime AI call routes\r\nthrough a single async **provider** you register once at app boot:\r\n\r\n```ts\r\nimport { setAIProvider, type AIProvider } from '@svgrid/grid'\r\n\r\nconst provider: AIProvider = async ({ prompt, responseFormat, signal, task }) => {\r\n  const r = await fetch('/api/ai', {\r\n    method: 'POST',\r\n    headers: { 'content-type': 'application/json' },\r\n    body: JSON.stringify({ prompt, responseFormat, task }),\r\n    signal,\r\n  })\r\n  if (!r.ok) throw new Error(`AI provider returned ${r.status}`)\r\n  return r.text()\r\n}\r\n\r\nsetAIProvider(provider)\r\n```\r\n\r\nThree design choices keep bad model output from becoming a silent wrong answer:\r\n\r\n- **Structured JSON, validated.** Helpers request `responseFormat: 'json'`\r\n  and the grid `JSON.parse`s the reply. It strips a single markdown code\r\n  fence automatically, so a model that wraps output in ` ```json ... ``` `\r\n  still parses. On malformed output you get a typed error, not a silent\r\n  wrong result.\r\n- **The prompt is grounded in your columns.** Before each call the grid\r\n  embeds the live column schema (names, types, sampled values) into the\r\n  prompt, so the model picks real field names instead of inventing them.\r\n- **A hallucination guard on the way back.** If a model still returns a\r\n  column that does not exist, the clause is dropped rather than passed to\r\n  `setFilter` - you lose a clause, never crash the page.\r\n\r\nThe provider shape is deliberately tiny (one async call, `text` or `json`\r\nresponse) so the same adapter drives an OpenAI `chat.completions` call, an\r\nAnthropic `messages` call, a self-hosted endpoint, or a server-side proxy.\r\nNo model client is ever bundled into your grid.\r\n\r\n> **Just evaluating?** The package ships a deterministic `mockAIProvider`\r\n> that returns plausible canned shapes per task. Wire it in with\r\n> `setAIProvider(mockAIProvider)` and every helper works end to end with\r\n> no key. The demo above runs on it.\r\n\r\n## In-grid helpers\r\n\r\n`installEnterprise(api)` - the same call you use for export and print -\r\naugments your `SvGridApi` with an `ai` namespace. Six helpers, all\r\nmodel-agnostic:\r\n\r\n```ts\r\napi.ai.filter(query, opts?)     // NL sentence  -> filter + sort plan\r\napi.ai.smartFill(opts)          // 1-2 examples -> proposed column values\r\napi.ai.summarize(opts)          // row/selection/group/all -> text + bullets\r\napi.ai.classify(opts)           // free-text cells -> a clean enum label\r\napi.ai.export(query, opts?)     // NL sentence  -> filter + group + format, then export\r\napi.ai.findAnomalies(opts?)     // scan a slice  -> outliers + severity\r\n```\r\n\r\n### Natural-language filter\r\n\r\nThe highest-leverage feature: replace a dozen per-column filter operators\r\nwith one search box.\r\n\r\n```ts\r\nconst plan = await api.ai.filter('accounts losing momentum in EMEA, by NPS')\r\n// {\r\n//   filters: [\r\n//     { field: 'region', operator: 'equals',   value: 'EMEA' },\r\n//     { field: 'nps',    operator: 'lessThan', value: '30' },\r\n//   ],\r\n//   sort: [{ field: 'nps', desc: false }],\r\n//   rationale: 'EMEA region, low NPS, sorted ascending.',\r\n// }\r\n```\r\n\r\nBy default it **returns the plan without applying it**, so you can show a\r\n\"here is what I would do, accept?\" preview and surface the `rationale`.\r\nPass `{ apply: true }` to commit straight to the grid.\r\n\r\n### Smart fill\r\n\r\nThe killer feature for spreadsheet-style entry: type one or two examples\r\nin a column, let the model propose the rest.\r\n\r\n```ts\r\nconst result = await api.ai.smartFill({\r\n  field: 'tier',\r\n  examples: [\r\n    { input: { company: 'Northwind' }, output: 'enterprise' },\r\n    { input: { company: 'Helios' },    output: 'growth' },\r\n  ],\r\n})\r\n// result.predictions: [{ rowIndex, value, confidence }, ...]\r\n```\r\n\r\nYou choose what to do with the predictions - accept-all, accept-per-cell\r\nwith a confidence pill, or write them onto the row for review.\r\n\r\n### Summarise, classify, export, anomalies\r\n\r\n- **`summarize`** drops a slice (row / selection / group / all) into the\r\n  model and returns a paragraph, bullets, and the fields the story leans\r\n  on. Large slices are sampled uniformly to stay under a token budget.\r\n- **`classify`** buckets free-text cells into a known set of labels, and\r\n  filters out any prediction not in your `classes` list so the output is a\r\n  clean enum.\r\n- **`export`** turns \"export EU orders from Q2 as a grouped PDF by\r\n  country\" into a `{ format, filters, sort, groupBy }` plan and hands it to\r\n  the exporter - self-contained, so the download is correct regardless of\r\n  the grid's current view.\r\n- **`findAnomalies`** scans a slice for outliers and inconsistent values,\r\n  each tagged `low | medium | high`. Pairs naturally with export: find the\r\n  odd rows, then export just those.\r\n\r\nFull API, response shapes, and the license gate are on the\r\n[AI assistant](./ai.md) page.\r\n\r\n## Build an agent that drives the grid\r\n\r\nThe imperative `SvGridApi` is a clean tool surface - each method becomes\r\none function a model can call. Three patterns, in order of how much agency\r\nyou hand over:\r\n\r\n1. **Read-only summary agent** - the model describes the current view\r\n   (`api.getDisplayedRows()`), no tool calling.\r\n2. **Stateful UI agent** - the model calls `setFilter` / `setSort` /\r\n   `setGroupBy` in response to natural language, bounded by a max-turns loop.\r\n3. **Autonomous workflow agent** - the grid is one node in a longer chain\r\n   (import -> enrich -> human approval -> export), and the visible table is\r\n   the state a human can audit between steps.\r\n\r\n```ts\r\n// Pattern 2, sketched: each SvGridApi method is one tool the model can call.\r\nswitch (call.function.name) {\r\n  case 'setFilter':       api.setFilter(args.columnId, args); break\r\n  case 'setSort':         api.setSort(args.columnId, args.direction); break\r\n  case 'setGroupBy':      api.setGroupBy(args.columnIds); break\r\n  case 'clearAllFilters': api.clearAllFilters(); break\r\n}\r\n```\r\n\r\nFull worked code, the sandboxing rules (whitelist tools, validate every\r\nargument against the shipped JSON Schemas, bound the loop), and the common\r\nfailure modes are on the [Agents](./agents.md) page.\r\n\r\n## MCP server: let your coding agent write the grid\r\n\r\nThe [MCP server](./mcp-server.md) exposes SvGrid to AI clients (Claude\r\nDesktop, Cursor, Zed, Continue, custom agents) over the Model Context\r\nProtocol. It grounds the model in the schemas the library actually ships,\r\nso your assistant retrieves version-pinned facts instead of hallucinating\r\nan API from its training cutoff. No API key, all local.\r\n\r\n```json\r\n{\r\n  \"mcpServers\": {\r\n    \"svgrid\": { \"command\": \"npx\", \"args\": [\"-y\", \"@svgrid/mcp\"] }\r\n  }\r\n}\r\n```\r\n\r\nIt registers callable tools - `list_examples`, `get_example_source`,\r\n`list_docs`, `get_doc`, `search_docs`, and `get_api_reference` - so the\r\nagent reads real demo source and current docs instead of guessing.\r\n\r\nFor **Studio** (turning a database or schema into a CRUD data-app), the\r\n[same server](../enterprise/studio/ai-generation.md) adds\r\n`introspect_source`, `scaffold_entity`, and 27 `studio_*` project-model\r\ntools. The generated screen is run\r\nthrough the Svelte compiler before it comes back, and each file carries\r\n`svgrid:managed` markers so a re-generation updates the managed regions and\r\nleaves your hand-written code untouched.\r\n\r\n## Ground any model, no MCP required\r\n\r\nIf you are not on an MCP client, four static artefacts ship with the docs\r\nso any model can ground itself in current facts:\r\n\r\n| File | Use for |\r\n| --- | --- |\r\n| [`/llms.txt`](/llms.txt) | First-pass context: the topic map with one-line summaries |\r\n| [`/llms-full.txt`](/llms-full.txt) | Deep grounding: every doc page concatenated |\r\n| [`/docs.json`](/docs.json) | Programmatic crawling: section tree + per-page metadata |\r\n| [`/schemas/index.json`](/schemas/index.json) | Validation: machine-checkable `ColumnDef`, `<SvGrid>` props, export options |\r\n\r\nUpload `llms-full.txt` into a custom GPT or Claude project, drop a rules\r\nblock into `.cursorrules`, or fetch the topic map into your own agent's\r\nsystem prompt at boot. All four are regenerated on every commit and served\r\nfrom the docs origin. Full recipes are on the\r\n[LLM grounding](./llm-grounding.md) page.\r\n\r\n## Best practices\r\n\r\n**Prompting the in-grid helpers.** These are handled for you - the grid\r\nalready embeds the column schema and samples rows before each call - but\r\nif you customise the prompt on your provider side:\r\n\r\n- Keep the live column set in front of the model every turn; it is the\r\n  single biggest defence against invented field names.\r\n- Include a few sample rows so the model learns value shapes (region codes,\r\n  date formats, enum spellings).\r\n- State the column ids exactly, including case - ids are case-sensitive\r\n  (`snake_case` vs `PascalCase` matters).\r\n\r\n**Previewing before committing.** `filter` and `export` default to\r\nreturning a plan without touching the grid. Show the `rationale`, let the\r\nuser confirm, then apply. This is the pattern that makes NL features feel\r\ntrustworthy rather than magic-that-sometimes-breaks.\r\n\r\n**Cost routing.** The `task` tag (`filter | smart-fill | summarize |\r\nclassify`) and the `maxOutputTokens` hint let you route a cheap model for\r\nfilters and a stronger one for summaries from inside your one adapter.\r\n\r\n**Data handling.** The grid makes no network calls of its own - the AI\r\nhelpers send exactly the prompt you construct to the adapter you configure.\r\nRoute through your own `/api/ai` proxy if you need to redact, log, or keep\r\ndata within a boundary before it reaches a provider.\r\n\r\n## Examples\r\n\r\n- **[Demo 51 - AI assistant](../../examples/src/demos/51-ai-assistant.svelte)** -\r\n  all six helpers wired to the mock provider, per-cell accept with\r\n  confidence pills.\r\n- **[AI Smart Paste](./ai-smart-paste.md)** - parse vCard / Markdown /\r\n  signature blocks / CSV into typed rows, with email-typo correction and\r\n  phone normalisation.\r\n\r\n## API reference\r\n\r\n| Symbol | Package | What it is |\r\n| --- | --- | --- |\r\n| `setAIProvider(p)` | `@svgrid/enterprise` | Register the model adapter every AI call routes through. `null` clears it. |\r\n| `mockAIProvider` | `@svgrid/enterprise` | Deterministic canned provider for demos and tests. |\r\n| `type AIProvider` | `@svgrid/enterprise` | `(req: AIRequest) => Promise<string>` - the one function you implement. |\r\n| `api.ai.filter` / `smartFill` / `summarize` / `classify` / `export` / `findAnomalies` | `@svgrid/enterprise` | The in-grid helpers, added by `installEnterprise(api)`. |\r\n| `search_docs`, `get_doc`, `list_examples`, `get_example_source`, `get_api_reference`, `list_docs` | `@svgrid/mcp` | Build-time MCP tools your coding agent calls. |\r\n| `introspect_source`, `scaffold_entity`, `studio_*` | `@svgrid/mcp` | Studio generation tools (schema -> CRUD screen, project model). |\r\n\r\nAuto-generated per-symbol reference: [`@svgrid/grid` · `ai.ts`](../reference/auto/svgrid-grid-ai.md).\r\n\r\n## Frequently asked questions\r\n\r\n### What AI features does SvGrid have?\r\n\r\nTwo kinds. At runtime, `@svgrid/grid` ships six model-agnostic helpers\r\nfree - natural-language filter, smart fill, summarise, classify, export,\r\nand anomaly detection. At build time, an MCP\r\nserver plus grounding files let your coding agent write correct SvGrid code\r\nand scaffold CRUD screens.\r\n\r\n### Which model does SvGrid use?\r\n\r\nNone by default - it is bring-your-own. You register one adapter for\r\nOpenAI, Anthropic Claude, a local model, or a server proxy, and the grid\r\nroutes every AI call through it. A deterministic mock provider ships so you\r\ncan evaluate the whole flow without a key.\r\n\r\n### Is my grid data sent to a model provider?\r\n\r\nOnly if you wire one up and invoke a helper. SvGrid itself makes no network\r\ncalls; the AI helpers send exactly the prompt you construct to the adapter\r\nyou configure, so you decide what leaves the browser and can proxy it\r\nthrough your own backend first.\r\n\r\n### Do I need the MCP server to use the AI features?\r\n\r\nNo. The in-grid helpers and the grounding files work without it. The MCP\r\nserver is the turnkey path for desktop AI clients; for a custom in-app\r\nagent you call `SvGridApi` directly.\r\n\r\n## See also\r\n\r\n- [AI assistant](./ai.md) - the in-grid helpers in full, with response shapes\r\n- [Agents](./agents.md) - build an agent that drives the live grid\r\n- [Agent Skill](./skill.md) - always-on, project-aware context and house style for coding assistants\r\n- [MCP server](./mcp-server.md) - turnkey integration for Claude Desktop / Cursor / Zed\r\n- [LLM grounding](./llm-grounding.md) - the static files any model reads\r\n- [AI generation - Studio](../enterprise/studio/ai-generation.md) - scaffold CRUD data-apps from a schema\r\n"
+        "markdown": "# AI Toolkit\r\n\r\nEverything SvGrid ships for building with language models, in one place.\r\nThe toolkit spans two axes: **AI inside your running app** (helpers your\r\nusers invoke - natural-language filter, smart fill, summarise, classify)\r\nand **AI inside your editor** (the MCP server + grounding files that make\r\nClaude, Cursor, and friends write correct SvGrid code).\r\n\r\nNothing here bundles a model. SvGrid is **model-agnostic and\r\nbring-your-own-key**: you register one adapter and keep full control of\r\nmodel choice, routing, and what data leaves the browser.\r\n\r\n<div data-docs-demo=\"51-ai-assistant\" data-height=\"560\"></div>\r\n\r\n## The two surfaces\r\n\r\n| | AI in your app (runtime) | AI in your editor (build time) |\r\n| --- | --- | --- |\r\n| **Who invokes it** | your end users | you and your coding agent |\r\n| **What it does** | filter / fill / summarise / classify / export the live grid | scaffold columns, generate CRUD screens, answer API questions |\r\n| **Package** | `@svgrid/enterprise` (`api.ai.*`) | `@svgrid/mcp`, grounding files |\r\n| **Needs a model key** | yes - the one you register | no - your agent brings its own |\r\n| **Deep dive** | [AI assistant](./ai.md) | [MCP server](./mcp-server.md) · [LLM grounding](./llm-grounding.md) |\r\n\r\nMost teams use both: the MCP server to write the grid, the in-grid\r\nhelpers to power features inside it.\r\n\r\n## How it works\r\n\r\nThe grid never calls a model directly. Every runtime AI call routes\r\nthrough a single async **provider** you register once at app boot:\r\n\r\n```ts\r\nimport { setAIProvider, type AIProvider } from '@svgrid/grid'\r\n\r\nconst provider: AIProvider = async ({ prompt, responseFormat, signal, task }) => {\r\n  const r = await fetch('/api/ai', {\r\n    method: 'POST',\r\n    headers: { 'content-type': 'application/json' },\r\n    body: JSON.stringify({ prompt, responseFormat, task }),\r\n    signal,\r\n  })\r\n  if (!r.ok) throw new Error(`AI provider returned ${r.status}`)\r\n  return r.text()\r\n}\r\n\r\nsetAIProvider(provider)\r\n```\r\n\r\nThree design choices keep bad model output from becoming a silent wrong answer:\r\n\r\n- **Structured JSON, validated.** Helpers request `responseFormat: 'json'`\r\n  and the grid `JSON.parse`s the reply. It strips a single markdown code\r\n  fence automatically, so a model that wraps output in ` ```json ... ``` `\r\n  still parses. On malformed output you get a typed error, not a silent\r\n  wrong result.\r\n- **The prompt is grounded in your columns.** Before each call the grid\r\n  embeds the live column schema (names, types, sampled values) into the\r\n  prompt, so the model picks real field names instead of inventing them.\r\n- **A hallucination guard on the way back.** If a model still returns a\r\n  column that does not exist, the clause is dropped rather than passed to\r\n  `setFilter` - you lose a clause, never crash the page.\r\n\r\nThe provider shape is deliberately tiny (one async call, `text` or `json`\r\nresponse) so the same adapter drives an OpenAI `chat.completions` call, an\r\nAnthropic `messages` call, a self-hosted endpoint, or a server-side proxy.\r\nNo model client is ever bundled into your grid.\r\n\r\n> **Just evaluating?** The package ships a deterministic `mockAIProvider`\r\n> that returns plausible canned shapes per task. Wire it in with\r\n> `setAIProvider(mockAIProvider)` and every helper works end to end with\r\n> no key. The demo above runs on it.\r\n\r\n## In-grid helpers\r\n\r\n`installEnterprise(api)` - the same call you use for export and print -\r\naugments your `SvGridApi` with an `ai` namespace. Six helpers, all\r\nmodel-agnostic:\r\n\r\n```ts\r\napi.ai.filter(query, opts?)     // NL sentence  -> filter + sort plan\r\napi.ai.smartFill(opts)          // 1-2 examples -> proposed column values\r\napi.ai.summarize(opts)          // row/selection/group/all -> text + bullets\r\napi.ai.classify(opts)           // free-text cells -> a clean enum label\r\napi.ai.export(query, opts?)     // NL sentence  -> filter + group + format, then export\r\napi.ai.findAnomalies(opts?)     // scan a slice  -> outliers + severity\r\n```\r\n\r\n### Natural-language filter\r\n\r\nThe highest-leverage feature: replace a dozen per-column filter operators\r\nwith one search box.\r\n\r\n```ts\r\nconst plan = await api.ai.filter('accounts losing momentum in EMEA, by NPS')\r\n// {\r\n//   filters: [\r\n//     { field: 'region', operator: 'equals',   value: 'EMEA' },\r\n//     { field: 'nps',    operator: 'lessThan', value: '30' },\r\n//   ],\r\n//   sort: [{ field: 'nps', desc: false }],\r\n//   rationale: 'EMEA region, low NPS, sorted ascending.',\r\n// }\r\n```\r\n\r\nBy default it **returns the plan without applying it**, so you can show a\r\n\"here is what I would do, accept?\" preview and surface the `rationale`.\r\nPass `{ apply: true }` to commit straight to the grid.\r\n\r\n### Smart fill\r\n\r\nThe killer feature for spreadsheet-style entry: type one or two examples\r\nin a column, let the model propose the rest.\r\n\r\n```ts\r\nconst result = await api.ai.smartFill({\r\n  field: 'tier',\r\n  examples: [\r\n    { input: { company: 'Northwind' }, output: 'enterprise' },\r\n    { input: { company: 'Helios' },    output: 'growth' },\r\n  ],\r\n})\r\n// result.predictions: [{ rowIndex, value, confidence }, ...]\r\n```\r\n\r\nYou choose what to do with the predictions - accept-all, accept-per-cell\r\nwith a confidence pill, or write them onto the row for review.\r\n\r\n### Summarise, classify, export, anomalies\r\n\r\n- **`summarize`** drops a slice (row / selection / group / all) into the\r\n  model and returns a paragraph, bullets, and the fields the story leans\r\n  on. Large slices are sampled uniformly to stay under a token budget.\r\n- **`classify`** buckets free-text cells into a known set of labels, and\r\n  filters out any prediction not in your `classes` list so the output is a\r\n  clean enum.\r\n- **`export`** turns \"export EU orders from Q2 as a grouped PDF by\r\n  country\" into a `{ format, filters, sort, groupBy }` plan and hands it to\r\n  the exporter - self-contained, so the download is correct regardless of\r\n  the grid's current view.\r\n- **`findAnomalies`** scans a slice for outliers and inconsistent values,\r\n  each tagged `low | medium | high`. Pairs naturally with export: find the\r\n  odd rows, then export just those.\r\n\r\nFull API, response shapes, and the license gate are on the\r\n[AI assistant](./ai.md) page.\r\n\r\n## Build an agent that drives the grid\r\n\r\nThe imperative `SvGridApi` is a clean tool surface - each method becomes\r\none function a model can call. Three patterns, in order of how much agency\r\nyou hand over:\r\n\r\n1. **Read-only summary agent** - the model describes the current view\r\n   (`api.getDisplayedRows()`), no tool calling.\r\n2. **Stateful UI agent** - the model calls `setFilter` / `setSort` /\r\n   `setGroupBy` in response to natural language, bounded by a max-turns loop.\r\n3. **Autonomous workflow agent** - the grid is one node in a longer chain\r\n   (import -> enrich -> human approval -> export), and the visible table is\r\n   the state a human can audit between steps.\r\n\r\n```ts\r\n// Pattern 2, sketched: each SvGridApi method is one tool the model can call.\r\nswitch (call.function.name) {\r\n  case 'setFilter':       api.setFilter(args.columnId, args); break\r\n  case 'setSort':         api.setSort(args.columnId, args.direction); break\r\n  case 'setGroupBy':      api.setGroupBy(args.columnIds); break\r\n  case 'clearAllFilters': api.clearAllFilters(); break\r\n}\r\n```\r\n\r\nFull worked code, the sandboxing rules (whitelist tools, validate every\r\nargument against the shipped JSON Schemas, bound the loop), and the common\r\nfailure modes are on the [Agents](./agents.md) page.\r\n\r\n## MCP server: let your coding agent write the grid\r\n\r\nThe [MCP server](./mcp-server.md) exposes SvGrid to AI clients (Claude\r\nDesktop, Cursor, Zed, Continue, custom agents) over the Model Context\r\nProtocol. It grounds the model in the schemas the library actually ships,\r\nso your assistant retrieves version-pinned facts instead of hallucinating\r\nan API from its training cutoff. No API key, all local.\r\n\r\n```json\r\n{\r\n  \"mcpServers\": {\r\n    \"svgrid\": { \"command\": \"npx\", \"args\": [\"-y\", \"@svgrid/mcp\"] }\r\n  }\r\n}\r\n```\r\n\r\nIt registers callable tools - `svgrid_search`, `svgrid_get`,\r\n`svgrid_check_code` and `svgrid_scaffold` - so the\r\nagent reads real demo source and current docs instead of guessing.\r\n\r\nFor **Studio** (turning a database or schema into a CRUD data-app), the\r\n[same server](../enterprise/studio/ai-generation.md) adds\r\n`svgrid_scaffold` and four `studio_*` project-model\r\ntools. The generated screen is run\r\nthrough the Svelte compiler before it comes back, and each file carries\r\n`svgrid:managed` markers so a re-generation updates the managed regions and\r\nleaves your hand-written code untouched.\r\n\r\n## Ground any model, no MCP required\r\n\r\nIf you are not on an MCP client, four static artefacts ship with the docs\r\nso any model can ground itself in current facts:\r\n\r\n| File | Use for |\r\n| --- | --- |\r\n| [`/llms.txt`](/llms.txt) | First-pass context: the topic map with one-line summaries |\r\n| [`/llms-full.txt`](/llms-full.txt) | Deep grounding: every doc page concatenated |\r\n| [`/docs.json`](/docs.json) | Programmatic crawling: section tree + per-page metadata |\r\n| [`/schemas/index.json`](/schemas/index.json) | Validation: machine-checkable `ColumnDef`, `<SvGrid>` props, export options |\r\n\r\nUpload `llms-full.txt` into a custom GPT or Claude project, drop a rules\r\nblock into `.cursorrules`, or fetch the topic map into your own agent's\r\nsystem prompt at boot. All four are regenerated on every commit and served\r\nfrom the docs origin. Full recipes are on the\r\n[LLM grounding](./llm-grounding.md) page.\r\n\r\n## Best practices\r\n\r\n**Prompting the in-grid helpers.** These are handled for you - the grid\r\nalready embeds the column schema and samples rows before each call - but\r\nif you customise the prompt on your provider side:\r\n\r\n- Keep the live column set in front of the model every turn; it is the\r\n  single biggest defence against invented field names.\r\n- Include a few sample rows so the model learns value shapes (region codes,\r\n  date formats, enum spellings).\r\n- State the column ids exactly, including case - ids are case-sensitive\r\n  (`snake_case` vs `PascalCase` matters).\r\n\r\n**Previewing before committing.** `filter` and `export` default to\r\nreturning a plan without touching the grid. Show the `rationale`, let the\r\nuser confirm, then apply. This is the pattern that makes NL features feel\r\ntrustworthy rather than magic-that-sometimes-breaks.\r\n\r\n**Cost routing.** The `task` tag (`filter | smart-fill | summarize |\r\nclassify`) and the `maxOutputTokens` hint let you route a cheap model for\r\nfilters and a stronger one for summaries from inside your one adapter.\r\n\r\n**Data handling.** The grid makes no network calls of its own - the AI\r\nhelpers send exactly the prompt you construct to the adapter you configure.\r\nRoute through your own `/api/ai` proxy if you need to redact, log, or keep\r\ndata within a boundary before it reaches a provider.\r\n\r\n## Examples\r\n\r\n- **[Demo 51 - AI assistant](../../examples/src/demos/51-ai-assistant.svelte)** -\r\n  all six helpers wired to the mock provider, per-cell accept with\r\n  confidence pills.\r\n- **[AI Smart Paste](./ai-smart-paste.md)** - parse vCard / Markdown /\r\n  signature blocks / CSV into typed rows, with email-typo correction and\r\n  phone normalisation.\r\n\r\n## API reference\r\n\r\n| Symbol | Package | What it is |\r\n| --- | --- | --- |\r\n| `setAIProvider(p)` | `@svgrid/enterprise` | Register the model adapter every AI call routes through. `null` clears it. |\r\n| `mockAIProvider` | `@svgrid/enterprise` | Deterministic canned provider for demos and tests. |\r\n| `type AIProvider` | `@svgrid/enterprise` | `(req: AIRequest) => Promise<string>` - the one function you implement. |\r\n| `api.ai.filter` / `smartFill` / `summarize` / `classify` / `export` / `findAnomalies` | `@svgrid/enterprise` | The in-grid helpers, added by `installEnterprise(api)`. |\r\n| `svgrid_search`, `svgrid_get` | `@svgrid/mcp` | Build-time MCP tools your coding agent calls: find anything across docs, demos and the API, then read it in full. |\r\n| `svgrid_check_code` | `@svgrid/mcp` | Verifies generated code against the real API surface before you see it. |\r\n| `svgrid_scaffold`, `studio_*` | `@svgrid/mcp` | Studio generation tools (schema -> CRUD screen, project model). Studio tools are opt-in: set `SVGRID_MCP_STUDIO=1` or a licence key. |\r\n\r\nAuto-generated per-symbol reference: [`@svgrid/grid` · `ai.ts`](../reference/auto/svgrid-grid-ai.md).\r\n\r\n## Frequently asked questions\r\n\r\n### What AI features does SvGrid have?\r\n\r\nTwo kinds. At runtime, `@svgrid/grid` ships six model-agnostic helpers\r\nfree - natural-language filter, smart fill, summarise, classify, export,\r\nand anomaly detection. At build time, an MCP\r\nserver plus grounding files let your coding agent write correct SvGrid code\r\nand scaffold CRUD screens.\r\n\r\n### Which model does SvGrid use?\r\n\r\nNone by default - it is bring-your-own. You register one adapter for\r\nOpenAI, Anthropic Claude, a local model, or a server proxy, and the grid\r\nroutes every AI call through it. A deterministic mock provider ships so you\r\ncan evaluate the whole flow without a key.\r\n\r\n### Is my grid data sent to a model provider?\r\n\r\nOnly if you wire one up and invoke a helper. SvGrid itself makes no network\r\ncalls; the AI helpers send exactly the prompt you construct to the adapter\r\nyou configure, so you decide what leaves the browser and can proxy it\r\nthrough your own backend first.\r\n\r\n### Do I need the MCP server to use the AI features?\r\n\r\nNo. The in-grid helpers and the grounding files work without it. The MCP\r\nserver is the turnkey path for desktop AI clients; for a custom in-app\r\nagent you call `SvGridApi` directly.\r\n\r\n## See also\r\n\r\n- [AI assistant](./ai.md) - the in-grid helpers in full, with response shapes\r\n- [Agents](./agents.md) - build an agent that drives the live grid\r\n- [Agent Skill](./skill.md) - always-on, project-aware context and house style for coding assistants\r\n- [MCP server](./mcp-server.md) - turnkey integration for Claude Desktop / Cursor / Zed\r\n- [LLM grounding](./llm-grounding.md) - the static files any model reads\r\n- [AI generation - Studio](../enterprise/studio/ai-generation.md) - scaffold CRUD data-apps from a schema\r\n"
     },
     {
         "slug": "help/ai",
@@ -4042,14 +4042,14 @@ export const docs = [
         "path": "docs/help/llm-grounding.md",
         "title": "Use sv-grid docs as LLM context",
         "section": "Help",
-        "markdown": "# Use sv-grid docs as LLM context\r\n\r\nThis page is the \"how do I make ChatGPT / Claude / Cursor write good\r\nsv-grid code?\" guide. Three pre-built artefacts ship with the docs\r\nspecifically so models can ground themselves in current, accurate\r\ninformation instead of hallucinating from training data.\r\n\r\n## The four files\r\n\r\n| File                                     | Format     | Size   | Use for                                                                |\r\n| ---------------------------------------- | ---------- | ------ | ---------------------------------------------------------------------- |\r\n| [`/llms.txt`](/llms.txt)                 | Plain text | ~10 kB | First-pass context: the topic map with one-line summaries              |\r\n| [`/llms-full.txt`](/llms-full.txt)       | Plain text | ~700 kB | Deep grounding: every doc page concatenated                            |\r\n| [`/docs.json`](/docs.json)               | JSON       | ~80 kB | Programmatic crawling: section tree, per-page metadata, demo links     |\r\n| [`/schemas/index.json`](/schemas/index.json) | JSON   | ~30 kB | Validation: machine-checkable shape of `ColumnDef`, `<SvGrid>` props, export options |\r\n\r\nAll four are regenerated on every commit by `tools/build-docs-index.mjs`\r\nand `tools/build-schemas.mjs`. They live at the docs origin\r\n(`https://svgrid.com/...`) so you can fetch them at runtime.\r\n\r\n## Recipe 1: Drop into a custom GPT / Claude project\r\n\r\nThe simplest way. Both ChatGPT (custom GPTs) and Claude (projects)\r\nlet you upload reference files that ride along with every chat.\r\n\r\n1. Save [`/llms-full.txt`](/llms-full.txt) locally.\r\n2. In ChatGPT: *Create custom GPT → Configure → Knowledge → Upload files*.\r\n3. In Claude: *Project → Project knowledge → Add document*.\r\n4. Add this system instruction:\r\n\r\n```\r\nYou are a sv-grid expert. Ground every answer in the attached\r\nllms-full.txt. If a question references an API not in the document,\r\nsay so and ask the user to upgrade rather than inventing one. Prefer\r\nthe smallest working example. When showing columns, follow the\r\ncolumn-def.json schema exactly.\r\n```\r\n\r\n5. (Optional) Upload `column-def.json` and `svgrid-options.json`\r\n   alongside so the model can self-check generated config.\r\n\r\nThat's it. The next time you ask \"how do I export only selected rows\r\nto xlsx?\" the model answers from the doc text, not from its\r\nyear-old training cutoff.\r\n\r\n## Recipe 2: Cursor / Continue / Cody rules file\r\n\r\nMost IDE assistants honour a `.cursorrules` / `.continuerules` /\r\n`.aider.conf.yml` file in the repo root. Drop in:\r\n\r\n```\r\n# .cursorrules\r\n\r\nWhen generating sv-grid code:\r\n- Read context from https://svgrid.com/llms.txt before answering.\r\n- For column definitions, generate against\r\n  https://svgrid.com/schemas/column-def.json (Draft 2020-12 JSON Schema).\r\n- Use Svelte 5 runes ($state, $derived, $effect) - never legacy stores.\r\n- Use `editorType: 'list'` with `editorOptions` for dropdowns,\r\n  not raw <select> elements.\r\n- Always type the grid as\r\n  `SvGrid<typeof features, RowType>` so column inference works.\r\n- The two npm packages are `@svgrid/grid` (MIT) and `@svgrid/enterprise`\r\n  (commercial). Never import from `@sv-grid/core` or `svelte-grid`,\r\n  which are different projects.\r\n```\r\n\r\n## Recipe 3: Programmatic grounding in your own agent\r\n\r\nIf you're building a custom agent (OpenAI Agents SDK, Anthropic SDK,\r\nLangChain, custom), fetch the docs once at boot:\r\n\r\n```ts\r\nconst [topicMap, schemas] = await Promise.all([\r\n  fetch('https://svgrid.com/llms.txt').then((r) => r.text()),\r\n  fetch('https://svgrid.com/schemas/index.json').then((r) => r.json()),\r\n])\r\n\r\nconst systemPrompt = `You write Svelte 5 code that uses sv-grid.\r\n\r\nDOCS INDEX (use these URLs to look up specifics):\r\n${topicMap}\r\n\r\nSCHEMAS available for validation:\r\n${JSON.stringify(schemas, null, 2)}\r\n\r\nFor deep API questions, fetch https://svgrid.com/llms-full.txt or\r\nthe specific page from the index above.`\r\n```\r\n\r\nNow hand the model a tool that can fetch arbitrary `/docs.json` paths\r\non demand, and it can answer any sv-grid question with current data.\r\n\r\n## Recipe 4: MCP server (best for daily-driver chat)\r\n\r\nIf your workflow centers on Claude Desktop / Cursor / Zed, the\r\n[MCP server](./mcp-server.md) is the single line of config that\r\nexposes the same grounding PLUS callable tools (`search_docs`,\r\n`get_doc`, `get_example_source`, `get_api_reference`, and the SvGrid\r\nStudio generators). Skip Recipes 1-3 and use the MCP server instead.\r\n\r\n## What's IN the grounding files\r\n\r\nEvery file is exhaustive but tightly scoped to sv-grid surface area:\r\n\r\n- **API surface**: every prop on `<SvGrid>`, every method on\r\n  `SvGridApi`, every field on `ColumnDef`\r\n- **Features**: when to use sorting / filtering / grouping / pagination\r\n  feature toggles, and the trade-offs\r\n- **Enterprise tier**: export, import, pivot - each documented as\r\n  if it were free, with the licensing call-out at the top of the page\r\n- **Recipes**: 25+ copy-paste patterns from the cookbook\r\n- **Migrations**: how to translate concepts from other data grids\r\n- **Errors**: every typed error the library throws, with the trigger\r\n  and the fix\r\n\r\n## What's NOT in the grounding files\r\n\r\n- **Internal implementation**: virtualizer math, headless engine\r\n  pipeline internals - not part of the public surface\r\n- **Future / roadmap**: deliberately excluded so the model never\r\n  confuses ambition with reality\r\n- **CSS class hashes**: Svelte mangles class names. The\r\n  `--sg-*` tokens are stable and documented; the class names are not.\r\n\r\n## Keeping the grounding fresh\r\n\r\nRe-fetch on every model turn for chat tools; cache for ~24h for\r\nagent loops. The docs are versioned - if you pin to a specific\r\nversion, append a `?v=1.6.0` query string when fetching from the\r\norigin (rejected if the major changes; we serve a 410).\r\n\r\n## See also\r\n\r\n- [MCP server](./mcp-server.md) - the easiest way to wire all this in\r\n- [Agents](./agents.md) - building an agent that DRIVES the grid (not just describes it)\r\n- [API stability](./api-stability.md) - what we promise to keep stable across versions\r\n"
+        "markdown": "# Use sv-grid docs as LLM context\r\n\r\nThis page is the \"how do I make ChatGPT / Claude / Cursor write good\r\nsv-grid code?\" guide. Three pre-built artefacts ship with the docs\r\nspecifically so models can ground themselves in current, accurate\r\ninformation instead of hallucinating from training data.\r\n\r\n## The four files\r\n\r\n| File                                     | Format     | Size   | Use for                                                                |\r\n| ---------------------------------------- | ---------- | ------ | ---------------------------------------------------------------------- |\r\n| [`/llms.txt`](/llms.txt)                 | Plain text | ~10 kB | First-pass context: the topic map with one-line summaries              |\r\n| [`/llms-full.txt`](/llms-full.txt)       | Plain text | ~700 kB | Deep grounding: every doc page concatenated                            |\r\n| [`/docs.json`](/docs.json)               | JSON       | ~80 kB | Programmatic crawling: section tree, per-page metadata, demo links     |\r\n| [`/schemas/index.json`](/schemas/index.json) | JSON   | ~30 kB | Validation: machine-checkable shape of `ColumnDef`, `<SvGrid>` props, export options |\r\n\r\nAll four are regenerated on every commit by `tools/build-docs-index.mjs`\r\nand `tools/build-schemas.mjs`. They live at the docs origin\r\n(`https://svgrid.com/...`) so you can fetch them at runtime.\r\n\r\n## Recipe 1: Drop into a custom GPT / Claude project\r\n\r\nThe simplest way. Both ChatGPT (custom GPTs) and Claude (projects)\r\nlet you upload reference files that ride along with every chat.\r\n\r\n1. Save [`/llms-full.txt`](/llms-full.txt) locally.\r\n2. In ChatGPT: *Create custom GPT → Configure → Knowledge → Upload files*.\r\n3. In Claude: *Project → Project knowledge → Add document*.\r\n4. Add this system instruction:\r\n\r\n```\r\nYou are a sv-grid expert. Ground every answer in the attached\r\nllms-full.txt. If a question references an API not in the document,\r\nsay so and ask the user to upgrade rather than inventing one. Prefer\r\nthe smallest working example. When showing columns, follow the\r\ncolumn-def.json schema exactly.\r\n```\r\n\r\n5. (Optional) Upload `column-def.json` and `svgrid-options.json`\r\n   alongside so the model can self-check generated config.\r\n\r\nThat's it. The next time you ask \"how do I export only selected rows\r\nto xlsx?\" the model answers from the doc text, not from its\r\nyear-old training cutoff.\r\n\r\n## Recipe 2: Cursor / Continue / Cody rules file\r\n\r\nMost IDE assistants honour a `.cursorrules` / `.continuerules` /\r\n`.aider.conf.yml` file in the repo root. Drop in:\r\n\r\n```\r\n# .cursorrules\r\n\r\nWhen generating sv-grid code:\r\n- Read context from https://svgrid.com/llms.txt before answering.\r\n- For column definitions, generate against\r\n  https://svgrid.com/schemas/column-def.json (Draft 2020-12 JSON Schema).\r\n- Use Svelte 5 runes ($state, $derived, $effect) - never legacy stores.\r\n- Use `editorType: 'list'` with `editorOptions` for dropdowns,\r\n  not raw <select> elements.\r\n- Always type the grid as\r\n  `SvGrid<typeof features, RowType>` so column inference works.\r\n- The two npm packages are `@svgrid/grid` (MIT) and `@svgrid/enterprise`\r\n  (commercial). Never import from `@sv-grid/core` or `svelte-grid`,\r\n  which are different projects.\r\n```\r\n\r\n## Recipe 3: Programmatic grounding in your own agent\r\n\r\nIf you're building a custom agent (OpenAI Agents SDK, Anthropic SDK,\r\nLangChain, custom), fetch the docs once at boot:\r\n\r\n```ts\r\nconst [topicMap, schemas] = await Promise.all([\r\n  fetch('https://svgrid.com/llms.txt').then((r) => r.text()),\r\n  fetch('https://svgrid.com/schemas/index.json').then((r) => r.json()),\r\n])\r\n\r\nconst systemPrompt = `You write Svelte 5 code that uses sv-grid.\r\n\r\nDOCS INDEX (use these URLs to look up specifics):\r\n${topicMap}\r\n\r\nSCHEMAS available for validation:\r\n${JSON.stringify(schemas, null, 2)}\r\n\r\nFor deep API questions, fetch https://svgrid.com/llms-full.txt or\r\nthe specific page from the index above.`\r\n```\r\n\r\nNow hand the model a tool that can fetch arbitrary `/docs.json` paths\r\non demand, and it can answer any sv-grid question with current data.\r\n\r\n## Recipe 4: MCP server (best for daily-driver chat)\r\n\r\nIf your workflow centers on Claude Desktop / Cursor / Zed, the\r\n[MCP server](./mcp-server.md) is the single line of config that\r\nexposes the same grounding PLUS callable tools (`svgrid_search`,\r\n`svgrid_get`, `svgrid_check_code`, and the SvGrid\r\nStudio generators). Skip Recipes 1-3 and use the MCP server instead.\r\n\r\n## What's IN the grounding files\r\n\r\nEvery file is exhaustive but tightly scoped to sv-grid surface area:\r\n\r\n- **API surface**: every prop on `<SvGrid>`, every method on\r\n  `SvGridApi`, every field on `ColumnDef`\r\n- **Features**: when to use sorting / filtering / grouping / pagination\r\n  feature toggles, and the trade-offs\r\n- **Enterprise tier**: export, import, pivot - each documented as\r\n  if it were free, with the licensing call-out at the top of the page\r\n- **Recipes**: 25+ copy-paste patterns from the cookbook\r\n- **Migrations**: how to translate concepts from other data grids\r\n- **Errors**: every typed error the library throws, with the trigger\r\n  and the fix\r\n\r\n## What's NOT in the grounding files\r\n\r\n- **Internal implementation**: virtualizer math, headless engine\r\n  pipeline internals - not part of the public surface\r\n- **Future / roadmap**: deliberately excluded so the model never\r\n  confuses ambition with reality\r\n- **CSS class hashes**: Svelte mangles class names. The\r\n  `--sg-*` tokens are stable and documented; the class names are not.\r\n\r\n## Keeping the grounding fresh\r\n\r\nRe-fetch on every model turn for chat tools; cache for ~24h for\r\nagent loops. The docs are versioned - if you pin to a specific\r\nversion, append a `?v=1.6.0` query string when fetching from the\r\norigin (rejected if the major changes; we serve a 410).\r\n\r\n## See also\r\n\r\n- [MCP server](./mcp-server.md) - the easiest way to wire all this in\r\n- [Agents](./agents.md) - building an agent that DRIVES the grid (not just describes it)\r\n- [API stability](./api-stability.md) - what we promise to keep stable across versions\r\n"
     },
     {
         "slug": "help/mcp-server",
         "path": "docs/help/mcp-server.md",
         "title": "MCP server",
         "section": "Help",
-        "markdown": "# MCP server\r\n\r\nThe SvGrid MCP server does two things for an AI client (Claude Code,\r\nClaude Desktop, Cursor, Zed, Codex, custom agents): it answers questions\r\nabout SvGrid from the files this repository ships, and it **checks the\r\ncode the model writes** against the real exported surface of the version\r\nyou have installed. No API key either way.\r\n\r\n![An AI coding agent calls the @svgrid/mcp server over the Model Context Protocol, which runs grid tools and returns structured JSON results back to the agent.](/docs-media/grid-mcp.svg)\r\n\r\n> **What is MCP?** Model Context Protocol is the open standard\r\n> ([modelcontextprotocol.io](https://modelcontextprotocol.io)) for\r\n> exposing tools to LLM clients. SvGrid ships an MCP server so the\r\n> model your team already uses can \"see\" the grid without you having\r\n> to copy-paste docs into prompts.\r\n\r\nIt runs either way you like: as a local process\r\n([`@svgrid/mcp`](https://www.npmjs.com/package/@svgrid/mcp) on npm), or as\r\na hosted endpoint at `https://mcp.svgrid.com/mcp` that needs no install at\r\nall. Both are listed in the official MCP registry as `com.svgrid/svgrid`.\r\n\r\n## Two ways to connect\r\n\r\n**Hosted (nothing to install).** Point any MCP client at the URL:\r\n\r\n```\r\nhttps://mcp.svgrid.com/mcp\r\n```\r\n\r\n```bash\r\nclaude mcp add --transport http svgrid https://mcp.svgrid.com/mcp\r\n```\r\n\r\nOne click:\r\n[Add to Cursor](https://cursor.com/en/install-mcp?name=svgrid&config=eyJ1cmwiOiJodHRwczovL21jcC5zdmdyaWQuY29tL21jcCJ9)\r\n· [Add to VS Code](https://insiders.vscode.dev/redirect/mcp/install?name=svgrid&config=%7B%22name%22%3A%22svgrid%22%2C%22type%22%3A%22http%22%2C%22url%22%3A%22https%3A%2F%2Fmcp.svgrid.com%2Fmcp%22%7D)\r\n\r\nIt carries six tools - `search`, `fetch`, `list_examples`,\r\n`get_example_source`, `get_api_reference` and `check_svgrid_code` - and\r\nneeds no Node, no config file, and no key.\r\n\r\n**Local (`npx @svgrid/mcp`).** Everything the hosted server has, plus\r\nthe 27 `studio_*` tools, and `check_svgrid_code` additionally *compiles*\r\nthe file with the Svelte compiler rather than checking it statically.\r\nUse it when you want the compile pass, the Studio tools, or no\r\nthird-party endpoint in the loop.\r\n\r\n|  | Hosted | Local |\r\n| --- | --- | --- |\r\n| Setup | a URL | `npx @svgrid/mcp` |\r\n| Needs Node | no | yes |\r\n| `check_svgrid_code` compiles | no, static checks only | yes |\r\n| `studio_*` tools | no | yes (27) |\r\n| Works offline | no | yes |\r\n\r\n## Install\r\n\r\nNo install step is required - `npx` fetches it on demand:\r\n\r\n```bash\r\n# One-shot, from any project\r\nnpx -y @svgrid/mcp\r\n```\r\n\r\nTo pin it as a dev dependency instead:\r\n\r\n```bash\r\npnpm add -D @svgrid/mcp\r\n```\r\n\r\nThe local server is a Node binary (`svgrid-mcp`) that speaks MCP over\r\nstdio. There is no daemon to maintain. The hosted server needs no install\r\nstep at all - skip to [Wire it into your AI client](#wire-it-into-your-ai-client)\r\nand use the URL.\r\n\r\n## Wire it into your AI client\r\n\r\nEvery snippet below shows the local (stdio) form and the hosted (HTTP)\r\nform. Pick one - running both connects the same tools twice.\r\n\r\n### Claude Code\r\n\r\nThe plugin is the shortest path: it installs the\r\n[Agent Skill](./skill.md) and the hosted server together, so the model\r\ngets the house style *and* the checker in one step.\r\n\r\n```\r\n/plugin marketplace add sv-grid/sv-grid\r\n/plugin install svgrid@svgrid\r\n```\r\n\r\nOr add the server on its own:\r\n\r\n```bash\r\n# hosted, nothing to install\r\nclaude mcp add --transport http svgrid https://mcp.svgrid.com/mcp\r\n\r\n# or local\r\nclaude mcp add svgrid -- npx -y @svgrid/mcp\r\n```\r\n\r\nThen run `/mcp` in a session and you will see `svgrid` listed.\r\n\r\nTo share the server with your team, add `--scope project`. That writes\r\na `.mcp.json` at the repository root which you can commit, so everyone\r\nwho clones the repo gets the same tooling with no per-machine setup:\r\n\r\n```bash\r\nclaude mcp add svgrid --scope project -- npx -y @svgrid/mcp\r\n```\r\n\r\n### Claude Desktop\r\n\r\nEdit `~/Library/Application Support/Claude/claude_desktop_config.json`\r\n(macOS) or `%APPDATA%\\Claude\\claude_desktop_config.json` (Windows):\r\n\r\n```json\r\n{\r\n  \"mcpServers\": {\r\n    \"svgrid\": {\r\n      \"command\": \"npx\",\r\n      \"args\": [\"-y\", \"@svgrid/mcp\"]\r\n    }\r\n  }\r\n}\r\n```\r\n\r\nOr the hosted server, with nothing to install:\r\n\r\n```json\r\n{\r\n  \"mcpServers\": {\r\n    \"svgrid\": {\r\n      \"type\": \"http\",\r\n      \"url\": \"https://mcp.svgrid.com/mcp\"\r\n    }\r\n  }\r\n}\r\n```\r\n\r\nRestart Claude Desktop, then ask *\"using svgrid, build me a grid that\r\ngroups by department\"* to confirm the tools are exposed.\r\n\r\n### Cursor\r\n\r\nOne click:\r\n[Add to Cursor](https://cursor.com/en/install-mcp?name=svgrid&config=eyJ1cmwiOiJodHRwczovL21jcC5zdmdyaWQuY29tL21jcCJ9)\r\n\r\nOr by hand, in `Settings -> MCP -> Add new MCP server`:\r\n\r\n```json\r\n{ \"url\": \"https://mcp.svgrid.com/mcp\" }\r\n```\r\n\r\n```json\r\n{ \"command\": \"npx\", \"args\": [\"-y\", \"@svgrid/mcp\"] }\r\n```\r\n\r\n### Zed\r\n\r\n`~/.config/zed/settings.json`:\r\n\r\n```json\r\n{\r\n  \"context_servers\": {\r\n    \"svgrid\": {\r\n      \"command\": \"npx\",\r\n      \"args\": [\"-y\", \"@svgrid/mcp\"],\r\n      \"env\": {}\r\n    }\r\n  }\r\n}\r\n```\r\n\r\n### VS Code\r\n\r\nOne click:\r\n[Add to VS Code](https://insiders.vscode.dev/redirect/mcp/install?name=svgrid&config=%7B%22name%22%3A%22svgrid%22%2C%22type%22%3A%22http%22%2C%22url%22%3A%22https%3A%2F%2Fmcp.svgrid.com%2Fmcp%22%7D)\r\n\r\nOr create `.vscode/mcp.json` in the workspace. Note that VS Code uses\r\n`servers` rather than the `mcpServers` wrapper:\r\n\r\n```json\r\n{\r\n  \"servers\": {\r\n    \"svgrid\": {\r\n      \"type\": \"http\",\r\n      \"url\": \"https://mcp.svgrid.com/mcp\"\r\n    }\r\n  }\r\n}\r\n```\r\n\r\n```json\r\n{\r\n  \"servers\": {\r\n    \"svgrid\": {\r\n      \"type\": \"stdio\",\r\n      \"command\": \"npx\",\r\n      \"args\": [\"-y\", \"@svgrid/mcp\"]\r\n    }\r\n  }\r\n}\r\n```\r\n\r\n### Custom agents (OpenAI Agents SDK, Anthropic SDK, LangChain)\r\n\r\nPoint your client's MCP stdio transport at `npx -y @svgrid/mcp`, or its\r\nstreamable-HTTP transport at `https://mcp.svgrid.com/mcp`. Any client that\r\nspeaks either transport works.\r\n\r\nThe hosted server names its two retrieval tools `search` and `fetch`\r\nexactly, which is what a connector needs to index it.\r\n\r\n## Tools exposed\r\n\r\nThe **local** server registers 36 tools: 9 for verification,\r\ndocumentation, examples, and scaffolding, plus 27 `studio_*` tools that\r\ndrive the SvGrid Studio project model. None require an API key.\r\n\r\nThe **hosted** server carries 6 of them: `check_svgrid_code`,\r\n`list_examples`, `get_example_source`, `get_api_reference`, and the\r\nretrieval pair `search` / `fetch` (which stand in for `search_docs`,\r\n`list_docs` and `get_doc`). The Studio tools need a filesystem, so they\r\nstay local - and a model that just wants a data grid should not spend\r\ncontext on an app builder it will never call.\r\n\r\n### Verification\r\n\r\n#### `check_svgrid_code`\r\n\r\nChecks a file **against the version you have installed** and returns\r\nline-numbered diagnostics with the exact replacement for each. Run it\r\non SvGrid code before you accept it; fix what it reports and run it\r\nagain.\r\n\r\n```ts\r\ncheck_svgrid_code(source: string, filename?: string): string\r\n```\r\n\r\n```jsonc\r\n{\r\n  \"ok\": false,\r\n  \"checkedAgainst\": \"@svgrid/grid@2.6.20\",\r\n  \"compiler\": \"svelte\",\r\n  \"counts\": { \"errors\": 2, \"warnings\": 0, \"info\": 0 },\r\n  \"diagnostics\": [\r\n    { \"rule\": \"svgrid/renamed-prop\", \"severity\": \"error\", \"line\": 24,\r\n      \"message\": \"`rowData` is not a SvGrid prop.\", \"fix\": \"Use `data`.\" },\r\n    { \"rule\": \"svgrid/renamed-column-key\", \"severity\": \"error\", \"line\": 10,\r\n      \"message\": \"`accessorKey` is not a SvGrid column key.\", \"fix\": \"Use `field`.\" }\r\n  ]\r\n}\r\n```\r\n\r\nIt checks four things:\r\n\r\n- **Names, against the installed version.** Importable symbols,\r\n  `<SvGrid>` props, `ColumnDef` keys, grid API methods, theme\r\n  stylesheets. The list is generated from the package sources at build\r\n  time, so it cannot drift from what the package exports; an unknown\r\n  name comes back with the nearest real one.\r\n- **Cross-package mistakes.** A symbol that lives in\r\n  `@svgrid/enterprise`, or an api method that only exists after\r\n  `installEnterprise(api)`.\r\n- **Svelte 5 rules.** `export let` and `$:` in a runes file (compiler\r\n  errors), `on:` / `<slot>` / `createEventDispatcher` (deprecations),\r\n  and a plain `let` array that is mutated and so never re-renders.\r\n- **The file, compiled.** When a Svelte compiler is reachable - your\r\n  project's copy first, then the one bundled here - real parse errors\r\n  come back too. The `compiler` field says which ran, so `\"ok\": true`\r\n  is never mistaken for \"this compiles\".\r\n\r\nIt is tuned to stay silent on correct code: it reports nothing across\r\nall 373 demos in the SvGrid repo, which a CI test asserts on every\r\ncommit. A checker that cries wolf is worse than none, because a model\r\nwill rewrite working code to satisfy it.\r\n\r\n### Documentation and examples\r\n\r\nThese six are free and need no license key.\r\n\r\n#### `list_examples`\r\n\r\nList every demo with `id`, `title`, and a one-line blurb. Use it to\r\ndiscover what exists before fetching source.\r\n\r\n```ts\r\nlist_examples(): Array<{ id, title, blurb, path }>\r\n```\r\n\r\n#### `get_example_source`\r\n\r\nReturn the full `.svelte` source of one demo, verbatim, including\r\nimports - the same file a user would copy into a project.\r\n\r\n```ts\r\nget_example_source({ id: '11-stock-market' }): string\r\n```\r\n\r\n#### `list_docs`\r\n\r\nList every documentation page with slug and title. Slugs use forward\r\nslashes, for example `help/columns/column-definitions`.\r\n\r\n```ts\r\nlist_docs(): Array<{ slug, title }>\r\n```\r\n\r\n#### `get_doc`\r\n\r\nReturn the markdown of a single page by slug.\r\n\r\n```ts\r\nget_doc({ slug: 'getting-started' }): string\r\n```\r\n\r\n#### `search_docs`\r\n\r\nCase-insensitive substring search across all docs. Returns matching\r\nslugs with a one-line excerpt around the first hit.\r\n\r\n`limit` is optional and defaults to 10.\r\n\r\n```ts\r\nsearch_docs({ query: 'row virtualization', limit: 10 })\r\n```\r\n\r\n#### `get_api_reference`\r\n\r\nThe curated public-API surface, grouped by category (components,\r\nheadless, scheduler, data ops, export, row models, features,\r\nvirtualization, accessibility, utilities).\r\n\r\n```ts\r\nget_api_reference(): string\r\n```\r\n\r\n### SvGrid Studio (commercial)\r\n\r\nThese tools generate application code. They still run without a\r\nlicense key, but generated files are prefixed with a comment pointing\r\nat [pricing](https://svgrid.com/pricing/). Set `SVGRID_LICENSE_KEY` in\r\nthe MCP server's environment for licensed use (see\r\n[Licensing](#licensing) below).\r\n\r\n#### `introspect_source`\r\n\r\nInfer a draft `EntitySchema` from a data source: either a Drizzle\r\nschema file (`kind: \"drizzle\"`, `source`: the file text) or sample\r\nrows (`kind: \"json\"`, `rows`, `name`). Review and refine the draft\r\nbefore scaffolding.\r\n\r\n```ts\r\nintrospect_source({ kind: 'drizzle', source: '...' })\r\nintrospect_source({ kind: 'json', rows: [...], name: 'orders' })\r\n```\r\n\r\n#### `scaffold_entity`\r\n\r\nGenerate runnable SvelteKit files from an `EntitySchema`: the `$lib`\r\nschema module, a `+server.ts` API route using `createKitHandlers`, and\r\na `+page.svelte` with `SvGrid` and `SvGridEditPanel`.\r\n\r\n`route` defaults to the schema name and `apiRoute` to `/api/{route}`.\r\n\r\n```ts {nocheck}\r\nscaffold_entity(args: {\r\n  schema: EntitySchema\r\n  route?: string\r\n  apiRoute?: string\r\n}): Array<{ path: string; contents: string; description: string }>\r\n```\r\n\r\nGenerated bodies are wrapped in `svgrid:managed` markers, so\r\nregeneration preserves your edits outside them. After writing the\r\nfiles, run the project's own `svelte-check` or `tsc` to verify they\r\ncompile.\r\n\r\n#### The `studio_*` tools\r\n\r\n27 tools let an agent build and edit the same validated project model\r\nthe visual designer uses, then generate the app:\r\n\r\n| Area | Tools |\r\n| ---- | ----- |\r\n| Project | `studio_new_project`, `studio_load_project`, `studio_describe_project`, `studio_validate`, `studio_capabilities`, `studio_get_config`, `studio_generate_app` |\r\n| Entities | `studio_add_entity`, `studio_set_entity_source` |\r\n| Screens | `studio_add_screen`, `studio_update_screen`, `studio_remove_screen`, `studio_set_screen_layout` |\r\n| Blocks and components | `studio_add_block`, `studio_update_block`, `studio_move_block`, `studio_remove_block`, `studio_add_component` |\r\n| Forms | `studio_set_form_layout`, `studio_set_field_conditions` |\r\n| Platform | `studio_set_auth`, `studio_set_access`, `studio_set_tenancy`, `studio_set_data_layer`, `studio_set_deploy_target`, `studio_set_theme`, `studio_set_job` |\r\n\r\nCall `studio_capabilities` first: it reports exactly what the\r\ninstalled version supports, so the agent does not have to guess.\r\n\r\n## Licensing\r\n\r\nThe documentation and example tools are free. The Studio code\r\ngenerators are part of the commercial offering: they run unlicensed,\r\nbut prepend a notice comment to generated files. To license them, set\r\nthe key in your MCP client's server config:\r\n\r\n```json\r\n{\r\n  \"mcpServers\": {\r\n    \"svgrid\": {\r\n      \"command\": \"npx\",\r\n      \"args\": [\"-y\", \"@svgrid/mcp\"],\r\n      \"env\": { \"SVGRID_LICENSE_KEY\": \"SVENTERPRISE-...\" }\r\n    }\r\n  }\r\n}\r\n```\r\n\r\n## Verifying it works\r\n\r\nAsk your model: *\"What MCP tools do you have from svgrid?\"* The local\r\nserver answers with 36, including `check_svgrid_code` and the `studio_*`\r\nset; the hosted server answers with 6.\r\n\r\nThen give it something to catch:\r\n\r\n> Check this with svgrid: `<SvGrid rowData={rows} {columns} />`\r\n\r\nIt should come back with `rowData` is not a SvGrid prop, use `data`. If\r\nit explains the code instead of calling a tool, the server is not\r\nconnected.\r\n\r\nIf nothing is listed at all, check your client's MCP log. For the local\r\nserver the usual cause is `npx` not being on PATH - use the absolute path\r\nto the binary. For the hosted one, confirm the endpoint answers:\r\n\r\n```bash\r\ncurl https://mcp.svgrid.com/health\r\n```\r\n\r\n## Security model\r\n\r\nThe two ways of running it differ here, so pick deliberately.\r\n\r\n**Local (`npx @svgrid/mcp`)**\r\n\r\n- Runs on your machine over stdio. No telemetry, no outbound network\r\n  calls, no API key.\r\n- Serves a documentation and example corpus bundled into the package at\r\n  build time, so answers are pinned to the version you installed.\r\n- `check_svgrid_code` reads the source you pass it in-process and never\r\n  sends it anywhere.\r\n\r\n**Hosted (`https://mcp.svgrid.com/mcp`)**\r\n\r\n- Your client sends tool arguments to a Cloudflare Worker we operate.\r\n  Anything you pass to a tool leaves your machine, and for\r\n  `check_svgrid_code` that means **the source you ask it to check**.\r\n- Each call is logged: tool name, duration, whether it succeeded, and the\r\n  query or id it was given. For `check_svgrid_code` only the **byte\r\n  length** of the submitted source is recorded, never the source itself.\r\n- No account, no key, no cookies. Requests are not tied to a user.\r\n- If your code cannot leave the building, use the local server. That is\r\n  what it is for.\r\n\r\n**Both**\r\n\r\n- The Studio tools return generated files as data. Writing them to disk\r\n  is your client's decision, not the server's.\r\n- See [security](./security.md) for the general supply-chain posture.\r\n\r\n## Building your own MCP integrations\r\n\r\nThe same docs manifest, JSON Schemas, and `llms.txt` files are also\r\nserved directly from the docs site:\r\n\r\n```ts\r\nconst docs    = await fetch('https://svgrid.com/docs.json').then((r) => r.json())\r\nconst schemas = await fetch('https://svgrid.com/schemas/index.json').then((r) => r.json())\r\nconst llms    = await fetch('https://svgrid.com/llms-full.txt').then((r) => r.text())\r\n```\r\n\r\nIf you do not want to run the MCP server, building these into your\r\nagent's system prompt gives most of the same grounding.\r\n\r\n## Frequently asked questions\r\n\r\n### What is the SvGrid MCP server?\r\n\r\nA Model Context Protocol server that lets AI clients (Claude Code, Claude\r\nDesktop, Cursor, Zed, custom agents) query SvGrid's documentation, read real\r\ndemo source, scaffold SvelteKit CRUD apps, and check the code they write\r\nagainst the real API - grounded in the files the package ships, so the model\r\nanswers from current facts instead of guessing.\r\n\r\n### Do I need an API key to run it?\r\n\r\nNo, on either transport. A `SVGRID_LICENSE_KEY` is optional and only affects\r\nthe commercial Studio code generators.\r\n\r\n### Local or hosted - which should I use?\r\n\r\nHosted (`https://mcp.svgrid.com/mcp`) if you want it working in one paste,\r\nwith no Node and no config file. Local (`npx @svgrid/mcp`) if you want the\r\nSvelte compiler pass in `check_svgrid_code`, the 27 Studio tools, offline\r\nuse, or your source never leaving the machine. See\r\n[Security model](#security-model) for what each one sends.\r\n\r\n### How does it help AI assistants write better SvGrid code?\r\n\r\nTwo ways. It exposes the docs, example sources, and API reference as tools,\r\nso the assistant retrieves version-pinned answers instead of hallucinating an\r\nAPI from training data. And `check_svgrid_code` closes the loop: the model\r\nruns what it wrote past the real exported surface and gets told exactly what\r\nis wrong before you see it. That matters most for Svelte 5, where models\r\nroutinely mix in outdated Svelte 4 syntax.\r\n\r\n### Does it work with a version of SvGrid I have not upgraded to?\r\n\r\nThe local server answers for the version bundled in the `@svgrid/mcp` release\r\nyou install, so pin it alongside `@svgrid/grid` if you are behind. The hosted\r\nserver always tracks the current release. Either way, every\r\n`check_svgrid_code` result names the version it checked against in its\r\n`checkedAgainst` field.\r\n\r\n## See also\r\n\r\n- [Agent Skill](./skill.md) - the always-on house-style layer; the Claude Code plugin installs it together with this server\r\n- [LLM grounding](./llm-grounding.md) - the same files used by the MCP server, but documented for direct LLM consumption\r\n- [Agents](./agents.md) - how to build an AI agent that drives the live grid\r\n- [AI assistant](./ai.md) - the in-grid AI features (filter / smart-fill / classify / summarise), free in @svgrid/grid\r\n"
+        "markdown": "# MCP server\r\n\r\nThe SvGrid MCP server does two things for an AI client (Claude Code,\r\nClaude Desktop, Cursor, Zed, Codex, custom agents): it answers questions\r\nabout SvGrid from the files this repository ships, and it **checks the\r\ncode the model writes** against the real exported surface of the version\r\nyou have installed. No API key either way.\r\n\r\n![An AI coding agent calls the @svgrid/mcp server over the Model Context Protocol, which runs grid tools and returns structured JSON results back to the agent.](/docs-media/grid-mcp.svg)\r\n\r\n> **What is MCP?** Model Context Protocol is the open standard\r\n> ([modelcontextprotocol.io](https://modelcontextprotocol.io)) for\r\n> exposing tools to LLM clients. SvGrid ships an MCP server so the\r\n> model your team already uses can \"see\" the grid without you having\r\n> to copy-paste docs into prompts.\r\n\r\nIt runs either way you like: as a local process\r\n([`@svgrid/mcp`](https://www.npmjs.com/package/@svgrid/mcp) on npm), or as\r\na hosted endpoint at `https://mcp.svgrid.com/mcp` that needs no install at\r\nall. Both are listed in the official MCP registry as `com.svgrid/svgrid`.\r\n\r\n## Two ways to connect\r\n\r\n**Hosted (nothing to install).** Point any MCP client at the URL:\r\n\r\n```\r\nhttps://mcp.svgrid.com/mcp\r\n```\r\n\r\n```bash\r\nclaude mcp add --transport http svgrid https://mcp.svgrid.com/mcp\r\n```\r\n\r\nOne click:\r\n[Add to Cursor](https://cursor.com/en/install-mcp?name=svgrid&config=eyJ1cmwiOiJodHRwczovL21jcC5zdmdyaWQuY29tL21jcCJ9)\r\n· [Add to VS Code](https://insiders.vscode.dev/redirect/mcp/install?name=svgrid&config=%7B%22name%22%3A%22svgrid%22%2C%22type%22%3A%22http%22%2C%22url%22%3A%22https%3A%2F%2Fmcp.svgrid.com%2Fmcp%22%7D)\r\n\r\nIt carries six tools - `search`, `fetch`, `list_examples`,\r\n`get_example_source`, `get_api_reference` and `check_svgrid_code` - and\r\nneeds no Node, no config file, and no key.\r\n\r\n**Local (`npx @svgrid/mcp`).** Everything the hosted server has, plus\r\nthe Studio tools, the docs and demos as MCP resources, ready-made\r\nprompts, and a `svgrid_check_code` that additionally *compiles* the file\r\nwith the Svelte compiler rather than checking it statically. Use it when\r\nyou want the compile pass, the Studio tools, or no third-party endpoint\r\nin the loop.\r\n\r\n|  | Hosted | Local |\r\n| --- | --- | --- |\r\n| Setup | a URL | `npx @svgrid/mcp` |\r\n| Needs Node | no | yes |\r\n| Code check compiles | no, static checks only | yes |\r\n| Resources and prompts | yes | yes |\r\n| Visual preview | yes | yes |\r\n| `studio_*` tools | no | yes, opt-in |\r\n| Works offline | no | yes |\r\n\r\n## Install\r\n\r\nNo install step is required - `npx` fetches it on demand:\r\n\r\n```bash\r\n# One-shot, from any project\r\nnpx -y @svgrid/mcp\r\n```\r\n\r\nTo pin it as a dev dependency instead:\r\n\r\n```bash\r\npnpm add -D @svgrid/mcp\r\n```\r\n\r\nThe local server is a Node binary (`svgrid-mcp`) that speaks MCP over\r\nstdio. There is no daemon to maintain. The hosted server needs no install\r\nstep at all - skip to [Wire it into your AI client](#wire-it-into-your-ai-client)\r\nand use the URL.\r\n\r\n## Wire it into your AI client\r\n\r\nEvery snippet below shows the local (stdio) form and the hosted (HTTP)\r\nform. Pick one - running both connects the same tools twice.\r\n\r\n### Claude Code\r\n\r\nThe plugin is the shortest path: it installs the\r\n[Agent Skill](./skill.md) and the hosted server together, so the model\r\ngets the house style *and* the checker in one step.\r\n\r\n```\r\n/plugin marketplace add sv-grid/sv-grid\r\n/plugin install svgrid@svgrid\r\n```\r\n\r\nOr add the server on its own:\r\n\r\n```bash\r\n# hosted, nothing to install\r\nclaude mcp add --transport http svgrid https://mcp.svgrid.com/mcp\r\n\r\n# or local\r\nclaude mcp add svgrid -- npx -y @svgrid/mcp\r\n```\r\n\r\nThen run `/mcp` in a session and you will see `svgrid` listed.\r\n\r\nTo share the server with your team, add `--scope project`. That writes\r\na `.mcp.json` at the repository root which you can commit, so everyone\r\nwho clones the repo gets the same tooling with no per-machine setup:\r\n\r\n```bash\r\nclaude mcp add svgrid --scope project -- npx -y @svgrid/mcp\r\n```\r\n\r\n### Claude Desktop\r\n\r\nEdit `~/Library/Application Support/Claude/claude_desktop_config.json`\r\n(macOS) or `%APPDATA%\\Claude\\claude_desktop_config.json` (Windows):\r\n\r\n```json\r\n{\r\n  \"mcpServers\": {\r\n    \"svgrid\": {\r\n      \"command\": \"npx\",\r\n      \"args\": [\"-y\", \"@svgrid/mcp\"]\r\n    }\r\n  }\r\n}\r\n```\r\n\r\nOr the hosted server, with nothing to install:\r\n\r\n```json\r\n{\r\n  \"mcpServers\": {\r\n    \"svgrid\": {\r\n      \"type\": \"http\",\r\n      \"url\": \"https://mcp.svgrid.com/mcp\"\r\n    }\r\n  }\r\n}\r\n```\r\n\r\nRestart Claude Desktop, then ask *\"using svgrid, build me a grid that\r\ngroups by department\"* to confirm the tools are exposed.\r\n\r\n### Cursor\r\n\r\nOne click:\r\n[Add to Cursor](https://cursor.com/en/install-mcp?name=svgrid&config=eyJ1cmwiOiJodHRwczovL21jcC5zdmdyaWQuY29tL21jcCJ9)\r\n\r\nOr by hand, in `Settings -> MCP -> Add new MCP server`:\r\n\r\n```json\r\n{ \"url\": \"https://mcp.svgrid.com/mcp\" }\r\n```\r\n\r\n```json\r\n{ \"command\": \"npx\", \"args\": [\"-y\", \"@svgrid/mcp\"] }\r\n```\r\n\r\n### Zed\r\n\r\n`~/.config/zed/settings.json`:\r\n\r\n```json\r\n{\r\n  \"context_servers\": {\r\n    \"svgrid\": {\r\n      \"command\": \"npx\",\r\n      \"args\": [\"-y\", \"@svgrid/mcp\"],\r\n      \"env\": {}\r\n    }\r\n  }\r\n}\r\n```\r\n\r\n### VS Code\r\n\r\nOne click:\r\n[Add to VS Code](https://insiders.vscode.dev/redirect/mcp/install?name=svgrid&config=%7B%22name%22%3A%22svgrid%22%2C%22type%22%3A%22http%22%2C%22url%22%3A%22https%3A%2F%2Fmcp.svgrid.com%2Fmcp%22%7D)\r\n\r\nOr create `.vscode/mcp.json` in the workspace. Note that VS Code uses\r\n`servers` rather than the `mcpServers` wrapper:\r\n\r\n```json\r\n{\r\n  \"servers\": {\r\n    \"svgrid\": {\r\n      \"type\": \"http\",\r\n      \"url\": \"https://mcp.svgrid.com/mcp\"\r\n    }\r\n  }\r\n}\r\n```\r\n\r\n```json\r\n{\r\n  \"servers\": {\r\n    \"svgrid\": {\r\n      \"type\": \"stdio\",\r\n      \"command\": \"npx\",\r\n      \"args\": [\"-y\", \"@svgrid/mcp\"]\r\n    }\r\n  }\r\n}\r\n```\r\n\r\n### Custom agents (OpenAI Agents SDK, Anthropic SDK, LangChain)\r\n\r\nPoint your client's MCP stdio transport at `npx -y @svgrid/mcp`, or its\r\nstreamable-HTTP transport at `https://mcp.svgrid.com/mcp`. Any client that\r\nspeaks either transport works.\r\n\r\nThe hosted server names its two retrieval tools `search` and `fetch`\r\nexactly, which is what a connector needs to index it.\r\n\r\n## Tools exposed\r\n\r\nFour, by default. `tools/list` is sent on **every** request, so the tool\r\nsurface is pure overhead on every turn - and this server used to spend\r\n~4,710 tokens of it on 36 tools, 79% of them Studio tools that most\r\nsessions never call once.\r\n\r\n| Tool | What it does |\r\n| ---- | ------------ |\r\n| `svgrid_search` | Search the docs, the 375 demos and the API surface **in one call**. No arguments returns an index. |\r\n| `svgrid_get` | Read one thing in full: a doc slug, a demo id, or `api`. |\r\n| `svgrid_check_code` | Verify code against the real exported surface before the user sees it. |\r\n| `svgrid_preview` | Render a **live, interactive grid** in the conversation from columns + rows. |\r\n| `svgrid_scaffold` | Turn a Drizzle schema, sample rows or an EntitySchema into runnable SvelteKit files. |\r\n\r\nStudio adds four more, and only when you ask for them - set\r\n`SVGRID_MCP_STUDIO=1` or a licence key in the server's env. They need a\r\nlicence to be useful, so they are not charged to everyone else's context\r\nwindow.\r\n\r\nThe **hosted** server carries `search`, `fetch`, `list_examples`,\r\n`get_example_source`, `get_api_reference`, `check_svgrid_code` and\r\n`svgrid_preview`, plus the same resources and prompts. The first two are named\r\nthat way deliberately: those exact names are what a one-click connector needs to\r\nindex a remote server. It also answers to `svgrid_search`, `svgrid_get` and\r\n`svgrid_check_code`, so a model that learned the npm package's names is never\r\ntold \"unknown tool\".\r\n\r\nWhat it does **not** have is the compile pass (the Svelte compiler cannot run in\r\na Worker), the Studio tools (they need a filesystem), and the offline guarantee\r\n- it is a remote server, so by definition your query reaches it. Use the local\r\none when any of those matter.\r\n\r\n### Verification\r\n\r\n#### `svgrid_check_code`\r\n\r\nChecks a file **against the version you have installed** and returns\r\nline-numbered diagnostics with the exact replacement for each: unknown\r\n`<SvGrid>` props, wrong `ColumnDef` keys, api methods that do not\r\nexist, imports that will not resolve, and Svelte 5 runes mistakes. It\r\nalso compiles the component, so a syntax error surfaces here rather\r\nthan in the user's terminal.\r\n\r\nThis is the tool that makes the rest worth having. Retrieval alone\r\nstill lets a model write a confident, wrong grid; nothing else in the\r\nserver stops it. Run it on every file you write, fix what it reports,\r\nand run it again.\r\n\r\n### Finding and reading\r\n\r\n#### `svgrid_search`\r\n\r\nOne call across all three corpora, because \"how do I pin a column\" does\r\nnot announce whether it is answered by a doc page, a demo, or an API\r\nname:\r\n\r\n```json\r\n{ \"query\": \"pin a column\" }\r\n```\r\n\r\nReturns ranked doc hits with excerpts, matching demos, and matching API\r\nnames - each with the reference you pass to `svgrid_get`. Narrow with\r\n`kind` (`docs` | `examples` | `api`), trade tokens for completeness\r\nwith `detail` (`concise` | `full`), and cap with `limit` (max 50).\r\n\r\nCall it with **no arguments** for an index of doc sections, demo\r\ncategories and API groups - the cheapest way to orient before searching.\r\n\r\n#### `svgrid_get`\r\n\r\n```json\r\n{ \"ref\": \"help/columns/column-definitions\" }\r\n{ \"ref\": \"11-stock-market\" }\r\n{ \"ref\": \"api\" }\r\n```\r\n\r\nThe kind is inferred from the reference; pass `kind` to force it. A\r\nreference that does not resolve comes back with near matches rather\r\nthan a bare \"not found\".\r\n\r\n### It fixes what it finds\r\n\r\n`svgrid_check_code` does not stop at telling you what is wrong. Where the\r\ncorrection is exact it returns the corrected file too:\r\n\r\n```json\r\n{\r\n  \"diagnostics\": [ ... ],\r\n  \"applied\": [\"rowData -> data (line 7)\", \"accessorKey -> field (line 3)\"],\r\n  \"fixed\": \"<the corrected source>\"\r\n}\r\n```\r\n\r\nBoth fields are omitted when there is nothing mechanically fixable, so a clean\r\ncheck stays small.\r\n\r\nThe rules are deliberately narrow, because this tool's whole worth is that it\r\nnever cries wolf - and rewriting raises the stakes from wasting a turn to\r\ncorrupting working code. Only exact renames are applied (a known rename, or a\r\nclose-enough spelling), only on word boundaries, and only on the line the\r\ndiagnostic reported. Advice that is ambiguous - \"this has no equivalent, remove\r\nit\" - stays advice. A test asserts that running auto-fix across all 367 demos\r\nin this repository changes nothing at all.\r\n\r\n### It knows which version you have\r\n\r\nThe result carries the version it checked against:\r\n\r\n```json\r\n{ \"version\": { \"corpus\": \"3.0.0\", \"installed\": \"2.6.8\", \"warning\": \"...\" } }\r\n```\r\n\r\nThe server reads the `@svgrid/grid` in your project and says plainly when it\r\ndisagrees with the corpus it ships, so a model is told to hedge instead of\r\nconfidently citing an API you do not have. A server that answers from a remote\r\nbackend cannot do this - it has no idea what is in your `node_modules`.\r\n\r\n### Nothing leaves your machine\r\n\r\nThis server makes **no network calls**. Not for docs, not for the API surface,\r\nnot for verification - the whole corpus (375 demos, 408 doc pages, the full\r\nexported API) ships inside the package, which is why it is 8 MB rather than\r\n90 KB. There is no API key, no licence check on the wire, and no telemetry.\r\n\r\nIt works on a plane, behind a corporate proxy, and inside an air-gapped\r\nnetwork. `tools/mcp-offline.test.ts` enforces it: the server is driven through\r\na full session with every network primitive booby-trapped, and the test fails if\r\nanything is even attempted.\r\n\r\nThe one honest exception: the **preview** loads the grid from a CDN to draw it.\r\nThat happens in your client's sandboxed iframe, never in this server, and only\r\nwhen you actually render a preview.\r\n\r\n### Seeing the grid, not just reading about it\r\n\r\n`svgrid_preview` renders a **real, interactive SvGrid inside the\r\nconversation** - sortable, filterable, scrollable. Not a screenshot and not a\r\nmock table: the same `<sv-grid>` custom element a page would use, loaded from\r\nthe CDN, with the columns and rows you passed.\r\n\r\n```json\r\n{\r\n  \"title\": \"Team roster\",\r\n  \"columns\": [{ \"field\": \"name\", \"header\": \"Name\" }, { \"field\": \"amount\", \"header\": \"Amount\" }],\r\n  \"data\": [{ \"name\": \"Ada\", \"amount\": 20000 }],\r\n  \"sortable\": true\r\n}\r\n```\r\n\r\nIt uses [MCP Apps](https://blog.modelcontextprotocol.io/posts/2026-01-26-mcp-apps/),\r\nthe official UI extension: the tool points at a `ui://` resource through\r\n`_meta`, the client loads that HTML in a sandboxed iframe, and the tool's\r\n`structuredContent` arrives over a postMessage bridge. Supported in Claude\r\n(web and desktop), VS Code and ChatGPT.\r\n\r\nClients without UI support are not left out - they ignore the `_meta` and get\r\na text summary of the same grid, so it is always safe to call. That is the\r\nextension's own rule, and it is why the text half describes the grid rather\r\nthan pointing at a picture the reader cannot see.\r\n\r\nPass `demo` instead of `columns` / `data` and you get the demo's source: a\r\ndemo is a Svelte component, not data, so there is nothing to hand the element\r\nand rendering an empty grid would just look broken.\r\n\r\n### Resources and prompts\r\n\r\nThe docs and demos are also exposed as **MCP resources**, so a user can\r\nattach a page or a demo directly instead of hoping the model thinks to\r\nsearch for it:\r\n\r\n```\r\nsvgrid://doc/help/columns/column-definitions\r\nsvgrid://example/11-stock-market\r\n```\r\n\r\nAnd three **prompts** ship ready to run: `build_grid`, `explain_api`\r\nand `review_grid_code`. Each is written to make the model use this\r\nserver rather than recall SvGrid from training data, and each ends at\r\n`svgrid_check_code`.\r\n\r\n### SvGrid Studio (commercial)\r\n\r\nOff unless enabled. Set `SVGRID_MCP_STUDIO=1`, or a valid\r\n`SVGRID_LICENSE_KEY`, in the server's env.\r\n\r\n#### `svgrid_scaffold`\r\n\r\nPoint it at a Drizzle schema, sample JSON rows, or an `EntitySchema`\r\nyou already have, and it infers the schema and generates the `$lib`\r\nschema module, a `+server.ts` API route and a `+page.svelte` with\r\n`SvGrid` + `SvGridEditPanel` - in one call. Pass `schemaOnly: true` to\r\nstop after inference. Generated bodies carry `svgrid:managed` markers,\r\nso regenerating preserves your edits outside them.\r\n\r\n#### The `studio_*` tools\r\n\r\nFour tools drive the same validated project model the visual designer\r\nuses:\r\n\r\n| Tool | What it does |\r\n| ---- | ------------ |\r\n| `studio_project` | `new`, `load`, `describe`, `config`, `capabilities` |\r\n| `studio_apply` | A **batch** of model changes - entities, screens, blocks, components - applied in order |\r\n| `studio_configure` | Theme, auth, access, tenancy, data layer, jobs, deploy target, layouts, in one call |\r\n| `studio_build` | `validate`, then `generate` the full runnable SvelteKit app |\r\n\r\nCall `studio_project` with `action: \"capabilities\"` first: it reports\r\nexactly what the installed version supports, so the agent does not have\r\nto guess block kinds or component keys.\r\n\r\n`studio_apply` takes a batch on purpose. Building a five-screen app was\r\ntwenty-odd round trips when every block was its own tool; now a whole\r\nscreen is one call, and a failure reports which op failed and what\r\nalready applied.\r\n\r\n### The pre-3.0 names\r\n\r\nEvery tool name from before 3.0 still answers - `search_docs`,\r\n`get_doc`, `list_examples`, `get_example_source`, `list_docs`,\r\n`get_api_reference`, `check_svgrid_code`, `introspect_source`,\r\n`scaffold_entity` and all 27 individual `studio_*` tools. They are not\r\n**listed**, because listing is what costs context and answering a name\r\nyou did not advertise costs nothing. Saved prompts and scripts keep\r\nworking; nobody pays for the compatibility.\r\n\r\nTheir JSON response shape follows 3.0, not 2.x. A model reads either\r\nwithout trouble; a script that parsed the old shape by hand needs a look.\r\n\r\n## Licensing\r\n\r\nThe documentation and example tools are free. The Studio code\r\ngenerators are part of the commercial offering: they run unlicensed,\r\nbut prepend a notice comment to generated files. To license them, set\r\nthe key in your MCP client's server config:\r\n\r\n```json\r\n{\r\n  \"mcpServers\": {\r\n    \"svgrid\": {\r\n      \"command\": \"npx\",\r\n      \"args\": [\"-y\", \"@svgrid/mcp\"],\r\n      \"env\": { \"SVGRID_LICENSE_KEY\": \"SVENTERPRISE-...\" }\r\n    }\r\n  }\r\n}\r\n```\r\n\r\n## Verifying it works\r\n\r\nAsk your model: *\"What MCP tools do you have from svgrid?\"* The local\r\nserver answers with 36, including `check_svgrid_code` and the `studio_*`\r\nset; the hosted server answers with 6.\r\n\r\nThen give it something to catch:\r\n\r\n> Check this with svgrid: `<SvGrid rowData={rows} {columns} />`\r\n\r\nIt should come back with `rowData` is not a SvGrid prop, use `data`. If\r\nit explains the code instead of calling a tool, the server is not\r\nconnected.\r\n\r\nIf nothing is listed at all, check your client's MCP log. For the local\r\nserver the usual cause is `npx` not being on PATH - use the absolute path\r\nto the binary. For the hosted one, confirm the endpoint answers:\r\n\r\n```bash\r\ncurl https://mcp.svgrid.com/health\r\n```\r\n\r\n## Security model\r\n\r\nThe two ways of running it differ here, so pick deliberately.\r\n\r\n**Local (`npx @svgrid/mcp`)**\r\n\r\n- Runs on your machine over stdio. No telemetry, no outbound network\r\n  calls, no API key.\r\n- Serves a documentation and example corpus bundled into the package at\r\n  build time, so answers are pinned to the version you installed.\r\n- `check_svgrid_code` reads the source you pass it in-process and never\r\n  sends it anywhere.\r\n\r\n**Hosted (`https://mcp.svgrid.com/mcp`)**\r\n\r\n- Your client sends tool arguments to a Cloudflare Worker we operate.\r\n  Anything you pass to a tool leaves your machine, and for\r\n  `check_svgrid_code` that means **the source you ask it to check**.\r\n- Each call is logged: tool name, duration, whether it succeeded, and the\r\n  query or id it was given. For `check_svgrid_code` only the **byte\r\n  length** of the submitted source is recorded, never the source itself.\r\n- No account, no key, no cookies. Requests are not tied to a user.\r\n- If your code cannot leave the building, use the local server. That is\r\n  what it is for.\r\n\r\n**Both**\r\n\r\n- The Studio tools return generated files as data. Writing them to disk\r\n  is your client's decision, not the server's.\r\n- See [security](./security.md) for the general supply-chain posture.\r\n\r\n## Building your own MCP integrations\r\n\r\nThe same docs manifest, JSON Schemas, and `llms.txt` files are also\r\nserved directly from the docs site:\r\n\r\n```ts\r\nconst docs    = await fetch('https://svgrid.com/docs.json').then((r) => r.json())\r\nconst schemas = await fetch('https://svgrid.com/schemas/index.json').then((r) => r.json())\r\nconst llms    = await fetch('https://svgrid.com/llms-full.txt').then((r) => r.text())\r\n```\r\n\r\nIf you do not want to run the MCP server, building these into your\r\nagent's system prompt gives most of the same grounding.\r\n\r\n## Frequently asked questions\r\n\r\n### What is the SvGrid MCP server?\r\n\r\nA Model Context Protocol server that lets AI clients (Claude Code, Claude\r\nDesktop, Cursor, Zed, custom agents) query SvGrid's documentation, read real\r\ndemo source, scaffold SvelteKit CRUD apps, and check the code they write\r\nagainst the real API - grounded in the files the package ships, so the model\r\nanswers from current facts instead of guessing.\r\n\r\n### Do I need an API key to run it?\r\n\r\nNo, on either transport. A `SVGRID_LICENSE_KEY` is optional and only affects\r\nthe commercial Studio code generators.\r\n\r\n### Local or hosted - which should I use?\r\n\r\nHosted (`https://mcp.svgrid.com/mcp`) if you want it working in one paste,\r\nwith no Node and no config file. Local (`npx @svgrid/mcp`) if you want the\r\nSvelte compiler pass in `check_svgrid_code`, the 27 Studio tools, offline\r\nuse, or your source never leaving the machine. See\r\n[Security model](#security-model) for what each one sends.\r\n\r\n### How does it help AI assistants write better SvGrid code?\r\n\r\nTwo ways. It exposes the docs, example sources, and API reference as tools,\r\nso the assistant retrieves version-pinned answers instead of hallucinating an\r\nAPI from training data. And `check_svgrid_code` closes the loop: the model\r\nruns what it wrote past the real exported surface and gets told exactly what\r\nis wrong before you see it. That matters most for Svelte 5, where models\r\nroutinely mix in outdated Svelte 4 syntax.\r\n\r\n### Does it work with a version of SvGrid I have not upgraded to?\r\n\r\nThe local server answers for the version bundled in the `@svgrid/mcp` release\r\nyou install, so pin it alongside `@svgrid/grid` if you are behind. The hosted\r\nserver always tracks the current release. Either way, every\r\n`check_svgrid_code` result names the version it checked against in its\r\n`checkedAgainst` field.\r\n\r\n## See also\r\n\r\n- [Agent Skill](./skill.md) - the always-on house-style layer; the Claude Code plugin installs it together with this server\r\n- [LLM grounding](./llm-grounding.md) - the same files used by the MCP server, but documented for direct LLM consumption\r\n- [Agents](./agents.md) - how to build an AI agent that drives the live grid\r\n- [AI assistant](./ai.md) - the in-grid AI features (filter / smart-fill / classify / summarise), free in @svgrid/grid\r\n"
     },
     {
         "slug": "help/migrating-from-ag-grid",
@@ -4441,7 +4441,7 @@ export const docs = [
         "path": "docs/help/skill.md",
         "title": "Agent Skill",
         "section": "Help",
-        "markdown": "# Agent Skill\n\nThe SvGrid **Agent Skill** gives AI coding assistants project-aware\ncontext for writing correct SvGrid code. It is the always-on counterpart\nto the [MCP server](./mcp-server.md): the skill carries the API surface and\nhouse style so your assistant follows SvGrid's conventions without being\ntold, and the MCP server supplies live, version-pinned lookups on demand.\n\nSkills are the [Agent Skills](https://docs.claude.com/en/docs/agents-and-tools/agent-skills)\nformat - a `SKILL.md` file with a short description the client loads\nautomatically, plus reference files it reads when it needs detail. Claude\nCode and other skill-aware clients pick it up with no per-prompt setup.\n\n## What it knows\n\nOnce installed, the assistant has SvGrid's rules in context whenever you\nwork in a project that imports from `@svgrid/*`:\n\n- **Project context** - it reads your `package.json` to see whether you\n  have `@svgrid/grid` alone or `@svgrid/enterprise` too, confirms Svelte 5,\n  and matches your existing theming convention instead of inventing one.\n- **The API surface** - `ColumnDef` (every column needs a stable `id`),\n  the `<SvGrid>` shortcut props (`sortable` / `filterable` / `pageable` /\n  `editable` / `groupable` each inject their feature), the `SvGridApi` from\n  `onApiReady`, and `createServerDataSource` for server-side data.\n- **Theming** - `--sg-*` tokens, dark mode through your app's selector,\n  the shipped design-system presets, and how to bridge to shadcn / Tailwind\n  tokens. Never targeting mangled internal class names.\n- **The package boundary** - enterprise symbols (`installEnterprise`,\n  `setAIProvider`, pivot, export) never leak into a grid-only project.\n- **Correct-vs-incorrect pairs** - the reference files show the wrong way\n  and the right way side by side, so the model corrects itself.\n\nCrucially, for anything version-specific the skill tells the model to\n**look it up rather than guess** - fetching the grounding files or calling\nthe MCP tools - so its answers track the version you actually have\ninstalled.\n\n## Install\n\n### Claude Code: the plugin (skill + MCP server in one)\n\nTwo commands, and you get the skill *and* the MCP server that checks the\ncode it produces:\n\n```\n/plugin marketplace add sv-grid/sv-grid\n/plugin install svgrid@svgrid\n```\n\nThe plugin wires up the hosted MCP server at `https://mcp.svgrid.com/mcp`,\nso there is nothing to install and no key to configure. The skill supplies\nthe house style; the server's `check_svgrid_code` tool verifies each file\nagainst the real API surface before you see it. Prefer this over installing\nthe two separately.\n\n### Any other client: the skill on its own\n\nWith the [`skills`](https://www.npmjs.com/package/skills) CLI, pointed at\nthe SvGrid repository:\n\n```bash\nnpx skills add sv-grid/sv-grid\n# or\npnpm dlx skills add sv-grid/sv-grid\n```\n\nThat installs the skill into your project. Alternatively, copy the folder\nstraight into your project's skills directory:\n\n```bash\ncp -r skills/svgrid your-project/.claude/skills/svgrid\n```\n\nThe skill lives at [`skills/svgrid/`](https://github.com/sv-grid/sv-grid/tree/main/skills/svgrid)\nin the repo, so you can also read or fork it directly.\n\n## What's inside\n\n| File | Covers |\n| --- | --- |\n| `SKILL.md` | Entry point: project context, the minimal grid, critical rules, grounding, package boundary, scaffolding |\n| `rules/columns.md` | `ColumnDef`, custom cell snippets, widths, `type`, conditional formatting, editors |\n| `rules/data-and-features.md` | Feature toggles vs. shortcut props, the `SvGridApi`, reactive data, server-side data source |\n| `rules/theming.md` | `--sg-*` tokens, dark mode, design-system presets, the shadcn / Tailwind bridge |\n\n## Skill vs. MCP server vs. grounding files\n\nSvGrid ships three ways to make an assistant write correct code; they\nlayer, they don't compete.\n\n| | Agent Skill | [MCP server](./mcp-server.md) | [Grounding files](./llm-grounding.md) |\n| --- | --- | --- | --- |\n| **What it is** | Always-on rules + house style | Callable tools (docs, demos, schemas) | Static `llms.txt` / `docs.json` / schemas |\n| **How it loads** | Auto, when a `@svgrid/*` project is detected | The model calls a tool | You paste or fetch the file |\n| **Best for** | Following SvGrid conventions by default | Version-pinned lookups mid-task | Custom GPTs, rules files, your own agent |\n| **Setup** | `npx skills add sv-grid/sv-grid` | One line of MCP config | Upload / fetch a URL |\n\nA common setup is the skill **and** the MCP server: the skill keeps the\nmodel on-convention, and the server answers \"what's the exact signature of\n`setFilter` in the version I have?\" when it matters.\n\n## See also\n\n- [MCP server](./mcp-server.md) - callable tools for Claude Desktop / Cursor / Zed / Claude Code\n- [LLM grounding](./llm-grounding.md) - the static files any model can read\n- [AI Toolkit](./ai-toolkit.md) - the full build-time and runtime AI surface\n- [Agents](./agents.md) - build an agent that drives the live grid\n"
+        "markdown": "# Agent Skill\n\nThe SvGrid **Agent Skill** gives AI coding assistants project-aware\ncontext for writing correct SvGrid code. It is the always-on counterpart\nto the [MCP server](./mcp-server.md): the skill carries the API surface and\nhouse style so your assistant follows SvGrid's conventions without being\ntold, and the MCP server supplies live, version-pinned lookups on demand.\n\nSkills are the [Agent Skills](https://docs.claude.com/en/docs/agents-and-tools/agent-skills)\nformat - a `SKILL.md` file with a short description the client loads\nautomatically, plus reference files it reads when it needs detail. Claude\nCode and other skill-aware clients pick it up with no per-prompt setup.\n\n## What it knows\n\nOnce installed, the assistant has SvGrid's rules in context whenever you\nwork in a project that imports from `@svgrid/*`:\n\n- **Project context** - it reads your `package.json` to see whether you\n  have `@svgrid/grid` alone or `@svgrid/enterprise` too, confirms Svelte 5,\n  and matches your existing theming convention instead of inventing one.\n- **The API surface** - `ColumnDef` (every column needs a stable `id`),\n  the `<SvGrid>` shortcut props (`sortable` / `filterable` / `pageable` /\n  `editable` / `groupable` each inject their feature), the `SvGridApi` from\n  `onApiReady`, and `createServerDataSource` for server-side data.\n- **Theming** - `--sg-*` tokens, dark mode through your app's selector,\n  the shipped design-system presets, and how to bridge to shadcn / Tailwind\n  tokens. Never targeting mangled internal class names.\n- **The package boundary** - enterprise symbols (`installEnterprise`,\n  `setAIProvider`, pivot, export) never leak into a grid-only project.\n- **Correct-vs-incorrect pairs** - the reference files show the wrong way\n  and the right way side by side, so the model corrects itself.\n\nCrucially, for anything version-specific the skill tells the model to\n**look it up rather than guess** - fetching the grounding files or calling\nthe MCP tools - so its answers track the version you actually have\ninstalled.\n\n## Install\n\n### Claude Code: the plugin (skill + MCP server in one)\n\nTwo commands, and you get the skill *and* the MCP server that checks the\ncode it produces:\n\n```\n/plugin marketplace add sv-grid/sv-grid\n/plugin install svgrid@svgrid\n```\n\nThe plugin wires up the hosted MCP server at `https://mcp.svgrid.com/mcp`,\nso there is nothing to install and no key to configure. The skill supplies\nthe house style; the server's `svgrid_check_code` tool verifies each file\nagainst the real API surface before you see it. Prefer this over installing\nthe two separately.\n\n### Any other client: the skill on its own\n\nWith the [`skills`](https://www.npmjs.com/package/skills) CLI, pointed at\nthe SvGrid repository:\n\n```bash\nnpx skills add sv-grid/sv-grid\n# or\npnpm dlx skills add sv-grid/sv-grid\n```\n\nThat installs the skill into your project. Alternatively, copy the folder\nstraight into your project's skills directory:\n\n```bash\ncp -r skills/svgrid your-project/.claude/skills/svgrid\n```\n\nThe skill lives at [`skills/svgrid/`](https://github.com/sv-grid/sv-grid/tree/main/skills/svgrid)\nin the repo, so you can also read or fork it directly.\n\n## What's inside\n\n| File | Covers |\n| --- | --- |\n| `SKILL.md` | Entry point: project context, the minimal grid, critical rules, grounding, package boundary, scaffolding |\n| `rules/columns.md` | `ColumnDef`, custom cell snippets, widths, `type`, conditional formatting, editors |\n| `rules/data-and-features.md` | Feature toggles vs. shortcut props, the `SvGridApi`, reactive data, server-side data source |\n| `rules/theming.md` | `--sg-*` tokens, dark mode, design-system presets, the shadcn / Tailwind bridge |\n\n## Skill vs. MCP server vs. grounding files\n\nSvGrid ships three ways to make an assistant write correct code; they\nlayer, they don't compete.\n\n| | Agent Skill | [MCP server](./mcp-server.md) | [Grounding files](./llm-grounding.md) |\n| --- | --- | --- | --- |\n| **What it is** | Always-on rules + house style | Callable tools (docs, demos, schemas) | Static `llms.txt` / `docs.json` / schemas |\n| **How it loads** | Auto, when a `@svgrid/*` project is detected | The model calls a tool | You paste or fetch the file |\n| **Best for** | Following SvGrid conventions by default | Version-pinned lookups mid-task | Custom GPTs, rules files, your own agent |\n| **Setup** | `npx skills add sv-grid/sv-grid` | One line of MCP config | Upload / fetch a URL |\n\nA common setup is the skill **and** the MCP server: the skill keeps the\nmodel on-convention, and the server answers \"what's the exact signature of\n`setFilter` in the version I have?\" when it matters.\n\n## See also\n\n- [MCP server](./mcp-server.md) - callable tools for Claude Desktop / Cursor / Zed / Claude Code\n- [LLM grounding](./llm-grounding.md) - the static files any model can read\n- [AI Toolkit](./ai-toolkit.md) - the full build-time and runtime AI surface\n- [Agents](./agents.md) - build an agent that drives the live grid\n"
     },
     {
         "slug": "help/spreadsheet-formulas",
@@ -5932,8 +5932,8 @@ export const apiReference = {
     ]
 };
 export const apiSurface = {
-    "gridVersion": "2.7.0",
-    "enterpriseVersion": "2.7.0",
+    "gridVersion": "3.0.0",
+    "enterpriseVersion": "3.0.0",
     "grid": {
         "values": [
             "ALL_FILTER_OPERATORS",

package/dist/index.d.ts CHANGED Viewed

@@ -2,11 +2,17 @@
 /**
  * SvGrid MCP server (stdio).
  *
- * Exposes the SvGrid example sources, docs, and curated API reference as
- * Model Context Protocol tools. Point an MCP-capable client (Claude
- * Desktop, Claude Code, etc.) at this server to give the model accurate,
- * version-pinned answers about SvGrid - no hallucinated APIs, no stale
- * blog-post output.
+ * Gives an MCP-capable client accurate, version-pinned answers about SvGrid -
+ * the real exported API, the shipped docs, 375 runnable demos - and, uniquely,
+ * a way to CHECK generated code against that surface before a user ever sees
+ * it.
+ *
+ * The surface is deliberately small. It was 36 tools, which cost ~4,710 tokens
+ * of `tools/list` on every single request; 79% of that was Studio, a commercial
+ * feature most sessions never touch. Five always-on tools cover the whole
+ * question-and-answer path - find, read, check-and-fix, preview, scaffold -
+ * Studio is four more behind an opt-in flag, and the old names all still work - they are just not listed, because listing is what
+ * costs tokens and calling an unlisted name costs nothing.
  *
  * Run with:
  *   npx @svgrid/mcp