varmory 1.0.4 → 1.0.5

package/mcp/showcaseMcp.js

@@ -1,16 +1,191 @@
+// ════════════════════════════════════════════════════════════════════════════
+//  varmory MCP — exposes showcase metadata, docs, and component APIs to AI
+//  agents over the Model Context Protocol.
+//
+//  HIGH-LEVEL FLOW
+//  ───────────────
+//  1. `attachShowcase(server, { rootDir, files })` is called once at boot.
+//  2. We assemble a flat list of input file paths:
+//       • when `rootDir` is given, scan the varmory layout and collect the
+//         files we care about (README, docs/*.md, showcase categories,
+//         hand-written definitions, and Quasar's component src JSONs)
+//       • merge with any `files` the caller passed in explicitly
+//  3. `loadFromFiles(paths)` routes each path by extension into three
+//     in-memory caches:
+//       • categories   — .vue files grouped by their parent folder
+//       • docs         — .md files (README.md + docs/*.md)
+//       • definitions  — .json files (component API definitions)
+//  4. Every definition is piped through `normalizeQuasarApi` to resolve
+//     `extends`, merge contributions from `mixins`, tag inherited entries, and
+//     sort (required → own → inherited). Definitions without mixins/extends
+//     pass through unchanged, so hand-written JSONs stay as-is.
+//  5. MCP resources (listing endpoints) and tools (search / fetch endpoints)
+//     are registered on the server, reading from the caches.
+//
+//  FILESYSTEM LAYOUT EXPECTED AT rootDir
+//  ─────────────────────────────────────
+//    README.md
+//    docs/*.md
+//    **/categories/<NN Name>/*.vue      (anywhere under rootDir, recursive
+//                                        scan that skips node_modules / .git
+//                                        / dist / build)
+//    **/definitions/<Vendor>/*.json     (same — any folder named
+//                                        `definitions` with vendor subfolders
+//                                        of JSON files)
+//    node_modules/quasar/src/…                          (optional; when
+//                                                        present, Quasar
+//                                                        components become
+//                                                        queryable via
+//                                                        get_api)
+//
+//  Merge order matters: caller-supplied `files` are appended AFTER root-scanned
+//  files, so they override anything with the same definition/doc name.
+// ════════════════════════════════════════════════════════════════════════════
+
 import fs from 'fs';
 import path from 'path';
 import { z } from 'zod';
 import { ResourceTemplate } from '@modelcontextprotocol/sdk/server/mcp.js';
+import normalizeQuasarApi from '../src/varmory/includes/normalizeQuasarApi.js';
+
+// ── Filesystem helpers ──────────────────────────────────────────────────────
+
+/**
+ * Recursively list all files beneath `dir` whose filename passes `predicate`.
+ * Returns absolute paths. Safe if `dir` doesn't exist. `skip` is a set of
+ * directory names to skip (e.g. `node_modules`).
+ */
+function walkFiles(dir, predicate, skip = new Set()) {
+    const out = [];
+    if (!fs.existsSync(dir)) return out;
+    for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+        const full = path.join(dir, entry.name);
+        if (entry.isDirectory()) {
+            if (skip.has(entry.name)) continue;
+            out.push(...walkFiles(full, predicate, skip));
+        } else if (entry.isFile() && predicate(entry.name)) out.push(full);
+    }
+    return out;
+}
+
+/**
+ * Recursively locate all directories with a given name under `dir`, skipping
+ * the entries in `skip` and giving up after `maxDepth` levels. Returns
+ * absolute paths in sorted order.
+ *
+ * Depth 0 is `dir` itself. A `maxDepth` of 5 means we look at `dir` and 5
+ * layers below it — deep enough for monorepo layouts but shallow enough to
+ * not wander into surprise directories.
+ */
+function findDirsByName(dir, name, skip = new Set(), maxDepth = 5, depth = 0) {
+    const out = [];
+    if (!fs.existsSync(dir) || depth > maxDepth) return out;
+    for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+        if (!entry.isDirectory()) continue;
+        if (skip.has(entry.name)) continue;
+        const full = path.join(dir, entry.name);
+        if (entry.name === name) out.push(full);
+        out.push(...findDirsByName(full, name, skip, maxDepth, depth + 1));
+    }
+    return out.sort();
+}
+
+/**
+ * Collect all files we care about from a varmory root directory, returned as a
+ * flat array of absolute paths. The caller feeds this into `loadFromFiles`.
+ *
+ * Files are emitted in a deterministic order so the resulting categories
+ * and definitions lists are stable across runs:
+ *   README.md
+ *   docs/*.md                                   (alphabetical)
+ *   showcase/categories/<NN Name>/*.vue         (folders by name, files a→z)
+ *   showcase/definitions/<Vendor>/*.json        (folders a→z, files a→z)
+ *   node_modules/quasar/src/components (recursive) Q*.json  (Quasar's own API,
+ *                                                            unless `quasar: false`)
+ *
+ * @param {string} rootDir
+ * @param {object} [opts]
+ * @param {boolean} [opts.quasar=true]  - When false, skip Quasar's component JSONs.
+ * @param {number}  [opts.maxDepth=5]   - How deep to search for `categories/`
+ *        and `definitions/` folders. Depth 0 is `rootDir` itself.
+ */
+function collectFilesFromRoot(rootDir, { quasar = true, maxDepth = 5 } = {}) {
+    const files = [];
+
+    // Skip these folder names when walking rootDir — they're expensive and
+    // never contain user-authored showcase/definition folders.
+    const skip = new Set(['node_modules', '.git', 'dist', 'build']);
+
+    // README.md at the root
+    const readme = path.join(rootDir, 'README.md');
+    if (fs.existsSync(readme)) files.push(readme);
+
+    // Markdown docs
+    const docsDir = path.join(rootDir, 'docs');
+    if (fs.existsSync(docsDir)) {
+        const mdFiles = fs.readdirSync(docsDir).filter(n => n.endsWith('.md')).sort();
+        for (const name of mdFiles) files.push(path.join(docsDir, name));
+    }
+
+    // Showcase categories: any folder named `categories` under rootDir (not in
+    // node_modules etc.) contains `<NN Name>/*.vue` subfolders.
+    for (const catDir of findDirsByName(rootDir, 'categories', skip, maxDepth)) {
+        const folders = fs.readdirSync(catDir, { withFileTypes: true })
+            .filter(d => d.isDirectory())
+            .map(d => d.name)
+            .sort();
+        for (const folder of folders) {
+            const sub = path.join(catDir, folder);
+            const vueFiles = fs.readdirSync(sub).filter(n => n.endsWith('.vue')).sort();
+            for (const name of vueFiles) files.push(path.join(sub, name));
+        }
+    }
+
+    // Hand-written API definitions: any folder named `definitions` under
+    // rootDir contains `<Vendor>/*.json` subfolders.
+    for (const defDir of findDirsByName(rootDir, 'definitions', skip, maxDepth)) {
+        const folders = fs.readdirSync(defDir, { withFileTypes: true })
+            .filter(d => d.isDirectory())
+            .map(d => d.name)
+            .sort();
+        for (const folder of folders) {
+            const sub = path.join(defDir, folder);
+            const jsonFiles = fs.readdirSync(sub).filter(n => n.endsWith('.json')).sort();
+            for (const name of jsonFiles) files.push(path.join(sub, name));
+        }
+    }
+
+    // Quasar's authoritative component JSONs (contain mixins + extends).
+    // These are added AFTER hand-written defs so they override by key (QBtn,
+    // QInput, etc.). Skipped when `quasar: false`.
+    if (quasar) {
+        const quasarComp = path.join(rootDir, 'node_modules/quasar/src/components');
+        if (fs.existsSync(quasarComp)) {
+            for (const f of walkFiles(quasarComp, n => /^Q[A-Z].*\.json$/.test(n))) {
+                files.push(f);
+            }
+        }
+    }
+
+    return files;
+}
+
+// ── Vue file parsing ────────────────────────────────────────────────────────
 
 /**
- * Extract the inner content of the root <template> block from a raw .vue string.
+ * Extract the inner content of the root <template> block from a raw .vue
+ * string. Handles nested <template> tags (used for slot templates) and strips
+ * the common leading indentation so the returned snippet reads cleanly when
+ * embedded in a markdown code fence.
  */
 function extractTemplate(raw) {
     if (!raw) return '';
     const openTag = raw.indexOf('<template');
     if (openTag === -1) return '';
     const contentStart = raw.indexOf('>', openTag) + 1;
+
+    // Track nesting depth so a `<template #foo>` inside the root doesn't
+    // trick us into closing early on its matching `</template>`.
     let depth = 1;
     let i = contentStart;
     while (i < raw.length && depth > 0) {
@@ -19,84 +194,134 @@ function extractTemplate(raw) {
         if (nextClose === -1) break;
         if (nextOpen !== -1 && nextOpen < nextClose) {
             depth++;
-            i = nextOpen + 9;
+            i = nextOpen + 9;   // past "<template"
         } else {
             depth--;
             if (depth === 0) {
                 const content = raw.slice(contentStart, nextClose);
                 const lines = content.replace(/^\n|\n$/g, '').split('\n');
+                // Dedent by the minimum leading whitespace among non-blank lines.
                 const indent = Math.min(
                     ...lines.filter(l => l.trim()).map(l => l.match(/^(\s*)/)[1].length),
                 );
                 return lines.map(l => l.slice(indent)).join('\n').trim();
             }
-            i = nextClose + 11;
+            i = nextClose + 11;  // past "</template>"
         }
     }
     return '';
 }
 
 /**
- * Parse a .vue file into a showcase item.
+ * Locate the body of the `export default { ... }` block and return everything
+ * between its braces. Brace counter ignores braces inside strings, template
+ * literals, and `// ... ` / block comments so it survives realistic Vue files.
+ * Returns '' if no `export default` is found.
+ */
+function findExportDefaultBody(raw) {
+    const m = raw.match(/export\s+default\s*\{/);
+    if (!m) return '';
+    const open = m.index + m[0].length - 1;   // index of the opening `{`
+    let depth = 1;
+    let i = open + 1;
+    while (i < raw.length && depth > 0) {
+        const ch = raw[i];
+        // Skip string / template literal — match quote and skip past it.
+        if (ch === "'" || ch === '"' || ch === '`') {
+            const q = ch;
+            i++;
+            while (i < raw.length) {
+                if (raw[i] === '\\') { i += 2; continue; }
+                if (raw[i] === q) { i++; break; }
+                i++;
+            }
+            continue;
+        }
+        // Skip line comment.
+        if (ch === '/' && raw[i + 1] === '/') {
+            while (i < raw.length && raw[i] !== '\n') i++;
+            continue;
+        }
+        // Skip block comment.
+        if (ch === '/' && raw[i + 1] === '*') {
+            i += 2;
+            while (i < raw.length - 1 && !(raw[i] === '*' && raw[i + 1] === '/')) i++;
+            i += 2;
+            continue;
+        }
+        if (ch === '{') depth++;
+        else if (ch === '}') {
+            depth--;
+            if (depth === 0) return raw.slice(open + 1, i);
+        }
+        i++;
+    }
+    return '';
+}
+
+/**
+ * Parse a single .vue showcase file into a flat metadata record. We don't run
+ * a full JS parser — we just look for the top-level `export default` options
+ * we care about (`label`, `icon`, `importName`, `importFrom`).
+ *
+ * Match constraint: the option must appear at the export default block's first
+ * indent level. This avoids picking up string values nested deeper (e.g. a
+ * `label: 'false'` inside a `data() { ... accentOptions: [{ label: 'false' }] }`
+ * would otherwise match before the real top-level `label`).
  */
 function parseVueFile(filePath) {
     const raw = fs.readFileSync(filePath, 'utf-8');
     const name = path.basename(filePath, '.vue');
     const template = extractTemplate(raw);
 
-    const labelMatch = raw.match(/label:\s*['"](.+?)['"]/);
-    const iconMatch = raw.match(/icon:\s*['"](.+?)['"]/);
-    const importFromMatch = raw.match(/importFrom:\s*['"](.+?)['"]/);
-
-    // importName can be a string or an array: importName: 'QBtn' or importName: ['QSlider', 'QRange']
-    const importArrayMatch = raw.match(/importName:\s*\[([^\]]+)\]/);
+    const body = findExportDefaultBody(raw);
+
+    // Detect the indent unit used by the body (tab or N spaces) by reading
+    // the first non-blank indented line.
+    const indentMatch = /^([\t ]+)\S/m.exec(body);
+    const indent = indentMatch ? indentMatch[1] : '    ';
+    // Anchor regexes to "newline + exactly this indent + key:" so deeper
+    // nested keys don't match.
+    const at = (key, valuePattern) =>
+        new RegExp(`(?:^|\\n)${indent.replace(/ /g, ' ').replace(/\t/g, '\\t')}${key}\\s*:\\s*${valuePattern}`);
+
+    const labelMatch = at('label', `(['"])(.+?)\\1`).exec(body);
+    const iconMatch = at('icon', `(['"])(.+?)\\1`).exec(body);
+    const importFromMatch = at('importFrom', `(['"])(.+?)\\1`).exec(body);
+
+    // `importName` can be either a string or an array of strings:
+    //   importName: 'QBtn'
+    //   importName: ['QSlider', 'QRange']
+    const importArrayMatch = at('importName', `\\[([^\\]]+)\\]`).exec(body);
     let importName = null;
     if (importArrayMatch) {
         importName = importArrayMatch[1].match(/['"]([^'"]+)['"]/g)?.map(s => s.replace(/['"]/g, '')) || null;
     } else {
-        const importNameMatch = raw.match(/importName:\s*['"](.+?)['"]/);
-        importName = importNameMatch?.[1] || null;
+        const importNameMatch = at('importName', `(['"])(.+?)\\1`).exec(body);
+        importName = importNameMatch?.[2] || null;
     }
 
     return {
         name,
-        label: labelMatch?.[1] || name,
-        icon: iconMatch?.[1] || null,
+        label: labelMatch?.[2] || name,
+        icon: iconMatch?.[2] || null,
         importName,
-        importFrom: importFromMatch?.[1] || null,
+        importFrom: importFromMatch?.[2] || null,
         template,
     };
 }
 
-/**
- * Scan showcase/categories/ directory and return structured data.
- */
-function loadCategoriesFromDir(catDir) {
-    if (!fs.existsSync(catDir)) return {};
-
-    const categories = {};
-    const folders = fs.readdirSync(catDir, { withFileTypes: true })
-        .filter(d => d.isDirectory())
-        .sort((a, b) => a.name.localeCompare(b.name));
-
-    for (const folder of folders) {
-        const displayName = folder.name.replace(/^\d+\s*/, '');
-        const files = fs.readdirSync(path.join(catDir, folder.name))
-            .filter(f => f.endsWith('.vue'))
-            .sort();
-
-        categories[displayName] = files.map(file =>
-            parseVueFile(path.join(catDir, folder.name, file)),
-        );
-    }
-    return categories;
-}
+// ── Unified loader ──────────────────────────────────────────────────────────
 
 /**
- * Build categories from a flat list of file paths.
- * .vue files are grouped by their parent directory name (numeric prefixes stripped).
- * .md files are collected as docs.
- * .json files are collected as API definitions.
+ * Route a flat list of file paths by extension into the three in-memory caches
+ * used by MCP tools:
+ *   .vue   → categories[<parent-folder-with-NN-stripped>].push(parsedItem)
+ *   .md    → docs[<name>]          (README.md keeps its `README` key)
+ *   .json  → definitions[<name>]   (by filename, without extension)
+ *
+ * Later paths overwrite earlier ones for docs/definitions by the same name,
+ * so callers can override root-scanned entries via `options.files`.
  */
 function loadFromFiles(filePaths) {
     const categories = {};
@@ -109,111 +334,149 @@ function loadFromFiles(filePaths) {
         const ext = path.extname(abs);
 
         if (ext === '.vue') {
+            // Group by the .vue's parent directory name, stripping any
+            // numeric prefix (e.g. "04 Buttons" → "Buttons") — that's the
+            // category naming convention used across the showcase folder.
             const folder = path.basename(path.dirname(abs));
             const cat = folder.replace(/^\d+\s*/, '');
             if (!categories[cat]) categories[cat] = [];
             categories[cat].push(parseVueFile(abs));
         } else if (ext === '.md') {
             const name = path.basename(abs, '.md');
-            const key = name === 'README' ? 'README' : name;
-            docs[key] = fs.readFileSync(abs, 'utf-8');
+            docs[name] = fs.readFileSync(abs, 'utf-8');
         } else if (ext === '.json') {
             const name = path.basename(abs, '.json');
-            definitions[name] = JSON.parse(fs.readFileSync(abs, 'utf-8'));
+            try { definitions[name] = JSON.parse(fs.readFileSync(abs, 'utf-8')); }
+            catch { /* ignore malformed json; don't poison the cache */ }
         }
     }
 
     return { categories, docs, definitions };
 }
 
+// ── Quasar normalizer data ─────────────────────────────────────────────────
+
 /**
- * Load README.md and docs/*.md from a root directory.
+ * Load the two kinds of "resolver data" that `normalizeQuasarApi` needs to
+ * flatten a raw Quasar src JSON:
+ *
+ *   apiExtends   — the shared prop/slot/event defs referenced by
+ *                  `"extends": "<name>"` in component JSONs. Lives in
+ *                  `quasar/src/api.extends.json`.
+ *   mixinLookup  — every non-Q*.json file under quasar/src/ keyed by its
+ *                  relative path minus the `.json` extension. Matches the
+ *                  mixin reference format used in Quasar JSONs, e.g.
+ *                  `"composables/private.use-size/use-size"` or
+ *                  `"components/btn/use-btn"`.
+ *
+ * Returns empty lookups when Quasar isn't installed at rootDir — definitions
+ * without mixins/extends still pass through normalize unchanged.
  */
-function loadDocsFromDir(rootDir) {
-    const docs = {};
-    const readme = path.join(rootDir, 'README.md');
-    if (fs.existsSync(readme)) {
-        docs['README'] = fs.readFileSync(readme, 'utf-8');
+function loadQuasarNormalizerData(rootDir) {
+    const quasarSrc = rootDir ? path.join(rootDir, 'node_modules/quasar/src') : null;
+    if (!quasarSrc || !fs.existsSync(quasarSrc)) {
+        return { apiExtends: {}, mixinLookup: {} };
     }
-    const docsDir = path.join(rootDir, 'docs');
-    if (fs.existsSync(docsDir)) {
-        for (const file of fs.readdirSync(docsDir).filter(f => f.endsWith('.md'))) {
-            docs[file.replace('.md', '')] = fs.readFileSync(path.join(docsDir, file), 'utf-8');
-        }
+
+    const readJson = (p) => {
+        try { return JSON.parse(fs.readFileSync(p, 'utf-8')); }
+        catch { return null; }
+    };
+
+    const apiExtends = readJson(path.join(quasarSrc, 'api.extends.json')) || {};
+
+    const mixinLookup = {};
+    for (const file of walkFiles(quasarSrc, n => n.endsWith('.json'))) {
+        const base = path.basename(file);
+        // Skip the extends source and any component JSON — we only want
+        // auxiliary mixin/composable definitions here.
+        if (base === 'api.extends.json' || /^Q[A-Z]/.test(base)) continue;
+        const rel = path.relative(quasarSrc, file).replace(/\\/g, '/').replace(/\.json$/, '');
+        const json = readJson(file);
+        if (json) mixinLookup[rel] = json;
     }
-    return docs;
+
+    return { apiExtends, mixinLookup };
 }
 
-/**
- * Load API definition JSON files from a root directory.
- */
-function loadDefinitionsFromDir(rootDir) {
-    const defs = {};
-    const defsDir = path.join(rootDir, 'src/varmory/showcase/definitions');
-    if (!fs.existsSync(defsDir)) return defs;
-
-    const folders = fs.readdirSync(defsDir, { withFileTypes: true })
-        .filter(d => d.isDirectory());
-
-    for (const folder of folders) {
-        const files = fs.readdirSync(path.join(defsDir, folder.name))
-            .filter(f => f.endsWith('.json'));
-        for (const file of files) {
-            const name = file.replace('.json', '');
-            const content = fs.readFileSync(path.join(defsDir, folder.name, file), 'utf-8');
-            defs[name] = JSON.parse(content);
-        }
-    }
-    return defs;
+// ── Markdown formatters (used by the get_api tool) ─────────────────────────
+
+function formatType(type) {
+    if (!type) return 'any';
+    return Array.isArray(type) ? type.join(' | ') : type;
 }
 
-/**
- * Format a component definition's props into a readable summary.
- */
+/** Small trailing tag rendered next to inherited props/slots/events/methods. */
+function formatMixinTag(entry) {
+    return entry?._mixin ? ` _[inherited: ${entry._mixin}]_` : '';
+}
+
+/** Render a component's props as a markdown bullet list. */
 function formatProps(apiDef) {
     if (!apiDef?.props) return 'No props defined.';
     const lines = [];
     for (const [name, prop] of Object.entries(apiDef.props)) {
+        const required = prop.required ? ' **(required)**' : '';
         const def = prop.default !== undefined ? ` (default: ${prop.default})` : '';
-        lines.push(`- **${name}**: ${prop.type || 'any'}${def} — ${prop.desc || ''}`);
+        const values = Array.isArray(prop.values) && prop.values.length
+            ? ` [values: ${prop.values.join(', ')}]`
+            : '';
+        lines.push(`- **${name}**${required}: ${formatType(prop.type)}${def}${values} — ${prop.desc || ''}${formatMixinTag(prop)}`);
     }
     return lines.join('\n');
 }
 
+// ── Public entry point ─────────────────────────────────────────────────────
+
 /**
  * Attach showcase resources and tools to an MCP server instance.
  *
  * @param {McpServer} server - An @modelcontextprotocol/sdk McpServer instance
  * @param {object} [options]
- * @param {string} [options.rootDir] - Absolute path to the varmory root. Defaults to one level up from this file.
- * @param {string[]} [options.files] - Explicit list of file paths (.vue, .md, .json). When provided, files are auto-classified by extension. Can be combined with rootDir.
- * @returns {McpServer} The same server instance, with resources and tools attached
+ * @param {string} [options.rootDir] - Absolute path to a varmory root. When
+ *        provided, the standard showcase layout is scanned automatically. When
+ *        omitted, the filesystem is NOT scanned — only `options.files` are
+ *        loaded.
+ * @param {string[]} [options.files] - Additional file paths to include on top
+ *        of whatever `rootDir` produced. Classified by extension — see
+ *        `loadFromFiles`. Useful for injecting fixtures in tests or overriding
+ *        a specific definition/doc.
+ * @param {boolean} [options.quasar=true] - When `false`, Quasar's component
+ *        JSONs and mixin/extends data are NOT auto-loaded from `node_modules`.
+ *        Definitions provided via `files` still pass through the normalizer
+ *        but won't have access to Quasar's shared `extends` / mixin pool.
+ * @param {number}  [options.maxDepth=5] - How deep the `categories/` /
+ *        `definitions/` folder search goes under `rootDir`.
+ * @returns {McpServer} The same server instance, now with resources and tools
+ *        attached.
  */
 export default function attachShowcase(server, options = {}) {
-    const rootDir = options.rootDir || (options.files ? null : path.resolve(path.dirname(new URL(import.meta.url).pathname), '..'));
-
-    let categories = {};
-    let docs = {};
-    let definitions = {};
-
-    if (rootDir) {
-        const catDir = path.join(rootDir, 'src/varmory/showcase/categories');
-        categories = loadCategoriesFromDir(catDir);
-        docs = loadDocsFromDir(rootDir);
-        definitions = loadDefinitionsFromDir(rootDir);
+    const rootDir = options.rootDir || null;
+    const quasar = options.quasar !== false;   // default true
+    const maxDepth = options.maxDepth ?? 5;
+
+    // Build one flat file list from (1) root-scan and (2) caller overrides,
+    // then run both through the same loader. `options.files` wins on
+    // same-named docs/definitions because it comes last.
+    const allFiles = [
+        ...(rootDir ? collectFilesFromRoot(rootDir, { quasar, maxDepth }) : []),
+        ...(options.files || []),
+    ];
+    const { categories, docs, definitions } = loadFromFiles(allFiles);
+
+    // Resolve `extends` / `mixins` in every definition. Pure no-op for
+    // definitions that don't have those markers, so hand-written JSONs
+    // (e.g. JPanel) are preserved byte-for-byte. When `quasar: false`, skip
+    // the (heavy) walk of node_modules/quasar/src — definitions still pass
+    // through normalize, just without Quasar's shared resolver pool.
+    const normalizerData = quasar ? loadQuasarNormalizerData(rootDir) : { apiExtends: {}, mixinLookup: {} };
+    for (const key of Object.keys(definitions)) {
+        definitions[key] = normalizeQuasarApi(definitions[key], normalizerData);
     }
 
-    if (options.files) {
-        const fromFiles = loadFromFiles(options.files);
-        for (const [cat, items] of Object.entries(fromFiles.categories)) {
-            if (!categories[cat]) categories[cat] = [];
-            categories[cat].push(...items);
-        }
-        Object.assign(docs, fromFiles.docs);
-        Object.assign(definitions, fromFiles.definitions);
-    }
-
-    // ── Resources ──────────────────────────────────────────
+    // ── Resources ──────────────────────────────────────────────────────
+    // Resources are URI-addressable listings; MCP clients typically enumerate
+    // them to discover what's available.
 
     server.resource('docs-list', 'showcase://docs', async () => {
         const names = Object.keys(docs);
@@ -259,10 +522,14 @@ export default function attachShowcase(server, options = {}) {
         };
     });
 
-    // ── Tools ──────────────────────────────────────────────
+    // ── Tools ──────────────────────────────────────────────────────────
+    // Tools are functions the model can call. All of ours are read-only —
+    // they only query the caches built above.
 
     const readOnly = { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false };
 
+    // Search across the showcase category tree. Matches on the raw filename,
+    // the display label, or any `importName` the Vue file declares.
     server.tool(
         'search_components',
         'Search showcase components by name or label',
@@ -290,6 +557,8 @@ export default function attachShowcase(server, options = {}) {
         },
     );
 
+    // Fetch a single showcase component's metadata + template snippet. Tries
+    // a case-insensitive match against file name, label, and importName.
     server.tool(
         'get_component',
         'Get a showcase component\'s template code and metadata',
@@ -312,6 +581,9 @@ export default function attachShowcase(server, options = {}) {
         },
     );
 
+    // Render a component's full API (props, slots, events, methods) as
+    // markdown. Works on both hand-written and Quasar-src definitions — the
+    // normalize step upstream makes them interchangeable here.
     server.tool(
         'get_api',
         'Get the API definition (props, slots, events) for a component',
@@ -323,22 +595,55 @@ export default function attachShowcase(server, options = {}) {
                 return { content: [{ type: 'text', text: `No API definition found for "${name}". Available: ${Object.keys(definitions).join(', ')}` }] };
             }
             const lines = [`# ${name} API`, '', '## Props', formatProps(def)];
-            if (def.slots) {
+
+            if (def.slots && Object.keys(def.slots).length) {
                 lines.push('', '## Slots');
                 for (const [slot, info] of Object.entries(def.slots)) {
-                    lines.push(`- **${slot}** — ${info.desc || ''}`);
+                    lines.push(`- **${slot}** — ${info.desc || ''}${formatMixinTag(info)}`);
+                    // Scoped slot props — indented under the slot bullet.
+                    if (info.scope && Object.keys(info.scope).length) {
+                        for (const [k, v] of Object.entries(info.scope)) {
+                            lines.push(`  - \`props.${k}\`: ${formatType(v?.type)} — ${v?.desc || ''}`);
+                        }
+                    }
                 }
             }
-            if (def.events) {
+
+            if (def.events && Object.keys(def.events).length) {
                 lines.push('', '## Events');
                 for (const [event, info] of Object.entries(def.events)) {
-                    lines.push(`- **${event}** — ${info.desc || ''}`);
+                    lines.push(`- **${event}** — ${info.desc || ''}${formatMixinTag(info)}`);
+                    // Event payload args — one bullet per param.
+                    if (info.params && Object.keys(info.params).length) {
+                        for (const [k, v] of Object.entries(info.params)) {
+                            lines.push(`  - \`${k}\`: ${formatType(v?.type)} — ${v?.desc || ''}`);
+                        }
+                    }
+                }
+            }
+
+            if (def.methods && Object.keys(def.methods).length) {
+                lines.push('', '## Methods');
+                for (const [method, info] of Object.entries(def.methods)) {
+                    lines.push(`- **${method}()** — ${info.desc || ''}${formatMixinTag(info)}`);
+                    // Method params + return — indented under the method bullet.
+                    if (info.params && Object.keys(info.params).length) {
+                        for (const [k, v] of Object.entries(info.params)) {
+                            const req = v?.required ? ' *(required)*' : '';
+                            lines.push(`  - param \`${k}\`${req}: ${formatType(v?.type)} — ${v?.desc || ''}`);
+                        }
+                    }
+                    if (info.returns && typeof info.returns === 'object') {
+                        lines.push(`  - returns: ${formatType(info.returns.type)} — ${info.returns.desc || ''}`);
+                    }
                 }
             }
             return { content: [{ type: 'text', text: lines.join('\n') }] };
         },
     );
 
+    // Simple full-text search across docs. Returns the first matching line as
+    // a short snippet so the model can decide whether to fetch the full doc.
     server.tool(
         'search_docs',
         'Search documentation pages by name or content',
@@ -364,6 +669,7 @@ export default function attachShowcase(server, options = {}) {
         },
     );
 
+    // Return the full raw markdown of a single doc.
     server.tool(
         'get_doc',
         'Read a documentation page by name',