@gemini-designer/mcp-server 0.1.0

package/src/components/catalog.ts

@@ -0,0 +1,214 @@
+/**
+ * Component Catalog
+ *
+ * Scans TSX/JSX files and extracts exported component-like symbols.
+ *
+ * Notes:
+ * - Uses TypeScript compiler API when available.
+ * - Falls back to a lightweight regex scan if TypeScript is not installed.
+ */
+
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { toPosixPath } from '../utils/walk.js';
+
+export interface ComponentExport {
+    name: string;
+    exportType: 'named' | 'default';
+    file: string; // relative to root
+    propsType?: string;
+    jsDoc?: string;
+}
+
+export interface CatalogResult {
+    root: string;
+    filesScanned: number;
+    components: ComponentExport[];
+    warnings: string[];
+}
+
+function readFileSafe(filePath: string): string | null {
+    try {
+        return fs.readFileSync(filePath, 'utf-8');
+    } catch {
+        return null;
+    }
+}
+
+function rel(root: string, abs: string): string {
+    return toPosixPath(path.relative(root, abs));
+}
+
+function extractJSDocFromLeadingComment(text: string): string | undefined {
+    // Simple: capture /** ... */ immediately preceding export
+    const m = text.match(/\/\*\*([\s\S]*?)\*\//);
+    if (!m) return undefined;
+    const cleaned = m[1]
+        .split('\n')
+        .map((l) => l.replace(/^\s*\*\s?/, '').trim())
+        .filter(Boolean)
+        .join(' ');
+    return cleaned || undefined;
+}
+
+async function scanWithTypeScript(root: string, files: string[]): Promise<CatalogResult> {
+    const warnings: string[] = [];
+    const components: ComponentExport[] = [];
+
+    const ts = await import('typescript');
+
+    const getScriptKind = (filePath: string): any => {
+        const ext = path.extname(filePath).toLowerCase();
+        if (ext === '.tsx') return ts.ScriptKind.TSX;
+        if (ext === '.jsx') return ts.ScriptKind.JSX;
+        if (ext === '.ts') return ts.ScriptKind.TS;
+        if (ext === '.js') return ts.ScriptKind.JS;
+        return ts.ScriptKind.Unknown;
+    };
+
+    for (const f of files) {
+        const content = readFileSafe(f);
+        if (content == null) continue;
+
+        const sf = ts.createSourceFile(f, content, ts.ScriptTarget.ES2022, true, getScriptKind(f));
+
+        const isExported = (node: any): boolean => {
+            const mods = node.modifiers;
+            if (!mods) return false;
+            return mods.some((m: any) => m.kind === ts.SyntaxKind.ExportKeyword);
+        };
+
+        const isDefaultExport = (node: any): boolean => {
+            const mods = node.modifiers;
+            if (!mods) return false;
+            return mods.some((m: any) => m.kind === ts.SyntaxKind.DefaultKeyword);
+        };
+
+        const textOfType = (typeNode: any): string | undefined => {
+            if (!typeNode) return undefined;
+            return content.slice(typeNode.pos, typeNode.end).trim();
+        };
+
+        // Collect import modules (optional future use)
+        // const imports = sf.statements.filter(ts.isImportDeclaration).map((i: any) => i.moduleSpecifier.text);
+
+        for (const stmt of sf.statements) {
+            if (ts.isFunctionDeclaration(stmt) && isExported(stmt)) {
+                const name = stmt.name?.text || (isDefaultExport(stmt) ? 'default' : 'anonymous');
+                const firstParam = stmt.parameters?.[0];
+                const propsType = textOfType(firstParam?.type);
+                components.push({
+                    name: name === 'default' ? path.basename(f, path.extname(f)) : name,
+                    exportType: isDefaultExport(stmt) ? 'default' : 'named',
+                    file: rel(root, f),
+                    propsType,
+                });
+                continue;
+            }
+
+            if (ts.isVariableStatement(stmt) && isExported(stmt)) {
+                for (const decl of stmt.declarationList.declarations) {
+                    const name = decl.name && ts.isIdentifier(decl.name) ? decl.name.text : undefined;
+                    if (!name) continue;
+
+                    // Component-like initializers
+                    const init = decl.initializer;
+                    let propsType: string | undefined;
+                    if (init && (ts.isArrowFunction(init) || ts.isFunctionExpression(init))) {
+                        const firstParam = init.parameters?.[0];
+                        propsType = textOfType(firstParam?.type);
+                    }
+
+                    // React.forwardRef(...) pattern: export const X = React.forwardRef<...>((props, ref) => ...)
+                    if (init && ts.isCallExpression(init)) {
+                        const args = init.arguments;
+                        const firstArg = args?.[0];
+                        if (firstArg && (ts.isArrowFunction(firstArg) || ts.isFunctionExpression(firstArg))) {
+                            const firstParam = firstArg.parameters?.[0];
+                            propsType = textOfType(firstParam?.type);
+                        }
+                    }
+
+                    components.push({
+                        name,
+                        exportType: 'named',
+                        file: rel(root, f),
+                        propsType,
+                    });
+                }
+                continue;
+            }
+
+            if (ts.isExportAssignment(stmt)) {
+                const expr = stmt.expression;
+                const name = ts.isIdentifier(expr) ? expr.text : path.basename(f, path.extname(f));
+                components.push({ name, exportType: 'default', file: rel(root, f) });
+                continue;
+            }
+        }
+    }
+
+    return {
+        root,
+        filesScanned: files.length,
+        components,
+        warnings,
+    };
+}
+
+function scanWithRegexFallback(root: string, files: string[]): CatalogResult {
+    const components: ComponentExport[] = [];
+    const warnings: string[] = ['TypeScript compiler API unavailable; using regex fallback (less accurate).'];
+
+    for (const f of files) {
+        const content = readFileSafe(f);
+        if (content == null) continue;
+
+        // export function Foo(...)
+        const fnRe = /export\s+(default\s+)?function\s+([A-Za-z0-9_]+)/g;
+        let m: RegExpExecArray | null;
+        while ((m = fnRe.exec(content))) {
+            components.push({
+                name: m[2],
+                exportType: m[1] ? 'default' : 'named',
+                file: rel(root, f),
+                jsDoc: extractJSDocFromLeadingComment(content.slice(0, m.index)),
+            });
+        }
+
+        // export const Foo = (...)
+        const constRe = /export\s+const\s+([A-Za-z0-9_]+)/g;
+        while ((m = constRe.exec(content))) {
+            components.push({
+                name: m[1],
+                exportType: 'named',
+                file: rel(root, f),
+                jsDoc: extractJSDocFromLeadingComment(content.slice(0, m.index)),
+            });
+        }
+
+        // export default Identifier
+        const defRe = /export\s+default\s+([A-Za-z0-9_]+)/g;
+        while ((m = defRe.exec(content))) {
+            components.push({
+                name: m[1],
+                exportType: 'default',
+                file: rel(root, f),
+                jsDoc: extractJSDocFromLeadingComment(content.slice(0, m.index)),
+            });
+        }
+    }
+
+    return { root, filesScanned: files.length, components, warnings };
+}
+
+export async function buildComponentCatalog(root: string, files: string[]): Promise<CatalogResult> {
+    try {
+        return await scanWithTypeScript(root, files);
+    } catch (error) {
+        const msg = error instanceof Error ? error.message : 'unknown error';
+        const fallback = scanWithRegexFallback(root, files);
+        fallback.warnings.push(`TypeScript scan failed: ${msg}`);
+        return fallback;
+    }
+}

package/src/config/index.ts

@@ -0,0 +1,237 @@
+/**
+ * Configuration System
+ *
+ * Loads config from environment variables, config file, and CLI args.
+ * Priority: CLI > ENV > config file > defaults
+ */
+
+import { z } from 'zod';
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+
+const ConfigSchema = z.object({
+    // Mode: 'local' uses direct Gemini API, 'remote' uses gateway
+    mode: z.enum(['local', 'remote']).default('local'),
+
+    // Local provider: direct Gemini SDK, or OpenAI-compatible proxy (e.g. LiteLLM)
+    // Default to LiteLLM because it unlocks routing, retries, caching, and load balancing.
+    // If LiteLLM is not configured, we will automatically fall back to direct Gemini.
+    localProvider: z.enum(['gemini', 'litellm']).default('litellm'),
+
+    // API key for local mode (required if mode is 'local')
+    apiKey: z.string().optional(),
+
+    // Remote gateway endpoint (required if mode is 'remote')
+    remoteEndpoint: z.string().url().optional(),
+
+    // Remote API key for gateway authentication
+    remoteApiKey: z.string().optional(),
+
+    // Workspace paths that can be accessed
+    allowedPaths: z.array(z.string()).default([process.cwd()]),
+
+    // Default framework for generated code
+    defaultFramework: z
+        .enum(['vanilla', 'react', 'vue', 'svelte', 'nextjs'])
+        .default('react'),
+
+    // Gemini model to use (for local mode)
+    model: z.string().default('gemini-2.5-flash-lite'),
+
+    // LiteLLM (or other OpenAI-compatible proxy) configuration for local mode
+    litellmEndpoint: z.string().url().optional(),
+    litellmApiKey: z.string().optional(),
+    litellmModel: z.string().optional(),
+
+    // Default accessibility level
+    accessibility: z.enum(['none', 'wcag-a', 'wcag-aa', 'wcag-aaa']).default('wcag-aa'),
+
+    // Responsive breakpoints
+    breakpoints: z
+        .record(z.number())
+        .default({
+            sm: 640,
+            md: 768,
+            lg: 1024,
+            xl: 1280,
+            '2xl': 1536,
+        }),
+
+    // Debug mode
+    debug: z.boolean().default(false),
+});
+
+export type Config = z.infer<typeof ConfigSchema>;
+
+/**
+ * Load configuration from all sources
+ */
+export function loadConfig(): Config {
+    const configFromFile = loadConfigFile();
+    const configFromEnv = loadConfigFromEnv();
+    const configFromArgs = loadConfigFromArgs();
+
+    // Merge configs with priority: args > env > file > defaults
+    const merged = {
+        ...configFromFile,
+        ...configFromEnv,
+        ...configFromArgs,
+    };
+
+    const result = ConfigSchema.safeParse(merged);
+
+    if (!result.success) {
+        console.error('[config] Invalid configuration:', result.error.format());
+        throw new Error('Invalid configuration');
+    }
+
+    // Apply smart defaults / fallbacks
+    // - We default to localProvider=litellm, but automatically fall back to direct Gemini
+    //   when LiteLLM isn't configured.
+    let cfg: Config = result.data;
+
+    if (cfg.mode === 'local') {
+        const hasLite = Boolean(cfg.litellmEndpoint);
+        const hasGemini = Boolean(cfg.apiKey);
+
+        if (cfg.localProvider === 'litellm' && !hasLite) {
+            if (hasGemini) {
+                if (cfg.debug) {
+                    console.error('[config] LITELLM_ENDPOINT missing; falling back to localProvider=gemini');
+                }
+                cfg = { ...cfg, localProvider: 'gemini' };
+            }
+        }
+
+        if (cfg.localProvider === 'gemini' && !hasGemini) {
+            if (hasLite) {
+                if (cfg.debug) {
+                    console.error('[config] GEMINI_API_KEY missing; falling back to localProvider=litellm');
+                }
+                cfg = { ...cfg, localProvider: 'litellm' };
+            }
+        }
+
+        // Validate mode-specific requirements after applying fallbacks
+        if (cfg.localProvider === 'gemini' && !cfg.apiKey) {
+            console.error('[config] Local mode (gemini) requires GEMINI_API_KEY environment variable');
+            throw new Error('Missing Gemini API key for local mode');
+        }
+
+        if (cfg.localProvider === 'litellm' && !cfg.litellmEndpoint) {
+            console.error('[config] Local mode (litellm) requires LITELLM_ENDPOINT');
+            throw new Error('Missing LiteLLM endpoint for local mode');
+        }
+    }
+
+    if (cfg.mode === 'remote' && !cfg.remoteEndpoint) {
+        console.error('[config] Remote mode requires GEMINI_DESIGNER_REMOTE_ENDPOINT');
+        throw new Error('Missing remote endpoint for remote mode');
+    }
+
+    return cfg;
+}
+
+/**
+ * Load from .gemini-designer.json config file
+ */
+function loadConfigFile(): Partial<Config> {
+    const configPath = path.join(process.cwd(), '.gemini-designer.json');
+
+    if (!fs.existsSync(configPath)) {
+        return {};
+    }
+
+    try {
+        const content = fs.readFileSync(configPath, 'utf-8');
+        return JSON.parse(content);
+    } catch (error) {
+        console.error('[config] Error reading config file:', error);
+        return {};
+    }
+}
+
+/**
+ * Load from environment variables
+ */
+function loadConfigFromEnv(): Partial<Config> {
+    const config: Partial<Config> = {};
+
+    if (process.env.GEMINI_API_KEY) {
+        config.apiKey = process.env.GEMINI_API_KEY;
+    }
+
+    if (process.env.GEMINI_DESIGNER_MODE) {
+        config.mode = process.env.GEMINI_DESIGNER_MODE as 'local' | 'remote';
+    }
+
+    if (process.env.GEMINI_DESIGNER_LOCAL_PROVIDER) {
+        config.localProvider = process.env.GEMINI_DESIGNER_LOCAL_PROVIDER as Config['localProvider'];
+    }
+
+    if (process.env.GEMINI_DESIGNER_REMOTE_ENDPOINT) {
+        config.remoteEndpoint = process.env.GEMINI_DESIGNER_REMOTE_ENDPOINT;
+    }
+
+    if (process.env.GEMINI_DESIGNER_REMOTE_API_KEY) {
+        config.remoteApiKey = process.env.GEMINI_DESIGNER_REMOTE_API_KEY;
+    }
+
+    if (process.env.GEMINI_DESIGNER_DEBUG === 'true') {
+        config.debug = true;
+    }
+
+    if (process.env.GEMINI_DESIGNER_FRAMEWORK) {
+        config.defaultFramework = process.env.GEMINI_DESIGNER_FRAMEWORK as Config['defaultFramework'];
+    }
+
+    if (process.env.GEMINI_MODEL) {
+        config.model = process.env.GEMINI_MODEL;
+    }
+
+    if (process.env.LITELLM_ENDPOINT) {
+        config.litellmEndpoint = process.env.LITELLM_ENDPOINT;
+    }
+
+    if (process.env.LITELLM_API_KEY) {
+        config.litellmApiKey = process.env.LITELLM_API_KEY;
+    }
+
+    if (process.env.LITELLM_MODEL) {
+        config.litellmModel = process.env.LITELLM_MODEL;
+    }
+
+    return config;
+}
+
+/**
+ * Load from CLI arguments
+ */
+function loadConfigFromArgs(): Partial<Config> {
+    const args = process.argv.slice(2);
+    const config: Partial<Config> = {};
+
+    for (let i = 0; i < args.length; i++) {
+        const arg = args[i];
+
+        if (arg === '--local') {
+            config.mode = 'local';
+        } else if (arg === '--remote') {
+            config.mode = 'remote';
+        } else if (arg === '--provider' && args[i + 1]) {
+            config.localProvider = args[++i] as Config['localProvider'];
+        } else if (arg === '--debug') {
+            config.debug = true;
+        } else if (arg === '--api-key' && args[i + 1]) {
+            config.apiKey = args[++i];
+        } else if (arg === '--litellm-endpoint' && args[i + 1]) {
+            config.litellmEndpoint = args[++i];
+        } else if (arg === '--litellm-model' && args[i + 1]) {
+            config.litellmModel = args[++i];
+        } else if (arg === '--endpoint' && args[i + 1]) {
+            config.remoteEndpoint = args[++i];
+        }
+    }
+
+    return config;
+}

package/src/context/builder.ts

@@ -0,0 +1,233 @@
+/**
+ * Context Builder
+ *
+ * Builds token-optimized context from specified files.
+ * Filters out sensitive content and optimizes for relevance.
+ * Includes token counting for quota management.
+ */
+
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { Config } from '../config/index.js';
+import { isPathAllowed, isSensitiveFile, sanitizeContent } from './filter.js';
+
+// Token estimation: ~4 characters per token for English text/code
+const CHARS_PER_TOKEN = 4;
+const MAX_CONTEXT_TOKENS = 12500; // ~50k chars
+const MAX_FILE_TOKENS = 2500; // ~10k chars per file
+
+export interface ContextResult {
+    content: string;
+    estimatedTokens: number;
+    filesIncluded: string[];
+    filesSkipped: string[];
+    truncated: boolean;
+}
+
+/**
+ * Estimate token count from text
+ */
+export function estimateTokens(text: string): number {
+    return Math.ceil(text.length / CHARS_PER_TOKEN);
+}
+
+/**
+ * Build context from specified file paths with token optimization
+ */
+export async function buildContext(paths: string[], config: Config): Promise<string> {
+    const result = await buildContextWithMetadata(paths, config);
+    return result.content;
+}
+
+/**
+ * Build context with full metadata (tokens, files included, etc.)
+ */
+export async function buildContextWithMetadata(
+    paths: string[],
+    config: Config
+): Promise<ContextResult> {
+    const contents: string[] = [];
+    const filesIncluded: string[] = [];
+    const filesSkipped: string[] = [];
+    let totalTokens = 0;
+    let truncated = false;
+
+    // Sort paths by likely relevance (design tokens first, then components)
+    const sortedPaths = sortByRelevance(paths);
+
+    for (const filePath of sortedPaths) {
+        // Resolve to absolute path
+        const absPath = path.isAbsolute(filePath) ? filePath : path.resolve(process.cwd(), filePath);
+
+        // Security check: path must be in allowed paths
+        if (!isPathAllowed(absPath, config.allowedPaths)) {
+            if (config.debug) {
+                console.error(`[context] Skipping ${filePath}: outside allowed paths`);
+            }
+            filesSkipped.push(`${filePath} (outside allowed paths)`);
+            continue;
+        }
+
+        // Security check: not a sensitive file
+        if (isSensitiveFile(absPath)) {
+            if (config.debug) {
+                console.error(`[context] Skipping ${filePath}: sensitive file`);
+            }
+            filesSkipped.push(`${filePath} (sensitive)`);
+            continue;
+        }
+
+        // Check if file exists and is a file
+        if (!fs.existsSync(absPath)) {
+            filesSkipped.push(`${filePath} (not found)`);
+            continue;
+        }
+
+        const stat = fs.statSync(absPath);
+        if (!stat.isFile()) {
+            filesSkipped.push(`${filePath} (not a file)`);
+            continue;
+        }
+
+        try {
+            let content = fs.readFileSync(absPath, 'utf-8');
+
+            // Sanitize content to remove any secrets
+            content = sanitizeContent(content);
+
+            // Calculate tokens for this file
+            let fileTokens = estimateTokens(content);
+            const maxFileChars = MAX_FILE_TOKENS * CHARS_PER_TOKEN;
+
+            // Truncate large files
+            if (fileTokens > MAX_FILE_TOKENS) {
+                content = smartTruncate(content, maxFileChars);
+                fileTokens = MAX_FILE_TOKENS;
+            }
+
+            // Check if adding this would exceed total limit
+            if (totalTokens + fileTokens > MAX_CONTEXT_TOKENS) {
+                if (config.debug) {
+                    console.error(`[context] Stopping: token limit reached`);
+                }
+                truncated = true;
+                break;
+            }
+
+            const ext = path.extname(absPath);
+            const header = `/* File: ${path.basename(absPath)} (${ext}) - ~${fileTokens} tokens */`;
+            contents.push(`${header}\n${content}`);
+            filesIncluded.push(filePath);
+            totalTokens += fileTokens;
+        } catch (error) {
+            if (config.debug) {
+                console.error(`[context] Error reading ${filePath}:`, error);
+            }
+            filesSkipped.push(`${filePath} (read error)`);
+        }
+    }
+
+    return {
+        content: contents.length > 0 ? contents.join('\n\n---\n\n') : '',
+        estimatedTokens: totalTokens,
+        filesIncluded,
+        filesSkipped,
+        truncated,
+    };
+}
+
+/**
+ * Sort paths by relevance (design tokens and variables first)
+ */
+function sortByRelevance(paths: string[]): string[] {
+    const priority: Record<string, number> = {
+        tokens: 0,
+        variables: 0,
+        theme: 1,
+        design: 1,
+        colors: 2,
+        typography: 2,
+        styles: 3,
+        css: 4,
+    };
+
+    return [...paths].sort((a, b) => {
+        const aName = path.basename(a).toLowerCase();
+        const bName = path.basename(b).toLowerCase();
+
+        let aPriority = 10;
+        let bPriority = 10;
+
+        for (const [key, value] of Object.entries(priority)) {
+            if (aName.includes(key)) aPriority = Math.min(aPriority, value);
+            if (bName.includes(key)) bPriority = Math.min(bPriority, value);
+        }
+
+        return aPriority - bPriority;
+    });
+}
+
+/**
+ * Smart truncate: keep beginning and end, with clear indicator
+ */
+function smartTruncate(content: string, maxChars: number): string {
+    if (content.length <= maxChars) return content;
+
+    const keepStart = Math.floor(maxChars * 0.7);
+    const keepEnd = Math.floor(maxChars * 0.2);
+
+    const start = content.slice(0, keepStart);
+    const end = content.slice(-keepEnd);
+
+    return `${start}\n\n/* ... [${Math.round((content.length - maxChars) / 1000)}k chars truncated] ... */\n\n${end}`;
+}
+
+/**
+ * Automatically discover relevant UI files in a directory
+ */
+export async function discoverUIFiles(directory: string, config: Config): Promise<string[]> {
+    const uiPatterns = [
+        /\.(css|scss|less|sass)$/,
+        /\.(tsx|jsx)$/,
+        /\.(vue|svelte)$/,
+        /theme\./,
+        /design[-_]?tokens?\./,
+        /tailwind\.config\./,
+    ];
+
+    const files: string[] = [];
+
+    function scan(dir: string, depth: number = 0) {
+        if (depth > 3) return; // Max depth
+
+        try {
+            const entries = fs.readdirSync(dir, { withFileTypes: true });
+
+            for (const entry of entries) {
+                const fullPath = path.join(dir, entry.name);
+
+                // Skip node_modules, .git, etc.
+                if (entry.isDirectory()) {
+                    if (['node_modules', '.git', 'dist', 'build', '.next', '.nuxt'].includes(entry.name)) {
+                        continue;
+                    }
+                    scan(fullPath, depth + 1);
+                } else if (entry.isFile()) {
+                    // Check if matches UI patterns
+                    if (uiPatterns.some((pattern) => pattern.test(entry.name))) {
+                        if (isPathAllowed(fullPath, config.allowedPaths) && !isSensitiveFile(fullPath)) {
+                            files.push(fullPath);
+                        }
+                    }
+                }
+            }
+        } catch {
+            // Skip directories we can't read
+        }
+    }
+
+    scan(directory);
+
+    // Sort by relevance
+    return sortByRelevance(files);
+}