@urbicon-ui/mcp-server 6.1.4

package/src/prompts/design-prompts.ts

@@ -0,0 +1,127 @@
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { z } from 'zod';
+
+/**
+ * MCP prompts that ship the *process* — the generate → validate → judge →
+ * synthesise loop (docs/DESIGN-MCP.md, Option E). MCP prompts are the
+ * client-agnostic way to deliver a workflow: any MCP client (Claude Code,
+ * Cursor, …) can invoke them, and they orchestrate the server's own tools
+ * (get_design_context, get_pattern, validate_design, get_design_principles).
+ *
+ * The creative loop itself runs in the consumer's harness (it needs file access
+ * and iteration); these prompts encode the steps so a single-shot generation
+ * doesn't regress to the mean.
+ */
+
+/** Clamp the requested variant count to a sane range. Prompt args arrive as strings. */
+export function variantCount(raw: string | undefined): number {
+  const n = Number.parseInt(raw ?? '', 10);
+  if (!Number.isFinite(n)) return 3;
+  return Math.min(5, Math.max(2, n));
+}
+
+function patternStep(pattern: string | undefined): string {
+  return pattern
+    ? `call \`get_pattern("${pattern}")\` and follow its layout, component-selection, and behavioural rules`
+    : 'if a composition pattern fits the brief (settings-page, dashboard, form-page, tab-navigation, onboarding-guide), call `get_pattern("<name>")` to load it';
+}
+
+const FOOTER =
+  'Output the final code, then a one-line rationale for each major design choice. Keep the rationale honest — name the trade-offs.';
+
+export function designPagePrompt(
+  brief: string,
+  pattern: string | undefined,
+  variants: string | undefined
+): string {
+  const n = variantCount(variants);
+  return `You are designing a new page for a project built on Urbicon UI:
+
+> **${brief}**
+
+Run this loop. Do not skip steps — a single-shot answer regresses to a generic template.
+
+1. **Context.** Call \`get_design_context\` and honour the project's paradigm, theme, density, and recorded decisions (ADRs). Then ${patternStep(pattern)}.
+2. **Ground rules.** Call \`get_design_principles\` for the heuristics and \`get_css_reference\` for the exact token names. Note the paradigm's token profile via \`get_design_principles(topic="theming")\`.
+3. **Generate ${n} variants.** Produce ${n} genuinely different implementations, each taking a distinct compositional approach *within* the paradigm — vary density, hierarchy emphasis, and the one signature moment. Do not let them converge. Use only real semantic tokens (no \`bg-status-*\`, no invented names).
+4. **Validate.** Run \`validate_design\` on every variant. Fix each error and warning. A variant that cannot pass is disqualified.
+5. **Judge.** Call \`get_design_principles(as="rubric")\` and score each surviving variant /40. Prefer a panel: judge correctness, hierarchy, paradigm-fidelity, and distinctiveness as separate lenses rather than one overall gut number.
+6. **Synthesise.** Pick the winner, then graft the best ideas from the runners-up. Run \`validate_design\` once more on the merged result — it must come back clean.
+7. **Record.** If the page follows a pattern, add \`data-design-pattern="<name>"\` to its root element and call \`sync_design_manifest\`. If you deviated from a pattern or principle on purpose, call \`record_design_decision\`.
+
+${FOOTER}`;
+}
+
+export function redesignPrompt(
+  brief: string,
+  code: string | undefined,
+  variants: string | undefined
+): string {
+  const n = variantCount(variants);
+  const current = code
+    ? `\n\nCurrent implementation:\n\n\`\`\`svelte\n${code}\n\`\`\``
+    : '\n\nFirst read the current implementation of the page in question.';
+  return `You are redesigning an existing page in a project built on Urbicon UI:
+
+> **${brief}**${current}
+
+Run a diagnosis-first loop:
+
+1. **Context.** Call \`get_design_context\` to recover the project's paradigm, theme, and prior decisions.
+2. **Diagnose.** Run \`validate_design\` on the current code, then call \`get_design_principles(as="rubric")\` and score the current page /40. Your revision targets are **every linter finding** plus the **two lowest-scoring criteria** — nothing else.
+3. **Generate ${n} variants** that fix exactly those weaknesses. Preserve the page's behaviour, data flow, and overall structure; change only what the diagnosis flagged. Use only real tokens.
+4. **Validate.** Run \`validate_design\` on each; fix every error and warning.
+5. **Judge.** Re-score each variant with the rubric. A redesign that does not beat the original on its target criteria is not shippable.
+6. **Synthesise.** Merge the best result, then run \`validate_design\` once more.
+7. **Record.** Call \`record_design_decision\` for any deliberate deviation; \`sync_design_manifest\` if pattern usage changed.
+
+End with a before/after table of the targeted criteria (old score → new score) and ${FOOTER.toLowerCase()}`;
+}
+
+export function registerDesignPrompts(server: McpServer): void {
+  server.prompt(
+    'design-page',
+    'Design a new page with the full generate → validate → judge → synthesise loop (variant exploration + rubric selection + linter gate). Keeps generation from regressing to a generic template.',
+    {
+      brief: z.string().describe('What to build, e.g. "a billing settings page for a SaaS admin".'),
+      pattern: z
+        .string()
+        .optional()
+        .describe(
+          'Composition pattern to follow (settings-page, dashboard, form-page, …). Optional.'
+        ),
+      variants: z.string().optional().describe('How many variants to explore (2–5, default 3).')
+    },
+    ({ brief, pattern, variants }) => ({
+      messages: [
+        {
+          role: 'user' as const,
+          content: { type: 'text' as const, text: designPagePrompt(brief, pattern, variants) }
+        }
+      ]
+    })
+  );
+
+  server.prompt(
+    'redesign',
+    'Redesign an existing page: diagnose with validate_design + the rubric, then fix exactly the flagged weaknesses through variant exploration. Preserves behaviour and structure.',
+    {
+      brief: z
+        .string()
+        .describe('What to redesign and why, e.g. "the dashboard feels flat and generic".'),
+      code: z
+        .string()
+        .optional()
+        .describe('The current page source. Optional — omit to have the model read it first.'),
+      variants: z.string().optional().describe('How many variants to explore (2–5, default 3).')
+    },
+    ({ brief, code, variants }) => ({
+      messages: [
+        {
+          role: 'user' as const,
+          content: { type: 'text' as const, text: redesignPrompt(brief, code, variants) }
+        }
+      ]
+    })
+  );
+}

package/src/resources/catalog.ts

@@ -0,0 +1,23 @@
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { loadCatalog } from '../data/catalog-loader.js';
+import { formatCompactCatalog } from '../utils/format-catalog.js';
+
+export function registerCatalogResource(server: McpServer): void {
+  server.resource('catalog', 'urbicon://catalog', async (uri) => {
+    const catalog = await loadCatalog();
+
+    const md = formatCompactCatalog(catalog.components, {
+      recipes: catalog.recipes
+    });
+
+    return {
+      contents: [
+        {
+          uri: uri.href,
+          mimeType: 'text/markdown',
+          text: md
+        }
+      ]
+    };
+  });
+}

package/src/resources/guides.ts

@@ -0,0 +1,60 @@
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import type { TemplateSections } from '../data/template-loader.js';
+import { loadTemplateSections } from '../data/template-loader.js';
+
+const GUIDE_RESOURCES: { id: string; name: string; key: keyof TemplateSections }[] = [
+  {
+    id: 'api-grammar',
+    name: 'API Grammar Guide',
+    key: 'api-grammar'
+  },
+  {
+    id: 'component-families',
+    name: 'Component Families Guide',
+    key: 'component-families'
+  },
+  {
+    id: 'tokens',
+    name: 'Design Tokens Guide',
+    key: 'tokens'
+  },
+  {
+    id: 'design-quality',
+    name: 'Design Quality Guide',
+    key: 'design-quality'
+  },
+  {
+    id: 'customization',
+    name: 'Customization Guide',
+    key: 'customization'
+  },
+  {
+    id: 'style-patterns',
+    name: 'Style Patterns Guide',
+    key: 'style-patterns'
+  },
+  {
+    id: 'auth-setup',
+    name: 'Auth Setup Guide',
+    key: 'auth-setup'
+  }
+];
+
+export function registerGuideResources(server: McpServer): void {
+  for (const guide of GUIDE_RESOURCES) {
+    server.resource(`guide-${guide.id}`, `urbicon://guide/${guide.id}`, async (uri) => {
+      const sections = await loadTemplateSections();
+      const content = sections[guide.key];
+
+      return {
+        contents: [
+          {
+            uri: uri.href,
+            mimeType: 'text/markdown',
+            text: content || `Guide section "${guide.id}" not found.`
+          }
+        ]
+      };
+    });
+  }
+}

package/src/server.test.ts

@@ -0,0 +1,69 @@
+import { describe, expect, it } from 'vitest';
+import { createServer } from './server.js';
+
+/**
+ * Smoke tests for the MCP server assembly. The SDK's `McpServer` keeps its
+ * tool/resource maps on private fields (`_registeredTools`, `_registeredResources`,
+ * `_registeredResourceTemplates`). We deliberately reach into those here because
+ * the point of this test is to guard the wiring in `server.ts` — if a tool
+ * registration goes missing or is renamed, this file should tell us about it.
+ */
+interface McpServerInternals {
+  _registeredTools: Record<string, unknown>;
+  _registeredResources: Record<string, unknown>;
+  _registeredResourceTemplates: Record<string, unknown>;
+  _registeredPrompts: Record<string, unknown>;
+}
+
+const EXPECTED_TOOLS = [
+  'find_components',
+  'get_component',
+  'get_recipe',
+  'suggest_implementation',
+  'get_implementation_checklist',
+  'get_css_reference',
+  'find_icons',
+  'get_design_principles',
+  'get_pattern',
+  'validate_design',
+  'get_design_context',
+  'record_design_decision',
+  'sync_design_manifest'
+] as const;
+
+describe('createServer', () => {
+  it('boots without throwing', () => {
+    expect(() => createServer()).not.toThrow();
+  });
+
+  it('returns an object', () => {
+    const server = createServer();
+    expect(server).toBeTypeOf('object');
+    expect(server).not.toBeNull();
+  });
+
+  it('registers exactly the expected set of tools', () => {
+    const server = createServer() as unknown as McpServerInternals;
+    const toolNames = Object.keys(server._registeredTools);
+
+    for (const expected of EXPECTED_TOOLS) {
+      expect(toolNames, `missing tool: ${expected}`).toContain(expected);
+    }
+    expect(toolNames).toHaveLength(EXPECTED_TOOLS.length);
+  });
+
+  it('registers at least one catalog resource', () => {
+    const server = createServer() as unknown as McpServerInternals;
+    const resourceCount =
+      Object.keys(server._registeredResources).length +
+      Object.keys(server._registeredResourceTemplates).length;
+    expect(resourceCount).toBeGreaterThan(0);
+  });
+
+  it('registers the design-process prompts', () => {
+    const server = createServer() as unknown as McpServerInternals;
+    const promptNames = Object.keys(server._registeredPrompts);
+    expect(promptNames).toContain('design-page');
+    expect(promptNames).toContain('redesign');
+  });
+});

package/src/server.ts

@@ -0,0 +1,48 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { registerDesignPrompts } from './prompts/design-prompts.js';
+import { registerCatalogResource } from './resources/catalog.js';
+import { registerGuideResources } from './resources/guides.js';
+import { registerFindComponentsTool } from './tools/find-components.js';
+import { registerFindIconsTool } from './tools/find-icons.js';
+import { registerGetChecklistTool } from './tools/get-checklist.js';
+import { registerGetComponentTool } from './tools/get-component.js';
+import { registerGetCssReferenceTool } from './tools/get-css-reference.js';
+import { registerGetDesignContextTool } from './tools/get-design-context.js';
+import { registerGetDesignPrinciplesTool } from './tools/get-design-principles.js';
+import { registerGetPatternTool } from './tools/get-pattern.js';
+import { registerGetRecipeTool } from './tools/get-recipe.js';
+import { registerRecordDesignDecisionTool } from './tools/record-design-decision.js';
+import { registerSuggestImplementationTool } from './tools/suggest-implementation.js';
+import { registerSyncDesignManifestTool } from './tools/sync-design-manifest.js';
+import { registerValidateDesignTool } from './tools/validate-design.js';
+
+export function createServer(): McpServer {
+  const server = new McpServer({
+    name: 'urbicon-ui',
+    version: '0.5.0'
+  });
+
+  // Resources
+  registerCatalogResource(server);
+  registerGuideResources(server);
+
+  // Tools
+  registerFindComponentsTool(server);
+  registerGetComponentTool(server);
+  registerGetRecipeTool(server);
+  registerSuggestImplementationTool(server);
+  registerGetChecklistTool(server);
+  registerGetCssReferenceTool(server);
+  registerFindIconsTool(server);
+  registerGetDesignPrinciplesTool(server);
+  registerGetPatternTool(server);
+  registerValidateDesignTool(server);
+  registerGetDesignContextTool(server);
+  registerRecordDesignDecisionTool(server);
+  registerSyncDesignManifestTool(server);
+
+  // Prompts — the deliverable design process (Option E)
+  registerDesignPrompts(server);
+
+  return server;
+}

package/src/tools/find-components.ts

@@ -0,0 +1,83 @@
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { z } from 'zod';
+import { loadCatalog } from '../data/catalog-loader.js';
+import { formatCompactCatalog } from '../utils/format-catalog.js';
+import { matchComponents } from '../utils/search.js';
+
+export function registerFindComponentsTool(server: McpServer): void {
+  server.tool(
+    'find_components',
+    'Browse and search the Urbicon UI component catalog. Without a query, lists all components grouped by category. With a query, performs fuzzy search across names, descriptions, and tags.',
+    {
+      query: z
+        .string()
+        .optional()
+        .describe(
+          'Search query to find components by name, description, or functionality (e.g. "date input", "modal", "accordeon")'
+        ),
+      tags: z
+        .array(z.string())
+        .optional()
+        .describe(
+          'Filter by category (form, layout, feedback, navigation, action, display, data) or by origin (auth = all components from the @urbicon-ui/auth package)'
+        )
+    },
+    { readOnlyHint: true, openWorldHint: true },
+    async ({ query, tags }) => {
+      const catalog = await loadCatalog();
+
+      if (query) {
+        const results = matchComponents(catalog.components, query, tags, 10);
+
+        if (results.length === 0) {
+          return {
+            content: [
+              {
+                type: 'text' as const,
+                text: `No components found for "${query}". Try broader terms or browse all with \`find_components\` (no query).`
+              }
+            ]
+          };
+        }
+
+        let md = `# Search Results for "${query}"\n\n`;
+        md += `> ${results.length} matching components.\n\n`;
+
+        for (const comp of results) {
+          const variants = comp.variants
+            .filter(
+              (v) => !['true', 'false'].every((b) => v.values.includes(b) && v.values.length <= 2)
+            )
+            .map((v) => `${v.name}: ${v.values.join('/')}`)
+            .join(' · ');
+
+          md += `- **${comp.name}** — ${comp.description}`;
+          if (variants) md += ` | ${variants}`;
+          if (comp.relatedComponents.length > 0) {
+            md += ` | Related: ${comp.relatedComponents.join(', ')}`;
+          }
+          md += '\n';
+        }
+
+        md += '\n> Use `get_component` with the component slug for full API docs.\n';
+        md += '> Use `get_css_reference` for CSS token documentation.\n';
+        md += '> Use `find_icons()` to browse all available icons.\n';
+
+        return {
+          content: [{ type: 'text' as const, text: md }]
+        };
+      }
+
+      let md = formatCompactCatalog(catalog.components, {
+        recipes: catalog.recipes,
+        tags
+      });
+      md += '\n> Use `get_css_reference` for CSS token documentation.\n';
+      md += '> Use `find_icons()` to browse all available icons.\n';
+
+      return {
+        content: [{ type: 'text' as const, text: md }]
+      };
+    }
+  );
+}

package/src/tools/find-icons.ts

@@ -0,0 +1,77 @@
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { loadIcons } from '../data/icon-loader.js';
+
+const CATEGORY_ORDER = [
+  'navigation',
+  'action',
+  'status',
+  'media',
+  'communication',
+  'data',
+  'layout',
+  'toggle'
+] as const;
+
+export function registerFindIconsTool(server: McpServer): void {
+  server.tool(
+    'find_icons',
+    'Get the complete Urbicon UI icon reference — all icons grouped by category with usage instructions.',
+    {},
+    { readOnlyHint: true, openWorldHint: false },
+    async () => {
+      const icons = await loadIcons();
+
+      if (icons.length === 0) {
+        return {
+          content: [
+            {
+              type: 'text' as const,
+              text: 'Icon metadata not available. Ensure the blocks package is accessible.'
+            }
+          ]
+        };
+      }
+
+      // Group by category
+      const byCategory = new Map<string, typeof icons>();
+      for (const icon of icons) {
+        for (const cat of icon.categories) {
+          if (!byCategory.has(cat)) byCategory.set(cat, []);
+          byCategory.get(cat)!.push(icon);
+        }
+      }
+
+      let md = `# Urbicon UI Icon Reference (${icons.length} icons)\n\n`;
+      md += '## Usage\n\n';
+      md += '**Direct import:**\n';
+      md += '```svelte\n';
+      md += '<script>\n';
+      md += "  import { SearchIcon } from '@urbicon-ui/blocks';\n";
+      md += '</script>\n\n';
+      md += '<SearchIcon size={24} />\n';
+      md += '```\n\n';
+      md += '**Dynamic (via IconProvider):**\n';
+      md += '```svelte\n';
+      md += '<Icon name="search" />\n';
+      md += '```\n\n';
+      md +=
+        '**Props:** `size` (default 24), `strokeWidth` (default 2), `class`, `rotate`, `flip`, `animation`\n\n';
+      md += '---\n\n';
+
+      for (const cat of CATEGORY_ORDER) {
+        const catIcons = byCategory.get(cat);
+        if (!catIcons || catIcons.length === 0) continue;
+
+        const sorted = [...catIcons].sort((a, b) => a.componentName.localeCompare(b.componentName));
+
+        md += `### ${cat} (${sorted.length})\n\n`;
+        for (const icon of sorted) {
+          md += `- ${icon.componentName} · \`${icon.name}\`\n`;
+        }
+        md += '\n';
+      }
+
+      return { content: [{ type: 'text' as const, text: md }] };
+    }
+  );
+}

package/src/tools/get-checklist.ts

@@ -0,0 +1,139 @@
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { z } from 'zod';
+import { loadCatalog } from '../data/catalog-loader.js';
+
+export function registerGetChecklistTool(server: McpServer): void {
+  server.tool(
+    'get_implementation_checklist',
+    'Get a best-practice checklist for implementing UI with Urbicon UI components. Optionally provide component names for context-specific advice.',
+    {
+      components: z
+        .array(z.string())
+        .optional()
+        .describe('Component names being used, e.g. ["Button", "Input", "Card"]')
+    },
+    { readOnlyHint: true },
+    async ({ components }) => {
+      let md = '# Urbicon UI Implementation Checklist\n\n';
+
+      // Project setup
+      md += '## Project Setup\n\n';
+      md += '- [ ] Install: `bun add @urbicon-ui/blocks @urbicon-ui/i18n`\n';
+      md +=
+        "- [ ] Add CSS imports to your root layout or entry CSS — your app owns the Tailwind import and it MUST come first:\n  ```css\n  @import 'tailwindcss';\n  @import '@urbicon-ui/blocks/style/index.css'; /* tokens + @source directives */\n  @import '@urbicon-ui/table/style/index.css';  /* only if using Table */\n  ```\n";
+      md +=
+        "- [ ] Import components from package root: `import { Button } from '@urbicon-ui/blocks'` (never from internal paths)\n";
+      md +=
+        '- [ ] **Import `style/index.css`, not the subfiles, and add NO manual `@source`** — `index.css` ships the Tailwind `@source` directives that make Tailwind scan component classes from `node_modules`, so responsive utilities (`lg:hidden`, `md:grid-cols-2`, etc.) inside library components compile correctly. The `foundation`/`semantic`/`interaction` subfiles omit those directives (and global classes like `.sr-only`); importing them instead of `index.css` is the usual cause of broken responsive layouts in production.\n';
+      md += '\n';
+
+      // Core checklist
+      md += '## Design Tokens\n\n';
+      md +=
+        '- [ ] Use semantic color tokens (`bg-surface-elevated`, `text-text-primary`, `border-border-default`) — not raw Tailwind colors (`bg-gray-100`)\n';
+      md +=
+        '- [ ] Use OKLCH interaction tokens for hover/active states (`bg-surface-hover`, `bg-surface-active`)\n';
+      md +=
+        '- [ ] Dark mode is automatic via `prefers-color-scheme` — semantic tokens switch automatically. For manual control, use `ThemeSwitcher` or set `data-theme="dark"` on `<html>`. Do NOT add `dark:` overrides\n';
+      md +=
+        '- [ ] Use z-index tokens via CSS custom properties: `z-[var(--z-modal)]`, `z-[var(--z-dropdown)]`, etc.\n';
+      md += '\n';
+
+      md += '## Styling\n\n';
+      md += '- [ ] Use `unstyled` prop to strip default styles when building custom designs\n';
+      md += '- [ ] Use `slotClasses` for targeted style overrides on specific sub-elements\n';
+      md +=
+        '- [ ] For reusable variant sets, register named `preset`s via `BlocksProvider` (and select with the `preset` prop) — not external variant libraries; Urbicon UI ships its own zero-dependency variant engine\n';
+      md +=
+        "- [ ] For conditional classes, pass an array to `class` (`class={['base', condition && 'extra']}`) — not concatenated conditional class strings\n";
+      md += '- [ ] Use `class` prop for simple additions — merges with defaults automatically\n';
+      md += '\n';
+
+      md += '## Accessibility\n\n';
+      md +=
+        '- [ ] Use `focus-visible:` for focus rings (not `focus:`) — keyboard-only visibility\n';
+      md +=
+        '- [ ] Provide `aria-label` on icon-only buttons and interactive elements without visible text\n';
+      md += '- [ ] Use semantic HTML elements — components render correct elements by default\n';
+      md += '- [ ] Test keyboard navigation — Tab, Enter, Space, Escape, Arrow keys\n';
+      md += '\n';
+
+      md += '## Micro-Interactions (Mint)\n\n';
+      md +=
+        '- [ ] Add `mint` prop for subtle feedback: `"scale"`, `"ripple"`, `"shake"`, or combine with arrays\n';
+      md += '- [ ] Use `mint` sparingly — primary CTAs and key interactive elements only\n';
+      md += '\n';
+
+      md += '## Component Integration\n\n';
+      md += '- [ ] Use `bind:value` / `bind:checked` / `bind:open` for two-way state binding\n';
+      md += '- [ ] Use callback props (`onValueChange`, `onOpenChange`) for side effects\n';
+      md += '- [ ] Use Svelte 5 snippets (`{#snippet ...}`) for custom content slots\n';
+      md += '\n';
+
+      md += '## i18n\n\n';
+      md += "- [ ] Wrap user-facing text in `$t('key')` from `@urbicon-ui/i18n`\n";
+      md +=
+        '- [ ] Components handle internal translations automatically — no manual i18n for built-in labels\n';
+      md += '\n';
+
+      md += '## Design Quality\n\n';
+      md +=
+        '- [ ] Visual weight varies across the page — not all Cards use the same `variant` and `padding`. Prominent content is `elevated`/`lg`, secondary is `outlined`/`md`\n';
+      md +=
+        '- [ ] Intent colors appear ONLY for semantic meaning (status, severity, actions) — never as decoration. Neutral surfaces dominate (80–90%)\n';
+      md +=
+        '- [ ] Spacing varies: tight (`gap-2`/`gap-3`) within related items, generous (`gap-8`/`gap-10`) between sections — not uniform everywhere\n';
+      md +=
+        "- [ ] Border-radius follows a deliberate strategy — overridden via `class` or `slotClasses` where component defaults don't match the design identity\n";
+      md +=
+        '- [ ] Data-driven styling: different states/severities are visually distinct through padding, font-weight, Badge `variant`, and text color — not just labels\n';
+      md +=
+        '- [ ] Each major section has one clearly dominant element. If everything is emphasized, nothing is\n';
+      md +=
+        '- [ ] Implementation has its own visual identity — not a copy of recipe or example styling\n';
+      md += '\n';
+
+      // Context-specific advice
+      if (components && components.length > 0) {
+        const catalog = await loadCatalog();
+        const catalogMap = new Map(catalog.components.map((c) => [c.name.toLowerCase(), c]));
+
+        const found = components
+          .map((name) => catalogMap.get(name.toLowerCase()))
+          .filter((c) => c !== undefined);
+
+        if (found.length > 0) {
+          md += '## Component-Specific Notes\n\n';
+
+          for (const comp of found) {
+            md += `### ${comp.name}\n`;
+            if (comp.variants.length > 0) {
+              const key = comp.variants
+                .filter((v) => !['true', 'false'].every((b) => v.values.includes(b)))
+                .map((v) => `\`${v.name}\`: ${v.values.join(' / ')}`)
+                .join(', ');
+              if (key) md += `- Variants: ${key}\n`;
+            }
+            if (comp.slots.length > 0) {
+              md += `- Customizable slots: \`${comp.slots.join('`, `')}\`\n`;
+            }
+            if (comp.relatedComponents.length > 0) {
+              md += `- Consider also: ${comp.relatedComponents.join(', ')}\n`;
+            }
+            md += '\n';
+          }
+        }
+      }
+
+      // Cross-references
+      md += '---\n\n**Related tools:**\n';
+      md += '- `get_css_reference()` — CSS variable names and override patterns\n';
+      md += '- `get_component("<slug>")` — specific component API details\n';
+      md += '- `find_icons()` — browse all available icons\n';
+
+      return {
+        content: [{ type: 'text' as const, text: md }]
+      };
+    }
+  );
+}