OpenBio Comfy MCP

English | 简体中文

OpenBio Comfy MCP — это локальный сервер Model Context Protocol и расширение ComfyUI V3 для просмотра и редактирования рабочего процесса, открытого в данный момент на живом холсте ComfyUI. Он использует нативные механизмы ComfyUI для работы с графом, выделением, группами, состояниями изменений и отменой действий; он никогда автоматически не ставит рабочий процесс в очередь, не выполняет и не сохраняет его.

[!IMPORTANT] Опубликованные релизы устанавливаются через ComfyUI Manager. Пакеты из реестра включают встроенный MCP-сервер, поэтому пользователям Manager не нужно выполнять npm ci.

Возможности

• Просматривать активный холст в виде компактного структурированного вывода MCP.

• Искать все типы узлов, установленные в подключённом экземпляре ComfyUI.

• Просматривать полную нативную схему конкретного типа узла.

• Выделять и фокусировать нативные узлы или группы без изменения рабочего процесса.

• Добавлять, удалять, соединять, разъединять, настраивать и перемещать узлы.

• Добавлять, обновлять, подгонять, перемещать и удалять нативные группы ComfyUI.

• Применять набор как одну атомарную, отменяемую нативную транзакцию ComfyUI.

• Отклонять устаревшие или недопустимые патчи до изменения живого графа.

• Сохранять локальность транспорта MCP: stdio-сервер не открывает порт для прослушивания, а команды холста принимаются ретранслятором только через loopback.

Related MCP server: comfy-mcp

Архитектура

MCP host application (Codex or another local host)
        | MCP over stdio
        v
Node.js MCP server
        | ComfyUI HTTP
        v
Python V3 extension relay
        | ComfyUI WebSocket event
        v
Browser page extension -> active app.canvas.graph

Браузерная страница является источником истины для живого графа. Python-расширение сопоставляет запросы с подключённой страницей, а Node.js stdio-сервер не хранит авторитетной копии рабочего процесса. Расширение не регистрирует узлы выполнения ComfyUI и не изменяет ComfyUI Core, ComfyUI_frontend, Desktop или формат файлов рабочих процессов.

Требования

• ComfyUI 0.33.0 или новее

• Python 3.10 или новее в среде выполнения ComfyUI

• Node.js 20 или новее

• Приложение MCP-хоста, поддерживающее локальные stdio-серверы

• Страница браузера ComfyUI или Desktop, остающаяся открытой при использовании инструментов

Расширение ComfyUI не требует дополнительных Python-пакетов. Релизы из реестра включают предварительно собранный MCP-сервер. Для установки из исходников и для разработки npm ci устанавливает только зависимости Node.js и собирает этот сервер; он не изменяет Python-окружение ComfyUI.

Установка

ComfyUI Manager (рекомендуется)

Откройте ComfyUI Manager, найдите OpenBio Comfy MCP или openbio-comfy-mcp, выберите Установить и перезапустите ComfyUI. Установленная точка входа MCP:

<ComfyUI>/custom_nodes/openbio-comfy-mcp/dist/openbio-comfy-mcp.mjs

Для установки из реестра шаг npm ci не требуется.

Стандартная установка из исходников

Склонируйте репозиторий непосредственно в каталог custom_nodes в ComfyUI, затем установите зависимость MCP-сервера и соберите объединённую точку входа.

Windows 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

Linux или macOS:

cd /path/to/ComfyUI/custom_nodes
git clone https://github.com/Open-Bio/openbio-comfy-mcp.git
cd openbio-comfy-mcp
npm ci

После установки перезапустите ComfyUI, откройте его интерфейс в браузере и убедитесь, что маршрут расширения доступен:

Invoke-RestMethod http://127.0.0.1:8188/openbio-comfy-mcp/health

Ожидаемый ответ: { "ok": true }.

Отдельный checkout для разработки

Храните Git-checkout за пределами ComfyUI и предоставляйте к нему доступ через ссылку, когда требуется сохранять изменения в отдельном репозитории.

Windows PowerShell:

$ComfyRoot = "C:\path\to\ComfyUI"
$Repo = "C:\path\to\openbio-comfy-mcp"

New-Item -ItemType Junction `
  -Path "$ComfyRoot\custom_nodes\openbio-comfy-mcp" `
  -Target $Repo

Set-Location $Repo
npm ci

Linux или macOS:

ln -s /path/to/openbio-comfy-mcp /path/to/ComfyUI/custom_nodes/openbio-comfy-mcp
cd /path/to/openbio-comfy-mcp
npm ci

Не предоставляйте один и тот же checkout через более чем один корень пользовательских узлов.

Подключение MCP-хоста

Codex

Зарегистрируйте локальный stdio-сервер, указав абсолютный путь:

$Repo = (Resolve-Path "C:\path\to\openbio-comfy-mcp").Path

codex mcp add openbio-comfy-mcp `
  --env OPENBIO_COMFY_URL=http://127.0.0.1:8188 `
  -- node "$Repo\dist\openbio-comfy-mcp.mjs"

codex mcp get openbio-comfy-mcp --json
codex mcp list --json

После добавления сервера перезапустите клиент Codex. Codex Desktop, CLI и IDE-расширение используют общую конфигурацию MCP на одном и том же хосте Codex. См. официальную документацию Codex MCP.

Другие stdio MCP-хосты

Для хостов, использующих JSON-конфигурацию mcpServers, адаптируйте этот пример, указав абсолютный путь:

{
  "mcpServers": {
    "openbio-comfy-mcp": {
      "command": "node",
      "args": ["C:\\path\\to\\openbio-comfy-mcp\\dist\\openbio-comfy-mcp.mjs"],
      "env": {
        "OPENBIO_COMFY_URL": "http://127.0.0.1:8188"
      }
    }
  }
}

Ключи конфигурации различаются в зависимости от хоста. Команда должна начинаться с dist/openbio-comfy-mcp.mjs, а OPENBIO_COMFY_URL должен указывать на локальный сервер ComfyUI.

Конфигурация

Инструменты

Рекомендуемый порядок редактирования:

1. Вызовите inspect_canvas и сохраните возвращённые canvas_id и revision.

2. Перед добавлением незнакомого типа узла используйте search_nodes и inspect_node_type.

3. Отправьте один apply_canvas_patch, указав полученные canvas_id и revision как base_revision.

4. При необходимости вызовите present_canvas, чтобы выделить и сфокусировать изменённые элементы.

5. Проверьте ещё раз. Если результат нежелателен, используйте нативную команду отмены ComfyUI.

Точное публичное поведение и набор операций см. в docs/spec.md.

Примечание по разработке фронтенда

Автономный Vite-сервер разработки ComfyUI_frontend (pnpm dev, обычно порт 5173) не загружает JavaScript-расширения, предоставляемые пользовательскими узлами. Поэтому OpenBio Comfy MCP не может подключиться к холсту, обслуживаемому только этим сервером разработки. Используйте фронтенд, который отдаёт сам ComfyUI, либо соберите фронтенд и запустите ComfyUI с этой сборкой в качестве корня фронтенда.

После установки или обновления этого репозитория перезапустите ComfyUI и перезагрузите страницу браузера, чтобы расширение страницы загрузилось.

Безопасность и конфиденциальность

• Устанавливайте MCP-серверы только из доверенных источников. Этот локальный сервер работает с теми же правами операционной системы, что и приложение MCP-хоста, которое его запускает.

• Относитесь к apply_canvas_patch как к инструменту с правом записи и просматривайте или одобряйте его использование в вашем MCP-хосте. Он изменяет рабочий процесс, открытый в выбранной странице, хотя весь патч можно отменить одной нативной командой отмены.

• stdio-MCP-сервер не открывает сетевого прослушивателя. Он отправляет запросы к настроенному HTTP-серверу ComfyUI, который по умолчанию равен http://127.0.0.1:8188.

• Запросы команд холста принимаются только через loopback. Это ограничение не является общим уровнем аутентификации для ComfyUI; не открывайте доступ к неаутентифицированному серверу ComfyUI из ненадёжных сетей.

• Мост предоставляет только типизированные операции с графом, а не произвольный JavaScript, доступ к DOM, файловой системе, shell-команды, постановку рабочих процессов в очередь или их выполнение.

• Инспекции холста могут включать имена рабочих процессов, пути, заголовки узлов, промпты, имена файлов, идентификаторы сэмплов и значения виджетов. Любая дальнейшая обработка регулируется политикой конфиденциальности и конфигурацией MCP-хоста и поставщика моделей, к которому вы подключаетесь.

• Отключённая страница возвращает NO_LIVE_CANVAS; система никогда не переключается на фоновое редактирование файлов рабочих процессов.

Устранение неполадок

• NO_LIVE_CANVAS: откройте или перезагрузите страницу ComfyUI и оставьте её подключённой.

• Инструменты отсутствуют в хосте: проверьте абсолютный путь dist/openbio-comfy-mcp.mjs и перезапустите приложение MCP-хоста. Для установки из исходников сначала выполните npm ci.

• Отсутствует эндпоинт проверки состояния: убедитесь, что репозиторий находится непосредственно в custom_nodes или связан с ними, затем перезапустите ComfyUI и проверьте его консоль на предмет ошибок импорта.

• STALE_CANVAS: снова вызовите inspect_canvas и создайте новый патч на основе возвращённой ревизии.

• Открыто несколько страниц: по умолчанию целевой является последняя сфокусированная страница ComfyUI; при неразрешённой неоднозначности выводится сообщение об ошибке, а не предположение.

• Страница разработки на порту 5173 не подключается: используйте фронтенд, который отдаёт бэкенд ComfyUI, как описано выше.

Обновление и удаление

Обновите установку из исходников и её зафиксированные зависимости Node.js:

git pull --ff-only
npm ci

После обновления перезапустите ComfyUI и перезагрузите его страницу в браузере.

Чтобы удалить расширение, сначала уберите регистрацию MCP-хоста. Для Codex:

codex mcp remove openbio-comfy-mcp

Затем удалите клонированный каталог openbio-comfy-mcp — или только junction/символическую ссылку для отдельного checkout в разработке — из ComfyUI/custom_nodes, и перезапустите ComfyUI.

Разработка

Установите зависимости Node.js и запустите тесты MCP/расширения страницы:

npm ci
npm test

Запустите тесты Python-ретранслятора с помощью того же интерпретатора, который использует ComfyUI:

C:\path\to\ComfyUI\.venv\Scripts\python.exe `
  -m pytest --rootdir=tests -c pyproject.toml tests -q

Структура репозитория:

dist/                     Bundled, dependency-free Registry MCP entry point
mcp_host/                 Node.js stdio MCP server
openbio_comfy_mcp/        ComfyUI V3 Python relay extension
scripts/                  Reproducible MCP bundle build
web/                      Live page extension and canvas bridge
tests/                    Node.js and Python tests
docs/spec.md              Public behavior and safety boundaries

Приветствуются баг-репорты и пулл-реквесты. Пожалуйста, не выходите за задокументированные границы проекта (живой холст и локальный транспорт) и запускайте оба набора тестов перед отправкой.

Лицензия

OpenBio Comfy MCP распространяется под лицензией MIT.

Этот проект использует официальный Model Context Protocol TypeScript SDK и задокументированные механизмы ComfyUI: расширение V3 и JavaScript-расширение.