@createlex/figma-swiftui-mcp 1.0.0 → 1.0.1

package/README.md

@@ -1,54 +1,32 @@
-# Figma to SwiftUI
+# CreateLex Figma to SwiftUI MCP
 
-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.
+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.
 
-## Overview
+## What it does
 
-This project consists of four main components:
+- 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
 
-- **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
+## Requirements
 
-## Architecture
+- 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
 
-```
-                ┌──────────────────────────────┐
-                │ 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
+## Install
 
-## Setup & Installation
-
-### Production Install
-
-Users do not need this repo checked out locally. The production flow is:
+Run directly with `npx`:
 
 ```bash
 npx @createlex/figma-swiftui-mcp login
 npx @createlex/figma-swiftui-mcp start --project /path/to/MyApp/MyApp
 ```
 
-Or install it once globally:
+Or install globally:
 
 ```bash
 npm install -g @createlex/figma-swiftui-mcp
@@ -56,329 +34,44 @@ 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
+## Login
 
-The MCP server persists the chosen Xcode source folder in:
+`login` opens your browser and signs you in with CreateLex. When login succeeds, the runtime saves your local session to:
 
 ```text
-~/Library/Application Support/FigmaSwiftUICompanion/config.json
+~/.createlex/auth.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
+## Start the runtime
 
-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
+Start the runtime with the Xcode source folder that contains your Swift files and `Assets.xcassets`:
 
-### 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"
-  }'
+npx @createlex/figma-swiftui-mcp start --project /path/to/MyApp/MyApp
 ```
 
-## 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
+If you omit `--project`, you can set the project path later from the plugin UI or your MCP client.
 
-- 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
+## Before you use it
 
-### Project path not recognized
+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
 
-- 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
+## Subscription and access
 
-### TypeScript compilation errors
+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.
 
-- Run `npm install` to ensure all dependencies are installed
-- Delete `node_modules` and reinstall if issues persist: `rm -rf node_modules && npm install`
+## Product page
 
-## Dependencies
+Manage plans and billing at:
 
-### Plugin
-- `@figma/plugin-typings` – Type definitions for Figma plugin API
-- `typescript` – TypeScript compiler
+- https://createlex.com/figma-swiftui
 
-### 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
+## Support
 
-## License
+For help, billing, or onboarding:
 
-Part of the AiWebplatform project.
+- https://createlex.com/contact

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@createlex/figma-swiftui-mcp",
-  "version": "1.0.0",
+  "version": "1.0.1",
   "description": "CreateLex MCP runtime for Figma-to-SwiftUI generation and Xcode export",
   "bin": {
     "figma-swiftui-mcp": "bin/figma-swiftui-mcp.js"