Skip to content

MCP Tools Reference

Koharu exposes MCP tools at:

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 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 PageIds 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.