@gemini-designer/mcp-server 0.1.0

package/src/context/filter.ts

@@ -0,0 +1,164 @@
+/**
+ * Context Filter
+ *
+ * Security patterns to prevent sensitive data from being shared.
+ * Ensures only UI-relevant files are included in context.
+ */
+
+import * as path from 'node:path';
+
+/**
+ * Files/directories that should NEVER be included in context
+ */
+const SENSITIVE_PATTERNS = [
+    // Environment and secrets
+    /\.env/i,
+    /secrets?\./i,
+    /\.pem$/i,
+    /\.key$/i,
+    /\.crt$/i,
+    /credentials/i,
+    /\.htpasswd/i,
+
+    // Private keys and certificates
+    /id_rsa/i,
+    /id_ed25519/i,
+    /\.p12$/i,
+    /\.pfx$/i,
+
+    // Config with potential secrets
+    /\.npmrc$/i,
+    /\.pypirc$/i,
+    /kubeconfig/i,
+    /\.docker\/config\.json$/i,
+
+    // Database
+    /\.sqlite$/i,
+    /\.db$/i,
+    /migrations?\//i,
+    /seeds?\//i,
+
+    // Backend/server code (when isolating UI)
+    /\/api\//i,
+    /\/server\//i,
+    /\/backend\//i,
+    /\/functions\//i, // Serverless
+    /\/lambda\//i,
+    /\/middleware\//i,
+
+    // Auth-related
+    /\/auth\//i,
+    /passport/i,
+    /jwt/i,
+
+    // System and dependencies
+    /node_modules\//i,
+    /\.git\//i,
+    /vendor\//i,
+    /\.cache\//i,
+    /\.next\//i,
+    /\.nuxt\//i,
+    /dist\//i,
+    /build\//i,
+];
+
+/**
+ * UI-relevant file patterns (for auto-discovery)
+ */
+export const UI_INCLUDE_PATTERNS = [
+    // Stylesheets
+    /\.(css|scss|less|sass|styl)$/i,
+
+    // Components
+    /\.(tsx|jsx)$/i,
+    /\.(vue|svelte)$/i,
+
+    // Design tokens
+    /theme\./i,
+    /tokens?\./i,
+    /variables\./i,
+    /design[-_]?system/i,
+
+    // Config files for styling
+    /tailwind\.config/i,
+    /postcss\.config/i,
+    /styled-components/i,
+];
+
+/**
+ * Check if a file path matches sensitive patterns
+ */
+export function isSensitiveFile(filePath: string): boolean {
+    const normalized = filePath.replace(/\\/g, '/');
+
+    for (const pattern of SENSITIVE_PATTERNS) {
+        if (pattern.test(normalized)) {
+            return true;
+        }
+    }
+
+    return false;
+}
+
+/**
+ * Check if a file path is within allowed paths
+ */
+export function isPathAllowed(filePath: string, allowedPaths: string[]): boolean {
+    const absPath = path.resolve(filePath);
+
+    for (const allowed of allowedPaths) {
+        const absAllowed = path.resolve(allowed);
+        if (absPath.startsWith(absAllowed)) {
+            return true;
+        }
+    }
+
+    return false;
+}
+
+/**
+ * Check if a file is UI-relevant
+ */
+export function isUIRelevant(filePath: string): boolean {
+    const normalized = filePath.replace(/\\/g, '/');
+
+    for (const pattern of UI_INCLUDE_PATTERNS) {
+        if (pattern.test(normalized)) {
+            return true;
+        }
+    }
+
+    return false;
+}
+
+/**
+ * Sanitize file content to remove potential secrets
+ * This is a best-effort filter for dynamic content
+ */
+export function sanitizeContent(content: string): string {
+    // Remove common secret patterns
+    const patterns = [
+        // API keys (generic patterns)
+        /(['"`])?(api[_-]?key|apikey|secret|password|token|auth)(['"`])?[\s]*[:=][\s]*['"`][^'"`]+['"`]/gi,
+
+        // Bearer tokens
+        /Bearer\s+[A-Za-z0-9\-_=]+\.[A-Za-z0-9\-_=]+\.?[A-Za-z0-9\-_.+/=]*/gi,
+
+        // AWS keys
+        /AKIA[0-9A-Z]{16}/g,
+
+        // Private keys
+        /-----BEGIN[\s\w]+PRIVATE KEY-----[\s\S]+?-----END[\s\w]+PRIVATE KEY-----/g,
+
+        // Connection strings
+        /(mongodb|postgresql|mysql|redis):\/\/[^\s'"]+/gi,
+    ];
+
+    let result = content;
+
+    for (const pattern of patterns) {
+        result = result.replace(pattern, '[REDACTED]');
+    }
+
+    return result;
+}

package/src/context/grounding.ts

@@ -0,0 +1,191 @@
+/**
+ * grounding.ts
+ *
+ * Deterministic “repo grounding” injected into prompts to improve output quality
+ * without burning large context windows.
+ *
+ * This module is used internally by tools like modify_ui and
+ * generate_component_variants to:
+ * - auto-detect the UI stack (framework/styling/libs)
+ * - catalog available components for reuse
+ *
+ * The output is intentionally concise and stable.
+ */
+
+import * as path from 'node:path';
+import { Config } from '../config/index.js';
+import { detectUiStack, type StackDetectionResult } from '../stack/detect.js';
+import { walkFiles, toPosixPath } from '../utils/walk.js';
+import { buildComponentCatalog, type CatalogResult, type ComponentExport } from '../components/catalog.js';
+
+type Cached = {
+    ts: number;
+    stack: StackDetectionResult;
+    catalog: CatalogResult;
+};
+
+const CACHE_TTL_MS = 60_000;
+const cache = new Map<string, Cached>();
+
+function resolveRootForFile(absFile: string | null, config: Config): string {
+    const allowed = (config.allowedPaths || []).map((p) => path.resolve(p));
+    const fallback = allowed[0] || process.cwd();
+    if (!absFile) return fallback;
+
+    const abs = path.resolve(absFile);
+
+    // pick the deepest allowed root that contains the file
+    const matches = allowed
+        .filter((root) => abs === root || abs.startsWith(root + path.sep))
+        .sort((a, b) => b.length - a.length);
+
+    return matches[0] || fallback;
+}
+
+function summarizeStack(stack: StackDetectionResult): string {
+    const summary = {
+        framework: stack.framework,
+        typescript: stack.language.typescript,
+        styling: stack.styling,
+        uiLibraries: stack.uiLibraries,
+        iconLibraries: stack.iconLibraries,
+        tooling: stack.tooling,
+        conventions: {
+            srcDir: stack.conventions.srcDir,
+            hasAppDir: stack.conventions.hasAppDir,
+            hasPagesDir: stack.conventions.hasPagesDir,
+            tsconfigPaths: stack.conventions.tsconfigPaths ? Object.keys(stack.conventions.tsconfigPaths) : undefined,
+        },
+        files: {
+            tailwindConfig: stack.files.tailwindConfig,
+            componentsJson: stack.files.componentsJson,
+            storybookDir: stack.files.storybookDir,
+        },
+        warnings: stack.warnings,
+    };
+    return JSON.stringify(summary, null, 2);
+}
+
+function tokenizeInstruction(instruction?: string): Set<string> {
+    const set = new Set<string>();
+    if (!instruction) return set;
+    const tokens = instruction.match(/[A-Za-z_][A-Za-z0-9_]*/g) || [];
+    for (const t of tokens) set.add(t.toLowerCase());
+    return set;
+}
+
+function scoreComponent(
+    c: ComponentExport,
+    focusDirRel: string | null,
+    instructionTokens: Set<string>
+): number {
+    let score = 0;
+
+    // Mentioned explicitly in instruction
+    if (instructionTokens.has(c.name.toLowerCase())) score += 8;
+
+    // Same directory as focused file
+    if (focusDirRel && c.file.startsWith(focusDirRel + '/')) score += 6;
+
+    // Common reusable directories
+    if (
+        c.file.includes('/components/') ||
+        c.file.startsWith('components/') ||
+        c.file.includes('/ui/') ||
+        c.file.includes('/shared/')
+    ) {
+        score += 3;
+    }
+
+    // Prefer TSX
+    if (c.file.endsWith('.tsx')) score += 1;
+
+    return score;
+}
+
+function formatCatalogSubset(catalog: CatalogResult, subset: ComponentExport[]): string {
+    const lines: string[] = [];
+    const header = `scanned_files=${catalog.filesScanned}, total_exports=${catalog.components.length}`;
+    lines.push(header);
+    if (catalog.warnings.length) {
+        lines.push(`warnings: ${catalog.warnings.join(' | ')}`);
+    }
+    lines.push('');
+    lines.push('components:');
+    for (const c of subset) {
+        const extras: string[] = [];
+        if (c.exportType) extras.push(c.exportType);
+        if (c.propsType) extras.push(`props: ${c.propsType}`);
+        if (c.jsDoc) extras.push(`doc: ${c.jsDoc}`);
+        const extra = extras.length ? ` (${extras.join(', ')})` : '';
+        lines.push(`- ${c.name} — ${c.file}${extra}`);
+    }
+    return lines.join('\n');
+}
+
+async function getOrBuildRepoData(root: string): Promise<Cached> {
+    const now = Date.now();
+    const hit = cache.get(root);
+    if (hit && now - hit.ts < CACHE_TTL_MS) return hit;
+
+    const stack = detectUiStack(root);
+    const files = walkFiles(root, {
+        includeExtensions: ['.tsx', '.jsx'],
+        maxFiles: 5000,
+    });
+    const catalog = await buildComponentCatalog(root, files);
+
+    const fresh: Cached = { ts: now, stack, catalog };
+    cache.set(root, fresh);
+    return fresh;
+}
+
+export interface RepoGroundingOptions {
+    focusFileAbs?: string;
+    instruction?: string;
+    maxComponents?: number;
+}
+
+/**
+ * Build a concise deterministic “grounding” string.
+ *
+ * This is safe to include in prompts because it contains only local, deterministic
+ * project metadata (no secrets).
+ */
+export async function buildRepoGrounding(config: Config, options: RepoGroundingOptions = {}): Promise<string> {
+    const maxComponents = typeof options.maxComponents === 'number' ? options.maxComponents : 120;
+
+    const root = resolveRootForFile(options.focusFileAbs ? path.resolve(options.focusFileAbs) : null, config);
+    const data = await getOrBuildRepoData(root);
+
+    const focusRel = options.focusFileAbs ? toPosixPath(path.relative(root, path.resolve(options.focusFileAbs))) : null;
+    const focusDirRel = focusRel ? toPosixPath(path.posix.dirname(focusRel)) : null;
+    const instructionTokens = tokenizeInstruction(options.instruction);
+
+    // Score and select a small subset for reuse.
+    const scored = data.catalog.components
+        .map((c) => ({ c, s: scoreComponent(c, focusDirRel, instructionTokens) }))
+        .sort((a, b) => b.s - a.s);
+
+    const subset: ComponentExport[] = [];
+    const seen = new Set<string>();
+    for (const item of scored) {
+        if (subset.length >= maxComponents) break;
+        const key = `${item.c.name}|${item.c.file}|${item.c.exportType}`;
+        if (seen.has(key)) continue;
+        // Skip ultra-low relevance if we already have enough
+        if (subset.length > 30 && item.s <= 0) break;
+        subset.push(item.c);
+        seen.add(key);
+    }
+
+    return [
+        'AUTO PROJECT CONTEXT (deterministic):',
+        '',
+        'STACK (json):',
+        summarizeStack(data.stack),
+        '',
+        'COMPONENT CATALOG (subset for reuse):',
+        formatCatalogSubset(data.catalog, subset),
+    ].join('\n');
+}

package/src/context/guards.ts

@@ -0,0 +1,94 @@
+/**
+ * Path Guards
+ *
+ * Centralized helpers to validate and resolve file paths for tools.
+ *
+ * Goals:
+ * - Prevent accidental reads/writes outside the workspace
+ * - Avoid including sensitive files (e.g. .env, private keys)
+ * - Provide consistent absolute-path resolution
+ */
+
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { Config } from '../config/index.js';
+import { isPathAllowed, isSensitiveFile } from './filter.js';
+
+/**
+ * Resolve a path to an absolute path (relative paths are resolved from process.cwd()).
+ */
+export function resolveToAbs(filePath: string): string {
+    return path.isAbsolute(filePath) ? filePath : path.resolve(process.cwd(), filePath);
+}
+
+/**
+ * Validate that a path is safe to read according to server config.
+ * Returns the resolved absolute path.
+ */
+export function assertReadablePath(filePath: string, config: Config): string {
+    const absPath = resolveToAbs(filePath);
+
+    if (!isPathAllowed(absPath, config.allowedPaths)) {
+        throw new Error(`Path is outside allowedPaths: ${filePath}`);
+    }
+
+    if (isSensitiveFile(absPath)) {
+        throw new Error(`Refusing to read sensitive file: ${filePath}`);
+    }
+
+    if (!fs.existsSync(absPath)) {
+        throw new Error(`File not found: ${filePath}`);
+    }
+
+    const stat = fs.statSync(absPath);
+    if (!stat.isFile()) {
+        throw new Error(`Not a file: ${filePath}`);
+    }
+
+    return absPath;
+}
+
+/**
+ * Validate that a path is safe to write according to server config.
+ * Returns the resolved absolute path.
+ */
+export function assertWritablePath(filePath: string, config: Config): string {
+    const absPath = resolveToAbs(filePath);
+
+    if (!isPathAllowed(absPath, config.allowedPaths)) {
+        throw new Error(`Path is outside allowedPaths: ${filePath}`);
+    }
+
+    if (isSensitiveFile(absPath)) {
+        throw new Error(`Refusing to write to sensitive path: ${filePath}`);
+    }
+
+    return absPath;
+}
+
+/**
+ * Validate that a directory path is safe to read according to server config.
+ * Returns the resolved absolute path.
+ */
+export function assertReadableDir(dirPath: string, config: Config): string {
+    const absPath = resolveToAbs(dirPath);
+
+    if (!isPathAllowed(absPath, config.allowedPaths)) {
+        throw new Error(`Path is outside allowedPaths: ${dirPath}`);
+    }
+
+    if (isSensitiveFile(absPath)) {
+        throw new Error(`Refusing to read sensitive directory: ${dirPath}`);
+    }
+
+    if (!fs.existsSync(absPath)) {
+        throw new Error(`Directory not found: ${dirPath}`);
+    }
+
+    const stat = fs.statSync(absPath);
+    if (!stat.isDirectory()) {
+        throw new Error(`Not a directory: ${dirPath}`);
+    }
+
+    return absPath;
+}

package/src/context/repo-hints.ts

@@ -0,0 +1,43 @@
+/**
+ * Repo Hints
+ *
+ * Very small, deterministic context that can be injected into LLM prompts
+ * to significantly improve output quality while avoiding big token burns.
+ *
+ * - Detects framework + styling + common libs
+ * - Does NOT include file contents
+ */
+
+import * as path from 'node:path';
+import { Config } from '../config/index.js';
+import { detectUiStack } from '../stack/detect.js';
+
+export function buildRepoHints(config: Config, rootDir: string = process.cwd()): string {
+    try {
+        const stack = detectUiStack(rootDir);
+
+        const hints = {
+            root: path.basename(stack.root),
+            framework: stack.framework,
+            typescript: stack.language.typescript,
+            styling: stack.styling,
+            uiLibraries: stack.uiLibraries,
+            iconLibraries: stack.iconLibraries,
+            tooling: stack.tooling,
+            conventions: {
+                srcDir: stack.conventions.srcDir,
+                hasAppDir: stack.conventions.hasAppDir,
+                hasPagesDir: stack.conventions.hasPagesDir,
+                tsconfigPaths: stack.conventions.tsconfigPaths,
+            },
+        };
+
+        return `REPO_HINTS (deterministic):\n${JSON.stringify(hints, null, 2)}`;
+    } catch (error) {
+        if (config.debug) {
+            const msg = error instanceof Error ? error.message : 'unknown error';
+            console.error('[repo-hints] Failed to detect stack:', msg);
+        }
+        return '';
+    }
+}

package/src/generation/gemini-client.ts

@@ -0,0 +1,94 @@
+/**
+ * Gemini API Client
+ *
+ * Handles direct communication with Google Gemini API.
+ * Used in local mode with user's own API key.
+ */
+
+import { GoogleGenerativeAI } from '@google/generative-ai';
+import { Config } from '../config/index.js';
+
+export type GeminiUserContent =
+    | string
+    | Array<
+          | { text: string }
+          | { inlineData: { mimeType: string; data: string } }
+      >;
+
+// Cache the client instance
+let genAI: GoogleGenerativeAI | null = null;
+
+export interface GenerateOptions {
+    toolName?: string;
+}
+
+/**
+ * Get or create the Gemini client
+ */
+function getClient(config: Config): GoogleGenerativeAI {
+    if (!config.apiKey) {
+        throw new Error('Gemini API key not configured. Set GEMINI_API_KEY environment variable.');
+    }
+
+    if (!genAI) {
+        genAI = new GoogleGenerativeAI(config.apiKey);
+    }
+
+    return genAI;
+}
+
+/**
+ * Generate content using Gemini
+ */
+export async function generateWithGemini(
+    config: Config,
+    systemPrompt: string,
+    userPrompt: GeminiUserContent,
+    options?: GenerateOptions
+): Promise<string> {
+    // If remote mode, delegate to remote client
+    if (config.mode === 'remote') {
+        const { generateWithRemote } = await import('./remote-client.js');
+        return generateWithRemote(config, systemPrompt, userPrompt, options?.toolName);
+    }
+
+    // If local mode is configured to use an OpenAI-compatible proxy (e.g. LiteLLM)
+    if (config.localProvider === 'litellm') {
+        const { generateWithLiteLLM } = await import('./litellm-client.js');
+        return generateWithLiteLLM(config, systemPrompt, userPrompt, options?.toolName);
+    }
+
+    const client = getClient(config);
+
+    // Use model from config (default: gemini-2.5-flash-lite)
+    const model = client.getGenerativeModel({
+        model: config.model,
+        systemInstruction: systemPrompt,
+    });
+
+    const result = await model.generateContent(userPrompt as any);
+    const response = result.response;
+    const text = response.text();
+
+    if (config.debug) {
+        console.error('[gemini] Tool:', options?.toolName || '(unknown)');
+        console.error('[gemini] Response length:', text.length);
+        console.error('[gemini] Usage:', response.usageMetadata);
+    }
+
+    return text;
+}
+
+/**
+ * Count tokens for a given text (useful for quota tracking)
+ */
+export async function countTokens(config: Config, text: string): Promise<number> {
+    if (config.localProvider === 'litellm') {
+        throw new Error('countTokens is not supported when localProvider=litellm');
+    }
+    const client = getClient(config);
+    const model = client.getGenerativeModel({ model: config.model });
+
+    const result = await model.countTokens(text);
+    return result.totalTokens;
+}

package/src/generation/litellm-client.ts

@@ -0,0 +1,121 @@
+/**
+ * LiteLLM (OpenAI-compatible) Client
+ *
+ * This client allows running the MCP server in local mode while routing
+ * requests through a self-hosted LiteLLM instance.
+ *
+ * Why LiteLLM?
+ * - Key management / key rotation
+ * - Load balancing across multiple upstream API keys
+ * - Unified OpenAI-compatible interface
+ * - Optional caching / retries / budgets
+ */
+
+import { Config } from '../config/index.js';
+import type { GeminiUserContent } from './gemini-client.js';
+
+type ChatContentPart =
+    | { type: 'text'; text: string }
+    | { type: 'image_url'; image_url: { url: string } };
+
+function normalizeBaseUrl(baseUrl: string): string {
+    const trimmed = baseUrl.replace(/\/+$/, '');
+    // Allow users to provide either http://host:port or http://host:port/v1
+    if (trimmed.endsWith('/v1')) return trimmed;
+    return `${trimmed}/v1`;
+}
+
+function inferMimeTypeFromInlineData(mimeType: string): string {
+    // LiteLLM expects a data URL. Ensure mime type is reasonable.
+    if (!mimeType || !mimeType.includes('/')) return 'application/octet-stream';
+    return mimeType;
+}
+
+function toOpenAIUserContent(userContent: GeminiUserContent): string | ChatContentPart[] {
+    if (typeof userContent === 'string') return userContent;
+
+    const parts: ChatContentPart[] = [];
+    for (const part of userContent) {
+        if ('text' in part) {
+            parts.push({ type: 'text', text: part.text });
+            continue;
+        }
+
+        if ('inlineData' in part) {
+            const mime = inferMimeTypeFromInlineData(part.inlineData.mimeType);
+            const url = `data:${mime};base64,${part.inlineData.data}`;
+            parts.push({ type: 'image_url', image_url: { url } });
+            continue;
+        }
+    }
+
+    // If the model only received one text part, prefer string (cheaper payload)
+    if (parts.length === 1 && parts[0].type === 'text') return parts[0].text;
+    return parts;
+}
+
+export async function generateWithLiteLLM(
+    config: Config,
+    systemPrompt: string,
+    userContent: GeminiUserContent,
+    toolName?: string
+): Promise<string> {
+    if (!config.litellmEndpoint) {
+        throw new Error('LiteLLM endpoint not configured. Set LITELLM_ENDPOINT.');
+    }
+
+    const baseUrl = normalizeBaseUrl(config.litellmEndpoint);
+    const url = `${baseUrl}/chat/completions`;
+
+    const model = config.litellmModel || config.model;
+
+    const body = {
+        model,
+        messages: [
+            { role: 'system', content: systemPrompt },
+            { role: 'user', content: toOpenAIUserContent(userContent) },
+        ],
+        // Keep default-ish sampling. Let downstream agents control via prompts.
+        temperature: 0.2,
+    };
+
+    const headers: Record<string, string> = {
+        'Content-Type': 'application/json',
+    };
+
+    if (config.litellmApiKey) {
+        headers.Authorization = `Bearer ${config.litellmApiKey}`;
+    }
+
+    const resp = await fetch(url, {
+        method: 'POST',
+        headers,
+        body: JSON.stringify(body),
+    });
+
+    if (!resp.ok) {
+        const text = await resp.text();
+        throw new Error(`LiteLLM error (${resp.status}): ${text}`);
+    }
+
+    const data = (await resp.json()) as any;
+    const content: unknown = data?.choices?.[0]?.message?.content;
+
+    if (config.debug) {
+        const usage = data?.usage;
+        console.error('[litellm] Tool:', toolName || '(unknown)');
+        if (usage) console.error('[litellm] Usage:', usage);
+        console.error('[litellm] Model:', data?.model || model);
+    }
+
+    if (typeof content === 'string') return content;
+    // Some providers return arrays; stringify safely.
+    if (Array.isArray(content)) {
+        return content
+            .map((p) => (typeof p === 'string' ? p : (p?.text ?? '')))
+            .filter(Boolean)
+            .join('');
+    }
+
+    return '';
+}