# Kumoha Figma

Kumoha Figma 是一个面向本机 Codex 工作流的独立 Figma MCP Manager。多个任务通过短命客户端连接同一个 Streamable HTTP Manager；Manager 再通过同一回环端口上的 WebSocket 与 `Kumoha Figma Bridge` 通信。

```text
Codex 任务 ── 短命客户端 ── HTTP http://localhost:9223/mcp ─┐
                                                               ├─ Kumoha Figma Manager
Figma Desktop ── Kumoha Figma Bridge ── ws://localhost:9223 ───┘
```

## 版本与来源

- 当前版本：`1.40.0-kumoha.3`
- 固定上游：[`southleft/figma-console-mcp@v1.40.0`](https://github.com/southleft/figma-console-mcp/tree/v1.40.0)
- 固定上游提交：`e4d5605e6108cd0b21a950f6f57fc189749bd2eb`
- 许可证：MIT；安装后的发行目录保留上游许可证和来源信息

本仓库保存 Kumoha 的安装器、控制器、短命客户端、Bridge 启动辅助脚本以及针对固定上游版本的补丁。安装器不会原地修改 `%USERPROFILE%\.figma-console-mcp`。

## 设计边界

| 项目 | Kumoha Figma |
| --- | --- |
| Codex MCP 名称 | `kumoha_figma` |
| 安装目录 | `%USERPROFILE%\.kumoha-figma-manager` |
| 包身份 | `kumoha-figma-manager` |
| MCP transport | Streamable HTTP |
| Figma 插件 | `Kumoha Figma Bridge` / `kumoha-figma-bridge-mcp` |
| 生命周期 | 一个显式管理的共享进程；调用客户端用完即退出 |

- Manager 只监听 loopback `9223`，不绑定 `0.0.0.0`，也不向局域网公开。
- HTTP 与 Bridge WebSocket 复用同一个 TCP listener。
- 请求级 dispatcher 在响应结束后释放；Manager 不绑定到某一个 Codex 对话。
- 默认最多同时处理 8 个请求；缓存有数量和时间上限。
- 控制器只依据 PID 记录和 `/health` 身份停止自己启动的 Manager，不按进程名或端口批量结束进程。
- 默认不启动 Manager，也不登记 Windows 开机自启。

## 环境要求

- Windows 10/11
- Git
- Node.js 与 npm
- PowerShell
- Figma Desktop

## 安装

在本仓库根目录执行：

```powershell
powershell -NoProfile -ExecutionPolicy Bypass -File .\install-kumoha-figma-manager.ps1
```

安装器会：

1. 克隆并核对固定的上游 tag 与提交；
2. 校验并应用 `patches/kumoha-figma-manager-v1.40.0.patch`；
3. 安装锁定依赖，运行上游测试并构建；
4. 安装到 `%USERPROFILE%\.kumoha-figma-manager\releases\1.40.0-kumoha.3`；
5. 复制独立 Bridge、控制器和短命客户端。

默认安装不会启动 Manager。需要安装后立即启动时显式增加 `-Start`；需要开机启动时显式增加 `-Autostart`。

## Codex 配置

在 `%USERPROFILE%\.codex\config.toml` 中登记：

```toml
[mcp_servers.kumoha_figma]
url = 'http://localhost:9223/mcp'
startup_timeout_sec = 120
tool_timeout_sec = 300
enabled = false
```

保持 `enabled = false` 可以避免普通任务自动加载完整工具目录。进入 Figma 工作流时使用短命客户端：

```powershell
node .\figmaClient.cjs activate
node .\figmaClient.cjs search screenshot
node .\figmaClient.cjs describe figma_capture_screenshot
node .\figmaClient.cjs call figma_get_status --json '{"probe":true}'
```

其它目录也可以使用安装后的固定入口：

```powershell
node "$env:USERPROFILE\.kumoha-figma-manager\figmaClient.cjs" activate
```

## 导入 Figma Bridge

在 Figma Desktop 中打开：

`Plugins → Development → Import plugin from manifest...`

选择：

```text
%USERPROFILE%\.kumoha-figma-manager\plugin\manifest.json
```

随后运行 `Kumoha Figma Bridge`。该 Bridge 只连接固定端口 `9223`，不会扫描或复用原 `Figma Desktop Bridge` 的动态端口实例。

## Manager 管理

```powershell
# 启动或复用健康的单实例
node .\manager-controller.cjs start

# 查看 endpoint、记录 PID 和健康身份
node .\manager-controller.cjs status

# 仅在 PID 与健康身份都匹配时停止
node .\manager-controller.cjs stop

# 可选的开机启动
node .\manager-controller.cjs install-autostart
node .\manager-controller.cjs remove-autostart
```

## 测试

```powershell
npm test
node .\figmaClient.smoke.cjs
```

单元测试和 smoke 只验证 Manager/客户端契约；真实 Figma 验收仍需要运行已导入的 `Kumoha Figma Bridge`，并执行带 `probe: true` 的 `figma_get_status`。

## 安全说明

- 不要通过公网、局域网、IPv6、SSH 端口转发或 `portproxy` 暴露 `9223`。
- Manager 不保存 Figma 账号密钥；它使用当前 Figma Desktop 登录态和打开文件的权限。
- 请求超时不能证明写操作未发生；写操作超时后应先读取状态，不要自动重试。
- 不要以进程名、模糊命令行或端口占用为依据批量结束 Node 进程。