# プロジェクトとワークフロー

> AI アシスタントが Nodaro のワークフローを JSON で構築し、バージョンの確認で安全に編集し、エクスポートとインポートで移動して、mcp プロジェクトで実行できます。

Source: https://nodaro.ai/ja/docs/mcp/tools/projects-and-workflows

**プロジェクトとワークフローのツール**を使うと、アシスタントは、エディターが保存するのと同じ形式で Nodaro のワークフローを構築できます。つまり、JSON のノードと接続です。アシスタントは、`start_workflow_editor` と `get_node_skill` で形式を学び、ワークフローを作成、編集します。そして、エクスポートとインポートでワークフローをプロジェクト間で移動し、実行します。アシスタントが作成または編集するワークフローはすべて [mcp プロジェクト](https://nodaro.ai/docs/mcp/tools#the-mcp-project)に置かれるため、自分のプロジェクトには手が加わりません。

## 典型的なセッション
### 形式を学ぶ
`start_workflow_editor` を呼び出します。このツールは、ワークフローの JSON の構造、接続をつなぐルール、ノードタイプのカタログを返します。ワークフローに必要なノードタイプごとに `get_node_skill` を呼び出し、各ピッカーの有効な値は `get_picker_catalog` で取得します。

### ワークフローを作成する
名前と、必要に応じて最初のノードと接続を指定して、`create_workflow` を呼び出します。作成したワークフローは、**MCP のワークフロー**からエディターで開けます。

### 安全に編集する
`get_workflow_json` で現在のグラフを読み取ります。次に、読み取ったバージョンを付けて、`update_workflow_json` に `delta` を送ります。変更されるのは、指定したノードと接続だけです。

### 実行する
`run_workflow` を呼び出し、[`get_app_run`](https://nodaro.ai/docs/mcp/tools/gallery-and-assets#get_app_run) で実行を追跡します。各ノードの結果は、ライブラリに保存されます。

## `start_workflow_editor`
アシスタントがワークフローを構築または編集する前に読む、ガイドを返します。ガイドでは、ワークフローの JSON の構造、接続と入力をつなぐ際の決まり、`update_workflow_json` のルールを説明しています。また、すべての生成ノードの結果フィールドと、ノードタイプのカタログも記載しています。

**権限**：不要（常に表示されます）。**クレジット**：無料。

このツールにパラメーターはありません。何も変更しないので、何度でも呼び出せます。

## `get_node_skill`
1 つのノードタイプについて、完全なガイドを返します。データフィールドとそのデフォルト値、使いどころ、よくある間違い、JSON の実例が含まれます。そのタイプのノードをワークフローに書き込む前に使います。

**権限**：不要（常に表示されます）。**クレジット**：無料。

| パラメーター | 型 | 説明 |
| --- | --- | --- |
| `node_type` | string | **必須**。`start_workflow_editor` に一覧表示される、ケバブケースのノードタイプです。たとえば `generate-image`、`list`、`trim-video` です。 |

**戻り値**：ノードのガイドです。不明なタイプを指定すると、有効なタイプの一覧とともにエラーが返されます。

## `get_picker_catalog`
**舞台設定**（Setting）、**ムード**（Mood）、**人物**（Person）、**レンズ**（Lens）などのピッカーノードについて、有効な値を返します。ピッカーは、接続先のノードのプロンプトにフレーズを追加します。そのため、ワークフローでは、カタログに実在する ID を使う必要があります。ピッカーの値をワークフローに書き込む前に、このツールを呼び出してください。

**権限**：不要（常に表示されます）。**クレジット**：無料。

| パラメーター | 型 | 説明 |
| --- | --- | --- |
| `node_type` | string | ケバブケースのピッカーのタイプです。たとえば `setting` です。省略すると、すべてのピッカーを一覧表示します。 |
| `detail` | string | `compact`（デフォルト）は、`id`、`label`、`category`、`term`、`icon`、`imageUrl` を返します。`full` では、各選択肢の `description` と `promptHint` も加わります。`promptHint` は、選択肢がプロンプトに追加する完全なフレーズです。 |
| `category` | string | 単一ディメンションのピッカーで使います。1 つのカテゴリーの選択肢だけを返します。 |
| `field` | string | マルチディメンションのピッカーの、1 つのディメンションだけを返します。たとえば**人物**、**スタイリング**（Styling）、**フレーミング**（Framing）で使います。単一ディメンションのピッカーの追加設定も返せます。たとえば、**トランジション**（Transition）と**キャラクター FX**（Character FX）の位置、長さ、強さや、**キャラクターモーション**（Character Motion）の位置とペースです。 |

**戻り値**：`node_type` を指定しない場合は、すべてのピッカーの一覧です。各ピッカーの `nodeType`、`label`、`kind`（`single` か `multi`）、値のフィールド、`optionCount`、`imageCount` が含まれます。`node_type` を指定した場合は、そのピッカーの選択肢です。不明なタイプを指定すると、有効なタイプとともにエラーが返されます。

どの選択肢にも `term` があります。`term` は、`whip pan left` のように、プロンプトに書き込む短い専門的なフレーズです。`label` は表示専用です。`auto` や `none` のように何もしない選択肢では、`term` は空です。画像のある選択肢には、絶対 URL の `imageUrl` が付きます。この URL はそのまま表示し、ID から URL を組み立てないでください。**人物**と**スタイリング**は、`sections` も返します。`sections` はトピックを順に並べたもので、それぞれにラベル、フィールド、任意の画像があります。

```json
{
"nodeType": "person",
"sections": [
{ "label": "Identity", "fields": ["type", "age", "ethnicity", "regionalAesthetic"],
"imageUrl": "https://app.nodaro.ai/picker-art/character/sections/identity.2d5ec1a4.webp" }
],
"dimensions": [
{ "field": "type", "label": "Type", "options": [
{ "id": "man", "label": "Man", "term": "man",
"imageUrl": "https://app.nodaro.ai/picker-art/character/person/man.441363db.webp" }
] }
]
}
```

ルックのピッカーの画像は、Nodaro Cloud でのみ返されます。開発者向けの同じデータは、[ピッカーカタログ](https://nodaro.ai/docs/developers/picker-catalogs)で説明しています。

## `list_projects`
アカウント内のすべてのプロジェクトを、名前順に一覧表示します。各プロジェクトの ID、名前、説明、ワークフローの数、作成日が含まれます。アシスタントはすべてのプロジェクトを読み取れますが、編集できるのは mcp プロジェクトだけです。

**権限**：`workflows:read`。**クレジット**：無料。

このツールにパラメーターはありません。

**戻り値**：プロジェクトの一覧である `data` です。

## `get_project`
ID または名前で指定した、1 つのプロジェクトを返します。

**権限**：`workflows:read`。**クレジット**：無料。

| パラメーター | 型 | 説明 |
| --- | --- | --- |
| `project_id` | string | **必須**。プロジェクトの ID または名前です。名前は、大文字と小文字も含めて完全に一致する必要があります。たとえば `My Feature Film` です。 |

**戻り値**：プロジェクトの ID、名前、説明、ワークフローの数、作成日です。

## `list_workflows`
mcp プロジェクト内のワークフローを、新しい順に一覧表示します。

**権限**：`workflows:read`。**クレジット**：無料。

| パラメーター | 型 | 説明 |
| --- | --- | --- |
| `limit` | integer | 1〜100 です。デフォルトは `20` です。 |
| `cursor` | string | 前のページの `next_cursor` です。 |
| `include_sub_workflows` | boolean | デフォルトは `false` です。この場合、エディターのプロジェクト表示と同じように、別のワークフローに属するサブワークフローは表示されません。サブワークフローも一覧表示するには、`true` を渡します。 |

**戻り値**：`data` と `next_cursor` です。`data` には、各ワークフローの ID、名前、説明、バージョン、サムネイル、日付が含まれます。`next_cursor` が `null` の場合は、最後のページです。

## `get_workflow`
mcp プロジェクト内の 1 つのワークフローについて、詳細を返します。名前、説明、バージョン、日付です。

**権限**：`workflows:read`。**クレジット**：無料。

| パラメーター | 型 | 説明 |
| --- | --- | --- |
| `workflow_id` | string | **必須**。mcp プロジェクト内のワークフローの ID です。 |

## `get_workflow_json`
mcp プロジェクト内のワークフローについて、グラフ全体を返します。ノード、接続、設定、名前、`updated_at`、`version` です。

**権限**：`workflows:read`。**クレジット**：無料。

| パラメーター | 型 | 説明 |
| --- | --- | --- |
| `workflow_id` | string | **必須**。mcp プロジェクト内のワークフローの ID です。 |

**戻り値**：グラフです。`version` を保持し、次の変更と一緒に送り返してください。そうすれば、ほかの人の編集を上書きする代わりに、変更が失敗します。

## `create_workflow`
mcp プロジェクトにワークフローを作成します。空のワークフローも、最初のグラフを含むワークフローも作成できます。

**権限**：`workflows:write`。**クレジット**：無料。

| パラメーター | 型 | 説明 |
| --- | --- | --- |
| `name` | string | **必須**。1〜200 文字です。 |
| `description` | string | 最大 2,000 文字です。 |
| `nodes` | array | 最初のノードです。エディターのノード形式で指定します。 |
| `edges` | array | 最初の接続です。 |
| `settings` | object | ワークフローの設定です。 |

**戻り値**：新しいワークフローの `id` と `name` です。モデルが対応していない設定は、[update_workflow_json](#update_workflow_json) で説明しているとおりに修正されます。

## `update_workflow_json`
mcp プロジェクト内のワークフローの、グラフ、設定、サムネイルを変更します。`workflow_id` 以外のフィールドはすべて任意なので、たとえばサムネイルだけを変更することもできます。

**権限**：`workflows:write`。**クレジット**：無料。

| パラメーター | 型 | 説明 |
| --- | --- | --- |
| `workflow_id` | string | **必須**。mcp プロジェクト内のワークフローの ID です。 |
| `delta` | object | 部分的な変更です。`delta.base_version` に対して、1 回の操作として適用されます。推奨される編集方法です。下記を参照してください。 |
| `nodes` | array | すべてのノードを置き換えます。`edges` と一緒に送ります。 |
| `edges` | array | すべての接続を置き換えます。`nodes` と一緒に送ります。 |
| `settings` | object | ワークフローの設定を置き換えます。 |
| `thumbnail_url` | string or null | すでにホストされている画像の URL です。サムネイルを削除するには、`null` を指定します。 |
| `expected_version` | integer | `get_workflow_json` で取得した `version` です。その後ワークフローが変更されていた場合、変更は拒否されます。 |
| `expected_updated_at` | string | `get_workflow_json` で取得した `updated_at` です。同じ確認を行う、以前からの方法です。`expected_version` を使うことをおすすめします。 |

**戻り値**：ノードの数を含む確認メッセージと、Nodaro が修正した設定の一覧です。

### delta で編集する
`delta` では、変更するものだけを ID で指定します。`nodes`、`edges`、`settings`、`thumbnail_url`、`expected_` で始まるフィールドとは組み合わせられません。

| delta のフィールド | 動作 |
| --- | --- |
| `base_version` | **必須**。`get_workflow_json` で取得した `version` です。その後ワークフローが変更されていた場合、変更は拒否されます。 |
| `upsert_nodes` | 追加または置き換えるノード全体です。ID で照合されます。 |
| `delete_node_ids` | 削除するノードです。その接続も削除されます。 |
| `upsert_edges` | 追加または置き換える接続全体です。ID で照合されます。 |
| `delete_edge_ids` | 削除する接続です。 |
| `set` | 新しい `name`、または古い設定を置き換える新しい `settings` です。 |

グラフ全体を送るより、delta を使ってください。古いコピーをもとにグラフ全体を書き込むと、その間に別のセッションが行った変更が消えてしまいます。

### その間にワークフローが変更された場合
`expected_version`、`expected_updated_at`、または delta を使う場合、読み取った後にワークフローが変更されていると、競合が返されます。メッセージは「Workflow was modified since you last read it. Fetch the latest JSON with get_workflow_json and retry.」です。ワークフローを読み取り直し、変更をやり直してください。これらのフィールドがない場合、書き込みは無条件にワークフローを上書きします。

### モデルが対応していない設定
画像ノードは、`aspectRatio`、`resolution`、`quality` などのモデル固有の設定を受け付けます。使える値は、モデルごとに異なります。モデルが受け付けない値をノードが指定していても、Nodaro は書き込みを拒否しません。値をモデルが対応している値に変更するか、モデルにその設定がない場合は削除します。そして、応答に次のように各変更を一覧表示します。

```text
Updated workflow 4f0c… (12 nodes).

Adjusted 2 parameter(s) the selected model does not accept:
  - node_8 (gpt-image): aspectRatio "16:9" → "1:1" — GPT Image 1.5 does not
support aspect_ratio "16:9". Supported: 1:1, 3:2, 2:3.
  - node_8 (gpt-image): resolution "2K" → removed — GPT Image 1.5 has no
resolution setting.
```

構造化された結果には、同じ一覧が `adjustments` として含まれます。保存された値は送った値とは異なるので、元の値を送り直さないでください。各モデルで使える値は [`list_models`](https://nodaro.ai/docs/mcp/tools/models-and-credits#list_models) で確認するか、必要な設定に対応したモデルを選んでください。`create_workflow` と `import_workflow` も、同じように設定を修正します。複数のモデルが同時に設定されたノードは、そのまま残ります。

### プロンプトの前後のテキスト
どの AI ノードの `data` にも、`promptPrefix` と `promptSuffix` を含められます。これは、ノードの実行時に Nodaro がプロンプトの前後に追加するテキストです。[プロンプトの前後のテキスト](https://nodaro.ai/docs/concepts/prompt-pre-post-text)を参照してください。

### スタジオプロダクション
スタジオプロダクションを含むワークフローは、シーンと結果を `settings.studio` に保持します。`settings.studio` を変更または削除する設定の変更は拒否されます。`get_workflow_json` で取得した値をそのままコピーするか、`settings` を省略してください。プロダクションを変更するには、[スタジオプロダクションのツール](https://nodaro.ai/docs/mcp/tools/studio-productions)を使います。

## `delete_workflow`
mcp プロジェクトからワークフローを削除します。削除は元に戻せません。

**権限**：`workflows:write`。**クレジット**：無料。

| パラメーター | 型 | 説明 |
| --- | --- | --- |
| `workflow_id` | string | **必須**。mcp プロジェクト内のワークフローの ID です。 |

**戻り値**：確認メッセージです。ワークフローが mcp プロジェクトにない場合は、エラーが返されます。

## `export_workflow`
どのプロジェクトにあるワークフローでも、自分のワークフローなら、持ち運べる JSON バンドルとしてエクスポートします。mcp プロジェクトに限定されないワークフローツールは、これだけです。

**権限**：`workflows:read`。**クレジット**：無料。

| パラメーター | 型 | 説明 |
| --- | --- | --- |
| `workflow_id` | string | **必須**。自分のワークフローであれば、どれでも指定できます。 |
| `with_assets` | boolean | デフォルトは `false` です。`true` にすると、ワークフローが使うキャラクター、オブジェクト、ロケーションもバンドルに含めます。 |

**戻り値**：JSON 文字列としてのバンドルです。この文字列全体を `import_workflow` に渡します。

| モード | バンドルの内容 | 用途 |
| --- | --- | --- |
| テンプレート（`with_assets: false`） | グラフのみ。アセット固有の内容は含みません | ワークフローの構造を、再利用できるテンプレートとして共有する |
| フル（`with_assets: true`） | グラフと、グラフが使うすべてのキャラクター、オブジェクト、ロケーション | 完成したプロダクションを、別のアカウントやインスタンスに移動する |

ノードが、別のインスタンスからはダウンロードできないメディアを使っている場合があります。たとえば、セルフホスティング環境のローカルストレージにあるファイルです。その場合、バンドルは `portability.unreachableMedia` に、そのメディアをノード、フィールド、URL とともに一覧表示します。バンドルはそれでもインポートできますが、メディアをもう一度アップロードするまで、それらのノードはほかの環境では実行できません。

## `import_workflow`
`export_workflow` で作ったバンドルを、mcp プロジェクトにインポートします。

**権限**：`workflows:write`。**クレジット**：無料。

| パラメーター | 型 | 説明 |
| --- | --- | --- |
| `workflow_json` | string | **必須**。`export_workflow` で取得した JSON 文字列全体です。 |

**戻り値**：新しいワークフローの `id` と `name`、そして `importReport` です。`importReport` には、コピーされたメディア、そのまま残されたメディア、スキップされたメディアが示されます。

- **メディアはコピーされます**。ほかのホストにあるメディアは、アクセスできる場合にこのインスタンスへコピーされ、ワークフローはそのコピーを使って実行されます。上限は、グラフのファイルが 25 個、バンドルしたアセットのファイルがさらに 25 個です。画像は 20 MB まで、動画とオーディオは 50 MB までです。このインスタンスからアクセスできないプライベートなホストにあるメディアは、そのまま残され、`unreachable` として一覧表示されます。
- **アセットは作成し直されます**。バンドルに含まれるキャラクター、オブジェクト、クリーチャー、ロケーションは、新しい ID でアカウントに作成し直されます。アセットノードと、グラフや設定の中のすべての `@` メンションは、新しいコピーを指します。`assetIdMap` は、古い ID を新しい ID に対応付けます。
- **コピーはストレージの容量を使います**。バンドルに含まれるアセットの画像は、自分のストレージにコピーされます。ストレージがいっぱいの場合は、作成されなかったアセットが `assetsSkipped` に示されます。その場合も、ワークフロー自体はインポートされます。

## `run_workflow`
mcp プロジェクトのワークフローを、エディターでの実行とまったく同じように実行します。

**権限**：`workflows:execute`。**クレジット**：実行されるすべてのノードのクレジットです。料金はエディターと同じです。

| パラメーター | 型 | 説明 |
| --- | --- | --- |
| `workflow_id` | string | **必須**。mcp プロジェクト内のワークフローの ID です。 |
| `inputs` | object | この実行での変更で、ノード ID をキーにして指定します。`"blue car"` のような単純な値は、ノードのメインの入力フィールドに入ります。`{ "prompt": "..." }` のようなオブジェクトでは、名前を指定したフィールドを設定します。 |
| `client_request_id` | string | 再試行用のトークンで、英字、数字、`_ - . :` からなる 8〜128 文字です。タイムアウトの後に再試行するときは、同じ値を使います。そうすれば、実行の開始や課金が 2 回行われることはありません。新しい実行には、新しい値を使います。 |

**戻り値**：`executionId` と `name` です。実行は [`get_app_run`](https://nodaro.ai/docs/mcp/tools/gallery-and-assets#get_app_run) で追跡し、失敗の原因は [`diagnose_run`](https://nodaro.ai/docs/mcp/tools/jobs#diagnose_run) で調べます。MCP Apps に対応したクライアントでは、実行の進行状況がカードに表示されます。

## Frequently asked questions

### アシスタントは、自分のプロジェクトにあるワークフローを編集できますか？

いいえ。ワークフローツールで編集、実行できるのは、mcp プロジェクト内のワークフローだけです。ほかのワークフローを扱うには、アシスタントが export_workflow でエクスポートし、import_workflow でコピーをインポートします。

### アシスタントは、ワークフローの形式をどのように学びますか？

最初に start_workflow_editor を呼び出します。このツールは、ワークフローの JSON の構造、接続のルール、ノードタイプの一覧を返します。次に、使いたいノードタイプごとに get_node_skill を呼び出します。

### 2 つのセッションが同じワークフローを編集すると、どうなりますか？

get_workflow_json で取得したバージョンを expected_version として渡すか、base_version を付けた delta を送ってください。その間にワークフローが変更されていた場合、書き込みは拒否され、何も上書きされません。

### モデルが対応していない設定をワークフローで指定すると、どうなりますか？

Nodaro は、エラーにする代わりに設定を修正します。対応していないアスペクト比、解像度、品質は、対応している値に変更されるか、削除されます。すべての変更は、応答の adjustments に一覧表示されます。

### MCP でワークフローを実行すると、エディターより費用がかかりますか？

いいえ。run_workflow で使われるクレジットは、エディターでの実行と同じです。ワークフローの構築、読み取り、編集は無料です。