@urbicon-ui/mcp-server 6.1.5 → 6.1.6

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

@@ -1,99 +0,0 @@
-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/sync-design-manifest.ts

@@ -1,92 +0,0 @@
-import { readFile, writeFile } from 'node:fs/promises';
-import { dirname } from 'node:path';
-import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
-import { z } from 'zod';
-import {
-  createManifestTemplate,
-  scanMarkers,
-  upsertUsagesSection
-} from '../design-manifest/index.js';
-import { getProjectManifestPath, getProjectSourceDir, isWithinProjectDir } from '../utils/paths.js';
-
-export function registerSyncDesignManifestTool(server: McpServer): void {
-  server.tool(
-    'sync_design_manifest',
-    'Scan the project source for `data-design-pattern="…"` markers and regenerate the Pattern Usages section of design.manifest.md. Run after adding, moving, or removing pattern-following pages so the usage index stays accurate — this is what makes a pattern change tractable (grep the markers → migrate every listed file). Creates the manifest if missing.',
-    {
-      sourceDir: z
-        .string()
-        .optional()
-        .describe('Directory to scan recursively. Defaults to ./src in the project root.'),
-      manifestPath: z
-        .string()
-        .optional()
-        .describe('Path to design.manifest.md. Defaults to the project root.')
-    },
-    { readOnlyHint: false },
-    async ({ sourceDir, 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
-        };
-      }
-      const src = sourceDir ?? getProjectSourceDir();
-
-      // Files in the manifest are relative to the project root (the manifest's directory).
-      const usages = await scanMarkers(src, dirname(path));
-
-      let content: string;
-      let created = false;
-      try {
-        content = await readFile(path, 'utf-8');
-      } catch {
-        content = createManifestTemplate({});
-        created = true;
-      }
-
-      const updated = upsertUsagesSection(content, usages);
-      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 byPattern = new Map<string, number>();
-      for (const u of usages) byPattern.set(u.pattern, (byPattern.get(u.pattern) ?? 0) + 1);
-
-      let text = `Synced \`${path}\`${created ? ' (created it)' : ''} — scanned \`${src}\`, found ${usages.length} marker(s)`;
-      if (byPattern.size > 0) {
-        const summary = [...byPattern]
-          .sort((a, b) => a[0].localeCompare(b[0]))
-          .map(([p, n]) => `${p} (${n})`)
-          .join(', ');
-        text += ` across ${byPattern.size} pattern(s): ${summary}.`;
-      } else {
-        text +=
-          '. No markers yet — add `data-design-pattern="<name>"` to the root element of pages that follow a composition pattern.';
-      }
-
-      return { content: [{ type: 'text' as const, text }] };
-    }
-  );
-}

package/src/utils/paths.test.ts

@@ -1,101 +0,0 @@
-import { afterEach, beforeEach, describe, expect, it } from 'vitest';
-import {
-  getCatalogPath,
-  getComponentLlmPath,
-  getDataDir,
-  getRecipeDir,
-  getTemplateDir,
-  getTemplatePath,
-  isWithinProjectDir
-} from './paths.js';
-
-describe('paths', () => {
-  const originalDataDir = process.env.DATA_DIR;
-
-  afterEach(() => {
-    if (originalDataDir === undefined) {
-      delete process.env.DATA_DIR;
-    } else {
-      process.env.DATA_DIR = originalDataDir;
-    }
-  });
-
-  describe('isWithinProjectDir', () => {
-    const original = process.env.DESIGN_PROJECT_DIR;
-    beforeEach(() => {
-      process.env.DESIGN_PROJECT_DIR = '/home/user/app';
-    });
-    afterEach(() => {
-      if (original === undefined) delete process.env.DESIGN_PROJECT_DIR;
-      else process.env.DESIGN_PROJECT_DIR = original;
-    });
-
-    it('accepts paths inside the project root', () => {
-      expect(isWithinProjectDir('/home/user/app/design.manifest.md')).toBe(true);
-      expect(isWithinProjectDir('/home/user/app/docs/design.manifest.md')).toBe(true);
-    });
-    it('rejects paths outside the project root', () => {
-      expect(isWithinProjectDir('/etc/motd.md')).toBe(false);
-      expect(isWithinProjectDir('/home/user/app/../other/x.md')).toBe(false);
-      expect(isWithinProjectDir('/home/user/application/x.md')).toBe(false); // prefix-but-not-child
-    });
-  });
-
-  describe('getDataDir', () => {
-    beforeEach(() => {
-      delete process.env.DATA_DIR;
-    });
-
-    it('defaults to apps/docs/static relative to the package', () => {
-      const dir = getDataDir();
-      expect(dir.endsWith('/apps/docs/static')).toBe(true);
-    });
-
-    it('honours DATA_DIR env override', () => {
-      process.env.DATA_DIR = '/custom/data/dir';
-      expect(getDataDir()).toBe('/custom/data/dir');
-    });
-  });
-
-  describe('getTemplateDir / getRecipeDir / getTemplatePath / getCatalogPath', () => {
-    it('returns absolute paths rooted in the monorepo', () => {
-      expect(getTemplateDir()).toMatch(/\/packages\/docs-gen\/templates$/);
-      expect(getRecipeDir()).toMatch(/\/apps\/docs\/src\/routes\/recipes$/);
-      expect(getTemplatePath()).toMatch(/\/packages\/docs-gen\/templates\/llms-full-template\.md$/);
-      expect(getCatalogPath()).toMatch(/\/mcp\/component-catalog\.json$/);
-    });
-  });
-
-  describe('getComponentLlmPath', () => {
-    it('resolves a valid slug to a path inside the data dir', () => {
-      const p = getComponentLlmPath('primitives', 'button');
-      expect(p).toMatch(/\/primitives\/button\/llm\.txt$/);
-    });
-
-    it('accepts multi-word hyphenated slugs', () => {
-      const p = getComponentLlmPath('components', 'date-picker');
-      expect(p).toMatch(/\/components\/date-picker\/llm\.txt$/);
-    });
-
-    it('rejects uppercase in the slug', () => {
-      expect(() => getComponentLlmPath('primitives', 'Button')).toThrow(/Invalid component slug/);
-    });
-
-    it('rejects whitespace', () => {
-      expect(() => getComponentLlmPath('primitives', 'bad slug')).toThrow(/Invalid component slug/);
-    });
-
-    it('rejects leading or trailing hyphens', () => {
-      expect(() => getComponentLlmPath('primitives', '-bad')).toThrow(/Invalid component slug/);
-      expect(() => getComponentLlmPath('primitives', 'bad-')).toThrow(/Invalid component slug/);
-    });
-
-    it('rejects path traversal attempts', () => {
-      // Any dotted segment fails the SAFE_SLUG regex first.
-      expect(() => getComponentLlmPath('primitives', '..')).toThrow(/Invalid component slug/);
-      expect(() => getComponentLlmPath('primitives', '../../../etc/passwd')).toThrow(
-        /Invalid component slug/
-      );
-    });
-  });
-});

package/src/utils/paths.ts

@@ -1,78 +0,0 @@
-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

@@ -1,141 +0,0 @@
-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

@@ -1,106 +0,0 @@
-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]!;
-}