/record-demo

name: record-demo
description: Record or regenerate the mcpc demo GIFs (the README hero docs/images/mcpc-demo.gif and the focused tapes in docs/vhs/) with VHS. Use whenever asked to create, refresh, restyle, shorten, or fix a terminal demo/animation/GIF of mcpc. The tapes drive real mcpc commands; for the authenticated step this skill ALWAYS prompts for a short-lived, low-permission TEST token first (never production). Captures the VHS + mcpc gotchas learned the hard way — read it fully before editing a tape.
allowed-tools: Bash, Read, Write, Edit, AskUserQuestion

record-demo: VHS demo GIFs for mcpc

The tapes in `docs/vhs/*.tape` are [VHS](https://github.com/charmbracelet/vhs) scripts that drive a **real** shell session — VHS types each command, runs it against a live MCP server, captures the terminal, and renders a GIF. The README hero is `docs/images/mcpc-demo.gif`, built from `docs/vhs/mcpc-demo.tape`.

This file is the accumulated know-how. **Read all of it before touching a tape** — most rules below were discovered by hitting the wall, and skipping them wastes whole render cycles (~1–2 min each).

The hero flow (`mcpc-demo.tape`)

A basic-use story across both transports:

1. `mcpc` — empty state (no sessions, no profiles) 2. `mcpc connect mcp.json:filesystem` — local **stdio** server (auto-names `@filesystem`) 3. `mcpc` — session list (now shows the live session) 4. `mcpc @filesystem tools-list` 5. `mcpc @filesystem tools-list --json` — JSON output, syntax-highlighted, no jq 6. `mcpc connect mcp.apify.com -H "Authorization: Bearer $APIFY_TOKEN"` — remote **HTTP** server (auto-names `@apify`) 7. `mcpc @apify tools-list` 8. `mcpc @apify tools-get search-actors` — inspect one tool's input schema 9. `mcpc @apify tools-call search-actors keywords:="web scraper" limit:=3` 10. `mcpc @apify close`

Ten commands run ~45s; there is no hard 30s cap for this flow.

Style conventions (the current standard — match these)

• **No `# comments`** in the visible script. The commands are self-descriptive.
• **No `| head`, no `2>/dev/null`** on visible commands. Show real output even if

long — it scrolls naturally. (`connect` ≈ 86 lines incl. an "Available commands" list, `tools-call search-actors` ≈ 56, filesystem `tools-list --json` ≈ 300.)

• **Continuous session — never `clear` between steps.** Put a single blank-line

`Enter` before each command (after the first) so it's separated from the previous output, like a real terminal session.

• **Colored prompt + bold-white typed commands.** In the hidden setup block:

  Type 'export PS1="\[\e[1;38;2;25;230;77m\]$\[\e[0m\] \[\e[1;97m\]"'
  Enter
  Type "trap 'tput sgr0' DEBUG"
  Enter

• `PS1` is a bold bright-green `$`, then ends with `\[\e[1;97m\]` so the typed

input renders bold bright-white.

• The `DEBUG` trap runs `tput sgr0` before every command so the bold-white

input does **not** bleed into command output.

• **Empty state** needs a clean home — hidden: `Type 'export MCPC_HOME_DIR="$(mktemp -d)"'`

so `mcpc` shows "No active MCP sessions / No OAuth profiles".

• **Color is automatic for non-piped commands** — mcpc detects the TTY and emits

color (256-color, plenty vivid). You only need `export FORCE_COLOR=3` (+ `COLORTERM=truecolor` for exact hex) when a command is **piped** (mcpc turns color off when stdout isn't a TTY). The current tapes avoid pipes, so they don't need it. (The CLI palette lives in `src/cli/output.ts`, `RAINBOW_SATURATION`, bumped to 78% for vividness — that's where the demo colors come from.)

VHS gotchas (these will bite you)

• **ASCII prompt symbols only.** Multibyte glyphs (`❯`, `»`, `▶`) break bash prompt

rendering under VHS and show up as garbage like `92m]`. Use `$` (or `>`), styled with color + bold.

• **`Type` quoting:** use **single quotes** around any command containing double

quotes. A `\"` inside a double-quoted `Type` breaks VHS's parser. e.g. `Type 'mcpc @apify tools-call search-actors keywords:="web scraper" limit:=3'` and `Type 'export PS1="\[\e[…m\]$\[\e[0m\] "'`.

• **Output/Screenshot paths:** must not start with a digit (`Output 1-foo.gif`

fails to parse) and must not be long absolute paths (the parser chokes). Use short, letter-leading, **relative** names and run `vhs` from `docs/vhs/`.

• **`Screenshot` is unreliable** (frequently exits 2 even though the GIF rendered

fine). Don't depend on it — pull frames from the finished GIF instead: `ffmpeg -y -ss <seconds> -i x.gif -vframes 1 frame.png`, then Read the PNG.

• **Renders are slow** (~1–2 min each: real-time timeline + Chromium + ffmpeg

encode). Render tapes **one at a time** — a `for` loop over several blows the 5-minute command timeout. Extracted frames often land mid-typing; sample a few timestamps around when output should be on screen.

• **Hidden connects leak into the recording if bash falls behind.** When a tape

connects in the hidden setup (so the feature commands run against a ready session, e.g. tools/scripting/grep), a slow connect lets VHS type ahead; bash then echoes the buffered commands and runs the `clear` *after* `Show`, so the setup spills into frame. Pattern that works: type the connect(s), then **one generous `Sleep` (7–8s)** so they finish, then `clear`, then **another `Sleep` (~1.5s) before `Show`**. (Tapes that connect *visibly* as their first command don't need this — their hidden setup is just fast exports + `clear`.)

Stdio servers in a headless / proxied box

• **`npx`-launched stdio servers are too slow here.** `npx -y <pkg>`'s registry

round-trip exceeds mcpc's 60s connect handshake, so `connect` times out (`MCP error -32001`). Fixes: pre-install the server (`npm i -g <pkg>`) and put the **direct binary** in `mcp.json` (e.g. `mcp-server-filesystem`, starts in ~0.3s — also a cleaner session header), or use `npx --prefer-offline -y <pkg>` once the npm cache is warm (~5s; plain `npx -y` still does the slow registry chec