Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
27 changes: 27 additions & 0 deletions external_plugins/figma-mcp/.zcode-plugin/plugin.json
Original file line number Diff line number Diff line change
@@ -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 授权指引。"
}
}
64 changes: 64 additions & 0 deletions external_plugins/figma-mcp/README.md
Original file line number Diff line number Diff line change
@@ -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`
56 changes: 56 additions & 0 deletions external_plugins/figma-mcp/README_CN.md
Original file line number Diff line number Diff line change
@@ -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`
44 changes: 44 additions & 0 deletions external_plugins/figma-mcp/skills/figma-mcp/SKILL.md
Original file line number Diff line number Diff line change
@@ -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.
72 changes: 59 additions & 13 deletions marketplace.json
Original file line number Diff line number Diff line change
Expand Up @@ -10,7 +10,10 @@
"url": "https://z.ai"
},
"unlistedPlugins": [
{ "name": "openpencil", "source": "./external_plugins/openpencil" }
{
"name": "openpencil",
"source": "./external_plugins/openpencil"
}
],
"plugins": [
{
Expand Down Expand Up @@ -827,7 +830,9 @@
},
{
"name": "excalidraw",
"componentTypes": ["ui"],
"componentTypes": [
"ui"
],
"displayName": "Excalidraw",
"displayName_i18n": {
"en": "Excalidraw",
Expand All @@ -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",
Expand All @@ -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",
Expand All @@ -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",
Expand All @@ -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",
Expand All @@ -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",
Expand All @@ -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",
Expand All @@ -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",
Expand All @@ -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",
Expand All @@ -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",
Expand Down Expand Up @@ -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",
Expand Down Expand Up @@ -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"
]
}
]
}
}