@pudge-ui/mcp-server 0.1.0

package/README.md

@@ -0,0 +1,63 @@
+# @pudge-ui/mcp-server
+
+MCP server for the pudge-ui design system. Lets coding agents query component specs programmatically.
+
+## Installation
+
+Add to your MCP client config (e.g. Claude Desktop, Claude Code):
+
+```json
+{
+  "mcpServers": {
+    "pudge-ui": {
+      "command": "npx",
+      "args": ["-y", "@pudge-ui/mcp-server"]
+    }
+  }
+}
+```
+
+For local development:
+
+```json
+{
+  "mcpServers": {
+    "pudge-ui": {
+      "command": "npx",
+      "args": ["tsx", "src/index.ts"],
+      "cwd": "/path/to/pudge-ui/packages/mcp-server"
+    }
+  }
+}
+```
+
+## Available Tools
+
+| Tool                | Description                                                  |
+| ------------------- | ------------------------------------------------------------ |
+| `list_components`   | List all components, optionally filtered by category         |
+| `search_components` | Fuzzy search components by name, description, or tags        |
+| `get_foundation`    | Get foundation spec docs (core 5 or extended 9)              |
+| `get_component`     | Get full spec for a single component (foundation + spec)     |
+| `get_components`    | Get specs for multiple components (foundation included once) |
+| `get_composition`   | Get a composition spec with all referenced component specs   |
+
+## Examples
+
+```
+list_components({ category: "buttons" })
+search_components({ query: "volume slider audio" })
+get_component({ name: "push-button" })
+get_components({ names: ["rotary-encoder", "vu-meter", "vertical-fader"] })
+get_composition({ name: "audio-mixer-strip" })
+get_foundation({ extended: true })
+```
+
+## Development
+
+```bash
+npm install
+npm run dev        # run with tsx
+npm run build      # compile + copy spec
+npm run typecheck  # type-check only
+```

package/dist/__tests__/catalog.test.d.ts

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

package/dist/__tests__/catalog.test.js

@@ -0,0 +1,50 @@
+import { describe, it, expect, beforeAll } from "vitest";
+import { loadCatalog, findComponent } from "../catalog.js";
+import { resolveSpecDir } from "../assembler.js";
+let catalog;
+let specDir;
+beforeAll(async () => {
+    specDir = resolveSpecDir();
+    catalog = await loadCatalog(specDir);
+});
+describe("loadCatalog", () => {
+    it("loads all 93 components", () => {
+        expect(catalog.components.length).toBe(93);
+    });
+    it("loads all 11 categories", () => {
+        expect(catalog.categories.length).toBe(11);
+    });
+    it("every component has required fields", () => {
+        for (const comp of catalog.components) {
+            expect(comp.id).toBeTruthy();
+            expect(comp.name).toBeTruthy();
+            expect(comp.class).toBeTruthy();
+            expect(comp.category).toBeTruthy();
+            expect(comp.file).toBeTruthy();
+            expect(comp.description).toBeTruthy();
+        }
+    });
+    it("every component belongs to a known category", () => {
+        const categoryIds = new Set(catalog.categories.map((c) => c.id));
+        for (const comp of catalog.components) {
+            expect(categoryIds.has(comp.category)).toBe(true);
+        }
+    });
+});
+describe("findComponent", () => {
+    it("finds a component by id", () => {
+        const comp = findComponent(catalog, "push-button");
+        expect(comp).toBeDefined();
+        expect(comp.name).toBe("Push Button");
+        expect(comp.class).toBe(".push-btn");
+    });
+    it("finds a component by name (case-insensitive)", () => {
+        const comp = findComponent(catalog, "push button");
+        expect(comp).toBeDefined();
+        expect(comp.id).toBe("push-button");
+    });
+    it("returns undefined for unknown component", () => {
+        const comp = findComponent(catalog, "nonexistent-widget");
+        expect(comp).toBeUndefined();
+    });
+});

package/dist/__tests__/search.test.d.ts

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

package/dist/__tests__/search.test.js

@@ -0,0 +1,44 @@
+import { describe, it, expect, beforeAll } from "vitest";
+import { loadCatalog } from "../catalog.js";
+import { createSearchIndex, searchComponents } from "../search.js";
+import { resolveSpecDir, loadFoundation } from "../assembler.js";
+let catalog;
+let index;
+let specDir;
+beforeAll(async () => {
+    specDir = resolveSpecDir();
+    catalog = await loadCatalog(specDir);
+    index = createSearchIndex(catalog.components);
+});
+describe("searchComponents", () => {
+    it("finds components matching 'button'", () => {
+        const results = searchComponents(index, "button");
+        expect(results.length).toBeGreaterThan(0);
+        expect(results.some((r) => r.id === "push-button")).toBe(true);
+    });
+    it("finds components matching 'LCD'", () => {
+        const results = searchComponents(index, "LCD");
+        expect(results.length).toBeGreaterThan(0);
+        expect(results.some((r) => r.id === "lcd-readout")).toBe(true);
+    });
+    it("returns empty array for nonsense query", () => {
+        const results = searchComponents(index, "xyzzy123nonexistent");
+        expect(results.length).toBe(0);
+    });
+    it("respects limit parameter", () => {
+        const results = searchComponents(index, "button", 3);
+        expect(results.length).toBeLessThanOrEqual(3);
+    });
+});
+describe("loadFoundation", () => {
+    it("loads core foundation (5 files)", async () => {
+        const content = await loadFoundation(specDir, false);
+        expect(content).toBeTruthy();
+        expect(content.length).toBeGreaterThan(1000);
+    });
+    it("loads extended foundation (9 files)", async () => {
+        const content = await loadFoundation(specDir, true);
+        expect(content).toBeTruthy();
+        expect(content.length).toBeGreaterThan(content.length * 0.5);
+    });
+});

package/dist/__tests__/validation.test.d.ts

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

package/dist/__tests__/validation.test.js

@@ -0,0 +1,34 @@
+import { describe, it, expect, beforeAll } from "vitest";
+import { resolveSpecDir, assembleComposition } from "../assembler.js";
+import { loadCatalog } from "../catalog.js";
+import { createSearchIndex } from "../search.js";
+import { handleTool } from "../tools.js";
+let ctx;
+beforeAll(async () => {
+    const specDir = resolveSpecDir();
+    const catalog = await loadCatalog(specDir);
+    ctx = { specDir, catalog, searchIndex: createSearchIndex(catalog.components) };
+});
+describe("assembleComposition rejects path traversal", () => {
+    it("throws on traversal / non-slug names before touching the filesystem", async () => {
+        for (const bad of ["../../../etc/passwd", "../secret", "a/b", "foo..bar", "UPPER"]) {
+            await expect(assembleComposition(ctx.specDir, ctx.catalog, bad)).rejects.toThrow(/Invalid composition name/);
+        }
+    });
+    it("accepts a valid composition slug", async () => {
+        const out = await assembleComposition(ctx.specDir, ctx.catalog, "audio-mixer-strip");
+        expect(out).toContain("COMPOSITION: audio-mixer-strip");
+    });
+});
+describe("handleTool validates inputs", () => {
+    it("rejects missing or malformed required args", async () => {
+        await expect(handleTool("get_component", {}, ctx)).rejects.toThrow(/non-empty string/);
+        await expect(handleTool("search_components", { query: "" }, ctx)).rejects.toThrow(/non-empty string/);
+        await expect(handleTool("get_components", { names: [] }, ctx)).rejects.toThrow(/non-empty array/);
+        await expect(handleTool("get_composition", { name: "../x" }, ctx)).rejects.toThrow(/Invalid composition name/);
+    });
+    it("clamps an out-of-range search limit", async () => {
+        const out = await handleTool("search_components", { query: "button", limit: 999 }, ctx);
+        expect(JSON.parse(out).length).toBeLessThanOrEqual(50);
+    });
+});

package/dist/assembler.d.ts

@@ -0,0 +1,6 @@
+import type { Catalog } from "./catalog.js";
+export declare function resolveSpecDir(): string;
+export declare function loadFoundation(specDir: string, extended?: boolean): Promise<string>;
+export declare function assembleComponent(specDir: string, catalog: Catalog, name: string): Promise<string>;
+export declare function assembleComponents(specDir: string, catalog: Catalog, names: string[]): Promise<string>;
+export declare function assembleComposition(specDir: string, catalog: Catalog, name: string): Promise<string>;

package/dist/assembler.js

@@ -0,0 +1,95 @@
+import { readFile } from "node:fs/promises";
+import { join, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+import { existsSync } from "node:fs";
+import { parse } from "yaml";
+import { findComponent } from "./catalog.js";
+const CORE_FOUNDATIONS = ["philosophy", "tokens", "materials", "depth-model", "naming"];
+const ALL_FOUNDATIONS = [...CORE_FOUNDATIONS, "theme", "accessibility", "layout", "canvas"];
+export function resolveSpecDir() {
+    const here = dirname(fileURLToPath(import.meta.url));
+    // Monorepo: src/ or dist/ -> package root -> ../../spec
+    const monorepo = join(here, "..", "..", "..", "spec");
+    if (existsSync(monorepo))
+        return monorepo;
+    // npm package: dist/ -> package root -> ./spec
+    const bundled = join(here, "..", "spec");
+    if (existsSync(bundled))
+        return bundled;
+    throw new Error("Could not find spec directory");
+}
+export async function loadFoundation(specDir, extended = false) {
+    const files = extended ? ALL_FOUNDATIONS : CORE_FOUNDATIONS;
+    const contents = await Promise.all(files.map((f) => readFile(join(specDir, "foundation", `${f}.md`), "utf8")));
+    return contents.join("\n\n");
+}
+export async function assembleComponent(specDir, catalog, name) {
+    const comp = findComponent(catalog, name);
+    if (!comp)
+        throw new Error(`Component not found: ${name}`);
+    const [foundation, spec] = await Promise.all([
+        loadFoundation(specDir),
+        readFile(join(specDir, "components", comp.file), "utf8"),
+    ]);
+    return [
+        `<!-- ═══ PUDGE-UI FOUNDATION ═══ -->`,
+        foundation,
+        "",
+        `<!-- ═══ COMPONENT: ${comp.name} ═══ -->`,
+        spec,
+    ].join("\n");
+}
+export async function assembleComponents(specDir, catalog, names) {
+    const comps = names.map((n) => {
+        const c = findComponent(catalog, n);
+        if (!c)
+            throw new Error(`Component not found: ${n}`);
+        return c;
+    });
+    const [foundation, ...specs] = await Promise.all([
+        loadFoundation(specDir),
+        ...comps.map((c) => readFile(join(specDir, "components", c.file), "utf8")),
+    ]);
+    const parts = [`<!-- ═══ PUDGE-UI FOUNDATION ═══ -->`, foundation, ""];
+    comps.forEach((c, i) => {
+        parts.push(`<!-- ═══ COMPONENT: ${c.name} ═══ -->`);
+        parts.push(specs[i]);
+        parts.push("");
+    });
+    return parts.join("\n");
+}
+export async function assembleComposition(specDir, catalog, name) {
+    if (!/^[a-z0-9-]+$/.test(name)) {
+        throw new Error(`Invalid composition name: ${name}`);
+    }
+    const compPath = join(specDir, "compositions", `${name}.md`);
+    const raw = await readFile(compPath, "utf8");
+    // Parse frontmatter for component IDs
+    const fmMatch = raw.match(/^---\n([\s\S]*?)\n---/);
+    const fm = fmMatch ? parse(fmMatch[1]) : {};
+    const componentIds = fm.components ?? [];
+    const comps = componentIds.map((id) => {
+        const c = findComponent(catalog, id);
+        if (!c)
+            throw new Error(`Component not found: ${id}`);
+        return c;
+    });
+    const [foundation, ...specs] = await Promise.all([
+        loadFoundation(specDir),
+        ...comps.map((c) => readFile(join(specDir, "components", c.file), "utf8")),
+    ]);
+    const parts = [
+        `<!-- ═══ PUDGE-UI FOUNDATION ═══ -->`,
+        foundation,
+        "",
+        `<!-- ═══ COMPOSITION: ${name} ═══ -->`,
+        raw,
+        "",
+    ];
+    comps.forEach((c, i) => {
+        parts.push(`<!-- ═══ COMPONENT: ${c.name} ═══ -->`);
+        parts.push(specs[i]);
+        parts.push("");
+    });
+    return parts.join("\n");
+}

package/dist/catalog.d.ts

@@ -0,0 +1,22 @@
+export interface Category {
+    id: string;
+    label: string;
+    prefix: string;
+    count: number;
+    description: string;
+}
+export interface Component {
+    id: string;
+    name: string;
+    class: string;
+    category: string;
+    file: string;
+    tags: string[];
+    description: string;
+}
+export interface Catalog {
+    categories: Category[];
+    components: Component[];
+}
+export declare function loadCatalog(specDir: string): Promise<Catalog>;
+export declare function findComponent(catalog: Catalog, id: string): Component | undefined;

package/dist/catalog.js

@@ -0,0 +1,10 @@
+import { readFile } from "node:fs/promises";
+import { join } from "node:path";
+import { parse } from "yaml";
+export async function loadCatalog(specDir) {
+    const raw = await readFile(join(specDir, "components", "_index.yaml"), "utf8");
+    return parse(raw);
+}
+export function findComponent(catalog, id) {
+    return catalog.components.find((c) => c.id === id || c.name.toLowerCase() === id.toLowerCase());
+}

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/index.js

@@ -0,0 +1,33 @@
+#!/usr/bin/env node
+import { readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { ListToolsRequestSchema, CallToolRequestSchema } from "@modelcontextprotocol/sdk/types.js";
+import { loadCatalog } from "./catalog.js";
+import { resolveSpecDir } from "./assembler.js";
+import { createSearchIndex } from "./search.js";
+import { toolDefinitions, handleTool } from "./tools.js";
+const pkg = JSON.parse(readFileSync(join(dirname(fileURLToPath(import.meta.url)), "..", "package.json"), "utf8"));
+const server = new Server({ name: "pudge-ui", version: pkg.version }, { capabilities: { tools: {} } });
+const specDir = resolveSpecDir();
+const catalog = await loadCatalog(specDir);
+const searchIndex = createSearchIndex(catalog.components);
+const ctx = { specDir, catalog, searchIndex };
+server.setRequestHandler(ListToolsRequestSchema, async () => ({
+    tools: toolDefinitions,
+}));
+server.setRequestHandler(CallToolRequestSchema, async (request) => {
+    const { name, arguments: args } = request.params;
+    try {
+        const text = await handleTool(name, args ?? {}, ctx);
+        return { content: [{ type: "text", text }] };
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        return { content: [{ type: "text", text: `Error: ${message}` }], isError: true };
+    }
+});
+const transport = new StdioServerTransport();
+await server.connect(transport);

package/dist/search.d.ts

@@ -0,0 +1,5 @@
+import Fuse from "fuse.js";
+import type { Component } from "./catalog.js";
+export type SearchIndex = Fuse<Component>;
+export declare function createSearchIndex(components: Component[]): SearchIndex;
+export declare function searchComponents(index: SearchIndex, query: string, limit?: number): Component[];

package/dist/search.js

@@ -0,0 +1,21 @@
+import Fuse from "fuse.js";
+export function createSearchIndex(components) {
+    return new Fuse(components, {
+        keys: [
+            { name: "name", weight: 2 },
+            { name: "description", weight: 1.5 },
+            { name: "tagsJoined", weight: 1 },
+            { name: "category", weight: 0.5 },
+        ],
+        threshold: 0.4,
+        getFn: (obj, path) => {
+            const key = Array.isArray(path) ? path[0] : path;
+            if (key === "tagsJoined")
+                return obj.tags.join(" ");
+            return obj[key];
+        },
+    });
+}
+export function searchComponents(index, query, limit = 10) {
+    return index.search(query, { limit }).map((r) => r.item);
+}

package/dist/tools.d.ts

@@ -0,0 +1,105 @@
+import type { Catalog } from "./catalog.js";
+import type { SearchIndex } from "./search.js";
+export interface ToolContext {
+    specDir: string;
+    catalog: Catalog;
+    searchIndex: SearchIndex;
+}
+export declare const toolDefinitions: ({
+    name: string;
+    description: string;
+    inputSchema: {
+        type: "object";
+        properties: {
+            category: {
+                type: string;
+                description: string;
+            };
+            query?: undefined;
+            limit?: undefined;
+            extended?: undefined;
+            name?: undefined;
+            names?: undefined;
+        };
+        required?: undefined;
+    };
+} | {
+    name: string;
+    description: string;
+    inputSchema: {
+        type: "object";
+        properties: {
+            query: {
+                type: string;
+                description: string;
+            };
+            limit: {
+                type: string;
+                description: string;
+            };
+            category?: undefined;
+            extended?: undefined;
+            name?: undefined;
+            names?: undefined;
+        };
+        required: string[];
+    };
+} | {
+    name: string;
+    description: string;
+    inputSchema: {
+        type: "object";
+        properties: {
+            extended: {
+                type: string;
+                description: string;
+            };
+            category?: undefined;
+            query?: undefined;
+            limit?: undefined;
+            name?: undefined;
+            names?: undefined;
+        };
+        required?: undefined;
+    };
+} | {
+    name: string;
+    description: string;
+    inputSchema: {
+        type: "object";
+        properties: {
+            name: {
+                type: string;
+                description: string;
+            };
+            category?: undefined;
+            query?: undefined;
+            limit?: undefined;
+            extended?: undefined;
+            names?: undefined;
+        };
+        required: string[];
+    };
+} | {
+    name: string;
+    description: string;
+    inputSchema: {
+        type: "object";
+        properties: {
+            names: {
+                type: string;
+                items: {
+                    type: string;
+                };
+                description: string;
+            };
+            category?: undefined;
+            query?: undefined;
+            limit?: undefined;
+            extended?: undefined;
+            name?: undefined;
+        };
+        required: string[];
+    };
+})[];
+export declare function handleTool(toolName: string, args: Record<string, unknown>, ctx: ToolContext): Promise<string>;

package/dist/tools.js

@@ -0,0 +1,129 @@
+import { searchComponents } from "./search.js";
+import { loadFoundation, assembleComponent, assembleComponents, assembleComposition, } from "./assembler.js";
+export const toolDefinitions = [
+    {
+        name: "list_components",
+        description: "List all pudge-ui components, optionally filtered by category.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                category: {
+                    type: "string",
+                    description: "Filter by category id (e.g. 'buttons', 'toggles')",
+                },
+            },
+        },
+    },
+    {
+        name: "search_components",
+        description: "Fuzzy search pudge-ui components by name, description, or tags.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                query: { type: "string", description: "Search query" },
+                limit: { type: "number", description: "Max results (default 10)" },
+            },
+            required: ["query"],
+        },
+    },
+    {
+        name: "get_foundation",
+        description: "Get pudge-ui foundation spec (philosophy, tokens, materials, depth, naming). Set extended=true for all 9 docs.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                extended: {
+                    type: "boolean",
+                    description: "Include all 9 foundation docs (default: core 5)",
+                },
+            },
+        },
+    },
+    {
+        name: "get_component",
+        description: "Get full spec for a single pudge-ui component (foundation + component spec).",
+        inputSchema: {
+            type: "object",
+            properties: {
+                name: {
+                    type: "string",
+                    description: "Component id or name (e.g. 'push-button' or 'Push Button')",
+                },
+            },
+            required: ["name"],
+        },
+    },
+    {
+        name: "get_components",
+        description: "Get full specs for multiple pudge-ui components (foundation included once).",
+        inputSchema: {
+            type: "object",
+            properties: {
+                names: {
+                    type: "array",
+                    items: { type: "string" },
+                    description: "Array of component ids or names",
+                },
+            },
+            required: ["names"],
+        },
+    },
+    {
+        name: "get_composition",
+        description: "Get a pudge-ui composition spec with all referenced component specs.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                name: { type: "string", description: "Composition name (e.g. 'audio-mixer-strip')" },
+            },
+            required: ["name"],
+        },
+    },
+];
+function asString(value, field) {
+    if (typeof value !== "string" || value.trim() === "") {
+        throw new Error(`"${field}" must be a non-empty string`);
+    }
+    return value;
+}
+function asStringArray(value, field) {
+    if (!Array.isArray(value) ||
+        value.length === 0 ||
+        !value.every((v) => typeof v === "string" && v.trim() !== "")) {
+        throw new Error(`"${field}" must be a non-empty array of strings`);
+    }
+    return value;
+}
+function asLimit(value) {
+    if (value === undefined)
+        return 10;
+    if (typeof value !== "number" || !Number.isFinite(value)) {
+        throw new Error(`"limit" must be a number`);
+    }
+    return Math.max(1, Math.min(50, Math.floor(value)));
+}
+export async function handleTool(toolName, args, ctx) {
+    switch (toolName) {
+        case "list_components": {
+            const category = args.category === undefined ? undefined : asString(args.category, "category");
+            const list = category
+                ? ctx.catalog.components.filter((c) => c.category === category)
+                : ctx.catalog.components;
+            return JSON.stringify(list.map(({ id, name, category, description }) => ({ id, name, category, description })), null, 2);
+        }
+        case "search_components": {
+            const results = searchComponents(ctx.searchIndex, asString(args.query, "query"), asLimit(args.limit));
+            return JSON.stringify(results.map(({ id, name, category, description }) => ({ id, name, category, description })), null, 2);
+        }
+        case "get_foundation":
+            return loadFoundation(ctx.specDir, args.extended === true);
+        case "get_component":
+            return assembleComponent(ctx.specDir, ctx.catalog, asString(args.name, "name"));
+        case "get_components":
+            return assembleComponents(ctx.specDir, ctx.catalog, asStringArray(args.names, "names"));
+        case "get_composition":
+            return assembleComposition(ctx.specDir, ctx.catalog, asString(args.name, "name"));
+        default:
+            throw new Error(`Unknown tool: ${toolName}`);
+    }
+}