@olo-studio/studio-mcp 0.0.0-stage → 1.0.1

package/README.md

@@ -1,3 +1,43 @@
-# Temporary Holding Version
+# `@olo-studio/studio-mcp`
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Local-first MCP server and CLI for **Olomni Studio** — compile `olomni.studio.scene.v1` scenes offline, generate 9:16 video scripts, render deterministic `.mp4` / `.webm` / alpha / chroma videos via headless Chrome (`window.OloStudioBridge.exportSceneBuffer`), and publish `<olo-presence>` 3D brand mascot embeds.
+
+## Installation & MCP Client Config
+
+Add to Claude Desktop, Cursor, Windsurf, or any MCP-compatible host:
+
+```json
+{
+  "mcpServers": {
+    "olomni-studio": {
+      "command": "npx",
+      "args": ["-y", "@olo-studio/studio-mcp"],
+      "env": {
+        "OLO_STUDIO_API_KEY": "olo_pat_your_token_here"
+      }
+    }
+  }
+}
+```
+
+## Tools (7)
+
+| Tool | Description |
+| --- | --- |
+| `olo_get_entitlements` | Inspect account tier, capabilities (`maxDuration`, `allowGLB`, `allowBatch`, `allowAlphaOrChroma`), and upgrade URLs (`/studio`, `/mcp`). Falls back to free-tier capabilities offline. |
+| `olo_generate_script` | Generate 9:16 scripts (`mode: "product" \| "chisme" \| "changelog"`) via `/functions/v1/studio-chisme-ai` with deterministic offline fallback. |
+| `olo_compile_scene` | Compile and validate `olomni.studio.scene.v1` SceneSpec JSON offline without a browser. |
+| `olo_render_video` | Render a real `.mp4`, `.webm`, `alpha`, or `chroma` video via headless Chrome (`OloStudioBridge.exportSceneBuffer`) to `outputPath`. |
+| `olo_render_batch` | Render multi-variant hooks/languages from a SceneSpec array or CSV in a single browser session. |
+| `olo_voice_clone_list` | List or delete cloned voices (`OLO_STUDIO_API_KEY` required) via `studio-entitlements` & `studio-voice-clone`. |
+| `olo_publish_embed` | Generate the `<script src="https://www.olomni.com/studio/embed/olo-presence.js" defer></script>` + `<olo-presence ...>` snippet. |
+
+## CLI Usage
+
+```bash
+olo-studio-mcp --help
+olo-studio-mcp serve
+olo-studio-mcp compile --title "Launch" --script "Olo: Ship 3D reels in seconds." --out scene.json
+olo-studio-mcp render --file scene.json --out demo.mp4 --format mp4
+olo-studio-mcp inspect-glb ./mascot.glb
+```

package/bin/olo-studio-mcp.js

@@ -0,0 +1,145 @@
+#!/usr/bin/env node
+/**
+ * @olo-studio/studio-mcp CLI & Stdio MCP Server Entrypoint
+ * Usage:
+ *   olo-studio-mcp [serve]           Start JSON-RPC 2.0 stdio MCP server
+ *   olo-studio-mcp compile [opts]    Compile SceneSpec v1 JSON offline
+ *   olo-studio-mcp render [opts]     Render MP4/WebM via headless Chrome
+ *   olo-studio-mcp inspect-glb <src> Inspect .glb header & JSON chunk
+ *   olo-studio-mcp --help            Show help
+ */
+import fs from 'node:fs'
+import fsp from 'node:fs/promises'
+import path from 'node:path'
+import { compileSceneSpec } from '../src/compiler.js'
+import { inspectGlb, renderVideoWithBrowser } from '../src/renderer.js'
+import { startStdioServer } from '../src/server.js'
+
+const PKG_VERSION = JSON.parse(
+  fs.readFileSync(new URL('../package.json', import.meta.url), 'utf8'),
+).version
+
+function parseFlags(argv) {
+  const flags = {}
+  const positional = []
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i]
+    if (arg === '--help' || arg === '-h') {
+      flags.help = true
+    } else if (arg.startsWith('--')) {
+      const key = arg.slice(2)
+      const next = argv[i + 1]
+      if (next !== undefined && !next.startsWith('--')) {
+        flags[key] = next
+        i++
+      } else {
+        flags[key] = true
+      }
+    } else {
+      positional.push(arg)
+    }
+  }
+  return { flags, positional }
+}
+
+function printHelp() {
+  console.log(`@olo-studio/studio-mcp v${PKG_VERSION} — Local-First MCP Server & CLI for Olomni Studio
+
+Usage:
+  olo-studio-mcp [serve]
+      Start the JSON-RPC 2.0 stdio MCP server (default when no subcommand is given).
+
+  olo-studio-mcp compile [--script "..."] [--file scene.json] [--title "..."] [--out out.json]
+      Compile and validate an olomni.studio.scene.v1 SceneSpec without a browser.
+
+  olo-studio-mcp render [--script "..."] [--file scene.json] [--out out.mp4] [--format mp4|webm|alpha|chroma] [--fps 24|30|60] [--quality fast|social|studio] [--glb path-or-url]
+      Render a deterministic 3D video via headless Chrome + OloStudioBridge.
+
+  olo-studio-mcp inspect-glb <path-or-url>
+      Inspect a .glb binary header, scenes, nodes, meshes, animations, and materials.
+
+Environment Variables:
+  OLO_STUDIO_API_KEY     Personal Access Token (olo_pat_...) for Pro/Agency entitlements
+  OLO_STUDIO_API_BASE    API base URL (default: https://www.olomni.com)
+  OLO_STUDIO_URL         Override Studio URL for headless rendering
+  OLO_STUDIO_PUBLIC_DIR  Override local public/ directory for static serving
+  OLO_CHROME_PATH        Override Chrome/Chromium executable path`)
+}
+
+async function loadInputSpec(flags) {
+  if (flags.file) {
+    const raw = await fsp.readFile(path.resolve(String(flags.file)), 'utf8')
+    return JSON.parse(raw)
+  }
+  return {
+    ...(flags.title ? { title: String(flags.title) } : {}),
+    ...(flags.script ? { script: String(flags.script) } : {}),
+    ...(flags.wear ? { wear: String(flags.wear) } : {}),
+    ...(flags.tint ? { tint: String(flags.tint) } : {}),
+    ...(flags.finish ? { finish: String(flags.finish) } : {}),
+    ...(flags.scenario ? { scenario: String(flags.scenario) } : {}),
+  }
+}
+
+async function main() {
+  const { flags, positional } = parseFlags(process.argv.slice(2))
+  const cmd = positional[0] || 'serve'
+
+  if (flags.help || cmd === 'help') {
+    printHelp()
+    return
+  }
+
+  if (cmd === 'serve') {
+    await startStdioServer()
+    return
+  }
+
+  if (cmd === 'compile') {
+    const input = await loadInputSpec(flags)
+    const sceneSpec = compileSceneSpec(input)
+    const json = JSON.stringify(sceneSpec, null, 2)
+    if (flags.out) {
+      const outPath = path.resolve(String(flags.out))
+      await fsp.mkdir(path.dirname(outPath), { recursive: true })
+      await fsp.writeFile(outPath, json, 'utf8')
+      console.log(JSON.stringify({ ok: true, outPath, sceneHash: sceneSpec.sceneHash, duration: sceneSpec.duration }))
+    } else {
+      console.log(json)
+    }
+    return
+  }
+
+  if (cmd === 'render') {
+    const input = await loadInputSpec(flags)
+    const glbArg = flags.glb ? String(flags.glb) : undefined
+    const isUrl = glbArg && /^https?:\/\//i.test(glbArg)
+    const result = await renderVideoWithBrowser({
+      sceneSpec: input,
+      format: flags.format ? String(flags.format) : 'mp4',
+      outputPath: flags.out ? String(flags.out) : './olo-render.mp4',
+      ...(flags.fps !== undefined ? { fps: Number(flags.fps) } : {}),
+      ...(flags.quality ? { quality: String(flags.quality) } : {}),
+      ...(isUrl ? { glbUrl: glbArg } : glbArg ? { glbPath: glbArg } : {}),
+      ...(flags.studioUrl ? { studioUrl: String(flags.studioUrl) } : {}),
+    })
+    console.log(JSON.stringify(result, null, 2))
+    return
+  }
+
+  if (cmd === 'inspect-glb') {
+    const target = positional[1] || flags.file || flags.url
+    const info = await inspectGlb(String(target || ''))
+    console.log(JSON.stringify(info, null, 2))
+    return
+  }
+
+  console.error(`Unknown subcommand: ${cmd}`)
+  printHelp()
+  process.exitCode = 1
+}
+
+main().catch((err) => {
+  console.error(err instanceof Error ? err.message : String(err))
+  process.exit(1)
+})

package/package.json

@@ -1,6 +1,50 @@
 {
   "name": "@olo-studio/studio-mcp",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "1.0.1",
+  "description": "Local-first MCP server and CLI for Olomni Studio 3D video rendering, SceneSpec v1 compilation, AI scripting, and <olo-presence> embeds.",
+  "type": "module",
+  "main": "./src/server.js",
+  "scripts": {
+    "prepack": "node -e \"const fs=require('fs'),p='../../public/studio/engine/director.js';if(fs.existsSync(p))fs.copyFileSync(p,'./src/director.js')\""
+  },
+  "exports": {
+    ".": "./src/server.js",
+    "./compiler": "./src/compiler.js",
+    "./renderer": "./src/renderer.js"
+  },
+  "bin": {
+    "olo-studio-mcp": "bin/olo-studio-mcp.js"
+  },
+  "files": [
+    "bin/",
+    "src/",
+    "README.md"
+  ],
+  "keywords": [
+    "mcp",
+    "olomni",
+    "olo-studio",
+    "3d-video",
+    "webgl",
+    "webcodecs",
+    "ai-agents"
+  ],
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/faustodariopenamondragon-web/OlomniAI.git",
+    "directory": "packages/studio-mcp"
+  },
+  "engines": {
+    "node": ">=20.0.0"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.12.0",
+    "jszip": "^3.10.1",
+    "playwright": "^1.64.1",
+    "zod": "^3.24.2"
+  }
+}

package/src/api-client.js

@@ -0,0 +1,271 @@
+/**
+ * Olomni Studio API Client (entitlements, AI script generation, voice clones).
+ * Supports OLO_STUDIO_API_KEY (olo_pat_...) and offline deterministic fallbacks.
+ */
+
+const DEFAULT_API_BASE = 'https://www.olomni.com'
+
+export function resolveApiBase(overrideBase) {
+  const raw = overrideBase || process.env.OLO_STUDIO_API_BASE || process.env.OLO_API_BASE || DEFAULT_API_BASE
+  return String(raw).replace(/\/+$/, '')
+}
+
+export function resolveApiKey(overrideKey) {
+  const key = overrideKey || process.env.OLO_STUDIO_API_KEY || ''
+  return String(key).trim()
+}
+
+export function getFreeTierEntitlements(extra = {}) {
+  return {
+    authenticated: false,
+    tier: 'free',
+    isPass: false,
+    isPro: false,
+    isAgency: false,
+    maxClones: 0,
+    maxDuration: 30,
+    allowAlphaOrChroma: false,
+    allowGLB: false,
+    allowBatch: false,
+    voiceMinutesLimit: 0,
+    voiceMinutesUsed: 0,
+    clonedVoices: [],
+    stripeEnabled: false,
+    upgradeUrl: 'https://www.olomni.com/studio',
+    mcpDocsUrl: 'https://www.olomni.com/mcp',
+    ...extra,
+  }
+}
+
+export async function getEntitlements(opts = {}) {
+  const apiBase = resolveApiBase(opts.apiBase)
+  const apiKey = resolveApiKey(opts.apiKey)
+  const fetchFn = opts.fetchFn || globalThis.fetch
+
+  if (!apiKey || typeof fetchFn !== 'function') {
+    return getFreeTierEntitlements({
+      source: apiKey ? 'offline_no_fetch' : 'offline_free_tier',
+    })
+  }
+
+  try {
+    const res = await fetchFn(`${apiBase}/functions/v1/studio-entitlements`, {
+      method: 'GET',
+      headers: {
+        Authorization: `Bearer ${apiKey}`,
+        Accept: 'application/json',
+      },
+      signal: AbortSignal.timeout(opts.timeoutMs || 8000),
+    })
+
+    if (!res.ok) {
+      return getFreeTierEntitlements({
+        source: 'remote_error',
+        httpStatus: res.status,
+      })
+    }
+
+    const data = await res.json()
+    return {
+      ...getFreeTierEntitlements(),
+      ...data,
+      stripeEnabled: false,
+      upgradeUrl: 'https://www.olomni.com/studio',
+      mcpDocsUrl: 'https://www.olomni.com/mcp',
+      source: 'remote',
+    }
+  } catch (err) {
+    return getFreeTierEntitlements({
+      source: 'offline_fallback',
+      error: err instanceof Error ? err.message : String(err),
+    })
+  }
+}
+
+const OFFLINE_TEMPLATES = {
+  product(topic, language) {
+    const isEs = String(language || 'es').toLowerCase().startsWith('es')
+    if (isEs) {
+      return {
+        title: topic ? `${topic} — Demo 9:16` : 'Lanzamiento de Producto 9:16',
+        beats: [
+          { speaker: 'Olo', line: `¿Todavía pierdes horas haciendo ${topic || 'esto'} a mano?`, state: 'alert', emotion: 'shocked' },
+          { speaker: 'Yo', line: 'Sí, cada lanzamiento me toma días enteros.', state: 'error', emotion: 'cringe' },
+          { speaker: 'Olo', line: `Con ${topic || 'Olomni Studio'} lo automatizas en 30 segundos.`, state: 'proud', emotion: 'proud' },
+          { speaker: 'Olo', line: 'Pruébalo hoy gratis y publica tu primer reel.', state: 'done', emotion: 'happy' },
+        ],
+      }
+    }
+    return {
+      title: topic ? `${topic} — 9:16 Demo` : 'Product Launch 9:16',
+      beats: [
+        { speaker: 'Olo', line: `Still spending hours doing ${topic || 'this'} manually?`, state: 'alert', emotion: 'shocked' },
+        { speaker: 'Yo', line: 'Yeah, every release takes way too long.', state: 'error', emotion: 'cringe' },
+        { speaker: 'Olo', line: `With ${topic || 'Olomni Studio'} you ship it in 30 seconds.`, state: 'proud', emotion: 'proud' },
+        { speaker: 'Olo', line: 'Try it free today and publish your first 3D reel.', state: 'done', emotion: 'happy' },
+      ],
+    }
+  },
+  changelog(topic, language) {
+    const isEs = String(language || 'es').toLowerCase().startsWith('es')
+    if (isEs) {
+      return {
+        title: topic ? `Novedades: ${topic}` : 'Changelog Release 9:16',
+        beats: [
+          { speaker: 'Olo', line: `Acabamos de lanzar ${topic || 'la nueva versión'} y cambia todo.`, state: 'alert', emotion: 'alert' },
+          { speaker: 'Olo', line: 'Exportación determinista, lip-sync neural y cero fricción.', state: 'proud', emotion: 'proud' },
+          { speaker: 'Olo', line: 'Actualiza ahora y pruébalo en tu próximo deploy.', state: 'done', emotion: 'happy' },
+        ],
+      }
+    }
+    return {
+      title: topic ? `What's New: ${topic}` : 'Changelog Release 9:16',
+      beats: [
+        { speaker: 'Olo', line: `We just shipped ${topic || 'our latest release'} and it changes everything.`, state: 'alert', emotion: 'alert' },
+        { speaker: 'Olo', line: 'Deterministic export, neural lip-sync, zero friction.', state: 'proud', emotion: 'proud' },
+        { speaker: 'Olo', line: 'Update now and test it on your next deploy.', state: 'done', emotion: 'happy' },
+      ],
+    }
+  },
+  chisme(topic, language) {
+    const isEs = String(language || 'es').toLowerCase().startsWith('es')
+    if (isEs) {
+      return {
+        title: topic ? `Chisme: ${topic}` : 'Storytime 9:16',
+        beats: [
+          { speaker: 'Yo', line: `No vas a creer lo que pasó con ${topic || 'el cliente hoy'}.`, state: 'curious', emotion: 'curious' },
+          { speaker: 'Contacto', line: 'Cuéntamelo todo sin censura, ¿qué hizo ahora?', state: 'alert', emotion: 'shocked' },
+          { speaker: 'Olo', line: 'Spoiler: terminó pidiendo perdón y pagando el doble.', state: 'curious', emotion: 'sarcastic' },
+          { speaker: 'Olo', line: 'Guarda este video antes de que lo borren.', state: 'proud', emotion: 'proud' },
+        ],
+      }
+    }
+    return {
+      title: topic ? `Storytime: ${topic}` : 'Storytime 9:16',
+      beats: [
+        { speaker: 'Yo', line: `You will not believe what happened with ${topic || 'our launch today'}.`, state: 'curious', emotion: 'curious' },
+        { speaker: 'Contacto', line: 'Wait, spill everything right now.', state: 'alert', emotion: 'shocked' },
+        { speaker: 'Olo', line: 'Spoiler: they came back asking for an enterprise plan.', state: 'curious', emotion: 'sarcastic' },
+        { speaker: 'Olo', line: 'Save this clip before it disappears.', state: 'proud', emotion: 'proud' },
+      ],
+    }
+  },
+}
+
+export async function generateScript(opts = {}) {
+  const mode = ['product', 'chisme', 'changelog'].includes(opts.mode) ? opts.mode : 'product'
+  const topic = String(opts.topic || opts.product || opts.text || '').trim()
+  const language = String(opts.language || 'es').trim()
+  const apiBase = resolveApiBase(opts.apiBase)
+  const apiKey = resolveApiKey(opts.apiKey)
+  const fetchFn = opts.fetchFn || globalThis.fetch
+
+  if (typeof fetchFn === 'function' && opts.offlineOnly !== true) {
+    try {
+      const headers = {
+        'Content-Type': 'application/json',
+        Accept: 'application/json',
+      }
+      if (apiKey) headers.Authorization = `Bearer ${apiKey}`
+
+      const res = await fetchFn(`${apiBase}/functions/v1/studio-chisme-ai`, {
+        method: 'POST',
+        headers,
+        body: JSON.stringify({
+          mode,
+          text: topic || `Generate a ${mode} 9:16 script in ${language}`,
+          language,
+        }),
+        signal: AbortSignal.timeout(opts.timeoutMs || 12000),
+      })
+
+      if (res.ok) {
+        const data = await res.json()
+        if (data && typeof data.script === 'string' && data.script.trim()) {
+          return {
+            ok: true,
+            mode: data.mode || mode,
+            title: data.title || topic || 'Olo Studio Show',
+            beats: Array.isArray(data.beats) ? data.beats : [],
+            script: data.script,
+            provider: data.provider || 'remote',
+          }
+        }
+      }
+    } catch {
+      // Fall through to deterministic offline generator
+    }
+  }
+
+  const builder = OFFLINE_TEMPLATES[mode] || OFFLINE_TEMPLATES.product
+  const generated = builder(topic, language)
+  const script = generated.beats.map((b) => `${b.speaker}: ${b.line}`).join('\n')
+  return {
+    ok: true,
+    mode,
+    title: generated.title,
+    beats: generated.beats,
+    script,
+    provider: 'offline-deterministic',
+  }
+}
+
+export async function manageVoiceClones(opts = {}) {
+  const action = opts.action === 'delete' ? 'delete' : 'list'
+  const apiBase = resolveApiBase(opts.apiBase)
+  const apiKey = resolveApiKey(opts.apiKey)
+  const fetchFn = opts.fetchFn || globalThis.fetch
+
+  if (!apiKey) {
+    return {
+      ok: false,
+      error: 'missing_api_key',
+      message: 'Set OLO_STUDIO_API_KEY (olo_pat_...) to list or manage cloned voices.',
+      clonedVoices: [],
+      maxClones: 0,
+      upgradeUrl: 'https://www.olomni.com/studio',
+    }
+  }
+
+  if (typeof fetchFn !== 'function') {
+    return { ok: false, error: 'fetch_unavailable', clonedVoices: [] }
+  }
+
+  if (action === 'delete') {
+    const voiceId = String(opts.voiceId || '').trim()
+    if (!voiceId) {
+      return { ok: false, error: 'missing_voice_id', message: 'voiceId is required when action is delete.' }
+    }
+    const res = await fetchFn(
+      `${apiBase}/functions/v1/studio-voice-clone?voiceId=${encodeURIComponent(voiceId)}`,
+      {
+        method: 'DELETE',
+        headers: {
+          Authorization: `Bearer ${apiKey}`,
+          Accept: 'application/json',
+        },
+        signal: AbortSignal.timeout(opts.timeoutMs || 10000),
+      },
+    )
+    const body = await res.json().catch(() => ({}))
+    return {
+      ok: res.ok,
+      status: res.status,
+      action: 'delete',
+      voiceId,
+      ...body,
+    }
+  }
+
+  const entitlements = await getEntitlements({ apiBase, apiKey, fetchFn, timeoutMs: opts.timeoutMs })
+  return {
+    ok: Boolean(entitlements.authenticated),
+    action: 'list',
+    tier: entitlements.tier,
+    maxClones: entitlements.maxClones || 0,
+    voiceMinutesLimit: entitlements.voiceMinutesLimit || 0,
+    voiceMinutesUsed: entitlements.voiceMinutesUsed || 0,
+    clonedVoices: Array.isArray(entitlements.clonedVoices) ? entitlements.clonedVoices : [],
+    upgradeUrl: 'https://www.olomni.com/studio',
+  }
+}