omp-figma-remote-auth 0.1.2 → 0.1.5
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +45 -80
- package/README.zh-CN.md +46 -81
- package/index.ts +4 -11
- package/package.json +2 -1
- package/skills/figma-mcp/SKILL.md +59 -0
- package/src/args.ts +5 -6
- package/src/migration.ts +2 -2
package/README.md
CHANGED
|
@@ -2,134 +2,99 @@
|
|
|
2
2
|
|
|
3
3
|
[简体中文](README.zh-CN.md)
|
|
4
4
|
|
|
5
|
-
|
|
5
|
+
Connect [Oh My Pi (OMP)](https://github.com/can1357/oh-my-pi) to the official Figma Remote MCP server with browser login. OMP handles connections and token refresh. This unofficial plugin is not affiliated with Figma or OpenAI.
|
|
6
6
|
|
|
7
|
-
##
|
|
7
|
+
## Installation and authorization
|
|
8
8
|
|
|
9
|
-
|
|
10
|
-
- A Figma account with access to the intended files, and a browser on the same machine as OMP for the local OAuth callback. Figma Desktop is not required. Git is only needed for source installation.
|
|
11
|
-
- Zero runtime package dependencies. No `pi-mcp-adapter`, `npm install`, or build step is needed. Development tests require Node.js 22.6.0+ and npm.
|
|
12
|
-
- OMP's npm installer requires the standalone `bun` command on `PATH`. A packaged OMP binary may not include it; see the [Bun installation guide](https://bun.com/docs/installation). This is an installer requirement, not a package dependency.
|
|
9
|
+
Requires OMP 18.1.17+ (verified on 18.1.17), a Figma account with file access, and a browser on the same machine as OMP. No Figma Desktop or manual MCP configuration is needed.
|
|
13
10
|
|
|
14
|
-
|
|
15
|
-
|
|
16
|
-
Run this command in your **terminal (CLI)** to install from npm:
|
|
11
|
+
### 1. Install in your terminal
|
|
17
12
|
|
|
18
13
|
```sh
|
|
19
14
|
omp plugin install omp-figma-remote-auth@latest
|
|
20
15
|
```
|
|
21
16
|
|
|
22
|
-
|
|
23
|
-
|
|
24
|
-
If OMP reports `Executable not found in $PATH: "bun"`, install Bun first. With Node.js/npm available, you can also supply Bun temporarily for this command:
|
|
17
|
+
If `bun` is missing, use Node.js/npm to supply it temporarily:
|
|
25
18
|
|
|
26
19
|
```sh
|
|
27
20
|
npm exec --yes --package=bun -- omp plugin install omp-figma-remote-auth@latest
|
|
28
21
|
```
|
|
29
22
|
|
|
30
|
-
|
|
23
|
+
Start or restart OMP after installation:
|
|
31
24
|
|
|
32
25
|
```sh
|
|
33
|
-
|
|
34
|
-
omp plugin link ./omp-figma-remote-auth
|
|
26
|
+
omp
|
|
35
27
|
```
|
|
36
28
|
|
|
37
|
-
|
|
38
|
-
|
|
39
|
-
Install or link the full package to use its MCP registration. Loading only `index.ts` with `omp -e` is useful for testing the authentication commands, but is not a substitute for package installation. A successful `/figma-remote-auth status` confirms local credential state; it does not confirm that OMP discovered or connected the MCP server. For normal use, start `omp` after installing the package, then run `/mcp reload` and `/mcp test figma`.
|
|
40
|
-
|
|
41
|
-
To switch an existing development link to the registry package:
|
|
42
|
-
|
|
43
|
-
1. Record the source checkout's canonical path with `realpath /absolute/path/to/omp-figma-remote-auth`, and note the installed plugin path in OMP's plugins directory (normally `~/.omp/plugins`).
|
|
44
|
-
2. Run `omp plugin uninstall omp-figma-remote-auth`, then `omp plugin list`. Confirm that the list no longer contains `omp-figma-remote-auth`; stop if it still does.
|
|
45
|
-
3. If the installed plugin path remains, inspect it before proceeding. Only if it is proven to be a leftover symlink whose `realpath` equals the recorded source checkout path may you use `unlink /absolute/path/to/installed/plugin` to remove that symlink alone. Never recursively delete the target. Stop and investigate any other directory or link conflict, including a link whose destination cannot be verified.
|
|
46
|
-
4. Install with `omp plugin install omp-figma-remote-auth@latest`, or `npm exec --yes --package=bun -- omp plugin install omp-figma-remote-auth@latest` if Bun is not on PATH.
|
|
47
|
-
5. Run `omp plugin list` to confirm installation, then run `realpath /absolute/path/to/installed/plugin`. The resolved path must not equal the recorded source checkout path; stop if it does or cannot be resolved. A registry installation may legitimately use a symlink into a package cache; that alone is not an error and is not a reason to unlink it.
|
|
48
|
-
|
|
49
|
-
Replace the example absolute paths with your actual paths. Restart OMP or run `/reload-plugins` after migration.
|
|
50
|
-
|
|
51
|
-
The following are **slash commands inside OMP's interactive interface (TUI)**, not shell commands. Start OMP with `omp` if needed, then run:
|
|
29
|
+
### 2. Log in from the OMP input box
|
|
52
30
|
|
|
53
31
|
```text
|
|
54
|
-
/figma-remote-auth setup
|
|
55
32
|
/figma-remote-auth login
|
|
56
33
|
```
|
|
57
34
|
|
|
58
|
-
|
|
35
|
+
Your browser opens automatically. If it does not, click **点击这里授权 Figma** (“Click here to authorize Figma”) above the editor, or copy the complete short URL into your browser. The default app name on the consent page is **Codex**; see [authentication details](#configuration-and-authentication).
|
|
59
36
|
|
|
60
|
-
|
|
37
|
+
Approve access and wait for OMP to confirm that credentials were saved.
|
|
61
38
|
|
|
62
|
-
|
|
63
|
-
|
|
64
|
-
With the default settings, Figma's consent page shows **Codex** as the application name; see the authentication explanation below. Approve access, keep OMP running for the callback to `http://127.0.0.1:<port>/callback`, and return to OMP to confirm that authorization was saved. Opening the browser or receiving the code alone does not confirm that token exchange succeeded. The entry remains available while waiting and is removed on success, failure, timeout, cancellation, or OMP shutdown.
|
|
65
|
-
|
|
66
|
-
After OMP confirms success, run these TUI commands:
|
|
39
|
+
### 3. Check the connection in OMP
|
|
67
40
|
|
|
68
41
|
```text
|
|
69
42
|
/mcp reload
|
|
70
43
|
/mcp test figma
|
|
71
44
|
```
|
|
72
45
|
|
|
73
|
-
|
|
46
|
+
The server name is `figma`. Once connected, give OMP a Figma file or node URL you can access.
|
|
47
|
+
|
|
48
|
+
The package also includes the on-demand `figma-mcp` skill. When you provide a Figma file or node link, it guides OMP through parsing the node reference and discovering the Figma MCP tools, including tools mounted under `xd://`.
|
|
74
49
|
|
|
75
50
|
## Commands
|
|
76
51
|
|
|
77
|
-
|
|
52
|
+
These commands run **inside OMP's TUI**, not in your terminal.
|
|
78
53
|
|
|
79
54
|
| Command | Purpose |
|
|
80
55
|
| --- | --- |
|
|
81
|
-
| `/figma-remote-auth
|
|
82
|
-
| `/figma-remote-auth
|
|
83
|
-
| `/figma-remote-auth
|
|
84
|
-
| `/figma-remote-auth
|
|
85
|
-
| `/figma-remote-auth
|
|
86
|
-
| `/
|
|
56
|
+
| `/figma-remote-auth login` | Log in or reauthorize, handling necessary migration automatically. |
|
|
57
|
+
| `/figma-remote-auth status` | Show local credentials; does not test the connection. |
|
|
58
|
+
| `/figma-remote-auth cancel` | Cancel authorization and close the local entry and listener. |
|
|
59
|
+
| `/figma-remote-auth logout` | Clear this plugin's local credentials without revoking Figma authorization. |
|
|
60
|
+
| `/figma-remote-auth help` | Show full usage. |
|
|
61
|
+
| `/mcp list` | List MCP servers. |
|
|
87
62
|
|
|
88
|
-
|
|
89
|
-
|
|
90
|
-
```text
|
|
91
|
-
/figma-remote-auth login --client-name Codex --port 19876
|
|
92
|
-
/figma-remote-auth login --no-browser
|
|
93
|
-
```
|
|
63
|
+
Add `--no-browser` to open the short entry manually, `--port` to choose a port (random by default), or `--client-name` to change the app name (default `Codex`). See `help` for full usage.
|
|
94
64
|
|
|
95
|
-
|
|
65
|
+
Authorization waits up to **10 minutes**. Completion, cancellation, or exiting OMP releases the listener; closing the browser does not cancel the wait.
|
|
96
66
|
|
|
97
|
-
|
|
67
|
+
## Uninstall
|
|
98
68
|
|
|
99
|
-
|
|
69
|
+
Run this in your terminal, then restart OMP:
|
|
100
70
|
|
|
101
|
-
|
|
102
|
-
|
|
103
|
-
|
|
71
|
+
```sh
|
|
72
|
+
omp plugin uninstall omp-figma-remote-auth
|
|
73
|
+
```
|
|
104
74
|
|
|
105
|
-
|
|
75
|
+
Uninstalling removes the package's Figma registration and retains credentials for reinstalling. Independent user/project configuration is unaffected.
|
|
106
76
|
|
|
107
|
-
|
|
77
|
+
To clear credentials too, run `/figma-remote-auth logout` and `/mcp reload` in OMP before uninstalling. Revoke server-side authorization separately in your Figma account settings.
|
|
108
78
|
|
|
109
79
|
## Troubleshooting
|
|
110
80
|
|
|
111
|
-
|
|
112
|
-
|
|
113
|
-
|
|
114
|
-
|
|
115
|
-
|
|
116
|
-
|
|
117
|
-
|
|
118
|
-
|
|
119
|
-
Installing or linking the plugin does not log you in. Uninstalling it and restarting OMP removes the package-provided `figma` MCP registration without requiring logout first or manual removal from `mcp.json`. Credentials remain in OMP for reuse after reinstalling in the same profile. For a legacy installation, complete the setup migration above before relying on this package-managed lifecycle; custom configuration conflicts still require explicit review.
|
|
120
|
-
|
|
121
|
-
For optional credential cleanup, run `/figma-remote-auth logout` and `/mcp reload` in each profile you authorized while the plugin is installed. Logout deletes only this plugin's owned local native profile/URL credential and owned legacy agent-directory credential; it leaves registration and credentials belonging to other authentication sources untouched. It does **not revoke the server-side authorization at Figma**. To revoke that authorization, remove the corresponding app authorization in your Figma account settings.
|
|
122
|
-
|
|
123
|
-
Uninstall from the terminal:
|
|
81
|
+
| Problem | What to do |
|
|
82
|
+
| --- | --- |
|
|
83
|
+
| Plugin command not found | Check `omp plugin list` in your terminal, then restart OMP. |
|
|
84
|
+
| MCP not connected | Confirm the full package is installed, then run `/mcp reload` and `/mcp test figma`. |
|
|
85
|
+
| Callback fails or login keeps waiting | Cancel and retry with `/figma-remote-auth login --port 0`. The browser must reach `127.0.0.1` on the OMP machine; SSH/container forwarding is not configured automatically. |
|
|
86
|
+
| Config or credential conflict | Inspect the reported path and back up before editing. Custom config and credentials from other sources are not overwritten. |
|
|
87
|
+
| Authentication fails | Run `/figma-remote-auth login` again, then reload/test. `/mcp reauth figma` does not invoke this plugin. |
|
|
88
|
+
| Permission or quota error | Check the account, file access, and plan; see [Figma's limits](https://developers.figma.com/docs/figma-mcp-server/rate-limits-access/). |
|
|
124
89
|
|
|
125
|
-
|
|
126
|
-
omp plugin uninstall omp-figma-remote-auth
|
|
127
|
-
```
|
|
90
|
+
## Configuration and authentication
|
|
128
91
|
|
|
129
|
-
|
|
92
|
+
- **Config and credentials:** the package's `.mcp.json` provides Figma MCP; new installs do not write user MCP config. OMP stores and refreshes credentials. When using profiles, log in within the same profile.
|
|
93
|
+
- **App name:** `Codex` accommodates [Figma's client policy](https://developers.figma.com/docs/figma-mcp-server/rate-limits-access/#which-mcp-clients-are-supported). Each login registers an independent client without using Codex accounts or credentials.
|
|
94
|
+
- **Authorization entry:** a local short URL forwards the complete OAuth request. Long authorization URLs and tokens are never printed in the terminal.
|
|
130
95
|
|
|
131
|
-
##
|
|
96
|
+
## License and credits
|
|
132
97
|
|
|
133
|
-
|
|
98
|
+
[MIT](LICENSE). Adapted from [DianP/pi-figma-remote-auth](https://github.com/DianP/pi-figma-remote-auth), whose authentication approach references [sdaoudi/mcp-auth-helper](https://github.com/sdaoudi/mcp-auth-helper).
|
|
134
99
|
|
|
135
|
-
|
|
100
|
+
For source installation and testing, see the [development guide](https://github.com/picasuo/omp-figma-remote-auth/blob/main/DEVELOPMENT.md#english).
|
package/README.zh-CN.md
CHANGED
|
@@ -2,134 +2,99 @@
|
|
|
2
2
|
|
|
3
3
|
[English](README.md)
|
|
4
4
|
|
|
5
|
-
|
|
5
|
+
为 [Oh My Pi（OMP）](https://github.com/can1357/oh-my-pi) 接入 Figma 官方远程 MCP，提供浏览器登录，连接和令牌刷新由 OMP 负责。非官方插件，与 Figma、OpenAI 无隶属关系。
|
|
6
6
|
|
|
7
|
-
##
|
|
7
|
+
## 安装和授权
|
|
8
8
|
|
|
9
|
-
|
|
10
|
-
- 拥有目标文件访问权限的 Figma 账号，以及与 OMP 运行在同一台机器上的浏览器，用于接收本地 OAuth 回调。无需 Figma 桌面客户端。仅源码安装需要 Git。
|
|
11
|
-
- 零运行时包依赖，无需 `pi-mcp-adapter`、`npm install` 或构建。开发测试需要 Node.js 22.6.0+ 和 npm。
|
|
12
|
-
- OMP 的 npm 安装功能要求 `PATH` 中有独立的 `bun` 命令。打包好的 OMP 可执行文件不一定附带它，请参阅 [Bun 安装说明](https://bun.com/docs/installation)。这是安装器的要求，不是插件的包依赖。
|
|
9
|
+
需要 OMP 18.1.17+（已验证 18.1.17）、有文件访问权限的 Figma 账号，以及与 OMP 在同一台机器上的浏览器。无需 Figma Desktop 或手动编辑 MCP 配置。
|
|
13
10
|
|
|
14
|
-
|
|
15
|
-
|
|
16
|
-
在**终端（CLI）**中执行以下命令，从 npm 安装：
|
|
11
|
+
### 1. 安装：在终端执行
|
|
17
12
|
|
|
18
13
|
```sh
|
|
19
14
|
omp plugin install omp-figma-remote-auth@latest
|
|
20
15
|
```
|
|
21
16
|
|
|
22
|
-
|
|
23
|
-
|
|
24
|
-
如果 OMP 提示 `Executable not found in $PATH: "bun"`，请先安装 Bun。已有 Node.js/npm 时，也可临时提供 Bun 来执行安装：
|
|
17
|
+
如果提示找不到 `bun`，可用 Node.js/npm 临时提供：
|
|
25
18
|
|
|
26
19
|
```sh
|
|
27
20
|
npm exec --yes --package=bun -- omp plugin install omp-figma-remote-auth@latest
|
|
28
21
|
```
|
|
29
22
|
|
|
30
|
-
|
|
23
|
+
安装后启动或重启 OMP：
|
|
31
24
|
|
|
32
25
|
```sh
|
|
33
|
-
|
|
34
|
-
omp plugin link ./omp-figma-remote-auth
|
|
26
|
+
omp
|
|
35
27
|
```
|
|
36
28
|
|
|
37
|
-
|
|
38
|
-
|
|
39
|
-
使用包内 MCP 注册需要安装或链接完整插件包。通过 `omp -e` 仅加载 `index.ts` 适合测试认证命令，不能替代插件安装。`/figma-remote-auth status` 成功只能确认本地凭据状态，不代表 OMP 已发现或连接 MCP 服务。正常使用时，安装插件后直接启动 `omp`，再执行 `/mcp reload` 和 `/mcp test figma`。
|
|
40
|
-
|
|
41
|
-
从已有开发链接切换到 registry 包时：
|
|
42
|
-
|
|
43
|
-
1. 使用 `realpath /absolute/path/to/omp-figma-remote-auth` 记录源码目录的规范路径，并记下 OMP plugins 目录（通常为 `~/.omp/plugins`）中的插件安装路径。
|
|
44
|
-
2. 执行 `omp plugin uninstall omp-figma-remote-auth`，再执行 `omp plugin list`。确认列表中已不包含 `omp-figma-remote-auth`；如果仍存在，请停止。
|
|
45
|
-
3. 如果插件安装路径仍存在，先检查它。只有确认它是残留符号链接，且其 `realpath` 等于已记录的源码目录路径时，才可以用 `unlink /absolute/path/to/installed/plugin` 仅移除该符号链接。绝不能递归删除目标目录。遇到任何其他目录或链接冲突（包括无法确认目标的链接），请停止并排查。
|
|
46
|
-
4. 执行 `omp plugin install omp-figma-remote-auth@latest` 安装；如果 PATH 中没有 Bun，则执行 `npm exec --yes --package=bun -- omp plugin install omp-figma-remote-auth@latest`。
|
|
47
|
-
5. 执行 `omp plugin list` 确认安装，再执行 `realpath /absolute/path/to/installed/plugin`。解析后的路径必须不同于已记录的源码目录路径；如果相同或无法解析，请停止。Registry 安装可以正常使用指向包缓存的符号链接；这本身不是错误，也不是解除链接的理由。
|
|
48
|
-
|
|
49
|
-
请将示例绝对路径替换为实际路径。迁移后重启 OMP 或运行 `/reload-plugins`。
|
|
50
|
-
|
|
51
|
-
以下是 **OMP 交互界面（TUI）中的斜杠命令**，不能直接在 shell 中运行。需要时先用 `omp` 启动 OMP，然后执行：
|
|
29
|
+
### 2. 登录：在 OMP 输入框执行
|
|
52
30
|
|
|
53
31
|
```text
|
|
54
|
-
/figma-remote-auth setup
|
|
55
32
|
/figma-remote-auth login
|
|
56
33
|
```
|
|
57
34
|
|
|
58
|
-
|
|
35
|
+
浏览器会自动打开。未打开时，点击编辑器上方的 **点击这里授权 Figma**，或复制完整短地址到浏览器。默认授权应用名称为 **Codex**，原因见[认证说明](#配置与认证说明)。
|
|
59
36
|
|
|
60
|
-
|
|
37
|
+
确认授权，等待 OMP 提示凭据已保存。
|
|
61
38
|
|
|
62
|
-
|
|
63
|
-
|
|
64
|
-
默认设置下，Figma 授权页显示的应用名称是 **Codex**，原因见下方认证机制说明。确认授权并保持 OMP 运行，浏览器会回调 `http://127.0.0.1:<port>/callback`。返回 OMP 确认凭据已保存；浏览器打开或收到授权码均不代表令牌交换已经成功。等待期间可重复点击入口；成功、失败、超时、取消或退出 OMP 后，入口和提示组件会关闭。
|
|
65
|
-
|
|
66
|
-
OMP 提示成功后，在 TUI 中执行：
|
|
39
|
+
### 3. 验证连接：在 OMP 输入框执行
|
|
67
40
|
|
|
68
41
|
```text
|
|
69
42
|
/mcp reload
|
|
70
43
|
/mcp test figma
|
|
71
44
|
```
|
|
72
45
|
|
|
73
|
-
|
|
46
|
+
服务名为 `figma`。连接成功后，即可向 OMP 提供你有权限访问的 Figma 文件或节点链接。
|
|
47
|
+
|
|
48
|
+
插件还内置按需加载的 `figma-mcp` skill。提供 Figma 文件或节点链接后，它会引导 OMP 解析节点参数并发现 Figma MCP 工具，包括挂载在 `xd://` 下的工具。
|
|
74
49
|
|
|
75
|
-
##
|
|
50
|
+
## 常用命令
|
|
76
51
|
|
|
77
|
-
|
|
52
|
+
以下均在 **OMP TUI** 中执行，不是终端命令。
|
|
78
53
|
|
|
79
54
|
| 命令 | 用途 |
|
|
80
55
|
| --- | --- |
|
|
81
|
-
| `/figma-remote-auth
|
|
82
|
-
| `/figma-remote-auth
|
|
83
|
-
| `/figma-remote-auth
|
|
84
|
-
| `/figma-remote-auth
|
|
85
|
-
| `/figma-remote-auth
|
|
86
|
-
| `/
|
|
56
|
+
| `/figma-remote-auth login` | 登录或重新授权，自动处理必要迁移。 |
|
|
57
|
+
| `/figma-remote-auth status` | 查看本地凭据，不测试连接。 |
|
|
58
|
+
| `/figma-remote-auth cancel` | 取消授权，关闭短入口和监听端口。 |
|
|
59
|
+
| `/figma-remote-auth logout` | 清除本插件的本地凭据，不撤销 Figma 端授权。 |
|
|
60
|
+
| `/figma-remote-auth help` | 查看完整用法。 |
|
|
61
|
+
| `/mcp list` | 查看 MCP 服务。 |
|
|
87
62
|
|
|
88
|
-
|
|
89
|
-
|
|
90
|
-
```text
|
|
91
|
-
/figma-remote-auth login --client-name Codex --port 19876
|
|
92
|
-
/figma-remote-auth login --no-browser
|
|
93
|
-
```
|
|
63
|
+
登录加 `--no-browser` 可手动打开短入口；`--port` 指定端口（默认随机），`--client-name` 修改应用名称（默认 `Codex`）。完整用法见 `help`。
|
|
94
64
|
|
|
95
|
-
|
|
65
|
+
授权最多等待 **10 分钟**。流程结束、取消或退出 OMP 后释放监听端口；关闭浏览器不会取消等待。
|
|
96
66
|
|
|
97
|
-
|
|
67
|
+
## 卸载
|
|
98
68
|
|
|
99
|
-
|
|
69
|
+
在终端执行，然后重启 OMP：
|
|
100
70
|
|
|
101
|
-
|
|
102
|
-
|
|
103
|
-
|
|
71
|
+
```sh
|
|
72
|
+
omp plugin uninstall omp-figma-remote-auth
|
|
73
|
+
```
|
|
104
74
|
|
|
105
|
-
|
|
75
|
+
卸载会移除包提供的 Figma 注册，保留凭据供重装使用，独立的用户/项目配置不受影响。
|
|
106
76
|
|
|
107
|
-
|
|
77
|
+
如需清除凭据，卸载前在 OMP 中执行 `/figma-remote-auth logout` 和 `/mcp reload`。撤销 Figma 服务器端授权需到账号设置中操作。
|
|
108
78
|
|
|
109
79
|
## 常见问题
|
|
110
80
|
|
|
111
|
-
|
|
112
|
-
|
|
113
|
-
|
|
114
|
-
|
|
115
|
-
-
|
|
116
|
-
|
|
117
|
-
|
|
118
|
-
|
|
119
|
-
安装或链接插件不会自动登录。卸载插件并重启 OMP 后，包提供的 `figma` MCP 注册项会随之移除，无需提前 logout，也无需手动从 `mcp.json` 中删除条目。凭据保留在 OMP 中，便于在同一 profile 下重新安装后复用。旧版安装应先完成上文的 setup 迁移，再依赖这一由包管理注册项的生命周期；自定义配置冲突仍需明确检查。
|
|
120
|
-
|
|
121
|
-
如需额外清理凭据，可在插件仍安装时，进入每个曾授权的 profile，执行 `/figma-remote-auth logout` 和 `/mcp reload`。Logout 仅删除属于本插件的本地原生 profile/URL 凭据及旧版 agent 目录凭据，保留注册项和其他认证来源的凭据，**不会撤销 Figma 服务器端授权**。如需撤销，请在 Figma 账号设置中移除对应应用的授权。
|
|
122
|
-
|
|
123
|
-
在终端执行卸载：
|
|
81
|
+
| 问题 | 处理方式 |
|
|
82
|
+
| --- | --- |
|
|
83
|
+
| 找不到插件命令 | 在终端用 `omp plugin list` 确认安装，再重启 OMP。 |
|
|
84
|
+
| MCP 未连接 | 确认完整插件包已安装，执行 `/mcp reload` 和 `/mcp test figma`。 |
|
|
85
|
+
| 回调失败或一直等待 | 取消后用 `/figma-remote-auth login --port 0` 重试。浏览器须能访问 OMP 所在机器的 `127.0.0.1`；SSH/容器不会自动配置端口转发。 |
|
|
86
|
+
| 配置或凭据冲突 | 检查提示路径，备份后再调整。插件不会覆盖自定义配置或其他来源的凭据。 |
|
|
87
|
+
| 认证失败 | 用 `/figma-remote-auth login` 重新登录，再 reload/test；`/mcp reauth figma` 不会调用本插件。 |
|
|
88
|
+
| 权限或额度不足 | 检查账号、文件权限及套餐，参见 [Figma 限额](https://developers.figma.com/docs/figma-mcp-server/rate-limits-access/)。 |
|
|
124
89
|
|
|
125
|
-
|
|
126
|
-
omp plugin uninstall omp-figma-remote-auth
|
|
127
|
-
```
|
|
90
|
+
## 配置与认证说明
|
|
128
91
|
|
|
129
|
-
|
|
92
|
+
- **配置与凭据：**包内 `.mcp.json` 提供 Figma 服务，新安装不写用户 MCP 配置。凭据由 OMP 保存和刷新；使用 profile 时，请在同一 profile 中登录。
|
|
93
|
+
- **授权应用名：**`Codex` 用于兼容 [Figma 客户端策略](https://developers.figma.com/docs/figma-mcp-server/rate-limits-access/#which-mcp-clients-are-supported)。每次登录注册独立客户端，不使用 Codex 的账号或凭据。
|
|
94
|
+
- **授权入口：**本机短链接转发完整 OAuth 请求，长授权 URL 和 token 不输出到终端。
|
|
130
95
|
|
|
131
|
-
##
|
|
96
|
+
## 许可证与致谢
|
|
132
97
|
|
|
133
|
-
|
|
98
|
+
[MIT](LICENSE)。改编自 [DianP/pi-figma-remote-auth](https://github.com/DianP/pi-figma-remote-auth)，其认证思路参考了 [sdaoudi/mcp-auth-helper](https://github.com/sdaoudi/mcp-auth-helper)。
|
|
134
99
|
|
|
135
|
-
|
|
100
|
+
源码安装与测试请参阅[开发指南](https://github.com/picasuo/omp-figma-remote-auth/blob/main/DEVELOPMENT.md#简体中文)。
|
package/index.ts
CHANGED
|
@@ -2,7 +2,7 @@ import { COMMAND_NAME, FIGMA_URL, UserError, formatError, helpText, parseArgs }
|
|
|
2
2
|
import { isAuthorizationEntry, openBrowser } from "./src/browser.ts";
|
|
3
3
|
import type { Exec } from "./src/browser.ts";
|
|
4
4
|
import { inspectLegacyConfig } from "./src/config.ts";
|
|
5
|
-
import {
|
|
5
|
+
import { migrateLegacyData } from "./src/migration.ts";
|
|
6
6
|
import { runOAuthFlow } from "./src/oauth.ts";
|
|
7
7
|
import type { FlowOptions, OAuthGrant } from "./src/oauth.ts";
|
|
8
8
|
import { legacyCredentialIdFor, nativeCredentialIdFor, resolveActiveProfile, credentialStatus, logout, saveCredential } from "./src/storage.ts";
|
|
@@ -87,7 +87,7 @@ export function registerExtension(pi: ExtensionAPI, dependencies: Dependencies =
|
|
|
87
87
|
`Figma Remote MCP: ${FIGMA_URL}`,
|
|
88
88
|
"Config: package-provided MCP definition; runtime discovery and connection are not checked here.",
|
|
89
89
|
"Install or link the full plugin package for MCP registration; loading index.ts alone is not an installation check.",
|
|
90
|
-
`Legacy config: ${config.kind === "owned" ? "migration pending" : config.kind === "conflict" ? `conflict at ${config.path}; resolve before
|
|
90
|
+
`Legacy config: ${config.kind === "owned" ? "migration pending; run /figma-remote-auth login" : config.kind === "conflict" ? `conflict at ${config.path}; resolve before login` : "absent"}.`,
|
|
91
91
|
credentialStatus(storage, credentialId),
|
|
92
92
|
`Authorization: ${active ? "operation in progress" : "idle"}.`,
|
|
93
93
|
].join("\n"), "info");
|
|
@@ -120,15 +120,8 @@ export function registerExtension(pi: ExtensionAPI, dependencies: Dependencies =
|
|
|
120
120
|
notify(`${removed ? "Removed this plugin's Figma credential." : "No credential owned by this plugin was found."} Run /mcp reload.`, "info");
|
|
121
121
|
return;
|
|
122
122
|
}
|
|
123
|
-
|
|
123
|
+
await migrateLegacyData(agentDir, storage, profile);
|
|
124
124
|
if (controller.signal.aborted) throw new UserError("Figma authorization cancelled.");
|
|
125
|
-
if (command.kind === "setup") {
|
|
126
|
-
if (migration.configRemoved || migration.credentialMigrated) {
|
|
127
|
-
notify("Legacy Figma setup migrated to native profile credentials and package-managed MCP registration.", "info");
|
|
128
|
-
}
|
|
129
|
-
notify("Figma MCP is managed by this plugin. Run /mcp reload.", "info");
|
|
130
|
-
return;
|
|
131
|
-
}
|
|
132
125
|
statusShown = true;
|
|
133
126
|
tryUI(() => ctx.ui.setStatus?.(COMMAND_NAME, "Waiting for Figma authorization"));
|
|
134
127
|
const grant = await (dependencies.runOAuth ?? runOAuthFlow)({
|
|
@@ -168,7 +161,7 @@ export function registerExtension(pi: ExtensionAPI, dependencies: Dependencies =
|
|
|
168
161
|
if (controller.signal.aborted) throw new UserError("Figma authorization cancelled.");
|
|
169
162
|
// Recheck the active profile, migration conflicts, and cancellation after the browser wait.
|
|
170
163
|
if (resolveActiveProfile() !== profile) throw new UserError("The active OMP profile changed during authorization; credentials were not saved.");
|
|
171
|
-
await
|
|
164
|
+
await migrateLegacyData(agentDir, storage, profile);
|
|
172
165
|
if (controller.signal.aborted) throw new UserError("Figma authorization cancelled.");
|
|
173
166
|
await saveCredential(storage, credentialId, grant);
|
|
174
167
|
notify("Figma authorization saved. Run /mcp reload.", "info");
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "omp-figma-remote-auth",
|
|
3
|
-
"version": "0.1.
|
|
3
|
+
"version": "0.1.5",
|
|
4
4
|
"description": "OAuth helper for Figma remote MCP using OMP native transport",
|
|
5
5
|
"type": "module",
|
|
6
6
|
"license": "MIT",
|
|
@@ -35,6 +35,7 @@
|
|
|
35
35
|
".mcp.json",
|
|
36
36
|
"index.ts",
|
|
37
37
|
"src",
|
|
38
|
+
"skills",
|
|
38
39
|
"LICENSE",
|
|
39
40
|
"README.md",
|
|
40
41
|
"README.zh-CN.md"
|
|
@@ -0,0 +1,59 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: figma-mcp
|
|
3
|
+
description: >
|
|
4
|
+
Use when the user provides a Figma design, file, page, or node URL or asks
|
|
5
|
+
to inspect, explain, screenshot, implement, or modify a Figma design. Use
|
|
6
|
+
the Figma MCP tools provided by this plugin, including tools mounted under
|
|
7
|
+
xd://.
|
|
8
|
+
---
|
|
9
|
+
|
|
10
|
+
# Figma MCP workflow
|
|
11
|
+
|
|
12
|
+
Use this skill whenever a user gives a Figma URL, file key, or node ID and asks for information about the design, a screenshot, design context, or implementation.
|
|
13
|
+
|
|
14
|
+
## 1. Parse the reference
|
|
15
|
+
|
|
16
|
+
For a URL such as `https://www.figma.com/design/<fileKey>/<name>?node-id=5077-10161`, extract:
|
|
17
|
+
|
|
18
|
+
- `fileKey`: the segment after `/design/`.
|
|
19
|
+
- `nodeId`: the `node-id` query value. Convert `-` to `:` before sending it to Figma MCP (`5077-10161` becomes `5077:10161`).
|
|
20
|
+
|
|
21
|
+
Treat the Figma URL as input data. It is not an `xd://` URL and must never be appended to an `xd://` path.
|
|
22
|
+
|
|
23
|
+
## 2. Discover the Figma MCP tool
|
|
24
|
+
|
|
25
|
+
Prefer the Figma MCP tool that matches the request:
|
|
26
|
+
|
|
27
|
+
- Implement or faithfully reproduce a design: `mcp__figma_get_design_context`.
|
|
28
|
+
- Inspect node structure, names, bounds, or children: `mcp__figma_get_metadata`.
|
|
29
|
+
- Get a rendered image when a screenshot is requested: use the available Figma screenshot/export tool.
|
|
30
|
+
|
|
31
|
+
If the tool is not visible in the top-level tool list, discover it before reporting that Figma MCP is unavailable:
|
|
32
|
+
|
|
33
|
+
```text
|
|
34
|
+
read xd://
|
|
35
|
+
read xd://mcp__figma_get_design_context
|
|
36
|
+
write xd://mcp__figma_get_design_context with the JSON arguments
|
|
37
|
+
```
|
|
38
|
+
|
|
39
|
+
Read `xd://` to find the exact mounted tool name. Read the selected tool path to obtain its current schema. Then call it by writing valid JSON arguments to that same `xd://` path. `xd://` is an OMP mounted-tool catalog, not a web proxy.
|
|
40
|
+
|
|
41
|
+
Do not try `xd://https://www.figma.com/...`. Do not stop after checking only top-level tools.
|
|
42
|
+
|
|
43
|
+
## 3. Use the Figma workflow guidance when available
|
|
44
|
+
|
|
45
|
+
For design-to-code requests, the Figma-provided workflow guidance can add implementation details. If the host exposes MCP resources, try the explicit MCP resource route:
|
|
46
|
+
|
|
47
|
+
```text
|
|
48
|
+
read mcp://skill://figma/figma-design-to-code/SKILL.md
|
|
49
|
+
```
|
|
50
|
+
|
|
51
|
+
Never use plain `skill://figma/...` for this resource: OMP may resolve that path through its local skill namespace and return `Unknown skill: figma`. This resource lookup is optional. If either route fails, continue with this skill's instructions and the successful Figma MCP call; do not report that Figma MCP is unavailable merely because a workflow document could not be read.
|
|
52
|
+
|
|
53
|
+
Adapt any retrieved reference code to the target project's actual stack and existing components. Do not let an auxiliary skill-resource error prevent metadata, screenshot, or design-context retrieval.
|
|
54
|
+
|
|
55
|
+
## 4. Report only observed results
|
|
56
|
+
|
|
57
|
+
Do not claim that a design was fetched, inspected, or implemented until the corresponding MCP call returns successfully. Preserve the user's file and node identifiers in follow-up calls, but do not expose access tokens, refresh tokens, client IDs, or long authorization URLs.
|
|
58
|
+
|
|
59
|
+
If discovery or a call fails, report the actual failure and the step that failed. Do not infer missing access from a tool that was never called.
|
package/src/args.ts
CHANGED
|
@@ -17,7 +17,7 @@ export function formatError(error: unknown): string {
|
|
|
17
17
|
}
|
|
18
18
|
|
|
19
19
|
export type Command =
|
|
20
|
-
| { kind: "help" | "
|
|
20
|
+
| { kind: "help" | "status" | "logout" | "cancel" }
|
|
21
21
|
| { kind: "login"; clientName: string; port: number; openBrowser: boolean };
|
|
22
22
|
|
|
23
23
|
/** Small shell-style tokenizer; no expansion, execution, or environment access. */
|
|
@@ -58,10 +58,10 @@ function tokenize(input: string): string[] {
|
|
|
58
58
|
export function parseArgs(input: string): Command {
|
|
59
59
|
const [kind = "help", ...args] = tokenize(input);
|
|
60
60
|
if (kind !== "login") {
|
|
61
|
-
if (!["help", "
|
|
61
|
+
if (!["help", "status", "logout", "cancel"].includes(kind) || args.length) {
|
|
62
62
|
throw new UserError("Invalid command or arguments. Use /figma-remote-auth help.");
|
|
63
63
|
}
|
|
64
|
-
return { kind: kind as "help" | "
|
|
64
|
+
return { kind: kind as "help" | "status" | "logout" | "cancel" };
|
|
65
65
|
}
|
|
66
66
|
let clientName = "Codex";
|
|
67
67
|
let port = 0;
|
|
@@ -96,17 +96,16 @@ export function parseArgs(input: string): Command {
|
|
|
96
96
|
export function helpText(): string {
|
|
97
97
|
return [
|
|
98
98
|
"/figma-remote-auth help",
|
|
99
|
-
"/figma-remote-auth setup",
|
|
100
99
|
"/figma-remote-auth login [--client-name Codex] [--port 0] [--no-browser]",
|
|
101
100
|
"/figma-remote-auth status",
|
|
102
101
|
"/figma-remote-auth logout",
|
|
103
102
|
"/figma-remote-auth cancel",
|
|
104
103
|
"",
|
|
105
104
|
`Server: ${SERVER_NAME} (${FIGMA_URL})`,
|
|
106
|
-
"Figma MCP is managed by this plugin.
|
|
105
|
+
"Figma MCP is managed by this plugin. Login migrates owned legacy configuration and credentials before authorization.",
|
|
107
106
|
"Login opens your browser in the interactive TUI and displays a highlighted local authorization entry.",
|
|
108
107
|
"Use --no-browser to open the short entry manually; RPC/print never open a browser automatically.",
|
|
109
108
|
"Use /figma-remote-auth cancel or exit OMP to stop waiting and close the local entry.",
|
|
110
|
-
"OMP handles MCP transport and token refresh. After
|
|
109
|
+
"OMP handles MCP transport and token refresh. After login or logout, run /mcp reload.",
|
|
111
110
|
].join("\n");
|
|
112
111
|
}
|
package/src/migration.ts
CHANGED
|
@@ -7,7 +7,7 @@ import type { AuthStorage } from "./storage.ts";
|
|
|
7
7
|
// AuthStorage has no compare-and-swap API. Prevent overlapping migrations in this process,
|
|
8
8
|
// including different agent directories that target the same native profile credential.
|
|
9
9
|
const migrating = new Set<string>();
|
|
10
|
-
export async function
|
|
10
|
+
export async function migrateLegacyData(
|
|
11
11
|
agentDir: string, storage: AuthStorage, profile: string | undefined,
|
|
12
12
|
): Promise<{ configRemoved: boolean; credentialMigrated: boolean }> {
|
|
13
13
|
const legacyId = legacyCredentialIdFor(agentDir);
|
|
@@ -37,7 +37,7 @@ export async function migrateLegacySetup(
|
|
|
37
37
|
const currentLegacy = ownedCredential(storage, legacyId);
|
|
38
38
|
const currentNative = ownedCredential(storage, nativeId);
|
|
39
39
|
if ((currentLegacy && JSON.stringify(currentLegacy)) !== legacySnapshot || (legacy && !currentNative)) {
|
|
40
|
-
throw new UserError("Figma credentials changed during migration; retry the command. The legacy
|
|
40
|
+
throw new UserError("Figma credentials changed during migration; retry the command. The legacy data was retained.");
|
|
41
41
|
}
|
|
42
42
|
// This re-reads under the config lock and refuses any newly conflicting entry.
|
|
43
43
|
// A successful copy can safely survive a removal failure for a subsequent retry.
|