gemini-design-mcp 1.0.0

package/README.md

@@ -0,0 +1,101 @@
+# gemini-design-mcp
+
+MCP server that uses **Google Gemini 3 Pro** for frontend/design code generation.
+
+## Why?
+
+Gemini excels at UI/UX design and frontend code generation. This MCP lets any AI agent (Claude Code, Codex, etc.) delegate frontend tasks to Gemini.
+
+**Key principle:** The calling agent manages context. No config files needed.
+
+## Installation
+
+Add to your Claude Desktop config (`~/.claude/claude_desktop_config.json`):
+
+```json
+{
+  "mcpServers": {
+    "gemini-design": {
+      "command": "npx",
+      "args": ["-y", "gemini-design-mcp"],
+      "env": {
+        "GEMINI_API_KEY": "your-api-key-here"
+      }
+    }
+  }
+}
+```
+
+Get your Gemini API key at: https://aistudio.google.com/app/apikey
+
+## Tools
+
+### generate_frontend
+
+Main tool for creating frontend code.
+
+**Parameters:**
+- `request` (required): What to create (e.g., "A hero section with gradient background")
+- `context` (nullable): Existing code for style reference. Pass `null` for new projects.
+- `techStack` (optional): Tech stack (e.g., "React + Tailwind", "Vue + CSS", "Next.js + shadcn")
+- `preferences` (optional): Style preferences (e.g., "dark mode", "glassmorphism", "minimal")
+
+### improve_frontend
+
+Improve existing frontend code.
+
+**Parameters:**
+- `code` (required): Current code to improve
+- `feedback` (required): What to improve (e.g., "Make it more modern", "Add hover effects")
+- `context` (optional): Additional context for consistency
+
+### suggest_design
+
+Get design suggestions without generating code. Saves tokens.
+
+**Parameters:**
+- `description` (required): What you're designing
+- `currentApproach` (optional): Current approach or constraints
+
+## How Context Works
+
+The calling agent (Claude, Codex) is responsible for passing relevant context:
+
+- **New project**: Pass `context: null`, Gemini creates from scratch
+- **Existing project**: Agent reads relevant components and passes them as context
+
+This ensures design consistency without requiring any user configuration.
+
+## Example Usage
+
+```
+Agent: "Create a pricing card component"
+
+→ Calls generate_frontend({
+    request: "A pricing card with 3 tiers, toggle for monthly/yearly",
+    context: "<existing Button and Card components>",
+    techStack: "React + Tailwind",
+    preferences: "glassmorphism, dark mode"
+  })
+
+← Returns complete, production-ready component code
+```
+
+## Development
+
+```bash
+# Clone and install
+git clone <repo>
+cd gemini-design-mcp
+npm install
+
+# Build
+npm run build
+
+# Test locally
+GEMINI_API_KEY=your-key node build/index.js
+```
+
+## License
+
+MIT

package/build/index.d.ts

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

package/build/index.js

@@ -0,0 +1,32 @@
+#!/usr/bin/env node
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { generateFrontendSchema, generateFrontend } from "./tools/generate-frontend.js";
+import { improveFrontendSchema, improveFrontend } from "./tools/improve-frontend.js";
+import { suggestDesignSchema, suggestDesign } from "./tools/suggest-design.js";
+// Create MCP server
+const server = new McpServer({
+    name: "gemini-design-mcp",
+    version: "1.0.0",
+});
+// Tool 1: generate_frontend
+server.tool("generate_frontend", `Generate frontend code (components, pages, sections) with Gemini 3 Pro.
+The calling agent MUST provide project context to ensure design consistency.
+If new project, pass context=null and Gemini will create a new design system.
+Gemini has 1M tokens of context - feel free to send multiple files.`, generateFrontendSchema, generateFrontend);
+// Tool 2: improve_frontend
+server.tool("improve_frontend", `Improve existing frontend code based on provided feedback.
+Use for design modifications, UX improvements, or visual refactoring.`, improveFrontendSchema, improveFrontend);
+// Tool 3: suggest_design
+server.tool("suggest_design", `Returns design suggestions without generating code.
+Useful for exploring directions before coding, saves tokens.`, suggestDesignSchema, suggestDesign);
+// Start server
+async function main() {
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    console.error("gemini-design-mcp v1.0.0 running on stdio");
+}
+main().catch((error) => {
+    console.error("Fatal error:", error);
+    process.exit(1);
+});

package/build/lib/gemini.d.ts

@@ -0,0 +1,4 @@
+import { GoogleGenAI } from "@google/genai";
+export declare const ai: GoogleGenAI;
+export declare const DEFAULT_MODEL = "gemini-3-pro";
+export declare function generateWithGemini(systemPrompt: string, userPrompt: string, model?: string): Promise<string>;

package/build/lib/gemini.js

@@ -0,0 +1,27 @@
+import { GoogleGenAI } from "@google/genai";
+const apiKey = process.env.GEMINI_API_KEY;
+if (!apiKey) {
+    console.error("ERROR: GEMINI_API_KEY environment variable is required");
+    console.error("Get your API key at: https://aistudio.google.com/app/apikey");
+    process.exit(1);
+}
+export const ai = new GoogleGenAI({ apiKey });
+// Default model - Gemini 3 Pro (best for design)
+export const DEFAULT_MODEL = "gemini-3-pro";
+export async function generateWithGemini(systemPrompt, userPrompt, model = DEFAULT_MODEL) {
+    try {
+        const response = await ai.models.generateContent({
+            model,
+            contents: userPrompt,
+            config: {
+                systemInstruction: systemPrompt,
+            },
+        });
+        return response.text ?? "";
+    }
+    catch (error) {
+        const errorMessage = error instanceof Error ? error.message : "Unknown error";
+        console.error("Gemini API error:", errorMessage);
+        throw new Error(`Gemini API error: ${errorMessage}`);
+    }
+}

package/build/prompts/system.d.ts

@@ -0,0 +1,3 @@
+export declare const GENERATE_FRONTEND_PROMPT = "You are an expert UI/UX designer and frontend developer.\nYou generate production-quality frontend code.\n\nSTRICT RULES:\n1. COMPLETE and functional code - never use placeholders like \"// TODO\" or \"...\"\n2. Modern, aesthetic, and professional design\n3. Responsive by default (mobile-first)\n4. Accessibility (aria-labels, semantic HTML, proper contrast)\n5. If CONTEXT is provided, you MUST match the existing style exactly\n6. If no context, create a coherent design system\n7. Use best practices for the requested framework/tech stack\n8. Return ONLY the code, no explanations\n\nDEFAULT STYLE (if not specified):\n- Colors: neutral tones with one accent color\n- Typography: clean and readable\n- Spacing: generous, airy\n- Effects: subtle (soft shadows, light transitions)";
+export declare const IMPROVE_FRONTEND_PROMPT = "You are an expert UI/UX designer and frontend developer.\nYou improve existing frontend code based on the feedback provided.\n\nRULES:\n1. Keep the general structure unless asked otherwise\n2. Only improve the aspects mentioned in the feedback\n3. Maintain consistency with the rest of the code\n4. Return the COMPLETE improved code, not just the changes\n5. No explanations, just the code";
+export declare const SUGGEST_DESIGN_PROMPT = "You are an expert UI/UX designer.\nYou provide concise and actionable design suggestions.\n\nRULES:\n1. Short and precise suggestions\n2. Focus on visual impact and UX\n3. Propose 3-5 ideas maximum\n4. Format: bullet points\n5. No code, just ideas";

package/build/prompts/system.js

@@ -0,0 +1,36 @@
+export const GENERATE_FRONTEND_PROMPT = `You are an expert UI/UX designer and frontend developer.
+You generate production-quality frontend code.
+
+STRICT RULES:
+1. COMPLETE and functional code - never use placeholders like "// TODO" or "..."
+2. Modern, aesthetic, and professional design
+3. Responsive by default (mobile-first)
+4. Accessibility (aria-labels, semantic HTML, proper contrast)
+5. If CONTEXT is provided, you MUST match the existing style exactly
+6. If no context, create a coherent design system
+7. Use best practices for the requested framework/tech stack
+8. Return ONLY the code, no explanations
+
+DEFAULT STYLE (if not specified):
+- Colors: neutral tones with one accent color
+- Typography: clean and readable
+- Spacing: generous, airy
+- Effects: subtle (soft shadows, light transitions)`;
+export const IMPROVE_FRONTEND_PROMPT = `You are an expert UI/UX designer and frontend developer.
+You improve existing frontend code based on the feedback provided.
+
+RULES:
+1. Keep the general structure unless asked otherwise
+2. Only improve the aspects mentioned in the feedback
+3. Maintain consistency with the rest of the code
+4. Return the COMPLETE improved code, not just the changes
+5. No explanations, just the code`;
+export const SUGGEST_DESIGN_PROMPT = `You are an expert UI/UX designer.
+You provide concise and actionable design suggestions.
+
+RULES:
+1. Short and precise suggestions
+2. Focus on visual impact and UX
+3. Propose 3-5 ideas maximum
+4. Format: bullet points
+5. No code, just ideas`;

package/build/tools/generate-frontend.d.ts

@@ -0,0 +1,18 @@
+import { z } from "zod";
+export declare const generateFrontendSchema: {
+    request: z.ZodString;
+    context: z.ZodNullable<z.ZodString>;
+    techStack: z.ZodOptional<z.ZodString>;
+    preferences: z.ZodOptional<z.ZodString>;
+};
+export declare function generateFrontend(params: {
+    request: string;
+    context: string | null;
+    techStack?: string;
+    preferences?: string;
+}): Promise<{
+    content: {
+        type: "text";
+        text: string;
+    }[];
+}>;

package/build/tools/generate-frontend.js

@@ -0,0 +1,32 @@
+import { z } from "zod";
+import { generateWithGemini } from "../lib/gemini.js";
+import { GENERATE_FRONTEND_PROMPT } from "../prompts/system.js";
+export const generateFrontendSchema = {
+    request: z.string().describe("Description of what to create (component, page, section, etc.)"),
+    context: z.string().nullable().describe("Existing project code for reference (components, styles, config). " +
+        "Send relevant files to ensure design consistency. " +
+        "Null if new project."),
+    techStack: z.string().optional().describe("Tech stack (e.g., 'React + Tailwind', 'Vue + CSS', 'HTML/CSS vanilla', 'Next.js + shadcn'). " +
+        "If not specified, Gemini will choose based on context."),
+    preferences: z.string().optional().describe("Style preferences (e.g., 'glassmorphism', 'dark mode', 'minimal', 'brutalist')"),
+};
+export async function generateFrontend(params) {
+    const { request, context, techStack, preferences } = params;
+    const systemPrompt = `${GENERATE_FRONTEND_PROMPT}
+
+${techStack ? `TECH STACK: ${techStack}` : ""}
+${preferences ? `STYLE PREFERENCES: ${preferences}` : ""}`.trim();
+    const userPrompt = context
+        ? `PROJECT CONTEXT (match this style):
+${context}
+
+---
+
+REQUEST:
+${request}`
+        : request;
+    const result = await generateWithGemini(systemPrompt, userPrompt);
+    return {
+        content: [{ type: "text", text: result }],
+    };
+}

package/build/tools/improve-frontend.d.ts

@@ -0,0 +1,16 @@
+import { z } from "zod";
+export declare const improveFrontendSchema: {
+    code: z.ZodString;
+    feedback: z.ZodString;
+    context: z.ZodOptional<z.ZodString>;
+};
+export declare function improveFrontend(params: {
+    code: string;
+    feedback: string;
+    context?: string;
+}): Promise<{
+    content: {
+        type: "text";
+        text: string;
+    }[];
+}>;

package/build/tools/improve-frontend.js

@@ -0,0 +1,21 @@
+import { z } from "zod";
+import { generateWithGemini } from "../lib/gemini.js";
+import { IMPROVE_FRONTEND_PROMPT } from "../prompts/system.js";
+export const improveFrontendSchema = {
+    code: z.string().describe("Current frontend code to improve"),
+    feedback: z.string().describe("What to improve or change"),
+    context: z.string().optional().describe("Additional context (other components for consistency)"),
+};
+export async function improveFrontend(params) {
+    const { code, feedback, context } = params;
+    const userPrompt = `CURRENT CODE:
+${code}
+
+${context ? `CONTEXT:\n${context}\n` : ""}
+FEEDBACK / REQUESTED IMPROVEMENTS:
+${feedback}`;
+    const result = await generateWithGemini(IMPROVE_FRONTEND_PROMPT, userPrompt);
+    return {
+        content: [{ type: "text", text: result }],
+    };
+}

package/build/tools/suggest-design.d.ts

@@ -0,0 +1,14 @@
+import { z } from "zod";
+export declare const suggestDesignSchema: {
+    description: z.ZodString;
+    currentApproach: z.ZodOptional<z.ZodString>;
+};
+export declare function suggestDesign(params: {
+    description: string;
+    currentApproach?: string;
+}): Promise<{
+    content: {
+        type: "text";
+        text: string;
+    }[];
+}>;

package/build/tools/suggest-design.js

@@ -0,0 +1,17 @@
+import { z } from "zod";
+import { generateWithGemini } from "../lib/gemini.js";
+import { SUGGEST_DESIGN_PROMPT } from "../prompts/system.js";
+export const suggestDesignSchema = {
+    description: z.string().describe("Description of the component/page you want suggestions for"),
+    currentApproach: z.string().optional().describe("Current approach or constraints to consider"),
+};
+export async function suggestDesign(params) {
+    const { description, currentApproach } = params;
+    const userPrompt = currentApproach
+        ? `DESCRIPTION: ${description}\n\nCURRENT APPROACH: ${currentApproach}`
+        : description;
+    const result = await generateWithGemini(SUGGEST_DESIGN_PROMPT, userPrompt);
+    return {
+        content: [{ type: "text", text: result }],
+    };
+}

package/package.json

@@ -0,0 +1,48 @@
+{
+  "name": "gemini-design-mcp",
+  "version": "1.0.0",
+  "description": "MCP server that uses Gemini 3 Pro for frontend/design code generation",
+  "main": "build/index.js",
+  "bin": {
+    "gemini-design-mcp": "./build/index.js"
+  },
+  "type": "module",
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch",
+    "start": "node build/index.js",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "mcp",
+    "gemini",
+    "design",
+    "frontend",
+    "ai",
+    "model-context-protocol",
+    "claude",
+    "codex"
+  ],
+  "author": "",
+  "license": "MIT",
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.0.0",
+    "@google/genai": "^1.33.0",
+    "zod": "^3.23.0"
+  },
+  "devDependencies": {
+    "@types/node": "^20.0.0",
+    "typescript": "^5.0.0"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": ""
+  },
+  "files": [
+    "build",
+    "README.md"
+  ]
+}