---
title: MCP ツールリファレンス
---

# MCP ツールリファレンス

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

```text
http://127.0.0.1:<PORT>/mcp
```

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

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

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

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

## ツール

| ツール                  | 役割                                                       | パラメータ                                                                       |
| ----------------------- | ---------------------------------------------------------- | -------------------------------------------------------------------------------- |
| `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 を手で計算するより取り消した方が早いときに便利です。

## 関連ページ

- [MCP クライアントを設定する](../how-to/configure-mcp-clients.md)
- [GUI / Headless / MCP モードを使う](../how-to/run-gui-headless-and-mcp.md)
- [HTTP API リファレンス](http-api.md)