modelcontextprotocol / modelcontextprotocol/python-sdk

Improving how function docstring gets converted to tool's jsonschema for FastMCP

未关闭
#226 13 条评论 16 个 reaction 已指派 0 人 在 GitHub 查看

还没有人认领这个 Issue。

enhancement good first issue needs decision P2
主要语言
Python
星标
24.3k
派生
4k
平均合并
1 天 1 小时
30 天内合并 PR
31

描述

Is your feature request related to a problem? Please describe.
Tool descriptions are not parsed as expected from the function docstring when using FastMCP. This affects tool calling performance.

Currently, FastMCP does some function inspection to create the docstring here:

From my understanding, it creates a FuncMetadata model in pydantic which then gets converted to jsonschema.

Current behaviour:
If we have a tool such as:

def add_numbers(a: float, b: float) -> float:
    """
    Adds two numbers and returns the result.

    Args:
        a (float): The first number.
        b (float): The second number.

    Returns:
        float: The sum of a and b.
    """
    return a + b

it gets parsed into:

>>> func_arg_metadata = func_metadata(add_numbers)
>>> parameters = func_arg_metadata.arg_model.model_json_schema()
>>> parameters
{'properties': {'a': {'title': 'A', 'type': 'number'}, 'b': {'title': 'B', 'type': 'number'}}, 'required': ['a', 'b'], 'title': 'add_numbersArguments', 'type': 'object'}

>>> add_numbers.__doc__  
'\nAdds two numbers and returns the result.\n\nArgs:\n    a (float): The first number.\n    b (float): The second number.\n\nReturns:\n    float: The sum of a and b.\n'

Describe the solution you'd like
It'd be nicer to follow one of the python docstring styles and parse out the argument descriptions from the docstring.

{
  "name": "add_numbers",
  "description": "Adds two numbers and returns the sum.",
  "parameters": {
    "type": "object",
    "properties": {
      "a": {
        "type": "number",
        "description": "The first number to add."
      },
      "b": {
        "type": "number",
        "description": "The second number to add."
      }
    },
    "required": ["a", "b"]
  }
}

Describe alternatives you've considered
we used to do this in a previous python version of goose: https://github.com/block/goose/blob/eccb1b22614f39b751db4e5efd73d728d9ca40fc/packages/exchange/src/exchange/utils.py#L82-L107

here are some test examples: https://github.com/block/goose/blob/eccb1b22614f39b751db4e5efd73d728d9ca40fc/packages/exchange/tests/test_utils.py#L32-L136

Additional context
I am happy to add this in - wanted to post this first to check that you're okay with enforcing a docstring style ("google", "numpy", "sphinx") & adding griffe as a dependency.

贡献指南

打开贡献指南

从这里开始

  1. 先读完整个 Issue,再读项目的贡献指南。
  2. 在 Issue 下留言说明你要接手 —— 这能避免两个人做同样的事。
  3. Fork 仓库,在一个分支上完成修改。
  4. 提交 Pull Request,并在描述里引用这个 Issue 编号。

调研方向

从 src/mcp/server/fastmcp/tools/base.py 和 src/mcp/server/fastmcp/utilities/func_metadata.py 开始,然后查看链接的 Goose 工具和测试示例。首先确定哪种 docstring 样式和解析器依赖是可接受的。完成的标准是,受支持的参数和函数描述会出现在生成的 JSON schema 中,并且测试覆盖所选样式。

由索引模型根据 Issue 内容生成。

评估

技术栈
python
领域
api, backend-api-design
Issue 类型
功能
难度
4/5
预计耗时
3-5 天
活跃度
冷清
描述清晰度
基本清楚
新手友好度
52/100

把新 issue 发到你的邮箱

精选适合新手参与的 GitHub issue 摘要。