| --- |
| title: MCP Tools Reference |
| --- |
| |
| # MCP Tools Reference |
|
|
| Koharu exposes MCP tools at: |
|
|
| ```text |
| http://127.0.0.1:<PORT>/mcp |
| ``` |
|
|
| The MCP server uses the streamable HTTP transport from `rmcp 1.5` and operates on the same project, scene, and pipeline state as the GUI and HTTP API. |
|
|
| ## What the MCP server exposes today |
|
|
| The current implementation deliberately exposes a small, low-level surface centred on the project lifecycle, the history layer, and pipeline jobs. Fine-grained edits go through `koharu.apply` with an `Op` payload rather than dedicated per-field tools. |
|
|
| If you need richer inspection (page thumbnails, image layers, font lists, scene snapshots), use the [HTTP API](http-api.md) directly. The two run side-by-side on the same port and share a single in-process state. |
|
|
| ## Tools |
|
|
| | Tool | Purpose | Parameters | |
| | ----------------------- | -------------------------------------------------------- | -------------------------------------------------------------------------------- | |
| | `koharu.apply` | apply an `Op` to the active scene | `op` — JSON-tagged `Op` value | |
| | `koharu.undo` | revert the most recent op | none | |
| | `koharu.redo` | re-apply the most recent undone op | none | |
| | `koharu.open_project` | open or create a Koharu project directory | `path`, optional `createName` | |
| | `koharu.close_project` | close the active project | none | |
| | `koharu.start_pipeline` | start a pipeline run; returns a `jobId` | `steps[]`, optional `pages[]`, `targetLanguage`, `systemPrompt`, `defaultFont` | |
|
|
| ### `koharu.apply` |
|
|
| Applies a single mutation to the scene through the history layer. The `op` value is the same JSON-tagged `Op` enum the HTTP API accepts at `POST /history/apply` — common variants include `AddPage`, `RemovePage`, `AddNode`, `UpdateNode`, `RemoveNode`, and `Batch`. |
|
|
| Returns `{ epoch }` — the new scene epoch after the op is applied. |
|
|
| ### `koharu.undo` / `koharu.redo` |
|
|
| Walk the history stack one step in either direction. Both return `{ epoch }` where `epoch` is `null` at a stack boundary (nothing left to undo or redo). |
|
|
| ### `koharu.open_project` |
| |
| Opens an existing project directory or creates one at the supplied path. Pass `createName` to create a new project under the path; omit it to open whatever is already there. |
| |
| Returns `{ name, path }` for the now-active session. |
| |
| ### `koharu.close_project` |
|
|
| Closes the current session. Subsequent calls that require a project return an `invalid request` error until another project is opened. |
|
|
| ### `koharu.start_pipeline` |
| |
| Spawns a pipeline run in the background. `steps` is an ordered list of engine ids registered through the pipeline `Registry` (validated against `GET /api/v1/engines`). Omit `pages` to run on every page in the project; pass a list of `PageId`s to scope the run to a subset. |
| |
| Returns `{ jobId }` immediately. Progress and completion are published on the HTTP `/events` stream as `JobStarted`, `JobProgress`, `JobWarning`, and `JobFinished`. The MCP transport itself does not stream job progress — you watch SSE for that. |
| |
| ## Suggested agent flow |
| |
| Most agent sessions look like this: |
| |
| 1. `koharu.open_project` — point at a managed project directory |
| 2. read `GET /api/v1/scene.json` over HTTP to inspect the scene |
| 3. either: |
| - apply scoped edits via `koharu.apply` with explicit `Op` payloads, or |
| - run an end-to-end pipeline via `koharu.start_pipeline` and watch `GET /api/v1/events` |
| 4. export through `POST /api/v1/projects/current/export` over HTTP |
| 5. `koharu.close_project` |
|
|
| `koharu.undo` and `koharu.redo` are useful when an op turns out to be wrong and you want to back out instead of computing the inverse manually. |
|
|
| ## Related pages |
|
|
| - [Configure MCP Clients](../how-to/configure-mcp-clients.md) |
| - [Run GUI, Headless, and MCP Modes](../how-to/run-gui-headless-and-mcp.md) |
| - [HTTP API Reference](http-api.md) |
|
|
