@urbicon-ui/mcp-server 6.1.4

package/src/tools/get-design-context.ts

@@ -0,0 +1,43 @@
+import { readFile } from 'node:fs/promises';
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { z } from 'zod';
+import { emptyManifest, formatContext, parseManifest } from '../design-manifest/index.js';
+import { getProjectManifestPath } from '../utils/paths.js';
+
+export function registerGetDesignContextTool(server: McpServer): void {
+  server.tool(
+    'get_design_context',
+    "Read this project's design manifest (design.manifest.md): the chosen paradigm / theme / density, which pages use which composition patterns, and the recorded design decisions (ADRs). Call this at the START of any UI task so generated code stays consistent with what the project has already committed to.",
+    {
+      manifestPath: z
+        .string()
+        .optional()
+        .describe(
+          'Path to design.manifest.md. Defaults to ./design.manifest.md in the project root.'
+        )
+    },
+    { readOnlyHint: true },
+    async ({ manifestPath }) => {
+      const path = manifestPath ?? getProjectManifestPath();
+
+      let manifest: ReturnType<typeof emptyManifest>;
+      try {
+        manifest = parseManifest(await readFile(path, 'utf-8'));
+      } catch {
+        manifest = emptyManifest();
+      }
+
+      let text = formatContext(manifest);
+      if (!manifest.exists) {
+        text +=
+          `\n\n> No manifest found at \`${path}\`. Scaffold one with \`sync_design_manifest\`, ` +
+          'or record the first decision with `record_design_decision`.\n';
+      }
+      text += '\n---\n\n**Next steps:**\n';
+      text += '- `get_pattern("<name>")` — the rules behind a pattern listed above\n';
+      text += '- `get_design_principles(topic="theming")` — the paradigm token profile\n';
+
+      return { content: [{ type: 'text' as const, text }] };
+    }
+  );
+}

package/src/tools/get-design-principles.ts

@@ -0,0 +1,72 @@
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { z } from 'zod';
+import {
+  extractPrincipleSection,
+  loadPrinciples,
+  PRINCIPLE_TOPICS
+} from '../data/design-system-loader.js';
+import { renderRubric } from '../design-rubric/rubric.js';
+
+export function registerGetDesignPrinciplesTool(server: McpServer): void {
+  server.tool(
+    'get_design_principles',
+    'Get design heuristics and rules for building UIs with Urbicon UI. Covers visual hierarchy, interaction patterns, component selection heuristics, layout rules, accessibility, theming (token hierarchy, paradigms, change decision tree). Call this FIRST when generating new UI — before selecting components. Pass `as="rubric"` to instead get the 1–5 scoring rubric for judging a generated UI.',
+    {
+      topic: z
+        .enum(PRINCIPLE_TOPICS)
+        .optional()
+        .describe(
+          'Filter to a specific topic. "theming" includes the design change decision tree, paradigm profiles, and token override guide. Omit for all principles.'
+        ),
+      as: z
+        .enum(['guide', 'rubric'])
+        .optional()
+        .describe(
+          'Output mode. "guide" (default) returns the heuristics for building UI. "rubric" returns the 8-criterion 1–5 scoring rubric for judging a generated UI (ignores `topic`).'
+        )
+    },
+    { readOnlyHint: true },
+    async ({ topic, as }) => {
+      if (as === 'rubric') {
+        let text = renderRubric();
+        text += '\n---\n\n**Next steps:**\n';
+        text +=
+          '- `validate_design(code)` — deterministic correctness check that anchors criterion 8\n';
+        text +=
+          '- `get_design_principles(topic="theming")` — paradigm profiles to judge fidelity against\n';
+        return { content: [{ type: 'text' as const, text }] };
+      }
+
+      const principles = await loadPrinciples();
+
+      if (!principles) {
+        return {
+          content: [
+            {
+              type: 'text' as const,
+              text: 'Design principles not found. Ensure design-system/principles.md exists at the monorepo root.'
+            }
+          ]
+        };
+      }
+
+      let text: string;
+
+      if (topic) {
+        const section = extractPrincipleSection(principles, topic);
+        text = section ?? principles;
+      } else {
+        text = principles;
+      }
+
+      text += '\n\n---\n\n**Next steps:**\n';
+      text += '- `get_pattern("<name>")` — composition patterns for specific page types\n';
+      text += '- `get_css_reference()` — CSS token names and override patterns\n';
+      text += '- `find_components()` — browse the component catalog\n';
+
+      return {
+        content: [{ type: 'text' as const, text }]
+      };
+    }
+  );
+}

package/src/tools/get-pattern.ts

@@ -0,0 +1,69 @@
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { z } from 'zod';
+import { getPatternByName, loadPatterns } from '../data/design-system-loader.js';
+
+export function registerGetPatternTool(server: McpServer): void {
+  server.tool(
+    'get_pattern',
+    'Get a composition pattern for a specific page type. Patterns describe layout structure, component selection, spacing, and behavioral rules for common page archetypes (settings-page, dashboard, form-page). Use after consulting design principles.',
+    {
+      name: z
+        .string()
+        .optional()
+        .describe(
+          'Pattern name (e.g. "settings-page", "dashboard", "form-page"). Omit to list all available patterns.'
+        )
+    },
+    { readOnlyHint: true },
+    async ({ name }) => {
+      if (!name) {
+        const patterns = await loadPatterns();
+
+        if (patterns.length === 0) {
+          return {
+            content: [
+              {
+                type: 'text' as const,
+                text: 'No composition patterns found. Ensure design-system/patterns/*.md exists at the monorepo root.'
+              }
+            ]
+          };
+        }
+
+        let md = '# Available Composition Patterns\n\n';
+        for (const p of patterns) {
+          md += `- **${p.title}** (\`${p.name}\`) — ${p.description}\n`;
+        }
+        md += '\n> Use `get_pattern("<name>")` to get the full pattern.\n';
+        md += '\n---\n\n**Next steps:**\n';
+        md += '- `get_design_principles()` — design heuristics and rules\n';
+        md += '- `get_css_reference()` — CSS token names and override patterns\n';
+        return { content: [{ type: 'text' as const, text: md }] };
+      }
+
+      const pattern = await getPatternByName(name);
+
+      if (!pattern) {
+        const all = await loadPatterns();
+        const available = all.map((p) => `\`${p.name}\``).join(', ');
+        return {
+          content: [
+            {
+              type: 'text' as const,
+              text: `Pattern "${name}" not found. Available patterns: ${available}`
+            }
+          ]
+        };
+      }
+
+      let md = pattern.content;
+      md += '\n\n---\n\n**Next steps:**\n';
+      md += '- `get_design_principles()` — design heuristics and rules\n';
+      md += '- `get_css_reference()` — CSS token names and override patterns\n';
+      md += '- `suggest_implementation("<description>")` — generate a component skeleton\n';
+      md += '- `get_recipe("<id>")` — get a complete code recipe\n';
+
+      return { content: [{ type: 'text' as const, text: md }] };
+    }
+  );
+}

package/src/tools/get-recipe.ts

@@ -0,0 +1,80 @@
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { z } from 'zod';
+import { getRecipeById, loadRecipes } from '../data/recipe-loader.js';
+
+export function registerGetRecipeTool(server: McpServer): void {
+  server.tool(
+    'get_recipe',
+    'Get a complete, production-ready Svelte 5 code recipe.',
+    {
+      scenario: z
+        .string()
+        .describe(
+          'Recipe id: login, settings, dashboard, pricing, profile-card, data-table, command-palette'
+        )
+    },
+    { readOnlyHint: true },
+    async ({ scenario }) => {
+      const recipe = await getRecipeById(scenario);
+
+      if (!recipe) {
+        const allRecipes = await loadRecipes();
+        const available = allRecipes.map((r) => r.id).join(', ');
+        return {
+          content: [
+            {
+              type: 'text' as const,
+              text: `Recipe "${scenario}" not found. Available recipes: ${available}`
+            }
+          ]
+        };
+      }
+
+      let md = `# Recipe: ${recipe.title}\n\n`;
+      if (recipe.description) md += `${recipe.description}\n\n`;
+      if (recipe.pattern) {
+        md += `**Composition pattern:** \`${recipe.pattern}\` — this recipe is one instance of that page archetype. Call \`get_pattern("${recipe.pattern}")\` for the layout/spacing/component-selection rules behind it.\n\n`;
+      }
+      if (recipe.components.length > 0) {
+        md += `**Components used:** ${recipe.components.join(', ')}\n\n`;
+      }
+      if (recipe.features.length > 0) {
+        md += '**Features:**\n';
+        for (const f of recipe.features) {
+          md += `- ${f}\n`;
+        }
+        md += '\n';
+      }
+      if (recipe.code) {
+        md += `\`\`\`svelte\n${recipe.code}\n\`\`\`\n`;
+      }
+
+      // Cross-references
+      md += '\n---\n\n**Next steps:**\n';
+      if (recipe.components.length > 0) {
+        for (const comp of recipe.components.slice(0, 5)) {
+          const slug = comp.replace(
+            /([A-Z])/g,
+            (_, c: string, i: number) => (i > 0 ? '-' : '') + c.toLowerCase()
+          );
+          md += `- \`get_component("${slug}")\` — ${comp} API docs\n`;
+        }
+      }
+      if (recipe.pattern) {
+        md += `- \`get_pattern("${recipe.pattern}")\` — the composition pattern this recipe follows\n`;
+      }
+      md += '- `get_implementation_checklist()` — design quality rules\n';
+      md += '- `get_css_reference()` — CSS token names and override patterns\n';
+      md += '- `validate_design(code)` — lint your adaptation before shipping\n';
+
+      return {
+        content: [
+          {
+            type: 'text' as const,
+            text: md
+          }
+        ]
+      };
+    }
+  );
+}

package/src/tools/record-design-decision.ts

@@ -0,0 +1,99 @@
+import { readFile, writeFile } from 'node:fs/promises';
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { z } from 'zod';
+import { appendDecision, createManifestTemplate, parseManifest } from '../design-manifest/index.js';
+import { getProjectManifestPath, isWithinProjectDir } from '../utils/paths.js';
+
+export function registerRecordDesignDecisionTool(server: McpServer): void {
+  server.tool(
+    'record_design_decision',
+    'Append a design decision (ADR) to the project design manifest — record a deliberate deviation from a pattern or principle so future sessions and other developers honour it. Creates design.manifest.md if it does not exist yet.',
+    {
+      title: z
+        .string()
+        .min(1)
+        .describe('Short decision title, e.g. "Tabs for settings instead of sidebar".'),
+      decision: z.string().min(1).describe('What was decided — concrete and imperative.'),
+      rationale: z
+        .string()
+        .optional()
+        .describe('Why — the trade-off that justifies the deviation.'),
+      status: z
+        .enum(['accepted', 'proposed', 'superseded'])
+        .optional()
+        .describe('Decision status. Defaults to "accepted".'),
+      date: z
+        .string()
+        .regex(/^\d{4}-\d{2}-\d{2}$/)
+        .optional()
+        .describe('ISO date (YYYY-MM-DD). Defaults to today.'),
+      manifestPath: z
+        .string()
+        .optional()
+        .describe('Path to design.manifest.md. Defaults to the project root.')
+    },
+    { readOnlyHint: false },
+    async ({ title, decision, rationale, status, date, manifestPath }) => {
+      const path = manifestPath ?? getProjectManifestPath();
+      if (!path.endsWith('.md')) {
+        return {
+          content: [
+            { type: 'text' as const, text: `Refusing to write: "${path}" is not a .md file.` }
+          ],
+          isError: true
+        };
+      }
+      if (manifestPath && !isWithinProjectDir(manifestPath)) {
+        return {
+          content: [
+            {
+              type: 'text' as const,
+              text: `Refusing to write outside the project root: "${path}".`
+            }
+          ],
+          isError: true
+        };
+      }
+
+      let content: string;
+      let created = false;
+      try {
+        content = await readFile(path, 'utf-8');
+      } catch {
+        content = createManifestTemplate({});
+        created = true;
+      }
+
+      const today = date ?? new Date().toISOString().slice(0, 10);
+      const updated = appendDecision(content, {
+        date: today,
+        title,
+        status: status ?? 'accepted',
+        decision,
+        rationale
+      });
+
+      try {
+        await writeFile(path, updated, 'utf-8');
+      } catch (err) {
+        return {
+          content: [
+            { type: 'text' as const, text: `Failed to write ${path}: ${(err as Error).message}` }
+          ],
+          isError: true
+        };
+      }
+
+      const total = parseManifest(updated).decisions.length;
+      const note = created ? ' (created the manifest)' : '';
+      return {
+        content: [
+          {
+            type: 'text' as const,
+            text: `Recorded ADR "${title}" dated ${today} in \`${path}\`${note}. ${total} decision(s) on record.`
+          }
+        ]
+      };
+    }
+  );
+}

package/src/tools/suggest-implementation.ts

@@ -0,0 +1,251 @@
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { z } from 'zod';
+import type { ComponentCatalogEntry } from '../data/catalog-loader.js';
+import { loadCatalog } from '../data/catalog-loader.js';
+import { loadRecipes } from '../data/recipe-loader.js';
+import { matchComponents } from '../utils/search.js';
+
+/** Default props and skeleton hints per component type */
+const SKELETON_HINTS: Record<string, { attrs: string; children?: string; selfClosing?: boolean }> =
+  {
+    Button: { attrs: 'onclick={handleClick}', children: 'Click me' },
+    Input: { attrs: 'label="Label" bind:value={value} placeholder="..."', selfClosing: true },
+    Textarea: { attrs: 'label="Label" bind:value={text} placeholder="..."', selfClosing: true },
+    Card: { attrs: 'variant="outlined"', children: '  <!-- card content -->' },
+    Checkbox: { attrs: 'label="Label" bind:checked={checked}', selfClosing: true },
+    Toggle: { attrs: 'label="Enable" bind:checked={enabled}', selfClosing: true },
+    Select: { attrs: 'label="Choose" bind:value={selected}', children: '...' },
+    Combobox: { attrs: 'label="Search" bind:value={selected}', selfClosing: true },
+    RadioGroup: { attrs: 'bind:value={selected}', children: '...' },
+    Slider: { attrs: 'bind:value={sliderValue}', selfClosing: true },
+    Alert: { attrs: 'intent="info"', children: 'Message text' },
+    Toast: { attrs: '', children: '' },
+    Badge: { attrs: '', children: 'Label' },
+    Dialog: { attrs: 'bind:open={showDialog} title="Title"', children: '  <!-- dialog body -->' },
+    Drawer: {
+      attrs: 'bind:open={showDrawer} placement="right"',
+      children: '  <!-- drawer content -->'
+    },
+    Avatar: { attrs: 'src="/avatar.jpg" alt="User"', selfClosing: true },
+    Spinner: { attrs: '', selfClosing: true },
+    Progress: { attrs: 'value={progress}', selfClosing: true },
+    Skeleton: { attrs: 'class="h-4 w-full"', selfClosing: true },
+    Separator: { attrs: '', selfClosing: true },
+    Tab: { attrs: '', children: '...' },
+    Breadcrumb: { attrs: '', children: '...' },
+    Pagination: { attrs: 'total={100} bind:page={page}', selfClosing: true },
+    Stepper: { attrs: 'bind:activeStep={step}', children: '...' },
+    Accordion: { attrs: '', children: '...' },
+    Collapsible: { attrs: '', children: '...' },
+    Sidebar: { attrs: 'bind:open={sidebarOpen}', children: '  <!-- nav links -->' },
+    Menu: { attrs: '', children: '...' },
+    Toolbar: { attrs: 'aria-label="Actions"', children: '...' },
+    Tooltip: { attrs: 'label="Tooltip text"', children: '...' },
+    Popover: { attrs: '', children: '...' },
+    Calendar: { attrs: 'bind:value={date}', selfClosing: true },
+    Planner: {
+      attrs: 'view="week" items={items} getDate={(item) => item.date}',
+      children:
+        '  {#snippet cell({ items, isoDate })}\n    <!-- your own per-day content; items are bucketed + typed -->\n  {/snippet}'
+    },
+    CommandPalette: { attrs: 'bind:open={showPalette} items={commands}', selfClosing: true },
+    Table: { attrs: 'data={rows} columns={columns}', selfClosing: true },
+    ButtonGroup: { attrs: 'selection="single" bind:value={selected}', children: '...' },
+    DatePicker: { attrs: 'label="Date" bind:value={date}', selfClosing: true },
+    DateRangePicker: {
+      attrs: 'label="Date range" bind:startDate={start} bind:endDate={end}',
+      selfClosing: true
+    },
+    SegmentGroup: { attrs: 'bind:value={selected}', children: '...' },
+    LocaleSwitcher: { attrs: '', selfClosing: true },
+    ThemeSwitcher: { attrs: '', selfClosing: true },
+    FileUpload: {
+      attrs: 'bind:files multiple title="Drop files here"',
+      selfClosing: true
+    }
+  };
+
+/** Compact implementation rules — embedded to avoid an extra get_implementation_checklist call */
+const IMPLEMENTATION_RULES = `## Implementation Rules
+
+- **CSS imports** — Add to root layout, Tailwind first: \`@import 'tailwindcss';\` then \`@import '@urbicon-ui/blocks/style/index.css';\` (ships tokens + the \`@source\` directives). Import \`index.css\`, NOT the \`foundation\`/\`semantic\`/\`interaction\` subfiles, and add no manual \`@source\`
+- **Semantic tokens only** — Use \`bg-surface-elevated\`, \`text-text-primary\`, \`border-border-default\` — never raw Tailwind colors
+- **Dark mode** — Automatic via \`prefers-color-scheme\`. Do NOT add \`dark:\` overrides
+- **Focus** — Always \`focus-visible:\` (not \`focus:\`) for keyboard-only focus rings
+- **State binding** — \`bind:value\`, \`bind:checked\`, \`bind:open\` for two-way state; callback props (\`onValueChange\`) for side effects
+- **Custom content** — Use Svelte 5 snippets (\`{#snippet name()}...{/snippet}\`), not legacy slots
+- **Styling overrides** — \`class\` for simple additions, \`slotClasses\` for per-slot targeting, \`unstyled\` to strip all defaults
+- **Mint** — Add \`mint="scale"\` or \`mint="ripple"\` sparingly on primary CTAs only
+
+## Design Quality
+
+- **Vary visual weight** — Don't use the same Card variant/padding everywhere. Reading-flow content → \`variant="quiet"\` (default) + \`padding="md"\`. Architectural delineation → \`variant="outlined"\` + \`padding="md"\`. Lifted content (cards-on-page) → \`variant="elevated"\` + \`padding="lg"\`. Popover-family floating surfaces → \`variant="floating"\`.
+- **Color = meaning** — Neutral surfaces dominate (80–90%). Use \`intent\` colors ONLY for semantic meaning (status, severity, actions) — never as decoration.
+- **Spacing = hierarchy** — Tight (\`gap-2\`/\`gap-3\`) within related items. Generous (\`gap-8\`/\`gap-10\`) between sections. Don't use uniform spacing everywhere.
+- **Commit to a radius** — Pick a radius philosophy (\`rounded-lg\`, \`rounded-xl\`, or \`rounded-2xl\`) and apply it consistently via \`class\` or \`slotClasses\`. Don't rely solely on component defaults.
+- **Data-driven styling** — Different states/severities should look visually distinct (vary padding, font-weight, Badge variant, text color) — not just carry a different label.
+- **Don't copy recipe styling** — Recipes show ONE interpretation. Create YOUR visual identity with your own spacing rhythm, color distribution, and layout density.
+`;
+
+export function registerSuggestImplementationTool(server: McpServer): void {
+  server.tool(
+    'suggest_implementation',
+    'Generate a Svelte 5 skeleton using Urbicon UI components. Either specify component names directly (preferred — pick them from the catalog first) or describe what you want to build.',
+    {
+      description: z.string().describe('What you want to build, e.g. "login form with validation"'),
+      components: z
+        .array(z.string())
+        .optional()
+        .describe(
+          'Specific component names to use (e.g. ["Input", "Button", "Card"]). If omitted, components are auto-matched from the description.'
+        ),
+      style: z.enum(['minimal', 'polished']).default('polished')
+    },
+    { readOnlyHint: true, openWorldHint: true },
+    async ({ description, components: requestedComponents, style }) => {
+      const catalog = await loadCatalog();
+      const recipes = await loadRecipes();
+
+      let matched: ComponentCatalogEntry[];
+
+      if (requestedComponents && requestedComponents.length > 0) {
+        // Use explicitly requested components — look them up in catalog
+        const catalogMap = new Map(catalog.components.map((c) => [c.name.toLowerCase(), c]));
+        matched = requestedComponents
+          .map((name) => catalogMap.get(name.toLowerCase()))
+          .filter((c): c is ComponentCatalogEntry => c !== undefined);
+      } else {
+        // Fall back to search-based matching
+        matched = matchComponents(catalog.components, description, undefined, 8);
+      }
+
+      if (matched.length === 0) {
+        return {
+          content: [
+            {
+              type: 'text' as const,
+              text: `No matching components found for "${description}". Try specifying component names directly via the \`components\` parameter, or browse the catalog with \`find_components\`.`
+            }
+          ]
+        };
+      }
+
+      // Find matching recipes — ID substring match OR ≥40% component overlap
+      const descLower = description.toLowerCase();
+      const matchedNames = new Set(matched.map((c) => c.name));
+      const matchingRecipes = recipes.filter((r) => {
+        // Direct ID match: description contains the recipe ID (e.g. "login" in "login form")
+        if (descLower.includes(r.id)) return true;
+        // Component overlap: at least 40% of recipe's components are in matched set
+        if (r.components.length > 0) {
+          const overlap = r.components.filter((c) => matchedNames.has(c)).length;
+          if (overlap / r.components.length >= 0.4) return true;
+        }
+        return false;
+      });
+
+      const imports = matched.map((c) => c.name);
+
+      let md = '# Implementation Suggestion\n\n';
+      md += `> ${description}\n\n`;
+
+      // Imports
+      md += '## Imports\n\n';
+      md += '```svelte\n<script lang="ts">\n';
+      md += `  import { ${imports.join(', ')} } from '@urbicon-ui/blocks';\n`;
+      md += '</script>\n```\n\n';
+
+      // Component details with prop types
+      md += '## Components\n\n';
+      for (const comp of matched) {
+        const meaningfulVariants = comp.variants
+          .filter((v) => {
+            const sorted = [...v.values].sort();
+            return !(
+              (sorted.length === 1 && (sorted[0] === 'true' || sorted[0] === 'false')) ||
+              (sorted.length === 2 && sorted[0] === 'false' && sorted[1] === 'true')
+            );
+          })
+          .map((v) => {
+            const def = v.default ? ` (default: ${v.default})` : '';
+            return `${v.name}: ${v.values.join('/')}${def}`;
+          })
+          .join(' · ');
+
+        md += `- **${comp.name}** — ${comp.description}`;
+        if (meaningfulVariants) md += ` | ${meaningfulVariants}`;
+        md += '\n';
+
+        // Show non-primitive prop types so LLMs understand the API shape
+        const propTypes = comp.keyPropTypes || {};
+        const typeEntries = Object.entries(propTypes);
+        if (typeEntries.length > 0) {
+          const formatted = typeEntries.map(([name, type]) => `\`${name}: ${type}\``).join(', ');
+          md += `  Key props: ${formatted}\n`;
+        }
+
+        if (comp.slots.length > 0) {
+          md += `  Slots: \`${comp.slots.join('`, `')}\`\n`;
+        }
+      }
+      md += '\n';
+
+      // Skeleton
+      md += '## Skeleton\n\n';
+      md += '```svelte\n<script lang="ts">\n';
+      md += `  import { ${imports.join(', ')} } from '@urbicon-ui/blocks';\n`;
+      md += '</script>\n\n';
+      md += generateSkeleton(matched, style);
+      md += '```\n\n';
+
+      // Embedded implementation rules (replaces separate checklist call)
+      md += IMPLEMENTATION_RULES;
+      md += '\n';
+
+      // Related recipes
+      if (matchingRecipes.length > 0) {
+        md += '## Related Recipes\n\n';
+        md += 'Use `get_recipe` tool to get full production-ready code:\n\n';
+        for (const recipe of matchingRecipes) {
+          md += `- **${recipe.title}** (\`${recipe.id}\`) — ${recipe.description}\n`;
+        }
+        md += '\n';
+      }
+
+      // Drill-down hint
+      md += '## Next Steps\n\n';
+      md += `For full API docs on any component, use \`get_component\`:\n`;
+      for (const comp of matched.slice(0, 5)) {
+        md += `- \`get_component("${comp.slug}")\`\n`;
+      }
+      md += '\nOther useful tools:\n';
+      md += '- `get_design_principles()` — design heuristics and theming guide\n';
+      md += '- `get_pattern("<name>")` — composition pattern for this page type\n';
+      md += '- `get_css_reference()` — CSS token names and override patterns\n';
+      md += '- `find_icons()` — browse all available icons\n';
+
+      return {
+        content: [{ type: 'text' as const, text: md }]
+      };
+    }
+  );
+}
+
+function generateSkeleton(components: ComponentCatalogEntry[], _style: string): string {
+  const lines: string[] = [];
+
+  for (const comp of components.slice(0, 6)) {
+    const hints = SKELETON_HINTS[comp.name];
+    const attrs = hints?.attrs || '';
+    const attrsStr = attrs ? ` ${attrs}` : '';
+
+    if (hints?.selfClosing) {
+      lines.push(`<${comp.name}${attrsStr} />`);
+    } else {
+      const children = hints?.children || '...';
+      lines.push(`<${comp.name}${attrsStr}>${children}</${comp.name}>`);
+    }
+  }
+
+  return `${lines.join('\n')}\n`;
+}