flyu

A local design-file client: it parses Sketch / Figma design files into a unified DSL v3 and exposes them to Cursor / Claude through a built-in MCP (HTTP, starts with the app), letting AI view the design, write code, iterate on drafts, and export sliced assets.

Demo

https://github.com/user-attachments/assets/51cc93c6-8413-4c3b-8bfd-7fd135e26a3c

License: MIT. Third-party notices: see NOTICE.md. Security disclosures: see SECURITY.md. Contributing: see CONTRIBUTING.md.

The file formats and trademarks of Sketch / Figma belong to their rights holders. This project parses the .sketch / .fig files you import on your local machine, without vendor endorsement, and does not claim affiliation with Figma, Inc. or Sketch B.V. Please follow their terms of service and only import design files you are authorized to use. The .fig decoding implementation is in crates/fig-kiwi-rs.

User-facing docs are in docs/user-guide.md (installation / features / prompts / troubleshooting); MCP tool details are in docs/write-tools-guide.md.

Related MCP server: figma-opencode-mcp

Development

pnpm install        # 安装依赖(postinstall 会把 better-sqlite3 编到 Electron ABI)
pnpm dev            # 启动 Electron + HMR
pnpm typecheck      # 类型检查(main + renderer + mcp + tests)
pnpm lint           # ESLint
pnpm test           # 单元 + 契约测试(tsx --test)
pnpm test:visual    # 渲染像素回归(改 import/render 后必跑)
pnpm build          # 构建到 out/(含 main/preload/renderer/mcp)
pnpm dist           # 打本机未签名 mac 双架构(arm64 + x64).dmg → release/

Packaging (unsigned local macOS)

pnpm dist           # build + electron-builder → release/flyu-*-mac-arm64.dmg + flyu-*-mac-x64.dmg
pnpm dist:dir       # 只打 arm64 .app 到 release/mac-arm64/(便于调试)

Dual-architecture: electron-builder packages each target architecture separately; better-sqlite3 is rebuilt per architecture (cross-compiling x64 on an arm64 host has been verified to work).

The output is an unsigned package (identity: null); after installation, the app is named “非鱼”. If Gatekeeper blocks opening it locally: right-click → Open. Do not launch it at the same time as a running pnpm dev (the single-instance lock makes the second process exit immediately).

MCP Server

Two connection methods, same set of tools/prompts (29 Tools + 4 Prompts):

• HTTP (recommended): the client embeds a Streamable HTTP server that starts with the app. Settings → MCP usage config → Copy (URL + Bearer token). The default port 32677 persists, only falling back when it is occupied; the token is persisted in userData/mcp-token (0600) and can be regenerated.

• stdio (fallback, requires local Node): node out/mcp/server.js. Requires the DB to already exist (the client has been started at least once).

Building the stdio entrypoint

pnpm mcp:build      # esbuild 打包到 out/mcp/server.js
pnpm mcp:dev        # tsx 直跑(调试用)

Verification (manual JSON-RPC testing)

echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"test","version":"1.0"}}}' | pnpm mcp:dev

It should return serverInfo: { name: "flyu-design", version: "1.0.0" }.

macOS local development pitfalls (dual ABI + code signing)

1. ABI switching: better-sqlite3 can only be compiled for one runtime at a time.

   • For Electron: pnpm rebuild (uses electron-rebuild)

   • For running Node directly (MCP debugging / tsx tests): cd node_modules/.pnpm/better-sqlite3@*/node_modules/better-sqlite3 && ./node_modules/.bin/prebuild-install -r node

   • Symptom: using the wrong runtime reports something like NODE_MODULE_VERSION 130 vs 127.

2. Code signing: prebuilt .node files pulled from npm are killed by AMFI on macOS 26+ with Invalid Page (SIGKILL, exit 137, empty stderr). Fix:

codesign --remove-signature node_modules/.pnpm/better-sqlite3@*/node_modules/better-sqlite3/build/Release/better_sqlite3.node
codesign --force --sign -       node_modules/.pnpm/better-sqlite3@*/node_modules/better-sqlite3/build/Release/better_sqlite3.node

You must redo this after every prebuild-install. Later, automate it during packaging with electron-builder’s afterSign hook.

Directory

src/
├── main/           Electron 主进程(DB / IPC / 渲染 / 导入导出)
│   ├── import/     双通道导入:sketch-*(.sketch)/ fig-*(.fig 本地,@open-pencil/core)
│   │               + html-to-dsl(HTML 生成)、collect-tokens(共享令牌统计)
│   ├── render/     渲染调度(fig 走 Skia 直渲;sketch 走 DSL→HTML→Chromium)
│   ├── export/     dsl-to-jsx / dsl-to-fig / vector-to-svg / code-snippets / cut-cache
│   ├── tokens/     设计令牌(L1 命名令牌 / L3 组件令牌 / tokenize)
│   ├── db/         SQLite(writers / write-ops / write-docs / restyle / migrations)
│   └── ipc/        渲染进程桥(files / folders / explorer / mcp-config / library)
├── preload/        contextBridge 桥
├── renderer/       React + AntD UI
├── mcp/            MCP Server:server.ts(stdio)+ tools.ts(聚合器)+ tools-*.ts(8 个域模块)
├── shared/         三端共享(DSL v3 类型 / IPC 通道 / 错误码 / 路径)
└── native/         fig-kiwi WASM(由 crates/ 编译)

crates/             Rust 原生(.fig Kiwi 解码)
resources/          打包图标 icon.png / icon.icns
docs/               用户教程 / 写能力设计与工具文档
scripts/            正式脚本(icons / wasm / 视觉回归)
tests/              单元与契约测试

Local runtime data is stored in the user directory (~/Library/Application Support/fly) and the optional .tokensave/ (gitignored); build artifacts live in out/.

Current status

• Dual-channel import: parse .sketch / .ig locally (@open-encil/core)

• Unified DSL v3 + SQLite persistence + versioned groups

• Rendering: fig straight-rendered with Skia; skrch/AI through DSL→HTML→Chromium; degreded is explicitly reported

• MCP 29 Tools + 4 Prompts (navigation / data / visual / code / assets / write operations / semantic edits)

• Write capabilities: transactualized applied_operations / restyled_*(drun) / created_from_html / fork_document / rollback

• Export: get_HTML (self-contained single file) / get_code (JSX+Tailwind, vw/rem/tokenized) / get_fig (.fig unofficial interoperability) / download_assets (SVG/PNG/original)

• Design tokens: L1 named tokens (Figma variables / Sketch styles, CSS/DTCG export) + L3 component token overrides appended

• Windows / Linux installers (config ready, not released)