[Bug]: Inconsistent structured output wrapping and opt-out for typing.Dict and typing sequence generics in func_metadata

未關閉 適合新手
  • 哪裡不對？
#3,771 3 則留言 0 個 reaction 已指派 0 人 在 GitHub 檢視

維護者通常 1 天內回覆

還沒有人認領這個 Issue。

  • #3772 來自 @chauvuusvn —— 已關閉，未合併

評估

難度
2/5
預估耗時
1-3 小時
新手友好度
82/100
Issue 類型
缺陷
描述清晰度
描述清楚
活躍度
活躍
技術堆疊
python
領域
api, backend

研究方向

從src/mcp/server/mcpserver/utilities/func_metadata.py開始，閱讀_create_output_model()和func_metadata()，issue指出的兩處不一致就在這裡。檢查現有的回傳型別內省測試，並新增對不帶型別引數的typing.Dict、typing.List和typing.Tuple以及對應內建型別的測試涵蓋。完成標準是：不帶型別引數的typing.Dict會產生未包裝的物件結構描述，而不帶型別引數的typing序列會如描述所述選擇不使用結構化輸出。

由索引模型根據 Issue 內容生成。

描述

bug v1 v2
Initial Checks
Release line

2.x (current stable)

Description

In src/mcp/server/mcpserver/utilities/func_metadata.py, return type introspection handles built-in types differently from their unsubscripted typing generic counterparts (typing.Dict, typing.List, typing.Tuple).

Issue 1: typing.Dict is forcibly wrapped in {"result": ...} instead of top-level object

When a tool returns dict or dict[str, Any], _create_output_model sets wrap_output = False and derives a top-level JSON object schema:

elif type_annotation is dict:
    model = dict[str, Any]

However, when a tool is annotated with typing.Dict (unsubscripted), get_origin(typing.Dict) is dict while get_args(typing.Dict) is (). In _create_output_model():

if origin is dict:
    args = get_args(type_expr)
    if len(args) == 2 and args[0] is str:
        model = type_expr
    else:
        # dict with non-str keys needs wrapping
        model = _create_wrapped_model(func_name, original_annotation)
        wrap_output = True

Because len(args) == 0 != 2, it falls through to else (intended only for non-str keys like dict[int, str]). As a result:

  • dict: treated as top-level JSON object (wrap_output = False)
  • typing.Dict: unexpectedly wrapped into {"result": ...} (wrap_output = True)
Issue 2: typing.List and typing.Tuple bypass the opt-out gate

In func_metadata():

if structured_output is None and (return_type_expr in (list, tuple) or _returns_content(return_type_expr)):
    return FuncMetadata(arg_model=arguments_model)

Because typing.List is not list (typing.List in (list, tuple) evaluates to False), tools annotated with -> typing.List or -> typing.Tuple fail to opt out and are forced through _create_output_model(), generating an unwanted wrapper schema { "result": typing.List }.

Example Code
import typing
from mcp.server.mcpserver.utilities.func_metadata import func_metadata

def tool_built_in_dict() -> dict:
    return {"status": "ok"}

def tool_typing_dict() -> typing.Dict:
    return {"status": "ok"}

def tool_built_in_list() -> list:
    return ["a", "b"]

def tool_typing_list() -> typing.List:
    return ["a", "b"]

meta_bi_dict = func_metadata(tool_built_in_dict)
meta_ty_dict = func_metadata(tool_typing_dict)
meta_bi_list = func_metadata(tool_built_in_list)
meta_ty_list = func_metadata(tool_typing_list)

# Inconsistent wrapping:
print("dict wrap_output:", meta_bi_dict.wrap_output)          # False
print("typing.Dict wrap_output:", meta_ty_dict.wrap_output)    # True (Expected: False)

# Inconsistent opt-out:
print("list schema:", meta_bi_list.output_schema)              # None
print("typing.List schema:", meta_ty_list.output_schema)        # {'type': 'object', 'properties': {'result': ...}} (Expected: None)
Proposed Fix
  1. In _create_output_model():
elif origin is dict:
    args = get_args(type_expr)
    if len(args) == 2 and args[0] is str:
        model = type_expr
    elif len(args) == 0:
        # Bare typing.Dict is equivalent to bare dict
        model = dict[str, Any]
    else:
        model = _create_wrapped_model(func_name, original_annotation)
        wrap_output = True
  1. In func_metadata():
if structured_output is None and (
    return_type_expr in (list, tuple, typing.List, typing.Tuple) or _returns_content(return_type_expr)
):
    return FuncMetadata(arg_model=arguments_model)
Version

Python 3.10+, MCP Python SDK 2.x

主要語言
Python
星號
24.7k
分支
4.1k
平均合併
18 小時 27 分鐘
30 天內合併 PR
15

環境準備

從這裡開始

  1. 先讀完整個 Issue，再讀專案的貢獻指南。
  2. 在 Issue 下留言說明你要接手 —— 這能避免兩個人做同樣的事。
  3. Fork 儲存庫，在一個分支上完成修改。
  4. 送出 Pull Request，並在描述裡引用這個 Issue 編號。

modelcontextprotocol/python-sdk 的其他 Issue

查看 modelcontextprotocol/python-sdk 的全部 Issue

相似的 Issue

更多 Python Issue

把新 issue 寄到你的電子郵件信箱

精選適合新手參與的 GitHub issue 摘要。