@svgrid/mcp 2.6.4 → 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
@@ -43,6 +46,28 @@ const DOCS_FOOTER = '\n\nSvGrid reference: full docs & 370+ live demos at https:
 function withDocs(text) {
     return { content: [{ type: 'text', text: text + DOCS_FOOTER }] };
 }
+/**
+ * Shorten a blurb for a listing. Demo blurbs run to ~240 chars and 373 of them
+ * is most of a context window, so the listings carry a one-line version and
+ * get_example_source still returns the full text.
+ */
+function trimBlurb(text, max = 120) {
+    const s = String(text ?? '').replace(/\s+/g, ' ').trim();
+    if (s.length <= max)
+        return s;
+    const cut = s.slice(0, max);
+    const space = cut.lastIndexOf(' ');
+    return (space > 40 ? cut.slice(0, space) : cut) + '...';
+}
+/** { value: count } over a key, ordered by descending count. */
+function countBy(rows, key) {
+    const counts = new Map();
+    for (const row of rows) {
+        const k = key(row) || 'Other';
+        counts.set(k, (counts.get(k) ?? 0) + 1);
+    }
+    return Object.fromEntries([...counts].sort((a, b) => b[1] - a[1]));
+}
 // 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.
@@ -67,8 +92,21 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
         tools: [
             {
                 name: 'list_examples',
-                description: 'List every SvGrid example demo with id, title, and short blurb. Use to discover what is available before fetching source.',
-                inputSchema: { type: 'object', properties: {} },
+                description: 'Find SvGrid example demos. Returns id, title, category and a one-line blurb (not source). Call with no arguments for a category index plus the first page; filter with `query` and/or `category` to find a specific demo, then call get_example_source with its id.',
+                inputSchema: {
+                    type: 'object',
+                    properties: {
+                        query: {
+                            type: 'string',
+                            description: 'Free-text filter over id, title, blurb and category, e.g. "kanban" or "server side".',
+                        },
+                        category: {
+                            type: 'string',
+                            description: 'Exact category, e.g. "Kanban" or "Inputs". Call with no arguments to see the available categories.',
+                        },
+                        limit: { type: 'number', description: 'Max results, default 25, max 100.', default: 25 },
+                    },
+                },
             },
             {
                 name: 'get_example_source',
@@ -81,8 +119,21 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
             },
             {
                 name: 'list_docs',
-                description: 'List every documentation page with slug and title. Slugs use forward slashes, e.g. "help/columns/column-definitions".',
-                inputSchema: { type: 'object', properties: {} },
+                description: 'Find SvGrid documentation pages. Returns slug, title and section. Call with no arguments for a section index plus the first page; filter with `query` and/or `section`, then call get_doc with a slug. Slugs use forward slashes, e.g. "help/columns/column-definitions". To search page CONTENT rather than titles, use search_docs.',
+                inputSchema: {
+                    type: 'object',
+                    properties: {
+                        query: {
+                            type: 'string',
+                            description: 'Free-text filter over slug, title and section, e.g. "column" or "export".',
+                        },
+                        section: {
+                            type: 'string',
+                            description: 'Exact section, e.g. "Columns" or "Server data". Call with no arguments to see the available sections.',
+                        },
+                        limit: { type: 'number', description: 'Max results, default 30, max 100.', default: 30 },
+                    },
+                },
             },
             {
                 name: 'get_doc',
@@ -95,7 +146,7 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
             },
             {
                 name: 'search_docs',
-                description: 'Case-insensitive substring search across all SvGrid docs. Returns matching slugs with a one-line excerpt around the first hit.',
+                description: 'Ranked full-text search across all SvGrid docs. Matches the query term by term (so "row virtualization" finds a page phrasing it either way) and returns the best pages first, each with a relevance score and an excerpt around the hit. Use this to find grounding before writing SvGrid code.',
                 inputSchema: {
                     type: 'object',
                     properties: {
@@ -110,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.',
@@ -160,9 +226,41 @@ server.setRequestHandler(CallToolRequestSchema, async (req) => {
     if (projectResult)
         return projectResult;
     switch (name) {
+        // Returning all 373 demos cost ~31k tokens on the call this tool's own
+        // description invites a model to start with. Filtered and capped instead,
+        // and a bare call answers with the category index to drill into.
         case 'list_examples': {
-            const items = examples.map((e) => ({ id: e.id, title: e.title, blurb: e.blurb, path: e.path }));
-            return withDocs(JSON.stringify(items, null, 2));
+            const a = (args ?? {});
+            const limit = Math.max(1, Math.min(100, Number(a.limit ?? 25)));
+            const q = String(a.query ?? '').trim().toLowerCase();
+            const category = String(a.category ?? '').trim().toLowerCase();
+            const pool = examples.filter((e) => {
+                if (category && e.category.toLowerCase() !== category)
+                    return false;
+                if (q && !`${e.id} ${e.title} ${e.blurb} ${e.category}`.toLowerCase().includes(q))
+                    return false;
+                return true;
+            });
+            const shown = pool.slice(0, limit);
+            const body = {
+                total: pool.length,
+                shown: shown.length,
+                examples: shown.map((e) => ({
+                    id: e.id,
+                    title: e.title,
+                    category: e.category,
+                    blurb: trimBlurb(e.blurb),
+                })),
+            };
+            if (!q && !category)
+                body.categories = countBy(examples, (e) => e.category);
+            if (shown.length < pool.length) {
+                body.hint = `Showing ${shown.length} of ${pool.length}. Narrow with \`query\` or \`category\`, or raise \`limit\` (max 100).`;
+            }
+            if (!pool.length) {
+                body.hint = 'No match. Drop `category`, or try a broader `query`.';
+            }
+            return withDocs(JSON.stringify(body, null, 2));
         }
         case 'get_example_source': {
             const id = String(args?.id ?? '');
@@ -179,9 +277,36 @@ server.setRequestHandler(CallToolRequestSchema, async (req) => {
                 ],
             };
         }
+        // Same shape as list_examples, for the same reason: all 370 pages was
+        // ~12.7k tokens. `path` is dropped from the listing because it is always
+        // "docs/<slug>.md" and get_doc takes the slug.
         case 'list_docs': {
-            const items = docs.map((d) => ({ slug: d.slug, title: d.title, path: d.path }));
-            return withDocs(JSON.stringify(items, null, 2));
+            const a = (args ?? {});
+            const limit = Math.max(1, Math.min(100, Number(a.limit ?? 30)));
+            const q = String(a.query ?? '').trim().toLowerCase();
+            const section = String(a.section ?? '').trim().toLowerCase();
+            const pool = docs.filter((d) => {
+                if (section && d.section.toLowerCase() !== section)
+                    return false;
+                if (q && !`${d.slug} ${d.title} ${d.section}`.toLowerCase().includes(q))
+                    return false;
+                return true;
+            });
+            const shown = pool.slice(0, limit);
+            const body = {
+                total: pool.length,
+                shown: shown.length,
+                docs: shown.map((d) => ({ slug: d.slug, title: d.title, section: d.section })),
+            };
+            if (!q && !section)
+                body.sections = countBy(docs, (d) => d.section);
+            if (shown.length < pool.length) {
+                body.hint = `Showing ${shown.length} of ${pool.length}. Narrow with \`query\` or \`section\`, raise \`limit\` (max 100), or use search_docs to search page content.`;
+            }
+            if (!pool.length) {
+                body.hint = 'No match. Drop `section`, or try search_docs to search page content instead of titles.';
+            }
+            return withDocs(JSON.stringify(body, null, 2));
         }
         case 'get_doc': {
             const slug = String(args?.slug ?? '');
@@ -201,25 +326,27 @@ server.setRequestHandler(CallToolRequestSchema, async (req) => {
             if (!query) {
                 return { isError: true, content: [{ type: 'text', text: 'query is required' }] };
             }
-            const q = query.toLowerCase();
-            const hits = [];
-            for (const d of docs) {
-                const lower = d.markdown.toLowerCase();
-                const idx = lower.indexOf(q);
-                if (idx >= 0) {
-                    const start = Math.max(0, idx - 60);
-                    const end = Math.min(d.markdown.length, idx + q.length + 120);
-                    const excerpt = d.markdown.slice(start, end).replace(/\s+/g, ' ').trim();
-                    hits.push({ slug: d.slug, title: d.title, excerpt });
-                    if (hits.length >= limit)
-                        break;
-                }
-            }
-            return withDocs(JSON.stringify({ query, total: hits.length, 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>;