diff --git a/external_plugins/figma-mcp/.zcode-plugin/plugin.json b/external_plugins/figma-mcp/.zcode-plugin/plugin.json new file mode 100644 index 00000000..3c6a317d --- /dev/null +++ b/external_plugins/figma-mcp/.zcode-plugin/plugin.json @@ -0,0 +1,27 @@ +{ + "name": "figma-mcp", + "version": "0.1.0", + "description": "Figma MCP integration: screenshots, design context, variables, code connect and FigJam via the official mcp.figma.com server, with guided first-time OAuth setup.", + "author": { + "name": "Jommmain", + "url": "https://github.com/Jommmain" + }, + "keywords": [ + "figma", + "mcp", + "design", + "ui", + "oauth" + ], + "mcpServers": { + "figma": { + "type": "http", + "url": "https://mcp.figma.com/mcp" + } + }, + "skills": "./skills", + "description_i18n": { + "en": "Figma MCP integration: screenshots, design context, variables, code connect and FigJam via the official mcp.figma.com server, with guided first-time OAuth setup.", + "zh-CN": "Figma MCP 集成:通过官方 mcp.figma.com 服务器获取截图、设计上下文、变量、code connect 与 FigJam,并提供首次 OAuth 授权指引。" + } +} diff --git a/external_plugins/figma-mcp/README.md b/external_plugins/figma-mcp/README.md new file mode 100644 index 00000000..fcd2b247 --- /dev/null +++ b/external_plugins/figma-mcp/README.md @@ -0,0 +1,64 @@ +# figma-mcp + +Connect ZCode to Figma through the official **Figma MCP server** +(`https://mcp.figma.com/mcp`): pull screenshots and structured design context, +read variables and design tokens, work with code connect mappings and FigJam +boards, and turn code into designs. + +## What's included + +- **MCP server declaration** for the official remote Figma MCP server. After + authorization it exposes ~45 tools, including: + - `get_screenshot` — render a file/frame/node to an image + - `get_design_context` — structured layout data for a selection + - `get_variable_defs`, `get_metadata`, `get_figjam` + - code connect: `get_code_connect_map`, `send_code_connect_mappings`, + `send_code_to_figma` + - `use_figma` and other higher-level design operations +- **Setup skill** that guides first-time OAuth authorization and 401 + troubleshooting. + +## First-time setup (one time) + +The Figma MCP server only whitelists a fixed list of OAuth client names, and +ZCode is not on it, so the out-of-the-box flow fails at client registration. +Authorize once with the helper script: + +```bash +git clone https://github.com/Jommmain/zcode-figma-mcp +cd zcode-figma-mcp && npm install +node figma-mcp-auth.mjs +``` + +The script opens a browser: log in to Figma and click Authorize. It injects +the tokens into ZCode's encrypted credential store +(`~/.zcode/v2/credentials.json`, backup is written alongside). Restart ZCode +(or reconnect the `figma` server) afterwards. + +Access tokens expire after roughly 90 days; when ZCode starts receiving 401s, +re-run the script. + +## Dependencies, network access and side effects + +- Network: connections to `https://mcp.figma.com` (MCP + OAuth), initiated by + ZCode after installation. The helper script additionally runs a local + callback server on `localhost:3000` during authorization. +- Service dependency: a Figma account with access to the files the user asks + about. +- File writes: none by the plugin itself. The optional helper script writes + only to `~/.zcode/v2/credentials.json` (plus a `.backup` copy). +- Command execution: the setup skill instructs running the helper script from + https://github.com/Jommmain/zcode-figma-mcp when authorization is needed. + +## Third-party code and services + +- **Figma MCP server** — remote service operated by Figma; subject to Figma's + terms of service. +- **zcode-figma-mcp helper** (optional) — + https://github.com/Jommmain/zcode-figma-mcp , a fork of + https://github.com/DarkGenius/zcode-figma-mcp ; the OAuth flow depends on + the `@modelcontextprotocol/sdk` (MIT). + +## Category + +`productivity` diff --git a/external_plugins/figma-mcp/README_CN.md b/external_plugins/figma-mcp/README_CN.md new file mode 100644 index 00000000..5f55e020 --- /dev/null +++ b/external_plugins/figma-mcp/README_CN.md @@ -0,0 +1,56 @@ +# figma-mcp + +通过 Figma **官方 MCP 服务器**(`https://mcp.figma.com/mcp`)将 ZCode 接入 +Figma:获取截图与结构化设计上下文、读取变量与设计令牌、处理 code connect +映射与 FigJam 画板,以及将代码转换为设计。 + +## 包含内容 + +- **MCP 服务器声明**:官方远程 Figma MCP 服务器。授权后提供约 45 个工具, + 包括: + - `get_screenshot` — 将文件/画框/节点渲染为图片 + - `get_design_context` — 获取选区的结构化布局数据 + - `get_variable_defs`、`get_metadata`、`get_figjam` + - code connect:`get_code_connect_map`、`send_code_connect_mappings`、 + `send_code_to_figma` + - `use_figma` 及其他高层设计操作 +- **配置技能**:指引首次 OAuth 授权与 401 排障。 + +## 首次配置(一次性) + +Figma MCP 服务器只允许固定名单内的 OAuth 客户端名称,ZCode 不在其中, +开箱即用的连接会在客户端注册一步失败。请先运行辅助脚本完成授权: + +```bash +git clone https://github.com/Jommmain/zcode-figma-mcp +cd zcode-figma-mcp && npm install +node figma-mcp-auth.mjs +``` + +脚本会打开浏览器:登录 Figma 并点击授权。随后脚本将令牌写入 ZCode 的加密 +凭据库(`~/.zcode/v2/credentials.json`,同时生成 `.backup` 备份)。完成后 +重启 ZCode(或重连 `figma` 服务器)。 + +访问令牌约 90 天过期;ZCode 收到 401 时重新运行该脚本。 + +## 依赖、网络访问与副作用 + +- 网络:安装后由 ZCode 连接 `https://mcp.figma.com`(MCP 与 OAuth)。辅助 + 脚本在授权期间额外在本机 `localhost:3000` 运行回调服务器。 +- 服务依赖:需要 Figma 账号,且对用户指定的文件有访问权限。 +- 文件写入:插件本身不写文件。可选的辅助脚本仅写入 + `~/.zcode/v2/credentials.json`(并生成 `.backup` 备份)。 +- 命令执行:配置技能在需要授权时指示运行来自 + https://github.com/Jommmain/zcode-figma-mcp 的辅助脚本。 + +## 第三方代码与服务 + +- **Figma MCP 服务器** — Figma 运营的远程服务,受 Figma 服务条款约束。 +- **zcode-figma-mcp 辅助脚本**(可选)— + https://github.com/Jommmain/zcode-figma-mcp ,为 + https://github.com/DarkGenius/zcode-figma-mcp 的 fork;OAuth 流程依赖 + `@modelcontextprotocol/sdk`(MIT)。 + +## 分类 + +`productivity` diff --git a/external_plugins/figma-mcp/skills/figma-mcp/SKILL.md b/external_plugins/figma-mcp/skills/figma-mcp/SKILL.md new file mode 100644 index 00000000..45b425a3 --- /dev/null +++ b/external_plugins/figma-mcp/skills/figma-mcp/SKILL.md @@ -0,0 +1,44 @@ +--- +name: figma-mcp +description: Use when the user asks to inspect or extract from Figma designs — screenshots, design context, variables/tokens, component code connect, FigJam boards — or to create designs from code. Also covers first-time OAuth setup and 401 troubleshooting for the Figma MCP server. +--- + +# Figma MCP + +The `figma` MCP server (official `https://mcp.figma.com/mcp`) exposes ~45 tools, +including `get_screenshot` (render a frame/node to an image), `get_design_context` +(structured layout data for a selection), `get_variable_defs` (design tokens), +`get_metadata`, `get_figjam`, code-connect tools (`get_code_connect_map`, +`send_code_to_figma`), and `use_figma` (higher-level design operations). + +## First-time setup (OAuth) + +The Figma MCP server only whitelists a fixed list of OAuth client names, and +ZCode is not on it — a plain connect fails at client registration. The +one-time workaround is an authorization helper script: + +```bash +git clone https://github.com/Jommmain/zcode-figma-mcp +cd zcode-figma-mcp && npm install +node figma-mcp-auth.mjs +``` + +The script opens a browser: the user logs in to Figma and clicks Authorize. It +then injects the tokens into ZCode's encrypted credential store. Afterwards +restart ZCode (or reconnect the `figma` server). Full details: +https://github.com/Jommmain/zcode-figma-mcp (fork of +https://github.com/DarkGenius/zcode-figma-mcp) + +## Troubleshooting + +- **401 from `figma` tools**: the access token expired (~90 days). Re-run + `node figma-mcp-auth.mjs` from the helper repository, then restart ZCode. +- **`Safari can't connect to "localhost"` after Authorize**: make sure port + 3000 is free (`lsof -i :3000`). + +## Working rules + +- Ask the user for a Figma URL (file, frame or node) when none is given; + never guess file keys. +- Prefer `get_screenshot` for visual review and `get_design_context` for + extracting structured layout data to rebuild a design. diff --git a/marketplace.json b/marketplace.json index c7f09a06..c10672ce 100644 --- a/marketplace.json +++ b/marketplace.json @@ -10,7 +10,10 @@ "url": "https://z.ai" }, "unlistedPlugins": [ - { "name": "openpencil", "source": "./external_plugins/openpencil" } + { + "name": "openpencil", + "source": "./external_plugins/openpencil" + } ], "plugins": [ { @@ -827,7 +830,9 @@ }, { "name": "excalidraw", - "componentTypes": ["ui"], + "componentTypes": [ + "ui" + ], "displayName": "Excalidraw", "displayName_i18n": { "en": "Excalidraw", @@ -850,7 +855,9 @@ "name": "photocraft", "icon": "https://cdn-zcode.z.ai/zcode/official-plugin/assets/photocraft/icon.png", "source": "./external_plugins/photocraft", - "componentTypes": ["ui"], + "componentTypes": [ + "ui" + ], "displayName": "PhotoCraft", "displayName_i18n": { "en": "PhotoCraft", @@ -877,7 +884,9 @@ "name": "vectorcraft", "icon": "https://cdn-zcode.z.ai/zcode/official-plugin/assets/vectorcraft/icon.png", "source": "./external_plugins/vectorcraft", - "componentTypes": ["ui"], + "componentTypes": [ + "ui" + ], "displayName": "VectorCraft", "displayName_i18n": { "en": "VectorCraft", @@ -904,7 +913,9 @@ "name": "pdfcraft", "icon": "https://cdn-zcode.z.ai/zcode/official-plugin/assets/pdfcraft/icon.png", "source": "./external_plugins/pdfcraft", - "componentTypes": ["ui"], + "componentTypes": [ + "ui" + ], "displayName": "PdfCraft", "displayName_i18n": { "en": "PdfCraft", @@ -931,7 +942,9 @@ "name": "designcraft", "icon": "https://cdn-zcode.z.ai/zcode/official-plugin/assets/designcraft/icon.png", "source": "./external_plugins/designcraft", - "componentTypes": ["ui"], + "componentTypes": [ + "ui" + ], "displayName": "DesignCraft", "displayName_i18n": { "en": "DesignCraft", @@ -958,7 +971,9 @@ "name": "wordcraft", "icon": "https://cdn-zcode.z.ai/zcode/official-plugin/assets/wordcraft/icon.png", "source": "./external_plugins/wordcraft", - "componentTypes": ["ui"], + "componentTypes": [ + "ui" + ], "displayName": "WordCraft", "displayName_i18n": { "en": "WordCraft", @@ -985,7 +1000,9 @@ "name": "gridcraft", "icon": "https://cdn-zcode.z.ai/zcode/official-plugin/assets/gridcraft/icon.png", "source": "./external_plugins/gridcraft", - "componentTypes": ["ui"], + "componentTypes": [ + "ui" + ], "displayName": "GridCraft", "displayName_i18n": { "en": "GridCraft", @@ -1012,7 +1029,9 @@ "name": "deckcraft", "icon": "https://cdn-zcode.z.ai/zcode/official-plugin/assets/deckcraft/icon.png", "source": "./external_plugins/deckcraft", - "componentTypes": ["ui"], + "componentTypes": [ + "ui" + ], "displayName": "DeckCraft", "displayName_i18n": { "en": "DeckCraft", @@ -1039,7 +1058,9 @@ "name": "cadcraft", "icon": "https://cdn-zcode.z.ai/zcode/official-plugin/assets/cadcraft/icon.png", "source": "./external_plugins/cadcraft", - "componentTypes": ["ui"], + "componentTypes": [ + "ui" + ], "displayName": "CADCraft", "displayName_i18n": { "en": "CADCraft", @@ -1066,7 +1087,9 @@ "name": "soundcraft", "icon": "https://cdn-zcode.z.ai/zcode/official-plugin/assets/soundcraft/icon.png", "source": "./external_plugins/soundcraft", - "componentTypes": ["ui"], + "componentTypes": [ + "ui" + ], "displayName": "SoundCraft", "displayName_i18n": { "en": "SoundCraft", @@ -1149,7 +1172,9 @@ }, "category": "developer-tools", "icon": "https://cdn-zcode.z.ai/zcode/official-plugin/assets/kicad/icon.png", - "componentTypes": ["ui"], + "componentTypes": [ + "ui" + ], "displayName": "KiCad", "displayName_i18n": { "en": "KiCad", @@ -1443,6 +1468,27 @@ "mcp", "verification" ] + }, + { + "name": "figma-mcp", + "source": "./external_plugins/figma-mcp", + "description": "Figma MCP integration: screenshots, design context, variables, code connect and FigJam via the official mcp.figma.com server, with guided first-time OAuth setup.", + "description_i18n": { + "en": "Figma MCP integration: screenshots, design context, variables, code connect and FigJam via the official mcp.figma.com server, with guided first-time OAuth setup.", + "zh-CN": "Figma MCP 集成:通过官方 mcp.figma.com 服务器获取截图、设计上下文、变量、code connect 与 FigJam,并提供首次 OAuth 授权指引。" + }, + "version": "0.1.0", + "author": { + "name": "Jommmain" + }, + "category": "productivity", + "keywords": [ + "figma", + "mcp", + "design", + "ui", + "oauth" + ] } ] -} \ No newline at end of file +}