@kitsra/kavio-mcp 0.1.1 → 0.1.3

package/dist/bin.js

@@ -1,12 +1,14 @@
 #!/usr/bin/env node
-import { mkdir, writeFile } from "node:fs/promises";
-import { resolve } from "node:path";
+import { cp, mkdir, writeFile } from "node:fs/promises";
+import { dirname, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { toAnthropicTools } from "./adapters/anthropic.js";
 import { toGeminiTools } from "./adapters/gemini.js";
 import { toOpenAITools } from "./adapters/openai.js";
 import { createCatalog } from "./catalog.js";
 import { createServer } from "./server.js";
+const packageRoot = resolve(dirname(fileURLToPath(import.meta.url)), "..");
 async function emitAdapters(outDir) {
     const tools = createCatalog().tools;
     await mkdir(outDir, { recursive: true });
@@ -14,6 +16,12 @@ async function emitAdapters(outDir) {
     await writeFile(resolve(outDir, "openai.tools.json"), `${JSON.stringify(toOpenAITools(tools), null, 2)}\n`);
     await writeFile(resolve(outDir, "gemini.tools.json"), `${JSON.stringify(toGeminiTools(tools), null, 2)}\n`);
 }
+async function emitSkill(outDir) {
+    const source = resolve(packageRoot, "plugins", "kavio-ai", "skills", "kavio-ai");
+    const destination = resolve(outDir, "kavio-ai");
+    await mkdir(outDir, { recursive: true });
+    await cp(source, destination, { recursive: true, force: true });
+}
 async function serve() {
     const server = createServer(createCatalog());
     await server.connect(new StdioServerTransport());
@@ -31,6 +39,18 @@ async function main(argv) {
         process.stdout.write(`Wrote anthropic/openai/gemini tool files to ${outDir}\n`);
         return;
     }
+    if (argv[2] === "emit-skill") {
+        const flagIndex = argv.indexOf("--out");
+        const outDir = flagIndex >= 0 ? argv[flagIndex + 1] : undefined;
+        if (outDir === undefined || outDir.length === 0) {
+            process.stderr.write("Usage: kavio-mcp emit-skill --out <skills-dir>\n");
+            process.exitCode = 1;
+            return;
+        }
+        await emitSkill(outDir);
+        process.stdout.write(`Wrote Kavio AI skill to ${resolve(outDir, "kavio-ai")}\n`);
+        return;
+    }
     await serve();
 }
 void main(process.argv).catch((error) => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kitsra/kavio-mcp",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "description": "Model Context Protocol server and provider tool adapters for Kavio.",
   "license": "Elastic-2.0",
   "repository": {
@@ -16,11 +16,11 @@
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.25.0",
-    "@kitsra/kavio-builder": "0.1.1",
-    "@kitsra/kavio-core": "0.1.1",
-    "@kitsra/kavio-render": "0.1.1",
-    "@kitsra/kavio-render-worker": "0.1.1",
-    "@kitsra/kavio-schema": "0.1.1"
+    "@kitsra/kavio-builder": "0.1.3",
+    "@kitsra/kavio-core": "0.1.3",
+    "@kitsra/kavio-render": "0.1.3",
+    "@kitsra/kavio-render-worker": "0.1.3",
+    "@kitsra/kavio-schema": "0.1.3"
   },
   "devDependencies": {
     "@types/node": "^22.0.0"
@@ -33,8 +33,11 @@
   },
   "files": [
     "dist",
+    "plugins",
     "!dist/**/*.tsbuildinfo"
   ],
+  "readme": "# @kitsra/kavio-mcp\n\nModel Context Protocol server and provider tool adapters for Kavio.\n\n## Install\n\n```bash\ncorepack pnpm add @kitsra/kavio-mcp\n```\n\n## Usage\n\nRun the MCP server over stdio:\n\n```bash\nkavio-mcp\n```\n\nExample MCP host configuration:\n\n```json\n{\n  \"mcpServers\": {\n    \"kavio\": {\n      \"command\": \"kavio-mcp\"\n    }\n  }\n}\n```\n\nThe package exposes tools for composition validation, inspection, migration,\nprop resolution, export preset listing, render planning, and rendering. It also\nships provider adapter schemas for Anthropic, OpenAI, and Gemini.\n\n## Links\n\n- Repository: https://github.com/kitsra/kavio\n- MCP docs: https://github.com/kitsra/kavio/blob/main/docs/mcp.md\n- Package overview: https://github.com/kitsra/kavio/blob/main/docs/packages.md\n- License: Elastic-2.0\n",
+  "readmeFilename": "README.md",
   "scripts": {
     "build": "tsc -p tsconfig.json",
     "check": "tsc -p tsconfig.json --noEmit",

package/plugins/kavio-ai/.claude-plugin/plugin.json

@@ -0,0 +1,19 @@
+{
+  "name": "kavio-ai",
+  "version": "0.1.0",
+  "description": "Author validated Kavio video templates from natural-language briefs.",
+  "author": {
+    "name": "Kitsra"
+  },
+  "homepage": "https://github.com/kitsra/kavio#readme",
+  "repository": "https://github.com/kitsra/kavio.git",
+  "license": "Elastic-2.0",
+  "keywords": [
+    "kavio",
+    "video",
+    "ai",
+    "json-schema",
+    "automation"
+  ],
+  "skills": "./skills/"
+}

package/plugins/kavio-ai/.codex-plugin/plugin.json

@@ -0,0 +1,40 @@
+{
+  "name": "kavio-ai",
+  "version": "0.1.0",
+  "description": "Author validated Kavio video templates from natural-language briefs.",
+  "author": {
+    "name": "Kitsra"
+  },
+  "homepage": "https://github.com/kitsra/kavio#readme",
+  "repository": "https://github.com/kitsra/kavio.git",
+  "license": "Elastic-2.0",
+  "keywords": [
+    "kavio",
+    "video",
+    "ai",
+    "json-schema",
+    "automation"
+  ],
+  "skills": "./skills/",
+  "interface": {
+    "displayName": "Kavio",
+    "shortDescription": "Author validated video templates",
+    "longDescription": "Turn briefs into portable Kavio JSON compositions, then validate, inspect, preview, render, and adapt them for social exports with the local Kavio CLI workflow.",
+    "developerName": "Kitsra",
+    "category": "Creativity",
+    "capabilities": [
+      "Read",
+      "Write"
+    ],
+    "websiteURL": "https://github.com/kitsra/kavio#readme",
+    "defaultPrompt": [
+      "Create a Kavio video from my brief.",
+      "Repair and validate this Kavio JSON.",
+      "Adapt this composition for social exports."
+    ],
+    "brandColor": "#60BFD0",
+    "composerIcon": "./assets/icon.png",
+    "logo": "./assets/logo.png",
+    "screenshots": []
+  }
+}

package/plugins/kavio-ai/gemini-extension.json

@@ -0,0 +1,5 @@
+{
+  "name": "kavio-ai",
+  "version": "0.1.0",
+  "description": "Author validated Kavio video templates from natural-language briefs."
+}

package/plugins/kavio-ai/plugin.json

@@ -0,0 +1,18 @@
+{
+  "name": "kavio-ai",
+  "version": "0.1.0",
+  "description": "Author validated Kavio video templates from natural-language briefs.",
+  "author": {
+    "name": "Kitsra"
+  },
+  "homepage": "https://github.com/kitsra/kavio#readme",
+  "repository": "https://github.com/kitsra/kavio.git",
+  "license": "Elastic-2.0",
+  "keywords": [
+    "kavio",
+    "video",
+    "ai",
+    "json-schema",
+    "automation"
+  ]
+}

package/plugins/kavio-ai/skills/kavio-ai/SKILL.md

@@ -0,0 +1,88 @@
+---
+name: kavio-ai
+description: Author, repair, validate, inspect, preview, and render Kavio JSON video compositions without requiring MCP tools. Use when an AI agent is asked to create a Kavio video, fix Kavio composition JSON, adapt a composition for social export presets, use the Kavio CLI instead of an MCP server, or work from a portable vendor-neutral skill workflow.
+---
+
+# Kavio AI
+
+## Workflow
+
+Use this vendor-neutral skill to work with Kavio through the local CLI, schema,
+and examples when an MCP host is unavailable or the user prefers a plain skill.
+
+1. Read the relevant local references before inventing document shape:
+   - `docs/schema.md` for the composition model.
+   - `packages/schema/schema/kavio-0.1.schema.json` for the canonical contract.
+   - `examples/basic-json/composition.json` for a compact valid example.
+   - `docs/template-authoring.md` for reusable template conventions.
+   - `docs/animation.md` when using keyframes, timing, transitions, masks, or effects.
+2. Draft or edit the composition as JSON or through the TypeScript builder.
+3. Validate after every meaningful change:
+   ```bash
+   node packages/cli/dist/index.js --json validate path/to/composition.json
+   ```
+4. If validation fails, change only the reported paths unless the user asks for
+   a broader redesign. Keep the document valid at each repair step.
+5. Inspect valid compositions before previewing or rendering:
+   ```bash
+   node packages/cli/dist/index.js --json inspect path/to/composition.json
+   ```
+6. Preview locally when layout, timing, or motion needs visual review:
+   ```bash
+   node packages/cli/dist/index.js preview path/to/composition.json
+   ```
+7. Render only when the user wants files produced and the optional browser and
+   FFmpeg binaries are already available, or after the user agrees to install
+   them through the repo's reviewed commands.
+
+## Build And Tooling
+
+- If `packages/cli/dist/index.js` is missing or stale, run:
+  ```bash
+  corepack pnpm run build
+  ```
+- Respect the repository package-age gate. Do not add dependencies or run
+  alternate package managers to make an agent workflow work.
+- Do not run package lifecycle scripts, downloaded binaries, or render-binary
+  installers just to inspect a composition. Validation, inspection, presets, and
+  most authoring work do not need browser or FFmpeg binaries.
+- Use `corepack pnpm run install:render-binaries` only for an explicit render
+  workflow that needs local output files.
+
+## Authoring Rules
+
+- Start from the required top-level keys: `version`, `composition`, `props`,
+  `assets`, `layers`, `audio`, and `exports`.
+- Prefer stable, descriptive ids such as `headline`, `logo`, `background-video`,
+  and `cta`. Keep asset ids and layer references in sync.
+- Use props for text, URLs, colors, assets, and other values that should vary
+  across rows or users. Add `maxLength` to user-facing text props.
+- Reserve layout zones for logo, headline, media, CTA, and captions so prop
+  changes do not create overlaps.
+- Prefer `exports[].layerOverrides` for aspect-ratio-specific layout changes
+  instead of duplicating whole compositions.
+- Keep layer timing within `composition.durationFrames`; remember layer timing is
+  inclusive at `startFrame` and exclusive at `startFrame + durationFrames`.
+- Use `node packages/cli/dist/index.js presets` to discover standard social
+  export presets, or `--json presets <preset-id>` for copyable JSON.
+
+## Repair Loop
+
+When validation returns errors:
+
+1. Read each error's `path`, `message`, `stage`, and `hint`.
+2. Patch only the smallest JSON region that can resolve the error.
+3. Re-run `validate` immediately.
+4. Run `inspect` after validation passes to catch suspicious duration, export,
+   asset, layer, mask, or transition counts.
+
+Do not guess around the schema. If the desired visual cannot be represented by
+the current schema, explain the limitation and offer the closest valid Kavio
+composition.
+
+## MCP Parity
+
+When an MCP host is available, `docs/mcp.md` describes the richer MCP path:
+`validate_composition`, `inspect_composition`, `list_export_presets`,
+`plan_render`, and `render`. This skill exists for agents and vendors that can
+load portable skills but do not want to configure MCP.

package/plugins/kavio-ai/skills/kavio-ai/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Kavio AI"
+  short_description: "Author and validate Kavio videos"
+  default_prompt: "Use $kavio-ai to create and validate a Kavio composition from my video brief."