omp-figma-remote-auth 0.1.1 → 0.1.2

package/.mcp.json

@@ -0,0 +1 @@
+{"mcpServers":{"figma":{"type":"http","url":"https://mcp.figma.com/mcp"}}}

package/README.md

@@ -7,19 +7,26 @@ An unofficial [Oh My Pi (OMP)](https://github.com/can1357/oh-my-pi) plugin for a
 ## Requirements
 
 - OMP **18.1.17 is the currently verified version**. Use 18.1.17+; compatibility with future releases is not guaranteed.
-- Git, 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.
+- 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.
 - 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.
+- 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.
 
 ## Install and connect
 
 Run this command in your **terminal (CLI)** to install from npm:
 
 ```sh
-omp install omp-figma-remote-auth
+omp plugin install omp-figma-remote-auth@latest
 ```
 
 Restart OMP, or enter `/reload-plugins` in an existing OMP session. No source checkout or separate `npm install -g` is required.
 
+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:
+
+```sh
+npm exec --yes --package=bun -- omp plugin install omp-figma-remote-auth@latest
+```
+
 To develop the plugin or install from source instead:
 
 ```sh
@@ -29,6 +36,18 @@ omp plugin link ./omp-figma-remote-auth
 
 For a source installation, keep the cloned directory in place: OMP links to it. Restart OMP or run `/reload-plugins` after linking.
 
+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`.
+
+To switch an existing development link to the registry package:
+
+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`).
+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.
+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.
+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.
+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.
+
+Replace the example absolute paths with your actual paths. Restart OMP or run `/reload-plugins` after migration.
+
 The following are **slash commands inside OMP's interactive interface (TUI)**, not shell commands. Start OMP with `omp` if needed, then run:
 
 ```text
@@ -36,9 +55,13 @@ The following are **slash commands inside OMP's interactive interface (TUI)**, n
 /figma-remote-auth login
 ```
 
-`setup` configures the server without logging in. It is optional here because `login` runs setup automatically.
+The package's `.mcp.json` provides the `figma` HTTP MCP server. A new installation writes no user `mcp.json`. `setup` checks for conflicts and migrates this plugin's exact legacy registration and owned credentials without logging in; `login` runs setup automatically.
+
+When upgrading from the legacy version, run `/figma-remote-auth setup` in each affected profile, then `/mcp reload` or restart OMP. Setup removes only the exact legacy `mcpServers.figma` entry from that profile's agent-directory `mcp.json` and migrates owned credentials to OMP's native profile/URL credential key. OMP may attempt its first MCP connection before setup runs, so the initial connection can still use the old registration or lack the migrated credentials. Reload or restart after migration to pick up the result.
 
-Open the displayed authorization URL manually in a browser on the same machine. 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. The browser receiving the code alone does not confirm that token exchange succeeded.
+In the interactive TUI, login opens your system browser automatically and keeps a bold **点击这里授权 Figma** (“Click here to authorize Figma”) link above the editor. If the browser does not open, click that link or copy its complete local URL into a browser on the same machine. The short `http://127.0.0.1:<port>/a/<random-token>` entry redirects to Figma with all OAuth parameters intact; the long authorization URL is never printed in the terminal. When terminal hyperlinks are unsupported or disabled, the complete short URL remains available to copy.
+
+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.
 
 After OMP confirms success, run these TUI commands:
 
@@ -56,43 +79,46 @@ All commands in this table run in the OMP TUI.
 | Command | Purpose |
 | --- | --- |
 | `/figma-remote-auth help` | Show usage; also the default with no subcommand. |
-| `/figma-remote-auth setup` | Add or merge the native `figma` HTTP MCP configuration. |
-| `/figma-remote-auth login` | Run setup, dynamically register a client, and display the browser authorization link. |
-| `/figma-remote-auth status` | Check local configuration, credential presence/expiry, and any active operation; this is not a live connection test. |
-| `/figma-remote-auth logout` | Delete only this plugin's credential for the active profile; keep the MCP configuration. |
+| `/figma-remote-auth setup` | Check conflicts and migrate the exact owned legacy registration/credentials to package-provided MCP and native credentials; create no user MCP configuration. |
+| `/figma-remote-auth login` | Run setup, dynamically register a client, open the browser, and display a highlighted local authorization entry. |
+| `/figma-remote-auth status` | Report package-provided MCP, legacy registration migration/conflict state, native credential presence/expiry, and any active operation; this is not a live connection test. |
+| `/figma-remote-auth logout` | Delete only locally owned native and legacy credentials for the active profile/agent directory; keep registration and do not revoke Figma authorization. |
 | `/figma-remote-auth cancel` | Cancel the pending authorization and close its callback listener. |
 
-`login` accepts `--client-name` (default `Codex`, 1–128 printable characters, not blank) and `--port` (default `0`, which lets the OS choose an available port; valid range 0–65535). For example:
+`login` accepts `--client-name` (default `Codex`, 1–128 printable characters, not blank), `--port` (default `0`, which lets the OS choose an available port; valid range 0–65535), and the value-free `--no-browser` flag to open the short entry manually. Flags can be mixed in any order; duplicates are rejected. RPC and print modes only provide the short URL and never automatically open a browser. For example:
 
 ```text
 /figma-remote-auth login --client-name Codex --port 19876
+/figma-remote-auth login --no-browser
 ```
 
 Quote names containing spaces. A different client name may be rejected by Figma. Login times out after 10 minutes; `cancel` or exiting OMP also stops the wait. Run `/mcp reload` after setup, login, or logout so OMP picks up the change.
 
+For SSH or container sessions, `--no-browser` avoids opening a browser on the remote host. The callback and short entry still require access to that host's loopback interface; the plugin does not set up public proxies or port forwarding. On an unsupported OMP version without the widget API, it reports the limitation and provides the complete short URL as plain text.
+
 ## Authentication, profiles, and limits
 
 Each login sends `client_name: Codex` by default to Figma's dynamic client registration endpoint and receives a **new `client_id`**. It then uses the OAuth authorization code flow with PKCE S256 and state validation. It does not reuse or steal an existing Codex client ID, secret, or account token. The display name does not make this an official Codex integration. This is a compatibility workaround for Figma's client acceptance policy; Figma may change registration rules or endpoints and stop accepting it. See Figma's [client access policy](https://developers.figma.com/docs/figma-mcp-server/rate-limits-access/#which-mcp-clients-are-supported).
 
-Setup writes to the **active OMP agent directory's `mcp.json`** (normally `~/.omp/agent/mcp.json`). With `omp --profile <name>`, perform setup, login, status, and logout in that same profile. Credential IDs are derived from the active agent directory and Figma endpoint, so authentication is not automatically shared between profiles. The plugin does not write project-local MCP configuration.
+The server registration comes from the package's **`.mcp.json`**, not a setup-created user configuration. With `omp --profile <name>`, perform setup, login, status, and logout in that same profile. OMP's native credential key is derived from the active profile and Figma endpoint (`mcp_oauth:profile:<profile>:https://mcp.figma.com/mcp`, using `default` for the default profile), so authentication is not automatically shared between profiles. The agent-directory-derived credential ID is used only for legacy migration and cleanup. The plugin does not write project-local MCP configuration.
 
-Access/refresh tokens and client registration data are saved through **OMP's native AuthStorage**. The `mcp.json` entry contains the server URL, transport type, and an OAuth `credentialId` reference, not the tokens. OMP handles subsequent token refresh.
+Access/refresh tokens and client registration data are saved through **OMP's native AuthStorage** under that profile/URL key. The package's `.mcp.json` declares the server URL and HTTP transport without tokens or a custom `credentialId` reference; OMP resolves the native credentials and handles subsequent token refresh. Setup copies an owned legacy credential only when no native credential exists, preserves an existing owned native credential, and removes the owned legacy credential after successful migration. Credentials managed by another authentication source are not overwritten.
 
 Figma's [official rate limits and access documentation](https://developers.figma.com/docs/figma-mcp-server/rate-limits-access/) currently gives Starter users **up to 20 calls per month for tools that read data from Figma**, with some tools exempt. Limits depend on plan and seat, can change, and do not replace file permissions. This plugin does not increase or bypass quotas.
 
 ## Troubleshooting
 
 - **Unknown slash command:** check `omp plugin list` in the terminal, then restart OMP or run `/reload-plugins`. Use `/figma-remote-auth ...` in the TUI; there is no `omp figma-remote-auth` CLI command. `/mcp ...` commands also belong in the TUI.
-- **Existing configuration conflict:** setup refuses to overwrite a conflicting `mcpServers.figma` entry. Back up the active agent directory's `mcp.json`, then inspect that entry for a different URL/type, an `Authorization` header, another `auth` source, or old transport/token options such as `command`, `args`, `env`, or `oauth`. If migrating, remove or rename the obsolete entry after reviewing it, then rerun setup/login. Preserve unrelated servers. Also check project MCP configurations if OMP still resolves a different `figma` server. A credential ownership conflict requires resolving the other authentication source; the plugin will not overwrite it.
-- **Browser callback fails or login stalls:** keep the browser and OMP on the same machine; a browser on your laptop cannot directly reach a remote SSH/container loopback listener. Check local port access, cancel the attempt, and retry with `--port 0` or an available fixed port. A failed login may leave setup in place without a saved credential.
+- **Existing configuration conflict:** setup automatically removes only this plugin's exact legacy `mcpServers.figma` entry: `type: "http"`, `url: "https://mcp.figma.com/mcp"`, and `auth` containing only `type: "oauth"` and this plugin's legacy `credentialId`, with no extra fields. Any custom or different entry requires explicit review. Back up the active agent directory's `mcp.json`, then inspect the entry for a different URL/type, an `Authorization` header, another `auth` source, extra fields, or old transport/token options such as `command`, `args`, `env`, or `oauth`. Remove or rename an obsolete entry only after reviewing it, then rerun setup/login and `/mcp reload` or restart OMP. Preserve unrelated servers. Also inspect independent project MCP configurations and sources loaded through `-e` or extension directories if OMP still resolves a different `figma` server; setup does not remove those sources. A credential ownership conflict requires resolving the other authentication source; the plugin will not overwrite it.
+- **Browser callback fails or login stalls:** keep the browser and OMP on the same machine; a browser on your laptop cannot directly reach a remote SSH/container loopback listener. Check local port access, cancel the attempt, and retry with `--port 0` or an available fixed port. A failed login may leave legacy migration complete without a newly saved credential.
 - **Authentication still fails:** run `/figma-remote-auth status`, log in again with `/figma-remote-auth login`, then `/mcp reload` and `/mcp test figma`. OMP's `/mcp reauth figma` is its own generic OAuth flow; it does **not** invoke this plugin's login or its client-name registration behavior.
 - **Permission or quota errors:** check the authorized Figma account, file access, plan, and seat against the official limits above; logging in again does not add quota.
 
 ## Logout and uninstall
 
-Installing or linking the plugin does not log you in. Uninstalling it does not automatically clear credentials or remove the `figma` MCP configuration.
+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.
 
-For credential cleanup, run `/figma-remote-auth logout` and `/mcp reload` in each profile you authorized **before uninstalling**. Logout deletes the local credential only; it does **not revoke the server-side authorization at Figma**. To revoke that authorization, remove the corresponding app authorization in your Figma account settings.
+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.
 
 Uninstall from the terminal:
 
@@ -100,7 +126,7 @@ Uninstall from the terminal:
 omp plugin uninstall omp-figma-remote-auth
 ```
 
-Restart OMP or run `/reload-plugins`. If you also want to remove the server, delete only its `mcpServers.figma` entry from the relevant `mcp.json` and run `/mcp reload`. You can delete the clone after unlinking/uninstalling it. If already uninstalled, link it again to use logout in the original profile.
+Restart OMP to stop loading the package's MCP registration. Independent project configuration or sources loaded through `-e` or extension directories can still contribute a `figma` server; uninstall does not remove them. Review those sources explicitly if you also want to remove their registrations. You can delete the clone after unlinking/uninstalling it. If already uninstalled and you want to clear retained credentials, reinstall or link the plugin again and run logout in the original profile.
 
 ## Development and credits
 

package/README.zh-CN.md

@@ -7,19 +7,26 @@
 ## 使用要求
 
 - **OMP 18.1.17 是目前验证过的版本**。建议使用 18.1.17+，但不保证未来版本兼容。
-- Git、拥有目标文件访问权限的 Figma 账号，以及与 OMP 运行在同一台机器上的浏览器，用于接收本地 OAuth 回调。无需 Figma 桌面客户端。
+- 拥有目标文件访问权限的 Figma 账号，以及与 OMP 运行在同一台机器上的浏览器，用于接收本地 OAuth 回调。无需 Figma 桌面客户端。仅源码安装需要 Git。
 - 零运行时包依赖，无需 `pi-mcp-adapter`、`npm install` 或构建。开发测试需要 Node.js 22.6.0+ 和 npm。
+- OMP 的 npm 安装功能要求 `PATH` 中有独立的 `bun` 命令。打包好的 OMP 可执行文件不一定附带它，请参阅 [Bun 安装说明](https://bun.com/docs/installation)。这是安装器的要求，不是插件的包依赖。
 
 ## 安装与连接
 
 在**终端（CLI）**中执行以下命令，从 npm 安装：
 
 ```sh
-omp install omp-figma-remote-auth
+omp plugin install omp-figma-remote-auth@latest
 ```
 
 重启 OMP，或在已有 OMP 会话中输入 `/reload-plugins`。无需克隆源码，也无需额外执行 `npm install -g`。
 
+如果 OMP 提示 `Executable not found in $PATH: "bun"`，请先安装 Bun。已有 Node.js/npm 时，也可临时提供 Bun 来执行安装：
+
+```sh
+npm exec --yes --package=bun -- omp plugin install omp-figma-remote-auth@latest
+```
+
 如需开发插件或从源码安装：
 
 ```sh
@@ -29,6 +36,18 @@ omp plugin link ./omp-figma-remote-auth
 
 源码安装需要保留克隆目录的位置，OMP 会链接到该目录。链接后重启 OMP 或运行 `/reload-plugins`。
 
+使用包内 MCP 注册需要安装或链接完整插件包。通过 `omp -e` 仅加载 `index.ts` 适合测试认证命令，不能替代插件安装。`/figma-remote-auth status` 成功只能确认本地凭据状态，不代表 OMP 已发现或连接 MCP 服务。正常使用时，安装插件后直接启动 `omp`，再执行 `/mcp reload` 和 `/mcp test figma`。
+
+从已有开发链接切换到 registry 包时：
+
+1. 使用 `realpath /absolute/path/to/omp-figma-remote-auth` 记录源码目录的规范路径，并记下 OMP plugins 目录（通常为 `~/.omp/plugins`）中的插件安装路径。
+2. 执行 `omp plugin uninstall omp-figma-remote-auth`，再执行 `omp plugin list`。确认列表中已不包含 `omp-figma-remote-auth`；如果仍存在，请停止。
+3. 如果插件安装路径仍存在，先检查它。只有确认它是残留符号链接，且其 `realpath` 等于已记录的源码目录路径时，才可以用 `unlink /absolute/path/to/installed/plugin` 仅移除该符号链接。绝不能递归删除目标目录。遇到任何其他目录或链接冲突（包括无法确认目标的链接），请停止并排查。
+4. 执行 `omp plugin install omp-figma-remote-auth@latest` 安装；如果 PATH 中没有 Bun，则执行 `npm exec --yes --package=bun -- omp plugin install omp-figma-remote-auth@latest`。
+5. 执行 `omp plugin list` 确认安装，再执行 `realpath /absolute/path/to/installed/plugin`。解析后的路径必须不同于已记录的源码目录路径；如果相同或无法解析，请停止。Registry 安装可以正常使用指向包缓存的符号链接；这本身不是错误，也不是解除链接的理由。
+
+请将示例绝对路径替换为实际路径。迁移后重启 OMP 或运行 `/reload-plugins`。
+
 以下是 **OMP 交互界面（TUI）中的斜杠命令**，不能直接在 shell 中运行。需要时先用 `omp` 启动 OMP，然后执行：
 
 ```text
@@ -36,9 +55,13 @@ omp plugin link ./omp-figma-remote-auth
 /figma-remote-auth login
 ```
 
-`setup` 只配置服务，不登录。此处可以省略，因为 `login` 会自动执行 setup。
+包内的 `.mcp.json` 提供 `figma` HTTP MCP 服务。全新安装不会写入用户 `mcp.json`。`setup` 检查冲突并迁移与本插件旧格式完全匹配的注册项及属于本插件的凭据，不执行登录；`login` 会自动执行 setup。
+
+从旧版升级时，请在每个受影响的 profile 中执行 `/figma-remote-auth setup`，然后执行 `/mcp reload` 或重启 OMP。Setup 仅从该 profile 的 agent 目录下的 `mcp.json` 中移除与本插件旧格式完全匹配的 `mcpServers.figma` 条目，并将属于本插件的凭据迁移到 OMP 原生的 profile/URL 凭据键。OMP 可能在 setup 执行前就尝试首次 MCP 连接，因此首次连接仍可能使用旧注册项，或尚未取得迁移后的凭据。迁移后需重新加载 MCP 或重启，使变更生效。
 
-在同一台机器的浏览器中手动打开输出的授权链接。默认设置下，Figma 授权页显示的应用名称是 **Codex**，原因见下方认证机制说明。确认授权并保持 OMP 运行，浏览器会回调 `http://127.0.0.1:<port>/callback`。返回 OMP 确认凭据已保存；浏览器收到授权码并不代表令牌交换已经成功。
+在交互 TUI 中，login 默认打开系统浏览器，并在编辑器上方保留加粗高亮的 **点击这里授权 Figma** 链接。浏览器未自动打开时，可点击该入口，或将完整短地址复制到同一台机器的浏览器中。`http://127.0.0.1:<port>/a/<随机标识>` 本机短入口会携带完整 OAuth 参数跳转到 Figma；终端不再输出原始长授权 URL。终端不支持或关闭超链接时，仍会显示完整短 URL 供复制。
+
+默认设置下，Figma 授权页显示的应用名称是 **Codex**，原因见下方认证机制说明。确认授权并保持 OMP 运行，浏览器会回调 `http://127.0.0.1:<port>/callback`。返回 OMP 确认凭据已保存；浏览器打开或收到授权码均不代表令牌交换已经成功。等待期间可重复点击入口；成功、失败、超时、取消或退出 OMP 后，入口和提示组件会关闭。
 
 OMP 提示成功后，在 TUI 中执行：
 
@@ -56,43 +79,46 @@ OMP 提示成功后，在 TUI 中执行：
 | 命令 | 用途 |
 | --- | --- |
 | `/figma-remote-auth help` | 查看帮助；不带子命令时也会显示帮助。 |
-| `/figma-remote-auth setup` | 添加或合并原生 `figma` HTTP MCP 配置。 |
-| `/figma-remote-auth login` | 自动 setup、动态注册客户端，并显示浏览器授权链接。 |
-| `/figma-remote-auth status` | 检查本地配置、凭据是否存在及到期时间、当前操作状态；不进行实际连接测试。 |
-| `/figma-remote-auth logout` | 仅删除当前 profile 中属于本插件的凭据，保留 MCP 配置。 |
+| `/figma-remote-auth setup` | 检查冲突，将完全匹配且属于本插件的旧注册项/凭据迁移为包内 MCP 注册和原生凭据；不创建用户 MCP 配置。 |
+| `/figma-remote-auth login` | 自动 setup、动态注册客户端、打开浏览器，并显示高亮本机授权入口。 |
+| `/figma-remote-auth status` | 显示包内 MCP 注册、旧注册项的待迁移/冲突状态、原生凭据是否存在及到期时间、当前操作状态；不进行实际连接测试。 |
+| `/figma-remote-auth logout` | 仅删除当前 profile/agent 目录中属于本插件的本地原生及旧版凭据；保留注册项，不撤销 Figma 授权。 |
 | `/figma-remote-auth cancel` | 取消正在等待的授权，关闭回调监听。 |
 
-`login` 支持 `--client-name`（默认 `Codex`，1–128 个可打印字符，不能全为空白）与 `--port`（默认 `0`，由操作系统选择可用端口；有效范围为 0–65535）。例如：
+`login` 支持 `--client-name`（默认 `Codex`，1–128 个可打印字符，不能全为空白）、`--port`（默认 `0`，由操作系统选择可用端口；有效范围为 0–65535）及无需取值的 `--no-browser` 旗标，用于手动打开短入口。选项可任意混排，重复选项会报错。RPC 和 print 模式仅提供短 URL，不会自动打开浏览器。例如：
 
 ```text
 /figma-remote-auth login --client-name Codex --port 19876
+/figma-remote-auth login --no-browser
 ```
 
 含空格的名称需加引号。Figma 可能拒绝其他客户端名称。登录会在 10 分钟后超时；执行 `cancel` 或退出 OMP 也会结束等待。setup、login 或 logout 后均应运行 `/mcp reload`，使 OMP 加载变更。
 
+通过 SSH 或容器运行时，可用 `--no-browser` 避免在远程主机打开浏览器。回调和短入口仍要求浏览器能够访问该主机的回环接口；插件不会自动建立公网代理或端口转发。如果 OMP 版本缺少 widget API，会提示宿主不受支持，并以纯文本提供完整短 URL。
+
 ## 认证机制、profile 与限额
 
 每次登录默认向 Figma 动态客户端注册端点发送 `client_name: Codex`，获取一个**新的 `client_id`**，再通过带 PKCE S256 和 state 校验的 OAuth 授权码流程登录。插件不会复用或偷用已有 Codex 的客户端 ID、密钥或账号令牌。显示名称也不代表这是官方 Codex 集成。这是针对 Figma 客户端准入策略的兼容方案；Figma 可能修改注册规则或端点，使其失效。参见 Figma 的[客户端访问策略](https://developers.figma.com/docs/figma-mcp-server/rate-limits-access/#which-mcp-clients-are-supported)。
 
-Setup 写入**当前 OMP agent 目录下的 `mcp.json`**（通常为 `~/.omp/agent/mcp.json`）。使用 `omp --profile <name>` 时，应在同一个 profile 中执行 setup、login、status 和 logout。凭据 ID 根据当前 agent 目录和 Figma 端点生成，因此各 profile 不会自动共享登录状态。插件不写入项目级 MCP 配置。
+服务注册来自包内的 **`.mcp.json`**，无需 setup 创建用户配置。使用 `omp --profile <name>` 时，应在同一个 profile 中执行 setup、login、status 和 logout。OMP 原生凭据键根据当前 profile 和 Figma 端点生成（`mcp_oauth:profile:<profile>:https://mcp.figma.com/mcp`，默认 profile 使用 `default`），因此各 profile 不会自动共享登录状态。根据 agent 目录生成的凭据 ID 仅用于旧版迁移和清理。插件不写入项目级 MCP 配置。
 
-访问令牌、刷新令牌及客户端注册信息通过 **OMP 原生 AuthStorage** 保存。`mcp.json` 中仅保存服务 URL、传输类型和 OAuth `credentialId` 引用，不保存令牌。后续令牌刷新由 OMP 处理。
+访问令牌、刷新令牌及客户端注册信息通过 **OMP 原生 AuthStorage** 保存在对应的 profile/URL 凭据键下。包内的 `.mcp.json` 声明服务 URL 和 HTTP 传输，不包含令牌或自定义 `credentialId` 引用；OMP 负责查找原生凭据并处理后续令牌刷新。Setup 仅在没有原生凭据时复制属于本插件的旧版凭据，保留已有且属于本插件的原生凭据，并在迁移成功后删除属于本插件的旧版凭据。由其他认证来源管理的凭据不会被覆盖。
 
 Figma 的[官方限额与访问说明](https://developers.figma.com/docs/figma-mcp-server/rate-limits-access/)目前规定：Starter 用户对**从 Figma 读取数据的工具，每月最多调用 20 次**，部分工具不计入该限额。额度取决于套餐和席位，可能变更，且不替代文件访问权限。本插件不会增加或绕过额度。
 
 ## 常见问题
 
 - **找不到斜杠命令：**在终端用 `omp plugin list` 检查插件，再重启 OMP 或运行 `/reload-plugins`。`/figma-remote-auth ...` 应在 TUI 中输入，不存在 `omp figma-remote-auth` CLI 命令。`/mcp ...` 同样属于 TUI 命令。
-- **已有配置冲突：**setup 不会覆盖有冲突的 `mcpServers.figma`。先备份当前 agent 目录的 `mcp.json`，检查该条目是否存在不同的 URL/type、`Authorization` 请求头、其他 `auth` 来源，或 `command`、`args`、`env`、`oauth` 等旧传输或令牌选项。迁移时，确认后删除或重命名旧条目，再执行 setup/login，保留其他服务。如果 OMP 仍加载了另一个 `figma` 服务，还需检查项目级 MCP 配置。若提示凭据归属冲突，应先解决其他认证来源的占用，插件不会覆盖它。
-- **浏览器回调失败或一直等待：**浏览器和 OMP 应运行在同一台机器上；笔记本浏览器无法直接连接远程 SSH 主机或容器的回环监听。检查本地端口访问，取消当前操作后用 `--port 0` 或一个可用的固定端口重试。登录失败后，setup 配置可能已写入，但凭据尚未保存。
+- **已有配置冲突：**setup 仅自动移除与本插件旧格式完全匹配的 `mcpServers.figma` 条目：`type: "http"`、`url: "https://mcp.figma.com/mcp"`，以及仅包含 `type: "oauth"` 和本插件旧版 `credentialId` 的 `auth`，不能有额外字段。任何自定义或不同的条目都需要明确检查。先备份当前 agent 目录的 `mcp.json`，检查该条目是否存在不同的 URL/type、`Authorization` 请求头、其他 `auth` 来源、额外字段，或 `command`、`args`、`env`、`oauth` 等旧传输或令牌选项。仅在检查确认后删除或重命名过时条目，再执行 setup/login，然后运行 `/mcp reload` 或重启 OMP，保留其他服务。如果 OMP 仍加载了另一个 `figma` 服务，还需检查独立的项目级 MCP 配置，以及通过 `-e` 或扩展目录加载的来源；setup 不会移除这些来源。若提示凭据归属冲突，应先解决其他认证来源的占用，插件不会覆盖它。
+- **浏览器回调失败或一直等待：**浏览器和 OMP 应运行在同一台机器上；笔记本浏览器无法直接连接远程 SSH 主机或容器的回环监听。检查本地端口访问，取消当前操作后用 `--port 0` 或一个可用的固定端口重试。登录失败时，旧版迁移可能已完成，但尚未保存新的凭据。
 - **仍然认证失败：**运行 `/figma-remote-auth status`，用 `/figma-remote-auth login` 重新登录，然后执行 `/mcp reload` 与 `/mcp test figma`。OMP 的 `/mcp reauth figma` 走其自身通用 OAuth 流程，**不会调用本插件的 login，也不会使用本插件的客户端名称注册逻辑**。
 - **权限或额度错误：**检查授权的 Figma 账号、文件权限、套餐和席位，并参照上方官方限额；重新登录不会增加额度。
 
 ## 退出登录与卸载
 
-安装或链接插件不会自动登录；卸载插件也不会自动清除凭据或删除 `figma` MCP 配置。
+安装或链接插件不会自动登录。卸载插件并重启 OMP 后，包提供的 `figma` MCP 注册项会随之移除，无需提前 logout，也无需手动从 `mcp.json` 中删除条目。凭据保留在 OMP 中，便于在同一 profile 下重新安装后复用。旧版安装应先完成上文的 setup 迁移，再依赖这一由包管理注册项的生命周期；自定义配置冲突仍需明确检查。
 
-如需清理凭据，请在**卸载前**进入每个曾授权的 profile，执行 `/figma-remote-auth logout` 和 `/mcp reload`。Logout 仅删除本地凭据，**不会撤销 Figma 服务器端授权**。如需撤销，请在 Figma 账号设置中移除对应应用的授权。
+如需额外清理凭据，可在插件仍安装时，进入每个曾授权的 profile，执行 `/figma-remote-auth logout` 和 `/mcp reload`。Logout 仅删除属于本插件的本地原生 profile/URL 凭据及旧版 agent 目录凭据，保留注册项和其他认证来源的凭据，**不会撤销 Figma 服务器端授权**。如需撤销，请在 Figma 账号设置中移除对应应用的授权。
 
 在终端执行卸载：
 
@@ -100,7 +126,7 @@ Figma 的[官方限额与访问说明](https://developers.figma.com/docs/figma-m
 omp plugin uninstall omp-figma-remote-auth
 ```
 
-重启 OMP 或运行 `/reload-plugins`。如需同时删除服务，仅从对应的 `mcp.json` 中删除 `mcpServers.figma` 条目，再运行 `/mcp reload`。解除链接或卸载后可以删除克隆目录。如果已经卸载，可重新链接插件，再进入原 profile 执行 logout。
+重启 OMP，使其停止加载包内的 MCP 注册项。独立的项目配置，以及通过 `-e` 或扩展目录加载的来源，仍可能提供 `figma` 服务；卸载不会移除这些来源。如需同时移除它们的注册项，请明确检查对应来源。解除链接或卸载后可以删除克隆目录。如果已经卸载且想清理保留的凭据，可重新安装或链接插件，再进入原 profile 执行 logout。
 
 ## 开发与致谢
 

package/index.ts

@@ -1,21 +1,32 @@
 import { COMMAND_NAME, FIGMA_URL, UserError, formatError, helpText, parseArgs } from "./src/args.ts";
-import { configStatus, setupConfig } from "./src/config.ts";
+import { isAuthorizationEntry, openBrowser } from "./src/browser.ts";
+import type { Exec } from "./src/browser.ts";
+import { inspectLegacyConfig } from "./src/config.ts";
+import { migrateLegacySetup } from "./src/migration.ts";
 import { runOAuthFlow } from "./src/oauth.ts";
 import type { FlowOptions, OAuthGrant } from "./src/oauth.ts";
-import { credentialIdFor, credentialStatus, logout, ownedCredential, saveCredential } from "./src/storage.ts";
+import { legacyCredentialIdFor, nativeCredentialIdFor, resolveActiveProfile, credentialStatus, logout, saveCredential } from "./src/storage.ts";
 import type { AuthStorage } from "./src/storage.ts";
 
 /** Minimal structural interface; OMP supplies all runtime services, no SDK dependency. */
 export interface CommandContext {
   signal?: AbortSignal;
+  mode?: string;
+  hasUI?: boolean;
   modelRegistry: { authStorage: AuthStorage };
   ui: {
     notify(message: string, level: "info" | "error"): void;
     setStatus?(key: string, message: string | undefined): void;
+    setWidget?(key: string, factory: (() => unknown) | undefined, options?: { placement: "aboveEditor" }): void;
   };
 }
 export interface ExtensionAPI {
-  pi: { getAgentDir(): string };
+  pi: {
+    getAgentDir(): string;
+    Markdown?: new (text: string, paddingX: number, paddingY: number, theme: unknown) => unknown;
+    getMarkdownTheme?: () => unknown;
+  };
+  exec?: Exec;
   registerCommand(name: string, command: {
     description: string;
     handler(args: string, ctx: CommandContext): Promise<void>;
@@ -24,9 +35,15 @@ export interface ExtensionAPI {
 }
 export interface Dependencies {
   runOAuth?: (options: FlowOptions) => Promise<OAuthGrant>;
+  platform?: NodeJS.Platform;
 }
 // One active mutation across extension instances in this process, including during a reload.
-let active: { controller: AbortController; done: Promise<void> } | undefined;
+let active: { controller: AbortController; done: Promise<void>; cleanup: () => void } | undefined;
+
+// Host UI failures must not interrupt cancellation, listener cleanup, or completion.
+function tryUI(action: () => void): void {
+  try { action(); } catch { /* The host may already be disposing its UI. */ }
+}
 
 export default function figmaRemoteAuthExtension(pi: ExtensionAPI): void {
   registerExtension(pi);
@@ -36,6 +53,7 @@ export function registerExtension(pi: ExtensionAPI, dependencies: Dependencies =
   pi.on("session_shutdown", async () => {
     shuttingDown = true;
     const pending = active;
+    pending?.cleanup();
     pending?.controller.abort();
     await pending?.done;
   });
@@ -45,25 +63,31 @@ export function registerExtension(pi: ExtensionAPI, dependencies: Dependencies =
       let finish: (() => void) | undefined;
       let cancel: (() => void) | undefined;
       let operation: typeof active;
+      const notify = (message: string, level: "info" | "error") => tryUI(() => ctx.ui.notify(message, level));
       try {
         const command = parseArgs(args);
-        if (command.kind === "help") { ctx.ui.notify(helpText(), "info"); return; }
+        if (command.kind === "help") { notify(helpText(), "info"); return; }
         if (command.kind === "cancel") {
           const pending = active;
+          pending?.cleanup();
           pending?.controller.abort();
           await pending?.done;
-          ctx.ui.notify(pending ? "Figma authorization cancelled." : "No Figma authorization is running.", "info");
+          notify(pending ? "Figma authorization cancelled." : "No Figma authorization is running.", "info");
           return;
         }
         if (shuttingDown) throw new UserError("OMP is shutting down; authentication is unavailable.");
         const agentDir = pi.pi.getAgentDir();
-        const credentialId = credentialIdFor(agentDir);
+        const profile = resolveActiveProfile();
+        const credentialId = nativeCredentialIdFor(profile);
+        const legacyId = legacyCredentialIdFor(agentDir);
         const storage = ctx.modelRegistry.authStorage;
         if (command.kind === "status") {
-          const config = configStatus(agentDir, credentialId);
+          const config = inspectLegacyConfig(agentDir, legacyId);
           ctx.ui.notify([
             `Figma Remote MCP: ${FIGMA_URL}`,
-            `Config: ${config.configured ? "configured" : "setup required"}.`,
+            "Config: package-provided MCP definition; runtime discovery and connection are not checked here.",
+            "Install or link the full plugin package for MCP registration; loading index.ts alone is not an installation check.",
+            `Legacy config: ${config.kind === "owned" ? "migration pending" : config.kind === "conflict" ? `conflict at ${config.path}; resolve before setup or login` : "absent"}.`,
             credentialStatus(storage, credentialId),
             `Authorization: ${active ? "operation in progress" : "idle"}.`,
           ].join("\n"), "info");
@@ -72,47 +96,94 @@ export function registerExtension(pi: ExtensionAPI, dependencies: Dependencies =
         if (active) throw new UserError("A Figma authentication operation is already running. Cancel it before starting another.");
         const controller = new AbortController();
         const done = new Promise<void>(resolve => { finish = resolve; });
-        operation = { controller, done };
+        let cleaned = false;
+        let widgetShown = false;
+        let statusShown = false;
+        let entryShown = false;
+        const current = {
+          controller, done,
+          cleanup: () => {
+            if (cleaned || active !== current) return;
+            cleaned = true;
+            if (widgetShown) tryUI(() => ctx.ui.setWidget?.(COMMAND_NAME, undefined));
+            if (statusShown && active === current) tryUI(() => ctx.ui.setStatus?.(COMMAND_NAME, undefined));
+          },
+        };
+        operation = current;
         active = operation;
-        cancel = () => controller.abort();
+        cancel = () => { current.cleanup(); controller.abort(); };
         ctx.signal?.addEventListener("abort", cancel, { once: true });
         if (ctx.signal?.aborted) cancel();
         if (controller.signal.aborted) throw new UserError("Figma authorization cancelled.");
         if (command.kind === "logout") {
-          const removed = await logout(storage, credentialId);
-          ctx.ui.notify(`${removed ? "Removed this plugin's Figma credential." : "No credential owned by this plugin was found."} Run /mcp reload.`, "info");
+          const removed = await logout(storage, credentialId, legacyId);
+          notify(`${removed ? "Removed this plugin's Figma credential." : "No credential owned by this plugin was found."} Run /mcp reload.`, "info");
           return;
         }
-        // Protect credential ownership before setup changes the configured auth source.
-        ownedCredential(storage, credentialId);
-        setupConfig(agentDir, credentialId);
+        const migration = await migrateLegacySetup(agentDir, storage, profile);
+        if (controller.signal.aborted) throw new UserError("Figma authorization cancelled.");
         if (command.kind === "setup") {
-          ctx.ui.notify("Figma MCP configured. Use /figma-remote-auth login to authorize, then run /mcp reload.", "info");
+          if (migration.configRemoved || migration.credentialMigrated) {
+            notify("Legacy Figma setup migrated to native profile credentials and package-managed MCP registration.", "info");
+          }
+          notify("Figma MCP is managed by this plugin. Run /mcp reload.", "info");
           return;
         }
-        ctx.ui.setStatus?.(COMMAND_NAME, "Waiting for Figma authorization");
+        statusShown = true;
+        tryUI(() => ctx.ui.setStatus?.(COMMAND_NAME, "Waiting for Figma authorization"));
         const grant = await (dependencies.runOAuth ?? runOAuthFlow)({
           clientName: command.clientName, port: command.port, signal: controller.signal,
-          onAuthorizationUrl: (url) => {
-            ctx.ui.notify(`Open this URL in your browser to authorize Figma:\n${url}\n\nReturn to OMP when finished. Use /figma-remote-auth cancel to stop waiting.`, "info");
+          onAuthorizationReady: async ({ startUrl, callbackUrl }) => {
+            if (controller.signal.aborted || cleaned || active !== current || entryShown) return;
+            if (!isAuthorizationEntry(startUrl, callbackUrl)) throw new UserError("Invalid local Figma authorization entry.");
+            entryShown = true;
+            const interactive = ctx.hasUI === true && ctx.mode === "tui";
+            const Markdown = pi.pi.Markdown;
+            const getMarkdownTheme = pi.pi.getMarkdownTheme;
+            let displayed = false;
+            if (interactive && ctx.ui.setWidget && Markdown && getMarkdownTheme) {
+              try {
+                widgetShown = true;
+                ctx.ui.setWidget(COMMAND_NAME, () => new Markdown(
+                  '**[点击这里授权 Figma](<' + startUrl + '>)**\n\n浏览器未自动打开时，点击上方入口。取消：/figma-remote-auth cancel',
+                  1, 0, getMarkdownTheme(),
+                ), { placement: "aboveEditor" });
+                displayed = true;
+              } catch { /* Fall back to the validated plain entry below. */ }
+            }
+            if (controller.signal.aborted || cleaned || active !== current) return;
+            if (!displayed) {
+              notify(`Open this local entry in your browser to authorize Figma:\n${startUrl}\n\nUse /figma-remote-auth cancel to stop waiting.`, "info");
+              if (interactive) notify("This host does not support the Figma authorization widget. Use the local entry above.", "info");
+            }
+            if (!interactive || !command.openBrowser || controller.signal.aborted || cleaned || active !== current) return;
+            const opened = pi.exec && await openBrowser(startUrl, pi.exec.bind(pi), {
+              platform: dependencies.platform ?? process.platform, signal: controller.signal,
+            });
+            if (!opened && !controller.signal.aborted && !cleaned && active === current) {
+              notify("The browser could not be opened automatically. Use the Figma authorization entry above; authorization is still waiting.", "info");
+            }
           },
         });
         if (controller.signal.aborted) throw new UserError("Figma authorization cancelled.");
-        // Recheck config and ownership after the browser wait before persisting credentials.
-        const config = configStatus(agentDir, credentialId);
-        if (!config.configured) throw new UserError("Figma configuration changed during authorization; credentials were not saved.");
+        // Recheck the active profile, migration conflicts, and cancellation after the browser wait.
+        if (resolveActiveProfile() !== profile) throw new UserError("The active OMP profile changed during authorization; credentials were not saved.");
+        await migrateLegacySetup(agentDir, storage, profile);
+        if (controller.signal.aborted) throw new UserError("Figma authorization cancelled.");
         await saveCredential(storage, credentialId, grant);
-        ctx.ui.notify("Figma authorization saved. Run /mcp reload.", "info");
+        notify("Figma authorization saved. Run /mcp reload.", "info");
       } catch (error) {
-        ctx.ui.notify(formatError(error), "error");
+        notify(formatError(error), "error");
       } finally {
-        if (cancel) ctx.signal?.removeEventListener("abort", cancel);
-        if (operation) {
-          operation.controller.abort();
-          if (active === operation) active = undefined;
-          // Resolve first: UI failures must never strand session_shutdown waiting for cleanup.
-          finish?.();
-          ctx.ui.setStatus?.(COMMAND_NAME, undefined);
+        try {
+          if (cancel) ctx.signal?.removeEventListener("abort", cancel);
+          if (operation && active === operation) operation.cleanup();
+        } finally {
+          if (operation) {
+            operation.controller.abort();
+            if (active === operation) active = undefined;
+            finish?.();
+          }
         }
       }
     },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "omp-figma-remote-auth",
-  "version": "0.1.1",
+  "version": "0.1.2",
   "description": "OAuth helper for Figma remote MCP using OMP native transport",
   "type": "module",
   "license": "MIT",
@@ -32,6 +32,7 @@
   "main": "./index.ts",
   "exports": "./index.ts",
   "files": [
+    ".mcp.json",
     "index.ts",
     "src",
     "LICENSE",

package/src/args.ts

@@ -18,7 +18,7 @@ export function formatError(error: unknown): string {
 
 export type Command =
   | { kind: "help" | "setup" | "status" | "logout" | "cancel" }
-  | { kind: "login"; clientName: string; port: number };
+  | { kind: "login"; clientName: string; port: number; openBrowser: boolean };
 
 /** Small shell-style tokenizer; no expansion, execution, or environment access. */
 function tokenize(input: string): string[] {
@@ -65,17 +65,19 @@ export function parseArgs(input: string): Command {
   }
   let clientName = "Codex";
   let port = 0;
+  let openBrowser = true;
   const seen = new Set<string>();
-  for (let i = 0; i < args.length; i += 2) {
-    const key = args[i];
-    const value = args[i + 1];
-    if (!key || !["--client-name", "--port"].includes(key) || seen.has(key)) {
+  for (let i = 0; i < args.length;) {
+    const key = args[i++];
+    if (!key || !["--client-name", "--port", "--no-browser"].includes(key) || seen.has(key)) {
       throw new UserError("Unknown or duplicate login option. Use /figma-remote-auth help.");
     }
+    seen.add(key);
+    if (key === "--no-browser") { openBrowser = false; continue; }
+    const value = args[i++];
     if (value === undefined || value.startsWith("--")) {
       throw new UserError("Login option requires a value.");
     }
-    seen.add(key);
     if (key === "--client-name") {
       if (!value.trim() || value.length > 128 || /[\x00-\x1f\x7f]/u.test(value)) {
         throw new UserError("Client name must contain 1–128 printable characters.");
@@ -88,21 +90,23 @@ export function parseArgs(input: string): Command {
       port = Number(value);
     }
   }
-  return { kind: "login", clientName, port };
+  return { kind: "login", clientName, port, openBrowser };
 }
 
 export function helpText(): string {
   return [
     "/figma-remote-auth help",
     "/figma-remote-auth setup",
-    "/figma-remote-auth login [--client-name Codex] [--port 0]",
+    "/figma-remote-auth login [--client-name Codex] [--port 0] [--no-browser]",
     "/figma-remote-auth status",
     "/figma-remote-auth logout",
     "/figma-remote-auth cancel",
     "",
     `Server: ${SERVER_NAME} (${FIGMA_URL})`,
-    "Setup uses the active OMP agent directory's mcp.json.",
-    "Login displays a link for you to open manually. Use /figma-remote-auth cancel or exit OMP to stop waiting.",
+    "Figma MCP is managed by this plugin. Setup migrates owned legacy configuration and credentials.",
+    "Login opens your browser in the interactive TUI and displays a highlighted local authorization entry.",
+    "Use --no-browser to open the short entry manually; RPC/print never open a browser automatically.",
+    "Use /figma-remote-auth cancel or exit OMP to stop waiting and close the local entry.",
     "OMP handles MCP transport and token refresh. After setup, login, or logout, run /mcp reload.",
   ].join("\n");
 }

package/src/browser.ts

@@ -0,0 +1,40 @@
+import { UserError } from "./args.ts";
+
+export type Exec = (
+  command: string, args: string[], options: { signal?: AbortSignal; timeout?: number; cwd?: string },
+) => Promise<{ stdout: string; stderr: string; code: number; killed: boolean }>;
+
+/** Accept only the canonical local entry; reject URL parser normalization and hidden suffixes. */
+export function isAuthorizationEntry(url: string, callbackUrl?: string): boolean {
+  const match = /^http:\/\/127\.0\.0\.1:([1-9][0-9]{0,4})\/a\/[A-Za-z0-9_-]{22}$/u.exec(url);
+  if (/[\x00-\x20\x7f]/u.test(url)) return false;
+  if (!match || Number(match[1]) > 65535) return false;
+  return callbackUrl === undefined || callbackUrl === `http://127.0.0.1:${match[1]}/callback`;
+}
+
+function checkCancelled(signal?: AbortSignal): void {
+  if (signal?.aborted) throw new UserError("Figma authorization cancelled.");
+}
+
+export async function openBrowser(
+  url: string, exec: Exec, options: { platform: NodeJS.Platform; signal?: AbortSignal },
+): Promise<boolean> {
+  checkCancelled(options.signal);
+  if (!isAuthorizationEntry(url)) return false;
+  let command: string;
+  let args: string[];
+  switch (options.platform) {
+    case "darwin": command = "open"; args = [url]; break;
+    case "linux": command = "xdg-open"; args = [url]; break;
+    case "win32": command = "rundll32.exe"; args = ["url.dll,FileProtocolHandler", url]; break;
+    default: return false;
+  }
+  try {
+    const result = await exec(command, args, { timeout: 5000, signal: options.signal });
+    checkCancelled(options.signal);
+    return result.code === 0 && !result.killed;
+  } catch {
+    checkCancelled(options.signal);
+    return false;
+  }
+}

package/src/config.ts

@@ -1,4 +1,4 @@
-import { constants, closeSync, existsSync, fsyncSync, lstatSync, mkdirSync, openSync, readFileSync, renameSync, unlinkSync, writeFileSync } from "node:fs";
+import { constants, closeSync, fstatSync, fsyncSync, lstatSync, openSync, readFileSync, renameSync, unlinkSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
 import { randomBytes } from "node:crypto";
 import { FIGMA_URL, UserError } from "./args.ts";
@@ -7,20 +7,26 @@ type JsonObject = Record<string, unknown>;
 function record(value: unknown): value is JsonObject {
   return !!value && typeof value === "object" && !Array.isArray(value);
 }
-export interface ConfigState { configured: boolean; path: string }
+export interface LegacyConfigState { kind: "absent" | "owned" | "conflict"; path: string }
 
-/** Newly created private directories use 0700; normal ancestor links (macOS /tmp) are allowed. */
-function privateDirectory(path: string): void {
-  mkdirSync(path, { recursive: true, mode: 0o700 });
-  const info = lstatSync(path);
-  if (!info.isDirectory() || info.isSymbolicLink()) {
-    throw new UserError("OMP config directory must be a real directory, not a symlink.");
+/** Do not create anything; normal ancestor links (macOS /tmp) are allowed. */
+function checkDirectory(path: string): void {
+  try {
+    const info = lstatSync(path);
+    if (!info.isDirectory() || info.isSymbolicLink()) {
+      throw new UserError("OMP config directory must be a real directory, not a symlink.");
+    }
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === "ENOENT") return;
+    if (error instanceof UserError) throw error;
+    throw new UserError("Unable to inspect the OMP config directory safely; it was not changed.");
   }
 }
 function readConfig(path: string): { raw?: string; config: JsonObject } {
   let fd: number | undefined;
   try {
-    fd = openSync(path, constants.O_RDONLY | constants.O_NOFOLLOW);
+    fd = openSync(path, constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK);
+    if (!fstatSync(fd).isFile()) throw new UserError("OMP mcp.json must be a regular file; it was not changed.");
     const raw = readFileSync(fd, "utf8");
     let config: unknown;
     try { config = JSON.parse(raw); }
@@ -36,58 +42,37 @@ function readConfig(path: string): { raw?: string; config: JsonObject } {
   }
 }
 
-/** Validate before mutation, preserving all unrelated JSON fields and servers. */
-export function mergeConfig(config: JsonObject, credentialId: string): JsonObject {
+function classify(config: JsonObject, legacyId: string): LegacyConfigState["kind"] {
+  if (!Object.hasOwn(config, "mcpServers")) return "absent";
   const servers = config.mcpServers;
-  if (servers !== undefined && !record(servers)) {
-    throw new UserError("mcpServers must be an object; mcp.json was not changed.");
-  }
-  const entries = servers ?? {};
-  const existing = entries.figma;
-  if (Object.hasOwn(entries, "figma")) {
-    if (!record(existing) || existing.url !== FIGMA_URL || existing.type !== "http") {
-      throw new UserError("Existing figma endpoint/type conflicts with official Figma HTTP MCP; mcp.json was not changed.");
-    }
-    if (existing.headers !== undefined) {
-      if (!record(existing.headers) || Object.keys(existing.headers).some(key => key.toLowerCase() === "authorization")) {
-        throw new UserError("Existing figma headers conflict with OAuth; mcp.json was not changed.");
-      }
-    }
-    if (Object.hasOwn(existing, "auth")) {
-      const auth = existing.auth;
-      if (!record(auth) || auth.type !== "oauth" || auth.credentialId !== credentialId ||
-          Object.keys(auth).some(key => !["type", "credentialId"].includes(key))) {
-        throw new UserError("Existing figma auth belongs to another source or has conflicting options; mcp.json was not changed.");
-      }
-    }
-    // Do not silently combine a URL transport with alternate endpoint/credential settings.
-    if (["endpoint", "command", "args", "env", "apiKey", "token", "bearerToken", "oauth"].some(key => Object.hasOwn(existing, key))) {
-      throw new UserError("Existing figma transport or credential options conflict; mcp.json was not changed.");
-    }
+  if (!record(servers)) throw new UserError("mcpServers must be an object; mcp.json was not changed.");
+  if (!Object.hasOwn(servers, "figma")) return "absent";
+  const figma = servers.figma;
+  if (!record(figma) || Object.keys(figma).length !== 3 ||
+      !Object.hasOwn(figma, "type") || figma.type !== "http" ||
+      !Object.hasOwn(figma, "url") || figma.url !== FIGMA_URL ||
+      !Object.hasOwn(figma, "auth") || !record(figma.auth)) return "conflict";
+  const auth = figma.auth;
+  return Object.keys(auth).length === 2 && Object.hasOwn(auth, "type") && auth.type === "oauth" &&
+    Object.hasOwn(auth, "credentialId") && auth.credentialId === legacyId ? "owned" : "conflict";
+}
+function requireRemovable(kind: LegacyConfigState["kind"], path: string): void {
+  if (kind === "conflict") {
+    throw new UserError(`Existing figma configuration in ${path} is not the exact legacy entry owned by this plugin. Resolve that configuration before retrying; it was not changed.`);
   }
-  return {
-    ...config,
-    mcpServers: {
-      ...entries,
-      figma: { ...(record(existing) ? existing : {}), type: "http", url: FIGMA_URL, auth: { type: "oauth", credentialId } },
-    },
-  };
 }
-
-export function configStatus(agentDir: string, credentialId: string): ConfigState {
+export function inspectLegacyConfig(agentDir: string, legacyId: string): LegacyConfigState {
+  checkDirectory(agentDir);
   const path = join(agentDir, "mcp.json");
-  const { config } = readConfig(path);
-  mergeConfig(config, credentialId); // Status reports conflicts without revealing values.
-  const servers = record(config.mcpServers) ? config.mcpServers : {};
-  const figma = record(servers.figma) ? servers.figma : {};
-  const auth = record(figma.auth) ? figma.auth : {};
-  return { configured: auth.credentialId === credentialId, path };
+  return { kind: classify(readConfig(path).config, legacyId), path };
 }
 
-/** Synchronous lock/read/merge/rename keeps local operations in one uninterrupted turn. */
-export function setupConfig(agentDir: string, credentialId: string): string {
-  privateDirectory(agentDir);
-  const path = join(agentDir, "mcp.json");
+/** Only delete the exact owned legacy entry, preserving the file and every unrelated field. */
+export function removeLegacyConfig(agentDir: string, legacyId: string): boolean {
+  const state = inspectLegacyConfig(agentDir, legacyId);
+  requireRemovable(state.kind, state.path);
+  if (state.kind === "absent") return false; // No lock, directory, or file writes when absent.
+  const path = state.path;
   const lockPath = join(agentDir, ".figma-remote-auth-config.lock");
   let lock: number;
   try { lock = openSync(lockPath, constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL | constants.O_NOFOLLOW, 0o600); }
@@ -95,28 +80,36 @@ export function setupConfig(agentDir: string, credentialId: string): string {
   let temporary: string | undefined;
   let file: number | undefined;
   try {
+    checkDirectory(agentDir);
     const { raw, config } = readConfig(path);
-    const merged = mergeConfig(config, credentialId);
-    if (JSON.stringify(config) === JSON.stringify(merged)) return path;
-    temporary = join(agentDir, `.mcp.json.${randomBytes(16).toString("hex")}.tmp`);
-    file = openSync(temporary, constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL | constants.O_NOFOLLOW, 0o600);
-    writeFileSync(file, `${JSON.stringify(merged, null, 2)}\n`, "utf8");
+    const kind = classify(config, legacyId);
+    requireRemovable(kind, path);
+    if (kind === "absent") return false;
+    const servers = { ...(config.mcpServers as JsonObject) };
+    delete servers.figma;
+    const remaining = { ...config, mcpServers: servers };
+    const candidate = join(agentDir, `.mcp.json.${randomBytes(16).toString("hex")}.tmp`);
+    file = openSync(candidate, constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL | constants.O_NOFOLLOW, 0o600);
+    temporary = candidate;
+    writeFileSync(file, `${JSON.stringify(remaining, null, 2)}\n`, "utf8");
     fsyncSync(file);
     closeSync(file);
     file = undefined;
-    if (readConfig(path).raw !== raw) throw new UserError("mcp.json changed during setup; retry the command.");
+    if (readConfig(path).raw !== raw) throw new UserError("mcp.json changed during migration; retry the command.");
     renameSync(temporary, path);
     temporary = undefined;
-    const directory = openSync(agentDir, constants.O_RDONLY);
+    const directory = openSync(agentDir, constants.O_RDONLY | constants.O_NOFOLLOW);
     try { fsyncSync(directory); } finally { closeSync(directory); }
-    return path;
+    return true;
   } catch (error) {
     if (error instanceof UserError) throw error;
-    throw new UserError("Unable to write OMP mcp.json atomically.");
+    throw new UserError("Unable to remove the legacy Figma configuration atomically; retry the command.");
   } finally {
     if (file !== undefined) closeSync(file);
-    if (temporary && existsSync(temporary)) unlinkSync(temporary);
-    closeSync(lock);
-    unlinkSync(lockPath);
+    try {
+      if (temporary !== undefined) unlinkSync(temporary);
+    } finally {
+      try { closeSync(lock); } finally { unlinkSync(lockPath); }
+    }
   }
 }

package/src/migration.ts

@@ -0,0 +1,51 @@
+import { resolve } from "node:path";
+import { UserError } from "./args.ts";
+import { inspectLegacyConfig, removeLegacyConfig } from "./config.ts";
+import { legacyCredentialIdFor, nativeCredentialIdFor, ownedCredential, saveCredential } from "./storage.ts";
+import type { AuthStorage } from "./storage.ts";
+
+// AuthStorage has no compare-and-swap API. Prevent overlapping migrations in this process,
+// including different agent directories that target the same native profile credential.
+const migrating = new Set<string>();
+export async function migrateLegacySetup(
+  agentDir: string, storage: AuthStorage, profile: string | undefined,
+): Promise<{ configRemoved: boolean; credentialMigrated: boolean }> {
+  const legacyId = legacyCredentialIdFor(agentDir);
+  const nativeId = nativeCredentialIdFor(profile);
+  const directoryKey = `directory:${resolve(agentDir)}`;
+  if (migrating.has(directoryKey) || migrating.has(nativeId)) {
+    throw new UserError("A Figma migration is already running. Retry after it finishes.");
+  }
+  migrating.add(directoryKey);
+  migrating.add(nativeId);
+  try {
+    // Complete the read-only preflight before copying or removing anything.
+    const config = inspectLegacyConfig(agentDir, legacyId);
+    const legacy = ownedCredential(storage, legacyId);
+    const native = ownedCredential(storage, nativeId);
+    if (config.kind === "conflict") {
+      throw new UserError(`Existing figma configuration in ${config.path} is not the exact legacy entry owned by this plugin. Resolve that configuration before retrying; nothing was migrated.`);
+    }
+    const legacySnapshot = legacy && JSON.stringify(legacy);
+    let credentialMigrated = false;
+    if (legacy && !native) {
+      await saveCredential(storage, nativeId, { ...legacy });
+      credentialMigrated = true;
+    }
+    // Saving can yield to another writer. Refuse newly foreign or changed legacy data,
+    // and never remove the old path unless an owned native credential now exists.
+    const currentLegacy = ownedCredential(storage, legacyId);
+    const currentNative = ownedCredential(storage, nativeId);
+    if ((currentLegacy && JSON.stringify(currentLegacy)) !== legacySnapshot || (legacy && !currentNative)) {
+      throw new UserError("Figma credentials changed during migration; retry the command. The legacy setup was retained.");
+    }
+    // This re-reads under the config lock and refuses any newly conflicting entry.
+    // A successful copy can safely survive a removal failure for a subsequent retry.
+    const configRemoved = removeLegacyConfig(agentDir, legacyId);
+    if (legacy) await storage.remove(legacyId);
+    return { configRemoved, credentialMigrated };
+  } finally {
+    migrating.delete(directoryKey);
+    migrating.delete(nativeId);
+  }
+}

package/src/oauth.ts

@@ -33,7 +33,7 @@ export interface FlowOptions {
   clientName: string;
   port: number;
   signal?: AbortSignal;
-  onAuthorizationUrl: (url: string, callbackUrl: string) => void | Promise<void>;
+  onAuthorizationReady: (entry: { startUrl: string; callbackUrl: string }) => void | Promise<void>;
   /** Test seams only. No CLI option can change the remote URLs. */
   fetch?: FetchLike;
   timeoutMs?: number;
@@ -188,6 +188,7 @@ export async function exchangeCode(
 
 export interface CallbackListener {
   callbackUrl: string;
+  setAuthorizationUrl(url: string): string;
   result: Promise<string>;
   close: () => Promise<void>;
 }
@@ -197,6 +198,10 @@ export async function listenForCallback(port: number, state: string, signal: Abo
   let rejectCode!: (error: unknown) => void;
   let settled = false;
   let closing: Promise<void> | undefined;
+  const entryPath = `/a/${randomBytes(16).toString("base64url")}`;
+  let authorizationUrl: string | undefined;
+  let callbackUrl = "";
+  let expectedHost = "";
   const result = new Promise<string>((resolve, reject) => { resolveCode = resolve; rejectCode = reject; });
   // Discovery/DCR can fail before the caller awaits result. Observe rejection immediately.
   void result.catch(() => {});
@@ -228,8 +233,17 @@ export async function listenForCallback(port: number, state: string, signal: Abo
       res.end(text);
     };
     if (settled) { reply(410, "Authorization already completed."); return; }
+    if (req.headers.host !== expectedHost) { reply(400, "Invalid local Host."); return; }
     if (req.method !== "GET") { reply(405, "GET required."); return; }
     if (!req.url?.startsWith("/") || req.url.startsWith("//")) { reply(400, "Bad callback."); return; }
+    if (req.url === entryPath && authorizationUrl) {
+      res.writeHead(302, {
+        Location: authorizationUrl, "Cache-Control": "no-store",
+        "Referrer-Policy": "no-referrer", Connection: "close",
+      });
+      res.end();
+      return;
+    }
     let url: URL;
     try { url = new URL(req.url, "http://127.0.0.1"); }
     catch { reply(400, "Bad callback."); return; }
@@ -276,7 +290,33 @@ export async function listenForCallback(port: number, state: string, signal: Abo
     if (!address || typeof address === "string") throw new UserError("OAuth callback listener has no port.");
     signal.addEventListener("abort", onAbort, { once: true });
     if (signal.aborted) { onAbort(); aborted(signal); }
-    return { callbackUrl: `http://127.0.0.1:${address.port}${CALLBACK_PATH}`, result, close };
+    expectedHost = `127.0.0.1:${address.port}`;
+    callbackUrl = `http://${expectedHost}${CALLBACK_PATH}`;
+    return {
+      callbackUrl, result, close,
+      setAuthorizationUrl(value: string): string {
+        if (authorizationUrl !== undefined || settled || closing) {
+          throw new UserError("Figma authorization entry is already bound or closed.");
+        }
+        let target: URL;
+        try { target = new URL(value); }
+        catch { throw new UserError("Invalid Figma authorization target."); }
+        const required: Record<string, string | undefined> = {
+          response_type: "code", client_id: undefined, redirect_uri: callbackUrl,
+          state, code_challenge: undefined, code_challenge_method: "S256",
+        };
+        if (/[\x00-\x20\x7f]/u.test(value) || target.origin + target.pathname !== ENDPOINTS.authorizationUrl ||
+            target.username || target.password || target.hash || value.includes("#") ||
+            Object.entries(required).some(([key, expected]) => {
+              const values = target.searchParams.getAll(key);
+              return values.length !== 1 || !values[0]?.trim() || (expected !== undefined && values[0] !== expected);
+            })) {
+          throw new UserError("Invalid Figma authorization target.");
+        }
+        authorizationUrl = value;
+        return `http://${expectedHost}${entryPath}`;
+      },
+    };
   } catch (error) {
     await close();
     throw error;
@@ -308,7 +348,8 @@ export async function runOAuthFlow(options: FlowOptions): Promise<OAuthGrant> {
       code_challenge: challenge, code_challenge_method: "S256", state,
     }).toString();
     aborted(controller.signal);
-    await abortable(Promise.resolve(options.onAuthorizationUrl(url.href, listener.callbackUrl)), controller.signal);
+    const startUrl = listener.setAuthorizationUrl(url.href);
+    await abortable(Promise.resolve(options.onAuthorizationReady({ startUrl, callbackUrl: listener.callbackUrl })), controller.signal);
     const code = await listener.result;
     aborted(controller.signal);
     const grant = await exchangeCode(fetcher, client, listener.callbackUrl, code, verifier, controller.signal, options.now);

package/src/storage.ts

@@ -15,17 +15,32 @@ export interface AuthStorage {
   set(provider: string, credential: Credential): Promise<void>;
   remove(provider: string): Promise<void>;
 }
-export function credentialIdFor(agentDir: string): string {
+export function legacyCredentialIdFor(agentDir: string): string {
   return `mcp_oauth_omp_figma_${createHash("sha256").update(`${agentDir}\n${FIGMA_URL}`).digest("hex").slice(0, 24)}`;
 }
+export function nativeCredentialIdFor(profile: string | undefined): string {
+  return `mcp_oauth:profile:${profile ?? "default"}:${FIGMA_URL}`;
+}
+export function resolveActiveProfile(env: Record<string, string | undefined> = process.env): string | undefined {
+  const profile = (env.OMP_PROFILE !== undefined ? env.OMP_PROFILE : env.PI_PROFILE)?.trim();
+  if (!profile || profile === "default") return undefined;
+  if (!/^[a-z0-9][a-z0-9._-]{0,63}$/u.test(profile) || profile.endsWith(".") ||
+      /^(?:con|prn|aux|nul|com[0-9]|lpt[0-9])(?:\.|$)/u.test(profile)) {
+    throw new UserError("Invalid OMP profile name. Resolve the profile environment setting before retrying.");
+  }
+  return profile;
+}
+function isOwnedCredential(value: unknown, credentialId: string): value is Credential {
+  return !!value && typeof value === "object" && !Array.isArray(value) &&
+    (value as Partial<Credential>).type === "oauth" &&
+    (value as Partial<Credential>).figmaRemoteAuthOwner === OWNER &&
+    (value as Partial<Credential>).figmaRemoteAuthCredentialId === credentialId;
+}
 export function ownedCredential(storage: AuthStorage, credentialId: string): Credential | undefined {
   const value = storage.get(credentialId);
   if (value === undefined || value === null) return undefined;
-  if (typeof value !== "object" || Array.isArray(value) ||
-      (value as Partial<Credential>).type !== "oauth" ||
-      (value as Partial<Credential>).figmaRemoteAuthOwner !== OWNER ||
-      (value as Partial<Credential>).figmaRemoteAuthCredentialId !== credentialId) {
-    throw new UserError("The Figma credential ID is occupied by another authentication source. It was not changed.");
+  if (!isOwnedCredential(value, credentialId)) {
+    throw new UserError("The Figma credential ID is occupied by another authentication source. Resolve that source before retrying; it was not changed.");
   }
   return value as Credential;
 }
@@ -41,14 +56,21 @@ export async function saveCredential(storage: AuthStorage, credentialId: string,
     ...grant, type: "oauth", figmaRemoteAuthOwner: OWNER, figmaRemoteAuthCredentialId: credentialId,
   });
 }
-export async function logout(storage: AuthStorage, credentialId: string): Promise<boolean> {
-  if (!ownedCredential(storage, credentialId)) return false;
-  await storage.remove(credentialId);
-  return true;
+export async function logout(storage: AuthStorage, nativeId: string, legacyId: string): Promise<boolean> {
+  // Inspect both keys before the first deletion, then recheck after any asynchronous removal.
+  const ids = [...new Set([nativeId, legacyId])].filter(id => isOwnedCredential(storage.get(id), id));
+  let removed = false;
+  for (const id of ids) {
+    if (!isOwnedCredential(storage.get(id), id)) continue;
+    await storage.remove(id);
+    removed = true;
+  }
+  return removed;
 }
 export function credentialStatus(storage: AuthStorage, credentialId: string, now = Date.now()): string {
-  const credential = ownedCredential(storage, credentialId);
-  if (!credential) return "Credential: not logged in.";
+  const credential = storage.get(credentialId);
+  if (credential === undefined || credential === null) return "Credential: not logged in.";
+  if (!isOwnedCredential(credential, credentialId)) return "Credential: managed by another authentication source.";
   const expiry = credential.expires;
   if (!Number.isSafeInteger(expiry) || expiry <= 0 || expiry > 8.64e15) {
     return "Credential: present, but expiration metadata is invalid; log in again.";