From a95d2035a396cc601287886964b1721b7a29d8fd Mon Sep 17 00:00:00 2001 From: Claude Date: Wed, 20 May 2026 21:26:13 +0000 Subject: [PATCH 1/2] docs: add VHS tape templates for recording mcpc demos Add docs/vhs/ with a flagship overview tape (mcpc-demo.tape) plus six focused per-feature tapes (quickstart, tools, shell, scripting, grep, proxy) and a README explaining how to render them with VHS. The flagship tape replays the Quickstart from the main README and produces the GIF embedded at docs/images/mcpc-demo.gif. All tapes share the same Set block for visual consistency. --- docs/README.md | 1 + docs/vhs/README.md | 80 +++++++++++++++++ docs/vhs/grep.tape | 56 ++++++++++++ docs/vhs/mcpc-demo.tape | 179 +++++++++++++++++++++++++++++++++++++++ docs/vhs/proxy.tape | 69 +++++++++++++++ docs/vhs/quickstart.tape | 59 +++++++++++++ docs/vhs/scripting.tape | 69 +++++++++++++++ docs/vhs/shell.tape | 61 +++++++++++++ docs/vhs/tools.tape | 66 +++++++++++++++ 9 files changed, 640 insertions(+) create mode 100644 docs/vhs/README.md create mode 100644 docs/vhs/grep.tape create mode 100644 docs/vhs/mcpc-demo.tape create mode 100644 docs/vhs/proxy.tape create mode 100644 docs/vhs/quickstart.tape create mode 100644 docs/vhs/scripting.tape create mode 100644 docs/vhs/shell.tape create mode 100644 docs/vhs/tools.tape diff --git a/docs/README.md b/docs/README.md index e859e8e..4fab8ba 100644 --- a/docs/README.md +++ b/docs/README.md @@ -5,6 +5,7 @@ Additional documentation for mcpc. ## Contents - [Claude Skill](./claude-skill/) - Claude Code skill for AI agents using mcpc +- [VHS demos](./vhs/) - VHS tape files for recording demo GIFs of mcpc - [CONTRIBUTING.md](../CONTRIBUTING.md) - Development, contributing, and publishing guide ## Main documentation diff --git a/docs/vhs/README.md b/docs/vhs/README.md new file mode 100644 index 0000000..951ae94 --- /dev/null +++ b/docs/vhs/README.md @@ -0,0 +1,80 @@ +# mcpc demo recordings (VHS) + +This folder contains [VHS](https://github.com/charmbracelet/vhs) tape files +that record terminal GIFs of mcpc. Each `.tape` is a small script that drives +a real shell session; VHS replays it, captures the output, and renders a GIF +(or MP4 / WebM) — no manual screen recording needed. + +## Prerequisites + +- **VHS** — `brew install vhs` (or see [installation guide](https://github.com/charmbracelet/vhs#installation)) +- **mcpc** — `npm install -g @apify/mcpc` +- **jq** — needed by `scripting.tape` +- **Auth (optional)** — `export APIFY_TOKEN=...` if you want the demos to hit + the authenticated Apify MCP server. Drop the `--header` line from the tape + to record an anonymous session against any public MCP server instead. + +## Tapes + +| File | Records | Notes | +| ---- | ------- | ----- | +| [`mcpc-demo.tape`](./mcpc-demo.tape) | Flagship overview: discover → connect → tools → grep → call → JSON → close | Source for `docs/images/mcpc-demo.gif` | +| [`quickstart.tape`](./quickstart.tape) | Minimal "connect, list, call" flow | Hero-sized GIF for README top | +| [`tools.tape`](./tools.tape) | `tools-list`, `tools-get`, `tools-call`, inline JSON, stdin | | +| [`shell.tape`](./shell.tape) | Interactive REPL (`mcpc @session shell`) | | +| [`scripting.tape`](./scripting.tape) | `--json` piped through `jq` and `xargs` (code mode) | | +| [`grep.tape`](./grep.tape) | Dynamic tool discovery with `mcpc grep` | | +| [`proxy.tape`](./proxy.tape) | MCP proxy / AI sandboxing | | + +## Recording + +Each tape outputs a GIF in this directory. Run from inside `docs/vhs/`: + +```bash +cd docs/vhs +vhs mcpc-demo.tape # → mcpc-demo.gif +vhs quickstart.tape # → quickstart.gif +# ... etc +``` + +To refresh the demo embedded in the main README: + +```bash +cd docs/vhs +vhs mcpc-demo.tape +cp mcpc-demo.gif ../images/mcpc-demo.gif +``` + +You can also render `.mp4` or `.webm` by editing the `Output` directive +inside the tape file (VHS infers the format from the extension). + +## Customising + +`mcpc-demo.tape` is the template — copy it, trim the sections you don't need, +and adjust: + +- `Output ` — destination GIF / MP4 / WebM +- `Set Width / Set Height` — frame size (current default: 1100×650) +- `Set FontSize` / `Set FontFamily` / `Set Theme` — appearance +- `Set TypingSpeed` / `Sleep` — pacing +- Server URL and `--header` — point at your own MCP server +- Tool / argument names — swap for tools your audience cares about + +The other tapes use the same Set block so they look consistent side by side. + +## Tips + +- Use `Hide` / `Show` around setup commands (clearing the screen, closing + stale sessions, exporting `PS1`) so they don't appear in the GIF. +- Add `Sleep` after each `Enter` so viewers have time to read the output + before the next command runs. +- `Set PlaybackSpeed 1.5` speeds up the final GIF without changing the + recording cadence — handy for long demos. +- Run the tape locally first (`vhs .tape`) and inspect the generated + GIF before committing. VHS does not run inside CI by default; the tapes + are version-controlled but the GIFs they produce are not (the main + `docs/images/mcpc-demo.gif` is checked in separately). + +See the [VHS documentation](https://github.com/charmbracelet/vhs#vhs-command-reference) +for the full list of directives (`Type`, `Sleep`, `Enter`, `Hide`, `Show`, +`Wait`, `Screenshot`, all `Set …` options, etc.). diff --git a/docs/vhs/grep.tape b/docs/vhs/grep.tape new file mode 100644 index 0000000..d3cde81 --- /dev/null +++ b/docs/vhs/grep.tape @@ -0,0 +1,56 @@ +# mcpc grep — dynamic tool discovery across sessions +# +# cd docs/vhs && vhs grep.tape + +Output grep.gif + +Require mcpc + +Set Shell "bash" +Set FontFamily "JetBrains Mono" +Set FontSize 16 +Set Width 1100 +Set Height 600 +Set Padding 20 +Set TypingSpeed 50ms +Set Theme "Catppuccin Mocha" +Set WindowBar Colorful +Set WindowBarSize 32 +Set BorderRadius 8 + +Hide +Type "export PS1='$ '" +Enter +Type "mcpc connect mcp.apify.com @apify --header \"Authorization: Bearer ${APIFY_TOKEN}\" >/dev/null 2>&1 || true" +Enter +Type "clear" +Enter +Show + +Type "# Find tools by keyword across every live session" +Sleep 600ms +Enter +Type 'mcpc grep "scraper"' +Sleep 400ms +Enter +Sleep 4s + +Type "clear" +Enter +Type "# Regex + case-sensitive, limited results" +Sleep 500ms +Enter +Type 'mcpc grep "search|find" -E -m 5' +Sleep 400ms +Enter +Sleep 4s + +Type "clear" +Enter +Type "# Search resources and prompts too" +Sleep 500ms +Enter +Type 'mcpc grep "config" --resources --prompts' +Sleep 400ms +Enter +Sleep 4s diff --git a/docs/vhs/mcpc-demo.tape b/docs/vhs/mcpc-demo.tape new file mode 100644 index 0000000..b66d716 --- /dev/null +++ b/docs/vhs/mcpc-demo.tape @@ -0,0 +1,179 @@ +# mcpc demo — flagship overview +# +# Generate the GIF with VHS (https://github.com/charmbracelet/vhs): +# +# cd docs/vhs && vhs mcpc-demo.tape +# +# This produces mcpc-demo.gif in the current directory. To update the demo +# embedded in the main README, copy it to docs/images/mcpc-demo.gif. +# +# Prerequisites: +# - VHS: brew install vhs (or see https://github.com/charmbracelet/vhs#installation) +# - mcpc: npm install -g @apify/mcpc +# - jq: brew install jq (for the scripting section) +# - Auth: export APIFY_TOKEN=... (or remove the --header line to use anonymous access) +# +# This is a template — adapt the commands below for your own server, +# tools, and audience. Use the focused tapes in this folder +# (quickstart.tape, tools.tape, shell.tape, scripting.tape, grep.tape, +# proxy.tape) as a starting point for shorter, single-feature demos. + +Output mcpc-demo.gif + +Require mcpc + +# Look & feel +Set Shell "bash" +Set FontFamily "JetBrains Mono" +Set FontSize 16 +Set Width 1100 +Set Height 650 +Set Padding 20 +Set TypingSpeed 50ms +Set PlaybackSpeed 1.0 +Set Theme "Catppuccin Mocha" +Set WindowBar Colorful +Set WindowBarSize 32 +Set BorderRadius 8 +Set CursorBlink true + +# Hidden setup: clean prompt, no scrollback, fresh state +Hide +Type "export PS1='$ '" +Enter +Type "mcpc @apify close 2>/dev/null; mcpc @fs close 2>/dev/null; true" +Enter +Type "clear" +Enter +Show + +# 1. Discover mcpc +Type "# mcpc — a universal MCP CLI client" +Sleep 800ms +Enter +Sleep 600ms + +Type "mcpc --help | head -25" +Sleep 400ms +Enter +Sleep 4s + +Type "clear" +Enter +Sleep 300ms + +# 2. List sessions and OAuth profiles +Type "# No sessions or profiles yet" +Sleep 600ms +Enter +Sleep 400ms + +Type "mcpc" +Sleep 400ms +Enter +Sleep 3s + +# 3. Connect to a remote MCP server +Type "# Connect to Apify's MCP server as session @apify" +Sleep 600ms +Enter +Sleep 400ms + +Type 'mcpc connect mcp.apify.com @apify --header "Authorization: Bearer ${APIFY_TOKEN}"' +Sleep 400ms +Enter +Sleep 3s + +# 4. Server info, capabilities, instructions +Type "# Show server capabilities and instructions" +Sleep 600ms +Enter +Sleep 400ms + +Type "mcpc @apify" +Sleep 400ms +Enter +Sleep 4s + +Type "clear" +Enter +Sleep 300ms + +# 5. List available tools +Type "# List available tools" +Sleep 600ms +Enter +Sleep 400ms + +Type "mcpc @apify tools-list | head -15" +Sleep 400ms +Enter +Sleep 4s + +# 6. Dynamic tool discovery +Type "clear" +Enter +Type "# Find tools by keyword — useful for AI agents" +Sleep 600ms +Enter +Sleep 400ms + +Type 'mcpc @apify grep "scraper"' +Sleep 400ms +Enter +Sleep 4s + +# 7. Inspect a tool's schema +Type "clear" +Enter +Type "# Inspect a tool's input schema" +Sleep 600ms +Enter +Sleep 400ms + +Type "mcpc @apify tools-get search-actors" +Sleep 400ms +Enter +Sleep 5s + +# 8. Call a tool +Type "clear" +Enter +Type "# Call a tool with key:=value arguments" +Sleep 600ms +Enter +Sleep 400ms + +Type 'mcpc @apify tools-call search-actors keywords:="web scraper" limit:=3' +Sleep 400ms +Enter +Sleep 5s + +# 9. JSON mode + jq for scripting (code mode) +Type "clear" +Enter +Type "# JSON mode composes with jq for scripts and agents" +Sleep 600ms +Enter +Sleep 400ms + +Type "mcpc --json @apify tools-list | jq -r '.[].name' | head -5" +Sleep 400ms +Enter +Sleep 4s + +# 10. Close the session +Type "# Close the session when done" +Sleep 600ms +Enter +Sleep 400ms + +Type "mcpc @apify close" +Sleep 400ms +Enter +Sleep 2s + +Type "# Learn more: https://github.com/apify/mcpc" +Sleep 2s +Enter +Sleep 1500ms diff --git a/docs/vhs/proxy.tape b/docs/vhs/proxy.tape new file mode 100644 index 0000000..33485ef --- /dev/null +++ b/docs/vhs/proxy.tape @@ -0,0 +1,69 @@ +# mcpc proxy — AI sandbox: expose a credentialed session without leaking tokens +# +# cd docs/vhs && vhs proxy.tape + +Output proxy.gif + +Require mcpc + +Set Shell "bash" +Set FontFamily "JetBrains Mono" +Set FontSize 16 +Set Width 1200 +Set Height 700 +Set Padding 20 +Set TypingSpeed 50ms +Set Theme "Catppuccin Mocha" +Set WindowBar Colorful +Set WindowBarSize 32 +Set BorderRadius 8 + +Hide +Type "export PS1='$ '" +Enter +Type "mcpc @relay close 2>/dev/null; mcpc @sandbox close 2>/dev/null; true" +Enter +Type "clear" +Enter +Show + +Type "# Human authenticates once and exposes a localhost MCP proxy" +Sleep 600ms +Enter +Type 'mcpc connect mcp.apify.com @relay --header "Authorization: Bearer ${APIFY_TOKEN}" --proxy 8080' +Sleep 400ms +Enter +Sleep 4s + +Type "# The proxy forwards MCP traffic but hides the upstream token" +Sleep 600ms +Enter +Type "mcpc" +Sleep 400ms +Enter +Sleep 4s + +Type "clear" +Enter +Type "# An AI agent (or another tool) connects to the proxy as a normal MCP server" +Sleep 600ms +Enter +Type "mcpc connect localhost:8080 @sandbox" +Sleep 400ms +Enter +Sleep 3s + +Type "mcpc @sandbox tools-list | head -8" +Sleep 400ms +Enter +Sleep 5s + +Type "clear" +Enter +Type "# Tear down both sides" +Sleep 500ms +Enter +Type "mcpc @sandbox close && mcpc @relay close" +Sleep 400ms +Enter +Sleep 2s diff --git a/docs/vhs/quickstart.tape b/docs/vhs/quickstart.tape new file mode 100644 index 0000000..7696d81 --- /dev/null +++ b/docs/vhs/quickstart.tape @@ -0,0 +1,59 @@ +# mcpc quickstart — first-time user flow +# +# A minimal demo of "install → connect → list tools → call tool". +# Best for the README hero / landing-page GIF. +# +# cd docs/vhs && vhs quickstart.tape + +Output quickstart.gif + +Require mcpc + +Set Shell "bash" +Set FontFamily "JetBrains Mono" +Set FontSize 16 +Set Width 1100 +Set Height 600 +Set Padding 20 +Set TypingSpeed 50ms +Set Theme "Catppuccin Mocha" +Set WindowBar Colorful +Set WindowBarSize 32 +Set BorderRadius 8 + +Hide +Type "export PS1='$ '" +Enter +Type "mcpc @apify close 2>/dev/null; true" +Enter +Type "clear" +Enter +Show + +Type "# Connect to any MCP server, get a stateful session" +Sleep 600ms +Enter +Type 'mcpc connect mcp.apify.com @apify --header "Authorization: Bearer ${APIFY_TOKEN}"' +Sleep 400ms +Enter +Sleep 3s + +Type "# List the tools the server exposes" +Sleep 500ms +Enter +Type "mcpc @apify tools-list | head -10" +Sleep 400ms +Enter +Sleep 4s + +Type "# Call one of them with typed key:=value arguments" +Sleep 500ms +Enter +Type 'mcpc @apify tools-call search-actors keywords:="web scraper" limit:=3' +Sleep 400ms +Enter +Sleep 5s + +Type "mcpc @apify close" +Enter +Sleep 2s diff --git a/docs/vhs/scripting.tape b/docs/vhs/scripting.tape new file mode 100644 index 0000000..87a16c6 --- /dev/null +++ b/docs/vhs/scripting.tape @@ -0,0 +1,69 @@ +# mcpc scripting — JSON mode + jq + pipelines (code mode) +# +# cd docs/vhs && vhs scripting.tape + +Output scripting.gif + +Require mcpc +Require jq + +Set Shell "bash" +Set FontFamily "JetBrains Mono" +Set FontSize 16 +Set Width 1200 +Set Height 700 +Set Padding 20 +Set TypingSpeed 50ms +Set Theme "Catppuccin Mocha" +Set WindowBar Colorful +Set WindowBarSize 32 +Set BorderRadius 8 + +Hide +Type "export PS1='$ '" +Enter +Type "mcpc connect mcp.apify.com @apify --header \"Authorization: Bearer ${APIFY_TOKEN}\" >/dev/null 2>&1 || true" +Enter +Type "clear" +Enter +Show + +Type "# --json emits MCP-spec JSON to stdout, errors to stderr" +Sleep 600ms +Enter +Type "mcpc --json @apify tools-list | jq -r '.[].name' | head -5" +Sleep 400ms +Enter +Sleep 4s + +Type "clear" +Enter +Type "# Chain tools across calls with jq + xargs" +Sleep 500ms +Enter +Type "mcpc --json @apify tools-call search-actors keywords:=\"scraper\" limit:=1 \\" +Sleep 200ms +Enter +Type ' | jq -r ".content[0].text | fromjson | .[0].name"' +Sleep 400ms +Enter +Sleep 5s + +Type "clear" +Enter +Type "# Snapshot every tool's schema for CI / contract tests" +Sleep 500ms +Enter +Type "for tool in $(mcpc --json @apify tools-list | jq -r '.[].name' | head -3); do" +Sleep 200ms +Enter +Type ' mcpc --json @apify tools-get "$tool" > "/tmp/$tool.json"' +Sleep 200ms +Enter +Type " echo \"saved /tmp/$tool.json\"" +Sleep 200ms +Enter +Type "done" +Sleep 400ms +Enter +Sleep 6s diff --git a/docs/vhs/shell.tape b/docs/vhs/shell.tape new file mode 100644 index 0000000..837122b --- /dev/null +++ b/docs/vhs/shell.tape @@ -0,0 +1,61 @@ +# mcpc shell — interactive REPL +# +# cd docs/vhs && vhs shell.tape + +Output shell.gif + +Require mcpc + +Set Shell "bash" +Set FontFamily "JetBrains Mono" +Set FontSize 16 +Set Width 1100 +Set Height 650 +Set Padding 20 +Set TypingSpeed 60ms +Set Theme "Catppuccin Mocha" +Set WindowBar Colorful +Set WindowBarSize 32 +Set BorderRadius 8 + +Hide +Type "export PS1='$ '" +Enter +Type "mcpc connect mcp.apify.com @apify --header \"Authorization: Bearer ${APIFY_TOKEN}\" >/dev/null 2>&1 || true" +Enter +Type "clear" +Enter +Show + +Type "# Drop into an interactive shell against the session" +Sleep 600ms +Enter +Type "mcpc @apify shell" +Sleep 400ms +Enter +Sleep 2500ms + +Type "help" +Sleep 400ms +Enter +Sleep 3s + +Type "tools-list" +Sleep 400ms +Enter +Sleep 4s + +Type "grep scraper" +Sleep 400ms +Enter +Sleep 3s + +Type 'tools-call search-actors keywords:="crawler" limit:=2' +Sleep 400ms +Enter +Sleep 5s + +Type "exit" +Sleep 400ms +Enter +Sleep 1500ms diff --git a/docs/vhs/tools.tape b/docs/vhs/tools.tape new file mode 100644 index 0000000..532da89 --- /dev/null +++ b/docs/vhs/tools.tape @@ -0,0 +1,66 @@ +# mcpc tools — list / get / call +# +# cd docs/vhs && vhs tools.tape + +Output tools.gif + +Require mcpc + +Set Shell "bash" +Set FontFamily "JetBrains Mono" +Set FontSize 16 +Set Width 1100 +Set Height 650 +Set Padding 20 +Set TypingSpeed 50ms +Set Theme "Catppuccin Mocha" +Set WindowBar Colorful +Set WindowBarSize 32 +Set BorderRadius 8 + +Hide +Type "export PS1='$ '" +Enter +Type "mcpc connect mcp.apify.com @apify --header \"Authorization: Bearer ${APIFY_TOKEN}\" >/dev/null 2>&1 || true" +Enter +Type "clear" +Enter +Show + +Type "# Browse the tools exposed by the server" +Sleep 600ms +Enter +Type "mcpc @apify tools-list | head -15" +Sleep 400ms +Enter +Sleep 4s + +Type "clear" +Enter +Type "# Inspect a single tool's input schema and description" +Sleep 500ms +Enter +Type "mcpc @apify tools-get search-actors" +Sleep 400ms +Enter +Sleep 5s + +Type "clear" +Enter +Type "# Call with auto-parsed key:=value arguments" +Sleep 500ms +Enter +Type 'mcpc @apify tools-call search-actors keywords:="web scraper" limit:=3' +Sleep 400ms +Enter +Sleep 5s + +Type "clear" +Enter +Type "# Pass complex JSON inline or from stdin" +Sleep 500ms +Enter +Type 'echo '"'"'{"keywords":"crawler","limit":2}'"'"' | mcpc @apify tools-call search-actors' +Sleep 400ms +Enter +Sleep 5s From e799270a4076bfe60681eff20c17a6333935bd16 Mon Sep 17 00:00:00 2001 From: Claude Date: Wed, 20 May 2026 22:29:56 +0000 Subject: [PATCH 2/2] docs: regenerate auto-generated mcpc --help block in README The v0.3.0 release commit (cfd3add) blanked out the code block in README.md but did not regenerate it, causing test/unit/cli/readme-help.test.ts to fail on every branch built from that commit (Node.js 20/22/24 CI jobs). Repopulate the block from the current `mcpc --help` output, restoring parity with the test's expectation. Equivalent to running `pnpm run build:readme` (sans TOC + link check, which require globally installed tooling). Refs #242 --- README.md | 48 ++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 48 insertions(+) diff --git a/README.md b/README.md index 0fcb893..843eb40 100644 --- a/README.md +++ b/README.md @@ -127,6 +127,54 @@ mcpc @fs tools-list ``` +Usage: mcpc [<@session>] [] [options] + +Universal command-line client for the Model Context Protocol (MCP). + +Commands: + connect [@session] Connect to an MCP server and start a new named @session + close <@session> Close a session + restart <@session> Restart a session (losing all state) + shell <@session> Open interactive shell for a session + login Interactively login to a server using OAuth and save profile + logout Delete an OAuth profile for a server + clean [resources...] Clean up mcpc data (sessions, profiles, logs, all) + grep Search tools and instructions across all active sessions + x402 [subcommand] [args...] Configure an x402 payment wallet (EXPERIMENTAL) + help [command] [subcommand] Show help for a specific command + +Options: + --json Output in JSON format for scripting + --verbose Enable debug logging + --profile OAuth profile for the server ("default" if not provided) + --timeout Request timeout in seconds (default: 300) + --max-chars Truncate output to n characters (ignored in --json mode) + --insecure Skip TLS certificate verification (for self-signed certs) + -v, --version Output the version number + -h, --help Display help + +MCP session commands (after connecting): + <@session> Show MCP server info, capabilities, and tools overview + <@session> grep Search tools and instructions + <@session> tools-list List all server tools + <@session> tools-get Get tool details and schema + <@session> tools-call [arg:=val ... | | prompts-list + <@session> prompts-get [arg:=val ... | | resources-list + <@session> resources-read + <@session> resources-subscribe + <@session> resources-unsubscribe + <@session> resources-templates-list + <@session> tasks-list + <@session> tasks-get + <@session> tasks-result + <@session> tasks-cancel + <@session> logging-set-level + <@session> ping + +Run "mcpc" without arguments to show active sessions and OAuth profiles. +Run "mcpc --json" to get the same data as `{ sessions: [...], profiles: [...] }`. ``` ### General actions