record-demo

record-demo: VHS demo GIFs for mcpc

The tapes in docs/vhs/*.tape are 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.)