@createlex/figma-swiftui-mcp 1.0.0

package/README.md

@@ -0,0 +1,384 @@
+# Figma to SwiftUI
+
+A Figma plugin and local MCP toolchain for generating SwiftUI code directly from Figma designs. You can export a ready-to-import Xcode package from the plugin UI, or run an MCP-first workflow that inspects the live Figma session and writes generated SwiftUI directly into Xcode. In production, the local MCP runtime is authenticated against CreateLex and only starts for paid subscribers.
+
+## Overview
+
+This project consists of four main components:
+
+- **Figma Plugin** (`code.ts`): Runs in Figma, converts selected design nodes to SwiftUI code, exports images, and can download an Xcode-ready package from the UI
+- **Local Bridge Server** (`companion/bridge-server.cjs`): Runs locally on port 7765, powers the bridge used by both the plugin and agent clients, and writes generated files into a dedicated `FigmaGenerated` area inside your Xcode source folder
+- **Bridge Relay** (`companion/bridge-server.cjs` WebSocket path `/bridge`): Relays structured Figma data between the live plugin UI and agent clients
+- **MCP Server** (`companion/mcp-server.mjs`): The main runtime entrypoint. Starts the localhost bridge automatically, exposes stdio MCP tools, and writes directly into Xcode
+
+## Architecture
+
+```
+                ┌──────────────────────────────┐
+                │ MCP / Agent Client           │
+                │ npx @createlex/figma-swiftui-mcp start │
+                └──────────────┬───────────────┘
+                               │ stdio MCP
+                               ▼
+                    MCP server boots localhost bridge
+                               │
+                               ▼
+                        ws://localhost:7765/bridge
+                               ▲
+                               │
+Figma UI ── pluginMessage ──> Plugin Code ── HTTP POST ──> Bridge Server ──> Xcode Project
+                               │                              │
+                               └──────── bridge events ───────┘
+```
+
+## Prerequisites
+
+- Figma account
+- Xcode project
+- Node.js (v18 or later) and npm for the MCP server, localhost bridge, or local plugin development
+
+## Setup & Installation
+
+### Production Install
+
+Users do not need this repo checked out locally. The production flow is:
+
+```bash
+npx @createlex/figma-swiftui-mcp login
+npx @createlex/figma-swiftui-mcp start --project /path/to/MyApp/MyApp
+```
+
+Or install it once globally:
+
+```bash
+npm install -g @createlex/figma-swiftui-mcp
+figma-swiftui-mcp login
+figma-swiftui-mcp start --project /path/to/MyApp/MyApp
+```
+
+- `login` opens the CreateLex browser flow and writes `~/.createlex/auth.json`
+- `start` boots the local MCP runtime and localhost bridge together
+- the Figma plugin UI must stay open while you use MCP tools
+
+### Development Setup
+
+```bash
+cd figma-plugin-swiftui
+npm install
+```
+
+`npm install` now installs both the plugin dependencies and the local MCP runtime dependencies.
+
+## Building
+
+Compile the TypeScript plugin code to JavaScript:
+
+```bash
+npm run build
+```
+
+Watch for changes during development:
+
+```bash
+npm run watch
+```
+
+This will continuously compile `code.ts` → `code.js` as you edit.
+
+## Production Access Model
+
+`figma-swiftui` is a local runtime, but it is not an offline-only product. The MCP process validates the current user against the CreateLex backend before it starts, and revalidates the session while it is running.
+
+Production expectations:
+
+- the MCP runtime runs locally on the developer machine
+- the user must already be authenticated with CreateLex
+- the user must have an active paid subscription
+- if the subscription becomes invalid, the local runtime stops accepting bridge and MCP requests
+- Supabase auth configuration lives on the backend / DigitalOcean environment, not inside the local MCP package
+
+Before starting the production runtime:
+
+1. Run `npx @createlex/figma-swiftui-mcp login` once.
+2. Ensure the account has an active paid subscription.
+3. Start the local runtime with `npx @createlex/figma-swiftui-mcp start --project /path/to/MyApp/MyApp`.
+
+Environment overrides for development:
+
+- `FIGMA_SWIFTUI_BYPASS_AUTH=true` bypasses the CreateLex subscription gate
+- `CREATELEX_API_BASE_URL=https://your-domain/api` points validation at a different backend
+- `CREATELEX_ACCESS_TOKEN=...` or `FIGMA_SWIFTUI_ACCESS_TOKEN=...` provides a token directly instead of reading `~/.createlex/auth.json`
+
+## Running MCP + Bridge
+
+The MCP server is the only runtime command. It starts the localhost bridge automatically, validates the current CreateLex subscriber session, and that bridge powers both the plugin's **Send to Xcode** button and the MCP tools. You do not need any local runtime for **Download Package**.
+
+### Option 1: With project path specified
+
+```bash
+npx @createlex/figma-swiftui-mcp start --project /path/to/MyApp/MyApp
+```
+
+Replace `/path/to/MyApp/MyApp` with the actual path to your Xcode project's source folder (the one containing your Swift files and `Assets.xcassets`).
+
+The companion writes generated files into:
+
+```text
+{ProjectSource}/FigmaGenerated/Screens/
+{ProjectSource}/FigmaGenerated/Components/
+{ProjectSource}/FigmaGenerated/Manifest/
+```
+
+Image sets still go into the existing `Assets.xcassets` for build compatibility.
+
+### Option 2: Without project path (set from plugin UI)
+
+```bash
+npx @createlex/figma-swiftui-mcp start
+```
+
+Then set the project path through MCP or the Figma plugin UI after connecting.
+
+The MCP process will also boot the bridge at `http://localhost:7765`.
+
+Example output:
+```
+🚀 Figma SwiftUI bridge running at http://localhost:7765
+📂 Project path: /Users/you/Projects/MyApp/MyApp
+🌉 Bridge ready at ws://localhost:7765/bridge
+MCP server running on stdio
+```
+
+## MCP-First Workflow
+
+If you are using Cursor, Codex, Claude Code, or another MCP-compatible local tool, this is the preferred workflow:
+
+1. Start the local bridge and MCP server:
+
+```bash
+npx @createlex/figma-swiftui-mcp start
+```
+
+2. Keep the Figma plugin UI open so the bridge remains attached to the live Figma session.
+3. From the MCP client:
+   - inspect the design structure
+   - generate SwiftUI
+   - write directly into the Xcode project
+
+The MCP server persists the chosen Xcode source folder in:
+
+```text
+~/Library/Application Support/FigmaSwiftUICompanion/config.json
+```
+
+You can set that path once through MCP and then write repeatedly from the MCP client.
+
+## High-Fidelity Workflow
+
+For `figma-swiftui`, the local MCP runtime should be the primary inspection and generation tool. The most effective pattern is:
+
+1. inspect the design with `figma-swiftui`
+2. generate the first SwiftUI scaffold with `figma-swiftui`
+3. refine assets and visual details with normal code editing
+
+In practice:
+- use `figma-swiftui` for raw facts like SVG-backed icons, nested node structure, screenshots, export planning, and exact generation diagnostics
+- use `figma-swiftui` for the initial native SwiftUI scaffold and Xcode export
+- use your project/file tools for final polish and wiring
+
+You only need Figma Dev MCP as a fallback if you want broader Figma platform features outside the `figma-swiftui` workflow.
+
+Detailed guidance is in [docs/HIGH_FIDELITY_WORKFLOW.md](/Users/alexkissijr/dev/GitHub/AiWebplatform/figma-plugin-swiftui/docs/HIGH_FIDELITY_WORKFLOW.md).
+
+## Hybrid Production Model
+
+For production, the recommended architecture is hybrid:
+
+- hosted CreateLex services own entitlement checks, signed execution plans, and the long-term home of premium generation logic
+- the local `figma-swiftui` runtime stays thin and handles only live Figma access plus local Xcode writes
+
+The current hybrid foundation and migration path are documented in [docs/HYBRID_ARCHITECTURE.md](/Users/alexkissijr/dev/GitHub/AiWebplatform/figma-plugin-swiftui/docs/HYBRID_ARCHITECTURE.md).
+
+Today, the first hosted generation path covers recognized single-screen `editable` semantic scaffolds. If the hosted service cannot confidently handle a screen yet, the local runtime falls back to the existing local generator.
+
+## Agent Bridge and MCP Mode
+
+The MCP runtime exposes the bridge endpoints used for agentic tooling:
+
+- Raw WebSocket bridge: `ws://localhost:7765/bridge`
+- Bridge status endpoint: `GET http://localhost:7765/bridge/info`
+- MCP runtime: `npx @createlex/figma-swiftui-mcp start`
+- Build plugin bundle: `npm run build`
+- Bridge smoke test: `npm run test:bridge-smoke`
+- High-fidelity inspection smoke: `npm run test:high-fidelity-smoke`
+- Auth status tool: `auth_status`
+
+The bridge only works when the Figma plugin UI is open and connected to the local companion. Once connected, agent clients can inspect document/page/selection data or call the same SwiftUI generation path used by the plugin UI.
+
+Available bridge-backed MCP tools:
+
+- `bridge_status`
+- `get_project_path`
+- `set_project_path`
+- `get_metadata`
+- `get_design_context`
+- `get_screenshot`
+- `export_svg`
+- `get_document_summary`
+- `get_viewport_context`
+- `get_selection_snapshot`
+- `get_page_snapshot`
+- `get_node_snapshot`
+- `find_nodes`
+- `dump_tree`
+- `get_asset_export_plan`
+- `extract_reusable_components`
+- `write_svg_to_xcode`
+- `generate_swiftui`
+- `analyze_generation`
+- `write_generated_swiftui_to_xcode`
+- `write_selection_to_xcode`
+
+## Using the Plugin
+
+### Loading the Plugin in Figma
+
+1. Open Figma
+2. Go to **Plugins** → **Create new plugin**
+3. Select **Link existing plugin** and point to `manifest.json` in this directory
+4. Alternatively, use the Figma dashboard to import this directory as a plugin
+
+### Using the Plugin
+
+1. Select a component or frame in Figma
+2. Run the plugin (Plugins menu → Figma to SwiftUI)
+3. A UI panel opens with the SwiftUI export controls.
+4. Pick one export path:
+   - **Download Package** exports a zip containing `{StructName}.swift` plus an `Assets.xcassets` payload. This path does not require any local server.
+   - **Copy** copies the generated SwiftUI if you only want the code.
+5. In the Xcode sync panel:
+   - **Choose Folder** opens a native folder picker so you can select the Xcode project source folder
+   - **Send to Xcode** writes the generated Swift file into `FigmaGenerated/Screens`, updates `FigmaGenerated/Manifest`, and writes exported images into the project's existing `Assets.xcassets`
+6. If the local runtime is running and authorized, the generated code and images can be written directly into your Xcode project
+
+### MCP-Only Xcode Sync
+
+If you want to drive the whole sync from MCP:
+
+1. Start the MCP runtime.
+2. Keep the plugin UI open in Figma.
+3. Call `set_project_path` once.
+4. Call `write_selection_to_xcode` to generate from the live selection and write directly into Xcode.
+
+### Environment Setup
+
+The plugin looks for the local bridge at `http://localhost:7765`. Ensure:
+- `npx @createlex/figma-swiftui-mcp start` is running before using **Send to Xcode**
+- Your Xcode project path is set (either via `--project` flag or the plugin UI)
+- If you are using **Download Package**, no local runtime is required
+- If you want to use MCP or a raw WebSocket client, keep the plugin UI open so the bridge stays attached to a live Figma session
+
+## Project Structure
+
+```
+figma-plugin-swiftui/
+├── README.md                 # This file
+├── package.json             # Plugin dependencies (TypeScript)
+├── tsconfig.json            # TypeScript configuration
+├── manifest.json            # Figma plugin manifest
+├── code.ts                  # Plugin source code (TypeScript)
+├── code.js                  # Compiled plugin code (generated)
+├── ui.html                  # Plugin UI (HTML/CSS/JS)
+│
+└── companion/
+    ├── package.json         # Companion + MCP dependencies
+    ├── bridge-server.cjs    # HTTP server + WebSocket bridge relay
+    ├── server.js            # Thin bridge-only wrapper (debug/legacy)
+    ├── mcp-server.mjs       # stdio MCP entrypoint that boots the bridge
+    ├── xcode-writer.cjs     # Shared Xcode write/layout logic
+    └── node_modules/        # Dependencies
+```
+
+## Development
+
+### Editing the Plugin
+
+1. Edit `code.ts` (the main plugin logic)
+2. Run `npm run watch` to auto-compile on save
+3. The compiled `code.js` is what Figma actually runs
+
+### Editing the UI
+
+Edit `ui.html` directly. It's loaded by the plugin via `figma.showUI()`.
+
+### Testing the Runtime
+
+The server has two main endpoints:
+
+- `GET /ping` – Health check, returns project path status
+- `GET /bridge/info` – Bridge health/status, reports whether a live plugin session is attached
+- `POST /set-project` – Saves a manually entered project path after validating it exists
+- `POST /choose-project` – Opens a native macOS folder picker and saves the selected path
+- `POST /write` – Receives `{ code, structName, images, customPath }`, writes `FigmaGenerated/Screens/{StructName}.swift`, updates `FigmaGenerated/Manifest`, and writes images into `Assets.xcassets`
+- `WS /bridge` – Relays structured Figma requests/responses/events between the plugin UI and external clients
+
+Example POST to test:
+```bash
+curl -X POST http://localhost:7765/write \
+  -H "Content-Type: application/json" \
+  -d '{
+    "code": "struct MyView: View { var body: some View { Text(\"Hello\") } }",
+    "structName": "MyView"
+  }'
+```
+
+## Troubleshooting
+
+### Server not reachable from plugin
+
+- This only affects **Send to Xcode**. The **Download Package** flow still works without the MCP runtime.
+- Ensure the MCP runtime is running: `npx @createlex/figma-swiftui-mcp start`
+- Check that it's listening on `http://localhost:7765`
+- Check the plugin's `manifest.json` `allowedDomains` includes both `http://localhost:7765` and `ws://localhost:7765`
+
+### Bridge or MCP shows no live Figma data
+
+- The MCP runtime can be running while the bridge is still disconnected from Figma. Open the plugin UI and leave it open.
+- Check `http://localhost:7765/bridge/info` and confirm `pluginConnected: true`
+- Restart the plugin UI if the bridge stays in `bridge waiting`
+- Start the MCP runtime with `npx @createlex/figma-swiftui-mcp start`
+
+### MCP runtime exits immediately
+
+- Run `npx @createlex/figma-swiftui-mcp login` first so `~/.createlex/auth.json` exists
+- Confirm the account has an active paid subscription
+- If needed, check `auth_status` from the MCP client after startup
+- In local development only, use `FIGMA_SWIFTUI_BYPASS_AUTH=true` to bypass the subscription gate
+
+### Project path not recognized
+
+- Verify the path points to the folder containing `.swift` files and `Assets.xcassets`
+- The server will create `FigmaGenerated/` and `Assets.xcassets` if they don't exist
+- Check filesystem permissions
+
+### TypeScript compilation errors
+
+- Run `npm install` to ensure all dependencies are installed
+- Delete `node_modules` and reinstall if issues persist: `rm -rf node_modules && npm install`
+
+## Dependencies
+
+### Plugin
+- `@figma/plugin-typings` – Type definitions for Figma plugin API
+- `typescript` – TypeScript compiler
+
+### MCP Runtime
+- `express` – Web server framework
+- `cors` – Cross-Origin Resource Sharing middleware
+- `ws` – WebSocket bridge relay
+- `@modelcontextprotocol/sdk` – MCP server SDK for the stdio wrapper
+- `zod` – MCP tool input schemas
+
+## License
+
+Part of the AiWebplatform project.

package/bin/figma-swiftui-mcp.js

@@ -0,0 +1,81 @@
+#!/usr/bin/env node
+'use strict';
+
+const path = require('node:path');
+const { spawn } = require('node:child_process');
+
+const CLI_NAME = 'figma-swiftui-mcp';
+const PACKAGE_NAME = '@createlex/figma-swiftui-mcp';
+
+function printHelp() {
+  console.log(`${CLI_NAME}
+
+Usage:
+  npx ${PACKAGE_NAME} login
+  npx ${PACKAGE_NAME} start [--project /path/to/Xcode/source]
+
+Commands:
+  login   Open the CreateLex browser login flow and save ~/.createlex/auth.json
+  start   Start the local figma-swiftui MCP runtime and localhost bridge
+  help    Show this help message
+  version Show the package version
+
+Examples:
+  npx ${PACKAGE_NAME} login
+  npx ${PACKAGE_NAME} start --project /Users/you/MyApp/MyApp
+  npm install -g ${PACKAGE_NAME}
+  ${CLI_NAME} start --project /Users/you/MyApp/MyApp
+`);
+}
+
+function resolveEntry(command) {
+  if (command === 'login') {
+    return path.join(__dirname, '..', 'companion', 'login.mjs');
+  }
+  return path.join(__dirname, '..', 'companion', 'mcp-server.mjs');
+}
+
+function runNode(entry, args) {
+  const child = spawn(process.execPath, [entry, ...args], {
+    stdio: 'inherit',
+  });
+
+  child.on('exit', (code, signal) => {
+    if (signal) {
+      process.kill(process.pid, signal);
+      return;
+    }
+    process.exit(code ?? 0);
+  });
+
+  child.on('error', (error) => {
+    console.error(`${CLI_NAME} failed: ${error.message}`);
+    process.exit(1);
+  });
+}
+
+const packageJson = require(path.join(__dirname, '..', 'package.json'));
+const [command = 'help', ...args] = process.argv.slice(2);
+
+switch (command) {
+  case 'login':
+    runNode(resolveEntry('login'), args);
+    break;
+  case 'start':
+    runNode(resolveEntry('start'), args);
+    break;
+  case 'help':
+  case '--help':
+  case '-h':
+    printHelp();
+    break;
+  case 'version':
+  case '--version':
+  case '-v':
+    console.log(packageJson.version);
+    break;
+  default:
+    console.error(`Unknown command: ${command}\n`);
+    printHelp();
+    process.exit(1);
+}