@gemini-designer/mcp-server 0.1.0

package/src/stack/detect.ts

@@ -0,0 +1,204 @@
+/**
+ * Stack Detection
+ *
+ * Deterministically detect the frontend stack of a project:
+ * - framework (next/react/vue/svelte)
+ * - styling approach (tailwind/css-modules/emotion/styled-components)
+ * - common component & icon libraries
+ * - presence of storybook, eslint, prettier
+ */
+
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+
+export interface StackDetectionResult {
+    root: string;
+    framework: {
+        name: 'nextjs' | 'react' | 'vue' | 'svelte' | 'unknown';
+        version?: string;
+        router?: 'app' | 'pages' | 'unknown';
+    };
+    language: {
+        typescript: boolean;
+    };
+    styling: {
+        primary: 'tailwind' | 'css-modules' | 'emotion' | 'styled-components' | 'sass' | 'vanilla' | 'unknown';
+        detected: string[];
+    };
+    uiLibraries: string[];
+    iconLibraries: string[];
+    tooling: {
+        storybook: boolean;
+        eslint: boolean;
+        prettier: boolean;
+        vitest: boolean;
+        jest: boolean;
+    };
+    conventions: {
+        srcDir: boolean;
+        hasAppDir: boolean;
+        hasPagesDir: boolean;
+        tsconfigPaths?: Record<string, string[]>;
+    };
+    files: {
+        packageJson?: string;
+        tsconfig?: string;
+        tailwindConfig?: string;
+        componentsJson?: string;
+        storybookDir?: string;
+    };
+    warnings: string[];
+}
+
+function readJsonIfExists(filePath: string): any | null {
+    if (!fs.existsSync(filePath)) return null;
+    try {
+        return JSON.parse(fs.readFileSync(filePath, 'utf-8'));
+    } catch {
+        return null;
+    }
+}
+
+function exists(root: string, ...parts: string[]): string | null {
+    const p = path.join(root, ...parts);
+    return fs.existsSync(p) ? p : null;
+}
+
+function depVersion(pkg: any, name: string): string | undefined {
+    const d = pkg?.dependencies?.[name] || pkg?.devDependencies?.[name] || pkg?.peerDependencies?.[name];
+    return typeof d === 'string' ? d : undefined;
+}
+
+export function detectUiStack(rootDir: string): StackDetectionResult {
+    const warnings: string[] = [];
+
+    const pkgPath = exists(rootDir, 'package.json');
+    const pkg = pkgPath ? readJsonIfExists(pkgPath) : null;
+    if (!pkg) warnings.push('package.json not found or invalid JSON');
+
+    const hasTs = Boolean(
+        exists(rootDir, 'tsconfig.json') ||
+            exists(rootDir, 'tsconfig.base.json') ||
+            exists(rootDir, 'tsconfig.app.json') ||
+            depVersion(pkg, 'typescript')
+    );
+
+    // Framework detection
+    let framework: StackDetectionResult['framework'] = { name: 'unknown', router: 'unknown' };
+
+    if (depVersion(pkg, 'next')) {
+        framework = { name: 'nextjs', version: depVersion(pkg, 'next'), router: 'unknown' };
+    } else if (depVersion(pkg, 'react')) {
+        framework = { name: 'react', version: depVersion(pkg, 'react'), router: 'unknown' };
+    } else if (depVersion(pkg, 'vue')) {
+        framework = { name: 'vue', version: depVersion(pkg, 'vue'), router: 'unknown' };
+    } else if (depVersion(pkg, 'svelte')) {
+        framework = { name: 'svelte', version: depVersion(pkg, 'svelte'), router: 'unknown' };
+    }
+
+    const srcDir = Boolean(exists(rootDir, 'src'));
+    const hasAppDir = Boolean(exists(rootDir, 'app') || exists(rootDir, 'src', 'app'));
+    const hasPagesDir = Boolean(exists(rootDir, 'pages') || exists(rootDir, 'src', 'pages'));
+
+    if (framework.name === 'nextjs') {
+        framework.router = hasAppDir ? 'app' : hasPagesDir ? 'pages' : 'unknown';
+    }
+
+    // Styling detection
+    const detectedStyling: string[] = [];
+    if (depVersion(pkg, 'tailwindcss') || exists(rootDir, 'tailwind.config.js') || exists(rootDir, 'tailwind.config.ts')) {
+        detectedStyling.push('tailwind');
+    }
+    if (depVersion(pkg, 'sass') || depVersion(pkg, 'node-sass')) detectedStyling.push('sass');
+    if (depVersion(pkg, 'styled-components')) detectedStyling.push('styled-components');
+    if (depVersion(pkg, '@emotion/react') || depVersion(pkg, '@emotion/styled')) detectedStyling.push('emotion');
+
+    // CSS Modules: heuristic – Next and CRA often use .module.css. We can't scan whole tree here; mark as possible.
+    if (framework.name === 'nextjs') detectedStyling.push('css-modules');
+
+    let primary: StackDetectionResult['styling']['primary'] = 'unknown';
+    if (detectedStyling.includes('tailwind')) primary = 'tailwind';
+    else if (detectedStyling.includes('emotion')) primary = 'emotion';
+    else if (detectedStyling.includes('styled-components')) primary = 'styled-components';
+    else if (detectedStyling.includes('sass')) primary = 'sass';
+    else if (framework.name !== 'unknown') primary = 'vanilla';
+
+    // UI libraries (coarse)
+    const uiCandidates = [
+        '@mui/material',
+        'antd',
+        '@chakra-ui/react',
+        '@radix-ui/react-dialog',
+        '@headlessui/react',
+        'shadcn-ui',
+        'lucide-react',
+        '@mantine/core',
+        '@nextui-org/react',
+    ];
+
+    const uiLibraries = uiCandidates.filter((n) => Boolean(depVersion(pkg, n)));
+
+    // Icon libraries
+    const iconCandidates = ['lucide-react', 'react-icons', '@heroicons/react', '@tabler/icons-react', '@phosphor-icons/react'];
+    const iconLibraries = iconCandidates.filter((n) => Boolean(depVersion(pkg, n)));
+
+    // Storybook / linting / formatting / tests
+    const hasStorybook = Boolean(exists(rootDir, '.storybook')) || Boolean(depVersion(pkg, 'storybook')) || Boolean(depVersion(pkg, '@storybook/react'));
+    const hasEslint = Boolean(depVersion(pkg, 'eslint')) || Boolean(exists(rootDir, '.eslintrc')) || Boolean(exists(rootDir, '.eslintrc.js'));
+    const hasPrettier = Boolean(depVersion(pkg, 'prettier')) || Boolean(exists(rootDir, '.prettierrc'));
+    const hasVitest = Boolean(depVersion(pkg, 'vitest'));
+    const hasJest = Boolean(depVersion(pkg, 'jest'));
+
+    // Shadcn detection
+    const componentsJson = exists(rootDir, 'components.json');
+    if (componentsJson) {
+        if (!uiLibraries.includes('shadcn-ui')) uiLibraries.push('shadcn-ui');
+    }
+
+    // tsconfig paths
+    const tsconfigPath = exists(rootDir, 'tsconfig.json') || exists(rootDir, 'tsconfig.base.json');
+    let tsconfigPaths: Record<string, string[]> | undefined;
+    if (tsconfigPath) {
+        const tsconfig = readJsonIfExists(tsconfigPath);
+        const paths = tsconfig?.compilerOptions?.paths;
+        if (paths && typeof paths === 'object') {
+            tsconfigPaths = paths;
+        }
+    }
+
+    const tailwindConfig =
+        exists(rootDir, 'tailwind.config.ts') ||
+        exists(rootDir, 'tailwind.config.js') ||
+        exists(rootDir, 'tailwind.config.cjs') ||
+        exists(rootDir, 'tailwind.config.mjs');
+
+    return {
+        root: rootDir,
+        framework,
+        language: { typescript: hasTs },
+        styling: { primary, detected: Array.from(new Set(detectedStyling)) },
+        uiLibraries: Array.from(new Set(uiLibraries)),
+        iconLibraries: Array.from(new Set(iconLibraries)),
+        tooling: {
+            storybook: hasStorybook,
+            eslint: hasEslint,
+            prettier: hasPrettier,
+            vitest: hasVitest,
+            jest: hasJest,
+        },
+        conventions: {
+            srcDir,
+            hasAppDir,
+            hasPagesDir,
+            tsconfigPaths,
+        },
+        files: {
+            packageJson: pkgPath || undefined,
+            tsconfig: tsconfigPath || undefined,
+            tailwindConfig: tailwindConfig || undefined,
+            componentsJson: componentsJson || undefined,
+            storybookDir: exists(rootDir, '.storybook') || undefined,
+        },
+        warnings,
+    };
+}

package/src/tokens/sync.ts

@@ -0,0 +1,212 @@
+/**
+ * Token Sync Utilities
+ *
+ * Normalizes tokens into a small internal representation and can output:
+ * - CSS custom properties
+ * - Tailwind theme extension
+ * - Tokens Studio JSON
+ * - Style Dictionary JSON
+ */
+
+import * as path from 'node:path';
+
+export type TokenType = 'color' | 'dimension' | 'fontFamily' | 'fontWeight' | 'number' | 'string' | 'shadow' | 'duration' | 'easing';
+
+export interface Token {
+    name: string; // normalized token name, e.g. color.primary
+    value: string;
+    type: TokenType;
+    description?: string;
+    source?: {
+        file?: string;
+        originalName?: string;
+    };
+}
+
+export interface TokenParseResult {
+    tokens: Token[];
+    warnings: string[];
+}
+
+function isColorValue(v: string): boolean {
+    const s = v.trim().toLowerCase();
+    return (
+        /^#([0-9a-f]{3,8})$/.test(s) ||
+        /^rgb\(/.test(s) ||
+        /^rgba\(/.test(s) ||
+        /^hsl\(/.test(s) ||
+        /^hsla\(/.test(s) ||
+        /^oklch\(/.test(s) ||
+        /^oklab\(/.test(s)
+    );
+}
+
+function isDimensionValue(v: string): boolean {
+    const s = v.trim().toLowerCase();
+    return /^-?\d+(\.\d+)?(px|rem|em|vh|vw|%|ch|ex)$/.test(s);
+}
+
+function isDurationValue(v: string): boolean {
+    const s = v.trim().toLowerCase();
+    return /^\d+(\.\d+)?(ms|s)$/.test(s);
+}
+
+function inferTokenType(name: string, value: string): TokenType {
+    const n = name.toLowerCase();
+    const v = value.trim();
+    if (isColorValue(v) || n.includes('color') || n.includes('bg') || n.includes('foreground') || n.includes('surface')) return 'color';
+    if (isDurationValue(v) || n.includes('duration') || n.includes('transition')) return 'duration';
+    if (n.includes('easing') || n.includes('ease')) return 'easing';
+    if (n.includes('shadow') || v.includes('rgba') && v.includes('px')) return 'shadow';
+    if (n.includes('font') && n.includes('family')) return 'fontFamily';
+    if (n.includes('weight')) return 'fontWeight';
+    if (isDimensionValue(v) || n.includes('space') || n.includes('radius') || n.includes('size') || n.includes('gap')) return 'dimension';
+    if (/^-?\d+(\.\d+)?$/.test(v)) return 'number';
+    return 'string';
+}
+
+function normalizeCssVarNameToTokenName(cssVar: string): string {
+    // '--color-primary' -> 'color.primary'
+    // '--radius-md' -> 'radius.md'
+    let n = cssVar.trim();
+    if (n.startsWith('--')) n = n.slice(2);
+    n = n.replace(/\s+/g, '-');
+    // Convert separators to dots for nesting
+    return n
+        .replace(/__/g, '.')
+        .replace(/--/g, '.')
+        .replace(/-/g, '.')
+        .replace(/\.+/g, '.')
+        .replace(/^\./, '')
+        .replace(/\.$/, '');
+}
+
+export function parseCssVars(content: string, sourceFile?: string): TokenParseResult {
+    const warnings: string[] = [];
+    const tokens: Token[] = [];
+
+    // Very simple parse: extract any --var: value; pairs
+    const re = /(--[A-Za-z0-9_-]+)\s*:\s*([^;\n\r]+)\s*;/g;
+    let match: RegExpExecArray | null;
+    const seen = new Set<string>();
+
+    while ((match = re.exec(content))) {
+        const originalName = match[1];
+        const value = match[2].trim();
+        const name = normalizeCssVarNameToTokenName(originalName);
+        if (!name) continue;
+        if (seen.has(name)) continue;
+        seen.add(name);
+
+        tokens.push({
+            name,
+            value,
+            type: inferTokenType(name, value),
+            source: {
+                file: sourceFile ? path.basename(sourceFile) : undefined,
+                originalName,
+            },
+        });
+    }
+
+    if (tokens.length === 0) {
+        warnings.push('No CSS custom properties found (expected patterns like --token-name: value;)');
+    }
+
+    return { tokens, warnings };
+}
+
+function setNested(obj: Record<string, unknown>, pathParts: string[], value: unknown): void {
+    // Protect against prototype pollution
+    const dangerousKeys = new Set(['__proto__', 'constructor', 'prototype']);
+
+    let cur: Record<string, unknown> = obj;
+    for (let i = 0; i < pathParts.length; i++) {
+        const key = pathParts[i];
+
+        // Block dangerous keys
+        if (dangerousKeys.has(key)) {
+            return;
+        }
+
+        if (i === pathParts.length - 1) {
+            cur[key] = value;
+            return;
+        }
+
+        if (!Object.hasOwn(cur, key) || typeof cur[key] !== 'object' || cur[key] === null) {
+            cur[key] = Object.create(null) as Record<string, unknown>;
+        }
+        cur = cur[key] as Record<string, unknown>;
+    }
+}
+
+export function tokensToCssVars(tokens: Token[], options?: { selector?: string }): string {
+    const selector = options?.selector || ':root';
+    const lines = [`${selector} {`];
+    for (const t of tokens) {
+        const cssName = `--${t.name.replace(/\./g, '-')}`;
+        lines.push(`  ${cssName}: ${t.value};`);
+    }
+    lines.push('}');
+    return lines.join('\n');
+}
+
+export function tokensToTailwindTheme(tokens: Token[]): string {
+    const extend: any = { colors: {}, spacing: {}, borderRadius: {}, boxShadow: {}, fontFamily: {}, fontWeight: {}, transitionDuration: {} };
+
+    for (const t of tokens) {
+        const parts = t.name.split('.').filter(Boolean);
+        if (parts.length === 0) continue;
+        const root = parts[0];
+        const rest = parts.slice(1);
+
+        if (t.type === 'color' && (root === 'color' || root === 'colors')) {
+            setNested(extend.colors, rest.length ? rest : ['DEFAULT'], t.value);
+        } else if (t.type === 'dimension' && (root === 'space' || root === 'spacing')) {
+            setNested(extend.spacing, rest.length ? rest : ['DEFAULT'], t.value);
+        } else if (t.type === 'dimension' && (root === 'radius' || root === 'radii' || root === 'borderRadius')) {
+            setNested(extend.borderRadius, rest.length ? rest : ['DEFAULT'], t.value);
+        } else if (t.type === 'shadow' && (root === 'shadow' || root === 'shadows')) {
+            setNested(extend.boxShadow, rest.length ? rest : ['DEFAULT'], t.value);
+        } else if (t.type === 'fontFamily') {
+            setNested(extend.fontFamily, rest.length ? rest : ['sans'], t.value);
+        } else if (t.type === 'fontWeight') {
+            setNested(extend.fontWeight, rest.length ? rest : ['normal'], t.value);
+        } else if (t.type === 'duration') {
+            setNested(extend.transitionDuration, rest.length ? rest : ['DEFAULT'], t.value);
+        }
+    }
+
+    // Prune empty sections
+    for (const k of Object.keys(extend)) {
+        if (extend[k] && typeof extend[k] === 'object' && Object.keys(extend[k]).length === 0) {
+            delete extend[k];
+        }
+    }
+
+    return `/** Auto-generated by sync_design_tokens */\nexport default {\n  theme: {\n    extend: ${JSON.stringify(extend, null, 2)}\n  }\n}`;
+}
+
+export function tokensToTokensStudio(tokens: Token[]): string {
+    // Tokens Studio expects {"token": {"value": ..., "type": ...}}
+    const out: any = {};
+    for (const t of tokens) {
+        const parts = t.name.split('.').filter(Boolean);
+        if (parts.length === 0) continue;
+        setNested(out, parts, { value: t.value, type: t.type, description: t.description });
+    }
+    return JSON.stringify(out, null, 2);
+}
+
+export function tokensToStyleDictionary(tokens: Token[]): string {
+    // Style Dictionary commonly uses nested objects with { value, type }
+    // We'll output a format compatible with SD v3+ token JSON.
+    const out: any = {};
+    for (const t of tokens) {
+        const parts = t.name.split('.').filter(Boolean);
+        if (parts.length === 0) continue;
+        setNested(out, parts, { value: t.value, type: t.type });
+    }
+    return JSON.stringify(out, null, 2);
+}

package/src/tools/analyze-screenshot-ui.ts

@@ -0,0 +1,150 @@
+/**
+ * analyze_screenshot_ui Tool
+ *
+ * Multimodal screenshot analysis:
+ * - layout breakdown
+ * - component suggestions
+ * - token guesses
+ * - accessibility notes
+ *
+ * This tool can run in:
+ * - local gemini mode (Gemini SDK multimodal)
+ * - remote mode (gateway supports userParts)
+ * - local litellm mode (OpenAI-compatible image_url content)
+ */
+
+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 { assertReadablePath } from '../context/guards.js';
+import { sanitizeContent } from '../context/filter.js';
+import { buildContext } from '../context/builder.js';
+import { generateWithGemini } from '../generation/gemini-client.js';
+
+const inputSchema = {
+    imagePath: z.string().optional().describe('Path to an image file (png/jpg/webp).'),
+    imageBase64: z.string().optional().describe('Base64 image data (if not using imagePath).'),
+    mimeType: z.string().optional().describe('Image mime type, e.g. image/png. Required when using imageBase64.'),
+    instruction: z
+        .string()
+        .optional()
+        .describe('What to extract from the screenshot. Defaults to a full UI breakdown.'),
+    outputFormat: z.enum(['json', 'markdown']).default('json').describe('Response format.'),
+    framework: z
+        .enum(['react', 'nextjs', 'vue', 'svelte', 'vanilla'])
+        .optional()
+        .describe('Target framework hint.'),
+    context: z.array(z.string()).optional().describe('Related design/token files for grounding.'),
+};
+
+const SYSTEM_PROMPT = `You are a senior UI engineer and design system expert.
+
+You will analyze a UI screenshot and return a structured breakdown suitable for code generation.
+
+Output requirements:
+- If outputFormat=json: output ONE valid JSON object only. No prose. No markdown. No code fences.
+- If outputFormat=markdown: output concise markdown with headings and bullet points.
+
+When outputFormat=json, include:
+{
+  "layout": {"type": "page|modal|panel|component", "grid": "...", "sections": [...]},
+  "components": [{"name": "...", "role": "...", "suggestedImplementation": "..."}],
+  "tokensGuess": {"colors": [...], "typography": [...], "spacing": [...], "radii": [...], "shadows": [...]},
+  "a11y": {"landmarks": [...], "labels": [...], "keyboard": [...], "contrastRisks": [...]},
+  "notes": [...]
+}
+
+Be practical: prefer reusable primitives (Button, Input, Card, Table) and suggest variants/states.
+Do not invent backend logic.`;
+
+function mimeFromPath(p: string): string {
+    const ext = path.extname(p).toLowerCase();
+    if (ext === '.png') return 'image/png';
+    if (ext === '.jpg' || ext === '.jpeg') return 'image/jpeg';
+    if (ext === '.webp') return 'image/webp';
+    return 'application/octet-stream';
+}
+
+export function registerAnalyzeScreenshotUI(server: McpServer, config: Config): void {
+    server.registerTool(
+        'analyze_screenshot_ui',
+        {
+            title: 'Analyze UI Screenshot',
+            description:
+                'Analyze a UI screenshot (layout/components/tokens/a11y). Supports multimodal prompts in local or remote mode.',
+            inputSchema,
+        },
+        async (args) => {
+            const imagePath = args.imagePath as string | undefined;
+            const imageBase64 = args.imageBase64 as string | undefined;
+            const mimeType = args.mimeType as string | undefined;
+            const instruction = (args.instruction as string | undefined) || '';
+            const outputFormat = (args.outputFormat as 'json' | 'markdown') || 'json';
+            const framework = (args.framework as Config['defaultFramework'] | undefined) || config.defaultFramework;
+            const contextPaths = args.context as string[] | undefined;
+
+            if (!imagePath && !imageBase64) {
+                return {
+                    content: [{ type: 'text' as const, text: 'Error: Provide imagePath or imageBase64.' }],
+                    isError: true,
+                };
+            }
+
+            let data: string;
+            let mime: string;
+
+            try {
+                if (imagePath) {
+                    const safe = assertReadablePath(imagePath, config);
+                    const buf = fs.readFileSync(safe);
+                    data = buf.toString('base64');
+                    mime = mimeFromPath(safe);
+                } else {
+                    data = imageBase64 as string;
+                    mime = mimeType || 'application/octet-stream';
+                }
+            } catch (error) {
+                const message = error instanceof Error ? error.message : 'Could not read image';
+                return { content: [{ type: 'text' as const, text: `Error: ${message}` }], isError: true };
+            }
+
+            let contextContent = '';
+            if (contextPaths && contextPaths.length > 0) {
+                contextContent = await buildContext(contextPaths, config);
+                contextContent = sanitizeContent(contextContent);
+            }
+
+            const userText = `Analyze this screenshot.
+
+outputFormat: ${outputFormat}
+frameworkHint: ${framework}
+instruction: ${instruction || '(full breakdown)'}
+
+${contextContent ? `RELATED FILES (sanitized):\n${contextContent}` : ''}
+
+Return in the requested format.`;
+
+            try {
+                const resp = await generateWithGemini(
+                    config,
+                    SYSTEM_PROMPT,
+                    [
+                        { text: userText },
+                        { inlineData: { mimeType: mime, data } },
+                    ],
+                    { toolName: 'analyze_screenshot_ui' }
+                );
+
+                return { content: [{ type: 'text' as const, text: resp.trim() }] };
+            } catch (error) {
+                const message = error instanceof Error ? error.message : 'Unknown error';
+                return {
+                    content: [{ type: 'text' as const, text: `Error analyzing screenshot: ${message}` }],
+                    isError: true,
+                };
+            }
+        }
+    );
+}

package/src/tools/analyze-tokens.ts

@@ -0,0 +1,123 @@
+/**
+ * analyze_tokens Tool
+ *
+ * Extracts and understands existing design systems.
+ * Returns structured design tokens from CSS/SCSS files.
+ */
+
+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 } from '../context/guards.js';
+import { sanitizeContent } from '../context/filter.js';
+import { generateWithGemini } from '../generation/gemini-client.js';
+
+const inputSchema = {
+    paths: z.array(z.string()).describe('Paths to CSS, SCSS, or design token files to analyze'),
+    format: z
+        .enum(['json', 'css-vars', 'tailwind', 'summary'])
+        .default('json')
+        .describe('Output format for the extracted tokens'),
+};
+
+const SYSTEM_PROMPT = `You are a design system analyst. Your task is to extract and structure design tokens from CSS/SCSS files.
+
+Analyze the provided files and extract:
+1. Colors - with semantic names and usage hints
+2. Typography - font families, sizes, weights, line heights
+3. Spacing - margin/padding values, identify a scale (e.g. 4px base)
+4. Breakpoints - media query values
+5. Shadows - box-shadow values
+6. Border radii - radius values
+7. Transitions - duration and easing values
+8. Z-index - layering values
+
+Output rules:
+- If format=json: output ONE valid JSON object only. No prose. No markdown. No code fences.
+- If format=css-vars: output ONLY CSS custom properties (no markdown).
+- If format=tailwind: output ONLY a tailwind theme extension (JS object or full tailwind.config.js), no markdown.
+- If format=summary: output concise bullet points.
+
+When naming tokens, prefer semantic names (primary, surface, text, border) rather than raw hex values.`;
+
+export function registerAnalyzeTokens(server: McpServer, config: Config): void {
+    server.registerTool(
+        'analyze_tokens',
+        {
+            title: 'Analyze Design Tokens',
+            description:
+                'Extract and structure design tokens from existing CSS/SCSS files. Use before create_ui to understand existing design systems.',
+            inputSchema,
+        },
+        async (args) => {
+            const paths = args.paths as string[];
+            const format = (args.format as 'json' | 'css-vars' | 'tailwind' | 'summary') || 'json';
+
+            // Read all specified files (with safety checks)
+            const fileContents: string[] = [];
+            const errors: string[] = [];
+
+            for (const filePath of paths) {
+                try {
+                    const safePath = assertReadablePath(filePath, config);
+                    const raw = fs.readFileSync(safePath, 'utf-8');
+                    const content = sanitizeContent(raw);
+                    fileContents.push(`/* File: ${filePath} */\n${content}`);
+                } catch (error) {
+                    const message = error instanceof Error ? error.message : 'Could not read';
+                    errors.push(`${filePath}: ${message}`);
+                }
+            }
+
+            if (fileContents.length === 0) {
+                return {
+                    content: [
+                        {
+                            type: 'text' as const,
+                            text: `Error: Could not read any files.\n${errors.join('\n')}`,
+                        },
+                    ],
+                    isError: true,
+                };
+            }
+
+            if (errors.length > 0 && config.debug) {
+                console.error('[analyze_tokens] Warnings:\n' + errors.join('\n'));
+            }
+
+            const combinedContent = fileContents.join('\n\n');
+
+            const userPrompt = `Analyze these CSS/SCSS files and extract design tokens.
+Format: ${format}
+
+FILES:
+${combinedContent}`;
+
+            try {
+                const response = await generateWithGemini(config, SYSTEM_PROMPT, userPrompt, { toolName: 'analyze_tokens' });
+
+                // IMPORTANT: Return raw model output ONLY (no wrappers) so JSON / CSS output stays valid.
+                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 analyzing tokens: ${message}`,
+                        },
+                    ],
+                    isError: true,
+                };
+            }
+        }
+    );
+}