Ir para o conteúdo

Referência das ferramentas MCP

O Koharu expõe ferramentas MCP em:

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