feat(docs[_ext]): add fastmcp_autodoc Sphinx extension for MCP tool docs#2
Merged
feat(docs[_ext]): add fastmcp_autodoc Sphinx extension for MCP tool docs#2
Conversation
tony
force-pushed
the
fastmcp-autodoc-extension
branch
from
5db9211 to
a716b50
Compare
tony
force-pushed
the
fastmcp-autodoc-extension
branch
from
fe75f57 to
91d60b4
Compare
tony
force-pushed
the
fastmcp-autodoc-extension
branch
from
91d60b4 to
33d88c6
Compare
why: MCP tool documentation was hand-maintained and prone to drift from source code. Tool parameter tables, safety tiers, and descriptions need to stay in sync with the actual function signatures and docstrings. what: Extension (docs/_ext/fastmcp_autodoc.py): - fastmcp-tool directive: autodoc a single tool as a ToC-visible section with safety badge (floated top-right), one-line description from docstring - fastmcp-tool-input directive: emit parameter table + return type, placed after hand-written judgment content (Use when / Avoid when) - fastmcp-toolsummary directive: grouped summary tables by safety tier (Inspect / Act / Destroy) with cross-reference links - Collects all 27 tools from source at build time via mock FastMCP collector - Strips | None from optional parameter types - Splits union types into comma-separated <code> elements for clean wrapping - Cleans up t.Literal[...] and Literal[...] to bare quoted values - Parses RST inline markup in docstring descriptions via state.inline_text() - All output via docutils node API — tables, sections, badges are proper nodes Tool area pages (docs/tools/): - sessions.md: list_sessions, get_server_info, create_session, rename_session, kill_session, kill_server - windows.md: list_windows, list_panes, create_window, split_window, rename_window, select_layout, resize_window, kill_window - panes.md: capture_pane, get_pane_info, search_panes, wait_for_text, send_keys, set_pane_title, clear_pane, resize_pane, kill_pane - options.md: show_option, show_environment, set_option, set_environment - Each tool has: Use when / Avoid when, Side effects, JSON example, auto-generated Input table at section end Scan layer (docs/tools/index.md): - Hand-written card grid grouped by Inspect / Act / Destroy - Links to area pages for each of the 27 tools CSS (docs/_static/css/custom.css): - .tool-safety-badge floats badge top-right, drops to own row on narrow screens Tests (tests/docs/_ext/test_fastmcp_autodoc.py): - 28 tests covering: docstring parsing, annotation formatting, Literal cleanup, union type splitting, table construction, badge classes, tool collection, parameter extraction, integration with real libtmux_mcp tools
tony
force-pushed
the
fastmcp-autodoc-extension
branch
from
33d88c6 to
686d27b
Compare
Codecov Report❌ Patch coverage is Additional details and impacted files@@ Coverage Diff @@
## main #2 +/- ##
==========================================
- Coverage 79.71% 75.12% -4.60%
==========================================
Files 17 20 +3
Lines 779 1202 +423
Branches 93 156 +63
==========================================
+ Hits 621 903 +282
- Misses 121 256 +135
- Partials 37 43 +6 ☔ View full report in Codecov by Sentry. 🚀 New features to boost your workflow:
|
tony
force-pushed
the
fastmcp-autodoc-extension
branch
from
686d27b to
0bdae82
Compare
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Custom Sphinx extension that autodocuments FastMCP tools from source code using the docutils node API.
What it does
fastmcp-tooldirective: creates a ToC-visible section with safety badge (readonly/mutating/destructive), one-line description parsed from the function's docstringfastmcp-tool-inputdirective: emits parameter table + return type, designed to be placed after hand-written judgment contentfastmcp-toolsummarydirective: generates grouped summary tables by safety tier (Inspect / Act / Destroy)Key features
libtmux_mcp.toolsat build time via mock FastMCP collector| Nonefrom optional parameter types<code>elements for clean wrappingt.Literal[...]to bare quoted values, each in its own<code>Tool area pages
Each tool has: Use when / Avoid when, Side effects, JSON example, auto-generated Input table.
Test plan
tests/docs/_ext/test_fastmcp_autodoc.py)ruff checkcleanruff formatcleanjust htmlbuilds successfully