コンテンツにスキップ

MCP ツールリファレンス

Koharu は次の場所で MCP ツールを公開しています。

http://127.0.0.1:<PORT>/mcp

MCP サーバーは rmcp 1.5 の streamable HTTP transport を使い、GUI および HTTP API と同じプロジェクト、シーン、パイプライン状態に対して動作します。

現在の MCP サーバーが公開しているもの

現在の実装は意図的に、プロジェクトのライフサイクル、履歴レイヤー、パイプラインジョブを中心とした小さく低レベルなサーフェスだけを公開しています。フィールド単位の細かな編集は、専用ツールではなく koharu.apply に Op ペイロードを渡して行います。

ページサムネイル、画像レイヤー、フォント一覧、シーンスナップショットなど、より詳細な検査が必要な場合は HTTP API を直接使ってください。両者は同じポートで並走し、同一プロセス内の状態を共有します。

ツール

ツール 役割 パラメータ
koharu.apply 有効なシーンに Op を適用する op — JSON タグ付きの Op 値
koharu.undo 直近の op を取り消す なし
koharu.redo 直近に取り消された op を再適用する なし
koharu.open_project Koharu プロジェクトディレクトリを開く、または作成する path、任意で createName
koharu.close_project 現在のプロジェクトを閉じる なし
koharu.start_pipeline パイプライン実行を開始し jobId を返す steps[]、任意で pages[]、targetLanguage、systemPrompt、defaultFont

koharu.apply

履歴レイヤー経由でシーンに 1 つの変更を適用します。op には HTTP API の POST /history/apply が受け付けるのと同じ JSON タグ付き Op enum を渡します。代表的な variant には AddPage、RemovePage、AddNode、UpdateNode、RemoveNode、Batch があります。

レスポンスは { epoch } で、op 適用後の新しいシーン epoch を返します。

koharu.undo / koharu.redo

履歴スタックを 1 ステップずつ進めたり戻したりします。両方とも { epoch } を返し、スタック端 (取り消すまたは再適用するものがない場合) では epoch が null になります。

koharu.open_project

既存のプロジェクトディレクトリを開くか、指定パスに新しく作成します。createName を渡すとそのパス配下に新規プロジェクトを作成し、省略するとそこにある既存のものを開きます。

レスポンスはアクティブになったセッションの { name, path } を返します。

koharu.close_project

現在のセッションを閉じます。これ以降、プロジェクトを必要とする呼び出しは、別のプロジェクトを開くまで invalid request エラーを返します。

koharu.start_pipeline

バックグラウンドでパイプライン実行をスポーンします。steps はパイプラインの Registry に登録された engine id の順序付きリストです (GET /api/v1/engines で検証されます)。pages を省略するとプロジェクト内全ページが対象になり、PageId のリストを渡すと対象を絞り込めます。

レスポンスは即座に { jobId } を返します。進捗と完了は HTTP の /events ストリームに JobStarted、JobProgress、JobWarning、JobFinished として配信されます。MCP transport 自体はジョブ進捗をストリームしないので、SSE を購読してください。

推奨されるエージェントフロー

ほとんどのエージェントセッションは次のような流れになります。

  1. koharu.open_project — 管理対象のプロジェクトディレクトリを指定する
  2. HTTP 経由で GET /api/v1/scene.json を読み、シーンを確認する
  3. 次のいずれか:
    • 明示的な Op ペイロードで koharu.apply を呼び、絞り込んだ編集を行う
    • koharu.start_pipeline でエンドツーエンドのパイプラインを実行し、GET /api/v1/events を監視する
  4. HTTP 経由で POST /api/v1/projects/current/export から書き出す
  5. koharu.close_project

koharu.undo と koharu.redo は、間違った op を適用してしまい、逆 op を手で計算するより取り消した方が早いときに便利です。

関連ページ