Repository navigation
Open the MCP overview with its worked example, and record the split flow for Ruby and Julia - #262
Merged
Merged
Conversation
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
force-pushed
the
fix/mcp-overview-replay
branch
from
November 7, 2026 18:58
4e6aea7 to
818315d
Compare
tony
temporarily deployed
to
docs-preview-cleanup
November 7, 2026 22:59 — with
GitHub Actions
Inactive
This was referenced Nov 8, 2026
This branch was previously deployed
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
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.
McpShowcasetakes apartprop (exampleortools) andDocPagerenders 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:
tmux_capabilitiestmux_create(sessionchecks)tmux_create(pane, split%1)tmux_snapshot(window layout)tmux_send+ 6.tmux_wait(pytest -qin%1, wait for2 passed)tmux_send+ 8.tmux_wait(cat checks.login%2, wait forchecks finished)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 asstale_target, as it does for Julia.tmux_runis 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 throughBUNDLE_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 acceptstmux_closeas a removal andshas 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_panesscoped to the session,send_keys_and_waitforpytest -qand forcat checks.log, andteardown_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-createand 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.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
CorePlayercopies the shown program's computed size into--core-program-sizeon each step, view change and resize.What ran
Locally, through
heavy.sh:scripts/gen-mcp-transcript.mjs --port rubyand--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) andworkspace-showcase: pass.The full
testworkflow, 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.