---
title: Referência das ferramentas MCP
---

# Referência das ferramentas MCP

O Koharu expõe ferramentas MCP em:

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

O servidor MCP usa o transporte HTTP streamable do `rmcp 1.5` e opera sobre o mesmo estado de projeto, cena e pipeline que a GUI e a API HTTP.

## O que o servidor MCP expõe hoje

A implementação atual expõe deliberadamente uma superfície pequena e de baixo nível, centrada no ciclo de vida do projeto, na camada de histórico e nos jobs de pipeline. Edições granulares passam por `koharu.apply` com um payload `Op`, em vez de ferramentas dedicadas por campo.

Se você precisa de inspeção mais rica (thumbnails de página, camadas de imagem, listas de fontes, snapshots de cena), use a [API HTTP](http-api.md) diretamente. As duas rodam lado a lado na mesma porta e compartilham um único estado in-process.

## Ferramentas

| Ferramenta              | Finalidade                                              | Parâmetros                                                                       |
| ----------------------- | ------------------------------------------------------- | -------------------------------------------------------------------------------- |
| `koharu.apply`          | aplica um `Op` à cena ativa                             | `op` — valor `Op` com tag JSON                                                   |
| `koharu.undo`           | reverte a op mais recente                               | nenhum                                                                           |
| `koharu.redo`           | reaplica a op mais recente desfeita                     | nenhum                                                                           |
| `koharu.open_project`   | abre ou cria um diretório de projeto Koharu             | `path`, `createName` opcional                                                    |
| `koharu.close_project`  | fecha o projeto ativo                                   | nenhum                                                                           |
| `koharu.start_pipeline` | inicia uma execução de pipeline; retorna um `jobId`     | `steps[]`, `pages[]` opcional, `targetLanguage`, `systemPrompt`, `defaultFont`   |

### `koharu.apply`

Aplica uma única mutação à cena, passando pela camada de histórico. O valor de `op` é o mesmo enum `Op` com tag JSON que a API HTTP aceita em `POST /history/apply` — variantes comuns incluem `AddPage`, `RemovePage`, `AddNode`, `UpdateNode`, `RemoveNode` e `Batch`.

Retorna `{ epoch }` — o novo epoch da cena após a op ser aplicada.

### `koharu.undo` / `koharu.redo`

Andam um passo na pilha de histórico em qualquer direção. Ambas retornam `{ epoch }`, onde `epoch` é `null` num limite da pilha (nada mais para desfazer ou refazer).

### `koharu.open_project`

Abre um diretório de projeto existente ou cria um no caminho informado. Passe `createName` para criar um novo projeto sob o caminho; omita para abrir o que já estiver lá.

Retorna `{ name, path }` para a sessão agora ativa.

### `koharu.close_project`

Fecha a sessão atual. Chamadas seguintes que exigem um projeto retornam um erro `invalid request` até que outro projeto seja aberto.

### `koharu.start_pipeline`

Dispara uma execução de pipeline em background. `steps` é uma lista ordenada de ids de engines registradas no `Registry` do pipeline (validados contra `GET /api/v1/engines`). Omita `pages` para rodar em todas as páginas do projeto; passe uma lista de `PageId`s para limitar a execução a um subconjunto.

Retorna `{ jobId }` imediatamente. O progresso e a conclusão são publicados no stream HTTP `/events` como `JobStarted`, `JobProgress`, `JobWarning` e `JobFinished`. O próprio transporte MCP não faz streaming do progresso do job — para isso, você acompanha o SSE.

## Fluxo de agente sugerido

A maioria das sessões de agente segue mais ou menos isto:

1. `koharu.open_project` — aponta para um diretório de projeto gerenciado
2. lê `GET /api/v1/scene.json` via HTTP para inspecionar a cena
3. seja:
    - aplique edições pontuais via `koharu.apply` com payloads `Op` explícitos, ou
    - rode um pipeline ponta a ponta via `koharu.start_pipeline` e acompanhe `GET /api/v1/events`
4. exporte via `POST /api/v1/projects/current/export` por HTTP
5. `koharu.close_project`

`koharu.undo` e `koharu.redo` são úteis quando uma op se mostra errada e você quer voltar atrás em vez de calcular o inverso na mão.

## Páginas relacionadas

- [Configurar clientes MCP](../how-to/configure-mcp-clients.md)
- [Executar modos GUI, Headless e MCP](../how-to/run-gui-headless-and-mcp.md)
- [Referência da API HTTP](http-api.md)