Skip to content

Commit 5662071

Browse files
tonytony
committed
feat(docs[_ext]): Add {badge} role, use on safety page tables and lists
why: The safety page had plain text tier names — colored badges make tiers scannable at a glance while preserving copyable text. what: - Add {badge} role that renders a colored safety badge inline - Overview table: add Label column with {badge}`readonly` etc. - Tool tags list: prepend badge before each `code` tag name - Tool annotations table: add Label column with badges per row - Text tier names preserved in all locations for copyability
1 parent 5adb109 commit 5662071

2 files changed

Lines changed: 51 additions & 37 deletions

File tree

‎docs/_ext/fastmcp_autodoc.py‎

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -911,13 +911,27 @@ def _tool_role(
911911
return [node], []
912912

913913

914+
def _badge_role(
915+
name: str,
916+
rawtext: str,
917+
text: str,
918+
lineno: int,
919+
inliner: object,
920+
options: dict[str, object] | None = None,
921+
content: list[str] | None = None,
922+
) -> tuple[list[nodes.Node], list[nodes.system_message]]:
923+
"""Inline role ``:badge:`readonly``` → colored safety badge span."""
924+
return [_safety_badge(text.strip())], []
925+
926+
914927
def setup(app: Sphinx) -> ExtensionMetadata:
915928
"""Register the fastmcp_autodoc extension."""
916929
app.connect("builder-inited", _collect_tools)
917930
app.connect("doctree-read", _register_tool_labels)
918931
app.connect("doctree-resolved", _add_section_badges)
919932
app.connect("doctree-resolved", _resolve_tool_refs)
920933
app.add_role("tool", _tool_role)
934+
app.add_role("badge", _badge_role)
921935
app.add_directive("fastmcp-tool", FastMCPToolDirective)
922936
app.add_directive("fastmcp-tool-input", FastMCPToolInputDirective)
923937
app.add_directive("fastmcp-toolsummary", FastMCPToolSummaryDirective)

‎docs/topics/safety.md‎

Lines changed: 37 additions & 37 deletions
Original file line numberDiff line numberDiff line change
@@ -6,11 +6,11 @@ libtmux-mcp uses a three-tier safety system to control which tools are available
66

77
## Overview
88

9-
| Tier | Access | Use case |
10-
|------|--------|----------|
11-
| `readonly` | List, capture, search, info | Monitoring, browsing |
12-
| `mutating` (default) | + create, send_keys, rename, resize | Normal agent workflow |
13-
| `destructive` | + kill_server, kill_session, kill_window, kill_pane | Full control |
9+
| Tier | Label | Access | Use case |
10+
|------|-------|--------|----------|
11+
| `readonly` | {badge}`readonly` | List, capture, search, info | Monitoring, browsing |
12+
| `mutating` (default) | {badge}`mutating` | + create, send_keys, rename, resize | Normal agent workflow |
13+
| `destructive` | {badge}`destructive` | + kill_server, kill_session, kill_window, kill_pane | Full control |
1414

1515
## Configuration
1616

@@ -42,9 +42,9 @@ Set the safety tier via the `LIBTMUX_SAFETY` environment variable:
4242

4343
Every tool is tagged with exactly one safety tier:
4444

45-
- `readonly` — Read-only operations that don't modify tmux state
46-
- `mutating` — Operations that create, modify, or send input to tmux objects
47-
- `destructive` — Operations that destroy tmux objects (kill commands)
45+
- {badge}`readonly` `readonly` — Read-only operations that don't modify tmux state
46+
- {badge}`mutating` `mutating` — Operations that create, modify, or send input to tmux objects
47+
- {badge}`destructive` `destructive` — Operations that destroy tmux objects (kill commands)
4848

4949
### Fail-closed design
5050

@@ -65,32 +65,32 @@ These protections use the `TMUX_PANE` environment variable to detect the caller'
6565

6666
Each tool carries MCP tool annotations that hint at its behavior:
6767

68-
| Tool | Tier | readOnly | destructive | idempotent |
69-
|------|------|----------|-------------|------------|
70-
| `list_sessions` | readonly | true | false | true |
71-
| `get_server_info` | readonly | true | false | true |
72-
| `list_windows` | readonly | true | false | true |
73-
| `list_panes` | readonly | true | false | true |
74-
| `capture_pane` | readonly | true | false | true |
75-
| `get_pane_info` | readonly | true | false | true |
76-
| `search_panes` | readonly | true | false | true |
77-
| `wait_for_text` | readonly | true | false | true |
78-
| `show_option` | readonly | true | false | true |
79-
| `show_environment` | readonly | true | false | true |
80-
| `create_session` | mutating | false | false | false |
81-
| `create_window` | mutating | false | false | false |
82-
| `split_window` | mutating | false | false | false |
83-
| `send_keys` | mutating | false | false | false |
84-
| `rename_session` | mutating | false | false | true |
85-
| `rename_window` | mutating | false | false | true |
86-
| `resize_pane` | mutating | false | false | true |
87-
| `resize_window` | mutating | false | false | true |
88-
| `set_pane_title` | mutating | false | false | true |
89-
| `clear_pane` | mutating | false | false | true |
90-
| `select_layout` | mutating | false | false | true |
91-
| `set_option` | mutating | false | false | true |
92-
| `set_environment` | mutating | false | false | true |
93-
| `kill_server` | destructive | false | true | false |
94-
| `kill_session` | destructive | false | true | false |
95-
| `kill_window` | destructive | false | true | false |
96-
| `kill_pane` | destructive | false | true | false |
68+
| Tool | Tier | Label | readOnly | destructive | idempotent |
69+
|------|------|-------|----------|-------------|------------|
70+
| `list_sessions` | readonly | {badge}`readonly` | true | false | true |
71+
| `get_server_info` | readonly | {badge}`readonly` | true | false | true |
72+
| `list_windows` | readonly | {badge}`readonly` | true | false | true |
73+
| `list_panes` | readonly | {badge}`readonly` | true | false | true |
74+
| `capture_pane` | readonly | {badge}`readonly` | true | false | true |
75+
| `get_pane_info` | readonly | {badge}`readonly` | true | false | true |
76+
| `search_panes` | readonly | {badge}`readonly` | true | false | true |
77+
| `wait_for_text` | readonly | {badge}`readonly` | true | false | true |
78+
| `show_option` | readonly | {badge}`readonly` | true | false | true |
79+
| `show_environment` | readonly | {badge}`readonly` | true | false | true |
80+
| `create_session` | mutating | {badge}`mutating` | false | false | false |
81+
| `create_window` | mutating | {badge}`mutating` | false | false | false |
82+
| `split_window` | mutating | {badge}`mutating` | false | false | false |
83+
| `send_keys` | mutating | {badge}`mutating` | false | false | false |
84+
| `rename_session` | mutating | {badge}`mutating` | false | false | true |
85+
| `rename_window` | mutating | {badge}`mutating` | false | false | true |
86+
| `resize_pane` | mutating | {badge}`mutating` | false | false | true |
87+
| `resize_window` | mutating | {badge}`mutating` | false | false | true |
88+
| `set_pane_title` | mutating | {badge}`mutating` | false | false | true |
89+
| `clear_pane` | mutating | {badge}`mutating` | false | false | true |
90+
| `select_layout` | mutating | {badge}`mutating` | false | false | true |
91+
| `set_option` | mutating | {badge}`mutating` | false | false | true |
92+
| `set_environment` | mutating | {badge}`mutating` | false | false | true |
93+
| `kill_server` | destructive | {badge}`destructive` | false | true | false |
94+
| `kill_session` | destructive | {badge}`destructive` | false | true | false |
95+
| `kill_window` | destructive | {badge}`destructive` | false | true | false |
96+
| `kill_pane` | destructive | {badge}`destructive` | false | true | false |

0 commit comments

Comments
 (0)