untitledui-mcp 0.1.0 → 0.1.3

package/README.md

@@ -74,7 +74,8 @@ Your AI gets these tools:
 | `list_components` | Browse a category |
 | `get_component_with_deps` | Fetch component + all dependencies |
 | `get_component` | Fetch component only |
-| `get_example` | Get complete page template |
+| `list_examples` | Browse available page templates |
+| `get_example` | Fetch a specific page template |
 
 ### Example: Add a modal
 
@@ -95,13 +96,22 @@ AI calls list_components { type: "application", subfolder: "sidebars" }
 → Returns all sidebar options for you to choose from
 ```
 
-### Example: Start from template
+### Example: Start from a page template
 
 ```
-You: "Set up a dashboard layout"
+You: "Show me available dashboard templates"
 
-AI calls get_example { name: "application" }
-→ Returns complete dashboard with sidebar, header, and sample pages
+AI calls list_examples { path: "" }
+→ Returns: application, marketing
+
+AI calls list_examples { path: "application" }
+→ Returns: dashboards-01, dashboards-02, settings-01, ...
+
+AI calls list_examples { path: "application/dashboards-01" }
+→ Returns: 01, 02, 03, ... (individual pages)
+
+AI calls get_example { path: "application/dashboards-01/01" }
+→ Returns complete page with 27 files, all dependencies
 ```
 
 ## Response Format

package/dist/index.js

@@ -126,17 +126,60 @@ var UntitledUIClient = class {
     }
     return data.components;
   }
-  async fetchExample(name) {
+  /**
+   * Browse examples hierarchy or fetch example content.
+   * - "" → lists types (application, marketing)
+   * - "application" → lists examples (dashboards-01, settings-01, etc.)
+   * - "application/dashboards-01" → lists pages (01, 02, 03, ...)
+   * - "application/dashboards-01/01" → returns actual content
+   */
+  async fetchExample(path2) {
     const response = await fetch(ENDPOINTS.fetchExample, {
       method: "POST",
       headers: { "Content-Type": "application/json" },
       body: JSON.stringify({
-        example: name,
+        example: path2,
         key: this.licenseKey
       })
     });
     return response.json();
   }
+  /**
+   * Fetch all pages in an example and combine them.
+   * Path should be "application/dashboards-01" (without page number).
+   */
+  async fetchFullExample(examplePath) {
+    const listing = await this.fetchExample(examplePath);
+    if (listing.type !== "directory" || !listing.results) {
+      throw new Error(`Invalid example path: ${examplePath}. Expected a directory with pages.`);
+    }
+    const pages = listing.results;
+    const allDeps = /* @__PURE__ */ new Set();
+    const allDevDeps = /* @__PURE__ */ new Set();
+    const fetchedPages = [];
+    for (const page of pages) {
+      const pageData = await this.fetchExample(`${examplePath}/${page}`);
+      if (pageData.type === "json-file" && pageData.content) {
+        const content = pageData.content;
+        fetchedPages.push({
+          page,
+          files: content.files || [],
+          dependencies: content.dependencies || [],
+          devDependencies: content.devDependencies || []
+        });
+        content.dependencies?.forEach((d) => allDeps.add(d));
+        content.devDependencies?.forEach((d) => allDevDeps.add(d));
+      }
+    }
+    const totalFiles = fetchedPages.reduce((sum, p) => sum + p.files.length, 0);
+    return {
+      name: examplePath,
+      pages: fetchedPages,
+      allDependencies: Array.from(allDeps),
+      allDevDependencies: Array.from(allDevDeps),
+      totalFiles
+    };
+  }
 };
 
 // src/cache/memory-cache.ts
@@ -289,6 +332,52 @@ function generateDescription(name, type) {
   return `UI component: ${name.replace(/-/g, " ")}`;
 }
 
+// src/utils/parse-deps.ts
+function parseComponentImports(files) {
+  const imports = /* @__PURE__ */ new Set();
+  const regex = /@\/components\/(base|application|foundations|shared-assets)\/([^"']+)/g;
+  for (const file of files) {
+    const code = file.content || file.code || "";
+    let match;
+    while ((match = regex.exec(code)) !== null) {
+      imports.add(match[0]);
+    }
+  }
+  const parsed = [];
+  for (const imp of imports) {
+    const match = imp.match(/@\/components\/(base|application|foundations|shared-assets)\/(.+)/);
+    if (match) {
+      parsed.push({
+        type: match[1],
+        path: match[2],
+        fullImport: imp
+      });
+    }
+  }
+  return parsed;
+}
+function extractBaseComponentPaths(files) {
+  const deps = parseComponentImports(files);
+  const basePaths = /* @__PURE__ */ new Set();
+  for (const dep of deps) {
+    if (dep.type === "base") {
+      basePaths.add(dep.path);
+    }
+  }
+  return Array.from(basePaths);
+}
+function getBaseComponentNames(files) {
+  const paths = extractBaseComponentPaths(files);
+  const names = /* @__PURE__ */ new Set();
+  for (const path2 of paths) {
+    const parts = path2.split("/");
+    if (parts.length >= 1) {
+      names.add(parts[0]);
+    }
+  }
+  return Array.from(names);
+}
+
 // src/server.ts
 function createServer(licenseKey) {
   const client = new UntitledUIClient(licenseKey);
@@ -390,18 +479,23 @@ function createServer(licenseKey) {
       },
       {
         name: "list_examples",
-        description: "List available page examples (dashboards, marketing pages, etc.)",
-        inputSchema: { type: "object", properties: {} }
+        description: "Browse available page examples. Call without path to see categories, then drill down.",
+        inputSchema: {
+          type: "object",
+          properties: {
+            path: { type: "string", description: "Path to browse (e.g., '', 'application', 'application/dashboards-01')" }
+          }
+        }
       },
       {
         name: "get_example",
-        description: "Get a complete page example with all files",
+        description: "Get a single example page with all files. Requires full path including page number.",
         inputSchema: {
           type: "object",
           properties: {
-            name: { type: "string", description: "Example name (e.g., 'application', 'marketing')" }
+            path: { type: "string", description: "Full path to example page (e.g., 'application/dashboards-01/01')" }
           },
-          required: ["name"]
+          required: ["path"]
         }
       },
       {
@@ -477,7 +571,7 @@ function createServer(licenseKey) {
               files: fetched.files,
               dependencies: fetched.dependencies || [],
               devDependencies: fetched.devDependencies || [],
-              baseComponents: (fetched.components || []).map((c) => c.name)
+              baseComponents: getBaseComponentNames(fetched.files)
             };
             cache.set(cacheKey, component, CACHE_TTL.componentCode);
           }
@@ -500,7 +594,7 @@ function createServer(licenseKey) {
               }]
             };
           }
-          const baseComponentNames = (primary.components || []).map((c) => c.name);
+          const baseComponentNames = getBaseComponentNames(primary.files);
           const baseComponents = baseComponentNames.length > 0 ? await client.fetchComponents("base", baseComponentNames) : [];
           const allDeps = /* @__PURE__ */ new Set();
           const allDevDeps = /* @__PURE__ */ new Set();
@@ -533,28 +627,69 @@ function createServer(licenseKey) {
           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)
-            }]
-          };
+          const { path: path2 = "" } = args;
+          const cacheKey = `examples:list:${path2}`;
+          let listing = cache.get(cacheKey);
+          if (!listing) {
+            listing = await client.fetchExample(path2);
+            if (listing) {
+              cache.set(cacheKey, listing, CACHE_TTL.componentList);
+            }
+          }
+          if (listing.type === "directory" && listing.results) {
+            return {
+              content: [{
+                type: "text",
+                text: JSON.stringify({
+                  path: path2 || "(root)",
+                  type: "directory",
+                  items: listing.results,
+                  hint: path2 === "" ? "Use list_examples with path='application' or path='marketing' to see available examples" : path2.split("/").length === 1 ? `Use list_examples with path='${path2}/<example>' to see pages` : `Use get_example with path='${path2}/<page>' to fetch a specific page`
+                }, null, 2)
+              }]
+            };
+          }
+          return { content: [{ type: "text", text: JSON.stringify(listing, null, 2) }] };
         }
         case "get_example": {
-          const { name: exampleName } = args;
-          const cacheKey = `example:${exampleName}`;
+          const { path: examplePath } = args;
+          const cacheKey = `example:${examplePath}`;
           let example = cache.get(cacheKey);
           if (!example) {
-            example = await client.fetchExample(exampleName);
+            example = await client.fetchExample(examplePath);
             if (example) {
               cache.set(cacheKey, example, CACHE_TTL.examples);
             }
           }
+          if (example.type === "directory") {
+            return {
+              content: [{
+                type: "text",
+                text: JSON.stringify({
+                  error: "Path is a directory, not a page",
+                  path: examplePath,
+                  availableItems: example.results,
+                  hint: `Use get_example with path='${examplePath}/<item>' to fetch a specific page`
+                }, null, 2)
+              }]
+            };
+          }
+          if (example.type === "json-file" && example.content) {
+            return {
+              content: [{
+                type: "text",
+                text: JSON.stringify({
+                  path: examplePath,
+                  name: example.content.name,
+                  files: example.content.files,
+                  dependencies: example.content.dependencies || [],
+                  devDependencies: example.content.devDependencies || [],
+                  components: example.content.components || [],
+                  fileCount: example.content.files?.length || 0
+                }, null, 2)
+              }]
+            };
+          }
           return { content: [{ type: "text", text: JSON.stringify(example, null, 2) }] };
         }
         case "validate_license": {

package/package.json

@@ -1,12 +1,15 @@
 {
   "name": "untitledui-mcp",
-  "version": "0.1.0",
+  "version": "0.1.3",
   "description": "MCP server for UntitledUI Pro components - browse, search, and retrieve UI components via Claude Code",
   "type": "module",
   "main": "dist/index.js",
   "bin": {
     "untitledui-mcp": "dist/index.js"
   },
+  "files": [
+    "dist"
+  ],
   "repository": {
     "type": "git",
     "url": "https://github.com/sbilde/untitledui-mcp"

package/.env.example

@@ -1 +0,0 @@
-UNTITLEDUI_LICENSE_KEY=your_license_key_here

package/src/api/client.test.ts

@@ -1,46 +0,0 @@
-import { describe, it, expect, vi, beforeEach } from "vitest";
-import { UntitledUIClient } from "./client.js";
-
-describe("UntitledUIClient", () => {
-  describe("validateLicense", () => {
-    it("should return true for valid license", async () => {
-      const client = new UntitledUIClient("valid-key");
-
-      global.fetch = vi.fn().mockResolvedValue({
-        status: 200,
-        ok: true,
-      });
-
-      const result = await client.validateLicense();
-      expect(result).toBe(true);
-    });
-
-    it("should return false for invalid license", async () => {
-      const client = new UntitledUIClient("invalid-key");
-
-      global.fetch = vi.fn().mockResolvedValue({
-        status: 401,
-        ok: false,
-      });
-
-      const result = await client.validateLicense();
-      expect(result).toBe(false);
-    });
-  });
-
-  describe("listComponentTypes", () => {
-    it("should return array of types", async () => {
-      const client = new UntitledUIClient("valid-key");
-
-      global.fetch = vi.fn().mockResolvedValue({
-        ok: true,
-        json: () => Promise.resolve({
-          types: ["application", "base", "foundations"]
-        }),
-      });
-
-      const result = await client.listComponentTypes();
-      expect(result).toEqual(["application", "base", "foundations"]);
-    });
-  });
-});

package/src/api/client.ts

@@ -1,117 +0,0 @@
-import { ENDPOINTS } from "./endpoints.js";
-import type {
-  ComponentListItem,
-  ComponentListResponse,
-  ComponentsResponse,
-  ExampleResponse,
-  FetchedComponent,
-} from "./types.js";
-
-export class UntitledUIClient {
-  constructor(private licenseKey: string) {}
-
-  async validateLicense(): Promise<boolean> {
-    try {
-      const response = await fetch(ENDPOINTS.validateKey(this.licenseKey));
-      return response.status === 200;
-    } catch {
-      return false;
-    }
-  }
-
-  async listComponentTypes(): Promise<string[]> {
-    const response = await fetch(ENDPOINTS.listTypes(this.licenseKey));
-    if (!response.ok) {
-      throw new Error(`API error: ${response.status}`);
-    }
-    const data = await response.json();
-    return data.types;
-  }
-
-  async listComponents(type: string, subfolder?: string): Promise<ComponentListItem[]> {
-    let url: string;
-    if (subfolder) {
-      url = ENDPOINTS.listSubfolder(this.licenseKey, type, [subfolder]);
-    } else {
-      url = ENDPOINTS.listComponents(this.licenseKey, type);
-    }
-
-    const response = await fetch(url);
-    if (!response.ok) {
-      throw new Error(`API error: ${response.status}`);
-    }
-
-    const data: ComponentListResponse = await response.json();
-
-    // Handle subfolder response format
-    if (subfolder && Array.isArray(data.components)) {
-      const subfolderData = data.components[0];
-      if (subfolderData && typeof subfolderData === "object" && subfolder in subfolderData) {
-        return (subfolderData as Record<string, ComponentListItem[]>)[subfolder];
-      }
-    }
-
-    return data.components as ComponentListItem[];
-  }
-
-  async fetchComponent(type: string, name: string): Promise<FetchedComponent | null> {
-    const response = await fetch(ENDPOINTS.fetchComponents, {
-      method: "POST",
-      headers: { "Content-Type": "application/json" },
-      body: JSON.stringify({
-        type,
-        components: [name],
-        key: this.licenseKey,
-      }),
-    });
-
-    if (!response.ok) {
-      throw new Error(`API error: ${response.status}`);
-    }
-
-    const data: ComponentsResponse = await response.json();
-
-    if (data.pro && data.pro.length > 0) {
-      throw new Error(`PRO access required for: ${data.pro.join(", ")}`);
-    }
-
-    return data.components[0] || null;
-  }
-
-  async fetchComponents(type: string, names: string[]): Promise<FetchedComponent[]> {
-    const response = await fetch(ENDPOINTS.fetchComponents, {
-      method: "POST",
-      headers: { "Content-Type": "application/json" },
-      body: JSON.stringify({
-        type,
-        components: names,
-        key: this.licenseKey,
-      }),
-    });
-
-    if (!response.ok) {
-      throw new Error(`API error: ${response.status}`);
-    }
-
-    const data: ComponentsResponse = await response.json();
-
-    if (data.pro && data.pro.length > 0) {
-      throw new Error(`PRO access required for: ${data.pro.join(", ")}`);
-    }
-
-    return data.components;
-  }
-
-  async fetchExample(name: string): Promise<ExampleResponse> {
-    const response = await fetch(ENDPOINTS.fetchExample, {
-      method: "POST",
-      headers: { "Content-Type": "application/json" },
-      body: JSON.stringify({
-        example: name,
-        key: this.licenseKey,
-      }),
-    });
-
-    return response.json();
-  }
-}

package/src/api/endpoints.ts

@@ -1,12 +0,0 @@
-export const API_BASE = "https://www.untitledui.com/react/api";
-
-export const ENDPOINTS = {
-  validateKey: (key: string) => `${API_BASE}/validate-key?key=${key}`,
-  listTypes: (key: string) => `${API_BASE}/components/list?key=${key}`,
-  listComponents: (key: string, type: string) =>
-    `${API_BASE}/components/list?key=${key}&type=${type}`,
-  listSubfolder: (key: string, type: string, subfolders: string[]) =>
-    `${API_BASE}/components/list?key=${key}&type=${type}&subfolders=${subfolders.join(",")}`,
-  fetchComponents: `${API_BASE}/components`,
-  fetchExample: `${API_BASE}/components/example`,
-} as const;

package/src/api/types.ts

@@ -1,84 +0,0 @@
-// UntitledUI API Response Types
-
-export interface ComponentType {
-  types: string[];
-}
-
-export interface ComponentListItem {
-  name: string;
-  type: "file" | "dir";
-  count?: number;
-}
-
-export interface ComponentListResponse {
-  components: ComponentListItem[] | ComponentListWithSubfolder[];
-}
-
-export interface ComponentListWithSubfolder {
-  [subfolder: string]: ComponentListItem[];
-}
-
-export interface ComponentFile {
-  path: string;
-  code: string;
-}
-
-export interface FetchedComponent {
-  name: string;
-  files: ComponentFile[];
-  dependencies?: string[];
-  devDependencies?: string[];
-  components?: BaseComponentRef[];
-}
-
-export interface BaseComponentRef {
-  name: string;
-  path: string;
-}
-
-export interface ComponentsResponse {
-  components: FetchedComponent[];
-  pro?: string[];
-}
-
-export interface ExampleResponse {
-  type: "json-file" | "directory" | "json-files" | "error";
-  content?: ExampleContent;
-  results?: string[];
-  status?: number;
-  message?: string;
-}
-
-export interface ExampleContent {
-  name: string;
-  files: ComponentFile[];
-  dependencies?: string[];
-  devDependencies?: string[];
-  components?: BaseComponentRef[];
-}
-
-// MCP Tool Response Types
-
-export interface MCPComponentResponse {
-  name: string;
-  type: string;
-  description: string;
-  files: ComponentFile[];
-  dependencies: string[];
-  devDependencies: string[];
-  baseComponents: string[];
-}
-
-export interface MCPSearchResult {
-  name: string;
-  type: string;
-  fullPath: string;
-  matchType: "exact" | "partial";
-  score: number;
-}
-
-export interface MCPErrorResponse {
-  error: string;
-  code: "INVALID_LICENSE" | "NOT_FOUND" | "API_ERROR" | "NETWORK_ERROR";
-  suggestions?: string[];
-}

package/src/cache/memory-cache.test.ts

@@ -1,56 +0,0 @@
-import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
-import { MemoryCache } from "./memory-cache.js";
-
-describe("MemoryCache", () => {
-  beforeEach(() => {
-    vi.useFakeTimers();
-  });
-
-  afterEach(() => {
-    vi.useRealTimers();
-  });
-
-  it("should store and retrieve values", () => {
-    const cache = new MemoryCache();
-    cache.set("key1", "value1", 60);
-    expect(cache.get("key1")).toBe("value1");
-  });
-
-  it("should return undefined for missing keys", () => {
-    const cache = new MemoryCache();
-    expect(cache.get("missing")).toBeUndefined();
-  });
-
-  it("should expire entries after TTL", () => {
-    const cache = new MemoryCache();
-    cache.set("key1", "value1", 60);
-
-    vi.advanceTimersByTime(61 * 1000);
-
-    expect(cache.get("key1")).toBeUndefined();
-  });
-
-  it("should clear all entries", () => {
-    const cache = new MemoryCache();
-    cache.set("key1", "value1", 60);
-    cache.set("key2", "value2", 60);
-
-    cache.clear();
-
-    expect(cache.get("key1")).toBeUndefined();
-    expect(cache.get("key2")).toBeUndefined();
-  });
-
-  it("should clear entries matching pattern", () => {
-    const cache = new MemoryCache();
-    cache.set("component:button", "data1", 60);
-    cache.set("component:input", "data2", 60);
-    cache.set("search:button", "data3", 60);
-
-    const cleared = cache.clearPattern("component:");
-
-    expect(cleared).toBe(2);
-    expect(cache.get("component:button")).toBeUndefined();
-    expect(cache.get("search:button")).toBe("data3");
-  });
-});

package/src/cache/memory-cache.ts

@@ -1,64 +0,0 @@
-interface CacheEntry<T> {
-  data: T;
-  expiresAt: number;
-}
-
-export class MemoryCache {
-  private cache = new Map<string, CacheEntry<unknown>>();
-
-  set<T>(key: string, data: T, ttlSeconds: number): void {
-    this.cache.set(key, {
-      data,
-      expiresAt: Date.now() + ttlSeconds * 1000,
-    });
-  }
-
-  get<T>(key: string): T | undefined {
-    const entry = this.cache.get(key);
-    if (!entry) return undefined;
-
-    if (Date.now() > entry.expiresAt) {
-      this.cache.delete(key);
-      return undefined;
-    }
-
-    return entry.data as T;
-  }
-
-  has(key: string): boolean {
-    return this.get(key) !== undefined;
-  }
-
-  clear(): void {
-    this.cache.clear();
-  }
-
-  clearPattern(pattern: string): number {
-    let cleared = 0;
-    for (const key of this.cache.keys()) {
-      if (key.startsWith(pattern)) {
-        this.cache.delete(key);
-        cleared++;
-      }
-    }
-    return cleared;
-  }
-
-  size(): number {
-    for (const [key, entry] of this.cache.entries()) {
-      if (Date.now() > entry.expiresAt) {
-        this.cache.delete(key);
-      }
-    }
-    return this.cache.size;
-  }
-}
-
-export const CACHE_TTL = {
-  componentTypes: 3600,
-  componentList: 3600,
-  componentCode: 86400,
-  searchResults: 1800,
-  examples: 86400,
-  licenseValidation: 300,
-} as const;