untitledui-mcp 0.1.0

package/src/server.ts

@@ -0,0 +1,374 @@
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import {
+  CallToolRequestSchema,
+  ListToolsRequestSchema,
+} from "@modelcontextprotocol/sdk/types.js";
+
+import { UntitledUIClient } from "./api/client.js";
+import { MemoryCache, CACHE_TTL } from "./cache/memory-cache.js";
+import { fuzzySearch, type SearchableItem } from "./utils/search.js";
+import { generateDescription } from "./utils/descriptions.js";
+import type { ComponentListItem, MCPComponentResponse } from "./api/types.js";
+
+export function createServer(licenseKey: string) {
+  const client = new UntitledUIClient(licenseKey);
+  const cache = new MemoryCache();
+
+  const server = new Server(
+    {
+      name: "untitledui-mcp",
+      version: "0.1.0",
+    },
+    {
+      capabilities: {
+        tools: {},
+      },
+    }
+  );
+
+  // Helper: Build searchable index
+  async function buildSearchIndex(): Promise<SearchableItem[]> {
+    const cacheKey = "search:index";
+    const cached = cache.get<SearchableItem[]>(cacheKey);
+    if (cached) return cached;
+
+    const items: SearchableItem[] = [];
+    const types = await client.listComponentTypes();
+
+    for (const type of types) {
+      const components = await client.listComponents(type);
+      for (const comp of components) {
+        if (comp.type === "dir" && comp.count) {
+          // Has variants - fetch them
+          const variants = await client.listComponents(type, comp.name);
+          for (const variant of variants) {
+            items.push({
+              name: variant.name,
+              type,
+              fullPath: `${type}/${comp.name}/${variant.name}`,
+            });
+          }
+        } else {
+          items.push({
+            name: comp.name,
+            type,
+            fullPath: `${type}/${comp.name}`,
+          });
+        }
+      }
+    }
+
+    cache.set(cacheKey, items, CACHE_TTL.componentList);
+    return items;
+  }
+
+  // List available tools
+  server.setRequestHandler(ListToolsRequestSchema, async () => ({
+    tools: [
+      {
+        name: "list_component_types",
+        description: "List all available component categories (application, base, marketing, etc.)",
+        inputSchema: { type: "object", properties: {} },
+      },
+      {
+        name: "list_components",
+        description: "List components in a category. Use subfolder for variants (e.g., type='application', subfolder='modals')",
+        inputSchema: {
+          type: "object",
+          properties: {
+            type: { type: "string", description: "Component type (application, base, foundations, marketing, shared-assets)" },
+            subfolder: { type: "string", description: "Optional subfolder for variants (e.g., 'modals', 'slideout-menus')" },
+          },
+          required: ["type"],
+        },
+      },
+      {
+        name: "search_components",
+        description: "Search for components by name across all categories",
+        inputSchema: {
+          type: "object",
+          properties: {
+            query: { type: "string", description: "Search query" },
+          },
+          required: ["query"],
+        },
+      },
+      {
+        name: "get_component",
+        description: "Get a single component's code. Does NOT include dependencies - use get_component_with_deps for that.",
+        inputSchema: {
+          type: "object",
+          properties: {
+            type: { type: "string", description: "Component type" },
+            name: { type: "string", description: "Component name (e.g., 'button' or 'modals/ai-assistant-modal')" },
+          },
+          required: ["type", "name"],
+        },
+      },
+      {
+        name: "get_component_with_deps",
+        description: "Get a component with all its base component dependencies included",
+        inputSchema: {
+          type: "object",
+          properties: {
+            type: { type: "string", description: "Component type" },
+            name: { type: "string", description: "Component name" },
+          },
+          required: ["type", "name"],
+        },
+      },
+      {
+        name: "list_examples",
+        description: "List available page examples (dashboards, marketing pages, etc.)",
+        inputSchema: { type: "object", properties: {} },
+      },
+      {
+        name: "get_example",
+        description: "Get a complete page example with all files",
+        inputSchema: {
+          type: "object",
+          properties: {
+            name: { type: "string", description: "Example name (e.g., 'application', 'marketing')" },
+          },
+          required: ["name"],
+        },
+      },
+      {
+        name: "validate_license",
+        description: "Verify that the license key is valid",
+        inputSchema: { type: "object", properties: {} },
+      },
+      {
+        name: "clear_cache",
+        description: "Clear cached data. Optionally specify a pattern to clear specific entries.",
+        inputSchema: {
+          type: "object",
+          properties: {
+            pattern: { type: "string", description: "Optional pattern to match (e.g., 'component:' clears all component cache)" },
+          },
+        },
+      },
+    ],
+  }));
+
+  // Handle tool calls
+  server.setRequestHandler(CallToolRequestSchema, async (request) => {
+    const { name, arguments: args } = request.params;
+
+    try {
+      switch (name) {
+        case "list_component_types": {
+          const cacheKey = "types";
+          let types = cache.get<string[]>(cacheKey);
+          if (!types) {
+            types = await client.listComponentTypes();
+            cache.set(cacheKey, types, CACHE_TTL.componentTypes);
+          }
+          return { content: [{ type: "text", text: JSON.stringify({ types }, null, 2) }] };
+        }
+
+        case "list_components": {
+          const { type, subfolder } = args as { type: string; subfolder?: string };
+          const cacheKey = subfolder ? `list:${type}:${subfolder}` : `list:${type}`;
+
+          let components = cache.get<ComponentListItem[]>(cacheKey);
+          if (!components) {
+            components = await client.listComponents(type, subfolder);
+            cache.set(cacheKey, components, CACHE_TTL.componentList);
+          }
+
+          return { content: [{ type: "text", text: JSON.stringify({ type, subfolder, components }, null, 2) }] };
+        }
+
+        case "search_components": {
+          const { query } = args as { query: string };
+          const index = await buildSearchIndex();
+          const results = fuzzySearch(query, index);
+          return { content: [{ type: "text", text: JSON.stringify({ query, results }, null, 2) }] };
+        }
+
+        case "get_component": {
+          const { type, name: componentName } = args as { type: string; name: string };
+          const cacheKey = `component:${type}:${componentName}`;
+
+          let component = cache.get<MCPComponentResponse>(cacheKey);
+          if (!component) {
+            const fetched = await client.fetchComponent(type, componentName);
+            if (!fetched) {
+              // Not found - suggest alternatives
+              const index = await buildSearchIndex();
+              const suggestions = fuzzySearch(componentName, index, 5).map(r => r.fullPath);
+              return {
+                content: [{
+                  type: "text",
+                  text: JSON.stringify({
+                    error: `Component "${componentName}" not found in ${type}`,
+                    code: "NOT_FOUND",
+                    suggestions,
+                  }, null, 2),
+                }],
+              };
+            }
+
+            component = {
+              name: fetched.name,
+              type,
+              description: generateDescription(fetched.name, type),
+              files: fetched.files,
+              dependencies: fetched.dependencies || [],
+              devDependencies: fetched.devDependencies || [],
+              baseComponents: (fetched.components || []).map(c => c.name),
+            };
+            cache.set(cacheKey, component, CACHE_TTL.componentCode);
+          }
+
+          return { content: [{ type: "text", text: JSON.stringify(component, null, 2) }] };
+        }
+
+        case "get_component_with_deps": {
+          const { type, name: componentName } = args as { type: string; name: string };
+
+          const primary = await client.fetchComponent(type, componentName);
+          if (!primary) {
+            const index = await buildSearchIndex();
+            const suggestions = fuzzySearch(componentName, index, 5).map(r => r.fullPath);
+            return {
+              content: [{
+                type: "text",
+                text: JSON.stringify({
+                  error: `Component "${componentName}" not found`,
+                  code: "NOT_FOUND",
+                  suggestions,
+                }, null, 2),
+              }],
+            };
+          }
+
+          // Fetch base components
+          const baseComponentNames = (primary.components || []).map(c => c.name);
+          const baseComponents = baseComponentNames.length > 0
+            ? await client.fetchComponents("base", baseComponentNames)
+            : [];
+
+          // Deduplicate dependencies
+          const allDeps = new Set<string>();
+          const allDevDeps = new Set<string>();
+
+          [primary, ...baseComponents].forEach(c => {
+            c.dependencies?.forEach(d => allDeps.add(d));
+            c.devDependencies?.forEach(d => allDevDeps.add(d));
+          });
+
+          const result = {
+            primary: {
+              name: primary.name,
+              type,
+              description: generateDescription(primary.name, type),
+              files: primary.files,
+              dependencies: primary.dependencies || [],
+              devDependencies: primary.devDependencies || [],
+              baseComponents: baseComponentNames,
+            },
+            baseComponents: baseComponents.map(c => ({
+              name: c.name,
+              type: "base",
+              description: generateDescription(c.name, "base"),
+              files: c.files,
+              dependencies: c.dependencies || [],
+              devDependencies: c.devDependencies || [],
+            })),
+            totalFiles: primary.files.length + baseComponents.reduce((sum, c) => sum + c.files.length, 0),
+            allDependencies: Array.from(allDeps),
+            allDevDependencies: Array.from(allDevDeps),
+          };
+
+          return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
+        }
+
+        case "list_examples": {
+          return {
+            content: [{
+              type: "text",
+              text: JSON.stringify({
+                examples: [
+                  { name: "application", type: "application", description: "Dashboard application example" },
+                  { name: "marketing", type: "marketing", description: "Marketing landing page example" },
+                ],
+              }, null, 2),
+            }],
+          };
+        }
+
+        case "get_example": {
+          const { name: exampleName } = args as { name: string };
+          const cacheKey = `example:${exampleName}`;
+
+          let example = cache.get(cacheKey);
+          if (!example) {
+            example = await client.fetchExample(exampleName);
+            if (example) {
+              cache.set(cacheKey, example, CACHE_TTL.examples);
+            }
+          }
+
+          return { content: [{ type: "text", text: JSON.stringify(example, null, 2) }] };
+        }
+
+        case "validate_license": {
+          const valid = await client.validateLicense();
+          return {
+            content: [{
+              type: "text",
+              text: JSON.stringify({
+                valid,
+                message: valid ? "License key is valid" : "Invalid or missing license key",
+              }, null, 2),
+            }],
+          };
+        }
+
+        case "clear_cache": {
+          const { pattern } = args as { pattern?: string };
+          let cleared: number;
+          if (pattern) {
+            cleared = cache.clearPattern(pattern);
+          } else {
+            cleared = cache.size();
+            cache.clear();
+          }
+          return {
+            content: [{
+              type: "text",
+              text: JSON.stringify({ cleared, message: `Cleared ${cleared} cache entries` }, null, 2),
+            }],
+          };
+        }
+
+        default:
+          return {
+            content: [{
+              type: "text",
+              text: JSON.stringify({ error: `Unknown tool: ${name}`, code: "UNKNOWN_TOOL" }, null, 2),
+            }],
+          };
+      }
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      return {
+        content: [{
+          type: "text",
+          text: JSON.stringify({ error: message, code: "API_ERROR" }, null, 2),
+        }],
+      };
+    }
+  });
+
+  return server;
+}
+
+export async function runServer(licenseKey: string) {
+  const server = createServer(licenseKey);
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+}

package/src/utils/descriptions.ts

@@ -0,0 +1,65 @@
+// Generated descriptions based on component name and type
+// Since UntitledUI API doesn't provide descriptions, we generate them
+
+const TYPE_DESCRIPTIONS: Record<string, string> = {
+  application: "Application UI component for dashboards and web apps",
+  base: "Core UI primitive component",
+  foundations: "Foundational element (icon, logo, visual)",
+  marketing: "Marketing section component for landing pages",
+  "shared-assets": "Shared visual asset (illustration, pattern, mockup)",
+  icons: "Icon component",
+};
+
+const NAME_PATTERNS: [RegExp, string][] = [
+  [/modal/i, "Modal dialog component"],
+  [/button/i, "Interactive button component"],
+  [/input/i, "Form input component"],
+  [/select/i, "Selection/dropdown component"],
+  [/table/i, "Data table component"],
+  [/calendar/i, "Calendar/date component"],
+  [/date-picker/i, "Date selection component"],
+  [/sidebar/i, "Sidebar navigation component"],
+  [/header/i, "Header/navigation component"],
+  [/footer/i, "Footer section component"],
+  [/card/i, "Card container component"],
+  [/avatar/i, "User avatar component"],
+  [/badge/i, "Badge/label component"],
+  [/alert/i, "Alert/notification component"],
+  [/toast/i, "Toast notification component"],
+  [/dropdown/i, "Dropdown menu component"],
+  [/tabs/i, "Tabbed interface component"],
+  [/pagination/i, "Pagination component"],
+  [/carousel/i, "Carousel/slider component"],
+  [/chart/i, "Chart/visualization component"],
+  [/metric/i, "Metrics/statistics component"],
+  [/form/i, "Form component"],
+  [/pricing/i, "Pricing section component"],
+  [/testimonial/i, "Testimonial section component"],
+  [/feature/i, "Features section component"],
+  [/cta/i, "Call-to-action section component"],
+  [/hero/i, "Hero section component"],
+  [/faq/i, "FAQ section component"],
+  [/blog/i, "Blog section component"],
+  [/team/i, "Team section component"],
+  [/contact/i, "Contact section component"],
+  [/login/i, "Login/authentication component"],
+  [/signup/i, "Signup/registration component"],
+];
+
+export function generateDescription(name: string, type: string): string {
+  // Check name patterns first
+  for (const [pattern, description] of NAME_PATTERNS) {
+    if (pattern.test(name)) {
+      return description;
+    }
+  }
+
+  // Fall back to type description
+  const typeDesc = TYPE_DESCRIPTIONS[type];
+  if (typeDesc) {
+    return `${typeDesc}: ${name.replace(/-/g, " ")}`;
+  }
+
+  // Generic fallback
+  return `UI component: ${name.replace(/-/g, " ")}`;
+}

package/src/utils/license.test.ts

@@ -0,0 +1,45 @@
+import { describe, it, expect, vi, beforeEach } from "vitest";
+import { resolveLicenseKey } from "./license.js";
+import * as fs from "fs";
+import * as os from "os";
+
+vi.mock("fs");
+vi.mock("os");
+
+describe("resolveLicenseKey", () => {
+  beforeEach(() => {
+    vi.resetAllMocks();
+    delete process.env.UNTITLEDUI_LICENSE_KEY;
+  });
+
+  it("should prefer CLI argument over env var", () => {
+    process.env.UNTITLEDUI_LICENSE_KEY = "env-key";
+    const result = resolveLicenseKey("cli-key");
+    expect(result).toBe("cli-key");
+  });
+
+  it("should use env var if no CLI argument", () => {
+    process.env.UNTITLEDUI_LICENSE_KEY = "env-key";
+    const result = resolveLicenseKey();
+    expect(result).toBe("env-key");
+  });
+
+  it("should read from config file if no env var", () => {
+    vi.mocked(os.homedir).mockReturnValue("/home/user");
+    vi.mocked(fs.existsSync).mockReturnValue(true);
+    vi.mocked(fs.readFileSync).mockReturnValue(
+      JSON.stringify({ license: "file-key" })
+    );
+
+    const result = resolveLicenseKey();
+    expect(result).toBe("file-key");
+  });
+
+  it("should return undefined if no key found", () => {
+    vi.mocked(os.homedir).mockReturnValue("/home/user");
+    vi.mocked(fs.existsSync).mockReturnValue(false);
+
+    const result = resolveLicenseKey();
+    expect(result).toBeUndefined();
+  });
+});

package/src/utils/license.ts

@@ -0,0 +1,35 @@
+import * as fs from "fs";
+import * as path from "path";
+import * as os from "os";
+
+function getConfigPath(): string {
+  return path.join(os.homedir(), ".untitledui", "config.json");
+}
+
+export function resolveLicenseKey(cliArg?: string): string | undefined {
+  // Priority 1: CLI argument
+  if (cliArg) {
+    return cliArg;
+  }
+
+  // Priority 2: Environment variable
+  const envKey = process.env.UNTITLEDUI_LICENSE_KEY;
+  if (envKey) {
+    return envKey;
+  }
+
+  // Priority 3: Config file (~/.untitledui/config.json)
+  try {
+    const configPath = getConfigPath();
+    if (fs.existsSync(configPath)) {
+      const config = JSON.parse(fs.readFileSync(configPath, "utf-8"));
+      if (config.license) {
+        return config.license;
+      }
+    }
+  } catch {
+    // Ignore file read errors
+  }
+
+  return undefined;
+}

package/src/utils/search.test.ts

@@ -0,0 +1,39 @@
+import { describe, it, expect } from "vitest";
+import { fuzzySearch, type SearchableItem } from "./search.js";
+
+describe("fuzzySearch", () => {
+  const items: SearchableItem[] = [
+    { name: "button", type: "base", fullPath: "base/button" },
+    { name: "date-picker", type: "application", fullPath: "application/date-picker" },
+    { name: "date-range-picker", type: "application", fullPath: "application/date-range-picker" },
+    { name: "ai-assistant-modal", type: "application", fullPath: "application/modals/ai-assistant-modal" },
+  ];
+
+  it("should find exact matches", () => {
+    const results = fuzzySearch("button", items);
+    expect(results[0].name).toBe("button");
+    expect(results[0].matchType).toBe("exact");
+  });
+
+  it("should find partial matches", () => {
+    const results = fuzzySearch("date", items);
+    expect(results.length).toBe(2);
+    expect(results.every(r => r.name.includes("date"))).toBe(true);
+  });
+
+  it("should rank exact matches higher", () => {
+    const results = fuzzySearch("date-picker", items);
+    expect(results[0].name).toBe("date-picker");
+    expect(results[0].matchType).toBe("exact");
+  });
+
+  it("should return empty array for no matches", () => {
+    const results = fuzzySearch("nonexistent", items);
+    expect(results).toEqual([]);
+  });
+
+  it("should limit results", () => {
+    const results = fuzzySearch("a", items, 2);
+    expect(results.length).toBeLessThanOrEqual(2);
+  });
+});

package/src/utils/search.ts

@@ -0,0 +1,71 @@
+export interface SearchableItem {
+  name: string;
+  type: string;
+  fullPath: string;
+}
+
+export interface SearchResult extends SearchableItem {
+  matchType: "exact" | "partial";
+  score: number;
+}
+
+export function fuzzySearch(
+  query: string,
+  items: SearchableItem[],
+  limit = 20
+): SearchResult[] {
+  const queryLower = query.toLowerCase();
+
+  const results: SearchResult[] = [];
+
+  for (const item of items) {
+    const nameLower = item.name.toLowerCase();
+    const fullPathLower = item.fullPath.toLowerCase();
+
+    let score = 0;
+    let matchType: "exact" | "partial" = "partial";
+
+    // Exact match on name
+    if (nameLower === queryLower) {
+      score = 1.0;
+      matchType = "exact";
+    }
+    // Name starts with query
+    else if (nameLower.startsWith(queryLower)) {
+      score = 0.9;
+    }
+    // Name contains query
+    else if (nameLower.includes(queryLower)) {
+      score = 0.7;
+    }
+    // Full path contains query
+    else if (fullPathLower.includes(queryLower)) {
+      score = 0.5;
+    }
+    // Fuzzy: all query chars appear in order
+    else {
+      let queryIndex = 0;
+      for (const char of nameLower) {
+        if (char === queryLower[queryIndex]) {
+          queryIndex++;
+        }
+        if (queryIndex === queryLower.length) {
+          score = 0.3;
+          break;
+        }
+      }
+    }
+
+    if (score > 0) {
+      results.push({
+        ...item,
+        matchType,
+        score,
+      });
+    }
+  }
+
+  return results
+    .sort((a, b) => b.score - a.score)
+    .slice(0, limit);
+}

package/tsconfig.json

@@ -0,0 +1,16 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "esModuleInterop": true,
+    "strict": true,
+    "skipLibCheck": true,
+    "outDir": "dist",
+    "rootDir": "src",
+    "declaration": true,
+    "resolveJsonModule": true
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "dist"]
+}