@studiomeyer/mcp-video 1.0.0

package/.github/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,31 @@
+---
+name: Bug Report
+about: Report a bug in mcp-video
+title: '[Bug] '
+labels: bug
+assignees: ''
+---
+
+## Describe the bug
+A clear description of what the bug is.
+
+## To Reproduce
+Steps to reproduce:
+1. Tool called: `video_record` / `video_edit` / etc.
+2. Parameters used: ...
+3. Error message: ...
+
+## Expected behavior
+What you expected to happen.
+
+## Environment
+- OS: [e.g., Ubuntu 22.04, macOS 14]
+- Node.js: [e.g., 20.x]
+- ffmpeg version: [run `ffmpeg -version`]
+- MCP client: [e.g., Claude Code, Claude Desktop]
+- Transport: [stdio / HTTP]
+
+## Logs
+```
+Paste any relevant log output here
+```

package/.github/ISSUE_TEMPLATE/feature_request.md

@@ -0,0 +1,19 @@
+---
+name: Feature Request
+about: Suggest a new feature or improvement
+title: '[Feature] '
+labels: enhancement
+assignees: ''
+---
+
+## Is your feature request related to a problem?
+A clear description of the problem.
+
+## Describe the solution you'd like
+What you want to happen.
+
+## Use case
+How would you use this feature?
+
+## Alternatives considered
+Any alternative solutions or features you've considered.

package/.github/workflows/ci.yml

@@ -0,0 +1,34 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        node-version: [18, 20, 22]
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Use Node.js ${{ matrix.node-version }}
+        uses: actions/setup-node@v4
+        with:
+          node-version: ${{ matrix.node-version }}
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Type check
+        run: npm run typecheck
+
+      - name: Install ffmpeg
+        run: sudo apt-get update && sudo apt-get install -y ffmpeg
+
+      - name: Run tests
+        run: npm test

package/CHANGELOG.md

@@ -0,0 +1,24 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [1.0.0] - 2026-03-14
+
+### Added
+
+- **40+ video/image tools** — comprehensive MCP toolset for video production
+- **Website recording** — full-page and element recording via Playwright
+- **Video editing** — cut, concatenate, crop, speed adjust, reverse, PiP compose via FFmpeg
+- **TTS narration** — text-to-speech with multiple voices and voice effects
+- **Social format export** — one-click conversion to Instagram, TikTok, YouTube Shorts, LinkedIn formats
+- **Dual transport** — stdio for CLI integration, HTTP for remote/agent access
+- **Smart screenshots** — element-level and full-page capture with auto-scroll
+- **Cinema-grade animations** — keyframe animations, text overlays, animated titles
+- **Color grading** — LUT presets and custom color grade application
+- **Audio tools** — background music, audio ducking, beat sync, multi-track mixing
+- **Chroma key** — green screen removal
+- **Auto captions** — automatic subtitle generation and burn-in
+- **Carousel and intro generation** — templated content creation

package/CONTRIBUTING.md

@@ -0,0 +1,75 @@
+# Contributing to MCP Video
+
+Thanks for your interest in contributing! MCP Video is an open-source Model Context Protocol server for video production, and we welcome contributions.
+
+## Getting Started
+
+1. Fork the repo and clone your fork
+2. Create a feature branch (`git checkout -b feat/my-feature`)
+3. Make your changes
+4. Run tests and submit a PR
+
+```bash
+git clone https://github.com/studiomeyer-io/mcp-video.git
+cd mcp-video
+npm install
+npm run build
+npm test
+```
+
+## Prerequisites
+
+- **Node.js 18+**
+- **FFmpeg** — installed and available in PATH (`ffmpeg -version`)
+- **Playwright** — installed with browsers (`npx playwright install chromium`)
+
+## Development
+
+### Project Structure
+
+```
+src/
+  tools/       — Tool implementations (40+ tools)
+  services/    — FFmpeg, Playwright, TTS services
+  transport/   — stdio + HTTP transport
+scripts/       — Build and utility scripts
+output/        — Generated files (gitignored)
+```
+
+### Commands
+
+```bash
+npm test          # Run all tests
+npm run build     # Build TypeScript
+npm start         # Start MCP server (stdio)
+```
+
+### Code Standards
+
+- **TypeScript strict** — no exceptions
+- **No `any`** — ever
+- **Tests must pass** before any PR
+- Tool implementations follow the MCP tool interface pattern
+
+## Adding a Tool
+
+1. Create your tool in `src/tools/`
+2. Follow the existing tool pattern (input schema, handler, output)
+3. Register it in the tool list
+4. Add tests
+5. Update the README with the new tool
+
+## Pull Requests
+
+1. Fork the repo and create a feature branch
+2. Make your changes
+3. Run `npm test`
+4. Submit a PR with a clear description of what and why
+
+## Reporting Security Issues
+
+If you find a security vulnerability, please email security@studiomeyer.io instead of opening a public issue.
+
+## License
+
+By contributing, you agree that your contributions will be licensed under the MIT License.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 StudioMeyer
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,198 @@
+<div align="center">
+
+# mcp-video
+
+**Cinema-grade video production for AI agents.**
+
+![CI](https://github.com/studiomeyer-io/mcp-video/actions/workflows/ci.yml/badge.svg)
+![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)
+![TypeScript](https://img.shields.io/badge/TypeScript-strict-blue)
+![Version](https://img.shields.io/badge/version-1.0.0-blue)
+[![npm version](https://img.shields.io/npm/v/mcp-video?color=blue)](https://www.npmjs.com/package/mcp-video)
+[![Node](https://img.shields.io/badge/node-%3E%3D18-brightgreen.svg)](https://nodejs.org)
+
+8 MCP tools for recording, editing, effects, captions, TTS, and smart screenshots.<br>
+Built on [ffmpeg](https://ffmpeg.org/) and [Playwright](https://playwright.dev/). Works with any MCP client.
+
+[Features](#features) · [Quick Start](#quick-start) · [Examples](#usage-examples) · [Architecture](#architecture)
+
+</div>
+
+## Features
+
+| Tool | Operations | Description |
+|------|-----------|-------------|
+| `video_record` | cinema, scroll, multi-device | Record websites at 60fps with frame-by-frame capture |
+| `video_edit` | speed, crop, reverse, keyframe, pip | Edit clips with zoom/pan, PiP, slow-mo |
+| `video_color` | grade, effect, lut, chroma | Color grading, 22 LUT presets, green screen |
+| `video_audio` | extract, music, ducking, mix, voice | Audio extraction, mixing, 9 voice effects |
+| `video_text` | subtitles, caption, overlay, animate | Burn SRT, Whisper auto-caption, 15 text animations |
+| `video_compose` | concat, intro, social, beat-sync, templates | Join clips, social format conversion, beat sync |
+| `video_speech` | generate, voices, narrated | ElevenLabs/OpenAI TTS, full narrated videos |
+| `video_screenshot` | capture, detect | Element-aware screenshots, page feature detection |
+
+### Highlights
+
+- **60fps frame-by-frame capture** — Playwright screenshots every frame, ffmpeg encodes. Zero frame drops.
+- **Cinema easing curves** — 16 easing options including `cinematic` and `showcase` for buttery smooth scrolling.
+- **Smart screenshots** — Auto-detects 15+ UI elements (chat widgets, pricing sections, booking forms, etc.).
+- **Narrated videos** — Provide a URL + script, get a professional video with synchronized AI voiceover.
+- **22 LUT presets** — Film-grade color grading (teal-orange, noir, vintage, cyberpunk, etc.).
+- **Social format export** — One-click conversion to Instagram Reel, TikTok, YouTube Short, LinkedIn.
+- **Dual transport** — Stdio (default) or HTTP mode for persistent microservice deployment.
+
+## Prerequisites
+
+- **Node.js** >= 18
+- **ffmpeg** and **ffprobe** (validated on startup)
+- **Playwright** browsers (`npx playwright install chromium`)
+- Optional: `ELEVENLABS_API_KEY` for ElevenLabs TTS
+- Optional: `OPENAI_API_KEY` for Whisper captions and OpenAI TTS
+
+## Quick Start
+
+### With Claude Code (stdio)
+
+```json
+{
+  "mcpServers": {
+    "video": {
+      "command": "npx",
+      "args": ["-y", "mcp-video"]
+    }
+  }
+}
+```
+
+### With npx
+
+```bash
+npx mcp-video
+```
+
+### From source
+
+```bash
+git clone https://github.com/studiomeyer-io/mcp-video.git
+cd mcp-video
+npm install
+npx playwright install chromium
+npm run build
+npm start
+```
+
+### HTTP mode
+
+```bash
+# Start as HTTP microservice
+npx mcp-video --http --port=9847
+
+# Or via environment variables
+MCP_HTTP=1 MCP_PORT=9847 npx mcp-video
+```
+
+## Configuration
+
+| Environment Variable | Default | Description |
+|---------------------|---------|-------------|
+| `VIDEO_OUTPUT_DIR` | `./output` | Directory for generated files |
+| `ELEVENLABS_API_KEY` | — | ElevenLabs TTS API key |
+| `OPENAI_API_KEY` | — | OpenAI API key (Whisper + TTS) |
+| `MCP_HTTP` | `false` | Enable HTTP transport |
+| `MCP_PORT` | `9847` | HTTP port |
+| `MCP_HOST` | `127.0.0.1` | HTTP bind address |
+| `MCP_VIDEO_DEBUG` | `false` | Enable debug logging |
+
+## What You Can Build
+
+| Use Case | Tools Used | Output |
+|----------|-----------|--------|
+| **Product demo video** | `video_record` → `video_text` → `video_audio` | 60fps website recording + auto-captions + background music |
+| **Social media clips** | `video_record` → `video_compose` | Record once → export to Instagram Reel, TikTok, YouTube Short |
+| **Narrated explainer** | `video_speech` → `video_color` | AI voiceover + cinematic color grade |
+| **Before/after comparison** | `video_screenshot` → `video_edit` | Smart element screenshots + PiP composition |
+| **Automated QA** | `video_record` + `video_screenshot` | Record user flows + screenshot specific elements |
+
+## Usage Examples
+
+### Record a website
+
+```
+Use video_record with type "cinema" to record https://example.com
+with a smooth scroll and hover over the navbar.
+```
+
+### Create a narrated explainer video
+
+```
+Use video_speech with type "narrated" to create a narrated video of
+https://example.com with these segments:
+1. "Welcome to our homepage" — pause on hero section
+2. "Check out our features" — scroll to features
+3. "Get started today" — hover over CTA button
+```
+
+### Auto-caption a video
+
+```
+Use video_text with type "caption" to add auto-generated captions
+to /path/to/video.mp4
+```
+
+### Export for social media
+
+```
+Use video_compose with type "social-all" to convert
+/path/to/video.mp4 to all social media formats.
+```
+
+### Smart screenshot
+
+```
+Use video_screenshot with type "capture" to screenshot the chat widget
+and pricing section on https://example.com
+```
+
+## Architecture
+
+```
+src/
+  server.ts            Entry point, 8 consolidated MCP tools
+  lib/                 Logger, types, dual transport
+  handlers/            Tool handlers (video, editing, post-production, tts, screenshots)
+  schemas/             JSON Schema definitions for legacy tool format
+  tools/
+    engine/            Core engines
+      capture.ts       Frame-by-frame recording (Playwright → PNG → ffmpeg)
+      encoder.ts       ffmpeg encoding pipeline
+      scenes.ts        Scene execution (scroll, hover, click, type, wait)
+      cursor.ts        Visible cursor simulation
+      smart-screenshot.ts  Element-aware screenshot engine
+      tts.ts           ElevenLabs + OpenAI TTS with fallback
+      narrated-video.ts    Full narration pipeline
+      social-format.ts     Social media format conversion
+      concat.ts        Video concatenation with transitions
+      lut-presets.ts   22 cinema LUT presets
+      ...and more
+```
+
+## Development
+
+```bash
+npm run dev          # Start with tsx (hot reload)
+npm run typecheck    # Type check
+npm test             # Run tests
+npm run check        # Verify ffmpeg/ffprobe installed
+```
+
+## License
+
+MIT
+
+## Credits
+
+Built by [StudioMeyer](https://studiomeyer.io). Part of our open-source toolkit for AI-powered content creation.
+
+- [ai-shield](https://github.com/studiomeyer-io/ai-shield) — LLM security middleware for TypeScript
+- [agent-fleet](https://github.com/studiomeyer-io/agent-fleet) — Multi-agent orchestration for Claude Code
+- [darwin-agents](https://github.com/studiomeyer-io/darwin-agents) — Self-evolving agent framework

package/USAGE.md

@@ -0,0 +1,144 @@
+# mcp-video — Usage Guide
+
+**Version:** 1.0.0
+**Tools:** 8 (consolidated from 33)
+
+---
+
+## Quick Start
+
+```bash
+npm run build
+npm start          # stdio
+npm run dev        # Dev mode
+npm test           # Tests
+```
+
+---
+
+## Tools (8)
+
+### 1. `video_record` — Record website videos
+
+```json
+{ "type": "cinema", "url": "https://example.com", "fps": 60, "scenes": [...] }
+{ "type": "scroll", "url": "https://example.com", "duration": 12 }
+{ "type": "multi-device", "url": "https://example.com", "devices": ["desktop", "tablet", "mobile"] }
+```
+
+Types: `cinema` (full control), `scroll` (quick scroll-through), `multi-device` (all viewports)
+
+---
+
+### 2. `video_edit` — Edit video clips
+
+```json
+{ "type": "speed", "inputPath": "/path/video.mp4", "outputPath": "/path/out.mp4", "speed": 0.5 }
+{ "type": "crop", "inputPath": "...", "width": 1080, "height": 1080 }
+{ "type": "reverse", "inputPath": "..." }
+{ "type": "keyframe", "inputPath": "...", "keyframes": [...] }
+{ "type": "pip", "mainVideo": "...", "overlayVideo": "...", "position": "bottom-right" }
+```
+
+Types: `speed`, `crop`, `reverse`, `keyframe`, `pip`
+
+---
+
+### 3. `video_color` — Color grading & effects
+
+```json
+{ "type": "grade", "inputPath": "...", "brightness": 1.1, "contrast": 1.2 }
+{ "type": "effect", "inputPath": "...", "effect": "blur", "intensity": 0.5 }
+{ "type": "lut", "inputPath": "...", "preset": "film-noir", "intensity": 0.8 }
+{ "type": "chroma", "inputPath": "...", "background": "/path/bg.mp4" }
+```
+
+Types: `grade`, `effect` (blur/sharpen/vignette/grayscale/sepia/noise/glow), `lut` (22 presets), `chroma`
+
+---
+
+### 4. `video_audio` — Audio operations
+
+```json
+{ "type": "extract", "inputPath": "...", "format": "mp3" }
+{ "type": "music", "videoPath": "...", "musicPath": "...", "musicVolume": 0.25 }
+{ "type": "ducking", "inputPath": "...", "duckLevel": 0.3 }
+{ "type": "mix", "tracks": [...], "outputPath": "..." }
+{ "type": "voice", "inputPath": "...", "effect": "echo" }
+```
+
+Types: `extract`, `music`, `ducking`, `mix`, `voice` (echo/reverb/deep/chipmunk/robot/whisper/radio/megaphone/underwater)
+
+---
+
+### 5. `video_text` — Text & captions
+
+```json
+{ "type": "subtitles", "inputPath": "...", "subtitlePath": "/path/subs.srt" }
+{ "type": "caption", "inputPath": "...", "language": "de" }
+{ "type": "overlay", "inputPath": "...", "overlays": [...] }
+{ "type": "animate", "inputPath": "...", "text": "Hello", "animation": "typewriter" }
+```
+
+Types: `subtitles`, `caption` (Whisper AI), `overlay`, `animate` (15 styles)
+
+---
+
+### 6. `video_compose` — Compose & export
+
+```json
+{ "type": "concat", "clips": [...], "transition": "fade" }
+{ "type": "intro", "text": "My Brand", "duration": 3 }
+{ "type": "social", "inputPath": "...", "format": "instagram-reel" }
+{ "type": "social-all", "inputPath": "..." }
+{ "type": "beat-sync", "audioPath": "...", "clips": [...] }
+{ "type": "templates" }
+{ "type": "render", "templateId": "social-reel-1", "assets": {...} }
+```
+
+Types: `concat`, `intro`, `social`, `social-all`, `beat-sync`, `templates`, `render`
+
+---
+
+### 7. `video_speech` — TTS & narration
+
+```json
+{ "type": "generate", "text": "Hello world", "provider": "elevenlabs" }
+{ "type": "voices" }
+{ "type": "narrated", "url": "https://example.com", "segments": [...] }
+```
+
+Types: `generate` (ElevenLabs/OpenAI), `voices` (list available), `narrated` (full narrated video)
+
+---
+
+### 8. `video_screenshot` — Smart screenshots
+
+```json
+{ "type": "capture", "url": "https://example.com", "targets": ["hero", "pricing"] }
+{ "type": "detect", "url": "https://example.com" }
+```
+
+Types: `capture` (element-aware screenshots), `detect` (page feature analysis)
+
+---
+
+## Typical Workflows
+
+### Product demo video
+1. `video_record` (type: cinema) → Record website
+2. `video_edit` (type: keyframe) → Add zoom/pan
+3. `video_text` (type: caption) → Auto-caption
+4. `video_audio` (type: music) → Background music
+5. `video_compose` (type: social-all) → Export all formats
+
+### Quick social reel
+1. `video_record` (type: scroll) → Scroll recording
+2. `video_color` (type: lut) → Cinema color grade
+3. `video_compose` (type: beat-sync) → Sync to music
+4. `video_compose` (type: social) → Instagram reel format
+
+### Narrated walkthrough
+1. `video_speech` (type: narrated) → Full narrated video
+2. `video_text` (type: overlay) → Title cards
+3. `video_compose` (type: intro) → Add intro/outro

package/dist/handlers/capcut.d.ts

@@ -0,0 +1,6 @@
+/**
+ * CapCut-tier tool handlers — LUT Presets, Voice Effects, Chroma Key,
+ * Beat-Sync, Text Animations, Audio Mixer, Templates
+ */
+import { type ToolHandler } from '../lib/types.js';
+export declare const capcutHandlers: Record<string, ToolHandler>;