@createlex/figma-swiftui-mcp 1.0.9 → 1.2.0

package/README.md

@@ -1,28 +1,42 @@
 # CreateLex Figma to SwiftUI MCP
 
-CreateLex Figma to SwiftUI MCP is a paid local runtime for CreateLex subscribers. It connects your live Figma plugin session to CreateLex and lets you inspect designs, generate SwiftUI, export assets, and write output directly into a local Xcode project.
+A local MCP (Model Context Protocol) runtime that connects your Figma plugin session to Claude Code, Cursor, Windsurf, or any MCP-compatible AI tool — and writes production-ready SwiftUI directly into your Xcode project.
 
-## What it does
+## Generation tiers
 
-- Connects to the Figma to SwiftUI plugin while the plugin window is open
-- Authenticates against your CreateLex account and subscription
-- Starts the local MCP runtime and localhost bridge automatically
-- Generates SwiftUI and asset output for your selected Figma frame
-- Writes generated files into your local Xcode project
+### Tier 1 — AI-native (zero extra API cost)
+Your AI IDE (Claude Code, Cursor, Windsurf, etc.) calls the MCP tools itself:
+
+1. `get_swiftui_generation_prompt` → returns a ready-to-use system prompt + user message
+2. The AI generates SwiftUI using **its own model** (your existing subscription)
+3. `write_generated_swiftui_to_xcode` → writes the file(s) to Xcode
+
+No CreateLex tokens consumed. No extra API keys required.
+
+### Tier 2 — BYOK (Bring Your Own Key)
+Set one of these env vars in your MCP client config and `generate_swiftui` runs locally:
+
+| Env var | Provider | Notes |
+|---|---|---|
+| `ANTHROPIC_API_KEY` | Claude (recommended) | Override model with `ANTHROPIC_MODEL` |
+| `HF_API_TOKEN` | Hugging Face | Default model: `Qwen/Qwen2.5-Coder-32B-Instruct`, override with `HF_MODEL` |
+| `OPENAI_API_KEY` | OpenAI or compatible | Override model with `OPENAI_MODEL` (default `gpt-4o`) |
+| `OPENAI_BASE_URL` | Ollama / LM Studio | Set alongside `OPENAI_API_KEY=ollama` for fully local generation |
+
+### Tier 3 — CreateLex hosted (subscription fallback)
+If no BYOK keys are set, falls back to the CreateLex hosted pattern matcher. Requires an active [CreateLex subscription](https://createlex.com/figma-swiftui).
+
+---
 
 ## Requirements
 
-- An active CreateLex subscription for `figma-swiftui`
 - Node.js 18 or later
 - Figma desktop app with the Figma to SwiftUI plugin open
-- A local Xcode project
+- A local Xcode project (optional for Tier 1 prompt-copy workflow)
 
 ## Install
 
-Run directly with `npx`:
-
 ```bash
-npx @createlex/figma-swiftui-mcp login
 npx @createlex/figma-swiftui-mcp start --project /path/to/MyApp/MyApp
 ```
 
@@ -30,48 +44,121 @@ Or install globally:
 
 ```bash
 npm install -g @createlex/figma-swiftui-mcp
-figma-swiftui-mcp login
 figma-swiftui-mcp start --project /path/to/MyApp/MyApp
 ```
 
-## Login
+## MCP client configuration
+
+Add to your Claude Code / Cursor / Windsurf MCP config:
+
+```json
+{
+  "mcpServers": {
+    "figma-swiftui": {
+      "command": "npx",
+      "args": ["@createlex/figma-swiftui-mcp", "start"],
+      "env": {
+        "FIGMA_SWIFTUI_PROJECT_PATH": "/path/to/MyApp/MyApp",
+        "ANTHROPIC_API_KEY": "sk-ant-..."
+      }
+    }
+  }
+}
+```
 
-`login` opens your browser and signs you in with CreateLex. When login succeeds, the runtime saves your local session to:
+For Hugging Face BYOK:
 
-```text
-~/.createlex/auth.json
+```json
+{
+  "env": {
+    "FIGMA_SWIFTUI_PROJECT_PATH": "/path/to/MyApp/MyApp",
+    "HF_API_TOKEN": "hf_...",
+    "HF_MODEL": "Qwen/Qwen2.5-Coder-32B-Instruct"
+  }
+}
 ```
 
-## Start the runtime
+For fully local generation with Ollama:
+
+```json
+{
+  "env": {
+    "FIGMA_SWIFTUI_PROJECT_PATH": "/path/to/MyApp/MyApp",
+    "OPENAI_API_KEY": "ollama",
+    "OPENAI_BASE_URL": "http://localhost:11434/v1",
+    "OPENAI_MODEL": "llama3"
+  }
+}
+```
 
-Start the runtime with the Xcode source folder that contains your Swift files and `Assets.xcassets`:
+## MCP tools
+
+| Tool | Description |
+|---|---|
+| `get_design_context` | Get the full Figma node tree, colors, typography, and layout for a selection |
+| `get_swiftui_generation_prompt` | Returns a ready-to-use system prompt + user message — feed to your AI model to generate SwiftUI |
+| `generate_swiftui` | Generate SwiftUI via BYOK key or CreateLex hosted (Tier 2/3) |
+| `write_generated_swiftui_to_xcode` | Write a generated Swift file (plus optional DesignTokens.swift and component files) to Xcode |
+| `get_project_path` / `set_project_path` | Read or update the target Xcode source directory |
+| `bridge_status` | Check if the Figma plugin bridge is connected |
+
+### Multi-file output
+
+`write_generated_swiftui_to_xcode` accepts an `additionalFiles` array for AI-generated companion files:
+
+```json
+{
+  "structName": "LoginScreen",
+  "code": "import SwiftUI\n...",
+  "additionalFiles": [
+    { "name": "DesignTokens.swift", "code": "...", "dir": "shared" },
+    { "name": "PrimaryButton.swift", "code": "...", "dir": "components" }
+  ]
+}
+```
 
-```bash
-npx @createlex/figma-swiftui-mcp start --project /path/to/MyApp/MyApp
+Output layout inside your Xcode source folder:
+
+```
+FigmaGenerated/
+  Screens/         ← primary view files
+  Components/      ← reusable component files
+  DesignTokens.swift  ← shared tokens (dir: "shared")
+  Manifest/        ← generation metadata
 ```
 
-If you omit `--project`, you can set the project path later from the plugin UI or your MCP client.
+## AI-native workflow (Tier 1 example)
 
-## Before you use it
+In Claude Code or any MCP-connected AI:
 
-1. Log in with CreateLex
-2. Make sure your subscription is active
-3. Open the Figma to SwiftUI plugin in Figma and keep it open
-4. Start the local runtime
-5. Use your MCP client or the plugin UI to generate and sync output
+```
+1. Select a frame in Figma
+2. Ask: "Generate SwiftUI for my selected Figma frame"
+3. Claude calls get_swiftui_generation_prompt → generates code → calls write_generated_swiftui_to_xcode
+4. File appears in Xcode immediately
+```
 
-## Subscription and access
+Zero CreateLex tokens consumed.
 
-This package is public to install, but runtime access is gated by CreateLex. If your account is not logged in or does not have an active `figma-swiftui` subscription, the runtime will not start.
+## Plugin UI
 
-## Product page
+The plugin's **Smart Generate** button supports two modes via the dropdown:
+- **Smart AI** — uses your AI IDE or BYOK key for true AI generation
+- **Classic** — uses the hosted pattern matcher (requires subscription)
 
-Manage plans and billing at:
+After generation, the **Copy AI Prompt** button copies a ready-to-use prompt you can paste into Claude.ai, ChatGPT, or any AI chat. Requires the MCP server to be running.
 
-- https://createlex.com/figma-swiftui
+## Login (CreateLex subscription)
 
-## Support
+Only required for Tier 3 hosted generation:
 
-For help, billing, or onboarding:
+```bash
+npx @createlex/figma-swiftui-mcp login
+```
+
+Saves your session to `~/.createlex/auth.json`.
+
+## Support
 
-- https://createlex.com/contact
+- Product: https://createlex.com/figma-swiftui
+- Help & billing: https://createlex.com/contact

package/companion/bridge-server.cjs

@@ -230,6 +230,55 @@ function startBridgeServer(options = {}) {
     });
   });
 
+  // GET /design-context — returns current selection's design context as JSON.
+  // Lets any AI tool (Windsurf, a script, a browser) fetch the live Figma context
+  // via a simple HTTP GET without needing MCP protocol or copy-paste.
+  // Usage: GET http://localhost:7765/design-context?maxDepth=4
+  app.get('/design-context', async (req, res) => {
+    if (!pluginBridgeClient || pluginBridgeClient.readyState !== WebSocket.OPEN) {
+      return res.status(503).json({
+        ok: false,
+        error: 'No Figma plugin is connected to the bridge. Open the plugin in Figma first.',
+        hint: 'npx @createlex/figma-swiftui-mcp start --project ./MyApp',
+      });
+    }
+
+    const maxDepth = Math.min(parseInt(req.query.maxDepth, 10) || 4, 8);
+    const requestId = `http-ctx-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
+
+    const response = await new Promise((resolve) => {
+      const timeout = setTimeout(() => {
+        pendingBridgeRequests.delete(requestId);
+        resolve({ ok: false, error: 'Timed out waiting for design context from plugin' });
+      }, 20000);
+
+      pendingBridgeRequests.set(requestId, {
+        origin: null,
+        action: 'get_design_context',
+        resolveCallback: (msg) => {
+          clearTimeout(timeout);
+          resolve(msg);
+        },
+      });
+
+      sendBridgeMessage(pluginBridgeClient, {
+        type: 'bridge-request',
+        requestId,
+        action: 'get_design_context',
+        params: { maxDepth, includeScreenshot: false },
+        protocolVersion: BRIDGE_PROTOCOL_VERSION,
+        timestamp: new Date().toISOString(),
+      });
+      broadcastBridgeStatus();
+    });
+
+    if (!response.ok) {
+      return res.status(502).json({ ok: false, error: response.error || 'Plugin returned an error' });
+    }
+
+    res.json({ ok: true, ...(response.data || {}) });
+  });
+
   function sendBridgeMessage(ws, payload) {
     if (!ws || ws.readyState !== WebSocket.OPEN) {
       return false;
@@ -497,11 +546,15 @@ function startBridgeServer(options = {}) {
         }
 
         pendingBridgeRequests.delete(message.requestId);
-        sendBridgeMessage(pending.origin, {
-          ...message,
-          protocolVersion: BRIDGE_PROTOCOL_VERSION,
-          timestamp: new Date().toISOString(),
-        });
+        if (typeof pending.resolveCallback === 'function') {
+          pending.resolveCallback(message);
+        } else {
+          sendBridgeMessage(pending.origin, {
+            ...message,
+            protocolVersion: BRIDGE_PROTOCOL_VERSION,
+            timestamp: new Date().toISOString(),
+          });
+        }
         broadcastBridgeStatus();
         return;
       }

package/companion/local-llm-generator.cjs

@@ -0,0 +1,432 @@
+'use strict';
+
+/**
+ * local-llm-generator.cjs
+ *
+ * BYOK (Bring Your Own Key) SwiftUI generation.
+ * Uses ANTHROPIC_API_KEY, OPENAI_API_KEY, or an OpenAI-compatible
+ * base URL (e.g. Ollama, LM Studio) to generate SwiftUI without
+ * touching the CreateLex hosted backend.
+ *
+ * Required env vars (at least one):
+ *   ANTHROPIC_API_KEY  — use Claude (recommended)
+ *   OPENAI_API_KEY     — use OpenAI or compatible API
+ *
+ * Optional:
+ *   OPENAI_MODEL       — model name (default: gpt-4o)
+ *   OPENAI_BASE_URL    — custom base URL for Ollama / LM Studio etc.
+ */
+
+// ---------------------------------------------------------------------------
+// Prompt constants
+// ---------------------------------------------------------------------------
+
+const SWIFTUI_SYSTEM_PROMPT = `You are an expert SwiftUI engineer generating production-ready iOS code from Figma design context JSON.
+
+RULES:
+1. Output ONLY valid Swift code inside <file name="StructName.swift"> XML tags — one tag per file.
+2. Always import SwiftUI. Never import UIKit or use UIViewRepresentable.
+3. Map Figma layoutMode: HORIZONTAL→HStack, VERTICAL→VStack, NONE→ZStack/overlay.
+4. Use the struct name supplied in OUTPUT_STRUCT_NAME for the primary view.
+5. Responsive sizing: follow every _responsiveHint annotation in the node tree.
+6. For colors: use Color extension token names when a styleName is present; otherwise Color(red:green:blue:).
+7. Generate @State vars for every interactive element (TextField, Toggle, Button, Picker).
+8. Add .accessibilityLabel() and .accessibilityHint() derived from node name and text content.
+9. End every file with a #Preview { StructName() } block.
+10. Emit best-effort code for anything complex — never emit TODO comments or placeholder stubs.
+11. If reusableComponents are present, output each as a separate <file name="ComponentName.swift"> tag.
+
+RESPONSIVE LAYOUT RULES:
+- Root frame with FILL sizing → .frame(maxWidth: .infinity)
+- Font sizes → @ScaledMetric var: e.g. @ScaledMetric var titleSize: CGFloat = 34
+- Horizontal scrolling children → ScrollView(.horizontal, showsIndicators: false)
+- Vertical root scroll behavior → wrap body in ScrollView
+- ViewThatFits for HStack→VStack fallback on narrow devices when content may wrap
+- VStack(spacing:) / HStack(spacing:) from Figma itemSpacing — not fixed .padding() for inter-item spacing
+- .ignoresSafeArea() only for background color/image layers, never for foreground content
+- Hardcoded values are acceptable only for: cornerRadius, icon sizes ≤24pt, stroke widths
+
+DESIGN TOKENS:
+If designTokens.colors or designTokens.fonts are non-empty, output a <file name="DesignTokens.swift"> containing:
+  extension Color { static let tokenName = Color(red: ..., green: ..., blue: ...) }
+  extension Font { static let tokenName = .system(size: ..., weight: ...) }
+Then use these token names everywhere in the main view code.
+
+REUSABLE COMPONENTS:
+For each item in reusableComponents:
+- Output a separate <file name="ComponentName.swift">
+- Promote repeated values (text, colors, image names) into View parameters
+- In the parent view, replace inline rendering with ComponentName(param: value)`;
+
+// ---------------------------------------------------------------------------
+// Context helpers
+// ---------------------------------------------------------------------------
+
+function cleanText(value) {
+  return typeof value === 'string' ? value.replace(/\s+/g, ' ').trim() : '';
+}
+
+function sanitizeName(value) {
+  const words = cleanText(value)
+    .replace(/[^a-zA-Z0-9]+/g, ' ')
+    .split(' ')
+    .filter(Boolean);
+  if (words.length === 0) return 'GeneratedView';
+  return words.map((w) => w[0].toUpperCase() + w.slice(1)).join('');
+}
+
+function getRootNode(metadata) {
+  if (!metadata || typeof metadata !== 'object') return null;
+  if (Array.isArray(metadata.nodes)) {
+    return metadata.nodes.length === 1 ? metadata.nodes[0] : null;
+  }
+  return metadata.type ? metadata : null;
+}
+
+function flattenNodes(node, limit = 200) {
+  const results = [];
+  const visit = (current) => {
+    if (!current || typeof current !== 'object' || results.length >= limit) return;
+    results.push(current);
+    if (Array.isArray(current.children)) {
+      current.children.forEach(visit);
+    }
+  };
+  visit(node);
+  return results;
+}
+
+function annotateResponsiveHints(node, rootWidth) {
+  if (!node || !rootWidth) return node;
+  const width = node?.geometry?.width;
+  if (typeof width === 'number' && width > 0) {
+    const frac = width / rootWidth;
+    if (frac > 0.5 && frac < 1.0) {
+      node._responsiveHint = `width is ~${Math.round(frac * 100)}% of root canvas — use .frame(maxWidth: .infinity) with horizontal padding`;
+    }
+  }
+  if (Array.isArray(node.children)) {
+    node.children.forEach((child) => annotateResponsiveHints(child, rootWidth));
+  }
+  return node;
+}
+
+function pruneNodeTree(root, maxNodes) {
+  const all = flattenNodes(root, maxNodes);
+  const ids = new Set(all.map((n) => n.id));
+
+  function prune(node) {
+    if (!node) return node;
+    const pruned = { ...node };
+    if (Array.isArray(pruned.children)) {
+      pruned.children = pruned.children
+        .filter((c) => ids.has(c?.id))
+        .map(prune);
+    }
+    return pruned;
+  }
+
+  return prune(root);
+}
+
+function extractDesignTokens(rootNode) {
+  const colors = new Map();
+  const fonts = new Map();
+  const radiusCounts = new Map();
+
+  function toSwiftTokenName(styleName) {
+    return styleName
+      .replace(/[^a-zA-Z0-9/]+/g, ' ')
+      .split(/[\s/]+/)
+      .filter(Boolean)
+      .map((w, i) => i === 0 ? w[0].toLowerCase() + w.slice(1) : w[0].toUpperCase() + w.slice(1))
+      .join('');
+  }
+
+  flattenNodes(rootNode, 500).forEach((node) => {
+    const style = node.style;
+    if (!style) return;
+
+    if (style.styleName && Array.isArray(style.fills)) {
+      const fill = style.fills.find((f) => f && f.visible !== false && f.type === 'SOLID' && f.color);
+      if (fill) colors.set(toSwiftTokenName(style.styleName), fill.color);
+    }
+
+    if (node.type === 'TEXT' && style.styleName && node.text?.fontSize) {
+      fonts.set(toSwiftTokenName(style.styleName), {
+        size: node.text.fontSize,
+        weight: node.text.fontName?.style,
+      });
+    }
+
+    if (typeof style.cornerRadius === 'number' && style.cornerRadius > 0) {
+      radiusCounts.set(style.cornerRadius, (radiusCounts.get(style.cornerRadius) ?? 0) + 1);
+    }
+  });
+
+  return {
+    colors: [...colors.entries()].map(([name, color]) => ({ name, color })),
+    fonts: [...fonts.entries()].map(([name, font]) => ({ name, ...font })),
+    commonRadii: [...radiusCounts.entries()].filter(([, count]) => count >= 3).map(([r]) => r),
+  };
+}
+
+function buildPromptContext(context) {
+  const root = getRootNode(context?.metadata);
+  if (!root) return null;
+
+  const rootWidth = root?.geometry?.width ?? 390;
+  const prunedRoot = pruneNodeTree(root, 200);
+  annotateResponsiveHints(prunedRoot, rootWidth);
+
+  const designTokens = extractDesignTokens(root);
+  const structName = sanitizeName(root.name || 'GeneratedView');
+
+  return {
+    structName,
+    canvasWidth: rootWidth,
+    canvasHeight: root?.geometry?.height ?? 844,
+    nodeTree: prunedRoot,
+    designTokens,
+    reusableComponents: (context?.reusableComponents?.candidates ?? []).slice(0, 10),
+    assetRequests: (context?.assetExportPlan?.candidates ?? []).slice(0, 10),
+    generationHints: context?.generationHints ?? null,
+  };
+}
+
+function buildUserMessage(context, generationMode) {
+  const promptCtx = buildPromptContext(context);
+  if (!promptCtx) {
+    throw new Error('Could not extract root node from design context');
+  }
+
+  return `Generate SwiftUI code for this Figma design.
+
+OUTPUT_STRUCT_NAME: ${promptCtx.structName}
+CANVAS_WIDTH: ${promptCtx.canvasWidth}
+GENERATION_MODE: ${generationMode}
+
+DESIGN CONTEXT:
+${JSON.stringify(promptCtx, null, 2)}
+
+Output all Swift files using <file name="StructName.swift"> tags.`;
+}
+
+// ---------------------------------------------------------------------------
+// Response parser
+// ---------------------------------------------------------------------------
+
+function parseClaudeResponse(text) {
+  const fileRegex = /<file name="([^"]+\.swift)">([\s\S]*?)<\/file>/g;
+  const files = [];
+  let match;
+  while ((match = fileRegex.exec(text)) !== null) {
+    files.push({ name: match[1], code: match[2].trim() });
+  }
+
+  if (files.length === 0) {
+    // Fallback: treat entire response as primary file code
+    return { code: text.trim(), designTokensCode: null, componentFiles: [] };
+  }
+
+  const tokensFile = files.find((f) => f.name === 'DesignTokens.swift');
+  const primaryName = buildPromptContext !== null
+    ? files.find((f) => f.name !== 'DesignTokens.swift' && !f.name.startsWith('Component') && !f.name.endsWith('Row.swift') && !f.name.endsWith('Card.swift') && !f.name.endsWith('Cell.swift'))
+    : null;
+  const primary = primaryName ?? files.find((f) => f !== tokensFile);
+  const componentFiles = files.filter((f) => f !== primary && f !== tokensFile);
+
+  return {
+    code: primary?.code ?? '',
+    designTokensCode: tokensFile?.code ?? null,
+    componentFiles,
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Anthropic generation
+// ---------------------------------------------------------------------------
+
+async function generateWithAnthropic(context, generationMode, apiKey) {
+  let Anthropic;
+  try {
+    ({ Anthropic } = require('@anthropic-ai/sdk'));
+  } catch {
+    throw new Error('ANTHROPIC_API_KEY is set but @anthropic-ai/sdk is not installed. Run: npm install @anthropic-ai/sdk');
+  }
+
+  const client = new Anthropic({ apiKey });
+  const userMessage = buildUserMessage(context, generationMode);
+
+  const response = await client.messages.create({
+    model: process.env.ANTHROPIC_MODEL || 'claude-sonnet-4-6',
+    max_tokens: 8192,
+    system: SWIFTUI_SYSTEM_PROMPT,
+    messages: [{ role: 'user', content: userMessage }],
+  });
+
+  const text = response.content
+    .filter((b) => b.type === 'text')
+    .map((b) => b.text)
+    .join('');
+
+  return parseClaudeResponse(text);
+}
+
+// ---------------------------------------------------------------------------
+// OpenAI-compatible generation (OpenAI, Ollama, LM Studio, etc.)
+// ---------------------------------------------------------------------------
+
+async function generateWithOpenAI(context, generationMode, apiKey) {
+  let OpenAI;
+  try {
+    ({ OpenAI } = require('openai'));
+  } catch {
+    throw new Error('OPENAI_API_KEY is set but the openai package is not installed. Run: npm install openai');
+  }
+
+  const client = new OpenAI({
+    apiKey,
+    baseURL: process.env.OPENAI_BASE_URL || undefined,
+  });
+
+  const model = process.env.OPENAI_MODEL || 'gpt-4o';
+  const userMessage = buildUserMessage(context, generationMode);
+
+  const response = await client.chat.completions.create({
+    model,
+    max_tokens: 8192,
+    messages: [
+      { role: 'system', content: SWIFTUI_SYSTEM_PROMPT },
+      { role: 'user', content: userMessage },
+    ],
+  });
+
+  const text = response.choices[0]?.message?.content ?? '';
+  return parseClaudeResponse(text);
+}
+
+// ---------------------------------------------------------------------------
+// Hugging Face Inference API
+//
+// Uses HF's OpenAI-compatible endpoint: https://api-inference.huggingface.co/v1
+//
+// Best models for SwiftUI generation (set HF_MODEL to override):
+//   Qwen/Qwen2.5-Coder-32B-Instruct  — default, best open-source code model
+//   meta-llama/Llama-3.3-70B-Instruct — strong reasoning + code
+//   deepseek-ai/DeepSeek-Coder-V2-Instruct — excellent complex code
+//   Qwen/Qwen2.5-Coder-7B-Instruct   — faster/cheaper for simpler screens
+//
+// Env vars:
+//   HF_API_TOKEN  — required
+//   HF_MODEL      — optional, defaults to Qwen2.5-Coder-32B-Instruct
+// ---------------------------------------------------------------------------
+
+const HF_INFERENCE_BASE_URL = 'https://api-inference.huggingface.co/v1';
+const HF_DEFAULT_MODEL = 'Qwen/Qwen2.5-Coder-32B-Instruct';
+
+async function generateWithHuggingFace(context, generationMode, apiKey) {
+  let OpenAI;
+  try {
+    ({ OpenAI } = require('openai'));
+  } catch {
+    throw new Error('HF_API_TOKEN is set but the openai package is not installed. Run: npm install openai');
+  }
+
+  const model = process.env.HF_MODEL || HF_DEFAULT_MODEL;
+  const client = new OpenAI({
+    apiKey,
+    baseURL: HF_INFERENCE_BASE_URL,
+  });
+
+  const userMessage = buildUserMessage(context, generationMode);
+
+  const response = await client.chat.completions.create({
+    model,
+    max_tokens: 8192,
+    messages: [
+      { role: 'system', content: SWIFTUI_SYSTEM_PROMPT },
+      { role: 'user', content: userMessage },
+    ],
+  });
+
+  const text = response.choices[0]?.message?.content ?? '';
+  return parseClaudeResponse(text);
+}
+
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+
+/**
+ * Returns the SwiftUI system prompt and a formatted user message for AI-native
+ * generation. AI tools (Claude Code, Cursor, Windsurf, etc.) call this to get a
+ * ready-to-use prompt, then generate code with their own model and call
+ * write_generated_swiftui_to_xcode — burning zero CreateLex tokens.
+ */
+function buildGenerationPrompt(context) {
+  const promptCtx = buildPromptContext(context);
+  if (!promptCtx) return null;
+
+  return {
+    systemPrompt: SWIFTUI_SYSTEM_PROMPT,
+    userMessage: buildUserMessage(context, 'editable'),
+    outputStructName: promptCtx.structName,
+    assetRequests: promptCtx.assetRequests,
+    canvasWidth: promptCtx.canvasWidth,
+  };
+}
+
+/**
+ * Generate SwiftUI using the user's own API key (BYOK).
+ *
+ * Priority order:
+ *   1. ANTHROPIC_API_KEY  → Claude (best quality, recommended)
+ *   2. HF_API_TOKEN       → Hugging Face (Qwen2.5-Coder-32B by default — best open-source)
+ *   3. OPENAI_API_KEY     → OpenAI or any OpenAI-compatible endpoint (Ollama, LM Studio)
+ *
+ * Returns: { handled, provider, code, designTokensCode, componentFiles, diagnostics }
+ */
+async function generateWithLocalKey(context, generationMode = 'editable') {
+  const anthropicKey = process.env.ANTHROPIC_API_KEY;
+  const hfKey = process.env.HF_API_TOKEN;
+  const openaiKey = process.env.OPENAI_API_KEY;
+
+  if (!anthropicKey && !hfKey && !openaiKey) {
+    return null; // No BYOK configured — caller should try next tier
+  }
+
+  let parsed;
+  let provider;
+
+  if (anthropicKey) {
+    parsed = await generateWithAnthropic(context, generationMode, anthropicKey);
+    provider = `local-anthropic:${process.env.ANTHROPIC_MODEL || 'claude-sonnet-4-6'}`;
+  } else if (hfKey) {
+    const model = process.env.HF_MODEL || HF_DEFAULT_MODEL;
+    parsed = await generateWithHuggingFace(context, generationMode, hfKey);
+    provider = `huggingface:${model}`;
+  } else {
+    parsed = await generateWithOpenAI(context, generationMode, openaiKey);
+    const baseUrl = process.env.OPENAI_BASE_URL;
+    const model = process.env.OPENAI_MODEL || 'gpt-4o';
+    provider = baseUrl ? `local-openai-compatible:${model}` : `local-openai:${model}`;
+  }
+
+  return {
+    handled: true,
+    provider,
+    screenType: 'llm-generated',
+    code: parsed.code,
+    designTokensCode: parsed.designTokensCode,
+    componentFiles: parsed.componentFiles,
+    assetRequests: [],
+    diagnostics: [],
+  };
+}
+
+module.exports = {
+  generateWithLocalKey,
+  buildGenerationPrompt,
+  SWIFTUI_SYSTEM_PROMPT,
+};

package/companion/mcp-server.mjs

@@ -25,6 +25,10 @@ const {
   postAuthorizedApi,
   validateRuntimeSession,
 } = require('./createlex-auth.cjs');
+const {
+  generateWithLocalKey,
+  buildGenerationPrompt,
+} = require('./local-llm-generator.cjs');
 
 const BRIDGE_HTTP_URL = process.env.FIGMA_SWIFTUI_BRIDGE_HTTP_URL || 'http://localhost:7765';
 const BRIDGE_WS_URL = process.env.FIGMA_SWIFTUI_BRIDGE_WS_URL || 'ws://localhost:7765/bridge';
@@ -110,6 +114,35 @@ async function tryHostedSemanticGeneration({ nodeIds, generationMode, includeOve
     includeScreenshot: false,
   });
 
+  // Tier 2: BYOK — use the user's own API key (Anthropic, OpenAI, or Ollama)
+  // Bypasses CreateLex backend entirely; no subscription token consumed.
+  if (process.env.ANTHROPIC_API_KEY || process.env.HF_API_TOKEN || process.env.OPENAI_API_KEY) {
+    try {
+      const byokResult = await generateWithLocalKey(context, generationMode);
+      if (byokResult?.handled) {
+        const metadata = context?.metadata;
+        const selection = Array.isArray(metadata?.nodes)
+          ? { ids: metadata.nodes.map((n) => n.id), names: metadata.nodes.map((n) => n.name) }
+          : { ids: [metadata?.id], names: [metadata?.name] };
+
+        if (analyze) {
+          return {
+            selection: metadata,
+            generated: { ...byokResult, imageCount: 0, imageNames: [] },
+            assetExportPlan: context?.assetExportPlan ?? null,
+            reusableComponents: context?.reusableComponents ?? null,
+            generationHints: context?.generationHints ?? null,
+            manualRefinementHints: context?.generationHints?.manualRefinementHints ?? [],
+            hosted: false,
+          };
+        }
+        return { ...byokResult, selection, imageCount: 0, imageNames: [], hosted: false };
+      }
+    } catch (byokError) {
+      console.error('[figma-swiftui-mcp] BYOK generation failed, falling back to hosted:', byokError.message);
+    }
+  }
+
   const metadata = context?.metadata;
   const isSingleRootNode = !!metadata && !Array.isArray(metadata?.nodes) ? true : Array.isArray(metadata?.nodes) && metadata.nodes.length === 1;
   if (!isSingleRootNode) {
@@ -387,7 +420,7 @@ server.registerTool('get_metadata', {
 });
 
 server.registerTool('get_design_context', {
-  description: 'Return node metadata, asset export candidates, and generation hints for the current selection or an explicit node.',
+  description: 'Return node metadata, asset export candidates, and generation hints for the current selection or an explicit node. AI-native workflow: call this tool, then generate SwiftUI yourself using your own model (burns zero CreateLex tokens), then call write_generated_swiftui_to_xcode to save the result. Alternatively call get_swiftui_generation_prompt to get a ready-to-use system prompt + user message.',
   inputSchema: {
     nodeIds: z.array(z.string()).optional().describe('Optional list of Figma node ids. If omitted, uses the current selection'),
     nodeId: z.string().optional().describe('Optional single Figma node id'),
@@ -404,6 +437,37 @@ server.registerTool('get_design_context', {
   return jsonResult(data);
 });
 
+server.registerTool('get_swiftui_generation_prompt', {
+  description: 'Return a ready-to-use SwiftUI system prompt and user message for AI-native generation. Call this, then feed the returned systemPrompt + userMessage to your own AI model (Claude Code, Cursor, Windsurf, ChatGPT, etc.) to generate SwiftUI — burning zero CreateLex tokens. After generation, parse <file name="X.swift"> tags in the response and call write_generated_swiftui_to_xcode with the code and any additionalFiles.',
+  inputSchema: {
+    nodeIds: z.array(z.string()).optional().describe('Optional list of Figma node ids. If omitted, uses the current selection'),
+    nodeId: z.string().optional().describe('Optional single Figma node id'),
+    maxDepth: z.number().int().min(0).max(8).default(4).describe('Maximum child depth to include'),
+  },
+}, async ({ nodeIds, nodeId, maxDepth }) => {
+  const context = await callBridge('get_design_context', {
+    nodeIds,
+    nodeId,
+    maxDepth,
+    includeScreenshot: false,
+  });
+
+  const prompt = buildGenerationPrompt(context);
+  if (!prompt) {
+    throw new Error('Could not extract root node from design context. Ensure a single frame or component is selected.');
+  }
+
+  return jsonResult({
+    ...prompt,
+    instructions: [
+      '1. Use systemPrompt as the system message and userMessage as the user message.',
+      '2. Ask your AI to generate SwiftUI code.',
+      '3. Parse <file name="X.swift"> tags from the response — each tag is one Swift file.',
+      '4. Call write_generated_swiftui_to_xcode with: code (primary view), additionalFiles for DesignTokens.swift (dir:"shared") and components (dir:"components").',
+    ],
+  });
+});
+
 server.registerTool('get_screenshot', {
   description: 'Export a PNG screenshot for a single target node or the single current selection.',
   inputSchema: {
@@ -642,9 +706,9 @@ server.registerTool('analyze_generation', {
 });
 
 server.registerTool('write_generated_swiftui_to_xcode', {
-  description: 'Write generated SwiftUI code and optional exported images directly into the configured Xcode project.',
+  description: 'Write generated SwiftUI code and optional exported images directly into the configured Xcode project. Supports writing multiple files: use additionalFiles for DesignTokens.swift (dir: "shared"), reusable components (dir: "components"), or extra screen files (dir: "screens"). AI tools generating code with their own model should call this after generating SwiftUI from get_design_context or get_swiftui_generation_prompt.',
   inputSchema: {
-    code: z.string().describe('SwiftUI source code to write'),
+    code: z.string().describe('SwiftUI source code for the primary view'),
     structName: z.string().optional().describe('Optional Swift struct name; if omitted it will be inferred from the code'),
     projectPath: z.string().optional().describe('Optional Xcode source folder override'),
     images: z.array(z.object({
@@ -652,8 +716,13 @@ server.registerTool('write_generated_swiftui_to_xcode', {
       base64: z.string(),
     })).default([]).describe('Optional exported image payloads'),
     selectionNames: z.array(z.string()).default([]).describe('Optional original Figma selection names for struct inference'),
+    additionalFiles: z.array(z.object({
+      name: z.string().describe('Swift filename, e.g. DesignTokens.swift'),
+      code: z.string().describe('Full Swift source code for this file'),
+      dir: z.enum(['shared', 'components', 'screens']).optional().describe('shared=project root, components=Components/ subdir, screens=same dir as primary (default)'),
+    })).optional().describe('Additional Swift files to write: DesignTokens.swift, reusable components, etc.'),
   },
-}, async ({ code, structName, projectPath, images, selectionNames }) => {
+}, async ({ code, structName, projectPath, images, selectionNames, additionalFiles }) => {
   const targetDir = resolveTargetProjectPath(projectPath);
   const effectiveStructName = inferStructName({ structName, code, selectionNames });
   const result = writeSwiftUIScreen({
@@ -661,6 +730,7 @@ server.registerTool('write_generated_swiftui_to_xcode', {
     code,
     structName: effectiveStructName,
     images,
+    additionalFiles,
   });
 
   if (!result.ok) {

package/companion/xcode-writer.cjs

@@ -73,11 +73,12 @@ function loadProjectPath({ explicitPath } = {}) {
   return getSavedProjectPath();
 }
 
-function writeSwiftUIScreen({ targetDir, code, structName, images = [] }) {
+function writeSwiftUIScreen({ targetDir, code, structName, images = [], additionalFiles = [] }) {
   const resolvedTarget = resolveWritableProjectPath(targetDir);
   const generatedDirs = ensureGeneratedLayout(resolvedTarget);
   const results = {
     swiftFile: null,
+    additionalSwiftFiles: [],
     images: [],
     manifestFiles: [],
     generatedRoot: generatedDirs.rootDir,
@@ -94,6 +95,34 @@ function writeSwiftUIScreen({ targetDir, code, structName, images = [] }) {
     }
   }
 
+  // Write additional files (DesignTokens.swift, component files, etc.)
+  if (Array.isArray(additionalFiles) && additionalFiles.length > 0) {
+    const componentsDir = path.join(generatedDirs.rootDir, 'Components');
+    for (const extra of additionalFiles) {
+      if (!extra.name || !extra.code) continue;
+      let destDir;
+      if (extra.dir === 'shared') {
+        destDir = generatedDirs.rootDir;
+      } else if (extra.dir === 'components') {
+        try {
+          fs.mkdirSync(componentsDir, { recursive: true });
+        } catch {
+          // ignore
+        }
+        destDir = componentsDir;
+      } else {
+        destDir = generatedDirs.screensDir;
+      }
+      const filePath = path.join(destDir, extra.name);
+      try {
+        fs.writeFileSync(filePath, extra.code, 'utf8');
+        results.additionalSwiftFiles.push(filePath);
+      } catch (error) {
+        results.errors.push(`Failed to write ${extra.name}: ${error.message}`);
+      }
+    }
+  }
+
   if (Array.isArray(images) && images.length > 0) {
     const assetResult = writeAssetCatalogEntries({
       targetDir: resolvedTarget,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@createlex/figma-swiftui-mcp",
-  "version": "1.0.9",
+  "version": "1.2.0",
   "description": "CreateLex MCP runtime for Figma-to-SwiftUI generation and Xcode export",
   "bin": {
     "figma-swiftui-mcp": "bin/figma-swiftui-mcp.js"
@@ -9,6 +9,7 @@
     "bin/",
     "companion/bridge-server.cjs",
     "companion/createlex-auth.cjs",
+    "companion/local-llm-generator.cjs",
     "companion/login.mjs",
     "companion/mcp-server.mjs",
     "companion/package.json",
@@ -39,6 +40,10 @@
     "ws": "^8.20.0",
     "zod": "^4.3.6"
   },
+  "optionalDependencies": {
+    "@anthropic-ai/sdk": "^0.52.0",
+    "openai": "^4.100.0"
+  },
   "devDependencies": {
     "@figma/plugin-typings": "*",
     "typescript": "^5.4.0"