@cooperco/component-library-mcp-server 0.1.0

package/README.md

@@ -0,0 +1,106 @@
+# @cooperco/component-library-mcp-server
+
+MCP (Model Context Protocol) server for the Cooper Component Library. Gives AI assistants like Claude Code access to component documentation, prop types, color palettes, passthrough configs, and scaffolding tools.
+
+## Install
+
+```bash
+npm install -g @cooperco/component-library-mcp-server
+# or use npx (no install needed)
+```
+
+## Configure Claude Code
+
+Add to your project's `.claude/settings.json`:
+
+```json
+{
+  "mcpServers": {
+    "cooper-components": {
+      "command": "npx",
+      "args": ["-y", "@cooperco/component-library-mcp-server"]
+    }
+  }
+}
+```
+
+The server auto-detects the project root by walking up from the working directory looking for `src/components/components.ts`.
+
+### Explicit project path
+
+If auto-detection doesn't work (e.g., you're in a monorepo), pass the path explicitly:
+
+```json
+{
+  "mcpServers": {
+    "cooper-components": {
+      "command": "npx",
+      "args": ["-y", "@cooperco/component-library-mcp-server", "/path/to/Cordblood-Component-Library"]
+    }
+  }
+}
+```
+
+Or use an environment variable:
+
+```json
+{
+  "mcpServers": {
+    "cooper-components": {
+      "command": "npx",
+      "args": ["-y", "@cooperco/component-library-mcp-server"],
+      "env": {
+        "COOPER_PROJECT_ROOT": "/path/to/Cordblood-Component-Library"
+      }
+    }
+  }
+}
+```
+
+### Local development (within this repo)
+
+When working in the component library repo itself, use the local build:
+
+```json
+{
+  "mcpServers": {
+    "cooper-components": {
+      "command": "node",
+      "args": ["mcp/dist/index.js"]
+    }
+  }
+}
+```
+
+## Tools
+
+| Tool | Description |
+|------|-------------|
+| `list-components` | List all components with categories, variants, and descriptions |
+| `get-component` | Full docs for a component: props, events, slots, passthrough, and source code |
+| `get-component-props` | Focused prop table with types, defaults, and required status |
+| `get-color-palettes` | Color palette system: available palettes, structure, and usage |
+| `get-passthrough-config` | Passthrough keys and default Tailwind classes for a component |
+| `search-components` | Search components by name, category, or prop names |
+| `scaffold-component` | Generate a new component with .vue, .ts, and .stories.ts files |
+
+## Examples
+
+Once configured, Claude Code can use the tools automatically:
+
+- *"What components are available?"* → calls `list-components`
+- *"Show me the props for ContainerModule"* → calls `get-component`
+- *"What color palettes can I use?"* → calls `get-color-palettes`
+- *"Create a new BannerModule component"* → calls `scaffold-component`
+
+## How it works
+
+The server reads your component library source files at runtime:
+
+- Parses TypeScript interfaces from `ComponentName.ts` files using the TypeScript Compiler API
+- Extracts `withDefaults`, `defineEmits`, and `<slot>` usage from `.vue` files
+- Reads passthrough configurations from `src/config/defaultPassthrough/index.ts`
+- Reads color palettes from `src/config/colorPalettes.ts`
+- Discovers components from `src/components/components.ts` barrel exports
+
+Results are cached in memory and invalidated when source files change, so documentation is always current.

package/dist/index.d.ts

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

package/dist/index.js

@@ -0,0 +1,55 @@
+#!/usr/bin/env node
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { ComponentRegistry } from './registry/component-registry.js';
+import { registerAllTools } from './server.js';
+import fs from 'fs';
+import path from 'path';
+import { createRequire } from 'module';
+const resolveProjectRoot = () => {
+    // 1. Explicit env var override
+    if (process.env.COOPER_PROJECT_ROOT) {
+        return path.resolve(process.env.COOPER_PROJECT_ROOT);
+    }
+    // 2. CLI argument: node dist/index.js /path/to/project
+    const cliArg = process.argv[2];
+    if (cliArg && !cliArg.startsWith('-')) {
+        return path.resolve(cliArg);
+    }
+    // 3. Walk up from cwd looking for src/components/components.ts
+    let dir = process.cwd();
+    while (dir !== path.dirname(dir)) {
+        if (fs.existsSync(path.join(dir, 'src/components/components.ts'))) {
+            return dir;
+        }
+        dir = path.dirname(dir);
+    }
+    // 4. Fall back to cwd
+    return process.cwd();
+};
+const main = async () => {
+    const projectRoot = resolveProjectRoot();
+    // Validate the project root has the expected structure
+    const barrelPath = path.join(projectRoot, 'src/components/components.ts');
+    if (!fs.existsSync(barrelPath)) {
+        process.stderr.write(`Error: Could not find component library at ${projectRoot}\n` +
+            `Expected to find: ${barrelPath}\n\n` +
+            `Set COOPER_PROJECT_ROOT env var or pass the path as an argument:\n` +
+            `  npx @cooperco/component-library-mcp-server /path/to/Cordblood-Component-Library\n`);
+        process.exit(1);
+    }
+    const require = createRequire(import.meta.url);
+    const { version } = require('../package.json');
+    const server = new McpServer({
+        name: 'cooper-component-library',
+        version,
+    });
+    const registry = new ComponentRegistry(projectRoot);
+    registerAllTools(server, registry, projectRoot);
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+};
+main().catch((error) => {
+    process.stderr.write(`Fatal error: ${error}\n`);
+    process.exit(1);
+});

package/dist/parsers/passthrough-parser.d.ts

@@ -0,0 +1,13 @@
+import { PassthroughKeyInfo } from '../types.js';
+interface ParsedPassthrough {
+    name: string;
+    variants: Record<string, PassthroughKeyInfo[]> | null;
+    keys: PassthroughKeyInfo[];
+}
+export declare const parsePassthroughFile: (source: string) => ParsedPassthrough[];
+/**
+ * Extracts the DEFAULT_PASSTHROUGH key-value pairs from the passthrough index source.
+ */
+export declare const parseDefaultPassthrough: (source: string) => PassthroughKeyInfo[];
+export declare const findPassthroughForComponent: (passthroughs: ParsedPassthrough[], componentName: string) => ParsedPassthrough | null;
+export {};

package/dist/parsers/passthrough-parser.js

@@ -0,0 +1,115 @@
+export const parsePassthroughFile = (source) => {
+    const results = [];
+    // Find all exported const declarations
+    const exportMatches = source.matchAll(/export const (\w+Pt\w*)\s*(?::\s*\w+\s*)?=\s*/g);
+    for (const match of exportMatches) {
+        const name = match[1];
+        const startIndex = (match.index ?? 0) + match[0].length;
+        // Determine if this is a variant-based passthrough (has nested keys like { Centered: ..., Hero: ... })
+        // or a flat passthrough
+        const rest = source.slice(startIndex);
+        if (rest.startsWith('{') && isVariantObject(rest)) {
+            const variants = parseVariantPassthrough(rest);
+            results.push({ name, variants, keys: [] });
+        }
+        else {
+            const keys = parseFlatPassthrough(rest);
+            results.push({ name, variants: null, keys });
+        }
+    }
+    return results;
+};
+const isVariantObject = (source) => {
+    // Variant objects have keys like List:, Tile:, Centered:, Hero:, link:, fill: at the top level
+    // Supports both capitalized (List, Hero) and lowercase (link, fill) variant keys
+    const variantPattern = /^\{\s*\n\s*(\w+)\s*:\s*(?:\{|combinePassthroughs)/;
+    return variantPattern.test(source);
+};
+const extractBalancedBraces = (source, start) => {
+    let depth = 0;
+    for (let i = start; i < source.length; i++) {
+        if (source[i] === '{')
+            depth++;
+        else if (source[i] === '}') {
+            depth--;
+            if (depth === 0)
+                return source.slice(start + 1, i);
+        }
+    }
+    return '';
+};
+const parseVariantPassthrough = (source) => {
+    const variants = {};
+    // First, extract only the outer object's content using balanced braces
+    const outerContent = extractBalancedBraces(source, 0);
+    if (!outerContent)
+        return variants;
+    // Match variant keys at the first indentation level (tab or spaces)
+    const variantKeyPattern = /(?:^|\n)\s+(\w+)\s*:\s*/g;
+    for (const match of outerContent.matchAll(variantKeyPattern)) {
+        const variantName = match[1];
+        const afterKey = (match.index ?? 0) + match[0].length;
+        const rest = outerContent.slice(afterKey);
+        if (rest.startsWith('combinePassthroughs(')) {
+            // Extract the override object (second argument)
+            const overrideMatch = rest.match(/combinePassthroughs\(\s*(?:\{[^}]*\}|[^,]+),\s*\{([^}]*)\}/s);
+            if (overrideMatch) {
+                variants[variantName] = parseKeyValuePairs(overrideMatch[1]);
+            }
+            else {
+                variants[variantName] = [];
+            }
+        }
+        else if (rest.startsWith('{')) {
+            // Use balanced brace extraction for nested objects
+            const block = extractBalancedBraces(rest, 0);
+            variants[variantName] = parseKeyValuePairs(block);
+        }
+    }
+    return variants;
+};
+const parseFlatPassthrough = (source) => {
+    // Check if it starts with combinePassthroughs(
+    if (source.startsWith('combinePassthroughs(')) {
+        // Extract the override object (second argument)
+        const overrideMatch = source.match(/combinePassthroughs\(\s*(?:\{[^}]*\}|[^,]+),\s*\{([^}]*)\}/s);
+        if (overrideMatch) {
+            return parseKeyValuePairs(overrideMatch[1]);
+        }
+        return [];
+    }
+    // Direct object literal
+    const objectMatch = source.match(/^\{([^}]*)\}/s);
+    if (objectMatch) {
+        return parseKeyValuePairs(objectMatch[1]);
+    }
+    return [];
+};
+const parseKeyValuePairs = (block) => {
+    const keys = [];
+    // Match key: 'value' or key: `value` or key: "value"
+    const pairs = block.matchAll(/(\w+)\s*:\s*(?:'([^']*)'|`([^`]*)`|"([^"]*)")/g);
+    for (const pair of pairs) {
+        const key = pair[1];
+        const value = pair[2] ?? pair[3] ?? pair[4] ?? '';
+        keys.push({ key, defaultClasses: value.trim() });
+    }
+    return keys;
+};
+/**
+ * Extracts the DEFAULT_PASSTHROUGH key-value pairs from the passthrough index source.
+ */
+export const parseDefaultPassthrough = (source) => {
+    const match = source.match(/export const DEFAULT_PASSTHROUGH\s*(?::\s*\w+\s*)?=\s*\{([^}]+)\}/s);
+    if (!match)
+        return [];
+    return parseKeyValuePairs(match[1]);
+};
+export const findPassthroughForComponent = (passthroughs, componentName) => {
+    // Try exact match first (e.g., "ContainerModulePt")
+    const exact = passthroughs.find((pt) => pt.name === `${componentName}Pt`);
+    if (exact)
+        return exact;
+    // Try partial match
+    return (passthroughs.find((pt) => pt.name.toLowerCase().startsWith(componentName.toLowerCase())) ?? null);
+};

package/dist/parsers/typescript-parser.d.ts

@@ -0,0 +1,11 @@
+import { PropInfo } from '../types.js';
+interface ParsedInterface {
+    name: string;
+    extendsTypes: string[];
+    props: PropInfo[];
+}
+export declare const parseTypeScriptFile: (source: string, filename: string) => ParsedInterface[];
+export declare const findMainInterface: (interfaces: ParsedInterface[], componentName: string) => ParsedInterface | null;
+export declare const findPassthroughInterface: (interfaces: ParsedInterface[]) => ParsedInterface | null;
+export declare const extractVariantsFromProp: (prop: PropInfo) => string[];
+export {};

package/dist/parsers/typescript-parser.js

@@ -0,0 +1,77 @@
+import ts from 'typescript';
+export const parseTypeScriptFile = (source, filename) => {
+    const sourceFile = ts.createSourceFile(filename, source, ts.ScriptTarget.Latest, true);
+    const interfaces = [];
+    ts.forEachChild(sourceFile, (node) => {
+        if (ts.isInterfaceDeclaration(node)) {
+            const name = node.name.text;
+            const extendsTypes = [];
+            if (node.heritageClauses) {
+                for (const clause of node.heritageClauses) {
+                    for (const type of clause.types) {
+                        extendsTypes.push(type.expression.getText(sourceFile));
+                    }
+                }
+            }
+            const props = [];
+            for (const member of node.members) {
+                if (ts.isPropertySignature(member) && member.name) {
+                    const propName = member.name.getText(sourceFile);
+                    const isOptional = !!member.questionToken;
+                    const typeText = member.type
+                        ? member.type.getText(sourceFile)
+                        : 'unknown';
+                    let description;
+                    const jsDocTags = ts.getJSDocTags(member);
+                    if (jsDocTags.length > 0) {
+                        description = jsDocTags
+                            .map((tag) => tag.comment?.toString() ?? '')
+                            .filter(Boolean)
+                            .join(' ');
+                    }
+                    // Also check for leading JSDoc comments
+                    const fullText = member.getFullText(sourceFile);
+                    const jsDocMatch = fullText.match(/\/\*\*\s*\n?\s*\*?\s*(.+?)\s*\*?\s*\*\//);
+                    if (jsDocMatch && !description) {
+                        description = jsDocMatch[1].trim();
+                    }
+                    props.push({
+                        name: propName,
+                        type: typeText,
+                        required: !isOptional,
+                        description,
+                    });
+                }
+            }
+            interfaces.push({ name, extendsTypes, props });
+        }
+    });
+    return interfaces;
+};
+export const findMainInterface = (interfaces, componentName) => {
+    // First try exact match
+    const exact = interfaces.find((i) => i.name === componentName);
+    if (exact)
+        return exact;
+    // Then try matching interfaces that extend Component
+    const extending = interfaces.find((i) => i.extendsTypes.includes('Component'));
+    if (extending)
+        return extending;
+    // Fall back to first interface that isn't a passthrough
+    return (interfaces.find((i) => !i.name.toLowerCase().includes('passthrough') &&
+        !i.name.toLowerCase().includes('pt')) ?? null);
+};
+export const findPassthroughInterface = (interfaces) => {
+    return (interfaces.find((i) => i.name.toLowerCase().includes('passthrough') &&
+        (i.extendsTypes.includes('ComponentPassthrough') ||
+            i.extendsTypes.includes('GenericComponentPassthrough') ||
+            i.extendsTypes.length > 0)) ?? null);
+};
+export const extractVariantsFromProp = (prop) => {
+    // Match union literal types like "'Centered' | 'Hero'"
+    const matches = prop.type.match(/'([^']+)'/g);
+    if (matches) {
+        return matches.map((m) => m.replace(/'/g, ''));
+    }
+    return [];
+};

package/dist/parsers/vue-sfc-parser.d.ts

@@ -0,0 +1,10 @@
+import { EmitInfo, SlotInfo } from '../types.js';
+interface VueSfcData {
+    interfaceName: string | null;
+    defaults: Record<string, string>;
+    emits: EmitInfo[];
+    slots: SlotInfo[];
+    usesColorPalette: boolean;
+}
+export declare const parseVueSfc: (source: string) => VueSfcData;
+export {};

package/dist/parsers/vue-sfc-parser.js

@@ -0,0 +1,61 @@
+export const parseVueSfc = (source) => {
+    const interfaceName = extractInterfaceName(source);
+    const defaults = extractDefaults(source);
+    const emits = extractEmits(source);
+    const slots = extractSlots(source);
+    const usesColorPalette = source.includes('withColorPalette');
+    return { interfaceName, defaults, emits, slots, usesColorPalette };
+};
+const extractInterfaceName = (source) => {
+    const match = source.match(/defineProps<(\w+)>/);
+    return match ? match[1] : null;
+};
+const extractDefaults = (source) => {
+    const defaults = {};
+    // Match withDefaults block - handle multi-line
+    const match = source.match(/withDefaults\(defineProps<\w+>\(\),\s*\{([^}]+)\}\)/s);
+    if (!match)
+        return defaults;
+    const block = match[1];
+    // Match each key: value pair
+    const pairs = block.matchAll(/(\w+)\s*:\s*(.+?)(?:,\s*$|\s*$)/gm);
+    for (const pair of pairs) {
+        const key = pair[1].trim();
+        const value = pair[2].trim().replace(/,$/, '').trim();
+        if (key && value) {
+            defaults[key] = value;
+        }
+    }
+    return defaults;
+};
+const extractEmits = (source) => {
+    const emits = [];
+    // Match defineEmits(['name1', 'name2'])
+    const match = source.match(/defineEmits\(\[([^\]]+)\]\)/);
+    if (match) {
+        const names = match[1].matchAll(/'([^']+)'/g);
+        for (const name of names) {
+            emits.push({ name: name[1] });
+        }
+    }
+    return emits;
+};
+const extractSlots = (source) => {
+    const slots = [];
+    const seen = new Set();
+    // Extract <template> section
+    const templateMatch = source.match(/<template>([\s\S]*)<\/template>/);
+    if (!templateMatch)
+        return slots;
+    const template = templateMatch[1];
+    // Match <slot /> and <slot name="xxx" />
+    const slotMatches = template.matchAll(/<slot\s*(?:name="([\w-]+)")?\s*\/?>/g);
+    for (const match of slotMatches) {
+        const name = match[1] ?? 'default';
+        if (!seen.has(name)) {
+            seen.add(name);
+            slots.push({ name });
+        }
+    }
+    return slots;
+};

package/dist/registry/component-descriptions.d.ts

@@ -0,0 +1 @@
+export declare const getComponentDescription: (componentName: string) => string;

package/dist/registry/component-descriptions.js

@@ -0,0 +1,43 @@
+const COMPONENT_DESCRIPTIONS = {
+    Accordion: 'Expandable content sections with List and Tile variants',
+    AccordionItem: 'Individual accordion panel with header and collapsible body',
+    AccordionListItem: 'List-style accordion item with bordered layout',
+    AccordionTileItem: 'Tile-style accordion item with card layout',
+    CarouselModule: 'Carousel/slider for content collections with navigation controls',
+    ContainerModule: 'Layout container with start/end content slots (Centered/Hero variants)',
+    ContentModule: 'Rich text content block with headline, body copy, and CTAs',
+    ContainerCollectionModule: 'Collection of ContainerModule components',
+    CTA: 'Call-to-action button/link (fill, outline, link, logo types)',
+    FooterNavigation: 'Footer navigation with grouped links',
+    FooterCopyright: 'Footer copyright text and legal links',
+    SocialMediaRef: 'Social media icon link',
+    Image: 'Responsive image with mobile variant and animation support',
+    LogoCollectionModule: 'Grid of logo images',
+    NavigationElement: 'Navigation link item with optional icon',
+    PrimaryNavigation: 'Top-level navigation bar',
+    SplitModule: 'Three-column layout with start/center/end slots',
+    TestimonialModule: 'Testimonial with quote, author, and media',
+    TileCollectionModule: 'Grid/collection of tile components',
+    TileContentIconTile: 'Tile with icon, headline, and body',
+    TileContentImageTile: 'Tile with image, headline, and body',
+    TileContentTextTile: 'Text-only tile with headline and body',
+    TileContentVideoTile: 'Tile with embedded video',
+    TileContentImageStackedAnimatedTile: 'Animated stacked image tile',
+    Video: 'Video player component with thumbnail',
+    AnimationWrapper: 'Wrapper that adds scroll-triggered animations',
+    HelloBar: 'Top-of-page announcement banner',
+};
+/**
+ * Splits a PascalCase name into human-readable words.
+ * E.g., "CarouselModule" -> "Carousel module", "CTA" -> "CTA"
+ */
+const humanizePascalCase = (name) => {
+    const words = name.replace(/([a-z])([A-Z])/g, '$1 $2').split(' ');
+    return words
+        .map((word, index) => (index === 0 ? word : word.toLowerCase()))
+        .join(' ');
+};
+export const getComponentDescription = (componentName) => {
+    return (COMPONENT_DESCRIPTIONS[componentName] ??
+        `${humanizePascalCase(componentName)} component`);
+};

package/dist/registry/component-registry.d.ts

@@ -0,0 +1,23 @@
+import { ComponentMetadata, ComponentDiscovery, PassthroughKeyInfo } from '../types.js';
+export declare class ComponentRegistry {
+    private cache;
+    private discoveryCache;
+    private discoveryMtime;
+    private passthroughCache;
+    private passthroughMtime;
+    private projectRoot;
+    constructor(projectRoot: string);
+    discoverComponents(): Promise<ComponentDiscovery[]>;
+    getComponent(name: string): Promise<ComponentMetadata | null>;
+    listComponents(): Promise<ComponentMetadata[]>;
+    searchComponents(query: string, category?: 'component' | 'module' | 'all'): Promise<ComponentMetadata[]>;
+    getPassthroughForComponent(componentName: string): Promise<{
+        variants: Record<string, PassthroughKeyInfo[]> | null;
+        keys: PassthroughKeyInfo[];
+    } | null>;
+    getColorPalettes(): Promise<string>;
+    getDefaultPassthrough(): Promise<PassthroughKeyInfo[]>;
+    componentExists(name: string): Promise<boolean>;
+    private loadPassthroughs;
+    private parseComponent;
+}