@gemini-designer/mcp-server 0.1.0

package/src/tools/catalog-components.ts

@@ -0,0 +1,99 @@
+/**
+ * catalog_components Tool
+ *
+ * Builds a machine-readable catalog of exported components in the codebase.
+ *
+ * Why this matters:
+ * - Lets create_ui/snippet_ui/modify_ui match existing patterns
+ * - Enables component-library detection & reuse instead of regenerating duplicates
+ * - Grounding data for agents (props, file paths, exports)
+ */
+
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { z } from 'zod';
+import * as path from 'node:path';
+import { Config } from '../config/index.js';
+import { assertReadableDir } from '../context/guards.js';
+import { walkFiles, toPosixPath } from '../utils/walk.js';
+import { buildComponentCatalog } from '../components/catalog.js';
+
+const inputSchema = {
+    roots: z
+        .array(z.string())
+        .optional()
+        .describe('Directories to scan (defaults to ["src"]).'),
+    extensions: z
+        .array(z.string())
+        .optional()
+        .describe('File extensions to include (defaults to [".tsx", ".jsx"]).'),
+    maxFiles: z
+        .number()
+        .int()
+        .min(1)
+        .max(50_000)
+        .default(2000)
+        .describe('Safety limit to avoid scanning huge repos.'),
+};
+
+export function registerCatalogComponents(server: McpServer, config: Config): void {
+    server.registerTool(
+        'catalog_components',
+        {
+            title: 'Catalog Components',
+            description: 'Scan the repo and return a JSON catalog of exported components (no LLM).',
+            inputSchema,
+        },
+        async (args) => {
+            const roots = (args.roots as string[] | undefined) || ['src'];
+            const extensions = (args.extensions as string[] | undefined) || ['.tsx', '.jsx'];
+            const maxFiles = (args.maxFiles as number | undefined) || 2000;
+
+            const safeRoots: string[] = [];
+            for (const r of roots) {
+                try {
+                    safeRoots.push(assertReadableDir(r, config));
+                } catch (error) {
+                    const message = error instanceof Error ? error.message : 'Invalid root';
+                    return {
+                        content: [{ type: 'text' as const, text: `Error: ${message}` }],
+                        isError: true,
+                    };
+                }
+            }
+
+            const allFiles: string[] = [];
+            for (const r of safeRoots) {
+                const found = walkFiles(r, { includeExtensions: extensions, maxFiles });
+                allFiles.push(...found);
+            }
+
+            // Use cwd as catalog root so paths are stable for agents
+            const root = path.resolve(process.cwd());
+
+            const catalog = await buildComponentCatalog(root, allFiles.map((f) => path.resolve(f)));
+
+            // Ensure POSIX paths
+            catalog.components = catalog.components.map((c) => ({ ...c, file: toPosixPath(c.file) }));
+            catalog.root = toPosixPath(catalog.root);
+
+            // Small summary
+            const summary = {
+                totalFiles: catalog.filesScanned,
+                totalComponents: catalog.components.length,
+                byExportType: {
+                    named: catalog.components.filter((c) => c.exportType === 'named').length,
+                    default: catalog.components.filter((c) => c.exportType === 'default').length,
+                },
+            };
+
+            return {
+                content: [
+                    {
+                        type: 'text' as const,
+                        text: JSON.stringify({ ...catalog, summary }, null, 2),
+                    },
+                ],
+            };
+        }
+    );
+}

package/src/tools/create-ui.ts

@@ -0,0 +1,194 @@
+/**
+ * create_ui Tool
+ *
+ * Scaffolds new UI components or views.
+ * Generates complete, responsive, accessible frontend code.
+ */
+
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { z } from 'zod';
+import { Config } from '../config/index.js';
+import { buildContext } from '../context/builder.js';
+import { assertWritablePath } from '../context/guards.js';
+import { generateWithGemini } from '../generation/gemini-client.js';
+import { writeFile } from '../output/file-writer.js';
+import { formatCode } from '../output/formatter.js';
+import { buildRepoHints } from '../context/repo-hints.js';
+
+const inputSchema = {
+    description: z.string().describe('Description of the UI to create (component or view)'),
+    framework: z.enum(['react', 'vue', 'svelte', 'html']).default('react'),
+    vibe: z.string().optional().describe('Design tokens/vibe from generate_vibes'),
+    contextFiles: z.array(z.string()).optional().describe('Paths to relevant UI files for context'),
+    targetPath: z.string().describe('Target file path to generate (e.g. src/components/Button.tsx)'),
+    includeStyles: z.boolean().default(true).describe('Include styling in the generated code'),
+    writeToFile: z.boolean().default(false).describe('Write the generated code to targetPath'),
+    backup: z.boolean().default(true).describe('Create .bak backup if overwriting an existing file'),
+    format: z.boolean().default(true).describe('Format the code with Prettier before returning/writing'),
+};
+
+const SYSTEM_PROMPT = `You are a senior frontend engineer and UI designer.
+
+Your task: generate a COMPLETE, production-ready UI implementation.
+
+Hard rules (must follow):
+- Output ONLY the final code. No explanations. No markdown. No code fences.
+- Use the specified framework and keep the code idiomatic for that ecosystem.
+- Do NOT introduce new dependencies unless the user explicitly asked to.
+- Accessibility: meet WCAG AA as a default.
+  - Semantic HTML, proper labels, aria-* where appropriate
+  - Keyboard navigation for all interactive elements
+  - Visible focus states (use :focus-visible patterns if relevant)
+- Responsive by default (mobile-first).
+- If design tokens / vibe are provided, use them (prefer CSS variables) and do not hard-code random colors.
+- Keep logic minimal and UI-focused; avoid fake backend calls.
+
+Quality bar:
+- TypeScript types where applicable
+- No unused imports/vars
+- Clean component structure and clear naming`;
+
+function buildUserPrompt(args: {
+    description: string;
+    framework: string;
+    vibe?: string;
+    context?: string;
+    targetPath: string;
+    includeStyles: boolean;
+    repoHints?: string;
+}): string {
+    return `Create UI code.
+
+${args.repoHints || ''}
+
+Framework: ${args.framework}
+Target file: ${args.targetPath}
+
+Description:
+${args.description}
+
+Design direction / tokens (if provided):
+${args.vibe || '(none)'}
+
+Project UI context (if provided):
+${args.context || '(none)'}
+
+Styling:
+- includeStyles = ${args.includeStyles}
+- If Tailwind classes appear in context, prefer Tailwind.
+- Otherwise use simple CSS variables + className patterns, minimal inline styles.
+
+Return ONLY the code for the target file.`;
+}
+
+/**
+ * Extract code from a model response that might contain fences.
+ * (We still tell the model not to use fences, but this makes the tool resilient.)
+ */
+function extractCode(response: string): string {
+    const codeBlockMatch = response.match(/```[a-zA-Z]*\n([\s\S]*?)```/);
+    if (codeBlockMatch) {
+        return codeBlockMatch[1].trim();
+    }
+    return response.trim();
+}
+
+export function registerCreateUI(server: McpServer, config: Config) {
+    server.registerTool(
+        'create_ui',
+        {
+            title: 'Create UI Component/View',
+            description: 'Generate a complete UI component or view from description and design vibe',
+            inputSchema,
+        },
+        async (args) => {
+            try {
+                const description = args.description as string;
+                const framework = (args.framework as string) || config.defaultFramework;
+                const vibe = args.vibe as string | undefined;
+                const contextFiles = (args.contextFiles as string[]) || [];
+                const targetPath = args.targetPath as string;
+                const includeStyles = args.includeStyles as boolean;
+                const writeToFile = args.writeToFile as boolean;
+                const backup = args.backup as boolean;
+                const format = args.format as boolean;
+
+                // Build context from files (token-optimized)
+                let context = '';
+                if (contextFiles.length > 0) {
+                    context = await buildContext(contextFiles, config);
+                }
+
+                const userPrompt = buildUserPrompt({
+                    description,
+                    framework,
+                    vibe,
+                    context,
+                    targetPath,
+                    includeStyles,
+                    repoHints: buildRepoHints(config),
+                });
+
+                if (config.debug) {
+                    console.error(`[create_ui] Generating UI for: ${description}`);
+                    console.error(`[create_ui] Framework: ${framework}`);
+                    console.error(`[create_ui] Context files: ${contextFiles.length}`);
+                }
+
+                // Generate code with Gemini
+                const response = await generateWithGemini(config, SYSTEM_PROMPT, userPrompt, { toolName: 'create_ui' });
+                let code = extractCode(response);
+
+                // Format if requested
+                if (format) {
+                    try {
+                        code = await formatCode(code, { filePath: targetPath });
+                    } catch {
+                        // ignore formatting errors
+                    }
+                }
+
+                // Write to file if requested
+                if (writeToFile) {
+                    const safePath = assertWritablePath(targetPath, config);
+                    const result = await writeFile(safePath, code, { backup, format });
+
+                    if (!result.success) {
+                        return {
+                            content: [
+                                {
+                                    type: 'text',
+                                    text: `Error writing file: ${result.error || 'Unknown error'}`,
+                                },
+                            ],
+                            isError: true,
+                        };
+                    }
+
+                    const msg = [
+                        `✅ UI written successfully.`,
+                        `File: ${result.filePath}`,
+                        result.backupPath ? `Backup: ${result.backupPath}` : undefined,
+                    ]
+                        .filter(Boolean)
+                        .join('\n');
+
+                    return {
+                        content: [{ type: 'text', text: msg }],
+                    };
+                }
+
+                // Return code only (no wrappers) for best compatibility with agents
+                return {
+                    content: [{ type: 'text', text: code }],
+                };
+            } catch (error) {
+                const message = error instanceof Error ? error.message : 'Unknown error';
+                return {
+                    content: [{ type: 'text', text: `Error: ${message}` }],
+                    isError: true,
+                };
+            }
+        }
+    );
+}

package/src/tools/detect-ui-stack.ts

@@ -0,0 +1,64 @@
+/**
+ * detect_ui_stack Tool
+ *
+ * Deterministically inspects the workspace to detect the UI stack:
+ * framework, styling approach, component libraries, storybook, etc.
+ *
+ * This tool is intentionally non-LLM to:
+ * - reduce token usage
+ * - increase reliability
+ * - enable downstream tools to condition prompts/outputs on real repo constraints
+ */
+
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { z } from 'zod';
+import * as path from 'node:path';
+import { Config } from '../config/index.js';
+import { assertReadableDir } from '../context/guards.js';
+import { detectUiStack } from '../stack/detect.js';
+
+const inputSchema = {
+    root: z
+        .string()
+        .optional()
+        .describe('Project root directory (defaults to current working directory)')
+        .default(process.cwd()),
+};
+
+export function registerDetectUIStack(server: McpServer, config: Config): void {
+    server.registerTool(
+        'detect_ui_stack',
+        {
+            title: 'Detect UI Stack',
+            description:
+                'Detect framework/styling/component libraries from the repo (no LLM). Useful to ground other tools.',
+            inputSchema,
+        },
+        async (args) => {
+            const root = (args.root as string) || process.cwd();
+
+            let safeRoot: string;
+            try {
+                safeRoot = assertReadableDir(root, config);
+            } catch (error) {
+                const message = error instanceof Error ? error.message : 'Invalid root directory';
+                return {
+                    content: [{ type: 'text' as const, text: `Error: ${message}` }],
+                    isError: true,
+                };
+            }
+
+            const result = detectUiStack(safeRoot);
+
+            // Normalize paths for agent readability
+            const normalized = {
+                ...result,
+                root: path.resolve(result.root),
+            };
+
+            return {
+                content: [{ type: 'text' as const, text: JSON.stringify(normalized, null, 2) }],
+            };
+        }
+    );
+}

package/src/tools/generate-component-variants.ts

@@ -0,0 +1,218 @@
+/**
+ * generate_component_variants Tool
+ *
+ * Given an existing component, generate variants (sizes, intents, states) and
+ * optional Storybook stories.
+ *
+ * Output contract:
+ * - When applyChanges=false: outputs ONE JSON object only:
+ *   {"files": [{"path": string, "content": string}]}
+ * - When applyChanges=true: writes files and returns a short summary string.
+ */
+
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { z } from 'zod';
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { Config } from '../config/index.js';
+import { buildContext } from '../context/builder.js';
+import { assertReadablePath, assertWritablePath } from '../context/guards.js';
+import { buildRepoGrounding } from '../context/grounding.js';
+import { generateWithGemini } from '../generation/gemini-client.js';
+import { writeFile } from '../output/file-writer.js';
+
+const inputSchema = {
+    componentFile: z.string().describe('Path to an existing component file (e.g., src/components/Button.tsx).'),
+    variants: z
+        .object({
+            sizes: z.array(z.string()).optional(),
+            intents: z.array(z.string()).optional(),
+            states: z.array(z.string()).optional(),
+            themes: z.array(z.string()).optional(),
+            custom: z.array(z.string()).optional().describe('Any additional variant requirements.'),
+        })
+        .optional()
+        .describe('Variant dimensions to generate.'),
+    instruction: z.string().optional().describe('Extra guidance about behavior, styling, or API.'),
+    storybook: z.boolean().default(true).describe('Generate a Storybook stories file if true.'),
+    storyFile: z.string().optional().describe('Optional path for the stories file (defaults next to component).'),
+    context: z.array(z.string()).optional().describe('Related files (tokens, theme, utilities).'),
+    applyChanges: z.boolean().default(false).describe('If true, write files to disk.'),
+    backup: z.boolean().default(true).describe('Create .bak backups before overwriting existing files.'),
+};
+
+const SYSTEM_PROMPT = `You are a senior frontend engineer specializing in reusable component APIs.
+
+Your task:
+- Update an existing component to support the requested variants.
+- Preserve existing behavior and imports unless required.
+- Keep code style consistent with the file.
+- Ensure accessibility: keyboard/focus, aria-labels, disabled states.
+
+Repo alignment (CRITICAL):
+- Prefer reusing existing utilities/components already present in the repo.
+- You will receive an auto-detected stack summary + component catalog; do not invent duplicates.
+
+Output contract (CRITICAL):
+- If storybook=true, output JSON with an array of files: {"files": [{"path": string, "content": string}]}
+- If storybook=false, output JSON with exactly one file (the component file).
+- Output MUST be ONE valid JSON object only. No prose. No markdown. No code fences.
+
+API guidance:
+- Prefer adding/expanding a typed prop such as "size" | "variant" | "intent" and mapping to classes.
+- Avoid breaking changes: keep default props aligned to existing visuals.
+- Do not introduce new dependencies unless explicitly requested.`;
+
+function cleanJson(response: string): string {
+    let out = response.trim();
+    const fenced = out.match(/```(?:json)?\n([\s\S]*?)```/);
+    if (fenced) out = fenced[1].trim();
+    return out;
+}
+
+function defaultStoryPath(componentFile: string): string {
+    const dir = path.dirname(componentFile);
+    const base = path.basename(componentFile).replace(/\.(tsx|jsx|ts|js)$/, '');
+    return path.join(dir, `${base}.stories.tsx`);
+}
+
+export function registerGenerateComponentVariants(server: McpServer, config: Config): void {
+    server.registerTool(
+        'generate_component_variants',
+        {
+            title: 'Generate Component Variants',
+            description:
+                'Enhance an existing component with variants (sizes/intents/states) and optionally generate Storybook stories.',
+            inputSchema,
+        },
+        async (args) => {
+            const componentFile = args.componentFile as string;
+            const variants = (args.variants as any) || {};
+            const instruction = (args.instruction as string | undefined) || '';
+            const storybook = args.storybook !== false;
+            const storyFile = (args.storyFile as string | undefined) || defaultStoryPath(componentFile);
+            const contextPaths = args.context as string[] | undefined;
+            const applyChanges = args.applyChanges === true;
+            const backup = args.backup !== false;
+
+            let safeComponent: string;
+            try {
+                safeComponent = assertReadablePath(componentFile, config);
+            } catch (error) {
+                const message = error instanceof Error ? error.message : 'Invalid componentFile';
+                return { content: [{ type: 'text' as const, text: `Error: ${message}` }], isError: true };
+            }
+
+            let componentContent: string;
+            try {
+                componentContent = fs.readFileSync(safeComponent, 'utf-8');
+            } catch {
+                return {
+                    content: [{ type: 'text' as const, text: `Error: Could not read ${componentFile}` }],
+                    isError: true,
+                };
+            }
+
+            let contextContent = '';
+            if (contextPaths && contextPaths.length > 0) {
+                contextContent = await buildContext(contextPaths, config);
+            }
+
+            // Deterministic repo grounding (stack + reusable components)
+            const grounding = await buildRepoGrounding(config, {
+                focusFileAbs: safeComponent,
+                instruction,
+            });
+
+            const userPrompt = `Enhance the component to support variants.
+
+${grounding}
+
+COMPONENT FILE PATH:
+${componentFile}
+
+VARIANTS (JSON):
+${JSON.stringify(variants, null, 2)}
+
+STORYBOOK:
+${storybook}
+
+STORY FILE PATH (if storybook=true):
+${storyFile}
+
+EXTRA INSTRUCTION:
+${instruction || '(none)'}
+
+CURRENT COMPONENT FILE CONTENT:
+${componentContent}
+
+${contextContent ? `RELATED FILES FOR CONTEXT:\n${contextContent}` : ''}
+
+Remember: Output JSON only: {"files": [{"path": string, "content": string}]}`;
+
+            try {
+                const resp = await generateWithGemini(config, SYSTEM_PROMPT, userPrompt, {
+                    toolName: 'generate_component_variants',
+                });
+                const cleaned = cleanJson(resp);
+                const parsed = JSON.parse(cleaned) as { files?: Array<{ path: string; content: string }> };
+
+                if (!parsed || !Array.isArray(parsed.files) || parsed.files.length === 0) {
+                    return {
+                        content: [
+                            {
+                                type: 'text' as const,
+                                text: 'Error: Model output did not match expected JSON format: {"files": [...]}',
+                            },
+                        ],
+                        isError: true,
+                    };
+                }
+
+                if (!applyChanges) {
+                    return { content: [{ type: 'text' as const, text: JSON.stringify(parsed, null, 2) }] };
+                }
+
+                const writes: Array<{ file: string; backup?: string }> = [];
+                for (const f of parsed.files) {
+                    const target = f.path;
+                    const content = f.content;
+                    let safeOut: string;
+                    try {
+                        safeOut = assertWritablePath(target, config);
+                    } catch (error) {
+                        const message = error instanceof Error ? error.message : 'Invalid output path';
+                        return { content: [{ type: 'text' as const, text: `Error: ${message}` }], isError: true };
+                    }
+
+                    const result = await writeFile(safeOut, content, { format: true, backup });
+                    if (!result.success) {
+                        return {
+                            content: [
+                                {
+                                    type: 'text' as const,
+                                    text: `Error: Failed writing ${target}: ${result.error || 'Unknown error'}`,
+                                },
+                            ],
+                            isError: true,
+                        };
+                    }
+                    writes.push({ file: result.filePath, backup: result.backupPath });
+                }
+
+                const summary = [
+                    '✅ Generated component variants and wrote files:',
+                    ...writes.map((w) => `- ${w.file}${w.backup ? ` (backup: ${w.backup})` : ''}`),
+                ].join('\n');
+
+                return { content: [{ type: 'text' as const, text: summary }] };
+            } catch (error) {
+                const message = error instanceof Error ? error.message : 'Unknown error';
+                return {
+                    content: [{ type: 'text' as const, text: `Error generating variants: ${message}` }],
+                    isError: true,
+                };
+            }
+        }
+    );
+}