[yultyyev]

Targets the integration branch feat/distribution. Nothing releases until that branch merges into main.

What

clip doctor checks whether this machine can run the editor and prints the fix for anything missing. The MCP server exposes the same report as a doctor tool, so a Claude Desktop user can ask "is my setup OK?".

Check	Status when missing	What it reads
Node.js	fail	process.versions.node against engines.node (24+)
FFmpeg	fail	The binary runFfmpeg resolves (MAKEMYCLIP_FFMPEG_PATH, then bundled ffmpeg-static, then ffmpeg on PATH), run with -version and -filters
Text and captions	warn	drawtext in that FFmpeg's filter list
Stabilization	warn	vidstabdetect and vidstabtransform (clip stabilize)
Workspace	fail	Creates the workspace if needed, then writes and removes one temp file
Caption font	warn	The font file captions use for Latin text (fontFileFor), and whether MAKEMYCLIP_FALLBACK_FONT is the one picked
whisper.cpp (optional)	warn	MAKEMYCLIP_WHISPER_PATH or whisper-cli, run with --help
Whisper model (optional)	warn	MAKEMYCLIP_WHISPER_MODEL is set and is a file

• Each warn or fail has a fix with the platform's install command (brew, apt or winget) or the env var to set.
• The FFmpeg fix depends on why it failed:
  • a broken override;
  • a bundled binary whose install script never ran (--ignore-scripts, or a package manager that blocks build scripts);
  • a platform ffmpeg-static has no build for.
• clip doctor --json prints { ok, checks: [{ id, label, status, detail, fix? }] }. The CLI exits 1 when any check fails; warnings exit 0.
• Refactor: resolveFfmpeg() in src/ffmpeg/run.ts is now the one place that picks the binary, so doctor reports the FFmpeg the tools run. Resolution order and the ?? semantics are unchanged.
• No network calls: the whisper model URL appears only in fix text.
• Docs: README install section ("Check your setup"), SKILL.md install section (run doctor on a setup error), llms.txt, and the AGENTS.md list of handlers that don't return { path }.

Sample output on a machine with a broken override and a read-only workspace:

MakeMyClip Editor setup

  ✓ Node.js                   24.22.2
  ✗ FFmpeg                    /nope/ffmpeg (MAKEMYCLIP_FFMPEG_PATH) doesn't run: not found.
                              Fix: Point MAKEMYCLIP_FFMPEG_PATH at a working ffmpeg binary, or unset it to use the bundled one.
  - Text and captions         Not checked: FFmpeg did not run.
  - Stabilization             Not checked: FFmpeg did not run.
  ✗ Workspace                 Cannot write to /System/nope (MAKEMYCLIP_WORKSPACE): EPERM: operation not permitted, mkdir '/System/nope'.
                              Fix: Set MAKEMYCLIP_WORKSPACE to a folder you can write to; the editor keeps its timeline, imports and exports there.
  ✓ Caption font              /System/Library/Fonts/Supplemental/Arial.ttf
  ✓ whisper.cpp (optional)    whisper-cli (on PATH)
  ! Whisper model (optional)  MAKEMYCLIP_WHISPER_MODEL is not set. Optional: transcript cuts, retake removal and captions need it.
                              Fix: Download a model such as ggml-base.en.bin from https://huggingface.co/ggerganov/whisper.cpp and set MAKEMYCLIP_WHISPER_MODEL to its path.

Not ready: 2 problems to fix.
Set environment variables in your shell profile; for `clip mcp`, set them in the MCP client config for the server.

Not checked: the ass and subtitles filters. The plan named them, but nothing in the editor uses them: captions burn in with drawtext. Doctor checks the two optional filters the tools do use, drawtext and vidstab.

Why

Distribution slice 1 of 4. The finish line: a new user installs the editor in one step from Claude Desktop (.mcpb), the official MCP Registry or a Claude Code plugin marketplace, and clip doctor says what's missing and how to fix it. The .mcpb bundle (slice 2) runs the server under Claude Desktop's Node with no terminal, so the doctor tool is how those users find a missing FFmpeg filter or whisper model.

How to test

clip doctor
clip doctor --json
MAKEMYCLIP_FFMPEG_PATH=/nope MAKEMYCLIP_WORKSPACE=/System/nope clip doctor; echo $?   # 1

Over MCP, call the doctor tool with no arguments.

Checks

• pnpm test: 757 passed, 24 skipped.
• pnpm type-check is clean. pnpm lint has 0 errors (the 7 warnings are pre-existing, in untouched files). pnpm build passes.
• tests/doctor.test.ts (15) runs every check against stubbed deps (env, platform, Node version, run, isFile, the workspace probe, the font lookup):
  • each pass and failure path;
  • the three FFmpeg failure causes and their fixes;
  • a whisper-cli that exits non-zero after printing help (ok), and one that dies on a missing library (warn);
  • resolveFfmpeg order;
  • the text report's verdict lines.
• tests/mcp-server.test.ts: the tool list includes doctor, and a call through the MCP SDK client returns the eight checks in order.
• Manual: node dist/cli.js doctor on macOS (bundled FFmpeg 6.0, whisper-cli from Homebrew), with --json and with broken env vars (exit 1).
• Codex review (codex review --base feat/distribution, gpt-6.1-sol), 2 passes:
  • Pass 1, P2: a whisper-cli that can't load its libraries exits non-zero, and doctor counted any non-zero exit as healthy. Fixed in 6eb711d: a non-zero exit passes only when the output has a usage line, and the warning quotes the loader's stderr.
  • Pass 2: no findings.

[github-actions]

🎉 This PR is included in version 0.4.1 🎉

The release is available on:

• v0.4.1
• GitHub release

Your semantic-release bot 📦🚀