@rio-cloud/uikit-mcp 1.1.10 → 1.1.12

package/dist/index.mjs

@@ -5,7 +5,7 @@ import { z } from "zod";
 import { existsSync, readFileSync } from "node:fs";
 import path from "node:path";
 import FlexSearch from "flexsearch";
-//#region server/lib/doc-id.ts
+//#region shared/content/doc-id.ts
 var InvalidDocIdError = class extends Error {
 	constructor(id, reason) {
 		super(`Invalid doc id "${id}": ${reason}`);
@@ -132,7 +132,7 @@ function buildSearchIndex(entries) {
 	});
 	for (const entry of entries) index.add({
 		id: entry.id,
-		title: entry.title,
+		title: entry.indexTitle ?? entry.title,
 		lead: entry.lead ?? "",
 		summary: entry.summary,
 		searchText: entry.searchText,
@@ -149,14 +149,163 @@ function buildSearchIndex(entries) {
 	return { search };
 }
 //#endregion
+//#region server/lib/search-docs.ts
+function normaliseKey(value) {
+	return value.toLowerCase().trim();
+}
+function slugifyHeading(value) {
+	return normaliseKey(value).replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "");
+}
+function compactText(value) {
+	return value.replace(/\s+/g, " ").trim();
+}
+function stripMarkdownForSearch(markdown) {
+	return compactText(markdown.replace(/```[\s\S]*?```/g, " ").replace(/^#{1,6}\s+/gm, "").replace(/`([^`]+)`/g, "$1").replace(/\*\*([^*]+)\*\*/g, "$1").replace(/\*([^*]+)\*/g, "$1").replace(/__([^_]+)__|_([^_]+)_/g, (_, bold, italic) => bold ?? italic ?? "").replace(/<[^>]+>/g, " ").replace(/[[\]()*_>#|]/g, " "));
+}
+function excerpt(value, maxLength = 240) {
+	const text = compactText(value);
+	if (text.length <= maxLength) return text;
+	return `${text.slice(0, maxLength - 1).trimEnd()}…`;
+}
+function extractSecondLevelMarkdownSections(markdown) {
+	const sections = [];
+	const lines = markdown.split(/\r?\n/);
+	let current = null;
+	for (const line of lines) {
+		const match = /^##\s+(.+?)\s*$/.exec(line);
+		if (match) {
+			if (current) sections.push({
+				heading: current.heading,
+				body: current.bodyLines.join("\n").trim()
+			});
+			current = {
+				heading: match[1].trim(),
+				bodyLines: []
+			};
+			continue;
+		}
+		if (current) current.bodyLines.push(line);
+	}
+	if (current) sections.push({
+		heading: current.heading,
+		body: current.bodyLines.join("\n").trim()
+	});
+	return sections;
+}
+function expandDomainSynonyms(rawQuery, config) {
+	const query = normaliseKey(rawQuery);
+	const expansions = /* @__PURE__ */ new Set();
+	const preferred = /* @__PURE__ */ new Set();
+	const hints = /* @__PURE__ */ new Set();
+	const synonyms = config.synonyms ?? {};
+	const preferredDocIds = config.preferredDocIds ?? {};
+	const allKeys = new Set([
+		...Object.keys(synonyms),
+		...Object.keys(preferredDocIds),
+		...Object.keys(config.hints ?? {})
+	]);
+	for (const key of allKeys) {
+		if (!query.includes(normaliseKey(key))) continue;
+		for (const value of synonyms[key] ?? []) if (normaliseKey(value) !== query) expansions.add(value);
+		for (const id of preferredDocIds[key] ?? []) preferred.add(id);
+		if (config.hints?.[key]) hints.add(config.hints[key]);
+	}
+	return {
+		expansions: Array.from(expansions),
+		preferredDocIds: Array.from(preferred),
+		hints: Array.from(hints)
+	};
+}
+function buildFoundationSectionAliases(foundation, markdown) {
+	if (!foundation || !markdown) return [];
+	return extractSecondLevelMarkdownSections(markdown).map((section) => {
+		const slug = slugifyHeading(section.heading);
+		if (!slug) return null;
+		const plainText = stripMarkdownForSearch(section.body);
+		const guidance = `Matched section: "${section.heading}". After reading this resource, use the "## ${section.heading}" section; ignore unrelated Foundations sections unless they are needed for context.`;
+		const summary = plainText ? `${guidance} Section excerpt: ${excerpt(plainText)}` : guidance;
+		return {
+			id: `foundations#${slug}`,
+			resourceDocId: foundation.id,
+			title: `Foundations: ${section.heading}`,
+			indexTitle: section.heading,
+			lead: null,
+			summary,
+			searchText: [section.heading, plainText].filter(Boolean).join("\n"),
+			category: foundation.category,
+			section: foundation.section,
+			boost: [
+				section.heading,
+				`foundations ${section.heading}`,
+				`#foundations/${slug}`
+			].join(" "),
+			matchedHeading: section.heading
+		};
+	}).filter((entry) => Boolean(entry));
+}
+function buildSearchEntries(metadata, options = {}) {
+	const foundation = metadata.find((entry) => entry.id === "foundations");
+	return [...metadata, ...buildFoundationSectionAliases(foundation, options.foundationMarkdown ?? null)];
+}
+function resolveSearchDocs(options) {
+	const { query, limit, index, entriesById, synonymsConfig, resourceForDocId } = options;
+	const searchQueue = [query];
+	const domainSynonyms = expandDomainSynonyms(query, synonymsConfig);
+	for (const extra of domainSynonyms.expansions) searchQueue.push(extra);
+	const seen = /* @__PURE__ */ new Set();
+	const results = [];
+	const normalizedQuery = normaliseKey(query);
+	function addResult(id) {
+		if (seen.has(id)) return results.length >= limit;
+		const entry = entriesById.get(id);
+		if (!entry) return false;
+		seen.add(id);
+		const resourceDocId = entry.resourceDocId ?? entry.id;
+		results.push({
+			resource: resourceForDocId(resourceDocId),
+			title: entry.title,
+			summary: entry.summary,
+			category: entry.category,
+			section: entry.section,
+			matchedHeading: entry.matchedHeading
+		});
+		return results.length >= limit;
+	}
+	if (/\bfoundations?\b/.test(normalizedQuery)) for (const entry of entriesById.values()) {
+		if (!entry.matchedHeading) continue;
+		if (!normalizedQuery.includes(normaliseKey(entry.matchedHeading))) continue;
+		if (addResult(entry.id)) return {
+			results,
+			domainSynonyms
+		};
+	}
+	for (const id of domainSynonyms.preferredDocIds) if (addResult(id)) return {
+		results,
+		domainSynonyms
+	};
+	for (const searchQuery of searchQueue) {
+		const hits = index.search(searchQuery, {
+			limit: Math.max(limit * 2, 10),
+			suggest: true
+		});
+		for (const group of hits) for (const id of group.result ?? []) if (addResult(String(id))) return {
+			results,
+			domainSynonyms
+		};
+	}
+	return {
+		results,
+		domainSynonyms
+	};
+}
+//#endregion
 //#region package.json
-var version = "1.1.10";
+var version = "1.1.11";
 //#endregion
 //#region server/index.ts
 const DIST_ROOT = import.meta.dirname;
 const { metadata, synonyms, version: capturedVersionInfo } = loadCompiledData(DIST_ROOT);
 const CAPTURED_UIKIT_VERSION = capturedVersionInfo?.version ?? null;
-const metadataById = new Map(metadata.map((m) => [m.id, m]));
 const server = new McpServer({
 	name: "uikit-mcp-server",
 	version
@@ -169,24 +318,6 @@ const server = new McpServer({
 function buildResourceUri(docId) {
 	return new URL(`uikit-doc://${docId}`);
 }
-function expandDomainSynonyms(rawQuery, config) {
-	const query = rawQuery.toLowerCase();
-	const expansions = /* @__PURE__ */ new Set();
-	const preferred = /* @__PURE__ */ new Set();
-	const hints = /* @__PURE__ */ new Set();
-	for (const [key, values] of Object.entries(config.synonyms ?? {})) if (query.includes(key.toLowerCase())) {
-		(values ?? []).forEach((value) => {
-			if (value.toLowerCase() !== query) expansions.add(value);
-		});
-		(config.preferredDocIds?.[key] ?? []).forEach((id) => preferred.add(id));
-		if (config.hints?.[key]) hints.add(config.hints[key]);
-	}
-	return {
-		expansions: Array.from(expansions),
-		preferredDocIds: Array.from(preferred),
-		hints: Array.from(hints)
-	};
-}
 function registerDocResources(docs) {
 	for (const doc of docs) {
 		const safeId = assertSafeDocId(doc.id);
@@ -207,7 +338,7 @@ function registerDocResources(docs) {
 	}
 	console.error(`Registered ${docs.length} documentation resources.`);
 }
-function registerSearchTool(index, metadataMap, synonymsConfig) {
+function registerSearchTool(index, entriesMap, synonymsConfig) {
 	const inputSchema = {
 		query: z.string().min(1, "Query is required"),
 		limit: z.number().int().min(1).max(20).optional()
@@ -217,7 +348,8 @@ function registerSearchTool(index, metadataMap, synonymsConfig) {
 		title: z.string(),
 		summary: z.string().optional(),
 		category: z.string().nullish(),
-		section: z.string().nullish()
+		section: z.string().nullish(),
+		matchedHeading: z.string().optional()
 	})) };
 	server.registerTool("search_docs", {
 		title: "Search UI Kit docs",
@@ -231,50 +363,14 @@ function registerSearchTool(index, metadataMap, synonymsConfig) {
 			openWorldHint: false
 		}
 	}, async ({ query, limit = 5 }) => {
-		const searchQueue = [query];
-		const domainSynonyms = expandDomainSynonyms(query, synonymsConfig);
-		for (const extra of domainSynonyms.expansions) searchQueue.push(extra);
-		const seen = /* @__PURE__ */ new Set();
-		const resolved = [];
-		for (const id of domainSynonyms.preferredDocIds) {
-			if (seen.has(id)) continue;
-			const doc = metadataMap.get(id);
-			if (!doc) continue;
-			seen.add(id);
-			resolved.push({
-				resource: buildResourceUri(id).href,
-				title: doc.title,
-				summary: doc.summary,
-				category: doc.category,
-				section: doc.section
-			});
-			if (resolved.length >= limit) break;
-		}
-		for (const searchQuery of searchQueue) {
-			const hits = index.search(searchQuery, {
-				limit: Math.max(limit * 2, 10),
-				suggest: true
-			});
-			for (const group of hits) {
-				for (const id of group.result ?? []) {
-					const docId = String(id);
-					if (seen.has(docId)) continue;
-					seen.add(docId);
-					const doc = metadataMap.get(docId);
-					if (!doc) continue;
-					resolved.push({
-						resource: buildResourceUri(docId).href,
-						title: doc.title,
-						summary: doc.summary,
-						category: doc.category,
-						section: doc.section
-					});
-					if (resolved.length >= limit) break;
-				}
-				if (resolved.length >= limit) break;
-			}
-			if (resolved.length >= limit) break;
-		}
+		const { results: resolved, domainSynonyms } = resolveSearchDocs({
+			query,
+			limit,
+			index,
+			entriesById: entriesMap,
+			synonymsConfig,
+			resourceForDocId: (docId) => buildResourceUri(docId).href
+		});
 		let text = resolved.length > 0 ? resolved.map((entry, idx) => `${idx + 1}. ${entry.title} (${entry.resource})${entry.summary ? `\n   ${entry.summary}` : ""}`).join("\n\n").concat("\n\nAlways call readResource on one of the URIs above instead of guessing component routes.") : `No matches for "${query}".`;
 		const uniqueHints = Array.from(new Set(domainSynonyms.hints.filter(Boolean)));
 		if (uniqueHints.length) text += `\n\n${uniqueHints.join("\n")}`;
@@ -289,9 +385,17 @@ function registerSearchTool(index, metadataMap, synonymsConfig) {
 	});
 }
 async function main() {
-	const index = buildSearchIndex(metadata);
+	let foundationMarkdown = null;
+	try {
+		foundationMarkdown = loadMarkdown(DIST_ROOT, "foundations");
+	} catch {
+		foundationMarkdown = null;
+	}
+	const searchEntries = buildSearchEntries(metadata, { foundationMarkdown });
+	const searchEntriesById = new Map(searchEntries.map((entry) => [entry.id, entry]));
+	const index = buildSearchIndex(searchEntries);
 	registerDocResources(metadata);
-	registerSearchTool(index, metadataById, synonyms);
+	registerSearchTool(index, searchEntriesById, synonyms);
 	const docIds = new Set(metadata.map((m) => m.id));
 	const missingPreferred = /* @__PURE__ */ new Set();
 	for (const ids of Object.values(synonyms.preferredDocIds ?? {})) for (const id of ids ?? []) if (!docIds.has(id)) missingPreferred.add(id);

package/dist/search-synonyms.json

@@ -1,134 +1,272 @@
 {
   "synonyms": {
-    "install": [
-      "installation",
-      "setup",
-      "how to",
-      "howto",
-      "getting started"
+    "accordion": [
+      "expander"
     ],
-    "version": [
-      "release"
+    "alert": [
+      "notification",
+      "toast"
     ],
     "button": [
       "btn",
-      "cta",
-      "buttons"
+      "buttons",
+      "cta"
+    ],
+    "chip": [
+      "tag",
+      "badge"
+    ],
+    "csv export": [
+      "download",
+      "export",
+      "table export"
+    ],
+    "datagrid": [
+      "grid",
+      "table"
+    ],
+    "date picker": [
+      "calendar",
+      "datepicker"
+    ],
+    "datepicker": [
+      "calendar",
+      "date picker"
+    ],
+    "download": [
+      "export",
+      "csv export",
+      "table export"
     ],
     "dropdown": [
-      "select",
-      "combobox"
+      "combobox",
+      "select"
     ],
-    "select": [
-      "dropdown",
-      "combobox"
+    "expander": [
+      "accordion"
     ],
-    "table": [
-      "datagrid",
-      "grid"
+    "export": [
+      "download",
+      "csv export",
+      "table export"
     ],
-    "datagrid": [
-      "table",
-      "grid"
+    "file picker": [
+      "file upload",
+      "filepicker",
+      "upload"
+    ],
+    "file upload": [
+      "file picker",
+      "filepicker",
+      "upload"
+    ],
+    "filepicker": [
+      "file picker",
+      "file upload",
+      "upload"
     ],
     "form": [
-      "input",
-      "field"
+      "field",
+      "input"
+    ],
+    "getting started": [
+      "how to use",
+      "install",
+      "installation",
+      "setup"
+    ],
+    "how to use": [
+      "getting started",
+      "install",
+      "installation",
+      "setup"
+    ],
+    "install": [
+      "getting started",
+      "how to",
+      "howto",
+      "installation",
+      "setup"
+    ],
+    "installation": [
+      "getting started",
+      "how to use",
+      "install",
+      "setup"
+    ],
+    "license plate": [
+      "licenseplate",
+      "number plate"
+    ],
+    "licenseplate": [
+      "license plate",
+      "number plate"
     ],
     "modal": [
       "dialog"
     ],
-    "dialog": [
-      "modal"
+    "notification": [
+      "alert",
+      "toast"
+    ],
+    "number plate": [
+      "license plate",
+      "licenseplate"
+    ],
+    "pager": [
+      "pages",
+      "pagination",
+      "paging"
+    ],
+    "pagination": [
+      "pager",
+      "pages",
+      "paging"
+    ],
+    "select": [
+      "combobox",
+      "dropdown"
+    ],
+    "setup": [
+      "getting started",
+      "install",
+      "installation"
+    ],
+    "table": [
+      "datagrid",
+      "grid"
+    ],
+    "table export": [
+      "csv export",
+      "download",
+      "export"
+    ],
+    "tag": [
+      "badge",
+      "chip"
     ],
     "toast": [
       "alert",
       "notification"
     ],
+    "upload": [
+      "file picker",
+      "file upload",
+      "filepicker"
+    ],
+    "version": [
+      "release"
+    ]
+  },
+  "preferredDocIds": {
+    "accordion": [
+      "components/expander"
+    ],
     "alert": [
-      "toast",
-      "notification"
+      "components/notifications"
     ],
-    "datepicker": [
-      "date picker",
-      "calendar"
+    "button": [
+      "components/button"
+    ],
+    "chip": [
+      "components/tags"
+    ],
+    "csv export": [
+      "utilities/useTableExport"
+    ],
+    "datagrid": [
+      "components/table"
     ],
     "date picker": [
-      "datepicker",
-      "calendar"
+      "components/datepickers"
     ],
-    "accordion": [
-      "expander"
+    "datepicker": [
+      "components/datepickers"
+    ],
+    "dialog": [
+      "components/dialogs"
+    ],
+    "download": [
+      "utilities/useTableExport"
+    ],
+    "dropdown": [
+      "components/dropdowns"
     ],
     "expander": [
-      "accordion"
+      "components/expander"
     ],
-    "chip": [
-      "tag",
-      "badge"
+    "export": [
+      "utilities/useTableExport"
     ],
-    "tag": [
-      "chip",
-      "badge"
-    ]
-  },
-  "preferredDocIds": {
-    "install": [
-      "start/howto"
+    "file picker": [
+      "components/filePickers"
+    ],
+    "file upload": [
+      "components/filePickers"
+    ],
+    "filepicker": [
+      "components/filePickers"
     ],
     "getting started": [
       "start/howto"
     ],
-    "setup": [
+    "how to use": [
       "start/howto"
     ],
-    "version": [
+    "install": [
       "start/howto"
     ],
-    "button": [
-      "components/button"
-    ],
-    "dropdown": [
-      "components/dropdowns"
-    ],
-    "select": [
-      "components/dropdowns"
+    "installation": [
+      "start/howto"
     ],
-    "table": [
-      "components/table"
+    "license plate": [
+      "components/licensePlate"
     ],
-    "datagrid": [
-      "components/table"
+    "licenseplate": [
+      "components/licensePlate"
     ],
     "modal": [
       "components/dialogs"
     ],
-    "dialog": [
-      "components/dialogs"
-    ],
-    "toast": [
+    "notification": [
       "components/notifications"
     ],
-    "alert": [
-      "components/notifications"
+    "number plate": [
+      "components/licensePlate"
     ],
-    "datepicker": [
-      "components/datepickers"
+    "pager": [
+      "components/pager"
     ],
-    "date picker": [
-      "components/datepickers"
+    "pagination": [
+      "components/pager"
     ],
-    "accordion": [
-      "components/expander"
+    "paging": [
+      "components/pager"
     ],
-    "expander": [
-      "components/expander"
+    "select": [
+      "components/dropdowns",
+      "components/selects"
     ],
-    "chip": [
-      "components/tags"
+    "setup": [
+      "start/howto"
+    ],
+    "table": [
+      "components/table"
+    ],
+    "table export": [
+      "utilities/useTableExport"
     ],
     "tag": [
       "components/tags"
+    ],
+    "toast": [
+      "components/notifications"
+    ],
+    "upload": [
+      "components/filePickers"
+    ],
+    "version": [
+      "start/howto"
     ]
   }
 }

package/dist/version.json

@@ -1,4 +1,4 @@
 {
-  "version": "2.3.0",
-  "captured_at": "2026-04-20T12:56:07.829Z"
+  "version": "2.4.1",
+  "captured_at": "2026-05-06T12:15:47.080Z"
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rio-cloud/uikit-mcp",
-  "version": "1.1.10",
+  "version": "1.1.12",
   "description": "MCP server that serves the captured RIO UI Kit documentation to Model Context Protocol clients.",
   "publishConfig": {
     "access": "public"
@@ -26,23 +26,25 @@
     "crawl:full": "tsx tools/crawl-full.ts",
     "crawl:navigation": "tsx crawler/cli/crawl-navigation.ts",
     "capture:all": "tsx crawler/cli/capture-all.ts",
-    "mcp:demo-client": "npm run build:server && tsx tools/demo-client.ts",
     "mcp:server": "npm run build:server && node dist/index.mjs"
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "1.29.0",
     "flexsearch": "0.8.212",
-    "zod": "4.3.6"
+    "zod": "4.4.1"
   },
   "overrides": {
     "@hono/node-server": "1.19.13",
-    "hono": "4.12.12"
+    "hono": "4.12.14",
+    "express-rate-limit": {
+      "ip-address": "10.1.1"
+    }
   },
   "devDependencies": {
     "@types/node": "24.12.2",
     "playwright": "1.59.1",
-    "tsdown": "0.21.8",
+    "tsdown": "0.21.10",
     "tsx": "4.21.0",
-    "typescript": "6.0.2"
+    "typescript": "6.0.3"
   }
 }