Server

FastMCP server instance for libtmux.

Creates and configures the MCP server with all tools and resources.

libtmux_mcp.server._ServerCacheKey

data

data

libtmux_mcp.server._ServerCacheKey

Cache-key shape used by _server_cache and the GC helper. (socket_name, socket_path, tmux_bin) — see libtmux_mcp._utils._get_server().

alias of tuple[str | None, str | None, str | None]

libtmux_mcp.server._INSTR_SCOPE = <...truncated, 465 chars>

data

data

libtmux_mcp.server._INSTR_SCOPE = <...truncated, 465 chars>

Activation rule. Names positive triggers and explicit anti-triggers so bare ‘pane’/’window’/’session’ default to tmux but the server stays out of the way for browser/editor/GUI/Jupyter contexts.

libtmux_mcp.server._INSTR_HOOKS_GAP = 'HOOKS ARE READ-ONLY: inspect via show_hooks / show_hook. Write-hooks survive process death; keep them in your tmux config file, not a transient MCP session.'

data

data

libtmux_mcp.server._INSTR_HOOKS_GAP = 'HOOKS ARE READ-ONLY: inspect via show_hooks / show_hook. Write-hooks survive process death; keep them in your tmux config file, not a transient MCP session.'

Gap-explainer: write-hook tools are intentionally absent. See module comment above for when to add another _GAP segment vs. push the explanation into a tool description.

libtmux_mcp.server._INSTR_BUFFERS_GAP = <...truncated, 204 chars>

data

data

libtmux_mcp.server._INSTR_BUFFERS_GAP = <...truncated, 204 chars>

Gap-explainer: list_buffers is intentionally absent because tmux buffers can include OS clipboard history. See module comment above.

libtmux_mcp.server._build_instructions(safety_level=TAG_MUTATING)

function

function

libtmux_mcp.server._build_instructions(safety_level=TAG_MUTATING)

Build server instructions with agent context and safety level.

When the MCP server process runs inside a tmux pane, TMUX_PANE and TMUX environment variables are available. This function appends that context so the LLM knows which pane is its own without extra tool calls.

Parameters:

safety_level (str) – Active safety tier (readonly, mutating, or destructive).

Returns:

Server instructions string, optionally with agent tmux context.

Return type:

str

libtmux_mcp.server._RESPONSE_LIMITED_TOOLS = ['capture_pane', 'search_panes', 'snapshot_pane', 'show_buffer']

data

data

libtmux_mcp.server._RESPONSE_LIMITED_TOOLS = ['capture_pane', 'search_panes', 'snapshot_pane', 'show_buffer']

Tools covered by the tail-preserving response limiter. Only tools whose output is terminal scrollback benefit from this backstop; structured responses from list/get tools stay under the cap naturally.

libtmux_mcp.server._lifespan(_app)

function

function

libtmux_mcp.server._lifespan(_app)

FastMCP lifespan: fail-fast startup + deterministic cache cleanup.

Startup

Verifies that a tmux binary is on PATH. Without this probe, tools fail at first call with a generic TmuxCommandNotFound deep inside libtmux. Failing at server start instead surfaces a clear cold-start error before any tool traffic arrives.

Shutdown

Clears the process-wide _server_cache so repeated test runs don’t share stale Server references and HTTP-transport reload cycles start clean. Also best-effort GC’s any leftover libtmux_mcp_* paste buffers on every cached server — agents are supposed to delete_buffer after use, but an interrupted call chain can leak. Note: FastMCP lifespan teardown runs on SIGTERM / SIGINT only; kill -9 and OOM bypass it, so this path must not be relied on for any invariant that must survive a hard crash (see the hook_tools module docstring for why write-hooks are explicitly NOT gated on lifespan cleanup).

Parameters:

_app (FastMCP)

Return type:

AsyncIterator[None]

libtmux_mcp.server._gc_mcp_buffers(cache)

function

function

libtmux_mcp.server._gc_mcp_buffers(cache)

Best-effort delete of leaked libtmux_mcp_* paste buffers.

Iterates every cached tmux Server, lists buffer names, and deletes anything matching the MCP prefix. Never raises: tmux may be unreachable, buffers may vanish mid-scan, and none of that should block lifespan shutdown. Logs at debug level so operators can still surface leaks via verbose logging.

Parameters:

cache (Mapping[_ServerCacheKey, Server])

Return type:

None

libtmux_mcp.server._register_all()

function

function

libtmux_mcp.server._register_all()

Register all tools, resources, and prompts with the MCP server.

Return type:

None

libtmux_mcp.server.run_server()

function

function

libtmux_mcp.server.run_server()

Run the MCP server.

Return type:

None