@rio-cloud/uikit-mcp 1.0.0

package/docs/search-synonyms.json

@@ -0,0 +1,43 @@
+{
+  "synonyms": {
+    "install": ["installation", "setup", "how to", "howto", "getting started"],
+    "version": ["release"],
+    "button": ["btn", "cta", "buttons"],
+    "dropdown": ["select", "combobox"],
+    "select": ["dropdown", "combobox"],
+    "table": ["datagrid", "grid"],
+    "datagrid": ["table", "grid"],
+    "form": ["input", "field"],
+    "modal": ["dialog"],
+    "dialog": ["modal"],
+    "toast": ["alert", "notification"],
+    "alert": ["toast", "notification"],
+    "datepicker": ["date picker", "calendar"],
+    "date picker": ["datepicker", "calendar"],
+    "accordion": ["expander"],
+    "expander": ["accordion"],
+    "chip": ["tag", "badge"],
+    "tag": ["chip", "badge"]
+  },
+  "preferredDocIds": {
+    "install": ["start/howto"],
+    "getting started": ["start/howto"],
+    "setup": ["start/howto"],
+    "version": ["start/howto"],
+    "button": ["components/button"],
+    "dropdown": ["components/dropdowns"],
+    "select": ["components/dropdowns"],
+    "table": ["components/tables"],
+    "datagrid": ["components/tables"],
+    "modal": ["components/dialogs"],
+    "dialog": ["components/dialogs"],
+    "toast": ["components/notifications"],
+    "alert": ["components/notifications"],
+    "datepicker": ["components/datepickers"],
+    "date picker": ["components/datepickers"],
+    "accordion": ["components/expander"],
+    "expander": ["components/expander"],
+    "chip": ["components/tags"],
+    "tag": ["components/tags"]
+  }
+}

package/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "@rio-cloud/uikit-mcp",
+  "version": "1.0.0",
+  "description": "MCP server that serves the captured RIO UI Kit documentation to Model Context Protocol clients.",
+  "publishConfig": {
+        "access": "public"
+    },
+  "type": "module",
+  "author": "TB Digital Services GmbH",
+  "license": "Apache-2.0",
+  "bin": {
+    "uikit-mcp": "./bin/uikit-mcp.mjs"
+  },
+  "files": [
+    "bin/",
+    "server/",
+    "data/",
+    "docs/",
+    "package.json",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "test": "node --test",
+    "setup:crawler": "npx playwright install chromium",
+    "crawl:full": "node tools/crawl-full.mjs",
+    "crawl:navigation": "node crawler/cli/crawl-navigation.mjs",
+    "capture:all": "node crawler/cli/capture-all.mjs",
+    "mcp:server": "node server/index.mjs",
+    "link:global": "npm link"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.20.2",
+    "flexsearch": "^0.8.212",
+    "playwright": "^1.45.0",
+    "zod": "^3.25.76"
+  }
+}

package/server/index.mjs

@@ -0,0 +1,268 @@
+#!/usr/bin/env node
+
+import { readFileSync } from 'node:fs';
+import path from 'node:path';
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { z } from 'zod';
+
+import { loadDocumentation } from './lib/load-docs.mjs';
+import { renderDocMarkdown } from './lib/render-markdown.mjs';
+import { buildSearchIndex } from './lib/search-index.mjs';
+
+function readCapturedVersion() {
+  try {
+    const versionPath = path.resolve(new URL('../data/version.json', import.meta.url).pathname);
+    return JSON.parse(readFileSync(versionPath, 'utf8'));
+  } catch {
+    return null;
+  }
+}
+
+function loadSearchSynonyms() {
+  try {
+    const synonymsPath = path.resolve(new URL('../docs/search-synonyms.json', import.meta.url).pathname);
+    return JSON.parse(readFileSync(synonymsPath, 'utf8'));
+  } catch (error) {
+    console.warn('Warning: failed to load search synonyms:', error.message);
+    return { synonyms: {}, preferredDocIds: {} };
+  }
+}
+
+const VERSION_INFO = readCapturedVersion();
+const CURRENT_UIKIT_VERSION = VERSION_INFO?.version ?? null;
+const SEARCH_SYNONYMS = loadSearchSynonyms();
+
+const server = new McpServer(
+  {
+    name: 'uikit-mcp-server',
+    version: '0.1.0'
+  },
+  {
+    instructions: `UI Kit MCP usage guidelines:
+- Always discover documentation with search_docs; listResources is a static inventory and must not be used for guessing. Call readResource on the returned uikit-doc:// URI before using anything.
+- Coding rules: import components from '@rio-cloud/rio-uikit', prefer styling via provided classes instead of custom CSS files, and wrap the app/content in ApplicationLayout.
+- Follow documented props tables and examples; avoid inventing undocumented variants.
+- Treat the captured metadata (Category, Section, Captured) as the source of truth. If you need newer upstream info, say so explicitly—live crawling/fetching is not available here.
+- This server serves offline captures only; do not attempt to run Playwright or crawling scripts from this MCP session.
+- Captured UI Kit version: ${CURRENT_UIKIT_VERSION ?? 'unknown'} (from data/version.json). Ask if you require a newer version.`
+  }
+);
+
+function buildResourceUri(docId) {
+  return new URL(`uikit-doc://${docId}`);
+}
+
+function expandDomainSynonyms(rawQuery) {
+  const config = SEARCH_SYNONYMS;
+  const query = rawQuery.toLowerCase();
+  const expansions = new Set();
+  const preferred = new Set();
+  const hints = 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);
+        }
+      });
+      const ids = config.preferredDocIds?.[key] ?? [];
+      ids.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.values()) {
+    const uri = buildResourceUri(doc.id);
+    const versionNote = CURRENT_UIKIT_VERSION
+      ? `\n\n> Captured UI Kit version: ${CURRENT_UIKIT_VERSION}`
+      : '';
+    const markdown = renderDocMarkdown(doc) + versionNote;
+
+    server.registerResource(
+      doc.id,
+      uri.href,
+      {
+        title: doc.title ?? doc.id,
+        description: doc.summary,
+        mimeType: 'text/markdown'
+      },
+      async () => ({
+        contents: [
+          {
+            uri: uri.href,
+            mimeType: 'text/markdown',
+            text: markdown
+          }
+        ]
+      })
+    );
+  }
+
+  console.error(`Registered ${docs.size} documentation resources.`);
+}
+
+function registerSearchTool(docs, index) {
+  const inputSchema = {
+    query: z.string().min(1, 'Query is required'),
+    limit: z.number().int().min(1).max(20).optional()
+  };
+
+  const outputSchema = {
+    results: z.array(
+      z.object({
+        resource: z.string(),
+        title: z.string(),
+        summary: z.string().optional(),
+        category: z.string().nullish(),
+        section: z.string().nullish()
+      })
+    )
+  };
+
+  server.registerTool(
+    'search_docs',
+    {
+      title: 'Search UI Kit docs',
+      description:
+        'Full-text search across the captured UI Kit documentation. Always call this before readResource; it is the only supported way to discover resource IDs.',
+      inputSchema,
+      outputSchema
+    },
+    async ({ query, limit = 5 }) => {
+      const searchQueue = [query];
+      const domainSynonyms = expandDomainSynonyms(query);
+      for (const extra of domainSynonyms.expansions) {
+        searchQueue.push(extra);
+      }
+
+      const seen = new Set();
+      const resolved = [];
+      const preferredDocIds = [];
+      const hints = [];
+
+      preferredDocIds.push(...domainSynonyms.preferredDocIds);
+      hints.push(...domainSynonyms.hints);
+
+      for (const id of preferredDocIds) {
+        if (seen.has(id)) continue;
+        const doc = docs.get(id);
+        if (!doc) continue;
+        seen.add(id);
+        resolved.push({
+          resource: buildResourceUri(id).href,
+          title: doc.title ?? id,
+          summary: doc.summary ?? '',
+          category: doc.category ?? null,
+          section: doc.section ?? null
+        });
+        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 ?? []) {
+            if (seen.has(id)) continue;
+            seen.add(id);
+            const doc = docs.get(id);
+            if (!doc) continue;
+            resolved.push({
+              resource: buildResourceUri(id).href,
+              title: doc.title ?? id,
+              summary: doc.summary ?? '',
+              category: doc.category ?? null,
+              section: doc.section ?? null
+            });
+            if (resolved.length >= limit) break;
+          }
+          if (resolved.length >= limit) break;
+        }
+        if (resolved.length >= limit) break;
+      }
+
+      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(hints.filter(Boolean)));
+      if (uniqueHints.length) {
+        text += `\n\n${uniqueHints.join('\n')}`;
+      }
+
+      if (CURRENT_UIKIT_VERSION) {
+        text += `\n\nCaptured UI Kit version: ${CURRENT_UIKIT_VERSION}. Read "How to use the UIKIT" → "Install the npm package" for installation details.`;
+      }
+
+      return {
+        structuredContent: { results: resolved },
+        content: [
+          {
+            type: 'text',
+            text
+          }
+        ]
+      };
+    }
+  );
+}
+
+async function initialiseServer() {
+  const docs = await loadDocumentation();
+  const index = buildSearchIndex(docs);
+  registerDocResources(docs);
+  registerSearchTool(docs, index);
+
+  const docIds = new Set(docs.keys());
+  const missingPreferred = new Set();
+  for (const ids of Object.values(SEARCH_SYNONYMS.preferredDocIds ?? {})) {
+    for (const id of ids ?? []) {
+      if (!docIds.has(id)) {
+        missingPreferred.add(id);
+      }
+    }
+  }
+  if (missingPreferred.size) {
+    console.warn(
+      `Warning: preferredDocIds not found in dataset: ${Array.from(missingPreferred).join(', ')}`
+    );
+  }
+
+  return { docs, index };
+}
+
+async function main() {
+  await initialiseServer();
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+}
+
+main().catch((error) => {
+  console.error(error);
+  process.exit(1);
+});

package/server/lib/load-docs.mjs

@@ -0,0 +1,48 @@
+import { readFile } from 'node:fs/promises';
+import { readdirSync, statSync } from 'node:fs';
+import path from 'node:path';
+
+import { normaliseDocument } from './normalise-doc.mjs';
+
+const DATA_ROOT = path.resolve(new URL('../../data/pages', import.meta.url).pathname);
+
+/**
+ * Recursively collect JSON file paths.
+ * @param {string} dir
+ * @returns {string[]}
+ */
+function walk(dir) {
+  const entries = readdirSync(dir);
+  const files = [];
+  for (const entry of entries) {
+    const fullPath = path.join(dir, entry);
+    const stats = statSync(fullPath);
+    if (stats.isDirectory()) {
+      files.push(...walk(fullPath));
+    } else if (stats.isFile() && entry.endsWith('.json')) {
+      files.push(fullPath);
+    }
+  }
+  return files;
+}
+
+/**
+ * Load all documentation artefacts and return a map keyed by doc id.
+ * @param {{ root?: string } } [options]
+ * @returns {Promise<Map<string, UiKitDoc>>}
+ */
+export async function loadDocumentation(options = {}) {
+  const root = options.root ? path.resolve(options.root) : DATA_ROOT;
+  const files = walk(root);
+  const docs = new Map();
+
+  for (const file of files) {
+    const rawText = await readFile(file, 'utf8');
+    const rawDoc = JSON.parse(rawText);
+    const normalised = normaliseDocument(rawDoc);
+    docs.set(normalised.id, normalised);
+  }
+
+  return docs;
+}
+

package/server/lib/normalise-doc.mjs

@@ -0,0 +1,220 @@
+import './types.js';
+
+/**
+ * Collapse excessive whitespace and normalise newlines.
+ * @param {string} value
+ * @returns {string}
+ */
+function normaliseWhitespace(value) {
+  return value
+    .replace(/\r\n?/g, '\n')
+    .split('\n')
+    .map((line) => line.trim())
+    .filter((line, index, all) => line.length > 0 || (index > 0 && all[index - 1].length > 0))
+    .join('\n')
+    .trim();
+}
+
+const BLOCK_BREAK_REGEXP = /<\/(p|div|section|article|li|ul|ol|pre|table|thead|tbody|tr|h[1-6])>/gi;
+const BR_REGEXP = /<br\s*\/?>/gi;
+const TAG_REGEXP = /<[^>]+>/g;
+const ENTITY_MAP = new Map([
+  ['&nbsp;', ' '],
+  ['&amp;', '&'],
+  ['&lt;', '<'],
+  ['&gt;', '>'],
+  ['&quot;', '"'],
+  ['&#39;', "'"],
+  ['&apos;', "'"]
+]);
+
+/**
+ * Convert HTML into best-effort plaintext suitable for indexing.
+ * @param {string} html
+ * @returns {string}
+ */
+export function htmlToPlainText(html) {
+  if (!html) return '';
+  let value = html;
+  value = value.replace(BLOCK_BREAK_REGEXP, '\n');
+  value = value.replace(BR_REGEXP, '\n');
+  value = value.replace(TAG_REGEXP, '');
+  for (const [entity, replacement] of ENTITY_MAP.entries()) {
+    value = value.replace(new RegExp(entity, 'g'), replacement);
+  }
+  return normaliseWhitespace(value);
+}
+
+/**
+ * Convert rudimentary markdown-ish copy into plain text.
+ * @param {string} markdown
+ * @returns {string}
+ */
+function markdownToPlainText(markdown) {
+  if (!markdown) return '';
+  return normaliseWhitespace(
+    markdown
+      .replace(/`{1,3}([^`]+)`{1,3}/g, '$1')
+      .replace(/\*\*([^*]+)\*\*/g, '$1')
+      .replace(/\*([^*]+)\*/g, '$1')
+      .replace(/__([^_]+)__|_([^_]+)_/g, (_, bold, italic) => bold ?? italic ?? '')
+      .replace(/> ?/g, '')
+  );
+}
+
+/**
+ * Escape Markdown table cell content.
+ * @param {string} value
+ * @returns {string}
+ */
+function escapeTableCell(value) {
+  return value
+    .replace(/\|/g, '\\|')
+    .replace(/\n+/g, '<br />')
+    .trim();
+}
+
+/**
+ * Turn props table data into Markdown.
+ * @param {RawPropsTable} table
+ * @returns {string}
+ */
+function propsTableToMarkdown(table) {
+  const header = '| Name | Type | Default | Description |';
+  const divider = '| --- | --- | --- | --- |';
+  const rows = table.rows
+    .map((row) => {
+      const name = escapeTableCell(row.name);
+      const type = escapeTableCell(row.type);
+      const defaultValue = escapeTableCell(row.default || '—');
+      const description = escapeTableCell(row.description);
+      return `| ${name} | ${type} | ${defaultValue} | ${description} |`;
+    })
+    .join('\n');
+
+  const heading = table.heading ? `### ${table.heading}\n\n` : '';
+  return `${heading}${header}\n${divider}\n${rows}`.trim();
+}
+
+/**
+ * Derive hash route and identifier from metadata.
+ * @param {RawDoc['metadata']} metadata
+ * @returns {{ route: string, id: string }}
+ */
+function deriveRoute(metadata) {
+  const source = metadata?.source ?? '';
+  const hashIndex = source.indexOf('#');
+  const fallback = metadata?.slug ? `#${metadata.slug}` : '';
+  const route = hashIndex >= 0 ? source.slice(hashIndex) : fallback;
+  const id = route.startsWith('#') ? route.slice(1) : route;
+  return { route, id };
+}
+
+/**
+ * Build a normalised document ready for MCP consumption.
+ * @param {RawDoc} raw
+ * @returns {UiKitDoc}
+ */
+export function normaliseDocument(raw) {
+  if (!raw || typeof raw !== 'object') {
+    throw new TypeError('Expected raw document object');
+  }
+
+  const { route, id } = deriveRoute(raw.metadata ?? {});
+  const title = raw.title ?? null;
+  const sections = [];
+  const textAccumulator = [];
+
+  if (title) textAccumulator.push(title);
+  if (raw.lead) textAccumulator.push(raw.lead);
+
+  for (const section of raw.content ?? []) {
+    const heading = section.heading ?? '';
+    const bodyMarkdown = section.body ? normaliseWhitespace(section.body) : '';
+    const bodyPlainText = markdownToPlainText(bodyMarkdown);
+
+    if (heading) textAccumulator.push(heading);
+    if (bodyPlainText) textAccumulator.push(bodyPlainText);
+
+    const examples = [];
+    for (const example of section.examples ?? []) {
+      const caption = example.caption ?? heading ?? title ?? 'Example';
+      const html = example.rendered_html ?? '';
+      const plainText = htmlToPlainText(html);
+      if (plainText) textAccumulator.push(plainText);
+
+      const codeTabs = [];
+      const propsTables = [];
+
+      for (const tab of example.tabs ?? []) {
+        if (tab.code && tab.code.trim().length) {
+          codeTabs.push({
+            label: tab.label,
+            language: tab.language,
+            code: tab.code.trim()
+          });
+        }
+
+        if (Array.isArray(tab.props) && tab.props.length) {
+          for (const table of tab.props) {
+            const markdown = propsTableToMarkdown(table);
+            propsTables.push({
+              heading: table.heading ?? null,
+              rows: table.rows,
+              markdown
+            });
+            textAccumulator.push(markdownToPlainText(markdown));
+          }
+        }
+      }
+
+      examples.push({
+        caption,
+        html,
+        plainText,
+        codeTabs,
+        propsTables
+      });
+    }
+
+    sections.push({
+      heading,
+      bodyMarkdown,
+      bodyPlainText,
+      examples
+    });
+  }
+
+  const summaryCandidate =
+    raw.lead ||
+    (sections.find((section) => section.bodyPlainText)?.bodyPlainText ?? '') ||
+    (sections.find((section) => section.examples.length)?.examples[0].plainText ?? '');
+
+  const summary = summaryCandidate
+    ? summaryCandidate.split('\n')[0]
+    : `Documentation entry for ${id}`;
+
+  const seeAlso = (raw.see_also ?? []).map((link) => ({
+    label: link.label,
+    href: link.href
+  }));
+
+  const searchText = normaliseWhitespace(textAccumulator.join('\n'));
+
+  return {
+    id,
+    route,
+    category: raw.metadata?.category ?? null,
+    section: raw.metadata?.section ?? null,
+    title,
+    lead: raw.lead ?? null,
+    sections,
+    seeAlso,
+    sourceUrl: raw.metadata?.source ?? '',
+    capturedAt: raw.metadata?.captured_at ?? '',
+    slug: raw.metadata?.slug ?? id,
+    summary,
+    searchText
+  };
+}
+

package/server/lib/render-markdown.mjs

@@ -0,0 +1,82 @@
+import './types.js';
+import { htmlToPlainText } from './normalise-doc.mjs';
+
+function heading(level, text) {
+  const prefix = '#'.repeat(level);
+  return `${prefix} ${text}`.trim();
+}
+
+function codeBlock(language, code) {
+  const fence = '```';
+  return `${fence}${language ?? ''}\n${code}\n${fence}`;
+}
+
+/**
+ * Convert a UiKitDoc to Markdown for MCP resource responses.
+ * @param {UiKitDoc} doc
+ * @returns {string}
+ */
+export function renderDocMarkdown(doc) {
+  const parts = [];
+
+  const title = doc.title ?? doc.id;
+  parts.push(heading(1, title));
+
+  parts.push([
+    `*Category:* ${doc.category ?? '—'}`,
+    `*Section:* ${doc.section ?? '—'}`,
+    `*Source:* ${doc.sourceUrl}`,
+    `*Captured:* ${doc.capturedAt}`
+  ].join('\n'));
+
+  if (doc.lead) {
+    parts.push(doc.lead.trim());
+  }
+
+  for (const section of doc.sections) {
+    if (section.heading) {
+      parts.push(heading(2, section.heading));
+    }
+
+    if (section.bodyMarkdown) {
+      parts.push(section.bodyMarkdown);
+    }
+
+    for (const example of section.examples) {
+      parts.push(heading(3, `Example: ${example.caption}`));
+
+      if (example.plainText) {
+        parts.push(example.plainText);
+      } else if (example.html) {
+        parts.push(htmlToPlainText(example.html));
+      }
+
+      if (example.plainText || example.html) {
+        parts.push(heading(4, 'Summary'));
+        const summary = example.plainText || htmlToPlainText(example.html);
+        parts.push(summary);
+      }
+
+      for (const tab of example.codeTabs) {
+        parts.push(heading(4, `${tab.label} (${tab.language})`));
+        parts.push(codeBlock(tab.language, tab.code));
+      }
+
+      for (const table of example.propsTables) {
+        parts.push(heading(4, table.heading ? `Props: ${table.heading}` : 'Props'));
+        parts.push(table.markdown);
+      }
+    }
+  }
+
+  if (doc.seeAlso.length) {
+    parts.push(heading(2, 'See Also'));
+    const list = doc.seeAlso
+      .map((link) => `- [${link.label}](${link.href})`)
+      .join('\n');
+    parts.push(list);
+  }
+
+  parts.push('\n');
+  return parts.join('\n\n').trim();
+}