@studiomeyer/mcp-video 1.0.0

package/src/schemas/video.ts

@@ -0,0 +1,211 @@
+/**
+ * MCP Tool Schemas for Cinema Video Engine
+ */
+
+const sceneSchema = {
+  type: 'object' as const,
+  properties: {
+    type: {
+      type: 'string',
+      enum: ['scroll', 'pause', 'hover', 'click', 'type', 'wait'],
+      description: 'Scene type',
+    },
+    to: {
+      type: ['string', 'number'],
+      description: '[scroll] Target: "bottom", "top", pixel number, or CSS selector',
+    },
+    duration: {
+      type: 'number',
+      description: '[scroll/pause/hover] Duration in seconds',
+    },
+    easing: {
+      type: 'string',
+      enum: [
+        'linear', 'easeInQuad', 'easeOutQuad', 'easeInOutQuad',
+        'easeInCubic', 'easeOutCubic', 'easeInOutCubic',
+        'easeInQuart', 'easeOutQuart', 'easeInOutQuart',
+        'easeInQuint', 'easeOutQuint', 'easeInOutQuint',
+        'easeInOutSine', 'cinematic', 'showcase',
+      ],
+      description: '[scroll] Easing curve (default: easeInOutCubic). "showcase" = dramatic slow start/end, "cinematic" = cruise-style',
+    },
+    selector: {
+      type: 'string',
+      description: '[hover/click/type/wait] CSS selector',
+    },
+    text: {
+      type: 'string',
+      description: '[type] Text to type',
+    },
+    delay: {
+      type: 'number',
+      description: '[type] Delay between keystrokes in ms (default: 80)',
+    },
+    waitFor: {
+      type: ['string', 'number'],
+      description: '[click] Wait strategy: "networkidle", "load", or milliseconds',
+    },
+    pauseAfter: {
+      type: 'number',
+      description: '[click] Pause after click in seconds (default: 1)',
+    },
+    animateCursor: {
+      type: 'boolean',
+      description: '[hover] Animate cursor movement (default: true)',
+    },
+    timeout: {
+      type: 'number',
+      description: '[wait] Max wait time in ms (default: 5000)',
+    },
+  },
+  required: ['type'],
+};
+
+export const videoSchemas = [
+  {
+    name: 'record_website_video',
+    description: `Record a cinema-quality video of a website with buttery-smooth 60fps scrolling. Uses frame-by-frame capture (not real-time screen recording) for perfect quality with zero frame drops. Supports custom scenes (scroll, hover, click, pause), multiple viewports (desktop/mobile/4K), cinematic easing curves, and visible cursor simulation. Output: MP4 + thumbnail PNG. Output directory: ./output/ (configurable via VIDEO_OUTPUT_DIR env var).`,
+    annotations: {
+      title: 'Record Website Video',
+      readOnlyHint: false,
+      destructiveHint: false,
+      openWorldHint: true,
+      idempotentHint: true,
+    },
+    inputSchema: {
+      type: 'object' as const,
+      properties: {
+        url: {
+          type: 'string',
+          description: 'URL of the website to record',
+        },
+        outputPath: {
+          type: 'string',
+          description: 'Output file path without extension (default: ./output/website-video-{timestamp})',
+        },
+        viewport: {
+          type: 'string',
+          enum: ['desktop', 'desktop-4k', 'tablet', 'tablet-landscape', 'mobile', 'mobile-landscape'],
+          description: 'Viewport preset (default: desktop = 1920x1080)',
+        },
+        fps: {
+          type: 'number',
+          description: 'Frames per second (default: 60). Use 30 for smaller files.',
+        },
+        scenes: {
+          type: 'array',
+          items: sceneSchema,
+          description: 'Array of scene definitions. If empty, does a default full-page scroll with pause at top/bottom.',
+        },
+        cursor: {
+          type: 'object',
+          properties: {
+            enabled: { type: 'boolean', description: 'Show visible cursor (default: true)' },
+            style: { type: 'string', enum: ['dot', 'arrow', 'pointer'], description: 'Cursor style (default: dot)' },
+            color: { type: 'string', description: 'Cursor color (default: rgba(255,255,255,0.9))' },
+            size: { type: 'number', description: 'Cursor size in px (default: 20)' },
+          },
+          description: 'Cursor configuration',
+        },
+        codec: {
+          type: 'string',
+          enum: ['h264', 'h265', 'vp9'],
+          description: 'Video codec (default: h264). h265 = smaller files, vp9 = WebM format.',
+        },
+        quality: {
+          type: 'number',
+          description: 'CRF quality (0=lossless, 51=worst, default: 18). Lower = better quality, bigger file.',
+        },
+        darkMode: {
+          type: 'boolean',
+          description: 'Enable dark mode (default: false)',
+        },
+        preloadContent: {
+          type: 'boolean',
+          description: 'Pre-scroll to trigger lazy loading (default: true)',
+        },
+        dismissOverlays: {
+          type: 'boolean',
+          description: 'Auto-dismiss cookie banners and popups (default: true)',
+        },
+      },
+      required: ['url'],
+    },
+  },
+  {
+    name: 'record_website_scroll',
+    description: 'Quick scroll-through video of a website. Simplified version of record_website_video — just provide URL and get a smooth 60fps scroll video. Perfect for quick portfolio showcases.',
+    annotations: {
+      title: 'Record Website Scroll',
+      readOnlyHint: false,
+      destructiveHint: false,
+      openWorldHint: true,
+      idempotentHint: true,
+    },
+    inputSchema: {
+      type: 'object' as const,
+      properties: {
+        url: {
+          type: 'string',
+          description: 'URL of the website to record',
+        },
+        duration: {
+          type: 'number',
+          description: 'Scroll duration in seconds (default: 12)',
+        },
+        viewport: {
+          type: 'string',
+          enum: ['desktop', 'desktop-4k', 'tablet', 'mobile'],
+          description: 'Viewport preset (default: desktop)',
+        },
+        easing: {
+          type: 'string',
+          enum: ['easeInOutCubic', 'easeInOutQuint', 'easeInOutSine', 'cinematic', 'showcase'],
+          description: 'Scroll easing curve (default: showcase)',
+        },
+        outputPath: {
+          type: 'string',
+          description: 'Output file path (default: ./output/scroll-{domain}-{timestamp})',
+        },
+      },
+      required: ['url'],
+    },
+  },
+  {
+    name: 'record_multi_device',
+    description: 'Record the same website in multiple viewports (desktop + tablet + mobile) in one go. Creates separate video files for each device. Great for responsive design showcases.',
+    annotations: {
+      title: 'Record Multi-Device Video',
+      readOnlyHint: false,
+      destructiveHint: false,
+      openWorldHint: true,
+      idempotentHint: true,
+    },
+    inputSchema: {
+      type: 'object' as const,
+      properties: {
+        url: {
+          type: 'string',
+          description: 'URL of the website to record',
+        },
+        devices: {
+          type: 'array',
+          items: {
+            type: 'string',
+            enum: ['desktop', 'desktop-4k', 'tablet', 'tablet-landscape', 'mobile', 'mobile-landscape'],
+          },
+          description: 'Device viewports to record (default: ["desktop", "tablet", "mobile"])',
+        },
+        duration: {
+          type: 'number',
+          description: 'Scroll duration per device in seconds (default: 10)',
+        },
+        outputDir: {
+          type: 'string',
+          description: 'Output directory (default: ./output/)',
+        },
+      },
+      required: ['url'],
+    },
+  },
+];

package/src/server.test.ts

@@ -0,0 +1,99 @@
+import { describe, it, expect, vi } from 'vitest';
+
+vi.mock('./lib/logger.js', () => ({
+  logger: { info: vi.fn(), logError: vi.fn(), warn: vi.fn(), error: vi.fn(), debug: vi.fn() },
+}));
+
+vi.mock('./lib/dual-transport.js', () => ({
+  startDualTransport: vi.fn().mockResolvedValue({ type: 'stdio' }),
+}));
+
+vi.mock('./lib/types.js', () => ({
+  jsonResponse: (data: unknown, isError?: boolean) => ({
+    content: [{ type: 'text' as const, text: JSON.stringify(data) }],
+    ...(isError ? { isError: true } : {}),
+  }),
+}));
+
+vi.mock('playwright', () => ({
+  chromium: { launch: vi.fn() },
+}));
+
+describe('createMcpServer', () => {
+  it('creates server with 8 tools', async () => {
+    const { createMcpServer } = await import('./server.js');
+    const server = createMcpServer();
+    expect(server).toBeDefined();
+  });
+});
+
+describe('delegate function', () => {
+  it('server exports createMcpServer', async () => {
+    const mod = await import('./server.js');
+    expect(typeof mod.createMcpServer).toBe('function');
+  });
+});
+
+describe('handler registries', () => {
+  it('video handlers exist', async () => {
+    const { videoHandlers } = await import('./handlers/video.js');
+    expect(videoHandlers).toBeDefined();
+    expect(videoHandlers.record_website_video).toBeDefined();
+    expect(videoHandlers.record_website_scroll).toBeDefined();
+    expect(videoHandlers.record_multi_device).toBeDefined();
+  });
+
+  it('editing handlers exist', async () => {
+    const { editingHandlers } = await import('./handlers/editing.js');
+    expect(editingHandlers).toBeDefined();
+    expect(editingHandlers.adjust_video_speed).toBeDefined();
+    expect(editingHandlers.crop_video).toBeDefined();
+    expect(editingHandlers.reverse_clip).toBeDefined();
+  });
+
+  it('capcut handlers exist', async () => {
+    const { capcutHandlers } = await import('./handlers/capcut.js');
+    expect(capcutHandlers).toBeDefined();
+    expect(capcutHandlers.apply_lut_preset).toBeDefined();
+    expect(capcutHandlers.sync_to_beat).toBeDefined();
+  });
+
+  it('post-production handlers exist', async () => {
+    const { postProductionHandlers } = await import('./handlers/post-production.js');
+    expect(postProductionHandlers).toBeDefined();
+    expect(postProductionHandlers.concatenate_videos).toBeDefined();
+    expect(postProductionHandlers.convert_social_format).toBeDefined();
+  });
+
+  it('tts handlers exist', async () => {
+    const { ttsHandlers } = await import('./handlers/tts.js');
+    expect(ttsHandlers).toBeDefined();
+    expect(ttsHandlers.generate_speech).toBeDefined();
+    expect(ttsHandlers.list_voices).toBeDefined();
+    expect(ttsHandlers.create_narrated_video).toBeDefined();
+  });
+
+  it('screenshot handlers exist', async () => {
+    const { smartScreenshotHandlers } = await import('./handlers/smart-screenshot.js');
+    expect(smartScreenshotHandlers).toBeDefined();
+    expect(smartScreenshotHandlers.screenshot_element).toBeDefined();
+    expect(smartScreenshotHandlers.detect_page_features).toBeDefined();
+  });
+});
+
+describe('tool consolidation', () => {
+  it('all handler names are covered by delegate map', () => {
+    const allOriginalNames = [
+      'record_website_video', 'record_website_scroll', 'record_multi_device',
+      'adjust_video_speed', 'crop_video', 'reverse_clip', 'add_keyframe_animation', 'compose_picture_in_pip',
+      'apply_color_grade', 'apply_video_effect', 'apply_lut_preset', 'apply_chroma_key',
+      'extract_audio', 'add_background_music', 'add_audio_ducking', 'mix_audio_tracks', 'apply_voice_effect',
+      'burn_subtitles', 'auto_caption', 'add_text_overlay', 'animate_text',
+      'concatenate_videos', 'generate_intro', 'convert_social_format', 'convert_all_social_formats',
+      'sync_to_beat', 'list_video_templates', 'render_template',
+      'generate_speech', 'list_voices', 'create_narrated_video',
+      'screenshot_element', 'detect_page_features',
+    ];
+    expect(allOriginalNames.length).toBe(33);
+  });
+});

package/src/server.ts

@@ -0,0 +1,289 @@
+#!/usr/bin/env node
+/**
+ * Video Production — MCP Server v1.0.0
+ *
+ * 8 consolidated tools (from 33+) for recording, editing, color grading,
+ * audio, text, compositing, speech/narration, and smart screenshots.
+ *
+ * Port: 9847 (HTTP mode, configurable via MCP_PORT)
+ */
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { z } from 'zod';
+import { logger } from './lib/logger.js';
+import { startDualTransport } from './lib/dual-transport.js';
+import { videoHandlers } from './handlers/video.js';
+import { editingHandlers } from './handlers/editing.js';
+import { capcutHandlers } from './handlers/capcut.js';
+import { postProductionHandlers } from './handlers/post-production.js';
+import { ttsHandlers } from './handlers/tts.js';
+import { smartScreenshotHandlers } from './handlers/smart-screenshot.js';
+
+const SERVER_NAME = 'mcp-video';
+const SERVER_VERSION = '1.0.0';
+
+/* eslint-disable @typescript-eslint/no-explicit-any */
+const ALL_HANDLERS: Record<string, (a: any) => any> = {
+  ...videoHandlers,
+  ...editingHandlers,
+  ...capcutHandlers,
+  ...postProductionHandlers,
+  ...ttsHandlers,
+  ...smartScreenshotHandlers,
+};
+
+/** Delegate to existing handler by original tool name, fix content type literals */
+async function delegate(name: string, args: Record<string, unknown>) {
+  const handler = ALL_HANDLERS[name];
+  if (!handler) throw new Error(`Unknown handler: ${name}`);
+  const result = await handler(args);
+  // Ensure content items have literal 'text' type for MCP SDK
+  if (result?.content) {
+    for (const item of result.content) {
+      if (item.type === 'text') item.type = 'text' as const;
+    }
+  }
+  return result;
+}
+
+export function createMcpServer() {
+  const server = new McpServer(
+    { name: SERVER_NAME, version: SERVER_VERSION },
+    {
+      instructions: `# Video Server — Tool Selection Guide
+
+You have 8 tools for video production. Each has a \`type\` parameter to select the operation.
+
+## Recording:
+- **video_record** — Record websites: cinema (full control), scroll (quick scroll-through), multi-device (desktop+tablet+mobile)
+
+## Editing:
+- **video_edit** — Edit clips: speed (slow-mo/timelapse), crop, reverse, keyframe (zoom/pan), pip (picture-in-picture)
+- **video_color** — Color & effects: grade (brightness/contrast/etc), effect (blur/sharpen/vignette/etc), lut (22 cinema presets), chroma (green screen)
+- **video_audio** — Audio: extract, music (background), ducking (auto volume), mix (multi-track), voice (effects like echo/robot/whisper)
+- **video_text** — Text & captions: subtitles (burn SRT), caption (Whisper AI auto-caption), overlay (animated text layers), animate (15 text animations)
+
+## Post-Production:
+- **video_compose** — Compose: concat (join clips), intro (animated intro/outro), social (format for Instagram/TikTok/etc), social-all (batch all platforms), beat-sync (cuts on music beats), templates (list), render (from template)
+
+## Speech & AI:
+- **video_speech** — TTS & narration: generate (ElevenLabs/OpenAI speech), voices (list available), narrated (full narrated video from script)
+
+## Screenshots:
+- **video_screenshot** — Smart screenshots: capture (element-aware), detect (page feature analysis)
+
+## Decision Flow:
+1. Record website? → video_record
+2. Edit existing video? → video_edit
+3. Color/effects? → video_color
+4. Audio work? → video_audio
+5. Text/captions? → video_text
+6. Join clips/format? → video_compose
+7. Need voiceover? → video_speech
+8. Screenshots? → video_screenshot`,
+    },
+  );
+
+  // ── 1. video_record ────────────────────────────────────
+  server.registerTool(
+    'video_record',
+    {
+      title: 'Record Website Video',
+      description: 'Record website videos. Types: cinema (full 60fps with scenes/cursor), scroll (quick scroll-through), multi-device (desktop+tablet+mobile).',
+      inputSchema: z.object({
+        type: z.enum(['cinema', 'scroll', 'multi-device']).describe('Recording type'),
+        url: z.string().min(1).describe('Website URL'),
+      }).passthrough(),
+      annotations: { title: 'Record Video', readOnlyHint: false, openWorldHint: true },
+    },
+    async (args) => {
+      const { type, ...rest } = args;
+      const handlerName = type === 'cinema' ? 'record_website_video'
+        : type === 'scroll' ? 'record_website_scroll'
+        : 'record_multi_device';
+      return await delegate(handlerName, rest);
+    },
+  );
+
+  // ── 2. video_edit ──────────────────────────────────────
+  server.registerTool(
+    'video_edit',
+    {
+      title: 'Edit Video',
+      description: 'Edit video clips. Types: speed (0.25x-4x), crop (region), reverse (± audio), keyframe (zoom/pan animation), pip (picture-in-picture overlay).',
+      inputSchema: z.object({
+        type: z.enum(['speed', 'crop', 'reverse', 'keyframe', 'pip']).describe('Edit operation'),
+      }).passthrough(),
+      annotations: { title: 'Edit Video', readOnlyHint: false },
+    },
+    async (args) => {
+      const { type, ...rest } = args;
+      const map: Record<string, string> = {
+        speed: 'adjust_video_speed', crop: 'crop_video', reverse: 'reverse_clip',
+        keyframe: 'add_keyframe_animation', pip: 'compose_picture_in_pip',
+      };
+      return await delegate(map[type], rest);
+    },
+  );
+
+  // ── 3. video_color ─────────────────────────────────────
+  server.registerTool(
+    'video_color',
+    {
+      title: 'Color & Effects',
+      description: 'Color grading & visual effects. Types: grade (brightness/contrast/saturation/gamma/temperature), effect (blur/sharpen/vignette/grayscale/sepia/noise/glow), lut (22 cinema presets), chroma (green/blue screen replacement).',
+      inputSchema: z.object({
+        type: z.enum(['grade', 'effect', 'lut', 'chroma']).describe('Color operation'),
+      }).passthrough(),
+      annotations: { title: 'Color & Effects', readOnlyHint: false },
+    },
+    async (args) => {
+      const { type, ...rest } = args;
+      const map: Record<string, string> = {
+        grade: 'apply_color_grade', effect: 'apply_video_effect',
+        lut: 'apply_lut_preset', chroma: 'apply_chroma_key',
+      };
+      return await delegate(map[type], rest);
+    },
+  );
+
+  // ── 4. video_audio ─────────────────────────────────────
+  server.registerTool(
+    'video_audio',
+    {
+      title: 'Audio Tools',
+      description: 'Audio operations. Types: extract (MP3/AAC/WAV/FLAC from video), music (add background music with fade), ducking (auto volume reduction), mix (multi-track mixing), voice (9 voice effects: echo/reverb/deep/chipmunk/robot/whisper/radio/megaphone/underwater).',
+      inputSchema: z.object({
+        type: z.enum(['extract', 'music', 'ducking', 'mix', 'voice']).describe('Audio operation'),
+      }).passthrough(),
+      annotations: { title: 'Audio', readOnlyHint: false },
+    },
+    async (args) => {
+      const { type, ...rest } = args;
+      const map: Record<string, string> = {
+        extract: 'extract_audio', music: 'add_background_music',
+        ducking: 'add_audio_ducking', mix: 'mix_audio_tracks', voice: 'apply_voice_effect',
+      };
+      return await delegate(map[type], rest);
+    },
+  );
+
+  // ── 5. video_text ──────────────────────────────────────
+  server.registerTool(
+    'video_text',
+    {
+      title: 'Text & Captions',
+      description: 'Text overlays & captions. Types: subtitles (burn SRT/ASS), caption (Whisper AI auto-caption), overlay (animated text layers), animate (15 text animation styles).',
+      inputSchema: z.object({
+        type: z.enum(['subtitles', 'caption', 'overlay', 'animate']).describe('Text operation'),
+      }).passthrough(),
+      annotations: { title: 'Text & Captions', readOnlyHint: false },
+    },
+    async (args) => {
+      const { type, ...rest } = args;
+      const map: Record<string, string> = {
+        subtitles: 'burn_subtitles', caption: 'auto_caption',
+        overlay: 'add_text_overlay', animate: 'animate_text',
+      };
+      return await delegate(map[type], rest);
+    },
+  );
+
+  // ── 6. video_compose ───────────────────────────────────
+  server.registerTool(
+    'video_compose',
+    {
+      title: 'Compose & Export',
+      description: 'Compose and export videos. Types: concat (join clips with transitions), intro (animated intro/outro), social (convert to Instagram/TikTok/YouTube/LinkedIn), social-all (batch all platforms), beat-sync (cut on music beats), templates (list available), render (render from template).',
+      inputSchema: z.object({
+        type: z.enum(['concat', 'intro', 'social', 'social-all', 'beat-sync', 'templates', 'render']).describe('Compose operation'),
+      }).passthrough(),
+      annotations: { title: 'Compose & Export', readOnlyHint: false },
+    },
+    async (args) => {
+      const { type, ...rest } = args;
+      const map: Record<string, string> = {
+        concat: 'concatenate_videos', intro: 'generate_intro',
+        social: 'convert_social_format', 'social-all': 'convert_all_social_formats',
+        'beat-sync': 'sync_to_beat', templates: 'list_video_templates', render: 'render_template',
+      };
+      return await delegate(map[type], rest);
+    },
+  );
+
+  // ── 7. video_speech ────────────────────────────────────
+  server.registerTool(
+    'video_speech',
+    {
+      title: 'Speech & Narration',
+      description: 'Text-to-speech & narrated videos. Types: generate (ElevenLabs/OpenAI TTS), voices (list available voices), narrated (full narrated video: script → TTS → website recording → sync → MP4).',
+      inputSchema: z.object({
+        type: z.enum(['generate', 'voices', 'narrated']).describe('Speech operation'),
+      }).passthrough(),
+      annotations: { title: 'Speech & Narration', readOnlyHint: false, openWorldHint: true },
+    },
+    async (args) => {
+      const { type, ...rest } = args;
+      const map: Record<string, string> = {
+        generate: 'generate_speech', voices: 'list_voices', narrated: 'create_narrated_video',
+      };
+      return await delegate(map[type], rest);
+    },
+  );
+
+  // ── 8. video_screenshot ────────────────────────────────
+  server.registerTool(
+    'video_screenshot',
+    {
+      title: 'Smart Screenshot',
+      description: 'Smart element-aware screenshots. Types: capture (detect & screenshot specific page features: chat, pricing, hero, etc.), detect (analyze page features without screenshotting).',
+      inputSchema: z.object({
+        type: z.enum(['capture', 'detect']).describe('Screenshot operation'),
+        url: z.string().min(1).describe('Website URL'),
+      }).passthrough(),
+      annotations: { title: 'Smart Screenshot', readOnlyHint: true, openWorldHint: true },
+    },
+    async (args) => {
+      const { type, ...rest } = args;
+      const handlerName = type === 'capture' ? 'screenshot_element' : 'detect_page_features';
+      return await delegate(handlerName, rest);
+    },
+  );
+
+  return server;
+}
+
+// ─── Startup Validation ──────────────────────────────────
+
+import { execSync } from 'child_process';
+import * as fs from 'fs';
+
+function checkDependencies(): void {
+  for (const bin of ['ffmpeg', 'ffprobe']) {
+    try {
+      execSync(`which ${bin}`, { stdio: 'pipe' });
+    } catch {
+      logger.error(`${bin} not found. Install ffmpeg: https://ffmpeg.org/download.html`);
+      process.exit(1);
+    }
+  }
+
+  const outputDir = process.env.VIDEO_OUTPUT_DIR || './output';
+  if (!fs.existsSync(outputDir)) {
+    fs.mkdirSync(outputDir, { recursive: true });
+    logger.info(`Created output directory: ${outputDir}`);
+  }
+}
+
+// ─── Start ────────────────────────────────────────────────
+checkDependencies();
+
+startDualTransport(createMcpServer, {
+  serverName: SERVER_NAME,
+  serverVersion: SERVER_VERSION,
+  defaultPort: 9847,
+}).then((result: { type: string; port?: number }) => {
+  logger.info(`Video MCP Server running — 8 tools (${result.type}${result.port ? ` :${result.port}` : ''})`);
+}).catch((error) => {
+  logger.logError('Fatal error', error);
+  process.exit(1);
+});