@urbicon-ui/mcp-server 6.3.1 → 6.3.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@urbicon-ui/mcp-server",
-  "version": "6.3.1",
+  "version": "6.3.3",
   "description": "Model Context Protocol server exposing the Urbicon UI component catalog, recipes and design intelligence to LLM agents",
   "license": "MIT",
   "repository": {
@@ -32,8 +32,8 @@
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.29.0",
-    "@urbicon-ui/design-content": "6.3.1",
-    "@urbicon-ui/design-engine": "6.3.1",
+    "@urbicon-ui/design-content": "6.3.3",
+    "@urbicon-ui/design-engine": "6.3.3",
     "zod": "^4.3.6"
   },
   "devDependencies": {

package/src/tools/find-components.ts

@@ -2,7 +2,7 @@ import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { matchComponents } from '@urbicon-ui/design-engine/search';
 import { z } from 'zod';
 import { loadCatalog } from '../data/catalog-loader.js';
-import { formatCompactCatalog } from '../utils/format-catalog.js';
+import { formatCompactCatalog, formatComponentLine } from '../utils/format-catalog.js';
 
 export function registerFindComponentsTool(server: McpServer): void {
   server.tool(
@@ -43,20 +43,11 @@ export function registerFindComponentsTool(server: McpServer): void {
         let md = `# Search Results for "${query}"\n\n`;
         md += `> ${results.length} matching components.\n\n`;
 
+        // Same line format as the browse view — including the origin-package tag for
+        // non-blocks components, so a match like `Table` (from @urbicon-ui/table) is
+        // never mistaken for a blocks export.
         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 += formatComponentLine(comp);
         }
 
         md += '\n> Use `get_component` with the component slug for full API docs.\n';

package/src/tools/get-css-reference.test.ts

@@ -0,0 +1,77 @@
+import { existsSync, readFileSync } from 'node:fs';
+import { dirname, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { describe, expect, it } from 'vitest';
+import { OVERVIEW, SECTIONS } from './get-css-reference.js';
+
+/**
+ * Drift guard for the hand-maintained CSS token reference.
+ *
+ * `get_css_reference` inlines its token tables as TS strings — the MCP server
+ * ships standalone (no blocks CSS at runtime), the same constraint that keeps
+ * design-engine's `VALID_TOKEN_CORES` inline. The hazard of any hand-copied list
+ * is silent drift: `--color-border-hairline` was added to the CSS and went
+ * unmirrored here for a while. When the blocks CSS is present (i.e. running
+ * in-repo) we re-derive the semantic surface / text / border token cores and
+ * assert each is documented, so a newly added token can no longer disappear.
+ *
+ * Scope: the three families `get_css_reference` enumerates exhaustively (one row
+ * per token). It deliberately does NOT require every intent scale step
+ * (`primary-50 … primary-950`, documented via shorthand), feedback/interactive,
+ * chart, or internal-only token (e.g. `skeleton-shimmer`, used by the Skeleton
+ * wave, never a consumer utility) to be spelled out. Whole-set token validity is
+ * already guarded by design-engine's `tokens.test.ts`.
+ */
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const semantic = resolve(
+  __dirname,
+  '..',
+  '..',
+  '..',
+  'blocks',
+  'src',
+  'lib',
+  'style',
+  'semantic.css'
+);
+const cssAvailable = existsSync(semantic);
+
+const ALL_CONTENT = [OVERVIEW, ...Object.values(SECTIONS)].join('\n');
+
+/** Families `get_css_reference` tables exhaustively, with the prose count to verify. */
+const TABLED_FAMILIES = [
+  { family: 'surface', section: SECTIONS.surfaces! },
+  { family: 'text', section: SECTIONS.text! },
+  { family: 'border', section: SECTIONS.borders! }
+] as const;
+
+/** Unique semantic `--color-<family>-*` cores in the CSS (scoped re-declarations collapse). */
+function deriveSemanticCores(family: string): string[] {
+  const css = readFileSync(semantic, 'utf-8');
+  const re = new RegExp(`--color-(${family}-[a-z-]+)\\s*:`, 'g');
+  const cores = new Set<string>();
+  for (const m of css.matchAll(re)) cores.add(m[1]!);
+  return [...cores].sort();
+}
+
+describe.skipIf(!cssAvailable)('get_css_reference token drift guard', () => {
+  for (const { family } of TABLED_FAMILIES) {
+    it(`documents every semantic \`${family}-*\` token defined in the CSS`, () => {
+      const missing = deriveSemanticCores(family).filter((c) => !ALL_CONTENT.includes(c));
+      expect(
+        missing,
+        `Semantic ${family} tokens in the CSS but absent from get_css_reference: ${missing.join(', ')}`
+      ).toEqual([]);
+    });
+  }
+
+  for (const { family, section } of TABLED_FAMILIES) {
+    it(`states the correct ${family}-token count`, () => {
+      const stated = Number(section.match(/(\d+)\s+tokens for/)?.[1]);
+      expect(stated, 'prose count drifted from the real token count').toBe(
+        deriveSemanticCores(family).length
+      );
+    });
+  }
+});

package/src/tools/get-css-reference.ts

@@ -1,7 +1,7 @@
 import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { z } from 'zod';
 
-const OVERVIEW = `# Urbicon UI — CSS Design Tokens
+export const OVERVIEW = `# Urbicon UI — CSS Design Tokens
 
 ## Architecture
 Three CSS layers, imported in order:
@@ -49,7 +49,7 @@ The \`@theme\` block sets the Tailwind utility value. The \`:root\` rule overrid
 ## Available Sections
 → \`get_css_reference(section="surfaces")\` — 11 surface background tokens
 → \`get_css_reference(section="text")\` — 9 text color tokens
-→ \`get_css_reference(section="borders")\` — 4 border color tokens
+→ \`get_css_reference(section="borders")\` — 5 border color tokens
 → \`get_css_reference(section="intents")\` — 6 intent palettes (primary, success, danger, etc.)
 → \`get_css_reference(section="shadows")\` — 5 shadow tokens + z-index scale
 → \`get_css_reference(section="theming")\` — How to create custom themes, available presets
@@ -114,16 +114,18 @@ Light → Dark mapping:
 
 const BORDERS = `# Border Tokens
 
-4 tokens for border colors. All auto-switch in dark mode.
+5 tokens for border colors. All auto-switch in dark mode.
 
 | CSS Variable | Tailwind Utility | Purpose |
 |---|---|---|
+| \`--color-border-hairline\` | \`border-border-hairline\` | Faintest divider — translucent (alpha), not a neutral step |
 | \`--color-border-subtle\` | \`border-border-subtle\` | Gentle grouping |
 | \`--color-border-default\` | \`border-border-default\` | Standard borders |
 | \`--color-border-emphasis\` | \`border-border-emphasis\` | Emphasized borders |
 | \`--color-border-strong\` | \`border-border-strong\` | High-contrast borders |
 
 Light → Dark mapping:
+- \`border-hairline\`: black 8% → white 6% (translucent, blends onto any surface)
 - \`border-subtle\`: neutral-200 → neutral-700
 - \`border-default\`: neutral-300 → neutral-600
 - \`border-emphasis\`: neutral-400 → neutral-500
@@ -416,7 +418,7 @@ So the only requirement is to import \`index.css\` (your app owns the Tailwind i
 **Do NOT add manual \`@source\` directives, and do NOT import the \`foundation\`/\`semantic\`/\`interaction\` subfiles instead of \`index.css\`** — the subfiles omit the \`@source\` directives (and global classes), which is the usual cause of "responsive layouts break in production".
 `;
 
-const SECTIONS: Record<string, string> = {
+export const SECTIONS: Record<string, string> = {
   surfaces: SURFACES,
   text: TEXT,
   borders: BORDERS,

package/src/tools/get-recipe.ts

@@ -10,7 +10,7 @@ export function registerGetRecipeTool(server: McpServer): void {
       scenario: z
         .string()
         .describe(
-          'Recipe id: login, settings, dashboard, pricing, profile-card, data-table, command-palette'
+          'Recipe id — e.g. login, settings, dashboard, pricing, profile-card, onboarding-flow, wizard, notification-center, or an auth flow (auth-invitation-register, auth-passkey-login, auth-password-reset). Pass any unrecognised id to get the full, current list.'
         )
     },
     { readOnlyHint: true },

package/src/utils/format-catalog.ts

@@ -110,7 +110,7 @@ function isBooleanVariant(values: string[]): boolean {
   );
 }
 
-function formatComponentLine(comp: ComponentCatalogEntry): string {
+export function formatComponentLine(comp: ComponentCatalogEntry): string {
   const variants = comp.variants
     .filter((v) => !isBooleanVariant(v.values))
     .map((v) => `${v.name}: ${v.values.join('/')}`)