mcp(feat[resources]): add tmux://reference/format-strings cheat sheet

Static markdown reference resource cataloging the tmux format strings
agents most commonly encounter via ``display_message`` and friends:
pane / window / session / server fields, plus the conditional and
string-operation forms (``#{?cond,then,else}``, ``#{=N:expr}``,
``#{s/from/to/:expr}``, etc.).

Why a resource and not a tool: tmux format strings are a closed
catalog, not a query. Agents that hit a ``#{...}`` field they don't
recognize need a fixed lookup, not a server round-trip. Pulling the
reference is cheaper than guessing a name and burning a
``display_message`` call to confirm it.

The new module follows the ``hierarchy.register(mcp)`` shape: closures
decorated with ``@mcp.resource(...)`` and a trailing ``_ = (fn,)``
tuple to silence type-checker unused-name warnings without exporting
the local name. Concrete URI (no template params), so it registers
under ``mcp.list_resources()`` rather than ``list_resource_templates()``.

Tests cover both layers: a closure-capture fixture verifies the body
contains the spot-check format strings (``#{pane_id}``, ``#{window_id}``,
``#{session_id}``, ``#{?cond,then,else}``), and a real-FastMCP test
verifies the registered resource advertises ``text/markdown`` so
clients render it correctly.

Author: tony

src/libtmux_mcp/resources/__init__.py

@@ -10,6 +10,7 @@
 
 def register_resources(mcp: FastMCP) -> None:
     """Register all resource modules with the FastMCP instance."""
-    from libtmux_mcp.resources import hierarchy
+    from libtmux_mcp.resources import hierarchy, reference
 
     hierarchy.register(mcp)
+    reference.register(mcp)

src/libtmux_mcp/resources/reference.py

@@ -0,0 +1,107 @@
+"""Static reference resources for tmux primitives.
+
+Why a resource and not a tool: tmux format strings (``#{pane_id}``,
+``#{pane_in_mode}``, ``#{?cond,then,else}``) are a closed reference
+catalog, not a query. Agents that hit a ``#{...}`` field they don't
+recognize need a fixed lookup, not a tool round-trip. Exposing this as
+an MCP resource lets clients pull it on demand and lets the agent
+recover from an unknown-format-name guess without paying a
+``display_message`` round-trip just to discover what's available.
+"""
+
+from __future__ import annotations
+
+import textwrap
+import typing as t
+
+if t.TYPE_CHECKING:
+    from fastmcp import FastMCP
+
+
+#: MIME type for the format-string reference resource. Markdown gives
+#: clients enough structure to render headings and code spans without
+#: requiring a richer content type.
+_MARKDOWN_MIME = "text/markdown"
+
+
+_FORMAT_STRING_REFERENCE = textwrap.dedent("""\
+    # tmux format strings
+
+    Pass via ``display_message(format_string="#{...}")`` or any other
+    tool that accepts a tmux format expression.
+
+    ## Pane
+
+    - ``#{pane_id}`` — globally unique pane identifier (e.g. ``%1``)
+    - ``#{pane_index}`` — index within the window
+    - ``#{pane_current_command}`` — foreground command name
+    - ``#{pane_current_path}`` — current working directory
+    - ``#{pane_pid}`` — pane process PID
+    - ``#{pane_dead}`` — ``1`` when the pane's process has exited
+    - ``#{pane_in_mode}`` — ``1`` when the pane is in copy/scroll mode
+    - ``#{pane_mode}`` — current pane mode name when in mode
+    - ``#{pane_active}`` — ``1`` for the active pane in its window
+    - ``#{pane_width}`` / ``#{pane_height}`` — pane dimensions in cells
+    - ``#{cursor_x}`` / ``#{cursor_y}`` — cursor position within the pane
+    - ``#{scroll_position}`` — scrollback position when in copy mode
+
+    ## Window
+
+    - ``#{window_id}`` — globally unique window identifier (e.g. ``@1``)
+    - ``#{window_index}`` — window index within the session
+    - ``#{window_name}`` — window name
+    - ``#{window_zoomed_flag}`` — ``1`` when a pane is zoomed
+    - ``#{window_layout}`` — current layout string
+    - ``#{window_panes}`` — number of panes in the window
+    - ``#{window_active}`` — ``1`` for the active window in its session
+
+    ## Session
+
+    - ``#{session_id}`` — globally unique session identifier (e.g. ``$1``)
+    - ``#{session_name}`` — session name
+    - ``#{session_attached}`` — ``1`` when at least one client is attached
+    - ``#{session_windows}`` — number of windows in the session
+
+    ## Server / client
+
+    - ``#{host}`` — hostname running the tmux server
+    - ``#{client_tty}`` — TTY of the client (when evaluated client-side)
+    - ``#{socket_path}`` — server socket path
+
+    ## Conditionals and string operations
+
+    - ``#{?cond,then,else}`` — emit ``then`` if ``cond`` is truthy, else
+      ``else``
+    - ``#{C/i:pattern}`` — case-insensitive search inside the result
+    - ``#{=N:expr}`` — truncate ``expr`` to ``N`` characters
+    - ``#{s/from/to/:expr}`` — substitution
+    - ``#{T:expr}`` — recursively expand format strings within ``expr``
+
+    See ``man tmux`` (FORMATS section) for the complete catalog.
+""")
+
+
+def register(mcp: FastMCP) -> None:
+    """Register reference resources with the FastMCP instance."""
+
+    @mcp.resource(
+        "tmux://reference/format-strings",
+        title="tmux Format String Reference",
+        mime_type=_MARKDOWN_MIME,
+    )
+    def get_format_string_reference() -> str:
+        """Return the tmux format-string cheat sheet as Markdown.
+
+        Static reference content. Use this when an agent encounters
+        an unfamiliar ``#{...}`` field — pulling the resource is
+        cheaper than a ``display_message`` round-trip and avoids
+        hallucinated format names.
+        """
+        return _FORMAT_STRING_REFERENCE
+
+    # Type checkers: list the function to silence unused-name warnings
+    # without exposing it outside this closure.
+    _ = (get_format_string_reference,)
+
+
+__all__ = ["register"]

tests/test_resources.py

@@ -8,6 +8,7 @@
 import pytest
 
 from libtmux_mcp.resources.hierarchy import register
+from libtmux_mcp.resources.reference import register as register_reference
 
 if t.TYPE_CHECKING:
     from libtmux.pane import Pane
@@ -184,3 +185,74 @@ def test_hierarchy_resources_advertise_mime_type(uri: str, expected_mime: str) -
     candidate = by_uri.get(uri)
     assert candidate is not None, f"resource {uri!r} not registered"
     assert candidate.mime_type == expected_mime
+
+
+# ---------------------------------------------------------------------------
+# Reference resources (static catalogs, no tmux server interaction)
+# ---------------------------------------------------------------------------
+
+
+@pytest.fixture
+def reference_resource_functions() -> dict[str, t.Any]:
+    """Capture reference-module resource closures by URI.
+
+    Mirrors ``resource_functions`` but registers
+    :mod:`libtmux_mcp.resources.reference` instead of ``hierarchy``.
+    Reference resources are static and need no tmux fixtures.
+    """
+    functions: dict[str, t.Any] = {}
+
+    class MockMCP:
+        def resource(self, uri: str, **kwargs: t.Any) -> t.Any:
+            def decorator(fn: t.Any) -> t.Any:
+                functions[uri] = fn
+                return fn
+
+            return decorator
+
+    register_reference(MockMCP())  # type: ignore[arg-type]
+    return functions
+
+
+def test_format_string_reference_returns_markdown(
+    reference_resource_functions: dict[str, t.Any],
+) -> None:
+    """tmux://reference/format-strings returns non-empty Markdown.
+
+    The agent's reason for pulling this resource is to recover from an
+    unfamiliar ``#{...}`` token without burning a ``display_message``
+    round-trip. The body must therefore (a) be present and (b) name
+    the format strings most likely to confuse — pane / window /
+    session ID forms and the ``#{?cond,then,else}`` conditional.
+    """
+    fn = reference_resource_functions["tmux://reference/format-strings"]
+    body = fn()
+    assert isinstance(body, str)
+    assert body.strip(), "format-string reference body is empty"
+    # Spot-check the highest-traffic catalog entries — if any of these
+    # vanish, the reference is failing at its job.
+    assert "#{pane_id}" in body
+    assert "#{window_id}" in body
+    assert "#{session_id}" in body
+    assert "#{?cond,then,else}" in body
+
+
+def test_format_string_reference_advertises_markdown_mime() -> None:
+    """tmux://reference/format-strings is registered with text/markdown.
+
+    Concrete URIs (no ``{...}`` template params) register as resources,
+    not resource templates — they show up under ``mcp.list_resources()``
+    rather than ``mcp.list_resource_templates()``.
+    """
+    import asyncio
+
+    from fastmcp import FastMCP
+
+    mcp = FastMCP(name="test-reference-mime")
+    register_reference(mcp)
+
+    resources = asyncio.run(mcp.list_resources())
+    by_uri = {str(getattr(r, "uri", "")): r for r in resources}
+    target = by_uri.get("tmux://reference/format-strings")
+    assert target is not None, "format-strings reference not registered"
+    assert target.mime_type == "text/markdown"