FastMCP alignment: new tools, prompts, and middleware

[tony]

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]

Codecov Report

❌ Patch coverage is 89.43466% with 114 lines in your changes missing coverage. Please review.
✅ Project coverage is 86.90%. Comparing base (1d4dd37) to head (79c3097).

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	72.30%	16 Missing and 2 partials ⚠️
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 ⚠️
docs/_ext/widgets/_directive.py	90.90%	3 Missing ⚠️
docs/_ext/widgets/_discovery.py	83.33%	2 Missing and 1 partial ⚠️
... and 9 more

Additional details and impacted files

@@            Coverage Diff             @@
##             main      #15      +/-   ##
==========================================
+ Coverage   82.92%   86.90%   +3.97%     
==========================================
  Files          17       38      +21     
  Lines         984     1710     +726     
  Branches      110      201      +91     
==========================================
+ Hits          816     1486     +670     
- Misses        122      165      +43     
- Partials       46       59      +13     

☔ 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]

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 👎.}

[tony]

Code review

Found 1 issue:

1. New widget-framework modules use from X import Y imports for standard-library modules, which AGENTS.md explicitly prohibits: "Use namespace imports for standard library modules: import enum instead of from enum import Enum … For typing, use import typing as t and access via namespace … Exception: dataclasses module may use from dataclasses import dataclass, field." 18 occurrences across 8 new files in docs/_ext/widgets/ and tests/docs/; existing src/libtmux_mcp/ code consistently follows the rule.

Representative examples (each touches abc, collections.abc, pathlib, typing, functools):

libtmux-mcp/docs/_ext/widgets/_base.py

Lines 4 to 9 in 34a7f3c

	from abc import ABC
	from collections.abc import Callable, Mapping
	from pathlib import Path
	from typing import TYPE_CHECKING, Any, ClassVar, Protocol

libtmux-mcp/docs/_ext/widgets/mcp_install.py

Lines 4 to 9 in 34a7f3c

	import textwrap
	from collections.abc import Mapping
	from dataclasses import dataclass
	from typing import TYPE_CHECKING, Any, ClassVar

libtmux-mcp/tests/docs/test_widgets.py

Lines 3 to 11 in 34a7f3c

	from __future__ import annotations
	import io
	import re
	import textwrap
	import typing as t
	from pathlib import Path
	import pytest

Suggested mechanical fix: from pathlib import Path → import pathlib (then pathlib.Path); from typing import TYPE_CHECKING, Any, ClassVar, Protocol → import typing as t (then t.TYPE_CHECKING, t.Any, etc.); from abc import ABC → import abc (then abc.ABC); from collections.abc import Callable, Mapping → import collections.abc (then collections.abc.Callable); from functools import partial → import functools. from dataclasses import dataclass in mcp_install.py is the explicitly-allowed exception and stays.

🤖 Generated with Claude Code

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

[tony]

Code review

No issues found. Checked for bugs and AGENTS.md compliance against the atomized commits (6b46a51..906dc40). The namespace-imports violation from the prior review is resolved.

🤖 Generated with Claude Code

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