Kavio MCP Server And AI Plugins

Status

The @kitsra/kavio-mcp package is implemented. It calls @kitsra/kavio-render for real render work and keeps Playwright, FFmpeg binaries, and process-spawning code out of MCP handlers. The same package also ships plugins/kavio-ai, a vendor-neutral skill bundle with Codex, Claude, Gemini CLI, and Antigravity manifests.

Choose A Path

Target	Use when	Install shape
`MCP`	The host can run a server and call tools.	Configure `kavio-mcp` as an MCP server.
`Skill`	The agent wants local instructions without MCP.	Emit `skills/kavio-ai/SKILL.md` from npm.
`Plugin`	The vendor supports plugin or extension manifests.	Install `plugins/kavio-ai` as the plugin root.

Architecture Boundary

@kitsra/kavio-mcp: Agent-facing MCP server, provider adapters, portable skill, and plugin manifests for Kavio workflows.
@kitsra/kavio-render: Execution layer for browser capture, FFmpeg orchestration, MP4 output, metadata, cleanup, and cancellation.
@kitsra/kavio-schema: Composition validation and versioned data contract.
@kitsra/kavio-core: Pure timeline evaluation, prop resolution, export presets, dimensions, and resource limits.
@kitsra/kavio-browser-renderer: Shared render harness and browser runtime used for preview and export parity.

Skill And Plugin Bundle

The plugin bundle lives at plugins/kavio-ai. Codex, Claude, Gemini CLI, and Antigravity each read their own manifest from that folder, while all of them share one skills/kavio-ai workflow for authoring, validating, inspecting, previewing, and rendering Kavio compositions.

CodexReads .codex-plugin/plugin.json and installs through the repo marketplace. Claude CodeReads .claude-plugin/plugin.json or a marketplace entry pointing at the bundle. Gemini CLIReads gemini-extension.json when the bundle is installed as an extension root. AntigravityReads plugin.json when the bundle is installed as a plugin root.

Install Paths

Use the smallest install path that fits the host.

Generic Skill

pnpm dlx @kitsra/kavio-mcp emit-skill --out ./skills

Writes ./skills/kavio-ai/SKILL.md.

Codex

codex plugin marketplace add .

The marketplace points Codex at ./plugins/kavio-ai.

Claude Code

claude --plugin-dir ./plugins/kavio-ai

Or install kavio-ai@kavio-local from the local marketplace.

Gemini CLI

gemini extensions install ./plugins/kavio-ai

For remote install, publish the bundle with gemini-extension.json at the root.

Antigravity

agy plugin install ./plugins/kavio-ai

For remote install, publish the bundle with plugin.json at the root.

The published @kitsra/kavio-mcp package mirrors this bundle under plugins/kavio-ai.

Tools

The MCP catalog exposes these workflows so agents can build and repair Kavio compositions reliably.

validate_compositionReturn structured schema, prop, timing, asset, and export errors. inspect_compositionSummarize duration, dimensions, layers, assets, audio, exports, transition windows, and browser/FFmpeg support with native filter names or fallback reasons. migrate_compositionNo-op current schema documents and fail clearly for unsupported versions. resolve_propsResolve template placeholders from supplied prop values. list_export_presetsReturn standard reels, square, and landscape presets. plan_renderExpand jobs, report direct-render eligibility and reasons, then assemble the matching FFmpeg-direct or browser-overlay plan without touching binaries. renderCall the render package for local video output when binaries are available.

inspect_composition keeps transition names portable while exposing renderer capability per overlap window. Agents can select the native path when a filter is present or preserve browser fidelity when a reason is returned.

{
  "transitionType": "cover",
  "renderSupport": {
    "browser": { "supported": true },
    "ffmpegDirect": { "supported": true, "filter": "coverleft" }
  }
}

Error Contract

MCP responses should preserve Kavio's structured error shape so agents can repair documents without scraping prose.

{
  "code": "SCHEMA_VALIDATION_FAILED",
  "severity": "error",
  "message": "Layer duration exceeds composition duration.",
  "path": "/layers/2/durationFrames",
  "stage": "validate",
  "hint": "Reduce durationFrames or extend the composition.",
  "retryable": false
}

Safety And Supply Chain

Keep binary execution quarantined in @kitsra/kavio-render.
Do not let MCP handlers spawn FFmpeg, launch browsers, or download assets outside the approved render layer.
Return structured validation errors before any render work begins.
Thread cancellation through long-running preview and render operations.
Respect the repository package-manager age gate for any dependency changes.
Keep default verification binary-free; put real render smoke tests behind a gated job.

Agent Workflow

Generate or update a Kavio composition.
Validate the composition and collect all repairable errors.
Inspect the document to confirm dimensions, duration, assets, layers, audio, and exports.
Preview locally for layout and timing checks.
Render through @kitsra/kavio-render.
Return output metadata, checksums, and any structured errors to the agent.

Kavio MCP server and AI plugins.