Skip to content

πŸš€ The fast, Pythonic way to build MCP servers and clients.

Keep colon-terminated prose lines in docstring tool descriptions (#6372)

nate nowackc39aa6f5392f
diff --git a/fastmcp_slim/fastmcp/utilities/docstring_parsing.py b/fastmcp_slim/fastmcp/utilities/docstring_parsing.py
index c2b295fea..54fd854ba 100644
--- a/fastmcp_slim/fastmcp/utilities/docstring_parsing.py
+++ b/fastmcp_slim/fastmcp/utilities/docstring_parsing.py
@@ -16,6 +16,33 @@ from typing import Any
_PARSERS = ("google", "numpy", "sphinx")
+# Griffe's Google parser reads any unindented `word:` line followed by an
+# indented block as an admonition, so prose such as `if enabled:` or `Rules:`
+# parses the same way as `Note:`. Only the Google-style headings griffe leaves
+# as admonitions (Napoleon's section names with no griffe section kind) count
+# as structure that ends the free-form description.
+_SECTION_ADMONITIONS = frozenset(
+ {
+ "attention",
+ "caution",
+ "danger",
+ "error",
+ "example",
+ "hint",
+ "important",
+ "note",
+ "notes",
+ "raise",
+ "references",
+ "return",
+ "see-also",
+ "tip",
+ "todo",
+ "warning",
+ "yield",
+ }
+)
+
logger = logging.getLogger("griffe")
# Griffe warns about missing type annotations in docstrings, which is noisy
# and irrelevant β€” we only care about descriptions.
@@ -67,6 +94,9 @@ def parse_docstring(fn: Callable[..., Any]) -> ParsedDocstring:
for param in section.value:
parameters[param.name] = param.description
found_structured_section = True
+ elif section.kind == DocstringSectionKind.admonition:
+ if section.value.kind in _SECTION_ADMONITIONS:
+ found_structured_section = True
elif section.kind != DocstringSectionKind.text:
found_structured_section = True
diff --git a/tests/utilities/test_docstring_parsing.py b/tests/utilities/test_docstring_parsing.py
index 3f3768bc3..a17986bcf 100644
--- a/tests/utilities/test_docstring_parsing.py
+++ b/tests/utilities/test_docstring_parsing.py
@@ -5,6 +5,7 @@ from typing import Annotated
from pydantic import Field
+from fastmcp import Client, FastMCP
from fastmcp.tools.function_parsing import ParsedFunction
from fastmcp.utilities.docstring_parsing import parse_docstring
@@ -352,6 +353,48 @@ class TestEdgeCases:
parsed = parse_docstring(fn)
assert parsed.description == inspect.getdoc(fn)
+ def test_colon_line_in_prose_is_not_a_section(self):
+ def fn() -> str:
+ """Choose an execution mode.
+
+ if bSudoMode:
+ Elevated privileges
+ else:
+ Normal privileges
+ """
+ return "ok"
+
+ parsed = parse_docstring(fn)
+ assert parsed.description == inspect.getdoc(fn)
+ assert parsed.parameters == {}
+
+ def test_custom_heading_in_prose_is_not_a_section(self):
+ def fn() -> str:
+ """Run a command.
+
+ Rules:
+ - Never run as root.
+ - Prefer dry runs.
+
+ Report the exit code.
+ """
+ return "ok"
+
+ parsed = parse_docstring(fn)
+ assert parsed.description == inspect.getdoc(fn)
+
+ def test_note_section_excluded_no_params(self):
+ def fn() -> int:
+ """Do a thing.
+
+ Note:
+ Only call this once.
+ """
+ return 1
+
+ parsed = parse_docstring(fn)
+ assert parsed.description == "Do a thing."
+
def test_async_function(self):
async def fn(a: float) -> float:
"""Async summary.
@@ -625,6 +668,25 @@ class TestParsedFunctionIntegration:
p = ParsedFunction.from_function(status)
assert p.description == "Return current status."
+ async def test_colon_line_in_prose_reaches_tool_listing(self):
+ server = FastMCP("docstrings")
+
+ @server.tool
+ def choose_mode() -> str:
+ """Choose an execution mode.
+
+ if bSudoMode:
+ Elevated privileges
+ else:
+ Normal privileges
+ """
+ return "ok"
+
+ async with Client(server) as client:
+ tools = await client.list_tools()
+
+ assert tools[0].description == inspect.getdoc(choose_mode)
+
def test_callable_class_falls_back_to_call_description(self):
"""If the class has no docstring, fall back to __call__'s description."""