> ## Documentation Index > Fetch the complete documentation index at: https://comfyui-mcp.artokun.io/docs/llms.txt > Use this file to discover all available pages before exploring further. # ツールの使い方 > ツールとは何か、なぜ自分では呼ばないのか、拒否されたときに何をするか。エンジニア向けではなく、人向けに書いています。 [ツールリファレンス](/docs/docs/tools/image-generation) は、このプロジェクトができることを、AI が読む形で すべて列挙します。このページはあなた向けの版です。 ここにコードを書くこと、JSON を打つこと、API を覚えることは必要ありません。人に 「ポートレートのワークフローを開いて、steps を 30 に上げて」と頼ったことがあれば、 もうインターフェースは知っています。 ## ツールはエージェントができることであり、あなたが入力するものではない それだけでは、チャットモデルはテキストしか出せません。ワークフローを説明はできます。開くことは できません。 **ツール** は、モデルが実際にあなたの ComfyUI に届けるよう渡す、具体的で名前の付いた動作です — ファイルを読み込む、レンダーをキューする、ノードパックをインストールする、出てきた絵を見る。 モデルがこれらを発明することはできません。固定されたメニューを受け取り、各項目は必要なものを 正確に言います。 **そのメニューから選ぶことはありません。** 欲しいものを、自然に出てくる言葉で言い、エージェントが 選びます。 | あなたが言うこと | 静かに走ること | | ------------------------ | ---------------------------------------------------------- | | 「何が保存してある？」 | `get_workflow` の `action: "list"` | | 「ポートレートのやつを開いて、何をするか教えて」 | `get_workflow` の `action: "list"`、それから `action: "analyze"` | | 「雪の中の赤いキツネを作って」 | `generate_image`（`image` ジョブ） | | 「もう終わった？」 | `queue`（`list` ジョブ） | | 「失敗したけど理由がわからない」 | `get_history`（`diagnose` ジョブ） | | 「ノードの半分が赤い」 | `list_packs`（`install_deps` ジョブ） | | 「ディスクがいっぱい。大きいのは何？」 | `list_local_models` | 2 行目に注目: 1 文、2 つのツール、知らなくてもよい順番。それがこの仕組み全体の要点です。 ファイルを見つけることと読むことが別の操作だと知る必要はありません。 どれだけ曖昧でも構いません。「何か壊れてる」は十分良い始まりです — エージェントは `get_system_stats (action:"health")` から始めて絞り込みます。具体的なほうが速いですが、 必須ではありません。 ### リファレンスページの JSON は何なのか どのツールページにも、次のようなブロックがあります: ```json theme={null} { "tool": "generate_image", "arguments": { "prompt": "a red fox in deep snow, golden hour, sharp focus", "steps": 30 } } ``` それはエージェントが送ったものの書き起こしであり、あなたへの指示ではありません。「雪の中の 赤いキツネを作って、もう少し細部を入れて」と言った。向こう側から出てきたのがそれです。 読めるようにしておく価値は 2 つあります: エージェントが理解したか確認したいとき、何かが おかしくて他人に説明するとき。暗記する価値はありません。 ## ツールの出所は 2 つある 面は 2 つあり、違う問いに答えるために存在します。 **ComfyUI の中**、エージェントタブにあります。そのツール（`panel_*`）は、いま見ている グラフ — 未保存の変更が載った実際のキャンバス — に作用します。 Claude Desktop、Claude Code、エディター、スマートフォン。そのツールは **サーバー** に 作用します: ディスク上のファイル、ジョブキュー、モデル、ノードパック、ComfyUI プロセスそのもの。 分かれ目は本当に「これ」という言葉です。「**これ** に LoRA を足して」と言うとき、パネルは 画面が見えるので「これ」が何か分かります。外側のクライアントは分かりません — ファイル名を 教える必要があります。 なのでパネルが扱うのは次のようなことです: * 目の前のグラフを読む（`panel_graph_outline`） * 自分で Queue Prompt を押したのとまったく同じように実行する（`panel_run`） * ノードを配線する、ウィジェットを変える、ノードが赤くなった理由を教える（`panel_add_node`、`panel_set_widget`、`panel_get_errors`） * ワークフロー全体をキャンバスに載せる、またはそこにあるものを保存する（`panel_load_workflow`、`panel_save_workflow`） そして外側のクライアントは、ゼロから画像を生成する、モデルとノードパックを管理する、 保存済みファイルを辿る、ComfyUI を再起動する、といったことを扱います。 **初めてなら、パネルを使ってください。** インストールは 1 つ、グラフのすぐ隣にあり、 別アプリは不要です。セットアップは [パネルガイド](/docs/docs/ja/panel) を参照。キャンバスでは ないことにエージェントを巻き込みたくなったら、あとから外側のクライアントを足してください。 ライバルではありません — パネルは下で同じサーバーと話し、1 つのセッションが両方を使えます。 デスクトップでグラフを編集しながら、スマートフォンが同じセッションを操作するのは、ハックではなく サポートされていることです。 ## 1 つのツール、複数の仕事 いくつかのツールが `action` を取ることに気づくでしょう: ```json theme={null} { "tool": "workspace", "arguments": { "action": "get" } } ``` 暗号に見えて、そうではありません。`workspace` は話題です — *どの ComfyUI インストールの話か* — `action` はその話題についてどの問いを聞いているかを言います: 読む、既定を変える、使えるものを 一覧する。 動詞と目的語が別の言葉である日常の話し方とまったく同じに読めます: | あなたが言うこと | アクション | | ------------------- | ------------- | | 「どの ComfyUI を使ってる？」 | `get` | | 「D ドライブのやつをいつも使う」 | `set_default` | | 「見えるインストールは何？」 | `list` | ### 何も削除されていない この形は比較的新しく、能力が削られたように読みやすいです。そうではありません。すでに出ている 混乱なので、正面から先回りしておきます。 かつては問いごとに 1 ツールでした — ワークスペースを読む名前、設定する別の名前、一覧するまた 別の名前。それらの名前はなく、ツール数を見ていると急に減って見えます。 実際に起きたのは、関連ツールの **統合** であり、削除ではありません: | 古い名前 | いま同じもの | | ------------------------------- | ------------------------------------------- | | `get_workspace` | `workspace` with `action: "get"` | | `get_queue` | `queue` with `action: "list"` | | `apps_run_status` | `apps` with `action: "run_status"` | | `install_workflow_dependencies` | `list_packs` with `action: "install_deps"` | | `list_workflows` | `get_workflow` with `action: "list"` | | `analyze_workflow` | `get_workflow` with `action: "analyze"` | | `validate_workflow` | `create_workflow` with `action: "validate"` | 下のコードは同じ、挙動は同じ、答えも同じ。手前のラベルだけが変わりました。 理由は、メニューが長すぎて害になったことです。各ツールの完全な説明は、選ぶ前にモデルへ渡す 必要があり、ある大きさを超えると選ぶこと自体が劣化します — 特に小さなモデルは、正しいものではなく それっぽい隣を選び始めます。明確な `action` を持つ、より少なく幅広いツールが、測定可能なほど それを直します。モデルの注意も、カタログを読むことではなくあなたの依頼に使われます。 これに気づく必要はありません。古い名前も打っていません。「どの ComfyUI にいる？」と言い、 それはいまも動きます。 古いガイドやモデル自身の記憶が、もう存在しない名前に手を伸ばすと、空白の 「unknown tool」ではなく、置き換えを名指しする具体的なエラーになります — 例: *removed in 0.49.0. Call workspace (action:"get") instead.* エージェントはたいてい 自分で直して再試行し、あなたが何かをする必要はありません。 ## 違うものを頼むとき どのツールページにもパラメータが並びます — `max_chars`、`limit`、`depth`、`fields`。 どこに打てばよいかは妥当な問いです。正直な答えは: どこにも、です。`max_chars` の設定箱は ありません。設定ではないからです。**エージェント** が、ツールを呼ぶたびに新しく埋める引数です。 それで外されるわけではありません。操作の見た目が変わります: パラメータは設定しません。頼むのです — もともと書こうとしていた同じ文の中で。 ### 頼み方は 2 通り どちらも動きます。失敗の仕方が違うので、両方知る唯一の理由があります。 | | 聞こえ方 | 手が伸びるとき | | ------ | ------------------------------------------------------------- | ------------------------------- | | **普通** | 「ノード 42 を詳しく読んで — そのノードだけ、グラフ全体じゃない。」 | いつもここから始める。人が実際に打つもので、たいてい動きます。 | | **明示** | 「`panel_query_graph` を `ids` \[42] と `max_chars` 20000 で使って。」 | モデルが一度すでに間違えて、余地を残したくないとき。 | ツールと引数を名指しするのは *正しい* 形ではありません — *強制的な* 形です。再試行のために 取っておいてください。 ### 答えが途中で切れたとき 長い読み取りには上限があり、巨大な 1 つのグラフが会話全体を飲み込めないようにしています。 同じ読み取りを止められる天井は 2 つあります — 列挙するノード数（`limit`）と文字予算 （`max_chars`）— 問題でなかったほうを上げても何も変わらず、再試行が失敗したように読めます。 どちらなのか自分で割り出す必要はありません。保存済みファイルでは、メモが **発火したレバーを 名指しし、もう一方を除外します**。そのとおりの言葉で: > … truncated at 40 of 300 by `limit`=40 — raise `limit` up to 200, or narrow with `types`/`where`/`ids`/`depth`. `max_chars` is not the constraint here. そしてレバーがすでに天井にあるときは、もう一度上げに送る代わりにそう言います。上げるものが 残っていないからです。 ライブキャンバス（`panel_query_graph`）では、同じ読み取りをパネル自身のこのエンジンの コピーが実行し、その文言にはまだ追いついていません。そこのメモが引数を名指しし、上げても 何も変わらないなら、ツールが壊れていると結論する前にもう一方を試してください。 エージェントは自分のメモを読んで自分で再試行する想定です。しないときは、あなたがフォールバック であり、この文です: > 途中で切れた — メモを読んで同じクエリを再試行し、名指しされている上限を上げて。 ### 上限はどこか 予算付きでグラフを読む 2 つのツール — `panel_query_graph`（ライブキャンバス）と `get_workflow` の `action: "query"`（保存済みファイル）— の数字です: | 引数 | 既定 | 頼める最大 | | ---------------- | ----- | ----- | | `max_chars` | 12000 | 60000 | | `limit`（列挙するノード） | 40 | 200 | この 2 つのツールでは、天井を超えた依頼は黙って切り下げられず無効な引数として拒否されるので、 エージェントはすぐに知り、自分で直せます。数字は万能でもありません: 他のいくつかのツールも `max_chars` を取り、それぞれの天井は各ツール自身の説明に書かれています。 ### 範囲のほうが予算より効く 天井を上げるのは最初ではなく 2 番目に試すことです。600 ノードのワークフローでは、大きな予算は 主に間違ったノードをもっと買います。数百の無関係なものの中に答えを埋めると、技術的に収まっていても 返信は劣化します。 先に狭めてください。自然な言葉で: | あなたが言うこと | 狭まる先 | | ------------------- | ---------- | | 「ノード 42 と 43 だけ見て。」 | それらの id だけ | | 「サンプラーに入ってくるものは何？」 | 1 ノードの上流側 | | 「…2 ホップだけ戻って。」 | そこからの有界な距離 | | 「各ノードタイプは何個ある？」 | 一覧ではなく件数 | それから、まだ切れるなら広げます。 ## 拒否されたとき ツールが拒否するのは、たいていバグではありません。ほとんどの拒否は、頼んでいないことをしそうな 呼び出しに対してガードが発火したことです。 ### 「拒否されたが理由がわからない」 スタックトレースではなく平文が見えます — やらなかったことと、代わりに何をするかを名指しする 何かです。行き詰まっているのではなく、慎重なエージェントとして読んでください。よくある正直な 拒否: * **どのワークフローか分からない。** タブが複数開いている、またはグラフにまだ保存済みの 身元がない。保存するか、どれかを言ってください。 * **何かを上書きしそう。** 新しいファイル名を頼めば進みます。 * **本当にそこにない。** モデルファイル、ノードパック、動いているサーバー。 拒否が慎重ではなくナンセンスに読めるなら、報告する価値があります — エージェントに出させて ください。セットアップの詳細を付けてくれます。 ### 「このパネルは古すぎる」 本物の直し方がある、いちばんよくある拒否です。だいたい次のように読めます: > This ComfyUI-MCP panel is too old for *"…"* — update the ComfyUI-MCP panel, then reconnect. サイドバーパネルとこのサーバーは別々に出荷される別部品なので、片方が遅れられます。サーバーが、 インストール済みパネルが安全にできないことを求めると、推測するより断ります — どのワークフローに コマンドが着地するかを確認できない古いパネルは、編集を間違ったタブに適用し得るので、更新される まで読み取りに留められます。 直し方は 3 ステップで、**3 つ目を人が飛ばします**: エージェントに更新させる（`install_comfyui(action:'panel', panel_action:'update')`）、 または ComfyUI-Manager から。そこでは `comfyui-agent-panel` として載っています。 更新は何も自分では再起動しません。エージェントに頼むか、自分で再起動してください。 **Ctrl+Shift+R**（Mac では **Cmd+Shift+R**）。ブラウザーは古いパネルコードをキャッシュ しており、再起動だけでは剥がれません。これを飛ばすと同じメッセージがすぐ戻り、更新が 失敗したように見えます。失敗していません。 ### 「パネルが接続されていません」 違う問題で、似た見た目のメッセージです。外側のエージェントが ComfyUI のブラウザータブを 見つけられないという意味です。ほぼ常に次のいずれかです: * ComfyUI がそもそもブラウザーで開いていない — 開いて、サイドバーのエージェントタブを見て ください。 * ComfyUI をちょうど再起動した、またはタブをリロードした。それで接続が落ちます。 **ComfyUI のタブをリロード** すればすぐ戻ります。 * エージェントタブは開いているが、一度も接続されていない。パネルはプロバイダーを選んで **接続** をクリックしたときに付きます。読み込み時には決して付かないので、何も出ていない 開いたばかりのタブは故障ではなく普通の状態です。 * パネルがまだインストールされていない。[パネルガイド](/docs/docs/ja/panel) を参照。 メッセージはこれらを 2 つのグループに分けます — 「以前つながっていて落ちた」と「まだ何も つながっていない」を区別します。それ以上は行かず、観察できない原因を選ぶ代わりにそう言います。 以前つながったタブは、パネルがインストール済みで動いていた証拠なので、ComfyUI タブのリロードが 最初に試すことで、たいていそれだけです。リロードで戻らなければ、2 つ目のグループとして上の 確認を下へ辿ってください。 ## 何も言わないとき より難しい失敗は、エラーがまったく入っていないものです。エージェントはツールを呼ばず、拒否せず、 文句も言いません。ただ話します: ワークフローにたぶん何が入っているかを説明する、スクリプトを 書きましょうかと申し出る。役に立ちそうに聞こえ、何も見ていません。 まったく違う 3 つの状況が同じ挙動を出し、座っている場所からは見分けがつきません: クライアントがツールを受け取っていません。モデルに渡す一覧になく、呼ぶものがありません。 クライアントはツールを持っていますが、モデルに走らせません。呼び出しはクライアントの中で 止まります。 すべて動いています。欲しかったものは、一度も話題に出ていない名前の下にあり、誰も手を伸ばして いません。 対処は 3 つの違う方向を向き、うち 2 つは当てずっぽうだと積極的に害です: すでに入っているものを 再インストールする、問題でなかった権限を緩める。なので最初の一手は何かを直すことではありません。 どれにいるかを知ることです。 ### 切り分けるための 2 つの質問 エージェントに、平文で聞いてください: > comfyui-mcp からどのツールを持ってる？ 名前だけ並べて。 数十個の名前の一覧は普通で健全です — それが直接の面で、0.50.0 以降の既定です。 **3 つの名前** — `list_tools`、`describe_tool`、`call_tool` — も *また* 普通で健全です。 それが [コンパクトモード](#小さなローカルモデルを使う場合) で、`--compact` を渡すと得られ、 小さなローカルモデルはいまも自動で選びます。カタログの残りは `list_tools` を 1 回呼べば 届くので、それを走らせてと頼めば本物の一覧が見えます。どちらの答えも、何かが隠されている 意味ではありません。 **名前がまったくない**、または「ComfyUI 用のツールは持っていない」は、3 つ目のケースを 除外するだけで、それ以外は何も除外しません。**不在を意味しません。** 権限ポリシーは、 モデルに見せる一覧からツールを隠せます。インストール済み、接続済み、動いているサーバーが まさにこの答えを出します。このステップでは不在とブロックは見分けがつかず、ユーザーに 何日もかかった枝がこれです — 配線だと確信していた。 1 つの確認が絞り込み、それはエージェントには見えません: **クライアント自身の MCP サーバー 一覧を開く** — どのサーバーに接続したかを見せる場所で、モデルに渡すツール一覧とは別です。 * **comfyui-mcp がそこにない、または失敗と出る** → **不在**。クライアント側の配線の問題で、 パネルやサーバーの故障ではありません。さらに 2 つに分かれます — 一度も配線されていない、 またはそもそも持てないホスト — [下](#それぞれの答えが通常どこから来るか) の一覧がそれを 分けます。 * **そこにあり接続済みで、モデルがまだ何も列挙しない** → ツールはクライアントに届きました。 そのあとどこで止まったかはまだ開いています: 権限ルールでモデルから隠されているか、 モデルが列挙に失敗または拒否したか。ここからはまったく同じに見えます。これだけで権限を 緩め **ないで** ください。 そのサーバー一覧が **comfyui-mcp から取ったどのツールか** も見せるなら、決まります: そこに載っていてモデルが言わないなら問題はモデルであり権限ではありません。そこに何も なければ、モデルが見る前にフィルタされています。クライアントがそれを見せない — 多くは 見せません — なら、ここでは 2 つを分けるものはなく、ステップ 2 のほうがチャンスです。 拒否は言葉で返ってくるからです。 > 動いていないことに使うほうをいま呼んで、返ってきたものをそのまま貼って — エラーも全部。 > 回避しないで。 その文の 2 つの細部が仕事をしています。 **動いていないことに使うほうのツール**、具体的に。権限ルールはたいていツールごとに書かれる ので、別のツールが成功しても気にしているほうについては何も証明しません — ブロックが隠れる のはまさにそのやり方です。読まれていないのがキャンバスなら、テストはキャンバスの読み取りで なければなりません。 **回避しないで。** 失敗モード全体が、障害を名指しせず静かに迂回するエージェントであり、 放っておけばまたそうします。 * **本物の結果** — そのツールは動きます。3 つ目のケースにいます。 * **「拒否された」/「許可されていない」/「権限が必要」** — **ブロック**、クライアントの中。 これは決定的です: エージェントが頼んで拒否されました。 * **「そのツールは持っていない」** — まだ不在 *または* ブロック。隠されたツールと欠けている ツールはモデルの席からは同じに見えるので、これだけで動かないでください: ステップ 1 の サーバー一覧に戻し、その一覧もサーバーごとのツールを見せなければ、届くもので 2 つを 分けるものはなく、正直な次の一手は設定を変え始めることではなく Issue トラッカーで聞く ことです。 * **まだ散文で、呼び出しなし** — 単刀直入に聞いてください: *「ツールを呼んだ？ 呼んでいない なら、なぜ？」* 2 回かわすエージェントはたいてい、言っていない何かを迂回しています。 ### こちらから見えること、見えないこと クライアントがツール呼び出しを拒否すると、その呼び出しはクライアントを出ません。この サーバーには何も届かず、ログにも現れず、届ける場所のどこにもエラーは出ません。ブロックは 検出できず、するふりもしません: 「クライアントがこれをブロックした」と教えるページや メッセージは、推測になります。 同じ事実は逆方向にも切れ、人を迷わせる部分です: 静かなログは、何も試されなかった証拠では ありません。不在、ブロック、頼まれていないは、こちらからはすべて沈黙に見えます。 だから上の 2 つの質問が本当の診断です。動くのは、その場に *いた* 唯一の参加者 — あなたの エージェント — に何を試したか言わせ、答えを迂回する選択肢を奪うからです。 ### それぞれの答えが通常どこから来るか **ブロック — クライアント自身の権限ルール。** Claude Code では `settings.json` の `permissions` ブロックです（`~/.claude/settings.json`、またはプロジェクトの `.claude/settings.json`）。MCP ツールは名前空間付きの名前 `mcp__comfyui__` でそこに 現れます。一度も言及しない厳しい `allow` リストは、送られる前にすべての呼び出しを止めます。 これが 1 人のユーザーに何日もかかったケースです: ツールは動いているように見えました。探して いたエラーが現れようがなかったからです。 **不在で、直せる — 一度も配線されていない。** クライアントは MCP を話しますが、このサーバーを 一度も教えられていないか、教えられて項目が間違っています。よくあるほうで、設定の編集です。 クライアントが期待する項目は [クイックスタート](/docs/docs/ja/quickstart) を参照。 **不在で、直せない — MCP クライアントがまったくないホスト。** 一部のエージェントは MCP を 話さず、どれだけ設定しても変わりません。`pi` が 1 つです: 独自の組み込みシェル / エディター ツールを持ち、MCP クライアントがないので、他に何が入っていてもこちらを渡せません。パネルは それを選ぶと率直に言います — *「pi には ComfyUI のツールがありません（MCP なし）」*。その行が 答えであり、デバッグする症状ではありません。直し方は別のバックエンドを選ぶことです。 **どちらでも — 間に座っている何か。** MCP トラフィックを運ぶゲートウェイ、プロキシ、ルーターが 面の一部だけを通すことがあります。カタログと実際に走るものが食い違うなら、真ん中を疑ってください。 ### 3 つ目のケースだった場合 何も壊れておらず、誰も設定を間違えませんでした: 能力があり、知る手段がありませんでした。 それはあなたの失敗ではなくこちら側の失敗で、教える価値があります — エージェントに出させて ください。セットアップを付けてくれます。誰も見つけられない機能は、座っている場所からは、 出荷しなかった機能です。 ## 小さなローカルモデルを使う場合 メニュー全体をモデルに渡すと、一言言う前に大量の読み取りがかかります。大きなホスト型モデルでは それで構いません。自分のマシンで動く小さなモデルでは、動くか動かないかの差になることが多いです。 なので既定では、エージェントは全セットではなく **3 つ** のツールを得ます: カタログを閲覧する 1 つ、1 つのツールを詳しく見る 1 つ、それを実行する 1 つ。必要なものを、必要なときに取り、 最初から全部は読みません。 これを得るために何かをする必要はありません — 既定です。欲しいなら操作があります: ```bash theme={null} # force the small three-tool mode npx -y comfyui-mcp --compact # or hand the model everything at once npx -y comfyui-mcp --full ``` どちらも `COMFYUI_MCP_TOOL_MODE=compact` または `COMFYUI_MCP_TOOL_MODE=full` でも設定できます。 取引は、最初の本物の動作の前に往復が少し増えることと引き換えに、考える余地が残ったモデルです。 大きなモデルはたいてい `--full` のほうが幸せです。どのモデルがどれに耐えるかは [ローカル LLM](/docs/docs/ja/local-llms) を参照してください。 ## 次のステップ インストールして、最初の画像を生成する。 ComfyUI 内のエージェントと、キャンバスにできること。 すべてのツールと、本物の呼び出しがどう見えるかの実例。 拒否ではなく、何かが本当に壊れているとき。