@studiomeyer/mcp-video 1.0.0

package/src/handlers/video.ts

@@ -0,0 +1,137 @@
+/**
+ * Video recording tool handlers
+ */
+
+import { jsonResponse, type ToolHandler } from '../lib/types.js';
+import { logger } from '../lib/logger.js';
+import { recordWebsite } from '../tools/index.js';
+import type { RecordingConfig, Scene, ViewportPreset } from '../tools/index.js';
+import * as path from 'path';
+
+const OUTPUT_DIR = process.env.VIDEO_OUTPUT_DIR || './output';
+
+export const videoHandlers: Record<string, ToolHandler> = {
+  /**
+   * Full-featured website video recording
+   */
+  record_website_video: async (args) => {
+    try {
+      const config: RecordingConfig = {
+        url: args.url,
+        outputPath: args.outputPath ?? generateOutputPath(args.url, 'video'),
+        viewport: args.viewport as ViewportPreset ?? 'desktop',
+        fps: args.fps ?? 60,
+        scenes: args.scenes as Scene[] | undefined,
+        cursor: args.cursor ?? { enabled: true },
+        encoding: {
+          codec: args.codec ?? 'h264',
+          crf: args.quality ?? 18,
+        },
+        darkMode: args.darkMode ?? false,
+        preloadContent: args.preloadContent ?? true,
+        dismissOverlays: args.dismissOverlays ?? true,
+      };
+
+      const result = await recordWebsite(config);
+      return jsonResponse(result);
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      logger.error(`record_website_video failed: ${message}`);
+      return jsonResponse({ success: false, error: message }, true);
+    }
+  },
+
+  /**
+   * Quick scroll-through video
+   */
+  record_website_scroll: async (args) => {
+    try {
+      const duration = args.duration ?? 12;
+      const easing = args.easing ?? 'showcase';
+
+      const config: RecordingConfig = {
+        url: args.url,
+        outputPath: args.outputPath ?? generateOutputPath(args.url, 'scroll'),
+        viewport: (args.viewport as ViewportPreset) ?? 'desktop',
+        fps: 60,
+        scenes: [
+          { type: 'pause', duration: 1.5 },
+          { type: 'scroll', to: 'bottom', duration, easing },
+          { type: 'pause', duration: 2 },
+        ],
+        cursor: { enabled: false },
+        encoding: { codec: 'h264', crf: 18 },
+      };
+
+      const result = await recordWebsite(config);
+      return jsonResponse(result);
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      logger.error(`record_website_scroll failed: ${message}`);
+      return jsonResponse({ success: false, error: message }, true);
+    }
+  },
+
+  /**
+   * Multi-device recording
+   */
+  record_multi_device: async (args) => {
+    try {
+      const devices: ViewportPreset[] = args.devices ?? ['desktop', 'tablet', 'mobile'];
+      const duration = args.duration ?? 10;
+      const outputDir = args.outputDir ?? OUTPUT_DIR;
+      const results: Record<string, unknown> = {};
+
+      for (const device of devices) {
+        logger.info(`Recording ${device} viewport for ${args.url}...`);
+
+        const config: RecordingConfig = {
+          url: args.url,
+          outputPath: path.join(outputDir, generateOutputName(args.url, device)),
+          viewport: device,
+          fps: 60,
+          scenes: [
+            { type: 'pause', duration: 1 },
+            { type: 'scroll', to: 'bottom', duration, easing: 'showcase' },
+            { type: 'pause', duration: 1.5 },
+          ],
+          cursor: { enabled: device !== 'mobile' && device !== 'mobile-landscape' },
+          encoding: { codec: 'h264', crf: 18 },
+        };
+
+        const result = await recordWebsite(config);
+        results[device] = result;
+      }
+
+      return jsonResponse({
+        success: true,
+        devices: devices.length,
+        results,
+      });
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      logger.error(`record_multi_device failed: ${message}`);
+      return jsonResponse({ success: false, error: message }, true);
+    }
+  },
+};
+
+/**
+ * Generate a descriptive output path from URL
+ */
+function generateOutputPath(url: string, prefix: string): string {
+  const name = generateOutputName(url, prefix);
+  return path.join(OUTPUT_DIR, name);
+}
+
+function generateOutputName(url: string, suffix: string): string {
+  try {
+    const hostname = new URL(url).hostname
+      .replace(/^www\./, '')
+      .replace(/\./g, '-');
+    const timestamp = new Date().toISOString().slice(0, 10);
+    return `${hostname}-${suffix}-${timestamp}`;
+  } catch {
+    return `website-${suffix}-${Date.now()}`;
+  }
+}

package/src/lib/dual-transport.ts

@@ -0,0 +1,272 @@
+/**
+ * Dual Transport for MCP Servers — Stdio + Streamable HTTP
+ *
+ * Default: stdio (backward compatible, used by Claude Code via subprocess)
+ * --http: Streamable HTTP on configurable port (persistent HTTP microservice)
+ *
+ * Usage:
+ *   startDualTransport(createMcpServer, { serverName, serverVersion, defaultPort })
+ *
+ * HTTP mode flags:
+ *   --http           Enable HTTP transport
+ *   --port=XXXX      Override default port
+ *   MCP_HTTP=1       Enable via env var
+ *   MCP_PORT=XXXX    Override port via env var
+ */
+
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/streamableHttp.js';
+import { createServer as createHttpServer, type IncomingMessage, type ServerResponse } from 'node:http';
+import { randomUUID } from 'node:crypto';
+import { logger } from './logger.js';
+
+// ─── Types ───────────────────────────────────────────
+
+/** Any MCP server that can connect to a transport */
+type ConnectableServer = { connect(transport: unknown): Promise<void> };
+
+/** Factory function that creates a fresh MCP server instance */
+export type McpServerFactory = () => ConnectableServer;
+
+export interface DualTransportOptions {
+  serverName: string;
+  serverVersion: string;
+  /** Default HTTP port (used when --http is active) */
+  defaultPort: number;
+}
+
+export interface TransportResult {
+  type: 'stdio' | 'http';
+  port?: number;
+}
+
+// ─── Detection ───────────────────────────────────────
+
+function isHttpMode(): boolean {
+  return (
+    process.argv.includes('--http') ||
+    process.env.MCP_HTTP === '1' ||
+    process.env.MCP_HTTP === 'true'
+  );
+}
+
+function getPort(defaultPort: number): number {
+  const portArg = process.argv.find((a) => a.startsWith('--port='));
+  if (portArg) {
+    const parsed = parseInt(portArg.split('=')[1], 10);
+    if (!isNaN(parsed)) return parsed;
+  }
+  if (process.env.MCP_PORT) {
+    const parsed = parseInt(process.env.MCP_PORT, 10);
+    if (!isNaN(parsed)) return parsed;
+  }
+  return defaultPort;
+}
+
+// ─── Main Entry ──────────────────────────────────────
+
+/**
+ * Start an MCP server with dual transport support.
+ *
+ * @param createServer - Factory that creates a fresh MCP server (McpServer or Server)
+ * @param options - Server name, version, and default HTTP port
+ *
+ * For stdio: creates one server, connects to StdioServerTransport.
+ * For HTTP: creates a new server per session, connects to StreamableHTTPServerTransport.
+ */
+export async function startDualTransport(
+  createServer: McpServerFactory,
+  options: DualTransportOptions,
+): Promise<TransportResult> {
+  if (isHttpMode()) {
+    return startHttpTransport(createServer, options);
+  }
+  return startStdioTransport(createServer, options);
+}
+
+// ─── Stdio Transport ─────────────────────────────────
+
+async function startStdioTransport(
+  createServer: McpServerFactory,
+  options: DualTransportOptions,
+): Promise<TransportResult> {
+  const server = createServer();
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+  logger.info(`${options.serverName} v${options.serverVersion} started (stdio)`);
+  return { type: 'stdio' };
+}
+
+// ─── HTTP Transport ──────────────────────────────────
+
+interface SessionEntry {
+  transport: StreamableHTTPServerTransport;
+  createdAt: number;
+}
+
+async function startHttpTransport(
+  createServer: McpServerFactory,
+  options: DualTransportOptions,
+): Promise<TransportResult> {
+  const port = getPort(options.defaultPort);
+  const sessions = new Map<string, SessionEntry>();
+
+  const httpServer = createHttpServer(async (req: IncomingMessage, res: ServerResponse) => {
+    try {
+      await handleHttpRequest(req, res, sessions, createServer, options);
+    } catch (err) {
+      logger.logError('HTTP request error', err);
+      if (!res.headersSent) {
+        res.writeHead(500, { 'Content-Type': 'application/json' });
+        res.end(JSON.stringify({ error: 'Internal server error' }));
+      }
+    }
+  });
+
+  const host = process.env.MCP_HOST || '127.0.0.1';
+  httpServer.listen(port, host, () => {
+    logger.info(`${options.serverName} v${options.serverVersion} started (HTTP on ${host}:${port})`);
+  });
+
+  // Session cleanup: remove stale sessions older than 30 minutes
+  const cleanupInterval = setInterval(() => {
+    const now = Date.now();
+    const staleThreshold = 30 * 60 * 1000;
+    for (const [sid, session] of sessions) {
+      if (now - session.createdAt > staleThreshold) {
+        session.transport.close();
+        sessions.delete(sid);
+        logger.info(`Session expired: ${sid.slice(0, 8)}...`);
+      }
+    }
+  }, 60_000);
+
+  // Graceful shutdown
+  const shutdown = () => {
+    logger.info('Shutting down HTTP transport...');
+    clearInterval(cleanupInterval);
+    for (const [, session] of sessions) {
+      session.transport.close();
+    }
+    httpServer.close();
+    process.exit(0);
+  };
+  process.on('SIGINT', shutdown);
+  process.on('SIGTERM', shutdown);
+
+  return { type: 'http', port };
+}
+
+// ─── Request Handler ─────────────────────────────────
+
+async function handleHttpRequest(
+  req: IncomingMessage,
+  res: ServerResponse,
+  sessions: Map<string, SessionEntry>,
+  createServer: McpServerFactory,
+  options: DualTransportOptions,
+): Promise<void> {
+  // CORS headers
+  res.setHeader('Access-Control-Allow-Origin', '*');
+  res.setHeader('Access-Control-Allow-Methods', 'GET, POST, DELETE, OPTIONS');
+  res.setHeader('Access-Control-Allow-Headers', 'Content-Type, MCP-Session-ID');
+  res.setHeader('Access-Control-Expose-Headers', 'MCP-Session-ID');
+
+  if (req.method === 'OPTIONS') {
+    res.writeHead(204);
+    res.end();
+    return;
+  }
+
+  // Health check endpoint
+  if (req.url === '/health') {
+    res.writeHead(200, { 'Content-Type': 'application/json' });
+    res.end(
+      JSON.stringify({
+        status: 'ok',
+        server: options.serverName,
+        version: options.serverVersion,
+        transport: 'streamable-http',
+        sessions: sessions.size,
+      }),
+    );
+    return;
+  }
+
+  // MCP endpoint
+  if (req.url === '/mcp') {
+    const sessionId = req.headers['mcp-session-id'] as string | undefined;
+
+    if (req.method === 'POST') {
+      const body = await parseBody(req);
+
+      if (sessionId && sessions.has(sessionId)) {
+        await sessions.get(sessionId)!.transport.handleRequest(req, res, body);
+      } else if (!sessionId) {
+        const mcpServer = createServer();
+        const transport = new StreamableHTTPServerTransport({
+          sessionIdGenerator: () => randomUUID(),
+          onsessioninitialized: (sid: string) => {
+            sessions.set(sid, { transport, createdAt: Date.now() });
+            logger.info(`Session created: ${sid.slice(0, 8)}... (${sessions.size} active)`);
+          },
+          onsessionclosed: (sid: string) => {
+            sessions.delete(sid);
+            logger.info(`Session closed: ${sid.slice(0, 8)}... (${sessions.size} active)`);
+          },
+        });
+
+        await mcpServer.connect(transport);
+        await transport.handleRequest(req, res, body);
+      } else {
+        res.writeHead(404, { 'Content-Type': 'application/json' });
+        res.end(JSON.stringify({ error: 'Session not found', code: 'SESSION_NOT_FOUND' }));
+      }
+      return;
+    }
+
+    if (req.method === 'GET') {
+      if (sessionId && sessions.has(sessionId)) {
+        await sessions.get(sessionId)!.transport.handleRequest(req, res);
+      } else {
+        res.writeHead(400, { 'Content-Type': 'application/json' });
+        res.end(JSON.stringify({ error: 'Invalid or missing session ID', code: 'INVALID_SESSION' }));
+      }
+      return;
+    }
+
+    if (req.method === 'DELETE') {
+      if (sessionId && sessions.has(sessionId)) {
+        const session = sessions.get(sessionId)!;
+        await session.transport.handleRequest(req, res);
+        sessions.delete(sessionId);
+      } else {
+        res.writeHead(404, { 'Content-Type': 'application/json' });
+        res.end(JSON.stringify({ error: 'Session not found', code: 'SESSION_NOT_FOUND' }));
+      }
+      return;
+    }
+  }
+
+  // 404 for anything else
+  res.writeHead(404, { 'Content-Type': 'application/json' });
+  res.end(JSON.stringify({ error: 'Not found', code: 'NOT_FOUND' }));
+}
+
+// ─── Body Parser ─────────────────────────────────────
+
+function parseBody(req: IncomingMessage): Promise<unknown> {
+  return new Promise((resolve, reject) => {
+    const chunks: Buffer[] = [];
+    req.on('data', (chunk: Buffer) => chunks.push(chunk));
+    req.on('end', () => {
+      const body = Buffer.concat(chunks).toString('utf-8');
+      try {
+        resolve(body ? JSON.parse(body) : undefined);
+      } catch {
+        resolve(undefined);
+      }
+    });
+    req.on('error', reject);
+  });
+}

package/src/lib/logger.ts

@@ -0,0 +1,59 @@
+/**
+ * Structured logging for mcp-video
+ * Logs to stderr to not interfere with MCP protocol on stdout
+ */
+
+type LogLevel = 'debug' | 'info' | 'warn' | 'error';
+
+interface LogEntry {
+  level: LogLevel;
+  message: string;
+  context?: Record<string, unknown>;
+  timestamp: string;
+}
+
+const DEBUG = process.env.DEBUG?.includes('mcp-video') || process.env.MCP_VIDEO_DEBUG === '1';
+
+function formatEntry(entry: LogEntry): string {
+  const prefix = `[${entry.timestamp}] [${entry.level.toUpperCase()}]`;
+  const ctx = entry.context ? ` ${JSON.stringify(entry.context)}` : '';
+  return `${prefix} ${entry.message}${ctx}`;
+}
+
+function log(level: LogLevel, message: string, context?: Record<string, unknown>): void {
+  if (level === 'debug' && !DEBUG) return;
+
+  const entry: LogEntry = {
+    level,
+    message,
+    context,
+    timestamp: new Date().toISOString(),
+  };
+
+  console.error(formatEntry(entry));
+}
+
+export const logger = {
+  debug: (message: string, context?: Record<string, unknown>) => log('debug', message, context),
+  info: (message: string, context?: Record<string, unknown>) => log('info', message, context),
+  warn: (message: string, context?: Record<string, unknown>) => log('warn', message, context),
+  error: (message: string, context?: Record<string, unknown>) => log('error', message, context),
+
+  logError: (message: string, error: unknown, context?: Record<string, unknown>) => {
+    const errorContext: Record<string, unknown> = { ...context };
+
+    if (error instanceof Error) {
+      errorContext.errorMessage = error.message;
+      errorContext.errorName = error.name;
+      if (DEBUG && error.stack) {
+        errorContext.stack = error.stack;
+      }
+    } else {
+      errorContext.error = String(error);
+    }
+
+    log('error', message, errorContext);
+  },
+};
+
+export type Logger = typeof logger;

package/src/lib/types.ts

@@ -0,0 +1,25 @@
+/**
+ * Shared types for MCP tool handlers
+ */
+
+export interface ToolResponse {
+  [key: string]: unknown;
+  content: Array<{ type: string; text: string }>;
+  isError?: boolean;
+}
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any -- MCP SDK passes raw JSON; validation is via tool schemas
+export type ToolHandler = (args: any) => ToolResponse | Promise<ToolResponse>;
+
+/** Helper to wrap a JSON result into a ToolResponse */
+export function jsonResponse(result: unknown, isError?: boolean): ToolResponse {
+  return {
+    content: [{ type: 'text', text: JSON.stringify(result, null, 2) }],
+    ...(isError !== undefined ? { isError } : {}),
+  };
+}
+
+/** Helper to create an error ToolResponse with structured error code */
+export function errorResponse(message: string, code?: string): ToolResponse {
+  return jsonResponse({ error: message, code: code ?? 'INTERNAL_ERROR' }, true);
+}