OpenBio Comfy MCP

English | 简体中文

OpenBio Comfy MCP は、ライブの ComfyUI キャンバスで現在開いているワークフローを検査・編集するための、ローカル Model Context Protocol サーバー兼 ComfyUI V3 拡張機能です。ComfyUI のネイティブなグラフ、選択、グループ、ダーティ状態、およびアンドゥの動作を使用します。ワークフローの自動的なキュー投入、実行、保存は一切行いません。

[!IMPORTANT] 公開リリースは ComfyUI Manager からインストールできます。レジストリパッケージにはバンドルされた MCP サーバーが含まれているため、Manager ユーザーが npm ci を実行する必要はありません。

機能

• アクティブなキャンバスを、コンパクトで構造化された MCP 出力として検査します。

• 接続中の ComfyUI インスタンスにインストールされているすべてのノードタイプを検索します。

• 特定のノードタイプの完全なネイティブスキーマを検査します。

• ワークフローを変更せずに、ネイティブなノードやグループを選択してフォーカスします。

• ノードの追加、削除、接続、切断、設定、移動を行います。

• ネイティブな ComfyUI グループを追加、更新、フィット、移動、削除します。

• 一連の操作を、アトミックかつアンドゥ可能な単一のネイティブ ComfyUI トランザクションとして適用します。

• ライブグラフを変更する前に、古いパッチや無効なパッチを拒否します。

• MCP トランスポートをローカルに保ちます。stdio サーバーは待受ポートを開かず、キャンバスコマンドはリレーがループバックからのみ受け付けます。

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 以上

• ComfyUI ランタイムの Python 3.10 以上

• Node.js 20 以上

• ローカル stdio サーバーをサポートする MCP ホストアプリケーション

• ツールを使用している間、開いたままにする ComfyUI ブラウザまたは Desktop ページ

ComfyUI 拡張機能には追加の Python パッケージ依存関係はありません。レジストリリリースには事前ビルド済みの MCP サーバーが含まれます。ソースや開発用チェックアウトの場合、npm ci は Node.js の依存関係のみをインストールしてそのサーバーをビルドします。ComfyUI の Python 環境は変更されません。

インストール

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 の手順は必要ありません。

標準的なソースインストール

リポジトリを ComfyUI の custom_nodes ディレクトリに直接クローンし、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 を再起動し、ブラウザで UI を開いて、拡張機能のルートが利用可能であることを確認します:

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

期待される応答は { "ok": true } です。

開発用の兄弟チェックアウト

編集内容を独立したリポジトリに残したい場合は、Git チェックアウトを 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

同じチェックアウトを複数のカスタムノードルートから公開しないでください。

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 拡張機能は、同じ Codex ホスト上で MCP 設定を共有します。公式の Codex MCP ドキュメント を参照してください。

その他の stdio MCP ホスト

mcpServers JSON 設定を使用するホストでは、この例を絶対パスで調整してください:

{
  "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. 検査した canvas_id と revision を base_revision として、1 つの apply_canvas_patch を送信します。

4. 必要に応じて present_canvas を呼び出し、変更した項目を選択してフォーカスします。

5. 再度検査します。結果が望ましくない場合は、ComfyUI のネイティブなアンドゥコマンドを使用します。

正確な公開動作と操作セットについては、docs/spec.md を参照してください。

フロントエンド開発に関する注意

スタンドアロンの ComfyUI_frontend Vite 開発サーバー (pnpm dev、通常はポート 5173) は、カスタムノードが提供する JavaScript 拡張機能を読み込みません。したがって、OpenBio Comfy MCP は、その開発サーバーだけが提供するキャンバスには接続できません。ComfyUI 自体が提供するフロントエンドを使用するか、フロントエンドをビルドして、そのビルドをフロントエンドルートとして ComfyUI を起動してください。

このリポジトリをインストールまたは更新した後は、ページ拡張機能が読み込まれるよう、ComfyUI を再起動してブラウザページを再読み込みしてください。

セキュリティとプライバシー

• MCP サーバーは信頼できるソースからのみインストールしてください。このローカルサーバーは、それを起動する MCP ホストアプリケーションと同じオペレーティングシステム権限で実行されます。

• apply_canvas_patch は書き込み可能なツールとして扱い、MCP ホストでの使用を確認または承認してください。選択したページで現在開いているワークフローを変更しますが、パッチ全体は 1 回のネイティブなアンドゥで元に戻せます。

• stdio MCP サーバーはネットワークリスナーを開きません。設定された ComfyUI サーバーを呼び出します。デフォルトは http://127.0.0.1:8188 です。

• キャンバスコマンドのリクエストはループバックからのみ受け付けられます。この制限は ComfyUI の一般的な認証レイヤーではありません。認証のない ComfyUI サーバーを信頼できないネットワークに公開しないでください。

• ブリッジが公開するのは型付きグラフ操作のみであり、任意の JavaScript、DOM アクセス、ファイルシステムアクセス、シェルコマンド、ワークフローのキュー投入、実行は対象外です。

• キャンバスの検査には、ワークフロー名、パス、ノードタイトル、プロンプト、ファイル名、サンプル識別子、ウィジェット値が含まれることがあります。その後の取り扱いは、接続する MCP ホストとモデルプロバイダーのプライバシーポリシーおよび設定に従います。

• 切断されたページは NO_LIVE_CANVAS を返します。システムがバックグラウンドでワークフローファイルを編集するフォールバックを行うことは決してありません。

トラブルシューティング

• NO_LIVE_CANVAS: ComfyUI ページを開くか再読み込みし、接続したままにしてください。

• ホストにツールが表示されない場合: dist/openbio-comfy-mcp.mjs の絶対パスを確認し、MCP ホストアプリケーションを再起動してください。ソースチェックアウトの場合は、最初に npm ci を実行してください。

• ヘルスエンドポイントが見つからない場合: リポジトリが custom_nodes の直下にあるか、そこにリンクされているかを確認し、ComfyUI を再起動して、コンソールにインポートエラーがないか確認してください。

• STALE_CANVAS: inspect_canvas を再度呼び出し、返された revision から新しいパッチを作成してください。

• 複数のページが開いている場合: 最後にフォーカスされた ComfyUI ページがデフォルトのターゲットです。解決できない曖昧さは推測ではなく報告されます。

• ポート 5173 の開発ページが接続しない場合: 上記のとおり、ComfyUI バックエンドが提供するフロントエンドを使用してください。

更新とアンインストール

ソースインストールと、そのロック済みの Node.js 依存関係を更新します:

git pull --ff-only
npm ci

更新後、ComfyUI を再起動し、ブラウザページを再読み込みします。

アンインストールするには、まず MCP ホストの登録を削除します。Codex の場合:

codex mcp remove openbio-comfy-mcp

次に、クローンした openbio-comfy-mcp ディレクトリ(開発用の兄弟チェックアウトの場合は Junction/シンボリックリンクのみ)を ComfyUI/custom_nodes から削除し、ComfyUI を再起動します。

開発

Node.js の依存関係をインストールし、MCP/ページ拡張機能のテストを実行します:

npm ci
npm test

ComfyUI が使用するものと同じインタープリターで Python リレーテストを実行します:

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

Issue とプルリクエストは歓迎します。変更はプロジェクトの文書化されたライブキャンバスとローカルトランスポートの境界内に収め、提出前に両方のテストスイートを実行してください。

ライセンス

OpenBio Comfy MCP は MIT License の下で公開されています。

このプロジェクトは、公式の Model Context Protocol TypeScript SDK と、ComfyUI の文書化された V3 拡張機能 および JavaScript 拡張機能 の仕組みを使用しています。