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

package/src/renderer.js

@@ -0,0 +1,401 @@
+/**
+ * Headless Chrome / Playwright deterministic video renderer and GLB inspector.
+ * Calls `window.OloStudioBridge.exportSceneBuffer` against local static `public/` or `https://www.olomni.com/studio`.
+ */
+import fs from 'node:fs'
+import fsp from 'node:fs/promises'
+import http from 'node:http'
+import path from 'node:path'
+import { createRequire } from 'node:module'
+import JSZip from 'jszip'
+import { compileSceneSpec, findPublicStudioDir, generateSrt, parseBatchInput } from './compiler.js'
+
+export const VALID_FORMATS = ['mp4', 'webm', 'webm_alpha', 'alpha', 'chroma']
+
+export function validateRenderFormat(rawFormat) {
+  const fmt = String(rawFormat || 'mp4').trim().toLowerCase()
+  if (!VALID_FORMATS.includes(fmt)) {
+    throw new Error(`Unsupported render format "${fmt}". Supported formats: ${VALID_FORMATS.join(', ')}`)
+  }
+  return fmt
+}
+
+const MIME_TYPES = {
+  '.html': 'text/html; charset=utf-8',
+  '.js': 'application/javascript; charset=utf-8',
+  '.mjs': 'application/javascript; charset=utf-8',
+  '.css': 'text/css; charset=utf-8',
+  '.json': 'application/json; charset=utf-8',
+  '.png': 'image/png',
+  '.jpg': 'image/jpeg',
+  '.jpeg': 'image/jpeg',
+  '.webp': 'image/webp',
+  '.svg': 'image/svg+xml',
+  '.glb': 'model/gltf-binary',
+  '.gltf': 'model/gltf+json',
+  '.woff2': 'font/woff2',
+  '.wasm': 'application/wasm',
+  '.mp3': 'audio/mpeg',
+  '.wav': 'audio/wav',
+}
+
+export function findChromeExecutable(overridePath) {
+  const candidates = [
+    overridePath,
+    process.env.OLO_CHROME_PATH,
+    '/Applications/Google Chrome.app/Contents/MacOS/Google Chrome',
+    '/Applications/Chromium.app/Contents/MacOS/Chromium',
+    '/usr/bin/google-chrome',
+    '/usr/bin/chromium',
+    '/usr/bin/chromium-browser',
+  ].filter(Boolean)
+
+  for (const candidate of candidates) {
+    if (fs.existsSync(candidate)) {
+      return candidate
+    }
+  }
+  return null
+}
+
+async function loadPlaywright() {
+  try {
+    return await import('playwright')
+  } catch {
+    // Try resolving from cwd (e.g., monorepo root devDependencies)
+    try {
+      const req = createRequire(path.join(process.cwd(), 'package.json'))
+      return req('playwright')
+    } catch {
+      try {
+        return await import('playwright-core')
+      } catch {
+        throw new Error(
+          'Playwright is required for headless video rendering. Install `playwright` in your workspace or set OLO_STUDIO_URL.',
+        )
+      }
+    }
+  }
+}
+
+export function startStaticServer(rootDir) {
+  return new Promise((resolve, reject) => {
+    const resolvedRoot = path.resolve(rootDir)
+    const server = http.createServer((req, res) => {
+      const urlPath = (req.url || '/').split('?')[0]
+      let relPath = decodeURIComponent(urlPath).replace(/^\/+/, '')
+      if (!relPath || relPath.endsWith('/')) relPath += 'index.html'
+      const absPath = path.resolve(resolvedRoot, relPath)
+
+      if (!absPath.startsWith(resolvedRoot)) {
+        res.writeHead(403)
+        res.end('Forbidden')
+        return
+      }
+
+      fs.stat(absPath, (err, stat) => {
+        if (err || !stat.isFile()) {
+          // Fallback to /studio/index.html if requesting /studio
+          const indexFallback = path.join(absPath, 'index.html')
+          if (fs.existsSync(indexFallback)) {
+            const data = fs.readFileSync(indexFallback)
+            res.writeHead(200, { 'Content-Type': 'text/html; charset=utf-8' })
+            res.end(data)
+            return
+          }
+          res.writeHead(404)
+          res.end('Not Found')
+          return
+        }
+
+        const ext = path.extname(absPath).toLowerCase()
+        res.writeHead(200, {
+          'Content-Type': MIME_TYPES[ext] || 'application/octet-stream',
+          'Cache-Control': 'no-cache',
+        })
+        fs.createReadStream(absPath).pipe(res)
+      })
+    })
+
+    server.on('error', reject)
+    server.listen(0, '127.0.0.1', () => {
+      const addr = server.address()
+      resolve({
+        server,
+        port: addr.port,
+        baseUrl: `http://127.0.0.1:${addr.port}`,
+        close: () => new Promise((resClose) => server.close(() => resClose())),
+      })
+    })
+  })
+}
+
+async function openStudioSession(opts = {}) {
+  const { chromium } = await loadPlaywright()
+  const chromePath = findChromeExecutable(opts.chromePath)
+
+  let staticSrv = null
+  let targetUrl = opts.studioUrl || process.env.OLO_STUDIO_URL || ''
+
+  if (!targetUrl) {
+    const publicDir = findPublicStudioDir(opts.publicDir)
+    if (publicDir) {
+      staticSrv = await startStaticServer(publicDir)
+      targetUrl = `${staticSrv.baseUrl}/studio/index.html`
+    } else {
+      targetUrl = 'https://www.olomni.com/studio'
+    }
+  }
+
+  const browser = await chromium.launch({
+    headless: true,
+    ...(chromePath ? { executablePath: chromePath } : {}),
+    args: [
+      '--use-gl=angle',
+      '--use-angle=swiftshader',
+      '--enable-webgl',
+      '--ignore-gpu-blocklist',
+      '--autoplay-policy=no-user-gesture-required',
+      '--no-sandbox',
+    ],
+  })
+
+  try {
+    const context = await browser.newContext({
+      viewport: { width: 1280, height: 900 },
+    })
+    const page = await context.newPage()
+
+    await page.goto(targetUrl, {
+      waitUntil: 'domcontentloaded',
+      timeout: opts.timeoutMs || 30000,
+    })
+
+    await page.waitForFunction(
+      () => Boolean(window.OloStudioBridge && window.OloStudioBridge.ready === true),
+      null,
+      { timeout: opts.timeoutMs || 25000 },
+    )
+
+    return { browser, context, page, staticSrv, targetUrl, chromePath }
+  } catch (err) {
+    await browser.close().catch(() => {})
+    if (staticSrv) await staticSrv.close().catch(() => {})
+    throw err
+  }
+}
+
+async function renderOnPage(page, opts) {
+  const compiled = compileSceneSpec(opts.sceneSpec || opts)
+  const format = validateRenderFormat(opts.format)
+
+  if (opts.glbPath) {
+    const absGlb = path.resolve(opts.glbPath)
+    const buf = await fsp.readFile(absGlb)
+    const b64 = buf.toString('base64')
+    await page.evaluate(
+      async ({ base64, fileName }) => {
+        const bin = atob(base64)
+        const bytes = new Uint8Array(bin.length)
+        for (let i = 0; i < bin.length; i++) bytes[i] = bin.charCodeAt(i)
+        await window.OloStudioBridge.loadGlbFromArrayBuffer(bytes.buffer, fileName)
+      },
+      { base64: b64, fileName: path.basename(absGlb) },
+    )
+  } else if (opts.glbUrl) {
+    await page.evaluate(async (url) => {
+      await window.OloStudioBridge.loadGlbFromUrl(url)
+    }, opts.glbUrl)
+  }
+
+  const exportResult = await page.evaluate(
+    async ({ scene, fmt }) => {
+      const res = await window.OloStudioBridge.exportSceneBuffer(scene, fmt)
+      const bytes = Array.from(new Uint8Array(res.arrayBuffer))
+      return {
+        bytes,
+        mimeType: res.mimeType,
+        ext: res.ext,
+        durationSec: res.durationSec,
+        watermarked: res.watermarked,
+      }
+    },
+    { scene: compiled, fmt: format },
+  )
+
+  const buffer = Buffer.from(exportResult.bytes)
+  const outPath = path.resolve(opts.outputPath || `olo-render-${compiled.sceneHash}.${exportResult.ext || 'mp4'}`)
+  await fsp.mkdir(path.dirname(outPath), { recursive: true })
+  await fsp.writeFile(outPath, buffer)
+
+  let srtPath = null
+  if (opts.srt !== false) {
+    const srtContent = generateSrt(compiled)
+    if (srtContent) {
+      const outputBase = outPath.slice(0, outPath.length - path.extname(outPath).length)
+      srtPath = `${outputBase}.srt`
+      await fsp.writeFile(srtPath, srtContent, 'utf8')
+    }
+  }
+
+  return {
+    ok: true,
+    outputPath: outPath,
+    srtPath,
+    bytes: buffer.byteLength,
+    mimeType: exportResult.mimeType,
+    ext: exportResult.ext,
+    durationSec: exportResult.durationSec,
+    watermarked: exportResult.watermarked,
+    sceneHash: compiled.sceneHash,
+    title: compiled.title,
+  }
+}
+
+export async function renderVideoWithBrowser(opts = {}) {
+  validateRenderFormat(opts.format)
+  const session = await openStudioSession(opts)
+  try {
+    const res = await renderOnPage(session.page, opts)
+    return {
+      ...res,
+      studioUrl: session.targetUrl,
+      chromePath: session.chromePath || 'playwright-chromium',
+    }
+  } finally {
+    await session.browser.close().catch(() => {})
+    if (session.staticSrv) await session.staticSrv.close().catch(() => {})
+  }
+}
+
+export async function renderBatchWithBrowser(opts = {}) {
+  const format = validateRenderFormat(opts.format)
+  let variants = Array.isArray(opts.variants) ? opts.variants : []
+
+  if (variants.length === 0) {
+    let csvContent = opts.csv
+    if (!csvContent && opts.csvPath) {
+      csvContent = await fsp.readFile(path.resolve(opts.csvPath), 'utf8')
+    }
+    variants = parseBatchInput({ specs: opts.specs, csv: csvContent })
+  }
+
+  if (variants.length === 0) {
+    throw new Error('variants array must be non-empty')
+  }
+
+  const outputDir = path.resolve(opts.outputDir || './olo-batch-renders')
+  const ext = format.includes('webm') || format === 'alpha' ? 'webm' : 'mp4'
+
+  const session = await openStudioSession(opts)
+  const results = []
+  try {
+    for (const variant of variants) {
+      const outPath = path.join(outputDir, `${variant.outputName}.${ext}`)
+      const rendered = await renderOnPage(session.page, {
+        sceneSpec: variant.sceneSpec,
+        format,
+        srt: opts.srt,
+        outputPath: outPath,
+        glbUrl: variant.glbUrl || opts.glbUrl,
+        glbPath: variant.glbPath || opts.glbPath,
+      })
+      results.push({
+        index: variant.index,
+        outputName: variant.outputName,
+        ...rendered,
+      })
+    }
+
+    await fsp.mkdir(outputDir, { recursive: true })
+    const manifestPath = path.join(outputDir, 'manifest.json')
+    const manifest = {
+      ok: true,
+      format,
+      count: results.length,
+      studioUrl: session.targetUrl,
+      generatedAt: new Date().toISOString(),
+      results,
+    }
+    await fsp.writeFile(manifestPath, JSON.stringify(manifest, null, 2), 'utf8')
+
+    let zipPath = null
+    if (opts.zip !== false) {
+      const zip = new JSZip()
+      zip.file('manifest.json', await fsp.readFile(manifestPath))
+      for (const item of results) {
+        if (item.outputPath && fs.existsSync(item.outputPath)) {
+          zip.file(path.basename(item.outputPath), await fsp.readFile(item.outputPath))
+        }
+        if (item.srtPath && fs.existsSync(item.srtPath)) {
+          zip.file(path.basename(item.srtPath), await fsp.readFile(item.srtPath))
+        }
+      }
+      zipPath = path.join(outputDir, 'batch.zip')
+      const zipBuffer = await zip.generateAsync({ type: 'nodebuffer', compression: 'DEFLATE' })
+      await fsp.writeFile(zipPath, zipBuffer)
+    }
+
+    return {
+      ok: true,
+      count: results.length,
+      outputDir,
+      manifestPath,
+      zipPath,
+      studioUrl: session.targetUrl,
+      results,
+    }
+  } finally {
+    await session.browser.close().catch(() => {})
+    if (session.staticSrv) await session.staticSrv.close().catch(() => {})
+  }
+}
+
+export async function inspectGlb(source) {
+  if (!source || typeof source !== 'string') {
+    throw new Error('GLB file path or https:// URL is required.')
+  }
+
+  let buffer
+  if (/^https?:\/\//i.test(source)) {
+    const res = await fetch(source, { signal: AbortSignal.timeout(15000) })
+    if (!res.ok) throw new Error(`Failed to fetch GLB (${res.status})`)
+    buffer = Buffer.from(await res.arrayBuffer())
+  } else {
+    buffer = await fsp.readFile(path.resolve(source))
+  }
+
+  if (buffer.byteLength < 20) {
+    throw new Error('File too small to be a valid GLB binary.')
+  }
+
+  const magic = buffer.readUInt32LE(0)
+  if (magic !== 0x46546c67) {
+    throw new Error(`Invalid GLB magic header: 0x${magic.toString(16)}`)
+  }
+
+  const version = buffer.readUInt32LE(4)
+  const totalLength = buffer.readUInt32LE(8)
+  const chunkLength = buffer.readUInt32LE(12)
+  const chunkType = buffer.readUInt32LE(16)
+
+  if (chunkType !== 0x4e4f534a) {
+    throw new Error('First GLB chunk is not JSON.')
+  }
+
+  const jsonStr = buffer.subarray(20, 20 + chunkLength).toString('utf8').replace(/\0+$/, '')
+  const gltf = JSON.parse(jsonStr)
+
+  return {
+    ok: true,
+    source,
+    version,
+    byteLength: totalLength,
+    generator: gltf.asset?.generator || null,
+    scenes: Array.isArray(gltf.scenes) ? gltf.scenes.length : 0,
+    nodes: Array.isArray(gltf.nodes) ? gltf.nodes.length : 0,
+    meshes: Array.isArray(gltf.meshes) ? gltf.meshes.map((m) => m.name || 'unnamed') : [],
+    animations: Array.isArray(gltf.animations) ? gltf.animations.map((a) => a.name || 'unnamed') : [],
+    materials: Array.isArray(gltf.materials) ? gltf.materials.map((m) => m.name || 'unnamed') : [],
+  }
+}

package/src/server.js

@@ -0,0 +1,250 @@
+/**
+ * @olomni/studio-mcp — Local-first MCP Server (JSON-RPC 2.0 over stdio)
+ * Registers the 7 canonical Olomni Studio tools via @modelcontextprotocol/sdk.
+ */
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js'
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js'
+import { z } from 'zod'
+import { getEntitlements, generateScript, manageVoiceClones } from './api-client.js'
+import {
+  compileSceneSpec,
+  buildPublishEmbed,
+  VALID_STATES,
+  VALID_TINTS,
+  VALID_WEARS,
+  VALID_FINISHES,
+  VALID_SCENARIOS,
+  STATE_ALIASES,
+  TINT_ALIASES,
+  WEAR_ALIASES,
+  FINISH_ALIASES,
+  SCENARIO_ALIASES,
+} from './compiler.js'
+import { VALID_FORMATS, renderVideoWithBrowser, renderBatchWithBrowser } from './renderer.js'
+
+function enumWithAliases(canonical, aliases, label) {
+  return z
+    .enum([...canonical, ...Object.keys(aliases)])
+    .optional()
+    .describe(`${label} (canonical: ${canonical.join(', ')})`)
+}
+
+function jsonToolResult(payload, isError = false) {
+  return {
+    content: [
+      {
+        type: 'text',
+        text: JSON.stringify(payload, null, 2),
+      },
+    ],
+    ...(isError ? { isError: true } : {}),
+  }
+}
+
+export function createStudioMcpServer(serverOpts = {}) {
+  const server = new McpServer({
+    name: '@olomni/studio-mcp',
+    version: '1.0.0',
+  })
+
+  // 1. olo_get_entitlements
+  server.tool(
+    'olo_get_entitlements',
+    'Inspect Olomni Studio account tier, capabilities (maxDuration, allowGLB, allowBatch, allowAlphaOrChroma), and upgrade URLs using OLO_STUDIO_API_KEY (or free-tier fallback).',
+    {
+      apiKey: z.string().optional().describe('Optional olo_pat_... token (defaults to OLO_STUDIO_API_KEY env var).'),
+      apiBase: z.string().optional().describe('Optional API base URL (defaults to https://www.olomni.com).'),
+    },
+    async (args) => {
+      const result = await getEntitlements({
+        apiKey: args.apiKey || serverOpts.apiKey,
+        apiBase: args.apiBase || serverOpts.apiBase,
+      })
+      return jsonToolResult(result)
+    },
+  )
+
+  // 2. olo_generate_script
+  server.tool(
+    'olo_generate_script',
+    'Generate a 9:16 video script (Olo: ... / Yo: ...) in product, chisme, or changelog mode via studio-chisme-ai with deterministic offline fallback.',
+    {
+      mode: z.enum(['product', 'chisme', 'changelog']).default('product').describe('Script style mode.'),
+      topic: z.string().min(1).describe('Product, feature, changelog, or story topic.'),
+      language: z.string().default('es').describe('Output language code (e.g. es, en, pt).'),
+      offlineOnly: z.boolean().optional().describe('Skip network call and use deterministic offline generator.'),
+      apiKey: z.string().optional(),
+      apiBase: z.string().optional(),
+    },
+    async (args) => {
+      const result = await generateScript({
+        mode: args.mode,
+        topic: args.topic,
+        language: args.language,
+        offlineOnly: args.offlineOnly,
+        apiKey: args.apiKey || serverOpts.apiKey,
+        apiBase: args.apiBase || serverOpts.apiBase,
+      })
+      return jsonToolResult(result)
+    },
+  )
+
+  // 3. olo_compile_scene
+  server.tool(
+    'olo_compile_scene',
+    'Compile and validate a deterministic olomni.studio.scene.v1 SceneSpec JSON from script text or structured beats without launching a browser.',
+    {
+      title: z.string().optional().describe('Show title (max 60 chars).'),
+      category: z.string().optional().describe('Category badge (e.g. Show 9:16, Product Demo).'),
+      script: z.string().optional().describe('Line-delimited script (e.g. "Olo: Hola\\nYo: Qué tal").'),
+      wear: enumWithAliases(VALID_WEARS, WEAR_ALIASES, 'Mascot wear accessory'),
+      tint: enumWithAliases(VALID_TINTS, TINT_ALIASES, 'Mascot body tint'),
+      finish: enumWithAliases(VALID_FINISHES, FINISH_ALIASES, 'Collector PBR finish'),
+      scenario: enumWithAliases(VALID_SCENARIOS, SCENARIO_ALIASES, '3D background scenario'),
+      state: enumWithAliases(VALID_STATES, STATE_ALIASES, 'Default 3D character state'),
+      stateOverride: enumWithAliases(VALID_STATES, STATE_ALIASES, 'Override 3D character state'),
+      emotion: z.string().optional().describe('Legacy alias for stateOverride.'),
+      vibe: z.string().optional(),
+      cameraOverride: z.string().optional(),
+      duelConfig: z.record(z.any()).optional().describe('Optional Duel / Sparring mode configuration.'),
+      voice: z.string().optional().describe('Voice preset or TTS voice name.'),
+      voiceId: z.string().optional().describe('Cloned voice ID for neural TTS.'),
+      captions: z.boolean().default(true).describe('Include timed captions/subtitles (default: true).'),
+      watermark: z.boolean().optional(),
+      maxLines: z.number().int().min(1).max(30).optional(),
+      beats: z.array(z.record(z.any())).optional().describe('Optional structured beats array with speaker, text, state, cam, sfx.'),
+      pipPath: z.string().optional().describe('Local file path for Picture-in-Picture media (png, jpg, webp, mp4, webm).'),
+      pipUrl: z.string().optional().describe('Remote URL for Picture-in-Picture media.'),
+      pipMeta: z.record(z.any()).optional().describe('Optional Picture-in-Picture metadata for product demos.'),
+      customOutro: z.record(z.any()).optional().describe('Optional custom outro card configuration.'),
+    },
+    async (args) => {
+      const sceneSpec = compileSceneSpec(args)
+      return jsonToolResult(sceneSpec)
+    },
+  )
+
+  // 4. olo_render_video
+  server.tool(
+    'olo_render_video',
+    'Render a deterministic 3D video (.mp4, .webm, webm_alpha, alpha, or chroma) via headless Chrome + window.OloStudioBridge.exportSceneBuffer and write it to outputPath.',
+    {
+      outputPath: z.string().min(1).describe('Destination file path for the rendered video (e.g. ./out/demo.mp4).'),
+      format: z.enum(VALID_FORMATS).default('mp4').describe('Output container/mode: mp4, webm, webm_alpha, alpha, chroma.'),
+      srt: z.boolean().default(true).describe('Write <outputBase>.srt timed captions alongside the video (default: true).'),
+      sceneSpec: z.record(z.any()).optional().describe('Pre-compiled olomni.studio.scene.v1 JSON.'),
+      script: z.string().optional().describe('Raw script text if sceneSpec is omitted.'),
+      title: z.string().optional(),
+      wear: z.string().optional(),
+      tint: z.string().optional(),
+      finish: z.string().optional(),
+      scenario: z.string().optional(),
+      glbUrl: z.string().optional().describe('Optional custom mascot .glb/.gltf URL.'),
+      glbPath: z.string().optional().describe('Optional local .glb/.gltf file path.'),
+      studioUrl: z.string().optional().describe('Optional Studio URL (defaults to local static server or https://www.olomni.com/studio).'),
+      timeoutMs: z.number().int().positive().optional(),
+    },
+    async (args) => {
+      try {
+        const result = await renderVideoWithBrowser(args)
+        return jsonToolResult(result)
+      } catch (err) {
+        return jsonToolResult(
+          { ok: false, error: err instanceof Error ? err.message : String(err) },
+          true,
+        )
+      }
+    },
+  )
+
+  // 5. olo_render_batch
+  server.tool(
+    'olo_render_batch',
+    'Render multiple SceneSpec variants or a CSV of hooks/languages in a single headless Chrome session.',
+    {
+      outputDir: z.string().min(1).describe('Directory where rendered variant videos will be saved.'),
+      format: z.enum(VALID_FORMATS).default('mp4').describe('Output container/mode: mp4, webm, webm_alpha, alpha, chroma.'),
+      specs: z.array(z.record(z.any())).optional().describe('Array of SceneSpec or compile-option objects.'),
+      csv: z.string().optional().describe('CSV string with header row (e.g. title,language,script,wear,tint,scenario,voice,voiceId,outputName).'),
+      csvPath: z.string().optional().describe('Path to a local CSV file with variant rows.'),
+      zip: z.boolean().default(true).describe('Package rendered videos, .srt files, and manifest.json into <outputDir>/batch.zip (default: true).'),
+      srt: z.boolean().default(true).describe('Write .srt timed captions alongside each video (default: true).'),
+      glbUrl: z.string().optional(),
+      glbPath: z.string().optional(),
+      studioUrl: z.string().optional(),
+      timeoutMs: z.number().int().positive().optional(),
+    },
+    async (args) => {
+      try {
+        const result = await renderBatchWithBrowser(args)
+        return jsonToolResult(result)
+      } catch (err) {
+        return jsonToolResult(
+          { ok: false, error: err instanceof Error ? err.message : String(err) },
+          true,
+        )
+      }
+    },
+  )
+
+  // 6. olo_voice_clone_list
+  server.tool(
+    'olo_voice_clone_list',
+    'List or delete cloned voices associated with your OLO_STUDIO_API_KEY via studio-entitlements and studio-voice-clone.',
+    {
+      action: z.enum(['list', 'delete']).default('list').describe('List cloned voices or delete a voice slot by voiceId.'),
+      voiceId: z.string().optional().describe('Voice ID to delete when action is "delete".'),
+      apiKey: z.string().optional(),
+      apiBase: z.string().optional(),
+    },
+    async (args) => {
+      const result = await manageVoiceClones({
+        action: args.action,
+        voiceId: args.voiceId,
+        apiKey: args.apiKey || serverOpts.apiKey,
+        apiBase: args.apiBase || serverOpts.apiBase,
+      })
+      return jsonToolResult(result, !result.ok && result.error !== 'missing_api_key')
+    },
+  )
+
+  // 7. olo_publish_embed
+  server.tool(
+    'olo_publish_embed',
+    'Generate the <script src="https://www.olomni.com/studio/embed/olo-presence.js"> + <olo-presence ...> Web Component embed snippet.',
+    {
+      mascotId: z.string().optional(),
+      brand: z.string().optional(),
+      glbUrl: z.string().optional(),
+      skin: z.string().optional(),
+      wear: z.string().optional(),
+      tint: z.string().optional(),
+      themeColor: z.string().optional(),
+      greeting: z.string().optional(),
+      ctaLabel: z.string().optional(),
+      ctaUrl: z.string().optional(),
+      voice: z.string().optional().describe('Voice preset or TTS voice name.'),
+      voiceId: z.string().optional().describe('Cloned voice ID for neural TTS.'),
+      position: z.enum(['bottom-right', 'bottom-left', 'inline']).optional(),
+      apiBase: z.string().optional(),
+      apiEndpoint: z.string().optional().describe('Custom chat/inference API endpoint URL.'),
+      ttsEndpoint: z.string().optional(),
+      systemPrompt: z.string().optional().describe('Custom system prompt for the embedded mascot agent.'),
+      knowledge: z.union([z.string(), z.array(z.any()), z.record(z.any())]).optional().describe('Knowledge base text, URL, or JSON payload.'),
+      open: z.boolean().optional(),
+    },
+    async (args) => {
+      const result = buildPublishEmbed(args)
+      return jsonToolResult(result)
+    },
+  )
+
+  return server
+}
+
+export async function startStdioServer(opts = {}) {
+  const server = createStudioMcpServer(opts)
+  const transport = new StdioServerTransport()
+  await server.connect(transport)
+  return { server, transport }
+}