feat: extract parameter descriptions from docstrings into JSON schema

Parses Google, NumPy, and Sphinx docstring styles with auto-detection.
Injects descriptions into the Pydantic Field used for JSON schema
generation, so tools get richer metadata for LLM consumption.

Explicit Field(description=...) annotations always take precedence.

Closes #226

Author: Thibbeer

src/mcp/server/mcpserver/utilities/docstring_parser.py

@@ -0,0 +1,119 @@
+"""Extract parameter descriptions from function docstrings.
+
+Auto-detects Google, NumPy, and Sphinx styles.
+"""
+
+from __future__ import annotations
+
+import re
+
+_GOOGLE_SECTION_RE = re.compile(
+    r"(?:Args|Arguments|Parameters)\s*:\s*\n"
+    r"(.*?)"
+    r"(?:\n\s*\n|\n\s*(?:Returns|Raises|Yields|Note|Example)|\Z)",
+    re.DOTALL,
+)
+_GOOGLE_PARAM_RE = re.compile(r"^(\s+)(\w+)\s*(?:\([^)]*\))?\s*:\s*(.*)")
+
+_NUMPY_SECTION_RE = re.compile(
+    r"Parameters\s*\n\s*-{3,}\s*\n"
+    r"(.*?)"
+    r"(?:\n\s*(?:Returns|Raises|Yields|See Also|Note|Example)\s*\n\s*-{3,}|\Z)",
+    re.DOTALL,
+)
+_NUMPY_PARAM_RE = re.compile(r"^\s*(\w+)\s*:\s*.*")
+
+_SPHINX_PARAM_RE = re.compile(
+    r":param\s+(?:\w+\s+)?(\w+)\s*:\s*(.+?)(?=\n\s*:|$)",
+    re.DOTALL,
+)
+
+_NUMPY_SEPARATOR_RE = re.compile(r"-{3,}")
+
+
+def parse_docstring_params(docstring: str | None) -> dict[str, str]:
+    """Extract parameter name→description mapping from a docstring."""
+    if not docstring:
+        return {}
+
+    if _NUMPY_SEPARATOR_RE.search(docstring):
+        parsers = (_parse_numpy, _parse_google, _parse_sphinx)
+    else:
+        parsers = (_parse_google, _parse_sphinx, _parse_numpy)
+
+    for parser in parsers:
+        result = parser(docstring)
+        if result:
+            return result
+    return {}
+
+
+def _collect_indented_block(
+    lines: list[str],
+    param_re: re.Pattern[str],
+    *,
+    extract_desc_from_header: bool = True,
+) -> dict[str, str]:
+    """Walk *lines* and collect param→description pairs.
+
+    A parameter header is any line matching *param_re* whose indent is
+    ≤ the previous header's indent.  Everything indented deeper is treated
+    as a continuation of the current description.
+    """
+    params: dict[str, str] = {}
+    current_param: str | None = None
+    desc_parts: list[str] = []
+    header_indent = 999
+
+    for line in lines:
+        stripped = line.rstrip()
+        if not stripped:
+            continue
+
+        indent = len(line) - len(line.lstrip())
+        m = param_re.match(line)
+
+        if m and indent <= header_indent:
+            if current_param is not None:
+                params[current_param] = " ".join(desc_parts).strip()
+
+            header_indent = indent
+            current_param = m.group(2) if m.lastindex and m.lastindex >= 2 else m.group(1)
+
+            if extract_desc_from_header and m.lastindex and m.lastindex >= 3:
+                tail = m.group(3).strip()
+                desc_parts = [tail] if tail else []
+            else:
+                desc_parts = []
+        elif current_param is not None and indent > header_indent:
+            desc_parts.append(stripped.strip())
+
+    if current_param is not None:
+        params[current_param] = " ".join(desc_parts).strip()
+    return params
+
+
+def _parse_google(docstring: str) -> dict[str, str]:
+    match = _GOOGLE_SECTION_RE.search(docstring)
+    if not match:
+        return {}
+    return _collect_indented_block(
+        match.group(1).split("\n"),
+        _GOOGLE_PARAM_RE,
+        extract_desc_from_header=True,
+    )
+
+
+def _parse_numpy(docstring: str) -> dict[str, str]:
+    match = _NUMPY_SECTION_RE.search(docstring)
+    if not match:
+        return {}
+    return _collect_indented_block(
+        match.group(1).split("\n"),
+        _NUMPY_PARAM_RE,
+        extract_desc_from_header=False,
+    )
+
+
+def _parse_sphinx(docstring: str) -> dict[str, str]:
+    return {m.group(1): " ".join(m.group(2).split()).strip() for m in _SPHINX_PARAM_RE.finditer(docstring)}

src/mcp/server/mcpserver/utilities/func_metadata.py

@@ -22,6 +22,7 @@
 )
 
 from mcp.server.mcpserver.exceptions import InvalidSignature
+from mcp.server.mcpserver.utilities.docstring_parser import parse_docstring_params
 from mcp.server.mcpserver.utilities.logging import get_logger
 from mcp.server.mcpserver.utilities.types import Audio, Image
 from mcp.types import CallToolResult, ContentBlock, TextContent
@@ -215,6 +216,7 @@ def func_metadata(
         # model_rebuild right before using it 🤷
         raise InvalidSignature(f"Unable to evaluate type annotations for callable {func.__name__!r}") from e
     params = sig.parameters
+    docstring_params = parse_docstring_params(func.__doc__)
     dynamic_pydantic_model_params: dict[str, Any] = {}
     for param in params.values():
         if param.name.startswith("_"):  # pragma: no cover
@@ -227,6 +229,11 @@ def func_metadata(
         field_kwargs: dict[str, Any] = {}
         field_metadata: list[Any] = []
 
+        # Add description from docstring if available and not already
+        # provided via Annotated[..., Field(description=...)]
+        if param.name in docstring_params and not _has_field_description(annotation):
+            field_kwargs["description"] = docstring_params[param.name]
+
         if param.annotation is inspect.Parameter.empty:
             field_metadata.append(WithJsonSchema({"title": param.name, "type": "string"}))
         # Check if the parameter name conflicts with BaseModel attributes
@@ -489,6 +496,20 @@ class DictModel(RootModel[dict_annotation]):
     return DictModel
 
 
+def _has_field_description(annotation: Any) -> bool:
+    """Check if an annotation already has a Field with a description.
+
+    This avoids overwriting explicit Field(description=...) with
+    a docstring-derived description.
+    """
+    if get_origin(annotation) is not Annotated:
+        return False
+    for arg in get_args(annotation):
+        if isinstance(arg, FieldInfo) and arg.description is not None:
+            return True
+    return False
+
+
 def _convert_to_content(result: Any) -> Sequence[ContentBlock]:
     """Convert a result to a sequence of content objects.
 

tests/server/mcpserver/test_docstring_parser.py

@@ -0,0 +1,162 @@
+"""Tests for docstring parameter description parsing."""
+
+from typing import Annotated
+
+import pytest
+from pydantic import Field
+
+from mcp.server.mcpserver.utilities.docstring_parser import parse_docstring_params
+from mcp.server.mcpserver.utilities.func_metadata import func_metadata
+
+
+class TestGoogleStyle:
+    def test_basic(self):
+        doc = """Do something.
+
+        Args:
+            name: The name of the thing.
+            count: How many times.
+        """
+        assert parse_docstring_params(doc) == {
+            "name": "The name of the thing.",
+            "count": "How many times.",
+        }
+
+    def test_with_type_annotations(self):
+        doc = """Do something.
+
+        Args:
+            name (str): The name of the thing.
+            count (int): How many times.
+        """
+        assert parse_docstring_params(doc) == {
+            "name": "The name of the thing.",
+            "count": "How many times.",
+        }
+
+    def test_multiline_description(self):
+        doc = """Do something.
+
+        Args:
+            name: The name of the thing.
+                This is a longer description
+                that spans multiple lines.
+            count: How many times.
+        """
+        result = parse_docstring_params(doc)
+        assert "longer description" in result["name"]
+        assert result["count"] == "How many times."
+
+    @pytest.mark.parametrize("keyword", ["Args", "Arguments", "Parameters"])
+    def test_section_keywords(self, keyword: str) -> None:
+        doc = f"""Do something.
+
+        {keyword}:
+            name: The name.
+        """
+        assert parse_docstring_params(doc) == {"name": "The name."}
+
+    def test_stops_at_returns(self):
+        doc = """Do something.
+
+        Args:
+            name: The name.
+
+        Returns:
+            The result.
+        """
+        assert parse_docstring_params(doc) == {"name": "The name."}
+
+
+class TestNumpyStyle:
+    def test_basic(self):
+        doc = """Do something.
+
+        Parameters
+        ----------
+        name : str
+            The name of the thing.
+        count : int
+            How many times.
+        """
+        assert parse_docstring_params(doc) == {
+            "name": "The name of the thing.",
+            "count": "How many times.",
+        }
+
+    def test_multiline(self):
+        doc = """Do something.
+
+        Parameters
+        ----------
+        name : str
+            The name of the thing.
+            More details here.
+        """
+        assert "More details" in parse_docstring_params(doc)["name"]
+
+
+class TestSphinxStyle:
+    def test_basic(self):
+        doc = """Do something.
+
+        :param name: The name of the thing.
+        :param count: How many times.
+        """
+        assert parse_docstring_params(doc) == {
+            "name": "The name of the thing.",
+            "count": "How many times.",
+        }
+
+    def test_with_type(self):
+        doc = """Do something.
+
+        :param str name: The name of the thing.
+        """
+        assert parse_docstring_params(doc) == {"name": "The name of the thing."}
+
+
+class TestEdgeCases:
+    @pytest.mark.parametrize("doc", [None, "", "Just a description."])
+    def test_returns_empty(self, doc: str | None) -> None:
+        assert parse_docstring_params(doc) == {}
+
+
+class TestFuncMetadataIntegration:
+    def test_descriptions_appear_in_schema(self):
+        def my_tool(name: str, count: int = 5) -> str:
+            """A tool.
+
+            Args:
+                name: The name to process.
+                count: Number of repetitions.
+            """
+            return name * count
+
+        schema = func_metadata(my_tool).arg_model.model_json_schema()
+        assert schema["properties"]["name"]["description"] == "The name to process."
+        assert schema["properties"]["count"]["description"] == "Number of repetitions."
+
+    def test_explicit_field_takes_precedence(self):
+        def my_tool(
+            name: Annotated[str, Field(description="Explicit")],
+            count: int = 5,
+        ) -> str:
+            """A tool.
+
+            Args:
+                name: Should be ignored.
+                count: From docstring.
+            """
+            return name * count
+
+        schema = func_metadata(my_tool).arg_model.model_json_schema()
+        assert schema["properties"]["name"]["description"] == "Explicit"
+        assert schema["properties"]["count"]["description"] == "From docstring."
+
+    def test_no_docstring(self):
+        def my_tool(name: str) -> str:
+            return name
+
+        schema = func_metadata(my_tool).arg_model.model_json_schema()
+        assert "name" in schema["properties"]