lubaui-mcp 1.0.0

package/README.md

@@ -0,0 +1,207 @@
+# LubaUI MCP Server
+
+An MCP (Model Context Protocol) server that makes the LubaUI design system actively queryable by AI assistants. Rather than reading Swift source files, your AI gets structured answers about tokens, components, and patterns through dedicated tools.
+
+---
+
+## Setup
+
+### Using LubaUI in your own project (recommended)
+
+One command — works from any project directory:
+
+```bash
+claude mcp add lubaui -- npx lubaui-mcp
+```
+
+That's it. Next time you start Claude Code, the LubaUI tools are available. Ask "What spacing should I use for card padding?" and Claude will query the server.
+
+### Contributing to LubaUI
+
+If you're working inside the LubaUI repo itself, the `.mcp.json` at the project root auto-discovers the server. Just install dependencies:
+
+```bash
+cd mcp-server && npm install
+```
+
+The server starts on demand when Claude Code opens the project.
+
+---
+
+## Tools
+
+The server provides 7 tools that solve real problems during development.
+
+### `lookup_token`
+
+Find any design token by name or description.
+
+```
+"What spacing should I use for card padding?"
+→ LubaSpacing.lg — 16pt — "Large — card padding, section spacing, standard gap"
+
+"What's the accent color hex?"
+→ LubaColors.accent — light: #5F7360, dark: #9AB897
+```
+
+**Parameters:**
+- `query` (required) — Token name, API path, or description
+- `category` (optional) — Filter: `spacing`, `radius`, `color`, `typography`, `motion`, `glass`
+
+### `lookup_component`
+
+Get the full API for any of the 25 components.
+
+```
+"How do I use LubaButton?"
+→ Parameters, styles (.primary/.secondary/.ghost/.destructive/.subtle/.glass),
+  sizes, code example, related tokens
+```
+
+**Parameters:**
+- `query` (required) — Component name (fuzzy: "Button", "LubaTextField", "toast")
+
+### `lookup_primitive`
+
+Look up any of the 7 interaction primitives.
+
+```
+"How do I add swipe-to-delete?"
+→ .lubaSwipeable() modifier, parameters, 6 presets (.delete, .archive, .pin, etc.),
+  code example, composability notes
+```
+
+**Parameters:**
+- `query` (required) — Primitive name (fuzzy: "pressable", "swipeable", "glass")
+
+### `validate_spacing`
+
+Check if a spacing value is on the 4pt grid and maps to a named token.
+
+```
+"Is 14pt valid?"
+→ No — 14pt is NOT on the 4pt grid.
+  Nearest: LubaSpacing.md (12pt) and LubaSpacing.lg (16pt)
+
+"Is 16pt valid?"
+→ Yes — 16pt is LubaSpacing.lg
+```
+
+**Parameters:**
+- `value` (required) — Spacing value in points
+
+### `validate_radius`
+
+Check if a corner radius is on the LubaRadius scale.
+
+```
+"Is 10pt a valid radius?"
+→ No — nearest: LubaRadius.sm (8pt) and LubaRadius.md (12pt)
+  Valid radii: none(0), xs(4), sm(8), md(12), lg(16), xl(24), full(9999)
+```
+
+**Parameters:**
+- `value` (required) — Radius value in points
+
+### `get_color_palette`
+
+Browse colors by category or search across the palette.
+
+```
+"Show me the surface colors"
+→ background (#FAFAFA/#0D0D0D), surface (#FFFFFF/#171717),
+  surfaceSecondary (#F5F5F5/#212121), surfaceTertiary (#EFEFEF/#2A2A2A)
+
+"What colors are available for errors?"
+→ error (#B54A4A/#E07A7A), errorSubtle (#FAEFEF/#251A1A)
+```
+
+**Parameters:**
+- `query` (required) — Category name (`greyscale`, `surfaces`, `accent`, `text`, `semantic`, `border`, `glass`) or search term
+
+### `suggest_tokens`
+
+Describe what you're building and get token, component, and primitive recommendations.
+
+```
+"I'm building a notification banner"
+→ Spacing: LubaSpacing.md (12pt) internal, LubaSpacing.lg (16pt) horizontal
+  Colors: LubaColors.success/warning/error for status
+  Radius: LubaRadius.md (12pt)
+  Typography: LubaTypography.subheadline for message
+  Components: LubaToast, LubaAlert
+  Primitives: lubaGlass for frosted effect
+```
+
+**Parameters:**
+- `description` (required) — What you're building ("settings page", "profile card", "loading state")
+
+Recognizes these patterns: `form`, `notification`, `banner`, `card`, `list`, `loading`, `navigation`, `profile`, `modal`, `settings`.
+
+---
+
+## Resources
+
+Three read-only resources provide full reference data.
+
+| URI | Description |
+|-----|-------------|
+| `lubaui://tokens/all` | Complete token catalog — spacing, radius, colors, typography, motion, glass |
+| `lubaui://architecture` | Three-tier system rules, design philosophy, naming conventions |
+| `lubaui://components` | Component and primitive directory with descriptions |
+
+---
+
+## Architecture
+
+```
+mcp-server/
+├── package.json
+├── tsconfig.json
+└── src/
+    ├── index.ts              # Server entry, tool/resource registration
+    ├── data/
+    │   ├── tokens.json       # Spacing, radius, colors, typography, motion, glass
+    │   ├── components.json   # 25 component APIs with parameters and examples
+    │   └── primitives.json   # 7 primitives with modifiers and patterns
+    ├── tools/
+    │   ├── lookup.ts         # lookup_token, lookup_component, lookup_primitive, get_color_palette
+    │   ├── validate.ts       # validate_spacing, validate_radius
+    │   └── suggest.ts        # suggest_tokens
+    └── utils/
+        └── search.ts         # Scored fuzzy search (camelCase-aware)
+```
+
+**Data strategy:** Hand-authored JSON files transcribed from the Swift sources. The data files include usage guidance, cross-references, and design rationale that don't exist in source code. The token system changes infrequently, so static JSON is reliable and avoids runtime Swift parsing.
+
+**Search:** Simple scored matching — exact (100) > starts-with (80) > contains (60) > camelCase part match (50). No external dependencies.
+
+**Transport:** stdio via `@modelcontextprotocol/sdk`. Runs with `npx tsx` (no build step).
+
+---
+
+## Updating Data
+
+When tokens or components change in the Swift sources, update the corresponding JSON file in `src/data/`:
+
+- **Token changes** (new spacing value, color tweak) → edit `tokens.json`
+- **New component or API change** → edit `components.json`
+- **New primitive or modifier change** → edit `primitives.json`
+
+The JSON structure is self-documenting. Match the existing patterns when adding entries.
+
+---
+
+## Development
+
+```bash
+# Install
+cd mcp-server && npm install
+
+# Test manually (sends JSON-RPC over stdin)
+echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"test","version":"1.0.0"}}}' | npx tsx src/index.ts
+
+# List tools
+echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"test","version":"1.0.0"}}}
+{"jsonrpc":"2.0","id":2,"method":"tools/list","params":{}}' | npx tsx src/index.ts
+```

package/bin/lubaui-mcp.js

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+import "../dist/index.js";

package/dist/index.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/index.js

@@ -0,0 +1,149 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { z } from "zod";
+import { lookupToken, lookupComponent, lookupPrimitive, getColorPalette, tokensData, componentsData, primitivesData, } from "./tools/lookup.js";
+import { validateSpacing, validateRadius } from "./tools/validate.js";
+import { suggestTokens } from "./tools/suggest.js";
+const server = new McpServer({
+    name: "lubaui",
+    version: "1.0.0",
+});
+// --- Tools ---
+server.tool("lookup_token", "Look up a LubaUI design token by name or description. Returns token name, API, value, tier, and usage guidance.", {
+    query: z.string().describe("Token name, API path, or description (e.g. 'spacing large', 'lg', 'card padding')"),
+    category: z
+        .enum(["spacing", "radius", "color", "typography", "motion", "glass"])
+        .optional()
+        .describe("Filter by token category"),
+}, async ({ query, category }) => {
+    const result = lookupToken(query, category);
+    return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
+});
+server.tool("lookup_component", "Look up a LubaUI component by name. Returns init parameters, styles, code example, and related tokens.", {
+    query: z.string().describe("Component name (e.g. 'Button', 'LubaTextField', 'toast')"),
+}, async ({ query }) => {
+    const result = lookupComponent(query);
+    return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
+});
+server.tool("lookup_primitive", "Look up a LubaUI interaction primitive by name. Returns modifier signature, parameters, presets, and code example.", {
+    query: z.string().describe("Primitive name (e.g. 'pressable', 'swipeable', 'glass', 'expandable')"),
+}, async ({ query }) => {
+    const result = lookupPrimitive(query);
+    return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
+});
+server.tool("validate_spacing", "Check if a spacing value is on the LubaUI 4pt grid and maps to a named token. Suggests nearest tokens if not.", {
+    value: z.number().describe("Spacing value in points to validate"),
+}, async ({ value }) => {
+    const result = validateSpacing(value);
+    return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
+});
+server.tool("validate_radius", "Check if a corner radius value is on the LubaUI radius scale. Suggests nearest token if not.", {
+    value: z.number().describe("Radius value in points to validate"),
+}, async ({ value }) => {
+    const result = validateRadius(value);
+    return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
+});
+server.tool("get_color_palette", "Get LubaUI colors by category or search. Returns light/dark hex values and usage context.", {
+    query: z.string().describe("Color category (greyscale, surfaces, accent, text, semantic, border, glass) or search term (e.g. 'error', 'background')"),
+}, async ({ query }) => {
+    const result = getColorPalette(query);
+    return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
+});
+server.tool("suggest_tokens", "Suggest LubaUI tokens, components, and primitives for a UI you're building. Describe what you're building and get recommendations.", {
+    description: z.string().describe("Description of what you're building (e.g. 'notification banner', 'settings page', 'profile card')"),
+}, async ({ description }) => {
+    const result = suggestTokens(description);
+    return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
+});
+// --- Resources ---
+server.resource("tokens-all", "lubaui://tokens/all", { description: "Complete LubaUI token catalog — spacing, radius, colors, typography, motion, and glass tokens" }, async () => {
+    return {
+        contents: [
+            {
+                uri: "lubaui://tokens/all",
+                mimeType: "application/json",
+                text: JSON.stringify(tokensData, null, 2),
+            },
+        ],
+    };
+});
+server.resource("architecture", "lubaui://architecture", { description: "LubaUI design system architecture — three-tier token system, design philosophy, and conventions" }, async () => {
+    const architecture = {
+        philosophy: "Composability over inheritance. Behaviors are extracted into primitives so any view can gain interactive powers through modifiers, not subclassing. Every magic number has a name, a token, and documented rationale.",
+        tokenSystem: {
+            tier1: {
+                name: "Primitives (LubaPrimitives)",
+                rule: "Raw hex values and numbers. The DNA. NEVER reference directly in component code.",
+                examples: ["LubaPrimitives.grey900Light → Color(hex: 0x1A1A1A)", "LubaPrimitives.space4 → 4"],
+            },
+            tier2: {
+                name: "Semantic Tokens",
+                rule: "Human-readable, context-aware names. USE THESE in components.",
+                modules: ["LubaColors", "LubaSpacing", "LubaRadius", "LubaTypography", "LubaMotion", "LubaAnimations"],
+                examples: ["LubaColors.textPrimary → adaptive grey900", "LubaSpacing.lg → 16pt", "LubaMotion.pressScale → 0.97"],
+            },
+            tier3: {
+                name: "Component Tokens",
+                rule: "Per-component configuration enums. Reference tier 2 tokens internally.",
+                modules: ["LubaCardTokens", "LubaFieldTokens", "LubaButtonSize", "LubaToastTokens", "LubaTabsTokens", "etc."],
+            },
+        },
+        colorSystem: {
+            approach: "Greyscale-first with organic sage green accent",
+            adaptive: "All colors use LubaColors.adaptive(light:dark:) for automatic light/dark mode",
+            surfaceHierarchy: "background → surface → surfaceSecondary → surfaceTertiary",
+            accentColor: "Sage green (#5F7360 light / #9AB897 dark) — WCAG AA compliant",
+        },
+        spacingGrid: "4pt base grid. Named tokens: xs(4), sm(8), md(12), lg(16), xl(24), xxl(32), xxxl(48), huge(64)",
+        radiusScale: "none(0), xs(4), sm(8), md(12), lg(16), xl(24), full(9999)",
+        typography: "SF Rounded by default. Config-aware via LubaConfig.shared.useRoundedFont",
+        motionSystems: {
+            LubaMotion: "Raw constants (scale values, animation parameters) — use with .scaleEffect(), .opacity()",
+            LubaAnimations: "Applied Animation objects — use with withAnimation(), .animation(), .transition()",
+        },
+        platforms: "iOS 16+, macOS 13+, watchOS 9+, tvOS 16+, visionOS 1.0+",
+        configuration: {
+            environment: "@Environment(\\.lubaConfig) for runtime settings, @Environment(\\.lubaTheme) for theming",
+            presets: [".minimal", ".accessible", ".debug"],
+        },
+    };
+    return {
+        contents: [
+            {
+                uri: "lubaui://architecture",
+                mimeType: "application/json",
+                text: JSON.stringify(architecture, null, 2),
+            },
+        ],
+    };
+});
+server.resource("components", "lubaui://components", { description: "LubaUI component directory — all 25 components with descriptions" }, async () => {
+    const summary = componentsData.map((c) => ({
+        name: c.name,
+        description: c.description,
+    }));
+    const primitivesSummary = primitivesData.map((p) => ({
+        name: p.name,
+        modifier: p.modifier,
+        description: p.description,
+    }));
+    return {
+        contents: [
+            {
+                uri: "lubaui://components",
+                mimeType: "application/json",
+                text: JSON.stringify({
+                    components: summary,
+                    primitives: primitivesSummary,
+                    total: { components: summary.length, primitives: primitivesSummary.length },
+                }, null, 2),
+            },
+        ],
+    };
+});
+// --- Start ---
+async function main() {
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+}
+main().catch(console.error);

package/dist/tools/lookup.d.ts

@@ -0,0 +1,118 @@
+declare const tokensData: any;
+declare const componentsData: ComponentEntry[];
+declare const primitivesData: PrimitiveEntry[];
+interface ComponentEntry {
+    name: string;
+    description: string;
+    parameters: Array<{
+        name: string;
+        type: string;
+        required?: boolean;
+        default?: string;
+        options?: string[];
+        description: string;
+    }>;
+    example: string;
+    tokens: string[];
+    notes: string;
+}
+interface PrimitiveEntry {
+    name: string;
+    modifier: string;
+    description: string;
+    parameters: Array<{
+        name: string;
+        type: string;
+        required?: boolean;
+        default?: string;
+        options?: string[];
+        description: string;
+    }>;
+    example: string;
+    tokens: string[];
+    composability: string;
+    [key: string]: unknown;
+}
+export declare function lookupToken(query: string, category?: string): {
+    found: boolean;
+    message: string;
+    count?: undefined;
+    tokens?: undefined;
+} | {
+    found: boolean;
+    count: number;
+    tokens: {
+        aliasOf?: string | undefined;
+        primitive?: string | undefined;
+        dark?: string | undefined;
+        light?: string | undefined;
+        name: string;
+        api: string;
+        value: string | number | undefined;
+        tier: number | undefined;
+        category: string;
+        subcategory: string | undefined;
+        description: string;
+    }[];
+    message?: undefined;
+};
+export declare function lookupComponent(query: string): {
+    found: boolean;
+    message: string;
+    components?: undefined;
+} | {
+    found: boolean;
+    components: {
+        name: string;
+        description: string;
+        parameters: {
+            name: string;
+            type: string;
+            required?: boolean;
+            default?: string;
+            options?: string[];
+            description: string;
+        }[];
+        example: string;
+        tokens: string[];
+        notes: string;
+    }[];
+    message?: undefined;
+};
+export declare function lookupPrimitive(query: string): {
+    found: boolean;
+    message: string;
+    primitives?: undefined;
+} | {
+    found: boolean;
+    primitives: Record<string, unknown>[];
+    message?: undefined;
+};
+export declare function getColorPalette(query: string): {
+    category: string;
+    description: any;
+    colors: any;
+    found?: undefined;
+    message?: undefined;
+} | {
+    found: boolean;
+    message: string;
+    category?: undefined;
+    description?: undefined;
+    colors?: undefined;
+} | {
+    found: boolean;
+    colors: {
+        aliasOf?: string | undefined;
+        name: string;
+        api: string;
+        light: string | undefined;
+        dark: string | undefined;
+        description: string;
+        subcategory: string | undefined;
+    }[];
+    category?: undefined;
+    description?: undefined;
+    message?: undefined;
+};
+export { tokensData, componentsData, primitivesData };

package/dist/tools/lookup.js

@@ -0,0 +1,201 @@
+import { readFileSync } from "fs";
+import { join } from "path";
+import { search } from "../utils/search.js";
+import { dataDir } from "../utils/paths.js";
+// Load data once at module level
+const tokensData = JSON.parse(readFileSync(join(dataDir, "tokens.json"), "utf-8"));
+const componentsData = JSON.parse(readFileSync(join(dataDir, "components.json"), "utf-8"));
+const primitivesData = JSON.parse(readFileSync(join(dataDir, "primitives.json"), "utf-8"));
+function flattenTokens() {
+    const flat = [];
+    // Spacing
+    for (const t of tokensData.spacing.tokens) {
+        flat.push({ ...t, category: "spacing", aliases: [t.api] });
+    }
+    // Radius
+    for (const t of tokensData.radius.tokens) {
+        flat.push({ ...t, category: "radius", aliases: [t.api] });
+    }
+    // Colors (all subcategories)
+    for (const sub of [
+        "greyscale",
+        "surfaces",
+        "accent",
+        "text",
+        "semantic",
+        "border",
+        "glass",
+    ]) {
+        const colors = tokensData.colors[sub];
+        if (colors) {
+            for (const c of colors) {
+                flat.push({
+                    ...c,
+                    category: "color",
+                    subcategory: sub,
+                    aliases: [c.api],
+                });
+            }
+        }
+    }
+    // Typography
+    for (const t of tokensData.typography.tokens) {
+        flat.push({
+            ...t,
+            category: "typography",
+            aliases: [t.api],
+            value: `${t.size}pt ${t.weight}`,
+        });
+    }
+    // Motion constants
+    for (const sub of ["pressScales", "animations", "other"]) {
+        const items = tokensData.motion.constants[sub];
+        if (items) {
+            for (const m of items) {
+                flat.push({ ...m, category: "motion", subcategory: sub, aliases: [m.api] });
+            }
+        }
+    }
+    // Applied animations
+    for (const a of tokensData.motion.appliedAnimations) {
+        flat.push({ ...a, category: "motion", subcategory: "applied", aliases: [a.api] });
+    }
+    // Glass
+    for (const s of tokensData.glass.styles) {
+        flat.push({ ...s, category: "glass", aliases: [s.api] });
+    }
+    for (const t of tokensData.glass.tokens) {
+        flat.push({ ...t, category: "glass", aliases: [t.api], description: t.name });
+    }
+    return flat;
+}
+const flatTokens = flattenTokens();
+// --- Tool implementations ---
+export function lookupToken(query, category) {
+    const results = search(flatTokens, query, { category, maxResults: 8 });
+    if (results.length === 0) {
+        return { found: false, message: `No tokens matching "${query}"${category ? ` in category "${category}"` : ""}` };
+    }
+    return {
+        found: true,
+        count: results.length,
+        tokens: results.map((t) => ({
+            name: t.name,
+            api: t.api,
+            value: t.value,
+            tier: t.tier,
+            category: t.category,
+            subcategory: t.subcategory,
+            description: t.description,
+            ...(t.light && { light: t.light }),
+            ...(t.dark && { dark: t.dark }),
+            ...(t.primitive && { primitive: t.primitive }),
+            ...(t.aliasOf && { aliasOf: t.aliasOf }),
+        })),
+    };
+}
+export function lookupComponent(query) {
+    const searchable = componentsData.map((c) => ({
+        ...c,
+        aliases: [c.name.replace("Luba", "")],
+    }));
+    const results = search(searchable, query, { maxResults: 3 });
+    if (results.length === 0) {
+        return {
+            found: false,
+            message: `No component matching "${query}". Available: ${componentsData.map((c) => c.name).join(", ")}`,
+        };
+    }
+    return {
+        found: true,
+        components: results.map((c) => ({
+            name: c.name,
+            description: c.description,
+            parameters: c.parameters,
+            example: c.example,
+            tokens: c.tokens,
+            notes: c.notes,
+        })),
+    };
+}
+export function lookupPrimitive(query) {
+    const searchable = primitivesData.map((p) => ({
+        ...p,
+        aliases: [p.name.replace("luba", ""), p.modifier],
+    }));
+    const results = search(searchable, query, { maxResults: 3 });
+    if (results.length === 0) {
+        return {
+            found: false,
+            message: `No primitive matching "${query}". Available: ${primitivesData.map((p) => p.name).join(", ")}`,
+        };
+    }
+    return {
+        found: true,
+        primitives: results.map((p) => {
+            const result = {
+                name: p.name,
+                modifier: p.modifier,
+                description: p.description,
+                parameters: p.parameters,
+                example: p.example,
+                tokens: p.tokens,
+                composability: p.composability,
+            };
+            if ("presets" in p)
+                result.presets = p.presets;
+            if ("variants" in p)
+                result.variants = p.variants;
+            if ("builtInStyles" in p)
+                result.builtInStyles = p.builtInStyles;
+            if ("hapticStyles" in p)
+                result.hapticStyles = p.hapticStyles;
+            return result;
+        }),
+    };
+}
+export function getColorPalette(query) {
+    const categories = [
+        "greyscale",
+        "surfaces",
+        "accent",
+        "text",
+        "semantic",
+        "border",
+        "glass",
+    ];
+    // Check if query matches a category directly
+    const directMatch = categories.find((c) => c.toLowerCase() === query.toLowerCase() ||
+        c.toLowerCase().startsWith(query.toLowerCase()));
+    if (directMatch) {
+        const colors = tokensData.colors[directMatch];
+        return {
+            category: directMatch,
+            description: tokensData.colors.description,
+            colors: colors,
+        };
+    }
+    // Otherwise search across all colors
+    const allColors = flatTokens.filter((t) => t.category === "color");
+    const results = search(allColors, query, { maxResults: 10 });
+    if (results.length === 0) {
+        return {
+            found: false,
+            message: `No colors matching "${query}". Categories: ${categories.join(", ")}`,
+        };
+    }
+    return {
+        found: true,
+        colors: results.map((c) => ({
+            name: c.name,
+            api: c.api,
+            light: c.light,
+            dark: c.dark,
+            description: c.description,
+            subcategory: c.subcategory,
+            ...(c.aliasOf && { aliasOf: c.aliasOf }),
+        })),
+    };
+}
+// Export data for resources
+export { tokensData, componentsData, primitivesData };