capcut-mcp-server-extended: Instructions file for Claude Code

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

capcut-mcp-server-extended is a Model Context Protocol (MCP) server that bridges AI assistants (Claude, etc.) with CapCut Pro video editing via a VectCutAPI backend. It is a fork of atx-guy/capcut-mcp-server extended toward a professional video automation tool, with a focus on talking head / reels content: vertical 1080×1920 videos, auto-subtitles, animated text, and composable presets that collapse multi-step workflows into a single tool call.

The end goal is to let an AI assistant produce a fully-edited short video by issuing a handful of MCP tool calls — no manual CapCut interaction required.

---

Commands

# Build (compile TypeScript → dist/, make dist/index.js executable)
npm run build

# Development (watch mode, recompiles on change)
npm run dev

# Run the compiled server
npm start

No test scripts are configured. The server starts and communicates over stdio (default) or HTTP. Always run npm run build after every code change and confirm zero errors before committing.

---

Architecture

Transport modes (set via TRANSPORT env var):

• stdio (default) — for Claude Desktop / local MCP clients
• http — listens on PORT (default 3000)

Key env vars: CAPCUT_API_URL (default http://localhost:9001), PORT, TRANSPORT

VectCutAPI backend: runs at http://localhost:9001. Useful endpoints:

• GET /get_font_types — returns the full list of supported font names
• POST /create_draft, /add_video, /add_text, /add_keyframe, /save_draft, etc.

Data flow

MCP Client
  → src/tools/index.ts          (tool registration + Zod validation)
  → src/tools/presets.ts        (high-level composite tools — Phase 3+)
  → src/services/api-client.ts  (axios singleton, 60 s timeout)
  → VectCutAPI backend          (http://localhost:9001)

Source layout

File / Dir	Role
src/index.ts	Entry point; stdio/HTTP transport setup — do not modify
src/tools/index.ts	All 13 MCP tool definitions; formatResponse / handleError helpers
src/tools/presets.ts	High-level composite tools (Phase 3+)
src/schemas/index.ts	Zod schemas for every base tool input
src/services/api-client.ts	Singleton apiClient; maps tool calls → POST endpoints — do not modify
src/types.ts	TypeScript interfaces (DraftConfig, VideoTrack, ResponseFormat, …)
src/constants.ts	API_BASE_URL, defaults, supported formats, effects, transitions
src/presets/typography.ts	[Phase 1 ✅] Three named text styles; font = Poppins_Bold
src/presets/animations.ts	[Phase 2 ✅] Keyframe animation sequences (popInUpper)
src/utils/validators.ts	[Phase 5] Path validation, Windows↔Unix helpers
utils_py/transcribe_audio.py	Whisper word-level transcription; outputs JSON word list
utils_py/inspect_draft.py	Reads draft_content.json; extracts audio path, duration, fps
utils_py/validate_project.py	Checks that all media files referenced in a draft exist