untitledui-mcp 0.1.0

package/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "untitledui-mcp",
+  "version": "0.1.0",
+  "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"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/sbilde/untitledui-mcp"
+  },
+  "homepage": "https://github.com/sbilde/untitledui-mcp#readme",
+  "bugs": {
+    "url": "https://github.com/sbilde/untitledui-mcp/issues"
+  },
+  "scripts": {
+    "build": "tsup src/index.ts --format esm --dts",
+    "dev": "tsup src/index.ts --format esm --watch",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "start": "node dist/index.js"
+  },
+  "keywords": ["mcp", "untitledui", "ui-components", "claude"],
+  "author": "Steffen Bilde",
+  "license": "MIT",
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "^20.0.0",
+    "tsup": "^8.0.0",
+    "typescript": "^5.0.0",
+    "vitest": "^2.0.0"
+  }
+}

package/src/api/client.test.ts

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

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

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

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

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

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

package/src/index.ts

@@ -0,0 +1,96 @@
+#!/usr/bin/env node
+
+import { resolveLicenseKey } from "./utils/license.js";
+import { runServer } from "./server.js";
+import { UntitledUIClient } from "./api/client.js";
+
+async function main() {
+  const args = process.argv.slice(2);
+
+  // Parse CLI arguments
+  let cliLicenseKey: string | undefined;
+  let testMode = false;
+
+  for (let i = 0; i < args.length; i++) {
+    if (args[i] === "--license-key" && args[i + 1]) {
+      cliLicenseKey = args[i + 1];
+      i++;
+    } else if (args[i] === "--test") {
+      testMode = true;
+    } else if (args[i] === "--help" || args[i] === "-h") {
+      console.log(`
+mcp-untitledui - MCP server for UntitledUI Pro components
+
+Usage:
+  mcp-untitledui [options]
+
+Options:
+  --license-key <key>  Specify license key (overrides env/config)
+  --test               Test connection and exit
+  --help, -h           Show this help message
+
+Environment:
+  UNTITLEDUI_LICENSE_KEY  License key (if not using --license-key)
+
+Config:
+  ~/.untitledui/config.json  Auto-detected from UntitledUI CLI login
+`);
+      process.exit(0);
+    }
+  }
+
+  // Resolve license key (optional - some features work without it)
+  const licenseKey = resolveLicenseKey(cliLicenseKey) || "";
+
+  // Test mode
+  if (testMode) {
+    console.log("Testing connection...");
+
+    if (!licenseKey) {
+      console.error("✗ No license key configured");
+      console.error("");
+      console.error("Get your license key:");
+      console.error("  npx untitledui login");
+      console.error("");
+      console.error("Then configure it via:");
+      console.error("  • Environment: UNTITLEDUI_LICENSE_KEY=<key>");
+      console.error("  • MCP config env field");
+      console.error("  • Auto-detected from ~/.untitledui/config.json");
+      process.exit(1);
+    }
+
+    const client = new UntitledUIClient(licenseKey);
+
+    const valid = await client.validateLicense();
+    if (!valid) {
+      console.error("✗ License key is invalid");
+      process.exit(1);
+    }
+    console.log("✓ License key is valid");
+
+    try {
+      const types = await client.listComponentTypes();
+      console.log(`✓ API connection successful`);
+      console.log(`✓ ${types.length} component types available`);
+      console.log("✓ Ready to serve");
+      process.exit(0);
+    } catch (error) {
+      console.error("✗ API connection failed:", error);
+      process.exit(1);
+    }
+  }
+
+  // Warn if no license key
+  if (!licenseKey) {
+    console.error("Warning: No license key configured. API calls will fail.");
+    console.error("Run 'npx untitledui login' to authenticate.");
+  }
+
+  // Run server
+  await runServer(licenseKey);
+}
+
+main().catch((error) => {
+  console.error("Fatal error:", error);
+  process.exit(1);
+});