@createlex/figgen 1.4.2

package/companion/mcp-server.mjs

@@ -0,0 +1,1365 @@
+#!/usr/bin/env node
+
+import { createRequire } from 'node:module';
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import WebSocket from 'ws';
+import * as z from 'zod/v4';
+
+const require = createRequire(import.meta.url);
+const {
+  GENERATED_LAYOUT_VERSION,
+  getConfigPath,
+  getSavedProjectPath,
+  inferStructName,
+  loadProjectPath,
+  resolveWritableProjectPath,
+  setSavedProjectPath,
+  writeAssetCatalogEntries,
+  writeMultiScreenProject,
+  writeSwiftUIScreen,
+} = require('./xcode-writer.cjs');
+const { startBridgeServer } = require('./bridge-server.cjs');
+const {
+  AUTH_FILE,
+  authorizeRuntimeStartup,
+  postAuthorizedApi,
+  validateRuntimeSession,
+} = require('./createlex-auth.cjs');
+const {
+  generateWithLocalKey,
+  buildGenerationPrompt,
+  parseClaudeResponse,
+  buildPromptContext,
+} = 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';
+const REQUEST_TIMEOUT_MS = Number(process.env.FIGMA_SWIFTUI_BRIDGE_TIMEOUT_MS || 30000);
+const AUTH_REVALIDATION_INTERVAL_MS = Number(process.env.FIGMA_SWIFTUI_AUTH_REVALIDATION_MS || (10 * 60 * 1000));
+const RESPONSE_SIZE_CAP = Number(process.env.FIGMA_SWIFTUI_RESPONSE_SIZE_CAP || 102400); // 100 KB default
+const MAX_DIAGNOSTICS = 20;
+
+let bridgeSocket = null;
+let connectPromise = null;
+let reconnectTimer = null;
+let authValidationTimer = null;
+let bridgeRuntimeHandle = null;
+let lastBridgeStatus = {
+  protocolVersion: 1,
+  pluginConnected: false,
+  connectedAgents: 0,
+  pendingRequests: 0,
+  supportedActions: [],
+};
+let runtimeAuthState = {
+  authorized: false,
+  bypass: false,
+  apiBaseUrl: null,
+  validatedAt: null,
+  userId: null,
+  email: null,
+  tokenSource: null,
+  expiresAt: null,
+  startupEndpoint: null,
+};
+
+const pendingRequests = new Map();
+
+function readProjectPathArg(argv) {
+  const argIdx = argv.indexOf('--project');
+  if (argIdx !== -1 && argv[argIdx + 1]) {
+    return argv[argIdx + 1];
+  }
+  return null;
+}
+
+function jsonResult(data) {
+  return {
+    content: [
+      {
+        type: 'text',
+        text: JSON.stringify(data, null, 2),
+      },
+    ],
+  };
+}
+
+function getPublicAuthState() {
+  return {
+    authorized: runtimeAuthState.authorized,
+    bypass: runtimeAuthState.bypass,
+    apiBaseUrl: runtimeAuthState.apiBaseUrl,
+    validatedAt: runtimeAuthState.validatedAt,
+    userId: runtimeAuthState.userId,
+    email: runtimeAuthState.email,
+    tokenSource: runtimeAuthState.tokenSource,
+    expiresAt: runtimeAuthState.expiresAt,
+    startupEndpoint: runtimeAuthState.startupEndpoint,
+    authFile: AUTH_FILE,
+  };
+}
+
+function ensureRuntimeAuthorized() {
+  if (!runtimeAuthState.authorized) {
+    throw new Error('CreateLex authentication required. Run "npx @createlex/figma-swiftui-mcp login" and ensure your subscription is active before starting figma-swiftui MCP.');
+  }
+}
+
+async function tryHostedSemanticGeneration({ nodeIds, generationMode, includeOverflow, analyze }) {
+  if (generationMode !== 'editable') {
+    return null;
+  }
+
+  const context = await callBridge('get_design_context', {
+    nodeIds,
+    maxDepth: 4,
+    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) {
+    return null;
+  }
+
+  const endpoint = analyze ? '/mcp/figma-swiftui/analyze' : '/mcp/figma-swiftui/generate';
+  const { response, data } = await postAuthorizedApi(runtimeAuthState, endpoint, {
+    context,
+    generationMode,
+    includeOverflow,
+  });
+
+  if (!response.ok) {
+    throw new Error(data?.error || `Hosted figma-swiftui request failed (${response.status})`);
+  }
+
+  if (!data?.handled) {
+    return null;
+  }
+
+  const selection = Array.isArray(metadata?.nodes)
+    ? {
+        ids: metadata.nodes.map((node) => node.id),
+        names: metadata.nodes.map((node) => node.name),
+      }
+    : {
+        ids: [metadata.id],
+        names: [metadata.name],
+      };
+
+  if (!analyze) {
+    return {
+      code: data.code,
+      selection,
+      imageCount: 0,
+      imageNames: [],
+      diagnostics: data.diagnostics || [],
+      provider: data.provider || 'createlex-hosted',
+      screenType: data.screenType || null,
+      assetRequests: data.assetRequests || [],
+      hosted: true,
+    };
+  }
+
+  return {
+    selection: metadata,
+    generated: {
+      code: data.code,
+      imageCount: 0,
+      imageNames: [],
+      diagnostics: data.diagnostics || [],
+      provider: data.provider || 'createlex-hosted',
+      screenType: data.screenType || null,
+      assetRequests: data.assetRequests || [],
+      hosted: true,
+    },
+    assetExportPlan: data.contextSummary?.assetExportPlan || context?.assetExportPlan || null,
+    reusableComponents: data.contextSummary?.reusableComponents || context?.reusableComponents || null,
+    generationHints: data.contextSummary?.generationHints || context?.generationHints || null,
+    manualRefinementHints: context?.generationHints?.manualRefinementHints || [],
+    hosted: true,
+  };
+}
+
+function resolveTargetProjectPath(projectPath) {
+  const resolved = loadProjectPath({ explicitPath: projectPath });
+  if (!resolved) {
+    throw new Error('No Xcode project path is configured. Use set_project_path first or pass projectPath explicitly.');
+  }
+  return resolved;
+}
+
+function scheduleReconnect() {
+  if (reconnectTimer) {
+    return;
+  }
+
+  reconnectTimer = setTimeout(() => {
+    reconnectTimer = null;
+    connectBridge().catch((error) => {
+      console.error('[figma-swiftui-mcp] Bridge reconnect failed:', error.message);
+    });
+  }, 1500);
+}
+
+function rejectPendingRequests(message) {
+  for (const [requestId, pending] of pendingRequests.entries()) {
+    clearTimeout(pending.timer);
+    pending.reject(new Error(message));
+    pendingRequests.delete(requestId);
+  }
+}
+
+function handleBridgeMessage(rawMessage) {
+  let message;
+  try {
+    message = JSON.parse(rawMessage.toString());
+  } catch (error) {
+    console.error('[figma-swiftui-mcp] Failed to parse bridge message:', error);
+    return;
+  }
+
+  if (message.type === 'hello-ack' || message.type === 'bridge-status') {
+    lastBridgeStatus = {
+      ...lastBridgeStatus,
+      ...message,
+    };
+    return;
+  }
+
+  if (message.type === 'bridge-response') {
+    const pending = pendingRequests.get(message.requestId);
+    if (!pending) {
+      return;
+    }
+
+    clearTimeout(pending.timer);
+    pendingRequests.delete(message.requestId);
+
+    if (message.ok) {
+      pending.resolve(message.data);
+    } else {
+      pending.reject(new Error(message.error || `Bridge action ${message.action} failed`));
+    }
+    return;
+  }
+
+  if (message.type === 'bridge-event') {
+    // Log bridge events concisely — skip full JSON payloads for noisy events
+    const summary = message.data && message.event === 'selectionchange'
+      ? `${message.data.selection?.count ?? 0} node(s) selected`
+      : message.data && message.event === 'currentpagechange'
+        ? `page "${message.data.currentPage?.name || 'unknown'}"`
+        : '';
+    if (summary) {
+      console.error(`[figma-swiftui-mcp] ${message.event}: ${summary}`);
+    }
+  }
+}
+
+async function connectBridge() {
+  if (bridgeSocket && bridgeSocket.readyState === WebSocket.OPEN) {
+    return bridgeSocket;
+  }
+
+  if (connectPromise) {
+    return connectPromise;
+  }
+
+  connectPromise = new Promise((resolve, reject) => {
+    const socket = new WebSocket(BRIDGE_WS_URL);
+    let settled = false;
+
+    socket.on('open', () => {
+      bridgeSocket = socket;
+      socket.send(JSON.stringify({
+        type: 'hello',
+        role: 'agent',
+        protocolVersion: 1,
+      }));
+
+      settled = true;
+      resolve(socket);
+    });
+
+    socket.on('message', (message) => {
+      handleBridgeMessage(message);
+    });
+
+    socket.on('close', () => {
+      if (bridgeSocket === socket) {
+        bridgeSocket = null;
+      }
+      rejectPendingRequests('Bridge socket closed');
+      scheduleReconnect();
+    });
+
+    socket.on('error', (error) => {
+      if (!settled) {
+        reject(error);
+      }
+    });
+  }).finally(() => {
+    connectPromise = null;
+  });
+
+  return connectPromise;
+}
+
+async function fetchBridgeStatus() {
+  try {
+    const response = await fetch(`${BRIDGE_HTTP_URL}/bridge/info`);
+    if (!response.ok) {
+      throw new Error(`HTTP ${response.status}`);
+    }
+    const data = await response.json();
+    lastBridgeStatus = {
+      ...lastBridgeStatus,
+      ...data,
+    };
+    return data;
+  } catch (error) {
+    return {
+      ...lastBridgeStatus,
+      ok: false,
+      error: error instanceof Error ? error.message : 'Unable to reach bridge info endpoint',
+    };
+  }
+}
+
+async function callBridge(action, params = {}) {
+  ensureRuntimeAuthorized();
+  await connectBridge();
+  const status = await fetchBridgeStatus();
+
+  if (!status.pluginConnected) {
+    throw new Error('No active Figma plugin session is connected to the bridge');
+  }
+
+  const requestId = `mcp-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
+
+  return new Promise((resolve, reject) => {
+    const timer = setTimeout(() => {
+      pendingRequests.delete(requestId);
+      reject(new Error(`Timed out waiting for bridge action "${action}"`));
+    }, REQUEST_TIMEOUT_MS);
+
+    pendingRequests.set(requestId, {
+      resolve,
+      reject,
+      timer,
+    });
+
+    bridgeSocket.send(JSON.stringify({
+      type: 'bridge-request',
+      requestId,
+      action,
+      params,
+    }));
+  });
+}
+
+const server = new McpServer({
+  name: 'figma-swiftui-bridge',
+  version: '1.0.0',
+});
+
+server.registerTool('bridge_status', {
+  description: 'Check the local Figma SwiftUI bridge status, including whether a live plugin session is connected.',
+}, async () => {
+  const data = await fetchBridgeStatus();
+  return jsonResult({
+    ...data,
+    auth: getPublicAuthState(),
+  });
+});
+
+server.registerTool('auth_status', {
+  description: 'Check whether the local figma-swiftui MCP runtime is authorized for a paid CreateLex subscription.',
+}, async () => {
+  return jsonResult(getPublicAuthState());
+});
+
+server.registerTool('get_metadata', {
+  description: 'Inspect selection, page, or node metadata in a format similar to Figma Dev MCP.',
+  inputSchema: {
+    scope: z.enum(['selection', 'page', 'node']).default('selection').describe('Metadata scope to inspect'),
+    nodeId: z.string().optional().describe('Required when scope=node'),
+    maxDepth: z.number().int().min(0).max(8).default(3).describe('Maximum child depth to include'),
+  },
+}, async ({ scope, nodeId, maxDepth }) => {
+  const data = await callBridge('get_metadata', { scope, nodeId, maxDepth });
+  return jsonResult(data);
+});
+
+server.registerTool('get_design_context', {
+  description: 'Return node metadata, asset export candidates, and generation hints for the current Figma selection. PREFERRED WORKFLOW: call figma_to_swiftui instead — it handles LLM generation, Image("name") asset refs, PNG export, DesignTokens, and reusable components in one shot. Only call get_design_context if you need to inspect the raw node tree before generating.',
+  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(3).describe('Maximum child depth to include'),
+    includeScreenshot: z.boolean().default(false).describe('Include a PNG screenshot when exactly one node is targeted'),
+  },
+}, async ({ nodeIds, nodeId, maxDepth, includeScreenshot }) => {
+  const data = await callBridge('get_design_context', {
+    nodeIds,
+    nodeId,
+    maxDepth,
+    includeScreenshot,
+  });
+  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. PREFERRED: use figma_to_swiftui instead — it pre-writes assets and handles LLM generation automatically. Only use get_swiftui_generation_prompt when you need the raw prompt. If you do: (a) use .font(.system(size:weight:)) — never hardcode custom font names like Inter or Roboto, (b) reference every assetExportPlan entry as Image("name") not Rectangle().',
+  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: {
+    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'),
+  },
+}, async ({ nodeIds, nodeId }) => {
+  const data = await callBridge('get_screenshot', { nodeIds, nodeId });
+  return jsonResult(data);
+});
+
+server.registerTool('export_svg', {
+  description: 'Export an exact SVG for a single vector-friendly node or the single current selection.',
+  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'),
+  },
+}, async ({ nodeIds, nodeId }) => {
+  const data = await callBridge('export_svg', { nodeIds, nodeId });
+  return jsonResult(data);
+});
+
+server.registerTool('write_svg_to_xcode', {
+  description: 'Export an exact SVG from Figma and write it directly into Assets.xcassets.',
+  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'),
+    assetName: z.string().optional().describe('Optional asset name override'),
+    projectPath: z.string().optional().describe('Optional Xcode source folder override'),
+  },
+}, async ({ nodeIds, nodeId, assetName, projectPath }) => {
+  const targetDir = resolveTargetProjectPath(projectPath);
+  const svgExport = await callBridge('export_svg', { nodeIds, nodeId });
+  const effectiveAssetName = assetName || svgExport.suggestedAssetName || 'VectorAsset';
+  const result = writeAssetCatalogEntries({
+    targetDir,
+    assets: [
+      {
+        name: effectiveAssetName,
+        format: 'svg',
+        svg: svgExport.svg,
+      },
+    ],
+  });
+
+  if (!result.ok) {
+    throw new Error(result.errors.join(' | ') || 'Failed to write SVG asset to Xcode');
+  }
+
+  return jsonResult({
+    ok: true,
+    projectPath: targetDir,
+    assetName: effectiveAssetName,
+    xcassetsDir: result.xcassetsDir,
+    files: result.files,
+    sourceNode: {
+      nodeId: svgExport.nodeId,
+      nodeName: svgExport.nodeName,
+      nodeType: svgExport.nodeType,
+    },
+  });
+});
+
+server.registerTool('get_project_path', {
+  description: 'Read the saved Xcode project source folder used for local SwiftUI writes.',
+}, async () => {
+  return jsonResult({
+    projectPath: getSavedProjectPath(),
+    configPath: getConfigPath(),
+    layoutVersion: GENERATED_LAYOUT_VERSION,
+  });
+});
+
+server.registerTool('set_project_path', {
+  description: 'Persist the Xcode project source folder used for local SwiftUI writes.',
+  inputSchema: {
+    projectPath: z.string().describe('Path to the Xcode source folder containing Swift files and Assets.xcassets'),
+  },
+}, async ({ projectPath }) => {
+  const resolved = resolveWritableProjectPath(projectPath);
+  const saved = setSavedProjectPath(resolved);
+  return jsonResult({
+    ok: true,
+    projectPath: saved,
+    configPath: getConfigPath(),
+  });
+});
+
+server.registerTool('get_document_summary', {
+  description: 'Read high-level Figma document, page, selection, and viewport metadata from the connected plugin session.',
+}, async () => {
+  const data = await callBridge('get_document_summary');
+  return jsonResult(data);
+});
+
+server.registerTool('get_viewport_context', {
+  description: 'Read the active Figma viewport center, zoom, and current page metadata.',
+}, async () => {
+  const data = await callBridge('get_viewport_context');
+  return jsonResult(data);
+});
+
+server.registerTool('get_selection_snapshot', {
+  description: 'Read a rich structural snapshot of the current Figma selection.',
+  inputSchema: {
+    maxDepth: z.number().int().min(0).max(8).default(3).describe('Maximum child depth to include in the snapshot'),
+  },
+}, async ({ maxDepth }) => {
+  const data = await callBridge('get_selection_snapshot', { maxDepth });
+  return jsonResult(data);
+});
+
+server.registerTool('get_page_snapshot', {
+  description: 'Read the current Figma page and its child hierarchy.',
+  inputSchema: {
+    maxDepth: z.number().int().min(0).max(6).default(2).describe('Maximum child depth to include for the page snapshot'),
+  },
+}, async ({ maxDepth }) => {
+  const data = await callBridge('get_page_snapshot', { maxDepth });
+  return jsonResult(data);
+});
+
+server.registerTool('get_node_snapshot', {
+  description: 'Read a rich structural snapshot for a specific Figma node id.',
+  inputSchema: {
+    nodeId: z.string().describe('Figma node id, for example "123:456"'),
+    maxDepth: z.number().int().min(0).max(8).default(3).describe('Maximum child depth to include for the node snapshot'),
+  },
+}, async ({ nodeId, maxDepth }) => {
+  const data = await callBridge('get_node_snapshot', { nodeId, maxDepth });
+  return jsonResult(data);
+});
+
+server.registerTool('find_nodes', {
+  description: 'Search the current Figma page for nodes by name substring and optional node type.',
+  inputSchema: {
+    query: z.string().default('').describe('Case-insensitive name substring to search for'),
+    type: z.string().optional().describe('Optional Figma node type to filter, for example FRAME or TEXT'),
+    limit: z.number().int().min(1).max(200).default(25).describe('Maximum number of matching nodes to return'),
+    maxDepth: z.number().int().min(0).max(2).default(0).describe('Maximum child depth to include for each match'),
+  },
+}, async ({ query, type, limit, maxDepth }) => {
+  const data = await callBridge('find_nodes', { query, type, limit, maxDepth });
+  return jsonResult(data);
+});
+
+server.registerTool('get_asset_export_plan', {
+  description: 'List vector/icon/image export candidates for the current selection or explicit node ids.',
+  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'),
+  },
+}, async ({ nodeIds, nodeId }) => {
+  const data = await callBridge('get_asset_export_plan', { nodeIds, nodeId });
+  return jsonResult(data);
+});
+
+server.registerTool('extract_reusable_components', {
+  description: 'Identify repeated Figma components and repeated sibling structures that should become reusable SwiftUI components.',
+  inputSchema: {
+    nodeIds: z.array(z.string()).optional().describe('Optional list of Figma node ids. If omitted, uses the current selection or current page when scope=page'),
+    nodeId: z.string().optional().describe('Optional single Figma node id'),
+    scope: z.enum(['selection', 'page']).default('selection').describe('Analyze the current selection or scan the full current page'),
+  },
+}, async ({ nodeIds, nodeId, scope }) => {
+  const data = await callBridge('extract_reusable_components', { nodeIds, nodeId, scope });
+  return jsonResult(data);
+});
+
+server.registerTool('dump_tree', {
+  description: 'Return a readable text tree for the current selection or explicit node ids.',
+  inputSchema: {
+    nodeIds: z.array(z.string()).optional().describe('Optional list of Figma node ids. If omitted, uses the current selection'),
+  },
+}, async ({ nodeIds }) => {
+  const data = await callBridge('dump_tree', { nodeIds });
+  return jsonResult(data);
+});
+
+server.registerTool('generate_swiftui', {
+  description: 'Run the same SwiftUI export path used by the plugin UI, optionally including image payloads.',
+  inputSchema: {
+    nodeIds: z.array(z.string()).optional().describe('Optional list of Figma node ids. If omitted, uses the current selection'),
+    includeOverflow: z.boolean().default(false).describe('Ignore Figma clipping when generating layout'),
+    generationMode: z.enum(['editable', 'fidelity']).default('editable').describe('Editable keeps more native SwiftUI structure; fidelity rasterizes more complex layouts'),
+    includeImages: z.boolean().default(false).describe('Include base64 image payloads in the tool result'),
+  },
+}, async ({ nodeIds, includeOverflow, generationMode, includeImages }) => {
+  if (!includeImages) {
+    const hosted = await tryHostedSemanticGeneration({
+      nodeIds,
+      generationMode,
+      includeOverflow,
+      analyze: false,
+    });
+    if (hosted) {
+      return jsonResult(hosted);
+    }
+  }
+
+  const data = await callBridge('generate_swiftui', {
+    nodeIds,
+    includeOverflow,
+    generationMode,
+    includeImages,
+  });
+  return jsonResult(data);
+});
+
+server.registerTool('analyze_generation', {
+  description: 'Return the generated SwiftUI plus per-node diagnostics and rasterization reasons for the current selection or explicit node ids.',
+  inputSchema: {
+    nodeIds: z.array(z.string()).optional().describe('Optional list of Figma node ids. If omitted, uses the current selection'),
+    includeOverflow: z.boolean().default(false).describe('Ignore Figma clipping when generating layout'),
+    generationMode: z.enum(['editable', 'fidelity']).default('editable').describe('Editable keeps more native SwiftUI structure; fidelity rasterizes more complex layouts'),
+    maxDepth: z.number().int().min(0).max(8).default(3).describe('Maximum child depth to include in the diagnostic node snapshot'),
+  },
+}, async ({ nodeIds, includeOverflow, generationMode, maxDepth }) => {
+  const hosted = await tryHostedSemanticGeneration({
+    nodeIds,
+    generationMode,
+    includeOverflow,
+    analyze: true,
+  });
+  if (hosted) {
+    return jsonResult(hosted);
+  }
+
+  const data = await callBridge('analyze_generation', {
+    nodeIds,
+    includeOverflow,
+    generationMode,
+    maxDepth,
+  });
+  return jsonResult(data);
+});
+
+server.registerTool('write_generated_swiftui_to_xcode', {
+  description: 'Write generated SwiftUI code into the configured Xcode project. Images are automatically exported from the current Figma selection and written to Assets.xcassets — you do not need to provide them manually. Supports 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 the /design-context URL.',
+  inputSchema: {
+    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({
+      name: z.string(),
+      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, additionalFiles }) => {
+  const targetDir = resolveTargetProjectPath(projectPath);
+  const effectiveStructName = inferStructName({ structName, code, selectionNames });
+
+  // Auto-fetch images from the current Figma selection when none were provided.
+  // This ensures Assets.xcassets is always populated even when the AI supplied
+  // its own SwiftUI code (e.g. from get_design_context / the /design-context URL).
+  let effectiveImages = Array.isArray(images) && images.length > 0 ? images : [];
+  if (effectiveImages.length === 0) {
+    try {
+      const generated = await callBridge('generate_swiftui', {
+        includeImages: true,
+        generationMode: 'editable',
+        includeOverflow: false,
+      });
+      if (Array.isArray(generated.images) && generated.images.length > 0) {
+        effectiveImages = generated.images;
+      }
+    } catch {
+      // Non-fatal: bridge may not be connected or selection may have no images.
+    }
+  }
+
+  const result = writeSwiftUIScreen({
+    targetDir,
+    code,
+    structName: effectiveStructName,
+    images: effectiveImages,
+    additionalFiles,
+  });
+
+  if (!result.ok) {
+    throw new Error(result.results.errors.join(' | ') || 'Failed to write generated SwiftUI to Xcode');
+  }
+
+  return jsonResult({
+    ...stripImageData(result),
+    structName: effectiveStructName,
+    imagesWritten: effectiveImages.length,
+  });
+});
+
+server.registerTool('write_selection_to_xcode', {
+  description: 'Generate SwiftUI from the connected Figma selection and write it into the configured Xcode project. THIS IS THE CORRECT TOOL TO CALL — it exports real PNG assets to Assets.xcassets and generates Image("name") references automatically. Always use the default generationMode="editable" — individual assets include blendModeSwiftUI values so blend modes are applied correctly on each Image(). Only use generationMode="fidelity" when the ENTIRE frame is a single photographic image or illustration with no text, no interactive elements, and no distinct layers (e.g. a full-bleed photo background).',
+  inputSchema: {
+    nodeIds: z.array(z.string()).optional().describe('Optional list of Figma node ids. If omitted, uses the current selection'),
+    includeOverflow: z.boolean().default(false).describe('Ignore Figma clipping when generating layout'),
+    generationMode: z.enum(['editable', 'fidelity']).default('editable').describe('Default: editable — generates individual SwiftUI elements with correct .blendMode() on each Image(). Use fidelity ONLY when the whole frame is a single photo/illustration with no text or interactive elements.'),
+    projectPath: z.string().optional().describe('Optional Xcode source folder override'),
+  },
+}, async ({ nodeIds, includeOverflow, generationMode, projectPath }) => {
+  const targetDir = resolveTargetProjectPath(projectPath);
+
+  // Try LLM generation (Tier 2/3) to get better code than the template generator
+  let llmCode = null;
+  let llmAdditionalFiles = [];
+  let analysisHints = null;
+  try {
+    const semanticResult = await tryHostedSemanticGeneration({
+      nodeIds,
+      generationMode,
+      includeOverflow,
+      analyze: false,
+    });
+    if (semanticResult?.code) {
+      const parsed = parseClaudeResponse(semanticResult.code);
+      llmCode = parsed.code || semanticResult.code;
+      if (parsed.designTokensCode) {
+        llmAdditionalFiles.push({ name: 'DesignTokens.swift', code: parsed.designTokensCode, dir: 'shared' });
+      }
+      for (const comp of (parsed.componentFiles || [])) {
+        llmAdditionalFiles.push({ name: comp.name, code: comp.code, dir: 'components' });
+      }
+    }
+    // Also try to get analysis hints
+    if (!semanticResult) {
+      const analysis = await tryHostedSemanticGeneration({
+        nodeIds,
+        generationMode,
+        includeOverflow,
+        analyze: true,
+      });
+      if (analysis) {
+        analysisHints = {
+          generationHints: analysis.generationHints,
+          manualRefinementHints: analysis.manualRefinementHints,
+          reusableComponents: analysis.reusableComponents,
+          assetExportPlan: analysis.assetExportPlan,
+        };
+      }
+    }
+  } catch (err) {
+    // Non-fatal — continue with plugin generation
+    console.error('[figma-swiftui-mcp] Semantic generation failed (non-fatal):', err?.message ?? err);
+  }
+
+  const generated = await callBridge('generate_swiftui', {
+    nodeIds,
+    includeOverflow,
+    generationMode,
+    includeImages: true,
+  });
+
+  // Prefer LLM-generated code over template-generated code
+  const finalCode = llmCode || generated.code;
+
+  const effectiveStructName = inferStructName({
+    code: finalCode,
+    selectionNames: generated.selection?.names ?? [],
+  });
+
+  const result = writeSwiftUIScreen({
+    targetDir,
+    code: finalCode,
+    structName: effectiveStructName,
+    images: Array.isArray(generated.images) ? generated.images : [],
+    additionalFiles: llmAdditionalFiles,
+  });
+
+  if (!result.ok) {
+    throw new Error(result.results.errors.join(' | ') || 'Failed to write generated selection to Xcode');
+  }
+
+  // Build refinement instructions from diagnostics and hints
+  const rasterNodes = (generated.diagnostics ?? []).filter(
+    (d) => d.rasterized || d.reason?.toLowerCase().includes('raster')
+  );
+  const refinementInstructions = buildRefinementInstructions({
+    diagnostics: generated.diagnostics ?? [],
+    rasterNodes,
+    analysisHints,
+    structName: effectiveStructName,
+    filePath: result.results?.swiftFile ?? null,
+  });
+
+  const imageNames = (generated.images ?? []).map((img) => img.name);
+
+  return jsonResult(buildCompactResponse({
+    result,
+    structName: effectiveStructName,
+    selection: generated.selection ?? null,
+    diagnostics: generated.diagnostics ?? [],
+    refinementInstructions,
+    analysisHints,
+    _critical: [
+      `✅ SwiftUI written to ${result.results?.swiftFile ?? 'Xcode'}. Images written to Assets.xcassets.`,
+      imageNames.length > 0
+        ? `🖼  ${imageNames.length} PNG asset(s) written: ${imageNames.join(', ')}. The generated code already references them with Image("name") calls.`
+        : null,
+      '🚫 DO NOT rewrite or overwrite the generated Swift file. DO NOT replace Image("name") calls with Rectangle(), shapes, or colors.',
+      '✏️  You may ONLY: add GeometryReader for responsiveness, wire @State interactions, extract reusable sub-views. Nothing else.',
+    ].filter(Boolean),
+  }));
+});
+
+// ---------------------------------------------------------------------------
+// figma_to_swiftui — true one-shot Figma-to-SwiftUI generation
+// ---------------------------------------------------------------------------
+
+server.registerTool('figma_to_swiftui', {
+  description:
+    'One-shot Figma-to-SwiftUI: generates production-ready SwiftUI code from the current Figma selection (or all page frames) and writes it to the Xcode project — including PNG assets, DesignTokens.swift, and reusable components. ' +
+    'With BYOK keys (ANTHROPIC_API_KEY / OPENAI_API_KEY) or a CreateLex subscription this is a TRUE single-call operation. ' +
+    'Without those, it pre-writes assets and returns a structured prompt so the calling AI can generate code and finish with one more write_generated_swiftui_to_xcode call. ' +
+    'Use scope="page" to batch-generate every top-level frame on the current page.',
+  inputSchema: {
+    nodeIds: z.array(z.string()).optional().describe('Optional list of Figma node ids. If omitted, uses the current selection'),
+    scope: z.enum(['selection', 'page']).default('selection').describe('selection = current selection; page = every top-level frame on the active page'),
+    generationMode: z.enum(['editable', 'fidelity']).default('editable').describe('editable (default) keeps native SwiftUI elements; fidelity rasterizes the whole frame'),
+    includeOverflow: z.boolean().default(false).describe('Ignore Figma clipping when generating layout'),
+    projectPath: z.string().optional().describe('Optional Xcode source folder override'),
+  },
+}, async ({ nodeIds, scope, generationMode, includeOverflow, projectPath }) => {
+  const targetDir = resolveTargetProjectPath(projectPath);
+
+  // -------------------------------------------------------------------------
+  // 1. Resolve target node ids
+  // -------------------------------------------------------------------------
+  let effectiveNodeIds = nodeIds;
+
+  if (scope === 'page') {
+    const pageSnapshot = await callBridge('get_page_snapshot', { maxDepth: 1 });
+    const topFrames = (pageSnapshot?.children ?? []).filter(
+      (c) => c.type === 'FRAME' || c.type === 'COMPONENT' || c.type === 'COMPONENT_SET'
+    );
+    if (topFrames.length === 0) {
+      throw new Error('No top-level frames found on the current page');
+    }
+    effectiveNodeIds = topFrames.map((f) => f.id);
+  }
+
+  // -------------------------------------------------------------------------
+  // 2. Get design context (node tree, tokens, asset plan, components)
+  // -------------------------------------------------------------------------
+  const context = await callBridge('get_design_context', {
+    nodeIds: effectiveNodeIds,
+    maxDepth: 4,
+    includeScreenshot: false,
+  });
+
+  // -------------------------------------------------------------------------
+  // 3. Get images from plugin generator
+  // -------------------------------------------------------------------------
+  const generated = await callBridge('generate_swiftui', {
+    nodeIds: effectiveNodeIds,
+    includeOverflow,
+    generationMode,
+    includeImages: true,
+  });
+
+  const images = Array.isArray(generated.images) ? generated.images : [];
+  const imageNames = images.map((img) => img.name);
+
+  // -------------------------------------------------------------------------
+  // 4. Attempt LLM generation (Tier 2 BYOK → Tier 3 Hosted)
+  // -------------------------------------------------------------------------
+  let llmResult = null;
+
+  // Tier 2: BYOK
+  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) {
+        llmResult = byokResult;
+      }
+    } catch (err) {
+      console.error('[figma-swiftui-mcp] BYOK generation failed:', err?.message ?? err);
+    }
+  }
+
+  // Tier 3: Hosted (only for editable single-root)
+  if (!llmResult && generationMode === 'editable') {
+    try {
+      const metadata = context?.metadata;
+      const isSingleRoot = !!metadata && (!Array.isArray(metadata?.nodes) || metadata.nodes.length === 1);
+      if (isSingleRoot && runtimeAuthState.authorized) {
+        const { response, data } = await postAuthorizedApi(runtimeAuthState, '/mcp/figma-swiftui/generate', {
+          context,
+          generationMode,
+          includeOverflow,
+        });
+        if (response.ok && data?.handled) {
+          llmResult = {
+            handled: true,
+            provider: data.provider || 'createlex-hosted',
+            code: data.code,
+            designTokensCode: null,
+            componentFiles: [],
+            diagnostics: data.diagnostics || [],
+          };
+        }
+      }
+    } catch (err) {
+      console.error('[figma-swiftui-mcp] Hosted generation failed (non-fatal):', err?.message ?? err);
+    }
+  }
+
+  // -------------------------------------------------------------------------
+  // 5a. Tier 2/3 succeeded — parse, write everything, return success
+  // -------------------------------------------------------------------------
+  if (llmResult) {
+    const parsed = parseClaudeResponse(llmResult.code || '');
+    const finalCode = parsed.code || llmResult.code || generated.code;
+    const effectiveStructName = inferStructName({
+      code: finalCode,
+      selectionNames: generated.selection?.names ?? [],
+    });
+
+    // Build additional files
+    const additionalFiles = [];
+    if (parsed.designTokensCode || llmResult.designTokensCode) {
+      additionalFiles.push({
+        name: 'DesignTokens.swift',
+        code: parsed.designTokensCode || llmResult.designTokensCode,
+        dir: 'shared',
+      });
+    }
+    for (const comp of (parsed.componentFiles || llmResult.componentFiles || [])) {
+      additionalFiles.push({ name: comp.name, code: comp.code, dir: 'components' });
+    }
+
+    const result = writeSwiftUIScreen({
+      targetDir,
+      code: finalCode,
+      structName: effectiveStructName,
+      images,
+      additionalFiles,
+    });
+
+    if (!result.ok) {
+      throw new Error(result.results.errors.join(' | ') || 'Failed to write generated SwiftUI to Xcode');
+    }
+
+    return jsonResult({
+      tier: llmResult.provider?.startsWith('local-') || llmResult.provider?.startsWith('huggingface:') ? 'byok' : 'hosted',
+      provider: llmResult.provider,
+      oneShot: true,
+      structName: effectiveStructName,
+      swiftFile: result.results?.swiftFile ?? null,
+      additionalFiles: result.results?.additionalSwiftFiles ?? [],
+      imagesWritten: imageNames.length,
+      imageNames,
+      generatedRoot: result.generatedRoot,
+      projectPath: result.projectPath,
+      _critical: [
+        `✅ SwiftUI generated via ${llmResult.provider} and written to ${result.results?.swiftFile ?? 'Xcode'}.`,
+        imageNames.length > 0
+          ? `🖼  ${imageNames.length} PNG asset(s) written: ${imageNames.join(', ')}.`
+          : null,
+        additionalFiles.length > 0
+          ? `📦 ${additionalFiles.length} additional file(s): ${additionalFiles.map((f) => f.name).join(', ')}.`
+          : null,
+        '🚫 DO NOT rewrite the generated Swift file. DO NOT replace Image("name") calls with shapes or colors.',
+        '✏️  You may ONLY: add GeometryReader for responsiveness, wire @State interactions, extract reusable sub-views.',
+      ].filter(Boolean),
+    });
+  }
+
+  // -------------------------------------------------------------------------
+  // 5b. Tier 1 — AI-native: pre-write assets, return structured prompt
+  // -------------------------------------------------------------------------
+
+  // Pre-write images to Assets.xcassets so Claude only needs to generate code
+  let assetsPreWritten = false;
+  if (images.length > 0) {
+    const assetResult = writeAssetCatalogEntries({
+      targetDir,
+      assets: images.map((img) => ({
+        name: img.name,
+        format: img.format || 'png',
+        base64: img.base64,
+        svg: img.svg,
+      })),
+    });
+    assetsPreWritten = assetResult.ok || assetResult.files.length > 0;
+  }
+
+  // Build the generation prompt
+  const prompt = buildGenerationPrompt(context);
+  const effectiveStructName = inferStructName({
+    code: generated.code,
+    selectionNames: generated.selection?.names ?? [],
+  });
+
+  // Build asset manifest for the prompt so the AI knows exactly which Image() names are valid
+  const assetManifest = (context?.assetExportPlan?.candidates ?? []).map((c) => ({
+    name: c.assetName || c.name,
+    blendMode: c.blendModeSwiftUI || null,
+    type: c.suggestedType || c.type || 'image',
+  }));
+
+  return jsonResult({
+    tier: 'ai-native',
+    oneShot: false,
+    assetsPreWritten,
+    imagesWritten: assetsPreWritten ? imageNames.length : 0,
+    imageNames,
+    structName: effectiveStructName,
+    projectPath: targetDir,
+    generationPrompt: prompt
+      ? {
+          systemPrompt: prompt.systemPrompt,
+          userMessage: prompt.userMessage + (assetManifest.length > 0
+            ? `\n\nASSET MANIFEST (already written to Assets.xcassets — use these exact names):\n${JSON.stringify(assetManifest, null, 2)}`
+            : ''),
+          outputStructName: prompt.outputStructName || effectiveStructName,
+        }
+      : null,
+    designContext: prompt ? null : context,
+    assetExportPlan: context?.assetExportPlan ?? null,
+    reusableComponents: context?.reusableComponents ?? null,
+    _critical: [
+      assetsPreWritten
+        ? `🖼  ${imageNames.length} PNG asset(s) pre-written to Assets.xcassets: ${imageNames.join(', ')}.`
+        : null,
+      'Generate SwiftUI code using the generationPrompt above (systemPrompt + userMessage).',
+      'Output code using <file name="StructName.swift"> XML tags.',
+      'Then call write_generated_swiftui_to_xcode with the generated code and images:[] (assets are already on disk).',
+      '⚠️  Use .font(.system(size:weight:)) ONLY — never custom font names.',
+      '⚠️  Reference every asset as Image("name") — never Rectangle() or Color() placeholders.',
+    ].filter(Boolean),
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Response-size mitigation helpers
+// ---------------------------------------------------------------------------
+
+/**
+ * Remove base64 / svg binary data from any image results.
+ * Files are already on disk — the model only needs names and paths.
+ */
+function stripImageData(obj) {
+  if (!obj || typeof obj !== 'object') return obj;
+
+  // Deep-clone to avoid mutating the original
+  const clone = JSON.parse(JSON.stringify(obj));
+
+  const walk = (node) => {
+    if (Array.isArray(node)) {
+      node.forEach(walk);
+      return;
+    }
+    if (node && typeof node === 'object') {
+      delete node.base64;
+      delete node.svg;
+      delete node.data;
+      for (const value of Object.values(node)) {
+        walk(value);
+      }
+    }
+  };
+
+  walk(clone);
+  return clone;
+}
+
+/**
+ * Cap the diagnostics array, prioritising rasterized nodes first.
+ */
+function capDiagnostics(diagnostics) {
+  if (!Array.isArray(diagnostics) || diagnostics.length <= MAX_DIAGNOSTICS) {
+    return diagnostics;
+  }
+
+  // Sort: rasterized nodes first (most useful for refinement)
+  const sorted = [...diagnostics].sort((a, b) => {
+    const aRaster = a.rasterized || a.reason?.toLowerCase().includes('raster') ? 1 : 0;
+    const bRaster = b.rasterized || b.reason?.toLowerCase().includes('raster') ? 1 : 0;
+    return bRaster - aRaster;
+  });
+
+  const kept = sorted.slice(0, MAX_DIAGNOSTICS);
+  kept.push({
+    _truncated: true,
+    totalCount: diagnostics.length,
+    shownCount: MAX_DIAGNOSTICS,
+    message: `${diagnostics.length - MAX_DIAGNOSTICS} additional diagnostic(s) omitted to reduce response size.`,
+  });
+  return kept;
+}
+
+/**
+ * Build a compact MCP response for write_selection_to_xcode.
+ *
+ * Strategy:
+ *  1. Strip all binary (base64/svg) data from image results.
+ *  2. Cap diagnostics to MAX_DIAGNOSTICS most relevant entries.
+ *  3. Estimate serialised size; if still over RESPONSE_SIZE_CAP,
+ *     compress analysis hints to summary-only.
+ */
+function buildCompactResponse({ result, structName, selection, diagnostics, refinementInstructions, analysisHints }) {
+  const compact = {
+    ...stripImageData(result),
+    structName,
+    selection,
+    diagnostics: capDiagnostics(diagnostics),
+    refinementInstructions,
+    ...(analysisHints ? { analysisHints } : {}),
+  };
+
+  // First size check
+  let serialised = JSON.stringify(compact);
+  if (serialised.length <= RESPONSE_SIZE_CAP) {
+    return compact;
+  }
+
+  // Compress: remove verbose analysis hints, keep only summary-level data
+  if (compact.analysisHints) {
+    const { generationHints, manualRefinementHints, ...rest } = compact.analysisHints;
+    compact.analysisHints = {
+      ...rest,
+      _compressed: true,
+      generationHintCount: generationHints?.interactiveElements?.length ?? 0,
+      manualRefinementHintCount: manualRefinementHints?.length ?? 0,
+    };
+  }
+
+  // Second size check — drop the full Swift code echo if still too large
+  serialised = JSON.stringify(compact);
+  if (serialised.length > RESPONSE_SIZE_CAP && compact.results?.swiftFile) {
+    // The code is already on disk at swiftFile; no need to echo it
+    if (compact.results) {
+      compact.results = { ...compact.results };
+      delete compact.results.code;
+    }
+    compact._responseCapped = true;
+    compact._responseNote = `Response was compressed to stay under ${Math.round(RESPONSE_SIZE_CAP / 1024)}KB. All files were written successfully to disk.`;
+  }
+
+  return compact;
+}
+
+function buildRefinementInstructions({ diagnostics, rasterNodes, analysisHints, structName, filePath }) {
+  const instructions = [];
+
+  // Adaptive layout
+  instructions.push(
+    `Make ${structName} adaptive: replace any fixed .frame(width:height:) on the root body with GeometryReader or .frame(maxWidth: .infinity, maxHeight: .infinity) so the screen fills any device.`
+  );
+
+  // Raster replacements
+  if (rasterNodes.length > 0) {
+    const rasterNames = rasterNodes
+      .map((d) => d.assetName || d.nodeName || d.name)
+      .filter(Boolean)
+      .slice(0, 8)
+      .join(', ');
+    instructions.push(
+      `IMPORTANT: ${rasterNodes.length} element(s) were rasterized and written to Assets.xcassets as PNG files${rasterNames ? ` (${rasterNames})` : ''}. ` +
+      `The generated code already references them with Image("name") calls — DO NOT remove or replace these Image() calls. ` +
+      `Only replace Image() calls if the asset name clearly identifies a native UI control (button, toggle, tab bar, text field). ` +
+      `Photos, illustrations, 3D renders, icons, and decorative graphics MUST stay as Image("name") — do not attempt to reconstruct them with SwiftUI shapes or colors.`
+    );
+  }
+
+  // Hosted analysis hints
+  if (analysisHints?.manualRefinementHints?.length) {
+    for (const hint of analysisHints.manualRefinementHints) {
+      const text = typeof hint === 'string' ? hint : hint.description || hint.message || hint.text || hint.title || null;
+      if (text) {
+        instructions.push(text);
+      }
+    }
+  }
+
+  if (analysisHints?.generationHints?.interactiveElements?.length) {
+    const names = analysisHints.generationHints.interactiveElements
+      .map((e) => e.name || e.nodeId || e.id || '(unnamed)')
+      .filter(Boolean)
+      .join(', ');
+    if (names) {
+      instructions.push(`These elements likely need interaction: ${names}`);
+    }
+  }
+
+  // Reusable components
+  if (analysisHints?.reusableComponents?.length) {
+    const names = analysisHints.reusableComponents
+      .map((c) => c.name || c.componentName || c.id || '(unnamed)')
+      .filter(Boolean)
+      .join(', ');
+    if (names) {
+      instructions.push(
+        `Consider extracting ${analysisHints.reusableComponents.length} reusable component(s): ${names}`
+      );
+    }
+  }
+
+  return {
+    summary: `After writing ${structName}.swift, apply these refinements to make it production-ready:`,
+    steps: instructions,
+    filePath,
+  };
+}
+
+async function shutdownBridgeAndExit(message, exitCode = 1) {
+  console.error(message);
+  if (authValidationTimer) {
+    clearInterval(authValidationTimer);
+    authValidationTimer = null;
+  }
+  if (bridgeRuntimeHandle && typeof bridgeRuntimeHandle.close === 'function' && !bridgeRuntimeHandle.alreadyRunning) {
+    try {
+      await bridgeRuntimeHandle.close();
+    } catch (error) {
+      console.error('[figma-swiftui-mcp] Failed to close bridge cleanly:', error.message);
+    }
+  }
+  process.exit(exitCode);
+}
+
+function startAuthValidationLoop() {
+  if (authValidationTimer) {
+    clearInterval(authValidationTimer);
+  }
+
+  authValidationTimer = setInterval(async () => {
+    try {
+      const validation = await validateRuntimeSession(runtimeAuthState);
+      if (!validation.valid) {
+        await shutdownBridgeAndExit(`[figma-swiftui-mcp] Authorization lost: ${validation.error}`);
+        return;
+      }
+
+      runtimeAuthState = {
+        ...runtimeAuthState,
+        ...validation.session,
+        authorized: true,
+      };
+
+      if (validation.refreshed) {
+        console.error('[figma-swiftui-mcp] Refreshed CreateLex MCP authorization');
+      }
+    } catch (error) {
+      await shutdownBridgeAndExit(`[figma-swiftui-mcp] Authorization revalidation failed: ${error.message}`);
+    }
+  }, AUTH_REVALIDATION_INTERVAL_MS);
+
+  authValidationTimer.unref?.();
+}
+
+async function main() {
+  runtimeAuthState = await authorizeRuntimeStartup();
+  console.error(
+    runtimeAuthState.bypass
+      ? '[figma-swiftui-mcp] Authorization bypass enabled'
+      : `[figma-swiftui-mcp] Authorized CreateLex user ${runtimeAuthState.email || runtimeAuthState.userId || 'unknown-user'}`
+  );
+
+  const bridgeHttpUrl = new URL(BRIDGE_HTTP_URL);
+  bridgeRuntimeHandle = await startBridgeServer({
+    host: bridgeHttpUrl.hostname,
+    port: Number(bridgeHttpUrl.port || (bridgeHttpUrl.protocol === 'https:' ? 443 : 80)),
+    projectPath: readProjectPathArg(process.argv),
+    logger: {
+      info: console.error,
+      warn: console.error,
+      error: console.error,
+    },
+  });
+
+  try {
+    await connectBridge();
+  } catch (error) {
+    console.error('[figma-swiftui-mcp] Bridge connect failed on startup:', error.message);
+  }
+
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+  startAuthValidationLoop();
+  console.error('[figma-swiftui-mcp] MCP server running on stdio');
+}
+
+main().catch((error) => {
+  console.error('[figma-swiftui-mcp] Server error:', error);
+  process.exit(1);
+});