@urbicon-ui/mcp-server 6.1.4

package/src/utils/paths.ts

@@ -0,0 +1,78 @@
+import { dirname, normalize, resolve, sep } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const packageRoot = resolve(__dirname, '..', '..');
+
+export function getDataDir(): string {
+  return process.env.DATA_DIR ?? resolve(packageRoot, '..', '..', 'apps', 'docs', 'static');
+}
+
+export function getTemplateDir(): string {
+  return resolve(packageRoot, '..', 'docs-gen', 'templates');
+}
+
+export function getRecipeDir(): string {
+  return resolve(packageRoot, '..', '..', 'apps', 'docs', 'src', 'routes', 'recipes');
+}
+
+export function getDesignSystemDir(): string {
+  return process.env.DESIGN_SYSTEM_DIR ?? resolve(packageRoot, '..', '..', 'design-system');
+}
+
+/**
+ * Root of the *consumer* project (the app being built with Urbicon UI), used by
+ * the design-context tools. Unlike the loaders above — which read the library's
+ * own shipped data — these tools read/write the consumer's `design.manifest.md`
+ * and scan its source, so the default is the process cwd (the consumer's repo
+ * when the server is launched from their editor). Override with env vars.
+ */
+export function getProjectDir(): string {
+  return process.env.DESIGN_PROJECT_DIR ?? process.cwd();
+}
+
+export function getProjectManifestPath(): string {
+  return process.env.DESIGN_MANIFEST_PATH ?? resolve(getProjectDir(), 'design.manifest.md');
+}
+
+export function getProjectSourceDir(): string {
+  return process.env.DESIGN_SOURCE_DIR ?? resolve(getProjectDir(), 'src');
+}
+
+/**
+ * Containment check for a caller-supplied manifest path. The write tools accept
+ * an LLM-supplied `manifestPath`; restrict it to the project root so a model
+ * cannot be steered into writing `.md` files elsewhere. (The user-configured
+ * `DESIGN_MANIFEST_PATH` env default is trusted and not run through this.)
+ */
+export function isWithinProjectDir(targetPath: string): boolean {
+  const resolved = resolve(targetPath);
+  const projectDir = normalize(getProjectDir());
+  return resolved === projectDir || resolved.startsWith(projectDir + sep);
+}
+
+export function getTemplatePath(): string {
+  return resolve(getTemplateDir(), 'llms-full-template.md');
+}
+
+export function getCatalogPath(): string {
+  return resolve(getDataDir(), 'mcp', 'component-catalog.json');
+}
+
+/** Validate that a slug contains only safe characters (lowercase alphanumeric + hyphens). */
+const SAFE_SLUG = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
+
+export function getComponentLlmPath(group: string, slug: string): string {
+  if (!SAFE_SLUG.test(slug)) {
+    throw new Error(`Invalid component slug: "${slug}"`);
+  }
+
+  const resolved = resolve(getDataDir(), group, slug, 'llm.txt');
+  const dataDir = normalize(getDataDir());
+
+  if (!resolved.startsWith(dataDir)) {
+    throw new Error(`Path traversal blocked for slug: "${slug}"`);
+  }
+
+  return resolved;
+}

package/src/utils/search.test.ts

@@ -0,0 +1,141 @@
+import { describe, expect, it } from 'vitest';
+import type { ComponentCatalogEntry } from '../data/catalog-loader.js';
+import { matchComponents } from './search.js';
+
+function makeEntry(
+  overrides: Partial<ComponentCatalogEntry> & Pick<ComponentCatalogEntry, 'name' | 'slug'>
+): ComponentCatalogEntry {
+  return {
+    package: '@urbicon-ui/blocks',
+    group: 'primitives',
+    description: '',
+    tags: [],
+    import: `import { ${overrides.name} } from '@urbicon-ui/blocks';`,
+    llmTxtPath: '',
+    variants: [],
+    keyProps: [],
+    keyPropTypes: {},
+    slots: [],
+    hasExamples: false,
+    relatedComponents: [],
+    ...overrides
+  };
+}
+
+const Button = makeEntry({
+  name: 'Button',
+  slug: 'button',
+  description: 'Click to trigger an action',
+  tags: ['action'],
+  keyProps: ['intent', 'variant', 'size']
+});
+
+const Input = makeEntry({
+  name: 'Input',
+  slug: 'input',
+  description: 'Single-line text field',
+  tags: ['form'],
+  keyProps: ['value', 'error']
+});
+
+const Dialog = makeEntry({
+  name: 'Dialog',
+  slug: 'dialog',
+  description: 'Modal overlay container',
+  tags: ['overlay']
+});
+
+const catalog = [Button, Input, Dialog];
+
+describe('matchComponents', () => {
+  it('ranks an exact name match first', () => {
+    const results = matchComponents(catalog, 'button');
+    expect(results[0]?.name).toBe('Button');
+  });
+
+  it('matches by case-insensitive substring of the name', () => {
+    const results = matchComponents(catalog, 'Butt');
+    expect(results.some((r) => r.name === 'Button')).toBe(true);
+  });
+
+  it('fuzz-matches a single-character typo', () => {
+    const results = matchComponents(catalog, 'Buton'); // typo: missing "t"
+    expect(results[0]?.name).toBe('Button');
+  });
+
+  it('ignores matches that are too distant', () => {
+    const results = matchComponents(catalog, 'xyzzy');
+    expect(results).toEqual([]);
+  });
+
+  it('scores tag matches when the tag keyword is present in the query', () => {
+    const results = matchComponents(catalog, 'form');
+    expect(results[0]?.name).toBe('Input');
+  });
+
+  it('filters by the explicit tags argument', () => {
+    const results = matchComponents(catalog, 'container', ['overlay']);
+    expect(results.some((r) => r.name === 'Dialog')).toBe(true);
+  });
+
+  it('respects the limit', () => {
+    const many = Array.from({ length: 10 }, (_, i) =>
+      makeEntry({ name: `Button${i}`, slug: `button-${i}`, description: 'click' })
+    );
+    const results = matchComponents(many, 'button', undefined, 3);
+    expect(results).toHaveLength(3);
+  });
+
+  it('drops words shorter than two characters before matching', () => {
+    // "a" and "x" below are too short and should be filtered;
+    // only "button" remains and should drive the match.
+    const results = matchComponents(catalog, 'a x button');
+    expect(results[0]?.name).toBe('Button');
+  });
+
+  it('uses the prop-name match as a weak signal', () => {
+    const results = matchComponents(catalog, 'intent');
+    expect(results.some((r) => r.name === 'Button')).toBe(true);
+  });
+
+  it('returns an empty list when the query has no usable keywords', () => {
+    const results = matchComponents(catalog, ', , ');
+    expect(results).toEqual([]);
+  });
+});
+
+// Regression for the DateGrid/Planner discovery fix: planning-board queries
+// used to steer toward Calendar (a timed-event scheduler). With Planner in the
+// catalog they must land on Planner instead — driven purely by its catalog
+// description/tags/slug, no hardcoded keyword map.
+describe('matchComponents — Planner discovery', () => {
+  const Calendar = makeEntry({
+    name: 'Calendar',
+    slug: 'calendar',
+    description: 'Event display and date selection with month, week and day views.',
+    tags: ['display'],
+    relatedComponents: ['DatePicker']
+  });
+  const Planner = makeEntry({
+    name: 'Planner',
+    slug: 'planner',
+    description:
+      'Date-indexed planning board — a week, month or custom-range grid whose cells hold your domain content (meals, shifts, bookings, content slots) via a generic cell snippet.',
+    tags: ['display', 'layout'],
+    keyProps: ['items', 'getDate', 'view', 'cell'],
+    relatedComponents: ['Calendar', 'DatePicker']
+  });
+  const dateCatalog = [Calendar, Planner];
+
+  for (const query of ['planner', 'meal planner', 'weekly plan', 'shift schedule', 'week board']) {
+    it(`ranks Planner first for "${query}"`, () => {
+      const results = matchComponents(dateCatalog, query);
+      expect(results[0]?.name).toBe('Planner');
+    });
+  }
+
+  it('still ranks Calendar first for an event/appointment query', () => {
+    const results = matchComponents(dateCatalog, 'event calendar');
+    expect(results[0]?.name).toBe('Calendar');
+  });
+});

package/src/utils/search.ts

@@ -0,0 +1,106 @@
+import type { ComponentCatalogEntry } from '../data/catalog-loader.js';
+
+interface ScoredEntry {
+  entry: ComponentCatalogEntry;
+  score: number;
+}
+
+export function matchComponents(
+  components: ComponentCatalogEntry[],
+  query: string,
+  tags?: string[],
+  limit = 5
+): ComponentCatalogEntry[] {
+  const keywords = query
+    .toLowerCase()
+    .split(/[\s,\-_]+/)
+    .filter((w) => w.length > 1);
+
+  const scored: ScoredEntry[] = components.map((entry) => {
+    let score = 0;
+    const nameLower = entry.name.toLowerCase();
+    const slugLower = entry.slug.toLowerCase();
+    const descLower = entry.description.toLowerCase();
+
+    for (const kw of keywords) {
+      // Exact match
+      if (nameLower === kw || slugLower === kw) {
+        score += 10;
+      } else if (nameLower.includes(kw) || slugLower.includes(kw)) {
+        score += 7;
+      } else {
+        // Fuzzy match on name/slug (Levenshtein distance <= 2)
+        const nameDist = levenshtein(nameLower, kw);
+        const slugDist = levenshtein(slugLower, kw);
+        const minDist = Math.min(nameDist, slugDist);
+        if (minDist <= 1) {
+          score += 6;
+        } else if (minDist <= 2) {
+          score += 3;
+        }
+      }
+
+      // Tag match
+      if (entry.tags.some((t) => t.toLowerCase() === kw)) {
+        score += 5;
+      }
+
+      // Description match
+      if (descLower.includes(kw)) {
+        score += 3;
+      }
+
+      // Prop name match
+      if (entry.keyProps.some((p) => p.toLowerCase().includes(kw))) {
+        score += 1;
+      }
+    }
+
+    if (tags && tags.length > 0) {
+      const entryTags = entry.tags.map((t) => t.toLowerCase());
+      for (const tag of tags) {
+        if (entryTags.includes(tag.toLowerCase())) {
+          score += 5;
+        }
+      }
+    }
+
+    return { entry, score };
+  });
+
+  return scored
+    .filter((s) => s.score > 0)
+    .sort((a, b) => b.score - a.score)
+    .slice(0, limit)
+    .map((s) => s.entry);
+}
+
+function levenshtein(a: string, b: string): number {
+  if (a.length === 0) return b.length;
+  if (b.length === 0) return a.length;
+
+  // Early exit for large length differences
+  if (Math.abs(a.length - b.length) > 2) return 3;
+
+  const matrix: number[][] = [];
+
+  for (let i = 0; i <= a.length; i++) {
+    matrix[i] = [i];
+  }
+  for (let j = 0; j <= b.length; j++) {
+    matrix[0]![j] = j;
+  }
+
+  for (let i = 1; i <= a.length; i++) {
+    for (let j = 1; j <= b.length; j++) {
+      const cost = a[i - 1] === b[j - 1] ? 0 : 1;
+      matrix[i]![j] = Math.min(
+        matrix[i - 1]![j]! + 1,
+        matrix[i]![j - 1]! + 1,
+        matrix[i - 1]![j - 1]! + cost
+      );
+    }
+  }
+
+  return matrix[a.length]![b.length]!;
+}

package/tsconfig.json

@@ -0,0 +1,27 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "outDir": "./dist",
+    "rootDir": "./src",
+    "composite": true,
+    "declaration": true,
+    "declarationMap": true,
+    "sourceMap": true,
+    "strict": true,
+    "esModuleInterop": true,
+    "forceConsistentCasingInFileNames": true,
+    "isolatedModules": true,
+    "skipLibCheck": true,
+    "resolveJsonModule": true,
+    "verbatimModuleSyntax": true,
+    "noImplicitReturns": true,
+    "noFallthroughCasesInSwitch": true,
+    "noUncheckedIndexedAccess": true,
+    "types": ["node"],
+    "tsBuildInfoFile": "./dist/tsconfig.tsbuildinfo"
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "dist"]
+}

package/vitest.config.ts

@@ -0,0 +1,15 @@
+import { defineConfig } from 'vitest/config';
+
+export default defineConfig({
+  test: {
+    // zod@4's ESM layout needs to be inlined so vitest's vite-ssr runner
+    // resolves the named export correctly; otherwise `z.string` comes back
+    // as undefined inside the tool modules.
+    server: {
+      deps: {
+        inline: ['zod']
+      }
+    },
+    include: ['src/**/*.test.ts']
+  }
+});