untitledui-mcp 0.1.3 → 0.1.5

package/README.md

@@ -10,9 +10,32 @@ AI tools can generate functional UI, but the result often lacks the polish and c
 
 Instead of generating a modal from patterns it's seen, your AI fetches the actual UntitledUI modal with all its carefully crafted details intact.
 
-## Setup
+## Quick Start
 
-### Add MCP to your tool
+### 1. Start with a UntitledUI Starter Kit
+
+UntitledUI components require specific Tailwind configuration, design tokens, and providers. The easiest way to get started is with an official starter kit:
+
+**Next.js:**
+```bash
+git clone https://github.com/untitleduico/untitledui-nextjs-starter-kit my-app
+cd my-app && npm install
+```
+
+**Vite:**
+```bash
+git clone https://github.com/untitleduico/untitledui-vite-starter-kit my-app
+cd my-app && npm install
+```
+
+These starter kits come pre-configured with:
+- Tailwind CSS with all UntitledUI design tokens
+- Theme provider for light/dark mode
+- Toast notifications
+- Routing setup
+- All required dependencies
+
+### 2. Add the MCP Server
 
 **Claude Code:**
 ```bash
@@ -25,7 +48,7 @@ claude mcp add untitledui -- npx untitledui-mcp
   "mcpServers": {
     "untitledui": {
       "command": "npx",
-      "args": ["untitledui-mcp"]
+      "args": ["-y", "untitledui-mcp"]
     }
   }
 }
@@ -33,7 +56,7 @@ claude mcp add untitledui -- npx untitledui-mcp
 
 This gives you access to **base components** (button, input, select, avatar, badge, etc.) without authentication.
 
-### For Pro components (optional)
+### 3. Authenticate for Pro Components (optional)
 
 To access application components (modals, sidebars, tables, dashboards) and marketing sections, authenticate with your UntitledUI Pro license:
 
@@ -49,7 +72,7 @@ Alternatively, set the key manually in your MCP config:
   "mcpServers": {
     "untitledui": {
       "command": "npx",
-      "args": ["untitledui-mcp"],
+      "args": ["-y", "untitledui-mcp"],
       "env": {
         "UNTITLEDUI_LICENSE_KEY": "<your-key>"
       }
@@ -58,13 +81,26 @@ Alternatively, set the key manually in your MCP config:
 }
 ```
 
-### Verify setup
+### 4. Verify Setup
 
 ```bash
 npx untitledui-mcp --test
 ```
 
-## How It Works
+## Recommended Workflow
+
+1. **Start with a starter kit** — Don't try to add UntitledUI components to an existing project without the proper Tailwind setup. The starter kits handle all configuration.
+
+2. **Ask your AI to fetch components** — Once your project is set up, ask your AI to add specific components:
+   - "Add a settings modal"
+   - "I need a sidebar navigation"
+   - "Add the user profile dropdown"
+
+3. **Build complete pages from examples** — For larger features, start with a page template:
+   - "Show me available dashboard templates"
+   - "Fetch the landing page example"
+
+## Available Tools
 
 Your AI gets these tools:
 
@@ -74,44 +110,70 @@ Your AI gets these tools:
 | `list_components` | Browse a category |
 | `get_component_with_deps` | Fetch component + all dependencies |
 | `get_component` | Fetch component only |
+| `get_component_file` | Fetch a single file (for large components) |
 | `list_examples` | Browse available page templates |
-| `get_example` | Fetch a specific page template |
+| `get_example` | Fetch a complete page template |
 
-### Example: Add a modal
+## What You Can Do
+
+### Recreate Any UI from a Screenshot
 
 ```
-You: "Add a settings modal"
+You: [paste screenshot] "Recreate this with UntitledUI components"
 
-AI searches → finds application/modals/settings-modal
-AI fetches → gets modal + button, input, select base components
-AI adds → places files in your project with correct imports
+AI analyzes the design → identifies matching components
+AI fetches sidebar, header, cards, tables → all with dependencies
+AI assembles → production-ready page matching your screenshot
 ```
 
-### Example: Browse options
+### Build Complete Pages in Seconds
 
 ```
-You: "What sidebar variants are there?"
+You: "Build me a SaaS pricing page with 3 tiers and a FAQ section"
 
-AI calls list_components { type: "application", subfolder: "sidebars" }
-→ Returns all sidebar options for you to choose from
+AI fetches marketing/pricing-sections + marketing/faq-sections
+AI combines components → complete pricing page with toggle for monthly/annual
+Result: Professional pricing page with all interactions working
 ```
 
-### Example: Start from a page template
+### Set Up Your Entire App Shell
 
 ```
-You: "Show me available dashboard templates"
+You: "Set up the main app layout with collapsible sidebar and header with user dropdown"
 
-AI calls list_examples { path: "" }
-→ Returns: application, marketing
+AI fetches application/sidebars + application/headers + base components
+AI wires up navigation state, theme toggle, user menu
+Result: Complete app shell ready for your content
+```
 
-AI calls list_examples { path: "application" }
-→ Returns: dashboards-01, dashboards-02, settings-01, ...
+### Clone a Page from UntitledUI's Templates
 
-AI calls list_examples { path: "application/dashboards-01" }
-→ Returns: 01, 02, 03, ... (individual pages)
+```
+You: "I want a dashboard like the one in dashboards-01"
 
 AI calls get_example { path: "application/dashboards-01/01" }
-→ Returns complete page with 27 files, all dependencies
+→ Returns 27 files: page layout, charts, tables, cards, all base components
+→ Ready to customize with your data
+```
+
+### Mix and Match Components
+
+```
+You: "Create a settings page with sections for profile, notifications, billing, and team members"
+
+AI searches → finds matching components for each section
+AI fetches settings panels, forms, tables, modals
+AI composes → cohesive settings page with consistent styling
+```
+
+### Rapid Feature Development
+
+```
+You: "Add a command palette like Linear/Notion with keyboard shortcut"
+
+AI fetches application/command-menus
+→ Complete command palette with search, keyboard navigation, sections
+→ Just wire up your actions
 ```
 
 ## Response Format
@@ -127,22 +189,44 @@ AI calls get_example { path: "application/dashboards-01/01" }
     { "name": "button", "files": [...] },
     { "name": "input", "files": [...] }
   ],
-  "allDependencies": ["@headlessui/react", "clsx"]
+  "allDependencies": ["@headlessui/react", "clsx"],
+  "estimatedTokens": 12500,
+  "fileList": [
+    { "path": "settings-modal.tsx", "tokens": 850 },
+    { "path": "button/button.tsx", "tokens": 420 }
+  ]
 }
 ```
 
+Responses include token estimates to help AI agents manage context limits. For very large responses (>25K tokens), the AI can use `get_component_file` to fetch individual files.
+
+## Troubleshooting
+
+### Components don't look right / missing styles
+
+UntitledUI components use custom Tailwind classes like `bg-primary`, `text-display-md`, and design tokens that aren't part of standard Tailwind.
+
+**Solution:** Use a [UntitledUI starter kit](#1-start-with-a-untitledui-starter-kit). The starter kits include all required Tailwind configuration and design tokens.
+
+### Import errors for base components
+
+Pro components depend on base components (button, input, etc.). When fetching a component with `get_component_with_deps`, all dependencies are included automatically.
+
+**Solution:** Make sure you're using `get_component_with_deps` instead of `get_component` for Pro components.
+
 ## Requirements
 
 - Node.js 18+
-- UntitledUI Pro license (only for Pro components)
+- UntitledUI Pro license (for Pro components only)
 
 ## Credits
 
-[UntitledUI](https://www.untitledui.com) is created by [Jordan Hughes](https://jordanhughes.co).
+[UntitledUI](https://www.untitledui.com?utm_source=untitledui-mcp&utm_medium=github&utm_campaign=readme) is created by [Jordan Hughes](https://jordanhughes.co?utm_source=untitledui-mcp&utm_medium=github&utm_campaign=readme).
 
 - [Twitter/X](https://x.com/jordanphughes)
 - [Dribbble](https://dribbble.com/jordanhughes)
 - [UntitledUI on X](https://x.com/UntitledUI)
+- [Get UntitledUI Pro](https://www.untitledui.com/pricing?utm_source=untitledui-mcp&utm_medium=github&utm_campaign=readme)
 
 ## License
 

package/dist/index.js

@@ -378,6 +378,28 @@ function getBaseComponentNames(files) {
   return Array.from(names);
 }
 
+// src/utils/tokens.ts
+function estimateTokens(content) {
+  return Math.ceil(content.length / 4);
+}
+function estimateFileTokens(file) {
+  const content = file.code || file.content || "";
+  return estimateTokens(content);
+}
+function estimateComponentTokens(files) {
+  return files.reduce((sum, file) => sum + estimateFileTokens(file), 0);
+}
+function getFileTokenList(files) {
+  return files.map((file) => ({
+    path: file.path,
+    tokens: estimateFileTokens(file)
+  }));
+}
+var CLAUDE_READ_TOKEN_LIMIT = 25e3;
+function isLikelyTooLarge(estimatedTokens) {
+  return estimatedTokens > CLAUDE_READ_TOKEN_LIMIT;
+}
+
 // src/server.ts
 function createServer(licenseKey) {
   const client = new UntitledUIClient(licenseKey);
@@ -455,7 +477,7 @@ function createServer(licenseKey) {
       },
       {
         name: "get_component",
-        description: "Get a single component's code. Does NOT include dependencies - use get_component_with_deps for that.",
+        description: "Get a single component's code with token estimates. Returns estimatedTokens and file list. If estimatedTokens > 25000, consider using get_component_file for specific files instead.",
         inputSchema: {
           type: "object",
           properties: {
@@ -467,7 +489,7 @@ function createServer(licenseKey) {
       },
       {
         name: "get_component_with_deps",
-        description: "Get a component with all its base component dependencies included",
+        description: "Get a component with all base dependencies. Returns estimatedTokens. If response is too large (>25000 tokens), use get_component_file to fetch specific files individually.",
         inputSchema: {
           type: "object",
           properties: {
@@ -477,6 +499,19 @@ function createServer(licenseKey) {
           required: ["type", "name"]
         }
       },
+      {
+        name: "get_component_file",
+        description: "Get a single file from a component. Use this when get_component or get_component_with_deps returns a large response (>25000 tokens). First call get_component to see the file list, then fetch specific files as needed.",
+        inputSchema: {
+          type: "object",
+          properties: {
+            type: { type: "string", description: "Component type" },
+            name: { type: "string", description: "Component name" },
+            file: { type: "string", description: "File path within the component (e.g., 'Button.tsx' or 'variants/InputPhone.tsx')" }
+          },
+          required: ["type", "name", "file"]
+        }
+      },
       {
         name: "list_examples",
         description: "Browse available page examples. Call without path to see categories, then drill down.",
@@ -575,7 +610,20 @@ function createServer(licenseKey) {
             };
             cache.set(cacheKey, component, CACHE_TTL.componentCode);
           }
-          return { content: [{ type: "text", text: JSON.stringify(component, null, 2) }] };
+          const estimatedTokens = estimateComponentTokens(component.files);
+          const fileTokens = getFileTokenList(component.files);
+          const tooLarge = isLikelyTooLarge(estimatedTokens);
+          const result = {
+            ...component,
+            estimatedTokens,
+            fileCount: component.files.length,
+            fileList: fileTokens,
+            ...tooLarge && {
+              warning: `Response is large (${estimatedTokens} tokens). Consider using get_component_file for specific files.`,
+              hint: "Use get_component_file with type, name, and file path to fetch individual files."
+            }
+          };
+          return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
         }
         case "get_component_with_deps": {
           const { type, name: componentName } = args;
@@ -602,12 +650,19 @@ function createServer(licenseKey) {
             c.dependencies?.forEach((d) => allDeps.add(d));
             c.devDependencies?.forEach((d) => allDevDeps.add(d));
           });
+          const allFiles = [
+            ...primary.files,
+            ...baseComponents.flatMap((c) => c.files)
+          ];
+          const estimatedTokens = estimateComponentTokens(allFiles);
+          const tooLarge = isLikelyTooLarge(estimatedTokens);
           const result = {
             primary: {
               name: primary.name,
               type,
               description: generateDescription(primary.name, type),
               files: primary.files,
+              fileList: getFileTokenList(primary.files),
               dependencies: primary.dependencies || [],
               devDependencies: primary.devDependencies || [],
               baseComponents: baseComponentNames
@@ -617,15 +672,77 @@ function createServer(licenseKey) {
               type: "base",
               description: generateDescription(c.name, "base"),
               files: c.files,
+              fileList: getFileTokenList(c.files),
               dependencies: c.dependencies || [],
               devDependencies: c.devDependencies || []
             })),
             totalFiles: primary.files.length + baseComponents.reduce((sum, c) => sum + c.files.length, 0),
+            estimatedTokens,
             allDependencies: Array.from(allDeps),
-            allDevDependencies: Array.from(allDevDeps)
+            allDevDependencies: Array.from(allDevDeps),
+            ...tooLarge && {
+              warning: `Response is large (${estimatedTokens} tokens, limit is ${CLAUDE_READ_TOKEN_LIMIT}). Consider using get_component_file for specific files.`,
+              hint: "To fetch individual files, use get_component_file with the component type, name, and file path from fileList."
+            }
           };
           return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
         }
+        case "get_component_file": {
+          const { type, name: componentName, file: filePath } = args;
+          const cacheKey = `component:${type}:${componentName}`;
+          let files;
+          const cached = cache.get(cacheKey);
+          if (cached) {
+            files = cached.files;
+          } else {
+            const fetched = await client.fetchComponent(type, componentName);
+            if (!fetched) {
+              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)
+                }]
+              };
+            }
+            files = fetched.files;
+          }
+          const file = files.find(
+            (f) => f.path === filePath || f.path.endsWith(`/${filePath}`) || f.path.endsWith(filePath)
+          );
+          if (!file) {
+            const availableFiles = files.map((f) => f.path);
+            return {
+              content: [{
+                type: "text",
+                text: JSON.stringify({
+                  error: `File "${filePath}" not found in ${type}/${componentName}`,
+                  code: "FILE_NOT_FOUND",
+                  availableFiles,
+                  hint: "Use one of the file paths from availableFiles"
+                }, null, 2)
+              }]
+            };
+          }
+          return {
+            content: [{
+              type: "text",
+              text: JSON.stringify({
+                component: `${type}/${componentName}`,
+                file: {
+                  path: file.path,
+                  code: file.code
+                },
+                estimatedTokens: estimateComponentTokens([file])
+              }, null, 2)
+            }]
+          };
+        }
         case "list_examples": {
           const { path: path2 = "" } = args;
           const cacheKey = `examples:list:${path2}`;
@@ -675,17 +792,25 @@ function createServer(licenseKey) {
             };
           }
           if (example.type === "json-file" && example.content) {
+            const files = example.content.files || [];
+            const estimatedTokens = estimateComponentTokens(files);
+            const tooLarge = isLikelyTooLarge(estimatedTokens);
             return {
               content: [{
                 type: "text",
                 text: JSON.stringify({
                   path: examplePath,
                   name: example.content.name,
-                  files: example.content.files,
+                  files,
+                  fileList: getFileTokenList(files),
                   dependencies: example.content.dependencies || [],
                   devDependencies: example.content.devDependencies || [],
                   components: example.content.components || [],
-                  fileCount: example.content.files?.length || 0
+                  fileCount: files.length,
+                  estimatedTokens,
+                  ...tooLarge && {
+                    warning: `Response is large (${estimatedTokens} tokens). Consider fetching specific component files instead.`
+                  }
                 }, null, 2)
               }]
             };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "untitledui-mcp",
-  "version": "0.1.3",
+  "version": "0.1.5",
   "description": "MCP server for UntitledUI Pro components - browse, search, and retrieve UI components via Claude Code",
   "type": "module",
   "main": "dist/index.js",
@@ -25,7 +25,12 @@
     "test:watch": "vitest",
     "start": "node dist/index.js"
   },
-  "keywords": ["mcp", "untitledui", "ui-components", "claude"],
+  "keywords": [
+    "mcp",
+    "untitledui",
+    "ui-components",
+    "claude"
+  ],
   "author": "Steffen Bilde",
   "license": "MIT",
   "dependencies": {