@svgrid/mcp 2.6.5 → 2.6.6

package/dist/index.d.ts

@@ -0,0 +1,14 @@
+#!/usr/bin/env node
+/**
+ * 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.
+ *
+ * Run with:
+ *   npx @svgrid/mcp
+ */
+export {};

package/dist/index.js

@@ -15,8 +15,11 @@ import { createRequire } from 'node:module';
 import { Server } from '@modelcontextprotocol/sdk/server/index.js';
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
 import { CallToolRequestSchema, ListToolsRequestSchema, } from '@modelcontextprotocol/sdk/types.js';
-import { apiReference, docs, examples } from './data.js';
+import { apiReference, apiSurface, docs, examples } from './data.js';
 import { projectTools, handleProjectTool } from './project-tools.js';
+import { checkSvGridCode } from './validate.js';
+import { compileWithSvelte } from './compile-svelte.js';
+import { rankDocs } from './search.js';
 import { checkLicenseKey, introspectDrizzle, introspectJson, scaffold, summarizeVerify, verifyScaffold, } from '@svgrid/enterprise/studio';
 /**
  * Soft commercial gate. Uses the SAME classifier as the browser
@@ -65,37 +68,6 @@ function countBy(rows, key) {
     }
     return Object.fromEntries([...counts].sort((a, b) => b[1] - a[1]));
 }
-function occurrences(haystack, needle) {
-    if (!needle)
-        return 0;
-    let n = 0;
-    let i = haystack.indexOf(needle);
-    while (i !== -1) {
-        n += 1;
-        i = haystack.indexOf(needle, i + needle.length);
-    }
-    return n;
-}
-/** Split a query into distinct lowercase terms, dropping one-character noise. */
-function queryTokens(query) {
-    const tokens = [...new Set(query.toLowerCase().split(/[^a-z0-9]+/).filter((t) => t.length > 1))];
-    return tokens.length ? tokens : [query.toLowerCase().trim()];
-}
-/** A window of text around the first needle that appears, for search results. */
-function excerptAround(markdown, needles) {
-    const lower = markdown.toLowerCase();
-    let idx = -1;
-    for (const n of needles) {
-        idx = lower.indexOf(n);
-        if (idx >= 0)
-            break;
-    }
-    if (idx < 0)
-        idx = 0;
-    const start = Math.max(0, idx - 60);
-    const end = Math.min(markdown.length, idx + 180);
-    return markdown.slice(start, end).replace(/\s+/g, ' ').trim();
-}
 // Report the real package version to MCP clients (read from package.json, which
 // ships in the tarball at ../package.json relative to the built dist/index.js),
 // so serverInfo.version never drifts from the published version.
@@ -189,6 +161,21 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
                 description: 'Return the curated SvGrid public-API surface, grouped by category (components, headless, scheduler, data ops, export, row models, features, virtualization, accessibility, utilities).',
                 inputSchema: { type: 'object', properties: {} },
             },
+            {
+                name: 'check_svgrid_code',
+                description: 'Verify SvGrid code BEFORE handing it to the user. Checks the source against the real exported surface of the installed version - <SvGrid> prop names, ColumnDef keys, grid API methods, importable symbols and theme files - plus Svelte 5 runes rules, and compiles it with the Svelte compiler when one is reachable. Returns line-numbered diagnostics with the exact replacement for each. Run this on every .svelte or .ts file you write that uses SvGrid, then fix what it reports and run it again.',
+                inputSchema: {
+                    type: 'object',
+                    properties: {
+                        source: { type: 'string', description: 'The full file contents to check.' },
+                        filename: {
+                            type: 'string',
+                            description: 'File name, used to pick the rules that apply. Defaults to "Component.svelte". Use the real name when you have one (e.g. "src/routes/+page.svelte", "state.svelte.ts").',
+                        },
+                    },
+                    required: ['source'],
+                },
+            },
             {
                 name: 'introspect_source',
                 description: 'SvGrid Studio (commercial): infer an EntitySchema from a data source. Pass a Drizzle schema file (kind:"drizzle", source: the file text) or sample rows (kind:"json", rows, name). Returns a DRAFT EntitySchema to review/refine before scaffolding code.',
@@ -339,75 +326,27 @@ server.setRequestHandler(CallToolRequestSchema, async (req) => {
             if (!query) {
                 return { isError: true, content: [{ type: 'text', text: 'query is required' }] };
             }
-            // Previously this matched the query only as one contiguous substring and
-            // returned hits in directory order, so the canonical page for a topic
-            // routinely lost to an incidental mention. Score per doc, rank, and treat
-            // the query as terms so word order and joining words stop mattering.
-            const phrase = query.toLowerCase();
-            const tokens = queryTokens(query);
-            const scored = [];
-            for (const d of docs) {
-                const title = d.title.toLowerCase();
-                const markdown = d.markdown.toLowerCase();
-                const headings = (d.markdown.match(/^#{1,6}\s+.*$/gm) ?? []).join('\n').toLowerCase();
-                // "help/rows/kanban-board" -> "help rows kanban board". The slug is the
-                // strongest canonical signal there is: a page named after the topic is
-                // the reference page for it, where a recipe merely mentioning it is not.
-                const slugWords = d.slug.toLowerCase().replace(/[/-]/g, ' ');
-                let score = 0;
-                // Whole-phrase hits are the strongest signal, title strongest of all.
-                if (title.includes(phrase))
-                    score += 100;
-                if (slugWords.includes(phrase))
-                    score += 60;
-                if (headings.includes(phrase))
-                    score += 30;
-                if (markdown.includes(phrase))
-                    score += 20;
-                let matched = 0;
-                for (const t of tokens) {
-                    const inTitle = title.includes(t);
-                    const inHeading = headings.includes(t);
-                    const count = occurrences(markdown, t);
-                    if (inTitle || inHeading || count > 0)
-                        matched += 1;
-                    if (inTitle)
-                        score += 25;
-                    if (slugWords.includes(t))
-                        score += 10;
-                    if (inHeading)
-                        score += 8;
-                    // Capped so a long page cannot outrank a precise one on bulk alone.
-                    score += Math.min(count, 5);
-                }
-                if (score > 0)
-                    scored.push({ d, score, complete: matched === tokens.length });
-            }
-            // Prefer pages containing every term; fall back to partial matches only
-            // when nothing covers the whole query.
-            const complete = scored.filter((s) => s.complete);
-            const ranked = (complete.length ? complete : scored)
-                .sort((a, b) => b.score - a.score || a.d.slug.localeCompare(b.d.slug))
-                .slice(0, limit);
-            const hits = ranked.map((s) => ({
-                slug: s.d.slug,
-                title: s.d.title,
-                section: s.d.section,
-                score: s.score,
-                excerpt: excerptAround(s.d.markdown, [phrase, ...tokens]),
-            }));
-            const matchedTotal = complete.length || scored.length;
-            return withDocs(JSON.stringify({
-                query,
-                total: matchedTotal,
-                shown: hits.length,
-                partial: complete.length === 0 && scored.length > 0 ? true : undefined,
-                hits,
-            }, null, 2));
+            // Ranking lives in ./search.ts so the remote server answers the same
+            // query the same way.
+            const { hits, total, partial } = rankDocs(docs, query, limit);
+            return withDocs(JSON.stringify({ query, total, shown: hits.length, partial: partial || undefined, hits }, null, 2));
         }
         case 'get_api_reference': {
             return withDocs(JSON.stringify(apiReference, null, 2));
         }
+        case 'check_svgrid_code': {
+            const a = (args ?? {});
+            if (typeof a.source !== 'string' || !a.source.trim()) {
+                return errText('source (the file contents to check) is required');
+            }
+            const result = await checkSvGridCode(a.source, apiSurface, {
+                filename: a.filename,
+                compile: compileWithSvelte,
+            });
+            // No docs footer: this output is a work list, and a marketing line at the
+            // end of it is noise the model has to read past on every iteration.
+            return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
+        }
         case 'introspect_source': {
             const a = (args ?? {});
             try {

package/dist/project-tools.d.ts

@@ -0,0 +1,16 @@
+type ToolResult = {
+    content: Array<{
+        type: 'text';
+        text: string;
+    }>;
+    isError?: boolean;
+};
+export type ProjectTool = {
+    name: string;
+    description: string;
+    inputSchema: Record<string, unknown>;
+};
+export declare const projectTools: ProjectTool[];
+/** Handle a studio_* project tool. Returns undefined if `name` isn't one of ours. */
+export declare function handleProjectTool(name: string, args: Record<string, unknown>): ToolResult | undefined;
+export {};

package/dist/search.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Doc ranking, shared by the stdio server and the remote Worker so both answer
+ * the same query the same way.
+ *
+ * Pure and dependency-free: it takes the docs it should rank rather than
+ * importing them, because the Worker loads its corpus from static assets at
+ * request time while the stdio server has it bundled.
+ */
+export type RankableDoc = {
+    slug: string;
+    title: string;
+    section: string;
+    markdown: string;
+};
+export type DocHit = {
+    slug: string;
+    title: string;
+    section: string;
+    score: number;
+    excerpt: string;
+};
+export declare function occurrences(haystack: string, needle: string): number;
+/** Split a query into distinct lowercase terms, dropping one-character noise. */
+export declare function queryTokens(query: string): string[];
+/** A window of text around the first needle that appears, for search results. */
+export declare function excerptAround(markdown: string, needles: string[]): string;
+/**
+ * Rank docs for a query. Whole-phrase hits outrank term hits, and the slug is
+ * weighted heavily: a page named after the topic is the reference page for it,
+ * where a recipe that merely mentions it is not. Pages matching every term win
+ * outright; partial matches are only returned when nothing covers the query.
+ */
+export declare function rankDocs<T extends RankableDoc>(docs: readonly T[], query: string, limit: number): {
+    hits: DocHit[];
+    total: number;
+    partial: boolean;
+};

package/dist/search.js

@@ -0,0 +1,99 @@
+/**
+ * Doc ranking, shared by the stdio server and the remote Worker so both answer
+ * the same query the same way.
+ *
+ * Pure and dependency-free: it takes the docs it should rank rather than
+ * importing them, because the Worker loads its corpus from static assets at
+ * request time while the stdio server has it bundled.
+ */
+export function occurrences(haystack, needle) {
+    if (!needle)
+        return 0;
+    let n = 0;
+    let i = haystack.indexOf(needle);
+    while (i !== -1) {
+        n += 1;
+        i = haystack.indexOf(needle, i + needle.length);
+    }
+    return n;
+}
+/** Split a query into distinct lowercase terms, dropping one-character noise. */
+export function queryTokens(query) {
+    const tokens = [...new Set(query.toLowerCase().split(/[^a-z0-9]+/).filter((t) => t.length > 1))];
+    return tokens.length ? tokens : [query.toLowerCase().trim()];
+}
+/** A window of text around the first needle that appears, for search results. */
+export function excerptAround(markdown, needles) {
+    const lower = markdown.toLowerCase();
+    let idx = -1;
+    for (const n of needles) {
+        idx = lower.indexOf(n);
+        if (idx >= 0)
+            break;
+    }
+    if (idx < 0)
+        idx = 0;
+    const start = Math.max(0, idx - 60);
+    const end = Math.min(markdown.length, idx + 180);
+    return markdown.slice(start, end).replace(/\s+/g, ' ').trim();
+}
+/**
+ * Rank docs for a query. Whole-phrase hits outrank term hits, and the slug is
+ * weighted heavily: a page named after the topic is the reference page for it,
+ * where a recipe that merely mentions it is not. Pages matching every term win
+ * outright; partial matches are only returned when nothing covers the query.
+ */
+export function rankDocs(docs, query, limit) {
+    const phrase = query.toLowerCase();
+    const tokens = queryTokens(query);
+    const scored = [];
+    for (const d of docs) {
+        const title = d.title.toLowerCase();
+        const markdown = d.markdown.toLowerCase();
+        const headings = (d.markdown.match(/^#{1,6}\s+.*$/gm) ?? []).join('\n').toLowerCase();
+        const slugWords = d.slug.toLowerCase().replace(/[/-]/g, ' ');
+        let score = 0;
+        if (title.includes(phrase))
+            score += 100;
+        if (slugWords.includes(phrase))
+            score += 60;
+        if (headings.includes(phrase))
+            score += 30;
+        if (markdown.includes(phrase))
+            score += 20;
+        let matched = 0;
+        for (const t of tokens) {
+            const inTitle = title.includes(t);
+            const inHeading = headings.includes(t);
+            const count = occurrences(markdown, t);
+            if (inTitle || inHeading || count > 0)
+                matched += 1;
+            if (inTitle)
+                score += 25;
+            if (slugWords.includes(t))
+                score += 10;
+            if (inHeading)
+                score += 8;
+            // Capped so a long page cannot outrank a precise one on bulk alone.
+            score += Math.min(count, 5);
+        }
+        if (score > 0)
+            scored.push({ d, score, complete: matched === tokens.length });
+    }
+    const complete = scored.filter((s) => s.complete);
+    const pool = complete.length ? complete : scored;
+    const ranked = pool
+        .sort((a, b) => b.score - a.score || a.d.slug.localeCompare(b.d.slug))
+        .slice(0, limit);
+    return {
+        hits: ranked.map((s) => ({
+            slug: s.d.slug,
+            title: s.d.title,
+            section: s.d.section,
+            score: s.score,
+            excerpt: excerptAround(s.d.markdown, [phrase, ...tokens]),
+        })),
+        total: pool.length,
+        partial: complete.length === 0 && scored.length > 0,
+    };
+}

package/dist/validate.d.ts

@@ -0,0 +1,101 @@
+/**
+ * check_svgrid_code - the verification half of the MCP server.
+ *
+ * Retrieval tools (docs, demos, API listing) only ever give a model something
+ * to read. This one closes the loop: the model writes SvGrid code, this checks
+ * it against the REAL exported surface of the installed version and hands back
+ * diagnostics it can act on. A wrong prop name, a symbol imported from the
+ * wrong package, or Svelte 4 syntax in a Svelte 5 component all come back with
+ * the exact replacement rather than "hmm, that didn't work" three edits later.
+ *
+ * Two layers:
+ *   1. Static analysis (this file) - pure, no dependencies, no filesystem, so
+ *      it runs identically in the Node stdio server and in a Worker.
+ *   2. The Svelte compiler - injected by the caller when it is available
+ *      (`compile` option). Node has it; the Worker does not, and skips.
+ *
+ * The API surface is generated from the workspace sources at build time by
+ * scripts/api-surface.mjs, so it cannot drift from what the package exports.
+ */
+export type Severity = 'error' | 'warning' | 'info';
+export type Diagnostic = {
+    /** Stable rule id, e.g. "svgrid/unknown-prop". */
+    rule: string;
+    severity: Severity;
+    /** 1-based line in the checked source. */
+    line: number;
+    message: string;
+    /** The concrete edit that fixes it, when there is one. */
+    fix?: string;
+    /** Doc slug or demo id to read for the full story. */
+    see?: string;
+};
+export type TypeMember = {
+    readonly name: string;
+    readonly optional: boolean;
+    readonly type: string;
+};
+export type ApiSurface = {
+    readonly gridVersion: string;
+    readonly enterpriseVersion: string;
+    readonly grid: {
+        readonly values: readonly string[];
+        readonly types: readonly string[];
+        readonly subpaths: readonly string[];
+    };
+    readonly enterprise: {
+        readonly values: readonly string[];
+        readonly types: readonly string[];
+        readonly subpaths: readonly string[];
+    };
+    readonly props: readonly TypeMember[];
+    readonly columnDef: readonly TypeMember[];
+    /** Methods on the free `SvGridApi`. */
+    readonly apiMethods: readonly string[];
+    /** Methods `installEnterprise(api)` adds on top. */
+    readonly enterpriseApiMethods: readonly string[];
+    readonly themes: readonly string[];
+    readonly features: readonly string[];
+    readonly rowModels: readonly string[];
+};
+export type CheckResult = {
+    ok: boolean;
+    /** Which version the code was checked against. */
+    checkedAgainst: string;
+    compiler: 'svelte' | 'unavailable' | 'not-svelte';
+    counts: {
+        errors: number;
+        warnings: number;
+        info: number;
+    };
+    diagnostics: Diagnostic[];
+    summary: string;
+};
+/** A compile pass supplied by the host when a Svelte compiler is reachable. */
+export type CompileFn = (source: string, filename: string) => Promise<{
+    available: boolean;
+    diagnostics: Diagnostic[];
+}>;
+/**
+ * Blank out comments and the inside of strings, keeping every offset and line
+ * break intact. All structural scanning runs on this copy so a prop name in a
+ * doc comment or a `<SvGrid>` inside a template string never trips a rule.
+ */
+export declare function blankOut(src: string): string;
+/**
+ * Closest known name to `word`, or null when nothing is near enough. A
+ * case-only difference always wins; otherwise the edit distance has to be
+ * small relative to the word so "foo" does not "resolve" to "bar".
+ */
+export declare function nearest(word: string, candidates: readonly string[]): string | null;
+/** Run every static rule. Exported for tests and for hosts that skip compiling. */
+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
+ * optional second gate: when the host can reach a Svelte compiler, real parse
+ * errors are merged in with the static findings.
+ */
+export declare function checkSvGridCode(source: string, surface: ApiSurface, opts?: {
+    filename?: string;
+    compile?: CompileFn;
+}): Promise<CheckResult>;