From 28dfd22c16e977ea6d38f7ecb62450b3f7713aa1 Mon Sep 17 00:00:00 2001 From: ethanfel Date: Sun, 28 Jun 2026 14:02:20 +0200 Subject: [PATCH] docs: Codex setup + reconcile MCP port in design doc README: add a Codex section with both connection methods (HTTP url entry and the stdio shim), matching the schema codex 0.142.3 writes; note that AgentReceive's wait_seconds blocks a ComfyUI worker; add COMFY_BRIDGE_TMP_TTL to the env-vars table. Design doc: add a decisions-log line recording that the MCP server ships on a separate daemon-thread side port (9188, /mcp). Co-Authored-By: Claude Opus 4.8 --- README.md | 34 +++++++++++++++---- .../2026-06-28-comfyui-agent-bridge-design.md | 3 ++ 2 files changed, 31 insertions(+), 6 deletions(-) diff --git a/README.md b/README.md index a51e683..f82c7ef 100644 --- a/README.md +++ b/README.md @@ -57,6 +57,10 @@ bridge failure never blocks ComfyUI from loading the nodes. > Single Receive per channel: the consume-once model means two `Agent Receive` > nodes on the same channel compete for pushes. Use distinct channel names. +> `wait_seconds` blocks a ComfyUI execution worker for its whole duration. +> Outside interactive use, keep it modest (seconds, not hours) so you don't tie +> up a worker waiting on an agent. + ## Connecting an agent The bridge speaks **MCP over streamable HTTP** at `http://127.0.0.1:9188/mcp`. @@ -69,18 +73,35 @@ claude mcp add --transport http comfy http://127.0.0.1:9188/mcp Then in Claude Code, `/mcp` should list the five tools. -**Codex (HTTP):** add an MCP server pointing at the same URL, e.g. in -`~/.codex/config.toml`: +### Codex + +Codex reads `~/.codex/config.toml`. Use **either** method below (HTTP is +preferred). The exact key schema can vary by Codex version; the snippets here +match the form `codex mcp add` writes on Codex CLI 0.142.3, verified locally. + +**Codex (HTTP, newer builds):** point a streamable-HTTP MCP server at the URL — +equivalent to `codex mcp add comfy --url http://127.0.0.1:9188/mcp`: ```toml [mcp_servers.comfy] url = "http://127.0.0.1:9188/mcp" ``` -**Codex (stdio only):** if your Codex build cannot use HTTP MCP, point it at -`scripts/codex_stdio_shim.py`. Note: the shim is a documented scaffold and is -**not** implemented for the installed MCP SDK (mcp 1.28.1 ships no proxy -helper) — it prints guidance and exits non-zero. Prefer HTTP MCP. +**Codex (stdio only):** if your Codex build can *only* speak stdio MCP, point it +at `scripts/codex_stdio_shim.py` — a real stdio<->HTTP MCP proxy that connects +to the same bridge URL and forwards tool calls. Equivalent to +`codex mcp add comfy --env COMFY_BRIDGE_URL=http://127.0.0.1:9188/mcp -- python /abs/path/scripts/codex_stdio_shim.py`: + +```toml +[mcp_servers.comfy] +command = "python" +args = ["/abs/path/ComfyUI-Nodes-Agents/scripts/codex_stdio_shim.py"] +env = { COMFY_BRIDGE_URL = "http://127.0.0.1:9188/mcp" } +``` + +The shim requires ComfyUI (and the bridge) to be running; if it can't reach the +HTTP bridge it exits non-zero with a clear stderr message so Codex surfaces the +error. Use an absolute path to the shim. ## MCP tools @@ -117,6 +138,7 @@ prompt and an `Agent Emit(channel=render)` on the output, then from the agent: | --- | --- | --- | | `COMFY_BRIDGE_MCP_PORT` | `9188` | Port the MCP bridge binds (use `0` for an ephemeral port, e.g. in tests). | | `COMFY_BRIDGE_TMP` | `.comfy_bridge_tmp` | Temp dir where `Agent Emit` writes image PNGs. | +| `COMFY_BRIDGE_TMP_TTL` | `3600` | Age (seconds) after which `save_tensor_png` reaps old `img_*.png` temp files. | | `COMFY_BRIDGE_WORKFLOWS` | `workflows` | Dir that `comfy_run_workflow` loads `.json` from. | | `COMFY_BASE_URL` | `http://127.0.0.1:8188` | ComfyUI HTTP API base URL used by `comfy_run_workflow` / `comfy_get_result`. | diff --git a/docs/plans/2026-06-28-comfyui-agent-bridge-design.md b/docs/plans/2026-06-28-comfyui-agent-bridge-design.md index 7b4a59e..5ef9bbd 100644 --- a/docs/plans/2026-06-28-comfyui-agent-bridge-design.md +++ b/docs/plans/2026-06-28-comfyui-agent-bridge-design.md @@ -158,3 +158,6 @@ docs/plans/2026-06-28-comfyui-agent-bridge-design.md - `wait_seconds` on `Agent Receive` covers both blocking and non-blocking turns. - Images passed **by path**; text inline. - **Standalone-lean** scope: don't reinvent the 108-tool control surface. +- MCP server ships on a **separate daemon-thread side port (default 9188, path + `/mcp`)** rather than mounted on PromptServer:8188 — the cleaner choice that + avoids ASGI-in-aiohttp coupling.