Kumoha Figma

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

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

• 固定上游提交：e4d5605e6108cd0b21a950f6f57fc189749bd2eb

• 许可证：MIT；安装后的发行目录保留上游许可证和来源信息

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

Related MCP server: Custom Figma 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 -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 中登记：

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

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

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}'

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

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

导入 Figma Bridge

在 Figma Desktop 中打开：

Plugins → Development → Import plugin from manifest...

选择：

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

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

Manager 管理

# 启动或复用健康的单实例
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

测试

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 进程。