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

package/src/server.js

@@ -0,0 +1,277 @@
+/**
+ * @olo-studio/studio-mcp — Local-first MCP Server (JSON-RPC 2.0 over stdio)
+ * Registers the 7 canonical Olomni Studio tools via @modelcontextprotocol/sdk.
+ */
+import fs from 'node:fs'
+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'
+
+const PKG_VERSION = JSON.parse(
+  fs.readFileSync(new URL('../package.json', import.meta.url), 'utf8'),
+).version
+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, VALID_QUALITIES, 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: '@olo-studio/studio-mcp',
+    version: PKG_VERSION,
+  })
+
+  // 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.'),
+      fps: z.union([z.literal(24), z.literal(30), z.literal(60)]).default(30).describe('Frames per second: 24, 30, or 60 (default: 30).'),
+      quality: z.enum(VALID_QUALITIES).default('social').describe('Render quality preset: fast, social, or studio (default: social).'),
+      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(),
+      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().optional().describe('Include timed captions/subtitles (default: true).'),
+      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.'),
+      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).'),
+      apiKey: z.string().optional().describe('Optional olo_pat_... token (defaults to OLO_STUDIO_API_KEY env var).'),
+      timeoutMs: z.number().int().positive().optional(),
+    },
+    async (args) => {
+      try {
+        const result = await renderVideoWithBrowser({
+          ...args,
+          apiKey: args.apiKey || serverOpts.apiKey,
+        })
+        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.'),
+      fps: z.union([z.literal(24), z.literal(30), z.literal(60)]).default(30).describe('Frames per second: 24, 30, or 60 (default: 30).'),
+      quality: z.enum(VALID_QUALITIES).default('social').describe('Render quality preset: fast, social, or studio (default: social).'),
+      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).'),
+      voice: z.string().optional().describe('Default voice preset or TTS voice name for variants.'),
+      voiceId: z.string().optional().describe('Default cloned voice ID for neural TTS.'),
+      captions: z.boolean().optional().describe('Include timed captions/subtitles by default (default: true).'),
+      pipPath: z.string().optional().describe('Default local file path for Picture-in-Picture media (png, jpg, webp, mp4, webm).'),
+      pipUrl: z.string().optional().describe('Default remote URL for Picture-in-Picture media.'),
+      glbUrl: z.string().optional(),
+      glbPath: z.string().optional(),
+      studioUrl: z.string().optional(),
+      apiKey: z.string().optional().describe('Optional olo_pat_... token (defaults to OLO_STUDIO_API_KEY env var).'),
+      timeoutMs: z.number().int().positive().optional(),
+    },
+    async (args) => {
+      try {
+        const result = await renderBatchWithBrowser({
+          ...args,
+          apiKey: args.apiKey || serverOpts.apiKey,
+        })
+        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 }
+}