FastMCP alignment: new tools, prompts, and middleware by tony · Pull Request #15 · tmux-python/libtmux-mcp

tony · 2026-04-13T23:37:23Z

Summary

FastMCP alignment for libtmux-mcp: new tool families, prompt recipes, middleware stack, bounded outputs, and correctness fixes.

Breaking changes

search_panes returns SearchPanesResult (was list[PaneContentMatch]). Matches move to .matches; new pagination fields. Migration: for m in search_panes(...).matches.
Minimum fastmcp>=3.2.4.

New tools

Discovery — list_servers.
Waits — wait_for_text, wait_for_content_change, wait_for_channel, signal_channel. Bounded, cancellable, emit ctx.report_progress / ctx.warning.
Buffers — load_buffer, paste_buffer, show_buffer, delete_buffer. UUID-namespaced; leaked buffers GC'd on shutdown.
Hooks (read-only) — show_hook, show_hooks.
Panes / windows — snapshot_pane, pipe_pane, display_message, paste_text, select_pane, swap_pane, select_window, move_window, enter_copy_mode, exit_copy_mode.

New prompts

Four recipes: run_and_wait, diagnose_failing_pane, build_dev_workspace, interrupt_gracefully. Expose as tools with LIBTMUX_MCP_PROMPTS_AS_TOOLS=1.

Middleware

TimingMiddleware, ErrorHandlingMiddleware, AuditMiddleware, SafetyMiddleware, ReadonlyRetryMiddleware, TailPreservingResponseLimitingMiddleware.

Bounded outputs

capture_pane, snapshot_pane, show_buffer take max_lines (default 500) with tail-preserving truncation. Pass max_lines=None to opt out.

Fixes

search_panes — neutralize tmux format-string injection.
macOS TMUX_TMPDIR self-kill guard — resolve socket via display-message before env fallback.
build_dev_workspace prompt — real parameter names, drop post-launch prompt waits, OS-neutral log_command.

Test plan

uv run ruff check . && uv run ruff format --check .
uv run mypy
uv run py.test --reruns 0 — 276 tests pass
just build-docs
Manual: start with tmux renamed on PATH → clean RuntimeError from lifespan probe
Manual: capture_pane on a >50 KB scrollback pane with max_lines=None → head trimmed, tail preserved
Manual: search_panes pagination via offset/limit
Manual: wait_for_channel + signal_channel round-trip
Manual: LIBTMUX_MCP_PROMPTS_AS_TOOLS=1 → prompts in tool list

codecov-commenter · 2026-04-13T23:54:24Z

Codecov Report

❌ Patch coverage is 88.77551% with 99 lines in your changes missing coverage. Please review.
✅ Project coverage is 86.18%. Comparing base (88fcf6a) to head (3f8f281).

Files with missing lines	Patch %	Lines
src/libtmux_mcp/_utils.py	84.34%	11 Missing and 7 partials ⚠️
src/libtmux_mcp/tools/server_tools.py	75.38%	15 Missing and 1 partial ⚠️
src/libtmux_mcp/tools/hook_tools.py	81.35%	8 Missing and 3 partials ⚠️
src/libtmux_mcp/tools/wait_for_tools.py	72.50%	11 Missing ⚠️
src/libtmux_mcp/tools/buffer_tools.py	89.01%	8 Missing and 2 partials ⚠️
src/libtmux_mcp/tools/pane_tools/io.py	86.20%	7 Missing and 1 partial ⚠️
src/libtmux_mcp/tools/pane_tools/layout.py	85.71%	4 Missing and 4 partials ⚠️
src/libtmux_mcp/middleware.py	90.47%	3 Missing and 3 partials ⚠️
src/libtmux_mcp/tools/pane_tools/lifecycle.py	86.36%	2 Missing and 1 partial ⚠️
src/libtmux_mcp/server.py	92.59%	2 Missing ⚠️
... and 3 more

Additional details and impacted files

@@            Coverage Diff             @@
##             main      #15      +/-   ##
==========================================
+ Coverage   82.90%   86.18%   +3.27%     
==========================================
  Files          17       30      +13     
  Lines         983     1513     +530     
  Branches      110      182      +72     
==========================================
+ Hits          815     1304     +489     
- Misses        122      155      +33     
- Partials       46       54       +8

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

tony · 2026-04-14T00:31:03Z

Code review

No issues found. Checked for bugs and CLAUDE.md compliance.

🤖 Generated with Claude Code

_{- If this code review was useful, please react with 👍. Otherwise, react with 👎.}

…thread around capture_pane why: In commit 67c3fc8 the wait tools became `async def` so that ctx.report_progress could be awaited during long polls. FastMCP direct-awaits async tools on the main event loop (`fastmcp/tools/function_tool.py:277-278`) — it only uses a threadpool for *sync* tools via `call_sync_fn_in_threadpool`. That means every blocking `pane.capture_pane()` subprocess.run inside the poll loop starves every other concurrent MCP request for the duration of the tmux roundtrip (~10s of ms per tick), for the full configured timeout. A 60-second `wait_for_text` call would pin the entire server for 60 seconds, delaying list_sessions / capture_pane / anything else. Loom code review surfaced this with 100% confidence (Gemini Skeptic pass on PR #15); verified against FastMCP source. what: - Wrap the three blocking `pane.capture_pane(...)` calls in src/libtmux_mcp/tools/pane_tools/wait.py with `asyncio.to_thread`: * `wait_for_text` polling call. * `wait_for_content_change` initial snapshot. * `wait_for_content_change` polling call. - Inline comment at the first site explains why (future maintainers will otherwise see "sync call inside async fn" as a bug and try to "fix" it by removing `async def`, reintroducing the blocking path). - No docstring changes — the `async def` signature already promises non-blocking semantics; this commit actually delivers on it. - Add `test_wait_tools_do_not_block_event_loop` in tests/test_pane_tools.py that runs `wait_for_text` against a never-matching pattern inside an asyncio.gather with a ticker coroutine. Asserts the ticker counter >= 5 over the 300 ms wait window — a blocking capture would leave it at 0 or 1. Deliberately a generous lower bound to stay robust on slow CI.

…_wait why: The ``run_and_wait`` prompt hardcoded ``mcp_done`` as the tmux wait-for channel name. tmux channels are server-global, so two concurrent agents (or parallel prompt renderings from one agent) would race: one agent's ``tmux wait-for -S mcp_done`` would unblock another's pending ``wait_for_channel("mcp_done")``, producing a false positive completion signal. Flagged as Critical by GPT Builder in the Loom review of PR #15. what: - Import ``uuid`` in src/libtmux_mcp/prompts/recipes.py. - Generate a fresh channel name at each call: ``libtmux_mcp_wait_<uuid4hex[:8]>``. * Prefix aligns with the buffer-tools namespace (libtmux_mcp_) so a future ``list_buffers(prefix="libtmux_mcp_")``-style operator sees every MCP-owned tmux artifact uniformly. * 8 hex characters (~32 bits) is safe against collision inside a single tmux server's concurrent-agent population. - Interpolate the same channel name into both the send_keys payload and the wait_for_channel call so one prompt rendering remains internally consistent. - Update the prompt docstring to note the per-invocation scope. - tests/test_prompts.py: * Update ``test_run_and_wait_returns_string_template`` to pin the new prefix. * Add ``test_run_and_wait_channel_is_uuid_scoped`` asserting (a) channel matches ``libtmux_mcp_wait_[0-9a-f]{8}``, (b) send_keys and wait_for_channel use the same name within one rendering, (c) two separate renderings emit different channel names.

why: ``show_hook`` swallowed three tmux error substrings into an empty result: ``"too many arguments"`` (correctly — that's how tmux reports an unset hook), but also ``"unknown hook"`` and ``"invalid option"``. The latter two fire for *typos* and *wrong-scope* mistakes, not "hook is unset". Agents sending ``show_hook("pane-esited")`` (typo) or ``show_hook("pane-exited", scope="server")`` (wrong scope) got back an empty list indistinguishable from a correctly-named but unset hook — masking the real input error. Flagged as Important by both Gemini (Skeptic) and GPT (Builder) in the Loom review of PR #15. This commit also lands the upstream TODO comment for Suggestion #15 (libtmux's scope-kwarg argv bug). what: - Narrow the ``except libtmux_exc.OptionError`` branch in src/libtmux_mcp/tools/hook_tools.py::show_hook to only match ``"too many arguments"`` — the single substring all tmux builds supported by this project use for an unset hook. Any other OptionError (``"unknown hook"``, ``"invalid option"``, new future substrings) re-raises so ``handle_tool_errors`` surfaces it. - Replace the block's comment with the reasoning so a future maintainer knows not to re-broaden the catch. - Add a TODO(libtmux upstream) comment in ``_resolve_hook_target`` explaining why the scope-nulling workaround exists. The fix belongs in libtmux's argv-assembly path, not here. - tests/test_hook_tools.py: * Remove ``test_show_hook_missing_returns_empty`` (its use of ``"after-nonexistent-hook-cxyz"`` was actually exercising the now-removed broad catch). * Add ``test_show_hook_unset_known_hook_returns_empty`` that sets and then unsets a real hook (``pane-exited``) before calling ``show_hook`` — exercises the narrow "too many arguments" path. * Add ``test_show_hook_unknown_name_raises`` asserting that a bogus hook name now surfaces as ``ToolError`` matching ``r"invalid option|unknown hook"`` (regression guard against re-broadening the swallow).

…tmcp why: ``fastmcp_model_classes`` in docs/conf.py is the allow-list that ``sphinx-autodoc-fastmcp`` uses to decide which Pydantic models get rendered in the generated schema docs. After PR #15 added seven new models, the tuple still listed only the original ten — so the new schemas (``SearchPanesResult``, ``PaneSnapshot``, ``ContentChangeResult``, ``HookEntry``, ``HookListResult``, ``BufferRef``, ``BufferContent``) were invisible in the built API docs, even though they're part of every tool surface that was documented. Flagged as Important by Gemini (Skeptic) in the Loom review. what: - Add the seven new model names to ``conf["fastmcp_model_classes"]`` in docs/conf.py. Keeps the existing order for the old entries; new entries are inserted at semantically adjacent positions (e.g. ``SearchPanesResult`` next to ``PaneContentMatch``, ``ContentChangeResult`` next to ``WaitForTextResult``, ``HookEntry`` / ``HookListResult`` grouped, ``BufferRef`` / ``BufferContent`` grouped). - Verified post-build: all seven names appear in the generated reference/api/models/index.html.

…ult shape why: PR #15 wrapped ``search_panes`` output in a ``SearchPanesResult`` model (matches + pagination fields) but the docs/tools/panes.md example still showed the pre-wrapper bare-array response shape. Three reviewers converged on this (Claude + Gemini + GPT in the Loom review, 3-way consensus). what: - Rewrite the response block in docs/tools/panes.md from: [ {pane_id: ..., matched_lines: [...]} ] to the actual wrapper: { matches: [...], truncated, truncated_panes, total_panes_matched, offset, limit } - Add a one-paragraph pagination hint above the example explaining how to iterate larger result sets via ``offset += len(matches)`` until ``truncated == false`` and ``truncated_panes == []``.

why: AGENTS.md §255-287 requires doctests on pure helpers. Most of the pure helpers introduced by PR #15 have them (``_validate_channel_name``, ``_validate_logical_name``, ``_validate_buffer_name``, ``_truncate_lines_tail``, ``_tmux_argv``, ``_pane_id_sort_key``). The critic pass surfaced ``_allocate_buffer_name`` as the lone remaining pure helper without a doctest — an oversight when commit 272396d introduced the module. Loom review Suggestion #16 (finalized). what: - Expand the docstring on src/libtmux_mcp/tools/buffer_tools.py::_allocate_buffer_name with a NumPy-style ``Examples`` block covering: * prefix contract (``"libtmux_mcp_"``), * logical-name suffix preservation, * 32-hex-character uuid nonce length, * empty-string and ``None`` both collapsing to the ``"buf"`` fallback. - The docstring also expands the rationale for why the name has the exact shape it does (privacy prefix + collision-resistant nonce + logical suffix), so future maintainers don't reduce the structure and accidentally re-introduce either the OS-clipboard read risk or the cross-agent collision risk that commit 272396d fixed.