feat: propagate docstring parameter descriptions to JSON Schema

Parse Python docstrings (Google, NumPy, and Sphinx styles) using griffe
to extract parameter descriptions, then include them in the generated
JSON Schema via Field(description=...).

This addresses issue #226: when a tool function has a docstring with an
Args/Parameters section, the descriptions are now automatically added to
the JSON Schema output, giving LLMs richer context about each parameter.

Key design decisions:
- Tries all three docstring styles (Google, NumPy, Sphinx) and picks the
  one that yields the most parameter descriptions
- Annotated Field descriptions take precedence over docstring descriptions
- Gracefully degrades: no docstring or unrecognized format → no descriptions
- Suppresses griffe's noisy type-annotation warnings (we only need descriptions)

Signed-off-by: zsxh1990 <zsxh1990@gmail.com>
Signed-off-by: zsxh1990 <445655361@qq.com>

Author: zsxh1990

pyproject.toml

@@ -144,6 +144,7 @@ dependencies = [
     "typing-extensions>=4.13.0",
     "typing-inspection>=0.4.1",
     "opentelemetry-api>=1.28.0",
+    "griffe>=1.0.0",
 ]
 
 [project.urls]

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

@@ -1,6 +1,7 @@
 import functools
 import inspect
 import json
+import logging
 import sys
 from collections.abc import Awaitable, Callable, Sequence
 from itertools import chain
@@ -9,7 +10,9 @@
 
 import anyio
 import anyio.to_thread
+import griffe
 import pydantic_core
+from griffe import DocstringSectionParameters
 from mcp_types import CallToolResult, ContentBlock, InputRequiredResult, TextContent
 from pydantic import (
     BaseModel,
@@ -36,9 +39,55 @@
 from mcp.server.mcpserver.utilities.logging import get_logger
 from mcp.server.mcpserver.utilities.types import Audio, Image
 
+# Suppress griffe's "No type or annotation" warnings — we parse descriptions, not types
+logging.getLogger("griffe").setLevel(logging.ERROR)
+
 logger = get_logger(__name__)
 
 
+def _parse_docstring_params(func: Callable[..., Any]) -> dict[str, str]:
+    """Parse parameter descriptions from a function's docstring.
+
+    Supports Google, NumPy, and Sphinx docstring styles via griffe.
+    Tries all styles and returns the one that yields the most parameter descriptions.
+
+    Returns:
+        A dict mapping parameter names to their descriptions.
+    """
+    docstring = func.__doc__
+    if not docstring:
+        return {}
+
+    docstring_obj = griffe.Docstring(docstring)
+    best: dict[str, str] = {}
+
+    for parser in (griffe.parse_google, griffe.parse_numpy, griffe.parse_sphinx):
+        try:
+            parsed = parser(docstring_obj)
+            found: dict[str, str] = {}
+            for section in parsed:
+                if isinstance(section, DocstringSectionParameters):
+                    for param in section.value:
+                        if param.description:
+                            found[param.name] = param.description
+            if len(found) > len(best):
+                best = found
+        except Exception:
+            continue
+
+    return best
+
+
+def _has_field_description(annotation: Any) -> bool:
+    """Check if a type annotation already contains a Pydantic Field with a description."""
+    if get_origin(annotation) is Annotated:
+        args = get_args(annotation)
+        for arg in args[1:]:
+            if isinstance(arg, FieldInfo) and arg.description is not None:
+                return True
+    return False
+
+
 def _is_input_required_type(obj: Any) -> bool:
     return isinstance(obj, type) and issubclass(obj, InputRequiredResult)
 
@@ -293,6 +342,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
+    param_descriptions = _parse_docstring_params(func)
     dynamic_pydantic_model_params: dict[str, Any] = {}
     for param in params.values():
         if param.name.startswith("_"):  # pragma: no cover
@@ -303,6 +353,9 @@ def func_metadata(
         annotation = param.annotation if param.annotation is not inspect.Parameter.empty else Any
         field_name = param.name
         field_kwargs: dict[str, Any] = {}
+        # Only add docstring description if the annotation doesn't already have a Field description
+        if param.name in param_descriptions and not _has_field_description(annotation):
+            field_kwargs["description"] = param_descriptions[param.name]
         field_metadata: list[Any] = []
 
         if param.annotation is inspect.Parameter.empty:

tests/server/mcpserver/test_func_metadata.py

@@ -1458,3 +1458,162 @@ def fn() -> StepA | StepB: ...  # pragma: no branch
 
     meta = func_metadata(fn)
     assert meta.output_schema is None
+
+
+# Tests for docstring → JSON Schema description propagation (issue #226)
+
+
+def test_google_style_docstring_descriptions():
+    """Test that Google-style docstrings are parsed and descriptions added to schema."""
+
+    def func_google_style(name: str, age: int, verbose: bool = False) -> str:
+        """A function with Google-style docstring.
+
+        Args:
+            name: The person's full name.
+            age: Age in years.
+            verbose: Whether to print verbose output.
+
+        Returns:
+            A greeting string.
+        """
+        return f"Hello {name}, you are {age}"
+
+    meta = func_metadata(func_google_style)
+    schema = meta.arg_model.model_json_schema(by_alias=True)
+
+    assert schema["properties"]["name"]["description"] == "The person's full name."
+    assert schema["properties"]["age"]["description"] == "Age in years."
+    assert schema["properties"]["verbose"]["description"] == "Whether to print verbose output."
+
+
+def test_numpy_style_docstring_descriptions():
+    """Test that NumPy-style docstrings are parsed and descriptions added to schema."""
+
+    def func_numpy_style(filename: str, encoding: str = "utf-8") -> str:
+        """A function with NumPy-style docstring.
+
+        Parameters
+        ----------
+        filename : str
+            Path to the file to read.
+        encoding : str, optional
+            File encoding. Defaults to utf-8.
+
+        Returns
+        -------
+        str
+            File contents.
+        """
+        return f"Reading {filename}"
+
+    meta = func_metadata(func_numpy_style)
+    schema = meta.arg_model.model_json_schema(by_alias=True)
+
+    assert schema["properties"]["filename"]["description"] == "Path to the file to read."
+    assert schema["properties"]["encoding"]["description"] == "File encoding. Defaults to utf-8."
+
+
+def test_sphinx_style_docstring_descriptions():
+    """Test that Sphinx-style docstrings are parsed and descriptions added to schema."""
+
+    def func_sphinx_style(url: str, timeout: int = 30) -> str:
+        """A function with Sphinx-style docstring.
+
+        :param url: The URL to fetch.
+        :param timeout: Request timeout in seconds.
+        :returns: Response text.
+        """
+        return f"Fetching {url}"
+
+    meta = func_metadata(func_sphinx_style)
+    schema = meta.arg_model.model_json_schema(by_alias=True)
+
+    assert schema["properties"]["url"]["description"] == "The URL to fetch."
+    assert schema["properties"]["timeout"]["description"] == "Request timeout in seconds."
+
+
+def test_no_docstring():
+    """Test that functions without docstrings still work correctly."""
+
+    def func_no_doc(x: int, y: str) -> str:  # pragma: no cover
+        return f"{x}: {y}"
+
+    meta = func_metadata(func_no_doc)
+    schema = meta.arg_model.model_json_schema(by_alias=True)
+
+    # No description should be added
+    assert "description" not in schema["properties"]["x"]
+    assert "description" not in schema["properties"]["y"]
+
+
+def test_docstring_no_args_section():
+    """Test docstrings without an Args section don't add descriptions."""
+
+    def func_no_args_section(x: int) -> str:
+        """Just a summary, no args section."""
+        return str(x)
+
+    meta = func_metadata(func_no_args_section)
+    schema = meta.arg_model.model_json_schema(by_alias=True)
+
+    assert "description" not in schema["properties"]["x"]
+
+
+def test_docstring_partial_args():
+    """Test that only documented parameters get descriptions."""
+
+    def func_partial(a: int, b: str, c: float) -> str:
+        """Function with partial docstring.
+
+        Args:
+            a: First parameter.
+            c: Third parameter.
+        """
+        return f"{a}{b}{c}"
+
+    meta = func_metadata(func_partial)
+    schema = meta.arg_model.model_json_schema(by_alias=True)
+
+    assert schema["properties"]["a"]["description"] == "First parameter."
+    assert "description" not in schema["properties"]["b"]
+    assert schema["properties"]["c"]["description"] == "Third parameter."
+
+
+def test_docstring_with_skip_names():
+    """Test that docstring parsing works correctly with skip_names."""
+
+    def func_skip(name: str, secret: str, verbose: bool = False) -> str:
+        """Function with skip.
+
+        Args:
+            name: User name.
+            secret: Secret to skip.
+            verbose: Be verbose.
+        """
+        return name
+
+    meta = func_metadata(func_skip, skip_names=["secret"])
+    schema = meta.arg_model.model_json_schema(by_alias=True)
+
+    assert "secret" not in schema["properties"]
+    assert schema["properties"]["name"]["description"] == "User name."
+    assert schema["properties"]["verbose"]["description"] == "Be verbose."
+
+
+def test_field_description_preserved_over_docstring():
+    """Test that Annotated Field descriptions take precedence over docstring descriptions."""
+
+    def func_field_priority(name: Annotated[str, Field(description="Field description")]) -> str:
+        """Function.
+
+        Args:
+            name: Docstring description.
+        """
+        return name
+
+    meta = func_metadata(func_field_priority)
+    schema = meta.arg_model.model_json_schema(by_alias=True)
+
+    # Field description should be preserved (Pydantic uses it directly)
+    assert schema["properties"]["name"]["description"] == "Field description"