Skip to content

Open the MCP overview with its worked example, and record the split flow for Ruby and Julia - #262

Merged
tony merged 8 commits into
mainfrom
fix/mcp-overview-replay
Nov 7, 2026
Merged

tony merged 8 commits into
mainfrom
fix/mcp-overview-replay

Conversation

@tony

@tony tony commented Nov 7, 2026 •

Copy link
Copy Markdown
Contributor

The MCP overview pages hid their worked example. The replay sat under "Worked example" after Install, Start here and the whole tool grid, so a reader of https://libtmux.org/en/go/latest/mcp/ or https://libtmux.org/en/ruby/latest/mcp/ never reached it (on Go it starts about 5,100px down a 6,200px page), while the landing page's MCP tab shows it first. Ruby's replay also had almost nothing in it: a prompt and two read-only calls, so tmux never changed.

Placement

Each MCP overview now reads: intro, worked example, Install, Start here, tool grid. The table of contents follows the same order. McpShowcase takes a part prop (example or tools) and DocPage renders the example after the intro and the tools at the end. The landing page's "All tools" link now targets the tools heading instead of the first heading the showcase lists, which is now the example.

Ruby's example

Ruby runs the shared prompt ("Create a tmux session called checks, split its window into two panes, run pytest -q in one and show checks.log in the other, ... then remove the session") with its own tools, in nine calls:

  1. tmux_capabilities
  2. tmux_create (session checks)
  3. tmux_create (pane, split %1)
  4. tmux_snapshot (window layout)
  5. tmux_send + 6. tmux_wait (pytest -q in %1, wait for 2 passed)
  6. tmux_send + 8. tmux_wait (cat checks.log in %2, wait for checks finished)
  7. tmux_close (session $1)

Every target carries the server's generation, which an earlier result returned; the file shows the stand-in 3f9a1c, and the recorder checks that the server refuses it as stale_target, as it does for Julia. tmux_run is not used because it needs an enrolled zsh editor. The recording is at libtmux-ruby 0bf78344f, the revision the snapshot already pins. To make it record, the recorder now runs Ruby's server in the project directory (found through BUNDLE_GEMFILE), puts the sandbox's pytest on the borrowed tmux server's PATH, and raises the server's request deadline to 30s. The state check accepts tmux_close as a removal and sh as a pane command.

Julia's example

Julia's example was also two read-only calls. LibTmuxMCP has no split tool, so the example splits from inside the pane with tmux itself, then runs the rest of the shared prompt with Julia's tools: create_session, send_keys (tmux split-window -h sh), list_panes scoped to the session, send_keys_and_wait for pytest -q and for cat checks.log, and teardown_session. Each id and generation comes from an earlier result. The recording is at libtmux-julia c19e4a164, the revision the snapshot pins; the recorder starts the server with --allow-create and every tool the snapshot lists. This PR supersedes #248, which did the recorder groundwork (generation handling, borrowed server) that is already on main.

Every port

Each port with an MCP page runs the shared split prompt, is recorded (not "Requests only"), shows a window with two panes at some step and the session gone at the end, and renders its example first on /mcp/ and on the landing tab. A new test checks the first four for all ten ports. Each recording is at the revision its snapshot pins.

Port Steps Recording revision
py 6 800aebd26
ruby 9 0bf78344f
julia 6 c19e4a164
ts 6 073b9d7de
rs 7 6942c1e60
go 7 f59af95c2
java 7 fe25ff5ed
csharp 6 486830df1
cxx 7 166ce2c74
swift 7 3fd9dfe3d

A page built from a newer port head shows the "documents a different revision" note while the schemas still match; no recording was redone for that.

Players and workspace overviews

  • The JSON a Core player call returned is now set at the size of the program beside it. It took the landing page's general code size before, 14.6px beside a 12px program at 896px. CorePlayer copies the shown program's computed size into --core-program-size on each step, view change and resize.
  • The MCP replay marks the call the tmux view shows with a 3px accent edge and the Core player's 14% accent tint (24% when pinned). The shown call and a hovered one were drawn alike before, in a background 1.23:1 against the dark panel and 1.08:1 against the light one.
  • A workspace overview whose port has one example (go, ruby, julia, csharp) now opens with that example, before Install, as the landing tab does; ports with several examples keep the preset picker first. The table of contents follows.

What ran

Locally, through heavy.sh:

  • scripts/gen-mcp-transcript.mjs --port ruby and --port julia: recorded 9 and 6 steps.

  • vitest: mcp-showcase, mcp-replay, mcp-tmux-state, mcp-transcript-checks, mcp-session, product-copy, port-landing-page, workspace-showcase: all pass.

  • oxlint (site and scripts): 0 errors. astro check: 0 errors.

  • vitest core-player (the returned value follows the program's size in each view; fails without the script change) and workspace-showcase: pass.

  • The full test workflow, including the assembled-site suites that only run in CI.

  • Look at a deployed or preview /mcp/ page for Go and Ruby and confirm the replay is the first thing under the intro.

  • Go dev server: the returned JSON matches the program at 12px and 13.2px, the shown MCP call stands out in light and dark, and /workspace/ opens with its example, listed once.

@tony tony changed the title Open the MCP overview with its worked example, and record a real one for Ruby Open the MCP overview with its worked example, and record the split flow for Ruby and Julia Nov 7, 2026
tony added 8 commits November 7, 2026 12:44
why: The replay sat under "Worked example" at the bottom of each
port's MCP overview, after Install, Start here and the whole tool grid.
On the Go page it starts about 5,100px down a 6,200px page, so readers
never saw it, while the landing page's MCP tab shows it first.

what:
- Render the example right after the page intro and before Install;
  the tool grid still closes the page.
- Give McpShowcase a part prop ("example" or "tools"); without it both
  render, example first.
- Split showcaseHeadings into exampleHeadings and toolHeadings, so the
  table of contents reads example, Install, prose, tools.
- Point the landing page's "All tools" link at the tools heading, no
  longer the first heading the showcase lists.
- Test the order of the components and of the headings in DocPage.
why: Ruby's example listed the panes with two read-only calls, so its
tmux preview never changed and the replay showed three steps next to
the other ports' six or seven. Ruby's targets carry the server's
generation, which the other split examples never needed, and its close
result returns ids tmux no longer has.

what:
- Run the shared split prompt with Ruby's own tools: tmux_capabilities,
  tmux_create for the session and the split pane, tmux_snapshot for the
  window layout, tmux_send and tmux_wait for each command, tmux_close
  for the session. tmux_run needs an enrolled zsh editor, so it is not
  used.
- Send each call the generation an earlier result returned, as Julia's
  recording does, and keep 3f9a1c in the file.
- Record at libtmux-ruby 0bf78344f. The server now runs in the project
  directory, found through BUNDLE_GEMFILE, so panes it creates start
  next to test_example.py and checks.log. The borrowed tmux server
  gets the sandbox's pytest on its PATH, and the server's request
  deadline is 30s.
- Accept tmux_close as a removal when checking a result's ids, and
  `sh` as a pane command alongside `cat`.
- Name a result entry's kind in the test's id lookup so a pane id in
  Ruby's created list is found; add the replay frames Ruby now draws.
why: Julia's example read the panes with two read-only calls, so its
tmux preview never changed. LibTmuxMCP has no split tool, which is why
the example stopped at reading; a pane can still be split from inside
the pane with tmux itself.

what:
- Run the shared split prompt with Julia's tools: create_session,
  send_keys (tmux split-window), list_panes scoped to the session,
  send_keys_and_wait for pytest and for cat checks.log, and
  teardown_session. Each id and generation comes from an earlier
  result.
- Record at libtmux-julia c19e4a164, the revision the snapshot pins.
  The recorder starts the server with --allow-create and every tool the
  snapshot lists, and accepts `sh` panes beside the borrowed `cat` one.
- Treat teardown_session as a removal when checking a result's ids.
- Rewrite the Julia tests for the new calls; the generation is now
  listed by create_session.
… flow

why: Ruby and Julia shipped read-only examples for weeks because no
test asked for more than a recording that held.

what:
- For each port with an MCP page, check the shared split prompt, a
  recording, a window with two panes at some step, and the example's
  session gone at the end.
- Show the check can fail: a read-only prefix of Ruby's recording never
  holds two panes in a window.
why: The assembled-site check required Install to be the first section
of every product overview. An MCP overview with a worked example now
opens with it, so the check failed on py/latest/mcp/ in CI.

what:
- Expect worked-example first on an MCP overview that has one, with
  Install after it; the install picker and card order checks stay.
- Leave the Workspace overview order as it was: the preset picker, then
  Install.
why: The JSON a call returned was drawn larger than the program beside
it. The program's size follows its own column and its longest line,
which the result box cannot see, so the box took the landing page's
general code size: 14.6px beside a 12px program at 896px.

what:
- CorePlayer copies the shown program's computed font size into
  --core-program-size on the side panel, on each render (a step or a
  change of view) and when the stage resizes
- core-player.css sets a returned value's code at that size, or at the
  program's smallest size without the script
- Cover both views in test/core-player.test.ts (fails without the
  script change)
why: The call the tmux view shows and a hovered call were drawn alike,
in a background 1.23:1 against the panel in dark mode and 1.08:1 in
light, with a muted edge. Readers could not tell it from the rest.

what:
- The shown call takes a 3px accent edge, 11:1 against the dark panel
  and 6:1 against the light one, and the 14% accent tint the Core
  player gives its current line; 24% when it is also pinned
- A hovered call that is not shown keeps the muted edge and tint
why: A workspace overview with several examples opens with the preset
picker; one with a single example (go, ruby, julia, csharp) has no
picker and showed its example at the end of the page, while the
landing page's Workspace Manager tab leads with it.

what:
- DocPage draws the showcase before Install when the port has one
  example, and after the prose when a picker opens the page; the
  table of contents follows the same order
- The assembled-site check expects example-workspaces first on such
  an overview, then Install, and the examples once
- Update the DocPage source check in test/workspace-showcase.test.ts
@tony
tony force-pushed the fix/mcp-overview-replay branch from 4e6aea7 to 818315d Compare November 7, 2026 18:58
@tony
tony merged commit c5b56f2 into main Nov 7, 2026
3 checks passed
@tony
tony temporarily deployed to docs-preview-cleanup November 7, 2026 22:59 — with GitHub Actions Inactive

This branch was previously deployed

2 inactive deployments
docs-preview-cleanup — 818315da Deployed Nov 7, 2026 by tony via cleanup #213
docs-preview — 818315da Deployed Nov 7, 2026 by tony via publish-preview / publish #1188
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant