From 0d756310351df934c9c420172ec6844203b4533b Mon Sep 17 00:00:00 2001 From: Tony Narlock Date: Sat, 25 Jul 2026 12:23:24 -0500 Subject: [PATCH 1/2] mcp(docs[_utils]): Document CallerIdentity fields why: Undocumented dataclass fields render in the API reference as "Alias for field number 0" or bare names, leaving readers to infer what each part of the parsed $TMUX/$TMUX_PANE identity means and what its None sentinel implies for the socket comparisons. what: - Add a NumPy Attributes section to CallerIdentity covering the socket path, server pid, session id, and pane id - Record which environment variable field each value comes from and what an unset value means for caller-on-server checks --- src/libtmux_mcp/_utils.py | 20 ++++++++++++++++++++ 1 file changed, 20 insertions(+) diff --git a/src/libtmux_mcp/_utils.py b/src/libtmux_mcp/_utils.py index 34340d6e..587e2d85 100644 --- a/src/libtmux_mcp/_utils.py +++ b/src/libtmux_mcp/_utils.py @@ -104,6 +104,26 @@ class CallerIdentity: Used to scope self-protection checks to the caller's own tmux server — a pane ID like ``%1`` is only unique within a single server, so comparisons must also verify the socket path matches. + + Attributes + ---------- + socket_path : str | None + Filesystem path of the tmux socket the caller is attached to, from + the first ``TMUX`` field. ``None`` when ``TMUX`` is unset or its + first field is empty — the socket comparisons in + :func:`_caller_is_on_server` and + :func:`_caller_is_strictly_on_server` then cannot prove which + server the caller belongs to. + server_pid : int | None + PID of the tmux server process, from the second ``TMUX`` field. + ``None`` when that field is absent or not an integer. + session_id : str | None + Session the caller's pane belongs to (e.g. ``$7``), from the third + ``TMUX`` field. ``None`` when that field is absent or empty. + pane_id : str | None + Pane the MCP server process runs in (e.g. ``%3``), read from + ``TMUX_PANE``. ``None`` when the variable is unset, meaning no + pane can be identified as the caller's own. """ socket_path: str | None From e862fb56ea3e54c1c191037dbe3c7e415f3d4bc0 Mon Sep 17 00:00:00 2001 From: Tony Narlock Date: Sat, 25 Jul 2026 20:13:13 -0500 Subject: [PATCH 2/2] docs(CHANGES) Documented class fields why: The unreleased entry did not record that class fields now carry descriptions where the API reference renders them. what: - Note the described fields under Documentation --- CHANGES | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/CHANGES b/CHANGES index c84bd224..af452ca3 100644 --- a/CHANGES +++ b/CHANGES @@ -6,6 +6,14 @@ _Notes on upcoming releases will be added here_ +### Documentation + +#### Caller identity fields are described (#105) + +The dataclass identifying an MCP caller now says what each field holds. They +previously reached the rendered API reference as "Alias for field number 0" +or as a bare name carrying only its type. + ### Development #### CI actions updated to current majors