openbio-comfy-mcp 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Open-Bio contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,177 @@
+# OpenBio Comfy MCP
+
+[English](README.md) | [简体中文](README.zh-CN.md)
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+[![npm](https://img.shields.io/npm/v/openbio-comfy-mcp.svg)](https://www.npmjs.com/package/openbio-comfy-mcp)
+[![Node.js 20+](https://img.shields.io/badge/Node.js-20%2B-339933.svg)](https://nodejs.org/)
+[![ComfyUI 0.33.0+](https://img.shields.io/badge/ComfyUI-0.33.0%2B-blue.svg)](https://github.com/Comfy-Org/ComfyUI)
+
+Let Cursor, Codex, Claude, or another local AI **inspect and edit the workflow currently open** on your ComfyUI canvas.
+
+It uses ComfyUI's own graph, selection, groups, and undo. It never queues, runs, or saves a workflow for you.
+
+This is **not** [Comfy's official MCP](https://docs.comfy.org/agent-tools/mcp). Official Comfy MCP generates images on Comfy Cloud or runs workflow files through `comfy-mcp`. This project edits the live graph you already have open.
+
+## What you can ask
+
+Once both pieces below are installed and a ComfyUI window is open:
+
+- What is on this canvas?
+- Add a node, connect these two, or move this group.
+- Search the node types installed in *this* ComfyUI.
+- Pack or unpack a native subgraph.
+
+Changes appear on the canvas immediately. One ComfyUI undo reverts a whole patch.
+
+## Install
+
+You need **both** steps. Manager only adds the ComfyUI side. The AI client still needs the MCP server.
+
+### 1. ComfyUI extension
+
+In ComfyUI Manager, search for `OpenBio Comfy MCP` or `openbio-comfy-mcp`, install it, and restart ComfyUI. Keep a browser or Desktop window open while you use the tools.
+
+The extension has no extra Python packages. Registry builds already include the bundled MCP server.
+
+Confirm the relay is up:
+
+```powershell
+Invoke-RestMethod http://127.0.0.1:8188/openbio-comfy-mcp/health
+```
+
+You should see `"ok": true`. Use your ComfyUI port if it is not `8188`.
+
+### 2. MCP host
+
+Node.js 20+ must be on your `PATH`. Point the host at the published package — do not copy a file path:
+
+```json
+{
+  "mcpServers": {
+    "openbio-comfy-mcp": {
+      "command": "npx",
+      "args": ["-y", "openbio-comfy-mcp@latest"]
+    }
+  }
+}
+```
+
+#### Codex
+
+```powershell
+codex mcp add openbio-comfy-mcp -- npx -y openbio-comfy-mcp@latest
+codex mcp get openbio-comfy-mcp --json
+```
+
+Restart the Codex client after adding it. Desktop, CLI, and the IDE extension share the same host config. See the [Codex MCP docs](https://developers.openai.com/codex/mcp).
+
+#### Cursor
+
+Add the JSON above to `~/.cursor/mcp.json` (global) or `.cursor/mcp.json` in a project, then reload MCP.
+
+#### Other stdio hosts (Claude Desktop, Claude Code, …)
+
+Use the same `npx -y openbio-comfy-mcp@latest` command. Key names vary by host; the command must stay `npx`.
+
+Local ComfyUI instances are discovered automatically. You only need one MCP registration even if several ComfyUI processes are running.
+
+## Requirements
+
+- ComfyUI 0.33.0 or newer
+- Python 3.10 or newer in the ComfyUI runtime
+- Node.js 20 or newer on the PATH of the MCP host
+- An MCP host that can launch a local stdio server
+- A ComfyUI page left open while the tools run
+
+## Configuration
+
+| Variable | Default | When to set it |
+| --- | --- | --- |
+| `OPENBIO_COMFY_URL` | Unset (discover locally) | Pin this MCP connection to one instance, for example `http://127.0.0.1:8189`. |
+| `OPENBIO_COMFY_REGISTRY_DIR` | `~/.openbio-comfy-mcp/instances` | Override the shared registration directory. ComfyUI and the MCP host must use the same path. |
+
+Install the extension in every ComfyUI instance you want to edit. Each running backend writes its address under the shared directory. Discovery uses loopback only; remote ComfyUI is not supported.
+
+With several online instances, tools pick the one whose page was focused last. Say “edit the workflow on port 8189” if you need a specific one. `list_instances` shows `instance_id`, status, and connected canvases.
+
+## Tools
+
+| Tool | Effect | Purpose |
+| --- | --- | --- |
+| `list_instances` | Read-only | List local instances and connected canvases. |
+| `inspect_canvas` | Read-only | Inspect the live graph, subgraphs, or specific nodes and groups. |
+| `search_nodes` | Read-only | Search the node types installed in that ComfyUI. |
+| `inspect_node_type` | Read-only | Read the native schema of one `class_type`. |
+| `present_canvas` | UI only | Navigate graphs, select items, optionally fit the view. |
+| `apply_canvas_patch` | Writes the canvas | Apply one atomic, undoable batch of graph edits. |
+
+Typical flow: inspect → search a node type if needed → apply one patch → undo in ComfyUI if the result is wrong.
+
+Exact operations live in [docs/spec.md](docs/spec.md).
+
+## Security
+
+- The MCP process runs with the same OS permissions as the host that launched it.
+- `apply_canvas_patch` can change the open workflow. Review it in your host if you gate write tools.
+- The server opens no listening port. Canvas commands are accepted from loopback only. That is not a general ComfyUI login; do not expose an unauthenticated ComfyUI to untrusted networks.
+- Inspections can include prompts, filenames, and widget values. What happens next follows your MCP host and model provider.
+
+## Troubleshooting
+
+- `NO_LIVE_CANVAS`: open or reload a ComfyUI page and leave it connected.
+- Host shows no tools: confirm Node 20+ is on `PATH`, that the host command is `npx -y openbio-comfy-mcp@latest`, then restart the host.
+- Health route missing: the extension is not loaded. Reinstall under `custom_nodes`, restart ComfyUI, check its console.
+- `STALE_CANVAS`: inspect again and send a new patch.
+- `AMBIGUOUS_INSTANCE`: several instances, no clear focus. Use `list_instances` and pass an `instance_id` or `canvas_id`.
+- `INSTANCE_UNAVAILABLE` / `INSTANCE_NOT_FOUND`: that ComfyUI is down or was restarted. List and inspect again.
+- Port `5173` Vite frontend: custom-node JavaScript does not load there. Use the frontend served by ComfyUI.
+
+## Update and uninstall
+
+Manager users: update the extension in ComfyUI Manager, then restart ComfyUI and reload the page. The MCP host always fetches `@latest` on the next `npx` launch.
+
+Remove the host registration first (Codex: `codex mcp remove openbio-comfy-mcp`), then uninstall the custom node and restart ComfyUI.
+
+## Source install
+
+Use this when you are developing the extension, or Manager is not available.
+
+```powershell
+$ComfyRoot = "C:\path\to\ComfyUI"
+Set-Location "$ComfyRoot\custom_nodes"
+git clone https://github.com/Open-Bio/openbio-comfy-mcp.git
+Set-Location .\openbio-comfy-mcp
+npm ci
+```
+
+```bash
+cd /path/to/ComfyUI/custom_nodes
+git clone https://github.com/Open-Bio/openbio-comfy-mcp.git
+cd openbio-comfy-mcp
+npm ci
+```
+
+To keep the Git checkout outside ComfyUI, Junction or symlink it into `custom_nodes`, then run `npm ci` in the checkout. Do not expose the same checkout through more than one custom-node root.
+
+For local MCP testing against that checkout, you can still launch `node dist/openbio-comfy-mcp.mjs` instead of `npx`.
+
+```bash
+npm ci
+npm test
+```
+
+Python relay tests, using the same interpreter as ComfyUI:
+
+```powershell
+C:\path\to\ComfyUI\.venv\Scripts\python.exe `
+  -m pytest --rootdir=tests -c pyproject.toml tests -q
+```
+
+The standalone ComfyUI_frontend Vite server (`pnpm dev`, usually port `5173`) does not load custom-node JavaScript. Open the UI that ComfyUI itself serves.
+
+## License
+
+OpenBio Comfy MCP is released under the [MIT License](LICENSE).
+
+This project uses the official [Model Context Protocol TypeScript SDK](https://github.com/modelcontextprotocol/typescript-sdk) and ComfyUI's documented [V3](https://docs.comfy.org/custom-nodes/v3_migration) and [JavaScript extension](https://docs.comfy.org/custom-nodes/js/javascript_overview) APIs.

package/README.zh-CN.md

@@ -0,0 +1,177 @@
+# OpenBio Comfy MCP
+
+[English](README.md) | [简体中文](README.zh-CN.md)
+
+[![许可证：MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+[![npm](https://img.shields.io/npm/v/openbio-comfy-mcp.svg)](https://www.npmjs.com/package/openbio-comfy-mcp)
+[![Node.js 20+](https://img.shields.io/badge/Node.js-20%2B-339933.svg)](https://nodejs.org/)
+[![ComfyUI 0.33.0+](https://img.shields.io/badge/ComfyUI-0.33.0%2B-blue.svg)](https://github.com/Comfy-Org/ComfyUI)
+
+让 Cursor、Codex、Claude 或其他本地 AI **查看并修改你 ComfyUI 里当前打开的工作流画布**。
+
+它走 ComfyUI 自己的图、选择、分组和撤销，不会帮你排队、执行或保存。
+
+这不是 [Comfy 官方 MCP](https://docs.comfy.org/agent-tools/mcp)。官方 Cloud MCP 在云端出图，`comfy-mcp` 跑的是工作流文件。本项目改的是你屏幕上正在打开的那张图。
+
+## 可以让 AI 做什么
+
+两边都装好、并且开着一个 ComfyUI 窗口之后，可以这样说：
+
+- 现在画布上有什么？
+- 加一个节点、把这两个连上、挪一下这个组。
+- 搜一下**这台** ComfyUI 里装了哪些节点。
+- 把节点打成原生子图，或再拆开。
+
+修改会立刻出现在画布上。一次 ComfyUI 撤销会整批还原。
+
+## 安装
+
+必须做 **两步**。Manager 只装 ComfyUI 这一侧；AI 客户端还要单独接 MCP 服务器。
+
+### 1. 安装 ComfyUI 扩展
+
+打开 ComfyUI Manager，搜索 `OpenBio Comfy MCP` 或 `openbio-comfy-mcp`，安装后重启 ComfyUI。用工具时请保持浏览器或 Desktop 窗口开着。
+
+扩展没有额外的 Python 依赖。Registry 版本已带打包好的 MCP 服务器。
+
+确认中继可用：
+
+```powershell
+Invoke-RestMethod http://127.0.0.1:8188/openbio-comfy-mcp/health
+```
+
+应返回 `"ok": true`。端口不是 `8188` 时换成你的端口。
+
+### 2. 接到 MCP Host
+
+MCP Host 所用环境的 `PATH` 上要有 Node.js 20+。写发布包即可，不必填本机文件路径：
+
+```json
+{
+  "mcpServers": {
+    "openbio-comfy-mcp": {
+      "command": "npx",
+      "args": ["-y", "openbio-comfy-mcp@latest"]
+    }
+  }
+}
+```
+
+#### Codex
+
+```powershell
+codex mcp add openbio-comfy-mcp -- npx -y openbio-comfy-mcp@latest
+codex mcp get openbio-comfy-mcp --json
+```
+
+添加后重启 Codex 客户端。Desktop、CLI 和 IDE 扩展共用同一套配置。参见 [Codex MCP 文档](https://developers.openai.com/codex/mcp)。
+
+#### Cursor
+
+把上面的 JSON 写进 `~/.cursor/mcp.json`（全局）或项目里的 `.cursor/mcp.json`，然后重载 MCP。
+
+#### 其他 stdio Host（Claude Desktop、Claude Code 等）
+
+同样使用 `npx -y openbio-comfy-mcp@latest`。各 Host 的配置键可能不同，命令必须是 `npx`。
+
+本地 ComfyUI 会自动发现。开了多个 ComfyUI 进程，也只需注册一次 MCP。
+
+## 环境要求
+
+- ComfyUI 0.33.0 或更高
+- ComfyUI 运行环境为 Python 3.10 或更高
+- MCP Host 的 PATH 上有 Node.js 20 或更高
+- 能拉起本地 stdio 服务器的 MCP Host
+- 使用工具时保持一个 ComfyUI 页面打开
+
+## 配置
+
+| 变量 | 默认值 | 什么时候设 |
+| --- | --- | --- |
+| `OPENBIO_COMFY_URL` | 不设置（自动发现） | 把这次 MCP 连接钉在某一个实例上，例如 `http://127.0.0.1:8189`。 |
+| `OPENBIO_COMFY_REGISTRY_DIR` | `~/.openbio-comfy-mcp/instances` | 覆盖共享注册目录。ComfyUI 和 MCP Host 必须用同一个路径。 |
+
+每个要编辑的 ComfyUI 实例都要装这个扩展。各后端会把本机地址写进共享目录。只发现回环地址，不支持远程 ComfyUI。
+
+多个实例同时在线时，默认选最近获得焦点的页面。需要指定时可以说「改 8189 端口上的工作流」。`list_instances` 会列出 `instance_id`、状态和已连接画布。
+
+## 工具
+
+| 工具 | 影响 | 用途 |
+| --- | --- | --- |
+| `list_instances` | 只读 | 列出本地实例和已连接画布。 |
+| `inspect_canvas` | 只读 | 查看当前图、子图，或指定节点/分组。 |
+| `search_nodes` | 只读 | 搜索该 ComfyUI 已安装的节点类型。 |
+| `inspect_node_type` | 只读 | 读取某个 `class_type` 的原生结构。 |
+| `present_canvas` | 仅界面 | 切换图、选中对象、按需适配视口。 |
+| `apply_canvas_patch` | 写入画布 | 原子化执行一批可撤销的图编辑。 |
+
+常见流程：先检查 → 需要时搜节点类型 → 发一次补丁 → 不满意就在 ComfyUI 里撤销。
+
+完整操作集合见 [docs/spec.md](docs/spec.md)。
+
+## 安全
+
+- MCP 进程的操作系统权限与拉起它的 Host 相同。
+- `apply_canvas_patch` 会改当前打开的工作流。若 Host 会审核写入工具，请打开审核。
+- 服务器不监听端口。画布命令只接受回环请求。这不是 ComfyUI 的登录层；不要把未认证的 ComfyUI 暴露到不可信网络。
+- 检查结果可能包含提示词、文件名和控件值。后续如何处理取决于你的 MCP Host 和模型提供方。
+
+## 故障排查
+
+- `NO_LIVE_CANVAS`：打开或刷新 ComfyUI 页面，并保持连接。
+- Host 里没有工具：确认 PATH 上有 Node 20+，命令是 `npx -y openbio-comfy-mcp@latest`，然后重启 Host。
+- 健康检查路由不存在：扩展没加载。确认装在 `custom_nodes` 下，重启 ComfyUI，看控制台。
+- `STALE_CANVAS`：重新检查，再发新补丁。
+- `AMBIGUOUS_INSTANCE`：多个实例且焦点不明确。先 `list_instances`，再传入 `instance_id` 或 `canvas_id`。
+- `INSTANCE_UNAVAILABLE` / `INSTANCE_NOT_FOUND`：该 ComfyUI 已关掉或刚重启。重新列出并检查。
+- 端口 `5173` 的 Vite 前端：不会加载自定义节点的 JavaScript。请用 ComfyUI 自己提供的前端。
+
+## 更新与卸载
+
+Manager 用户：在 Manager 里更新扩展，重启 ComfyUI 并刷新页面。MCP Host 下次 `npx` 时会拉取 `@latest`。
+
+先删 Host 注册（Codex：`codex mcp remove openbio-comfy-mcp`），再卸载自定义节点，最后重启 ComfyUI。
+
+## 源码安装
+
+开发本扩展，或无法使用 Manager 时：
+
+```powershell
+$ComfyRoot = "C:\path\to\ComfyUI"
+Set-Location "$ComfyRoot\custom_nodes"
+git clone https://github.com/Open-Bio/openbio-comfy-mcp.git
+Set-Location .\openbio-comfy-mcp
+npm ci
+```
+
+```bash
+cd /path/to/ComfyUI/custom_nodes
+git clone https://github.com/Open-Bio/openbio-comfy-mcp.git
+cd openbio-comfy-mcp
+npm ci
+```
+
+Git 仓库放在 ComfyUI 外面时，用 Junction 或符号链接挂到 `custom_nodes`，再在仓库里运行 `npm ci`。不要把同一个仓库挂到多个自定义节点目录。
+
+对本仓库做本地 MCP 调试时，可以继续用 `node dist/openbio-comfy-mcp.mjs`，不必走 `npx`。
+
+```bash
+npm ci
+npm test
+```
+
+Python 中继测试请用 ComfyUI 同一个解释器：
+
+```powershell
+C:\path\to\ComfyUI\.venv\Scripts\python.exe `
+  -m pytest --rootdir=tests -c pyproject.toml tests -q
+```
+
+独立的 ComfyUI_frontend Vite 开发服务器（`pnpm dev`，通常是 `5173`）不会加载自定义节点的 JavaScript。请打开 ComfyUI 自己提供的界面。
+
+## 许可证
+
+OpenBio Comfy MCP 使用 [MIT License](LICENSE) 发布。
+
+本项目使用官方 [Model Context Protocol TypeScript SDK](https://github.com/modelcontextprotocol/typescript-sdk)，以及 ComfyUI 文档中的 [V3](https://docs.comfy.org/custom-nodes/v3_migration) 和 [JavaScript 扩展](https://docs.comfy.org/custom-nodes/js/javascript_overview)接口。