Server

FastMCP server instance for libtmux.

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

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 = 'NO DEDICATED HOOK-WRITE TOOLS: use show_hooks/show_hook. Write hooks survive process death; keep them in your tmux config file.'
data
data
libtmux_mcp.server._INSTR_HOOKS_GAP = 'NO DEDICATED HOOK-WRITE TOOLS: use show_hooks/show_hook. Write hooks survive process death; keep them in your tmux config file.'

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 = 'BUFFERS: load_buffer stages, paste_buffer delivers, delete_buffer removes via returned BufferRef. No list_buffers: tmux buffers may include clipboard history.'
data
data
libtmux_mcp.server._INSTR_BUFFERS_GAP = 'BUFFERS: load_buffer stages, paste_buffer delivers, delete_buffer removes via returned BufferRef. No list_buffers: tmux buffers may include clipboard history.'

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

libtmux_mcp.server.DEFAULT_TOOLSETS: frozenset[str] = frozenset({'execute', 'inspect', 'manage'})
data
data
libtmux_mcp.server.DEFAULT_TOOLSETS: frozenset[str] = frozenset({'execute', 'inspect', 'manage'})

Enabled when LIBTMUX_TOOLSETS is unset. teardown is not in it: this server still reaches whichever tmux server the environment points at, so deletion stays something an operator asks for by name.

libtmux_mcp.server._build_instructions(toolsets=DEFAULT_TOOLSETS, suppress_history=True)
function[source]
function[source]
libtmux_mcp.server._build_instructions(toolsets=DEFAULT_TOOLSETS, suppress_history=True)

Build server instructions with agent context and toolsets.

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:

  • toolsets (frozenset of str) – Enabled toolsets.

  • suppress_history (bool) – Effective MCP default for semantic shell-command suppression.

Returns:

Server instructions string, optionally with agent tmux context.

Return type:

str

libtmux_mcp.server._resolve_toolsets(value)
function[source]
function[source]
libtmux_mcp.server._resolve_toolsets(value)

Return the enabled toolsets for a LIBTMUX_TOOLSETS value.

Parameters:

value (str or None) – Comma-separated toolset names. None takes the default; an empty string enables none, which is legal.

Returns:

Enabled toolsets.

Return type:

frozenset of str

Raises:

RuntimeError – If a name is not a toolset. A typo silently falling back is how a narrowed surface quietly becomes a wider one.

libtmux_mcp.server._resolve_tool_names(value)
function[source]
function[source]
libtmux_mcp.server._resolve_tool_names(value)

Return a comma-separated tool-name list as a set.

Parameters:

value (str | None)

Return type:

frozenset[str]

libtmux_mcp.server._reject_retired_safety_env()
function[source]
function[source]
libtmux_mcp.server._reject_retired_safety_env()

Fail startup when LIBTMUX_SAFETY is still set.

The former setting selected an ordered ladder that read as a permission system and was not one. Ignoring the variable would silently widen a surface an operator believes is narrow.

Return type:

None

libtmux_mcp.server._RESPONSE_LIMITED_TOOLS = ['capture_pane', 'capture_since', 'search_panes', 'snapshot_pane', 'show_buffer']
data
data
libtmux_mcp.server._RESPONSE_LIMITED_TOOLS = ['capture_pane', 'capture_since', '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[source]
function[source]
libtmux_mcp.server._lifespan(_app)

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

Startup

Validates named tool includes and exclusions against the transformed catalog, then verifies that a tmux binary is on PATH. Without the binary 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 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. Shutdown sends no tmux commands. Buffer tools expose explicit cleanup, and a process-wide prefix does not prove which MCP instance owns a buffer.

Parameters:

_app (FastMCP)

Return type:

AsyncIterator[None]

libtmux_mcp.server._register_all()
function[source]
function[source]
libtmux_mcp.server._register_all()

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

Return type:

None

libtmux_mcp.server._enable_allowed_tools()
function[source]
function[source]
libtmux_mcp.server._enable_allowed_tools()

Apply FastMCP’s visibility gate for the enabled toolsets.

Return type:

None

libtmux_mcp.server.build_mcp_server()
function[source]
function[source]
libtmux_mcp.server.build_mcp_server()

Build and return the registered production FastMCP server.

This factory is used by fastmcp.json so FastMCP’s CLI can inspect or run the same populated server that the libtmux-mcp console script starts.

Return type:

FastMCP

libtmux_mcp.server.run_server()
function[source]
function[source]
libtmux_mcp.server.run_server()

Run the MCP server.

Return type:

None