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._ICONS_BASE = 'https://libtmux-mcp.git-pull.com/_static/img/'
data
data
libtmux_mcp.server._ICONS_BASE = 'https://libtmux-mcp.git-pull.com/_static/img/'

Server icons, hosted on the docs site so the wheel carries no image data. Clients must render PNG and should render SVG, so both are declared. One mark serves both themes, as in the docs sidebar.

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