MCP server

@miraiclip/mcp serves one project file over MCP (stdio). An agent can read the project, apply commands, undo, look at rendered frames, and export. Every successful edit is saved to the file.

npx @miraiclip/mcp --project ./video.json --assets ./media

The project file is created if it doesn't exist. Previews and exports run in headless Chrome through @miraiclip/server-export.

FlagsCopy Anchor Link

MP4 export needs Google Chrome. WebM works with any Chromium. See The browser.

Connect a clientCopy Anchor Link

Claude DesktopCopy Anchor Link

Add the server to claude_desktop_config.json, then restart Claude Desktop. Use absolute paths.

{
  "mcpServers": {
    "miraiclip": {
      "command": "npx",
      "args": ["-y", "@miraiclip/mcp", "--project", "/path/to/video.json", "--assets", "/path/to/media"]
    }
  }
}

Claude CodeCopy Anchor Link

claude mcp add miraiclip -- npx -y @miraiclip/mcp --project ./video.json --assets ./media

Everything after -- is the server command.

Other clientsCopy Anchor Link

Any client that launches stdio MCP servers works the same way: command npx, arguments -y @miraiclip/mcp --project …. For example, Codex (~/.codex/config.toml):

[mcp_servers.miraiclip]
command = "npx"
args = ["-y", "@miraiclip/mcp", "--project", "/path/to/video.json"]

ToolsCopy Anchor Link

All times are integer microseconds. The tool descriptions tell the model so.

ErrorsCopy Anchor Link

A failed dispatch or apply_commands changes nothing and returns isError: true. dispatch returns the failure from tryDispatch:

{
  "kind": "rejected",
  "commandType": "clip/move",
  "code": "clip-not-found",
  "message": "Command \"clip/move\" rejected (clip-not-found): no clip \"nope\""
}

apply_commands returns the applyCommands result, { ok: false, applied: 0, failedIndex, error }, so the model knows which command to fix.

PreviewsCopy Anchor Link

preview_frame renders through the export pipeline, so the frame matches the exported file. Without width and height, the longest side is capped at 768 px. The first call starts headless Chrome; later calls reuse it.

ExportCopy Anchor Link

The file streams to disk. The tool returns { ok, filePath, bytesWritten }.

A typical sessionCopy Anchor Link

1. get_state: read the composition and its ids.
2. apply_commands: make the edit as one batch, for example asset/add, track/add, clip/add.
3. preview_frame at the moments that matter, to check the result.
4. undo if it's wrong, or export when it's right.

NotesCopy Anchor Link

Embed itCopy Anchor Link

The package exports the pieces for your own server. To run it over MCP yourself, also install @modelcontextprotocol/sdk.

import { ProjectSession, callTool, createMcpServer, listTools } from "@miraiclip/mcp";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";

const session = await ProjectSession.open({ projectPath: "./video.json", assetsDir: "./media" });

// As an MCP server
const server = createMcpServer(session);
await server.connect(new StdioServerTransport());

// Or call the tools directly
listTools(session).map((tool) => tool.name);
const result = await callTool(session, "get_state", {});