# Pi：Figma Remote MCP（`pi-figma-remote-auth`）

> 本文件为 **@suwenguang/pi-kb 自有口径**。本包已 bundled [`pi-figma-remote-auth`](https://www.npmjs.com/package/pi-figma-remote-auth)，配合已 bundled 的 `pi-mcp-adapter`，在 Pi 内配置并 OAuth 登录 Figma Remote MCP（`https://mcp.figma.com/mcp`）。由 SKILL.md「Figma Remote MCP」一节引用。

## 1. 能力边界

| 项 | 说明 |
|----|------|
| 扩展命令 | `/figma-remote-auth`（setup / login / status / logout / help） |
| Token 同步 | `/figma-oauth-sync`（本包扩展）；`session_start` 若已有明文 token 则自动导入适配器密钥环 |
| 用途 | 写入 `mcpServers.figma`（`auth: "oauth"`）并把 OAuth token 写入社区包明文路径，再 **sync** 进 `pi-mcp-adapter` |
| 不替代 | 本地 Figma Desktop MCP 桥；KB 提案阶段的「有无设计图」产品闸门仍按 `/kb-propose` |
| 依赖 | 本包已 bundled `pi-mcp-adapter`；无需再单独装 adapter |
| 环境 | 扩展声明 Node.js ≥ 22.6（与 Cursor 路径类似，建议业务机用较新 Node） |

**为何需要 sync（不是 login 就够）**

| 存储 | 路径 / 位置 | 谁写 |
|------|-------------|------|
| 社区包明文 | `~/.pi/agent/mcp-oauth/figma/tokens.json` | `/figma-remote-auth login` |
| 适配器遗留 | `~/.pi/agent/mcp-oauth/sha256-<hash>/tokens.json` | `/figma-oauth-sync` |
| 适配器正式 | OS 密钥环 `pi-mcp-adapter.oauth` / `sha256-...` | `/figma-oauth-sync` |

只 login、不 sync 时，`/mcp` 常仍显示 figma **needs auth**。本包扩展在有明文 token 时于 `session_start` 自动 sync；也可手动 `/figma-oauth-sync`。

**与 KB Figma 闸门的分工**

1. **产品闸门**（`/kb-propose`）：用户确认有无设计图 → `external.figma_confirmed` / 可选 `figma_url`  
2. **工程能力**（本扩展）：Pi 里真能调 Figma MCP 工具读帧/组件时，先 `setup` + `login`（+ sync）  
3. 有链接但未登录 MCP：仍可把 URL 写入 manifest；读设计细节前引导 `/kb-figma-setup`

## 2. 配置引导（必做一次）

装好 `@suwenguang/pi-kb` 后（已含本扩展），在 Pi 中：

### 2.1 写 MCP 配置

```text
/figma-remote-auth setup --project
```

- `--project`：写入业务仓 `.pi/mcp.json`（推荐团队共享结构；token 不进 git）  
- 默认 `--global`：写 `~/.pi/agent/mcp.json`  
- 若仓内已有 `figma` 条目（与 vkk 示例一致），`setup` 会合并/确认，勿重复冲突 server 名

### 2.2 OAuth 登录 + 同步密钥环

```text
/figma-remote-auth login
/figma-oauth-sync
```

Pi 会打印 Figma 授权 URL（**不会**自动打开浏览器；TUI 里 URL 可能不可点，请复制到浏览器）。授权后执行 sync（或 `/reload`，扩展会在下次 `session_start` 自动 sync），再：

```text
/mcp reconnect figma
```

或 `/reload`。

Token 明文默认：`~/.pi/agent/mcp-oauth/figma/tokens.json`（`0600`）；可用 `MCP_OAUTH_DIR` 覆盖根目录。**勿提交**。

手工同步（与斜杠等价）：

```bash
node "$PI_KB_ROOT/scripts/import-figma-mcp-oauth.mjs"
```

### 2.3 调用方式

经 `pi-mcp-adapter` 代理，例如：

```text
mcp({ search: "figma" })
mcp({ connect: "figma" })
mcp({ tool: "figma_TOOL_NAME", args: "{}" })
```

具体工具名以连接后列表为准。

### 2.4 常见失败

| 现象 | 处理 |
|------|------|
| 提示缺 `pi-mcp-adapter` | `pi update` 到含 bundled adapter 的本包版本后 `/reload` |
| login 后仍 **needs auth** | `/figma-oauth-sync` → `/mcp reconnect figma`；或 `/reload` 触发自动 sync |
| sync 报缺 `@napi-rs/keyring` | 确认本包已 bundled `pi-mcp-adapter` 且完整安装 |
| OAuth 回调冲突 | 默认随机端口；仅在需要固定回调时用 `--port` |
| 只有产品链接、不读 MCP | 正常；提案闸门不依赖本扩展 |

## 3. 与业务仓已有配置

若业务仓已手工配置 `.pi/mcp.json` 的 `figma`（url + oauth），仍须 `/figma-remote-auth login` + sync；仅有 JSON、无 token/密钥环时连接会失败。

可从 `.pi/settings.json` 移除单独的 `npm:pi-figma-remote-auth`（装本包后已自带）。若业务仓曾自带 `.pi/extensions/figma-mcp-oauth-sync.ts`，装本包后可删项目副本，避免重复注册 `/figma-oauth-sync`。

## 4. 斜杠入口

业务仓执行：`/kb-figma-setup`（豁免 Bootstrap 门禁）。

上游细节：[pi-figma-remote-auth README](https://github.com/DianP/pi-figma-remote-auth)。