@svgrid/mcp 2.6.3 → 2.6.5

package/dist/index.js

@@ -43,6 +43,59 @@ 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]));
+}
+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.
@@ -67,8 +120,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 +147,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 +174,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: {
@@ -160,9 +239,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 +290,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,21 +339,71 @@ server.setRequestHandler(CallToolRequestSchema, async (req) => {
             if (!query) {
                 return { isError: true, content: [{ type: 'text', text: 'query is required' }] };
             }
-            const q = query.toLowerCase();
-            const hits = [];
+            // 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 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;
+                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 });
             }
-            return withDocs(JSON.stringify({ query, total: hits.length, hits }, null, 2));
+            // 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));
         }
         case 'get_api_reference': {
             return withDocs(JSON.stringify(apiReference, null, 2));

package/package.json

@@ -5,7 +5,7 @@
     "type": "commercial",
     "url": "https://svgrid.com/pricing"
   },
-  "version": "2.6.3",
+  "version": "2.6.5",
   "description": "Model Context Protocol (MCP) server for SvGrid. Exposes example sources, docs, and API reference to AI assistants.",
   "license": "MIT",
   "author": "jQWidgets <sales@jqwidgets.com>",

package/server.json

@@ -3,7 +3,7 @@
   "name": "com.svgrid/svgrid",
   "title": "SvGrid",
   "description": "Version-pinned Svelte 5 data grid APIs, 373 demo sources, and SvelteKit app scaffolding.",
-  "version": "2.6.1",
+  "version": "2.6.5",
   "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.1",
+      "version": "2.6.5",
       "runtimeHint": "npx",
       "transport": {
         "type": "stdio"