@gemini-designer/mcp-server 0.1.0

package/src/tools/snippet-ui.ts

@@ -0,0 +1,222 @@
+/**
+ * snippet_ui Tool
+ *
+ * Generate standalone UI components (modals, tables, forms, etc.)
+ * for injection into an existing architecture.
+ * Can optionally write directly to a file if requested.
+ */
+
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { z } from 'zod';
+import { Config } from '../config/index.js';
+import { generateWithGemini } from '../generation/gemini-client.js';
+import { buildContext } from '../context/builder.js';
+import { buildRepoHints } from '../context/repo-hints.js';
+import { assertWritablePath } from '../context/guards.js';
+import { writeFile } from '../output/file-writer.js';
+
+const inputSchema = {
+    type: z
+        .enum(['modal', 'table', 'chart', 'form', 'card', 'nav', 'hero', 'footer', 'sidebar', 'custom'])
+        .describe('Type of UI component to generate'),
+    description: z
+        .string()
+        .describe(
+            'Detailed description of the component (e.g., "A data table with sorting, filtering, and pagination")'
+        ),
+    framework: z
+        .enum(['vanilla', 'react', 'vue', 'svelte', 'nextjs'])
+        .optional()
+        .describe('Target framework'),
+    context: z
+        .array(z.string())
+        .optional()
+        .describe('Paths to design tokens or existing components to match style'),
+    propsInterface: z
+        .string()
+        .optional()
+        .describe('TypeScript interface for component props (if applicable)'),
+    animated: z.boolean().default(false).describe('Include animations/transitions'),
+    targetPath: z.string().optional().describe('Where to write the output file (if writeToFile=true)'),
+    writeToFile: z.boolean().default(false).describe('If true, write the generated code to targetPath'),
+};
+
+function getSystemPrompt(type: string, framework: string): string {
+    return `You are a senior frontend engineer and UI designer.
+
+Generate a standalone ${type} component in ${framework}.
+
+Hard rules:
+- Output ONLY the code. No explanations. No markdown. No code fences.
+- Accessible by default (WCAG AA): semantic HTML, labels, aria-* where needed, keyboard support, focus-visible.
+- Responsive by default (mobile-first).
+- Do not add new dependencies unless explicitly requested.
+- Avoid placeholder TODOs. Provide complete, production-ready implementation.
+
+Type-specific requirements:
+${getComponentGuidelines(type)}`;
+}
+
+function getComponentGuidelines(type: string): string {
+    const guidelines: Record<string, string> = {
+        modal: [
+            '- Trap focus inside the modal',
+            '- Close on Escape',
+            '- Close on backdrop click',
+            '- Ensure aria-modal, role=dialog, accessible title/description wiring',
+        ].join('\n'),
+        table: [
+            '- Optional sortable columns (no external deps)',
+            '- Responsive: horizontal scroll or stacked layout on small screens',
+            '- Accessible headers and caption support',
+        ].join('\n'),
+        form: [
+            '- Accessible labels and error messages',
+            '- Validation states and disabled/loading submit state',
+            '- Keyboard submit behavior',
+        ].join('\n'),
+        card: ['- Flexible content slots', '- Hover/focus states', '- Optional media support'].join('\n'),
+        nav: [
+            '- Mobile hamburger pattern if needed',
+            '- Active state indication',
+            '- Keyboard navigation (tab, arrow keys if menus)',
+        ].join('\n'),
+        hero: ['- Responsive layout', '- CTA buttons', '- Ensure text contrast/legibility'].join('\n'),
+        footer: ['- Responsive multi-column layout', '- Social links', '- Legal/copyright'].join('\n'),
+        sidebar: ['- Collapsible (optional)', '- Active item highlighting', '- Nested items support'].join('\n'),
+        chart: [
+            '- Responsive sizing',
+            '- Provide an accessible table fallback for data',
+            '- Avoid heavy chart deps unless explicitly requested',
+        ].join('\n'),
+        custom: '- Follow best practices for the described component type',
+    };
+
+    return guidelines[type] || guidelines.custom;
+}
+
+/**
+ * Extract code from markdown code blocks.
+ * (We still instruct the model not to use fences; this is a safety net.)
+ */
+function extractCode(response: string): string {
+    const codeBlockMatch = response.match(/```(?:\w+)?\n([\s\S]*?)```/);
+    if (codeBlockMatch) {
+        return codeBlockMatch[1].trim();
+    }
+    return response.trim();
+}
+
+export function registerSnippetUI(server: McpServer, config: Config): void {
+    server.registerTool(
+        'snippet_ui',
+        {
+            title: 'Generate UI Snippet',
+            description:
+                'Generate standalone UI components (modals, tables, forms, etc.) ready to inject. Set writeToFile=true to write directly.',
+            inputSchema,
+        },
+        async (args) => {
+            const type = args.type as string;
+            const description = args.description as string;
+            const framework =
+                (args.framework as 'vanilla' | 'react' | 'vue' | 'svelte' | 'nextjs') ||
+                config.defaultFramework;
+            const contextPaths = args.context as string[] | undefined;
+            const propsInterface = args.propsInterface as string | undefined;
+            const animated = args.animated === true;
+            const targetPath = args.targetPath as string | undefined;
+            const shouldWrite = args.writeToFile === true;
+
+            // Build context from existing files
+            let contextContent = '';
+            if (contextPaths && contextPaths.length > 0) {
+                contextContent = await buildContext(contextPaths, config);
+            }
+
+            const systemPrompt = getSystemPrompt(type, framework);
+
+            let userPrompt = `Create a ${type} component.
+
+${buildRepoHints(config)}
+
+Description:
+${description}`;
+
+            if (propsInterface) {
+                userPrompt += `\n\nProps interface:\n${propsInterface}`;
+            }
+
+            if (animated) {
+                userPrompt += `\n\nInclude smooth, subtle animations/transitions (respect reduced motion).`;
+            }
+
+            if (contextContent) {
+                userPrompt += `\n\nMatch the style/tokens from these existing files:\n${contextContent}`;
+            }
+
+            try {
+                const response = await generateWithGemini(config, systemPrompt, userPrompt, { toolName: 'snippet_ui' });
+                const code = extractCode(response);
+
+                // Write to file if requested
+                if (shouldWrite) {
+                    if (!targetPath) {
+                        return {
+                            content: [
+                                {
+                                    type: 'text' as const,
+                                    text: `Error: writeToFile=true but no targetPath was provided.`,
+                                },
+                            ],
+                            isError: true,
+                        };
+                    }
+
+                    const safePath = assertWritablePath(targetPath, config);
+                    const result = await writeFile(safePath, code, { format: true, backup: true });
+
+                    if (!result.success) {
+                        return {
+                            content: [
+                                {
+                                    type: 'text' as const,
+                                    text: `❌ Failed to write file: ${result.error || 'Unknown error'}`,
+                                },
+                            ],
+                            isError: true,
+                        };
+                    }
+
+                    const msg = [
+                        `✅ Snippet written successfully.`,
+                        `File: ${result.filePath}`,
+                        result.backupPath ? `Backup: ${result.backupPath}` : undefined,
+                    ]
+                        .filter(Boolean)
+                        .join('\n');
+
+                    return {
+                        content: [{ type: 'text' as const, text: msg }],
+                    };
+                }
+
+                // Return code only (no wrappers) for best agent compatibility
+                return {
+                    content: [{ type: 'text' as const, text: code }],
+                };
+            } catch (error) {
+                const message = error instanceof Error ? error.message : 'Unknown error';
+                return {
+                    content: [
+                        {
+                            type: 'text' as const,
+                            text: `Error generating snippet: ${message}`,
+                        },
+                    ],
+                    isError: true,
+                };
+            }
+        }
+    );
+}

package/src/tools/sync-design-tokens.ts

@@ -0,0 +1,256 @@
+/**
+ * sync_design_tokens Tool
+ *
+ * Converts design tokens between formats and optionally writes them to files.
+ *
+ * Primary use cases:
+ * - Take existing CSS vars and generate Tailwind theme extension
+ * - Export Tokens Studio JSON for Figma/Tokens Studio workflows
+ * - Normalize token files for team consistency
+ */
+
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { z } from 'zod';
+import * as fs from 'node:fs';
+import { Config } from '../config/index.js';
+import { assertReadablePath, assertWritablePath } from '../context/guards.js';
+import { sanitizeContent } from '../context/filter.js';
+import { writeFile } from '../output/file-writer.js';
+import {
+    parseCssVars,
+    tokensToCssVars,
+    tokensToTailwindTheme,
+    tokensToTokensStudio,
+    tokensToStyleDictionary,
+    type Token,
+} from '../tokens/sync.js';
+import { generateWithGemini } from '../generation/gemini-client.js';
+
+const inputSchema = {
+    sourcePath: z.string().optional().describe('Path to a token source file (CSS vars or JSON).'),
+    sourceContent: z.string().optional().describe('Inline token content (if not using sourcePath).'),
+    sourceType: z
+        .enum(['css-vars', 'tokens-json', 'style-dictionary'])
+        .default('css-vars')
+        .describe('How to interpret the source.'),
+    targets: z
+        .array(z.enum(['css-vars', 'tailwind', 'tokens-studio', 'style-dictionary']))
+        .default(['css-vars', 'tailwind', 'tokens-studio'])
+        .describe('Target formats to generate.'),
+    aiNormalize: z
+        .boolean()
+        .default(false)
+        .describe('If true, use the model to improve token naming & grouping (uses tokens).'),
+    writeToFile: z.boolean().default(false).describe('If true, write generated outputs to files.'),
+    outputPaths: z
+        .object({
+            cssVars: z.string().optional(),
+            tailwind: z.string().optional(),
+            tokensStudio: z.string().optional(),
+            styleDictionary: z.string().optional(),
+        })
+        .optional()
+        .describe('Where to write outputs if writeToFile=true.'),
+    backup: z.boolean().default(true).describe('Create .bak backups for overwritten files.'),
+};
+
+const NORMALIZE_SYSTEM_PROMPT = `You are a design systems engineer. You will normalize and improve a design token set.
+
+Goal:
+- Improve token naming and grouping using semantic names (primary, surface, text, border, danger, success)
+- Preserve ALL token values exactly (do not change hex codes, sizes, etc.)
+- Remove duplicates when values are identical AND names are redundant
+
+Output rules:
+- Output ONE valid JSON array of tokens only. No markdown. No prose.
+- Each token: {"name": string, "value": string, "type": string, "description"?: string}
+`;
+
+function cleanJsonArray(response: string): string {
+    let out = response.trim();
+    const fenced = out.match(/```(?:json)?\n([\s\S]*?)```/);
+    if (fenced) out = fenced[1].trim();
+    return out;
+}
+
+export function registerSyncDesignTokens(server: McpServer, config: Config): void {
+    server.registerTool(
+        'sync_design_tokens',
+        {
+            title: 'Sync Design Tokens',
+            description:
+                'Convert tokens between CSS vars, Tailwind theme, Tokens Studio JSON, and Style Dictionary. Optionally writes outputs to files.',
+            inputSchema,
+        },
+        async (args) => {
+            const sourcePath = args.sourcePath as string | undefined;
+            const sourceContent = args.sourceContent as string | undefined;
+            const sourceType = (args.sourceType as 'css-vars' | 'tokens-json' | 'style-dictionary') || 'css-vars';
+            const targets = (args.targets as Array<'css-vars' | 'tailwind' | 'tokens-studio' | 'style-dictionary'>) || [
+                'css-vars',
+                'tailwind',
+                'tokens-studio',
+            ];
+            const aiNormalize = args.aiNormalize === true;
+            const writeToFile = args.writeToFile === true;
+            const outputPaths = args.outputPaths as
+                | {
+                      cssVars?: string;
+                      tailwind?: string;
+                      tokensStudio?: string;
+                      styleDictionary?: string;
+                  }
+                | undefined;
+            const backup = args.backup !== false;
+
+            if (!sourcePath && !sourceContent) {
+                return {
+                    content: [{ type: 'text' as const, text: 'Error: Provide either sourcePath or sourceContent.' }],
+                    isError: true,
+                };
+            }
+
+            let raw: string;
+            let safeSourcePath: string | undefined;
+            try {
+                if (sourcePath) {
+                    safeSourcePath = assertReadablePath(sourcePath, config);
+                    raw = fs.readFileSync(safeSourcePath, 'utf-8');
+                } else {
+                    raw = sourceContent as string;
+                }
+            } catch (error) {
+                const message = error instanceof Error ? error.message : 'Could not read source';
+                return {
+                    content: [{ type: 'text' as const, text: `Error: ${message}` }],
+                    isError: true,
+                };
+            }
+
+            raw = sanitizeContent(raw);
+
+            let tokens: Token[] = [];
+            const warnings: string[] = [];
+
+            try {
+                if (sourceType === 'css-vars') {
+                    const parsed = parseCssVars(raw, safeSourcePath);
+                    tokens = parsed.tokens;
+                    warnings.push(...parsed.warnings);
+                } else {
+                    // Very lightweight: accept either Tokens Studio or Style Dictionary style
+                    const json = JSON.parse(raw);
+                    const collected: Token[] = [];
+
+                    const walk = (obj: any, prefix: string[]) => {
+                        if (!obj || typeof obj !== 'object') return;
+                        if (typeof obj.value === 'string' && typeof obj.type === 'string') {
+                            collected.push({
+                                name: [...prefix].join('.'),
+                                value: obj.value,
+                                type: obj.type,
+                                description: typeof obj.description === 'string' ? obj.description : undefined,
+                                source: { file: safeSourcePath ? safeSourcePath.split('/').pop() : undefined },
+                            });
+                            return;
+                        }
+                        for (const [k, v] of Object.entries(obj)) {
+                            walk(v, [...prefix, k]);
+                        }
+                    };
+
+                    walk(json, []);
+                    tokens = collected;
+                    if (tokens.length === 0) warnings.push('No tokens found in JSON (expected nested {value,type} nodes).');
+                }
+            } catch (error) {
+                const message = error instanceof Error ? error.message : 'Failed to parse tokens';
+                return {
+                    content: [{ type: 'text' as const, text: `Error: ${message}` }],
+                    isError: true,
+                };
+            }
+
+            // Optional AI normalization
+            if (aiNormalize && tokens.length > 0) {
+                const userPrompt = `Normalize these tokens. Remember: never change values.
+
+TOKENS (JSON array):
+${JSON.stringify(tokens, null, 2)}`;
+                try {
+                    const resp = await generateWithGemini(config, NORMALIZE_SYSTEM_PROMPT, userPrompt, {
+                        toolName: 'sync_design_tokens',
+                    });
+                    const cleaned = cleanJsonArray(resp);
+                    const normalized = JSON.parse(cleaned);
+                    if (Array.isArray(normalized)) {
+                        tokens = normalized as Token[];
+                    } else {
+                        warnings.push('AI normalization returned non-array output; keeping original tokens.');
+                    }
+                } catch (error) {
+                    const message = error instanceof Error ? error.message : 'AI normalization failed';
+                    warnings.push(`AI normalization failed: ${message}`);
+                }
+            }
+
+            const outputs: Record<string, string> = {};
+            for (const t of targets) {
+                if (t === 'css-vars') outputs.cssVars = tokensToCssVars(tokens);
+                if (t === 'tailwind') outputs.tailwind = tokensToTailwindTheme(tokens);
+                if (t === 'tokens-studio') outputs.tokensStudio = tokensToTokensStudio(tokens);
+                if (t === 'style-dictionary') outputs.styleDictionary = tokensToStyleDictionary(tokens);
+            }
+
+            // Optional writing
+            const written: Array<{ path: string; backupPath?: string }> = [];
+            if (writeToFile) {
+                const mapping = [
+                    { outKey: 'cssVars', pathKey: 'cssVars' },
+                    { outKey: 'tailwind', pathKey: 'tailwind' },
+                    { outKey: 'tokensStudio', pathKey: 'tokensStudio' },
+                    { outKey: 'styleDictionary', pathKey: 'styleDictionary' },
+                ] as const;
+
+                for (const m of mapping) {
+                    const content = outputs[m.outKey];
+                    const outPath = outputPaths?.[m.pathKey];
+                    if (!content || !outPath) continue;
+                    try {
+                        const safeOut = assertWritablePath(outPath, config);
+                        const result = await writeFile(safeOut, content, { format: false, backup });
+                        if (!result.success) {
+                            return {
+                                content: [
+                                    {
+                                        type: 'text' as const,
+                                        text: `Error: Failed writing ${outPath}: ${result.error || 'Unknown error'}`,
+                                    },
+                                ],
+                                isError: true,
+                            };
+                        }
+                        written.push({ path: result.filePath, backupPath: result.backupPath || undefined });
+                    } catch (error) {
+                        const message = error instanceof Error ? error.message : 'Write failed';
+                        return {
+                            content: [{ type: 'text' as const, text: `Error: ${message}` }],
+                            isError: true,
+                        };
+                    }
+                }
+            }
+
+            const response = {
+                tokens,
+                outputs,
+                warnings,
+                written,
+            };
+
+            return {
+                content: [{ type: 'text' as const, text: JSON.stringify(response, null, 2) }],
+            };
+        }
+    );
+}

package/src/utils/walk.ts

@@ -0,0 +1,75 @@
+/**
+ * walk.ts
+ *
+ * Lightweight recursive file walker with sane defaults.
+ * - No extra deps (no glob)
+ * - Skips common large / sensitive directories
+ */
+
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+
+export interface WalkOptions {
+    includeExtensions?: string[];
+    excludeDirNames?: string[];
+    maxFiles?: number;
+}
+
+const DEFAULT_EXCLUDE_DIRS = [
+    'node_modules',
+    '.git',
+    '.next',
+    '.nuxt',
+    'dist',
+    'build',
+    '.turbo',
+    '.cache',
+    'coverage',
+];
+
+export function walkFiles(rootDir: string, options: WalkOptions = {}): string[] {
+    const includeExtensions = (options.includeExtensions || []).map((e) => e.toLowerCase());
+    const exclude = new Set((options.excludeDirNames || DEFAULT_EXCLUDE_DIRS).map((d) => d.toLowerCase()));
+    const maxFiles = typeof options.maxFiles === 'number' ? options.maxFiles : 10_000;
+
+    const results: string[] = [];
+    const queue: string[] = [rootDir];
+
+    while (queue.length > 0) {
+        const current = queue.pop()!;
+        let entries: fs.Dirent[];
+        try {
+            entries = fs.readdirSync(current, { withFileTypes: true });
+        } catch {
+            continue;
+        }
+
+        for (const ent of entries) {
+            if (results.length >= maxFiles) return results;
+            const abs = path.join(current, ent.name);
+
+            if (ent.isDirectory()) {
+                if (exclude.has(ent.name.toLowerCase())) continue;
+                queue.push(abs);
+                continue;
+            }
+
+            if (!ent.isFile()) continue;
+            if (includeExtensions.length === 0) {
+                results.push(abs);
+                continue;
+            }
+
+            const ext = path.extname(ent.name).toLowerCase();
+            if (includeExtensions.includes(ext)) {
+                results.push(abs);
+            }
+        }
+    }
+
+    return results;
+}
+
+export function toPosixPath(p: string): string {
+    return p.replace(/\\/g, '/');
+}

package/tsconfig.json

@@ -0,0 +1,34 @@
+{
+    "compilerOptions": {
+        "target": "ES2022",
+        "module": "NodeNext",
+        "moduleResolution": "NodeNext",
+        "lib": [
+            "ES2022"
+        ],
+        "outDir": "dist",
+        "rootDir": "src",
+        "strict": true,
+        "esModuleInterop": true,
+        "skipLibCheck": true,
+        "forceConsistentCasingInFileNames": true,
+        "resolveJsonModule": true,
+        "declaration": true,
+        "declarationMap": true,
+        "sourceMap": true,
+        "baseUrl": ".",
+        "paths": {
+            "@/*": [
+                "src/*"
+            ]
+        }
+    },
+    "include": [
+        "src/**/*"
+    ],
+    "exclude": [
+        "node_modules",
+        "dist",
+        "**/*.test.ts"
+    ]
+}

package/vitest.config.ts

@@ -0,0 +1,15 @@
+import { defineConfig } from 'vitest/config';
+
+export default defineConfig({
+    test: {
+        globals: true,
+        environment: 'node',
+        include: ['src/**/*.test.ts'],
+        coverage: {
+            provider: 'v8',
+            reporter: ['text', 'json', 'html'],
+            include: ['src/**/*.ts'],
+            exclude: ['src/**/*.test.ts', 'src/index.ts'],
+        },
+    },
+});