@gemini-designer/mcp-server 0.1.0

package/src/tools/generate-vibes.ts

@@ -0,0 +1,177 @@
+/**
+ * generate_vibes Tool
+ *
+ * Generates design direction options (vibes) before creating UI.
+ * Returns color palettes, typography, spacing, and sample CSS variables.
+ */
+
+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 { generateWithGemini } from '../generation/gemini-client.js';
+
+const inputSchema = {
+    projectContext: z
+        .string()
+        .optional()
+        .describe('Brief description of the project (e.g., "Modern SaaS dashboard for analytics")'),
+    existingTokens: z
+        .string()
+        .optional()
+        .describe('Path to existing design tokens or CSS file to analyze (optional)'),
+    vibeCount: z
+        .number()
+        .min(1)
+        .max(5)
+        .default(3)
+        .describe('Number of vibe options to generate (1-5)'),
+    preferences: z
+        .object({
+            colorTemp: z.enum(['warm', 'cool', 'neutral']).optional(),
+            density: z.enum(['compact', 'comfortable', 'spacious']).optional(),
+            style: z.enum(['minimal', 'playful', 'corporate', 'brutalist', 'glassmorphism']).optional(),
+        })
+        .optional()
+        .describe('Optional style preferences to guide generation'),
+};
+
+const SYSTEM_PROMPT = `You are an expert UI/UX designer specializing in modern web design systems.
+
+Your task is to generate design "vibes"—cohesive design directions that include colors, typography, and spacing.
+
+Requirements:
+- Return ONE valid JSON object with a "vibes" array (no markdown, no code fences, no extra commentary).
+- Use semantic color roles (primary, secondary, accent, background, surface, text, textMuted, border, danger, success).
+- Prefer accessible color combinations (aim for WCAG AA contrast for text on background/surface).
+- Provide a sensible type scale and spacing scale (consistent multiplier).
+- Provide a ready-to-paste CSS variable block (light theme). If you can, include a dark theme block too.
+
+Output structure:
+{
+  "vibes": [
+    {
+      "name": "Vibe Name",
+      "description": "Brief aesthetic description",
+      "colors": {
+        "primary": "#hex",
+        "secondary": "#hex",
+        "accent": "#hex",
+        "background": "#hex",
+        "surface": "#hex",
+        "text": "#hex",
+        "textMuted": "#hex",
+        "border": "#hex",
+        "danger": "#hex",
+        "success": "#hex"
+      },
+      "typography": {
+        "fontFamily": "font stack",
+        "headingFamily": "font stack or same",
+        "scale": [12, 14, 16, 18, 20, 24, 30, 36, 48, 60]
+      },
+      "spacing": {
+        "unit": 4,
+        "scale": [0, 4, 8, 12, 16, 24, 32, 48, 64, 96]
+      },
+      "cssVariables": "/* light */\\n:root { --color-primary: #...; }\\n\\n/* dark */\\n[data-theme='dark'] { --color-primary: #...; }"
+    }
+  ]
+}`;
+
+export function registerGenerateVibes(server: McpServer, config: Config): void {
+    server.registerTool(
+        'generate_vibes',
+        {
+            title: 'Generate Design Vibes',
+            description:
+                'Generate design direction options (vibes) with color palettes, typography, and spacing. Call this before create_ui to establish design consistency.',
+            inputSchema,
+        },
+        async (args) => {
+            const projectContext = args.projectContext as string | undefined;
+            const vibeCount = args.vibeCount as number | undefined;
+            const preferences = args.preferences as
+                | {
+                      colorTemp?: 'warm' | 'cool' | 'neutral';
+                      density?: 'compact' | 'comfortable' | 'spacious';
+                      style?: 'minimal' | 'playful' | 'corporate' | 'brutalist' | 'glassmorphism';
+                  }
+                | undefined;
+
+            const existingTokensPath = args.existingTokens as string | undefined;
+
+            let existingTokensContext = '';
+            if (existingTokensPath) {
+                // Use the same context pipeline (path allowlist + sensitive file filtering + truncation)
+                existingTokensContext = await buildContext([existingTokensPath], config);
+            }
+
+            let userPrompt = buildPrompt({
+                projectContext,
+                vibeCount,
+                preferences,
+            });
+
+            if (existingTokensContext) {
+                userPrompt += `\n\nExisting design tokens / styles to respect:\n${existingTokensContext}`;
+            }
+
+            try {
+                const response = await generateWithGemini(config, SYSTEM_PROMPT, userPrompt, { toolName: 'generate_vibes' });
+
+                return {
+                    content: [
+                        {
+                            type: 'text' as const,
+                            text: response.trim(),
+                        },
+                    ],
+                };
+            } catch (error) {
+                const message = error instanceof Error ? error.message : 'Unknown error';
+                return {
+                    content: [
+                        {
+                            type: 'text' as const,
+                            text: `Error generating vibes: ${message}`,
+                        },
+                    ],
+                    isError: true,
+                };
+            }
+        }
+    );
+}
+
+function buildPrompt(input: {
+    projectContext?: string;
+    vibeCount?: number;
+    preferences?: {
+        colorTemp?: 'warm' | 'cool' | 'neutral';
+        density?: 'compact' | 'comfortable' | 'spacious';
+        style?: 'minimal' | 'playful' | 'corporate' | 'brutalist' | 'glassmorphism';
+    };
+}): string {
+    const vibeCount = input.vibeCount ?? 3;
+    let prompt = `Generate ${vibeCount} distinct design vibes`;
+
+    if (input.projectContext) {
+        prompt += ` for this project: "${input.projectContext}"`;
+    }
+
+    if (input.preferences) {
+        const prefs = [];
+        if (input.preferences.colorTemp) prefs.push(`${input.preferences.colorTemp} color temperature`);
+        if (input.preferences.density) prefs.push(`${input.preferences.density} spacing density`);
+        if (input.preferences.style) prefs.push(`${input.preferences.style} style`);
+
+        if (prefs.length > 0) {
+            prompt += `. Preferences: ${prefs.join(', ')}`;
+        }
+    }
+
+    prompt += '. Return valid JSON only.';
+
+    return prompt;
+}

package/src/tools/index.ts

@@ -0,0 +1,42 @@
+/**
+ * Tool Registry
+ *
+ * Registers all MCP tools with the server.
+ */
+
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { Config } from '../config/index.js';
+import { registerGenerateVibes } from './generate-vibes.js';
+import { registerCreateUI } from './create-ui.js';
+import { registerModifyUI } from './modify-ui.js';
+import { registerSnippetUI } from './snippet-ui.js';
+import { registerScaffoldProject } from './scaffold-project.js';
+import { registerAnalyzeTokens } from './analyze-tokens.js';
+import { registerDetectUIStack } from './detect-ui-stack.js';
+import { registerSyncDesignTokens } from './sync-design-tokens.js';
+import { registerCatalogComponents } from './catalog-components.js';
+import { registerGenerateComponentVariants } from './generate-component-variants.js';
+import { registerAnalyzeScreenshotUI } from './analyze-screenshot-ui.js';
+
+/**
+ * Register all MCP tools
+ */
+export function registerTools(server: McpServer, config: Config): void {
+    console.error('[tools] Registering MCP tools...');
+
+    registerGenerateVibes(server, config);
+    registerCreateUI(server, config);
+    registerModifyUI(server, config);
+    registerSnippetUI(server, config);
+    registerScaffoldProject(server, config);
+    registerAnalyzeTokens(server, config);
+
+    // New grounding + power tools
+    registerDetectUIStack(server, config);
+    registerSyncDesignTokens(server, config);
+    registerCatalogComponents(server, config);
+    registerGenerateComponentVariants(server, config);
+    registerAnalyzeScreenshotUI(server, config);
+
+    console.error('[tools] All tools registered');
+}

package/src/tools/modify-ui.ts

@@ -0,0 +1,230 @@
+/**
+ * modify_ui Tool
+ *
+ * Surgical edits to existing components with minimal breakage.
+ * Preserves logic and only modifies UI-related code.
+ * Can optionally apply changes directly if requested.
+ */
+
+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 { 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 = {
+    targetFile: z.string().describe('Path to the file to modify'),
+    instruction: z
+        .string()
+        .describe('What to change (e.g., "Make the header sticky and add a subtle shadow")'),
+    context: z
+        .array(z.string())
+        .optional()
+        .describe('Related files for awareness (design tokens, parent components)'),
+    preserveLogic: z
+        .boolean()
+        .default(true)
+        .describe('Never touch non-UI code like API calls, state logic, etc.'),
+    returnDiff: z.boolean().default(false).describe('Return unified diff instead of full file'),
+    applyChanges: z
+        .boolean()
+        .default(false)
+        .describe('If true, apply the modifications directly to the file (only when returnDiff=false)'),
+    backup: z.boolean().default(true).describe('If true (default), create a .bak backup before modifying'),
+};
+
+function getSystemPrompt(returnDiff: boolean): string {
+    const base = `You are a senior frontend engineer performing surgical code modifications.
+
+CRITICAL RULES (must follow):
+1. ONLY modify what is explicitly requested.
+2. PRESERVE all existing functionality, imports, and logic.
+3. If preserveLogic is true, NEVER touch:
+   - API calls, fetch, axios
+   - State management (useState, Redux, Vuex, stores)
+   - Event handlers that aren't purely UI
+   - Business logic / data transforms
+4. Maintain the existing code style and formatting.
+5. Keep existing comments unless they conflict with the requested change.
+6. Accessibility: do not regress accessibility; keep/repair aria, labels, focus handling.
+7. Prefer reusing existing components/utilities from the repo (you will receive an auto component catalog).
+8. Output MUST NOT contain explanations, markdown, or code fences.`;
+
+    if (returnDiff) {
+        return `${base}\n\nOutput a UNIFIED DIFF only.`;
+    }
+
+    return `${base}\n\nOutput the COMPLETE modified file only (raw code).`;
+}
+
+/**
+ * Extract code from a model response that might contain fences.
+ */
+function cleanResponse(response: string): string {
+    let out = response.trim();
+    const codeBlockMatch = out.match(/```(?:\w+)?\n([\s\S]*?)```/);
+    if (codeBlockMatch) {
+        out = codeBlockMatch[1].trim();
+    }
+    return out;
+}
+
+export function registerModifyUI(server: McpServer, config: Config): void {
+    server.registerTool(
+        'modify_ui',
+        {
+            title: 'Modify UI Component',
+            description:
+                'Make surgical edits to existing UI components. Preserves logic and only modifies UI-related code. Set applyChanges=true to write directly.',
+            inputSchema,
+        },
+        async (args) => {
+            const targetFile = args.targetFile as string;
+            const instruction = args.instruction as string;
+            const contextPaths = args.context as string[] | undefined;
+            const preserveLogic = args.preserveLogic !== false;
+            const returnDiff = args.returnDiff === true;
+            const shouldApply = args.applyChanges === true;
+            const shouldBackup = args.backup !== false;
+
+            if (shouldApply && returnDiff) {
+                return {
+                    content: [
+                        {
+                            type: 'text' as const,
+                            text: 'Error: applyChanges=true is not supported when returnDiff=true. Set returnDiff=false to apply changes.',
+                        },
+                    ],
+                    isError: true,
+                };
+            }
+
+            // Resolve and validate the target path
+            let safeReadPath: string;
+            try {
+                safeReadPath = assertReadablePath(targetFile, config);
+            } catch (error) {
+                const message = error instanceof Error ? error.message : 'Invalid targetFile';
+                return {
+                    content: [{ type: 'text' as const, text: `Error: ${message}` }],
+                    isError: true,
+                };
+            }
+
+            // Read the target file
+            let fileContent: string;
+            try {
+                fileContent = fs.readFileSync(safeReadPath, 'utf-8');
+            } catch {
+                return {
+                    content: [
+                        {
+                            type: 'text' as const,
+                            text: `Error: Could not read file at ${targetFile}`,
+                        },
+                    ],
+                    isError: true,
+                };
+            }
+
+            // Build context from related files
+            let contextContent = '';
+            if (contextPaths && contextPaths.length > 0) {
+                contextContent = await buildContext(contextPaths, config);
+            }
+
+            // Auto-inject deterministic project grounding (stack + reusable components)
+            const grounding = await buildRepoGrounding(config, {
+                focusFileAbs: safeReadPath,
+                instruction,
+            });
+
+            const systemPrompt = getSystemPrompt(returnDiff);
+
+            const userPrompt = `Modify this file according to the instruction.
+
+${grounding}
+
+INSTRUCTION:
+${instruction}
+
+PRESERVE LOGIC:
+${preserveLogic}
+
+CURRENT FILE (${targetFile}):
+${fileContent}
+
+${contextContent ? `\n\nRELATED FILES FOR CONTEXT:\n${contextContent}\n` : ''}
+
+${returnDiff ? 'Return a unified diff only.' : 'Return the full modified file only.'}`;
+
+            try {
+                const response = await generateWithGemini(config, systemPrompt, userPrompt, { toolName: 'modify_ui' });
+                const cleaned = cleanResponse(response);
+
+                // Apply changes if requested (and not returning diff)
+                if (shouldApply) {
+                    let safeWritePath: string;
+                    try {
+                        safeWritePath = assertWritablePath(targetFile, config);
+                    } catch (error) {
+                        const message = error instanceof Error ? error.message : 'Invalid targetFile';
+                        return {
+                            content: [{ type: 'text' as const, text: `Error: ${message}` }],
+                            isError: true,
+                        };
+                    }
+
+                    const result = await writeFile(safeWritePath, cleaned, {
+                        format: true,
+                        backup: shouldBackup,
+                    });
+
+                    if (!result.success) {
+                        return {
+                            content: [
+                                {
+                                    type: 'text' as const,
+                                    text: `❌ Failed to apply changes: ${result.error || 'Unknown error'}`,
+                                },
+                            ],
+                            isError: true,
+                        };
+                    }
+
+                    const msg = [
+                        `✅ Applied changes successfully.`,
+                        `File: ${result.filePath}`,
+                        result.backupPath ? `Backup: ${result.backupPath}` : undefined,
+                    ]
+                        .filter(Boolean)
+                        .join('\n');
+
+                    return {
+                        content: [{ type: 'text' as const, text: msg }],
+                    };
+                }
+
+                // Return diff or full file ONLY (no wrappers) for best agent compatibility
+                return {
+                    content: [{ type: 'text' as const, text: cleaned }],
+                };
+            } catch (error) {
+                const message = error instanceof Error ? error.message : 'Unknown error';
+                return {
+                    content: [
+                        {
+                            type: 'text' as const,
+                            text: `Error modifying UI: ${message}`,
+                        },
+                    ],
+                    isError: true,
+                };
+            }
+        }
+    );
+}

package/src/tools/scaffold-project.ts

@@ -0,0 +1,138 @@
+/**
+ * scaffold_project Tool
+ *
+ * Creates a complete UI plan for a new project.
+ * Outputs component hierarchy, page layouts, and design tokens.
+ */
+
+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';
+
+const inputSchema = {
+    projectType: z
+        .enum(['landing', 'dashboard', 'ecommerce', 'saas', 'blog', 'portfolio', 'docs', 'custom'])
+        .describe('Type of project to scaffold'),
+    name: z.string().describe('Project name'),
+    pages: z
+        .array(z.string())
+        .describe('List of pages to plan (e.g., ["Home", "Pricing", "About", "Contact"])'),
+    vibe: z.string().optional().describe('Selected design vibe from generate_vibes'),
+    features: z
+        .array(z.string())
+        .optional()
+        .describe('Special features (e.g., ["dark mode", "i18n", "auth", "animations"])'),
+    framework: z
+        .enum(['vanilla', 'react', 'vue', 'svelte', 'nextjs'])
+        .optional()
+        .describe('Target framework'),
+};
+
+const SYSTEM_PROMPT = `You are a senior frontend architect creating a comprehensive UI plan for a new project.
+
+Return ONE valid JSON object only. No markdown. No code fences. No extra commentary.
+
+Output structure (example):
+{
+  "projectName": "name",
+  "projectType": "saas",
+  "framework": "nextjs",
+  "structure": {
+    "components": {
+      "common": ["Button", "Input", "Card"],
+      "layout": ["Header", "Footer", "Sidebar"],
+      "features": { "auth": ["LoginForm", "SignupForm"] }
+    },
+    "pages": {
+      "Home": {
+        "path": "/",
+        "layout": "MarketingLayout",
+        "components": ["Hero", "Features", "CTA"],
+        "description": "Page purpose"
+      }
+    }
+  },
+  "designTokens": {
+    "colors": {},
+    "typography": {},
+    "spacing": {},
+    "breakpoints": {}
+  },
+  "fileStructure": [
+    "src/components/common/Button.tsx",
+    "src/components/layout/Header.tsx",
+    "src/pages/Home.tsx"
+  ],
+  "dependencies": [],
+  "setupInstructions": []
+}
+
+Focus on:
+- Reusable component identification
+- Consistent naming conventions
+- Logical file organization
+- Clear responsibilities (avoid bloated god-components)
+- Accessibility defaults (WCAG AA) for interactive components`;
+
+export function registerScaffoldProject(server: McpServer, config: Config): void {
+    server.registerTool(
+        'scaffold_project',
+        {
+            title: 'Scaffold Project',
+            description:
+                'Create a complete UI architecture plan for a new project including component hierarchy, pages, and design tokens.',
+            inputSchema,
+        },
+        async (args) => {
+            const projectType = args.projectType as string;
+            const name = args.name as string;
+            const pages = args.pages as string[];
+            const vibe = args.vibe as string | undefined;
+            const features = args.features as string[] | undefined;
+            const framework =
+                (args.framework as 'vanilla' | 'react' | 'vue' | 'svelte' | 'nextjs') ||
+                config.defaultFramework;
+
+            let userPrompt = `Create a UI scaffold for a ${projectType} project called "${name}".
+
+Framework: ${framework}
+Pages: ${pages.join(', ')}`;
+
+            if (features && features.length > 0) {
+                userPrompt += `\nFeatures: ${features.join(', ')}`;
+            }
+
+            if (vibe) {
+                userPrompt += `\n\nDesign vibe/tokens:\n${vibe}`;
+            }
+
+            userPrompt += '\n\nReturn valid JSON only.';
+
+            try {
+                const response = await generateWithGemini(config, SYSTEM_PROMPT, userPrompt, { toolName: 'scaffold_project' });
+
+                // IMPORTANT: Return raw JSON ONLY (no wrappers) so agents can parse it reliably.
+                return {
+                    content: [
+                        {
+                            type: 'text' as const,
+                            text: response.trim(),
+                        },
+                    ],
+                };
+            } catch (error) {
+                const message = error instanceof Error ? error.message : 'Unknown error';
+                return {
+                    content: [
+                        {
+                            type: 'text' as const,
+                            text: `Error scaffolding project: ${message}`,
+                        },
+                    ],
+                    isError: true,
+                };
+            }
+        }
+    );
+}