@svgrid/mcp 2.6.7 → 3.0.0

package/dist/studio-tools.d.ts

@@ -0,0 +1,13 @@
+import { type ProjectTool } from './project-tools.js';
+type ToolResult = {
+    content: Array<{
+        type: 'text';
+        text: string;
+    }>;
+    isError?: boolean;
+};
+/** Studio is opt-in: an explicit flag, or a licence key that implies intent. */
+export declare function studioEnabled(): boolean;
+export declare const STUDIO_TOOLS: ProjectTool[];
+export declare function handleStudioTool(name: string, args: Record<string, unknown>): ToolResult | undefined;
+export {};

package/dist/studio-tools.js

@@ -0,0 +1,227 @@
+/**
+ * The Studio surface, as four tools instead of twenty-seven.
+ *
+ * The old surface was one tool per model mutation - `studio_add_block`,
+ * `studio_update_block`, `studio_remove_block`, `studio_move_block`, and ten
+ * separate `studio_set_*` tools. That is the API-wrapping antipattern: it made
+ * building a five-screen app twenty-odd round trips, and it cost ~3,741 tokens
+ * of `tools/list` on EVERY request, to every user, including the ones who only
+ * wanted to ask a question about the free grid. Studio was 79% of the payload
+ * and most sessions never called it once.
+ *
+ * These four delegate into the same `handleProjectTool` switch, so none of the
+ * behaviour is reimplemented here - only the shape a model sees. `studio_apply`
+ * takes a BATCH, which is the real win: a whole screen in one call rather than
+ * six.
+ *
+ * Off unless asked for. Set `SVGRID_MCP_STUDIO=1`, or a valid
+ * `SVGRID_LICENSE_KEY` - the tools that need a licence to be useful should not
+ * be charged to everyone else's context window.
+ */
+import { checkLicenseKey } from '@svgrid/enterprise/studio';
+import { handleProjectTool } from './project-tools.js';
+/** Studio is opt-in: an explicit flag, or a licence key that implies intent. */
+export function studioEnabled() {
+    if (process.env.SVGRID_MCP_STUDIO === '1')
+        return true;
+    return checkLicenseKey(process.env.SVGRID_LICENSE_KEY ?? null).valid;
+}
+const PROJECT_ACTIONS = {
+    new: 'studio_new_project',
+    load: 'studio_load_project',
+    describe: 'studio_describe_project',
+    config: 'studio_get_config',
+    capabilities: 'studio_capabilities',
+};
+const APPLY_OPS = {
+    add_entity: 'studio_add_entity',
+    add_screen: 'studio_add_screen',
+    add_block: 'studio_add_block',
+    add_component: 'studio_add_component',
+    update_block: 'studio_update_block',
+    remove_block: 'studio_remove_block',
+    move_block: 'studio_move_block',
+    update_screen: 'studio_update_screen',
+    remove_screen: 'studio_remove_screen',
+};
+const SETTINGS = {
+    theme: 'studio_set_theme',
+    access: 'studio_set_access',
+    auth: 'studio_set_auth',
+    data_layer: 'studio_set_data_layer',
+    tenancy: 'studio_set_tenancy',
+    job: 'studio_set_job',
+    deploy_target: 'studio_set_deploy_target',
+    screen_layout: 'studio_set_screen_layout',
+    form_layout: 'studio_set_form_layout',
+    field_conditions: 'studio_set_field_conditions',
+    entity_source: 'studio_set_entity_source',
+};
+const BUILD_ACTIONS = {
+    validate: 'studio_validate',
+    generate: 'studio_generate_app',
+};
+const keys = (map) => Object.keys(map).join(' | ');
+export const STUDIO_TOOLS = [
+    {
+        name: 'studio_project',
+        description: 'SvGrid Studio (commercial): open or inspect the project model. `new` starts an empty one, `load` parses a studio.config.json string, `describe` summarises the current project (entities, screens, blocks, ids), `config` returns it as studio.config.json, `capabilities` lists the block kinds, UI components, themes and data sources you can use. Call `capabilities` before `studio_apply` so you use real names.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                action: { type: 'string', enum: Object.keys(PROJECT_ACTIONS), description: keys(PROJECT_ACTIONS) },
+                title: { type: 'string', description: 'For action "new": the project title.' },
+                config: { type: 'string', description: 'For action "load": a studio.config.json string.' },
+            },
+            required: ['action'],
+        },
+    },
+    {
+        name: 'studio_apply',
+        description: 'SvGrid Studio (commercial): change the project model. Takes a BATCH of operations applied in order, so a whole screen is one call rather than six. Each op is { op, ...args } where op is one of: ' +
+            keys(APPLY_OPS) +
+            '. The args are the same ones the individual operations took (entity, screen, kind, blockId, config, ...). Stops at the first failure and reports which op failed and what already applied. Get ids from studio_project action:"describe".',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                ops: {
+                    type: 'array',
+                    description: 'Operations to apply in order.',
+                    items: {
+                        type: 'object',
+                        properties: {
+                            op: { type: 'string', enum: Object.keys(APPLY_OPS), description: 'Which operation.' },
+                        },
+                        required: ['op'],
+                        additionalProperties: true,
+                    },
+                },
+            },
+            required: ['ops'],
+        },
+    },
+    {
+        name: 'studio_configure',
+        description: 'SvGrid Studio (commercial): set project-wide options. Pass any combination of: ' +
+            keys(SETTINGS) +
+            '. Each value is the argument object the individual setting took, e.g. { "theme": { "preset": "ember" }, "auth": { "enabled": true } }. Applied in one call so a full app configuration is one round trip.',
+        inputSchema: {
+            type: 'object',
+            properties: Object.fromEntries(Object.keys(SETTINGS).map((k) => [
+                k,
+                { type: 'object', description: `Arguments for ${SETTINGS[k]}.`, additionalProperties: true },
+            ])),
+            required: [],
+        },
+    },
+    {
+        name: 'studio_build',
+        description: 'SvGrid Studio (commercial): `validate` reports codegen errors and warnings for the current project; `generate` emits the full runnable SvelteKit app - every route, $lib module, package.json and config. Validate first: generate on an invalid project wastes a large response.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                action: { type: 'string', enum: Object.keys(BUILD_ACTIONS), description: keys(BUILD_ACTIONS) },
+            },
+            required: ['action'],
+        },
+    },
+];
+const fail = (message) => ({ isError: true, content: [{ type: 'text', text: message }] });
+/**
+ * Catch the shape mistakes that would otherwise surface three calls later.
+ *
+ * An `EntitySchema` field is `{ field, type }`. Passing `{ name, type }` is the
+ * obvious guess and it is accepted silently: the entity stores, the screen
+ * builds, and nothing complains until `studio_build generate` fails with
+ * "no primary key ... or name a field \`id\`" - on a schema that HAS a field
+ * called id. That message is about the `field` property, but it reads as the
+ * `name` one, and following its advice reproduces the error exactly. It cost
+ * three round trips to diagnose by hand; a model would burn the same and then
+ * guess.
+ *
+ * So it is caught here, at the call that got it wrong, naming the fix.
+ */
+function checkOpShape(op, entry) {
+    if (op !== 'add_entity')
+        return null;
+    const schema = entry.schema;
+    if (!schema || !Array.isArray(schema.fields))
+        return null;
+    const misnamed = schema.fields.filter((f) => f && typeof f === 'object' && !('field' in f) && 'name' in f);
+    if (!misnamed.length)
+        return null;
+    const names = misnamed
+        .map((f) => f.name)
+        .filter((n) => typeof n === 'string')
+        .join(', ');
+    return (`EntitySchema fields use \`field\`, not \`name\` - rewrite { "name": "id" } as ` +
+        `{ "field": "id" } (affected: ${names}). Left as-is this stores fine and then ` +
+        `fails at generate time with a message about the primary key.`);
+}
+const isError = (r) => !r || r.isError;
+const textOf = (r) => (r?.content ?? []).map((c) => c.text).join('\n');
+export function handleStudioTool(name, args) {
+    if (name === 'studio_project') {
+        const action = String(args.action ?? '');
+        const target = PROJECT_ACTIONS[action];
+        if (!target)
+            return fail(`Unknown action "${action}". Use one of: ${keys(PROJECT_ACTIONS)}.`);
+        return handleProjectTool(target, args);
+    }
+    if (name === 'studio_apply') {
+        const ops = args.ops;
+        if (!Array.isArray(ops) || ops.length === 0) {
+            return fail(`ops must be a non-empty array of { op, ... }. Valid ops: ${keys(APPLY_OPS)}.`);
+        }
+        const applied = [];
+        for (const [i, raw] of ops.entries()) {
+            const entry = (raw ?? {});
+            const op = String(entry.op ?? '');
+            const target = APPLY_OPS[op];
+            if (!target) {
+                return fail(`ops[${i}]: unknown op "${op}". Valid ops: ${keys(APPLY_OPS)}.` +
+                    (applied.length ? `\nAlready applied: ${applied.join(', ')}.` : ''));
+            }
+            const shapeError = checkOpShape(op, entry);
+            if (shapeError) {
+                return fail(`ops[${i}] (${op}): ${shapeError}` +
+                    (applied.length ? `\nAlready applied: ${applied.join(', ')}.` : '\nNothing was applied.'));
+            }
+            const result = handleProjectTool(target, entry);
+            if (isError(result)) {
+                // Say what landed before the failure - the model has to know whether to
+                // retry the whole batch or only the tail.
+                return fail(`ops[${i}] (${op}) failed: ${textOf(result)}` +
+                    (applied.length ? `\nAlready applied: ${applied.join(', ')}.` : '\nNothing was applied.'));
+            }
+            applied.push(`${i}:${op}`);
+        }
+        const describe = handleProjectTool('studio_describe_project', {});
+        return { content: [{ type: 'text', text: `Applied ${applied.length} op(s).\n\n${textOf(describe)}` }] };
+    }
+    if (name === 'studio_configure') {
+        const entries = Object.keys(SETTINGS).filter((k) => args[k] !== undefined);
+        if (!entries.length) {
+            return fail(`Pass at least one of: ${keys(SETTINGS)}.`);
+        }
+        const done = [];
+        for (const key of entries) {
+            const value = (args[key] ?? {});
+            const result = handleProjectTool(SETTINGS[key], value);
+            if (isError(result)) {
+                return fail(`${key} failed: ${textOf(result)}` +
+                    (done.length ? `\nAlready set: ${done.join(', ')}.` : '\nNothing was set.'));
+            }
+            done.push(key);
+        }
+        return { content: [{ type: 'text', text: `Set ${done.join(', ')}.` }] };
+    }
+    if (name === 'studio_build') {
+        const action = String(args.action ?? '');
+        const target = BUILD_ACTIONS[action];
+        if (!target)
+            return fail(`Unknown action "${action}". Use one of: ${keys(BUILD_ACTIONS)}.`);
+        return handleProjectTool(target, args);
+    }
+    return undefined;
+}

package/dist/validate.d.ts

@@ -27,6 +27,20 @@ export type Diagnostic = {
     message: string;
     /** The concrete edit that fixes it, when there is one. */
     fix?: string;
+    /**
+     * A mechanically applicable identifier rename, when the correction is exact.
+     *
+     * Machine-readable ON PURPOSE. `fix` is prose written for a human or a model
+     * to read; parsing it back out to edit code would make the wording
+     * load-bearing, and someone would eventually reword it and silently break
+     * every rewrite. Set only where the replacement is certain - a known rename
+     * or a close-enough spelling guess - and never where the advice is "this has
+     * no equivalent, remove it".
+     */
+    rename?: {
+        from: string;
+        to: string;
+    };
     /** Doc slug or demo id to read for the full story. */
     see?: string;
 };
@@ -89,6 +103,32 @@ export declare function blankOut(src: string): string;
  */
 export declare function nearest(word: string, candidates: readonly string[]): string | null;
 /** Run every static rule. Exported for tests and for hosts that skip compiling. */
+/**
+ * Apply the mechanically-safe renames to the source, returning the corrected
+ * text and a description of every edit.
+ *
+ * Reporting a mistake and leaving the caller to re-derive the edit from prose
+ * is the loop this tool exists to shorten. But the tool's entire worth is that
+ * it never cries wolf, and rewriting raises those stakes: a false positive no
+ * longer wastes a turn, it corrupts working code. So the rules here are narrow
+ * on purpose.
+ *
+ * - Only diagnostics carrying a `rename`, which is set only where the
+ *   replacement is exact.
+ * - Word-boundary matches only, so `data` never rewrites `rowData`.
+ * - Scoped to the reported LINE. `Diagnostic` has no column, and a whole-file
+ *   replace would hit identifiers the checker never looked at - a local
+ *   variable that happens to share a name with a wrong prop, say.
+ * - Skipped when the line does not contain the identifier, which means the
+ *   source has moved on since the check.
+ *
+ * `applied` is the audit trail; a caller that wants to review before trusting
+ * has everything it needs.
+ */
+export declare function applyFixes(source: string, diagnostics: readonly Diagnostic[]): {
+    fixed: string;
+    applied: string[];
+};
 export declare function checkStatic(source: string, surface: ApiSurface, filename?: string): Diagnostic[];
 /**
  * Check a snippet and report what a model should do next. `compile` is the

package/dist/validate.js

@@ -348,7 +348,10 @@ function checkImports(ctx) {
                     severity: 'error',
                     line,
                     message: `${pkgName}@${isGrid ? surface.gridVersion : surface.enterpriseVersion} does not export \`${name}\`.`,
-                    fix: guess ? `Did you mean \`${guess}\`?` : 'Call get_api_reference for the exported surface.',
+                    fix: guess
+                        ? `Did you mean \`${guess}\`?`
+                        : 'Call svgrid_get with ref:"api" for the exported surface.',
+                    rename: guess ? { from: name, to: guess } : undefined,
                 });
             }
         }
@@ -470,7 +473,7 @@ function checkGridProps(ctx) {
                     message: `\`on:${evt}\` never fires: SvGrid dispatches no component events, it takes callback props.`,
                     fix: real
                         ? `Use \`${real}={...}\`.`
-                        : `Look for the matching \`on...\` prop - call get_api_reference or read reference/SvGrid.`,
+                        : `Look for the matching \`on...\` prop - call svgrid_get with ref:"api" or read reference/SvGrid.`,
                     see: 'reference/SvGrid',
                 });
                 continue;
@@ -497,6 +500,9 @@ function checkGridProps(ctx) {
                     line: attr.line,
                     message: `\`${name}\` is not a SvGrid prop.`,
                     fix: renamed ? `Use \`${renamed}\`.` : PROP_RENAME_NOTES[name],
+                    // An empty target means "there is no equivalent, take it out" - a
+                    // deletion, not a rename, so it is never applied automatically.
+                    rename: renamed ? { from: name, to: renamed } : undefined,
                     see: 'reference/SvGrid',
                 });
                 continue;
@@ -518,7 +524,10 @@ function checkGridProps(ctx) {
                 severity: 'error',
                 line: attr.line,
                 message: `\`${name}\` is not a prop of <SvGrid> in @svgrid/grid@${surface.gridVersion}.`,
-                fix: guess ? `Did you mean \`${guess}\`?` : 'Call get_api_reference, or read the reference/SvGrid doc for the prop list.',
+                fix: guess
+                    ? `Did you mean \`${guess}\`?`
+                    : 'Call svgrid_search with the prop name, or read the reference/SvGrid doc for the prop list.',
+                rename: guess ? { from: name, to: guess } : undefined,
                 see: 'reference/SvGrid',
             });
         }
@@ -652,6 +661,7 @@ function checkColumns(ctx) {
                         line,
                         message: `\`${key}\` is not a SvGrid column key.`,
                         fix: renamed ? `Use \`${renamed}\`.` : COLUMN_RENAME_NOTES[key],
+                        rename: renamed ? { from: key, to: renamed } : undefined,
                         see: 'help/columns/column-definitions',
                     });
                     continue;
@@ -874,13 +884,18 @@ function checkEnterpriseUsage(ctx) {
                 continue;
             }
             const hint = API_METHOD_HINTS[method];
-            const guess = hint ?? nearest(method, all);
+            const spelling = nearest(method, all);
+            const guess = hint ?? spelling;
             push(ctx, {
                 rule: 'svgrid/unknown-api-method',
                 severity: 'error',
                 line,
                 message: `The grid API has no \`${method}()\` in @svgrid/grid@${ctx.surface.gridVersion}.`,
-                fix: guess ? `Use \`${guess}\`.` : 'Call get_api_reference for the api surface.',
+                fix: guess ? `Use \`${guess}\`.` : 'Call svgrid_get with ref:"api" for the api surface.',
+                // Only the spelling guess is a bare identifier. An API_METHOD_HINTS
+                // value is a call expression - `exportData({ format: "xlsx" })` - and
+                // substituting that for an identifier would emit `api.exportData({...})(...)`.
+                rename: !hint && spelling ? { from: method, to: spelling } : undefined,
                 see: 'reference/SvGrid',
             });
         }
@@ -941,6 +956,56 @@ function checkFeatures(ctx) {
 // Entry point
 // ---------------------------------------------------------------------------
 /** Run every static rule. Exported for tests and for hosts that skip compiling. */
+/**
+ * Apply the mechanically-safe renames to the source, returning the corrected
+ * text and a description of every edit.
+ *
+ * Reporting a mistake and leaving the caller to re-derive the edit from prose
+ * is the loop this tool exists to shorten. But the tool's entire worth is that
+ * it never cries wolf, and rewriting raises those stakes: a false positive no
+ * longer wastes a turn, it corrupts working code. So the rules here are narrow
+ * on purpose.
+ *
+ * - Only diagnostics carrying a `rename`, which is set only where the
+ *   replacement is exact.
+ * - Word-boundary matches only, so `data` never rewrites `rowData`.
+ * - Scoped to the reported LINE. `Diagnostic` has no column, and a whole-file
+ *   replace would hit identifiers the checker never looked at - a local
+ *   variable that happens to share a name with a wrong prop, say.
+ * - Skipped when the line does not contain the identifier, which means the
+ *   source has moved on since the check.
+ *
+ * `applied` is the audit trail; a caller that wants to review before trusting
+ * has everything it needs.
+ */
+export function applyFixes(source, diagnostics) {
+    const lines = source.split('\n');
+    const applied = [];
+    for (const d of diagnostics) {
+        if (!d.rename)
+            continue;
+        const { from, to } = d.rename;
+        if (!from || !to || from === to)
+            continue;
+        const i = d.line - 1;
+        const line = lines[i];
+        if (line === undefined)
+            continue;
+        // Word boundaries via an explicit character class rather than \b, which
+        // treats `$` and `-` as boundaries and would match inside `$derived` or a
+        // hyphenated attribute.
+        const pattern = new RegExp(`(^|[^A-Za-z0-9_$])${escapeRegExp(from)}(?![A-Za-z0-9_$])`, 'g');
+        if (!pattern.test(line))
+            continue;
+        pattern.lastIndex = 0;
+        lines[i] = line.replace(pattern, (_m, before) => `${before}${to}`);
+        applied.push(`${from} -> ${to} (line ${d.line})`);
+    }
+    return { fixed: lines.join('\n'), applied };
+}
+function escapeRegExp(value) {
+    return value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
 export function checkStatic(source, surface, filename = 'Component.svelte') {
     const ctx = {
         raw: source,

package/package.json

@@ -5,7 +5,7 @@
     "type": "commercial",
     "url": "https://svgrid.com/pricing"
   },
-  "version": "2.6.7",
+  "version": "3.0.0",
   "description": "Model Context Protocol server for SvGrid, the Svelte 5 data grid: checks the code your AI writes against the real API surface, plus version-pinned docs, API reference and 373 demo sources.",
   "license": "MIT",
   "author": "jQWidgets <sales@jqwidgets.com>",
@@ -33,7 +33,7 @@
     "@modelcontextprotocol/sdk": "^1.0.4",
     "svelte": "^5.55.5",
     "zod": "^3.23.8",
-    "@svgrid/enterprise": "^2.6.4"
+    "@svgrid/enterprise": "^2.7.0"
   },
   "devDependencies": {
     "@types/node": "^22.10.7",

package/server.json

@@ -3,7 +3,7 @@
   "name": "com.svgrid/svgrid",
   "title": "SvGrid",
   "description": "Checks AI-written SvGrid code against the real API, plus version-pinned Svelte 5 grid docs.",
-  "version": "2.6.7",
+  "version": "3.0.0",
   "websiteUrl": "https://svgrid.com/docs/help/mcp-server/",
   "repository": {
     "url": "https://github.com/sv-grid/sv-grid",
@@ -15,7 +15,7 @@
       "registryType": "npm",
       "registryBaseUrl": "https://registry.npmjs.org",
       "identifier": "@svgrid/mcp",
-      "version": "2.6.7",
+      "version": "3.0.0",
       "runtimeHint": "npx",
       "transport": {
         "type": "stdio"