罗罗编程学习记录
本页内容 展开查看

04.7.18.2 工具、资源、提示与 Schema

所属:全栈开发面试题库 / 04 后端语言与运行时 / 04.7 Python / 04.7.18 FastMCP 服务端框架

覆盖范围

  • @mcp.tool 注册方式、同步与异步函数、函数签名到 JSON Schema 的生成流程
  • 基本类型、集合类型、Optional/Union/Enum/Literal 与 Pydantic 模型的 schema 映射
  • docstring、Field 描述与参数约束如何进入 schema
  • Context 注入:日志、进度上报、读取资源、会话信息
  • 工具返回值形态:文本内容块、结构化对象、媒体/二进制内容块与自定义序列化
  • @mcp.resource 静态资源、URI 模板、MIME 类型与订阅
  • @mcp.prompt 参数化模板、Message 返回与参数 schema
  • 动态注册/移除、标签过滤、重名冲突、长任务超时与取消、严格输入校验
  • schema 质量对客户端调用成功率的影响与版本敏感项

04.7.18.2-001 用 @mcp.tool 注册工具的基本写法是什么?

一句话结论

在普通 Python 函数上叠加 @mcp.tool 装饰器,函数即被注册为 MCP 工具:框架收集函数名、docstring、类型注解生成输入 schema,客户端通过 tools/call 调用。装饰器参数为 name=、description=、tags=、meta=、enabled=、annotations=、output_schema= 等;name 默认取函数名,description 默认取 docstring。

概念解释

  • 注册发生在模块加载/实例构造阶段,工具进入服务端内部清单。
  • 函数参数即工具入参,返回值经框架转换为内容块或结构化结果。
  • 工具名默认取函数名,也可在装饰器参数中显式指定。

原理流程

  1. 定义带类型注解与 docstring 的函数。
  2. 叠加 @mcp.tool,框架把函数包装为工具组件并登记。
  3. tools/list 输出工具元数据,tools/call 时按参数绑定执行函数。

代码或图示

from fastmcp import FastMCP

mcp = FastMCP("demo")

@mcp.tool
def multiply(a: float, b: float) -> float:
    """两个浮点数相乘。"""
    return a * b

常见误区

  • 装饰器后忘记保留函数定义:装饰器必须写在 def 上方,不能只调用一次装饰器函数而不包裹函数。
  • 工具名与其他工具重名:按重复注册策略处理,默认行为见冲突题。

追问

  • 装饰器能不传括号吗?答:@mcp.tool 与 @mcp.tool() 都可使用;需要传配置时用括号。
  • 工具可以在函数外程序化添加吗?答:可以,框架提供动态注册 API,见动态注册题。
  • 注册后函数还能直接调用吗?答:测试优先用内存内 client 经协议会话 call_tool 调用;核心计算可抽到内层函数直连复用。

04.7.18.2-002 同步函数与异步函数都能注册为工具吗?

一句话结论

可以。装饰器同时支持同步普通函数与 async def 异步函数:异步函数在事件循环中直接 await 执行;同步函数由 FastMCP 2.x 经线程池卸载执行,阻塞操作建议用 anyio.to_thread.run_sync。IO 密集工具优先写异步,避免阻塞事件循环。

概念解释

  • 异步工具:适合 httpx.AsyncClient、异步数据库驱动等非阻塞 IO。
  • 同步工具:适合纯计算或同步库调用;在异步框架中长时间阻塞会影响其他会话。
  • 框架负责调用约定转换,工具作者不必手写协程包装。

原理流程

  1. 注册时框架记录函数是否为协程函数。
  2. 调用阶段:协程函数直接 await;同步函数经线程池卸载执行。
  3. 返回值统一走同一套结果序列化路径。

代码或图示

@mcp.tool
def sync_add(a: int, b: int) -> int:
    return a + b

@mcp.tool
async def async_fetch(url: str) -> dict:
    import httpx
    async with httpx.AsyncClient() as client:
        resp = await client.get(url)
        return {"status": resp.status_code}

常见误区

  • 在异步工具里调用阻塞型同步库:阻塞事件循环,应改用异步驱动或把阻塞操作放到合适的执行器。
  • 以为同步工具会自动变成协程:注册不改函数本身,只是调用路径由框架管理。

追问

  • 同步阻塞调用会拖垮 HTTP 传输吗?答:长时间阻塞会占用事件循环或工作线程,影响并发会话,需控制耗时或换异步实现。
  • 工具内可以起后台任务吗?答:可以发起,但生命周期与取消需自行管理,不能依赖工具返回后任务仍被托管。
  • 异步工具异常如何返回?答:与同步工具一致,在框架边界捕获并转换为协议错误。

04.7.18.2-003 函数签名到 JSON Schema 的生成总流程是什么?

一句话结论

框架解析函数签名:逐个参数读取类型注解、默认值与 Field 约束,结合 docstring 生成 inputSchema 对象——type: object、properties 描述各参数、required 列出无默认值参数。返回类型用于推断输出形态;注解缺失则 schema 退化为宽松类型。

概念解释

  • 输入 schema 描述“客户端该传什么”,是客户端填参与校验的契约。
  • 类型注解是 schema 类型的主要来源;默认值决定必填与可选。
  • docstring 与参数说明补充人类可读描述,提升模型理解质量。

原理流程

  1. 反射函数签名,获取参数名、注解、默认值与种类。
  2. 把 Python 类型映射为 JSON Schema 类型与约束。
  3. 组装 properties、required 与描述,写入工具元数据供 tools/list 输出。

代码或图示

@mcp.tool
def create_user(name: str, age: int = 18) -> dict:
    """创建用户。"""
    return {"name": name, "age": age}
{
  "type": "object",
  "properties": {
    "name": {"type": "string"},
    "age": {"type": "integer", "default": 18}
  },
  "required": ["name"]
}

常见误区

  • 以为 schema 只看类型不看默认值:有无默认值直接决定参数是否必填。
  • 忽略返回类型注解:出参形态推断可能变宽松,结构化出参建议显式标注模型。

追问

  • schema 生成在什么时候完成?答:注册阶段解析签名,list 时输出;运行期不改签名。
  • 类型映射规则在哪里核对?答:对照 FastMCP 2.x 文档的类型到 schema 映射表与本地类型定义。
  • 手写 schema 能覆盖自动生成吗?答:输入 schema 由签名自动生成;输出结构可用装饰器 output_schema= 显式声明。

04.7.18.2-004 位置参数、关键字参数与默认值如何反映到 schema?

一句话结论

普通位置/关键字参数按名进入 properties;有默认值的参数标记为可选,无默认值进入 required。*args/**kwargs 这类可变参数的 schema 支持程度取决于框架实现,通常不建议在工具签名中使用;带默认值的参数在客户端未传时由函数默认值生效。

概念解释

  • 必填判定:参数无默认值且非 Context 注入参数,即进入 required。
  • 默认值写入 schema 的 default 字段,帮助客户端理解取值范围。
  • Context 类型参数由框架注入,不进入客户端可见的 arguments schema。

原理流程

  1. 遍历签名参数,跳过框架注入的 Context 参数。
  2. 检查默认值:有则可选并记录 default;无则加入 required。
  3. 类型注解映射为 properties 条目。

代码或图示

@mcp.tool
def order(sku: str, quantity: int = 1, note: str | None = None) -> dict:
    return {"sku": sku, "quantity": quantity, "note": note}

常见误区

  • 把 None 当必填值传:可选参数未传时使用函数默认值,不应要求客户端显式传 null。
  • 使用 **kwargs 聚合参数:schema 无法描述具体键,客户端填参失去约束。

追问

  • Context 参数为什么不出现在 schema?答:它由服务端按会话注入,不属于客户端入参契约。
  • 默认值会被 schema 校验覆盖吗?答:未传参数走默认值;显式传入的值按 schema 校验。
  • 必填参数缺失返回什么错误?答:参数无效错误,data 中可带缺失字段名。

04.7.18.2-005 类型注解缺失或为 Any 时 schema 退化成什么样?

一句话结论

注解缺失或标注为 Any 时,框架无法推出确定类型,schema 通常退化为不限制类型的宽松条目(或省略类型约束),客户端只能传任意 JSON 值。这会降低调用成功率:模型不知道该填字符串还是数字,参数校验也变弱。

概念解释

  • 宽松类型:schema 无 type 或类型约束很宽,校验形同虚设。
  • 风险:错误类型数据进入函数体,可能触发类型错误或下游异常。
  • 修复:补全具体类型注解,复杂结构用 Pydantic 模型描述。

原理流程

  1. 注册时读取参数注解,缺失/Any 走宽松映射分支。
  2. 生成的 schema 缺少明确类型与约束。
  3. 调用时校验宽松,错误参数直达函数体,异常概率上升。

代码或图示

# 不推荐:注解缺失
@mcp.tool
def guess(value) -> str:
    return str(value)

常见误区

  • 用 dict 注解代替内部结构模型:schema 只知道是对象,不知道有哪些字段,仍属宽松。
  • 认为运行时类型错误会被框架拦住:宽松注解下校验不拦截,错误会在函数体内抛出。

追问

  • 如何检查工具 schema 是否过宽?答:调用 tools/list 检查 inputSchema 的 type 与 properties 是否明确。
  • 退回 Any 后还能加约束吗?答:改用 Pydantic 模型类型或 Annotated + Field 补充约束。
  • 返回值也需要注解吗?答:建议标注,便于推断输出结构;无注解时按默认序列化处理。

04.7.18.2-006 基本类型 str/int/float/bool 如何映射为 schema?

一句话结论

str 映射为 type: string,int 为 integer,float 为 number,bool 为 boolean。数值范围、字符串格式等细化约束需通过 Field 或模型校验补充;基本类型映射是 schema 中最稳定、跨版本一致的部分。

概念解释

  • JSON Schema 没有整数与浮点数细分之外的数值子类型,Python int/float 对应 integer/number。
  • 日期时间、UUID 等不是基本 JSON 类型,需按字符串格式或模型序列化处理。
  • 类型映射与 Pydantic 2.x 的类型体系一致,字段约束写在模型或 Field 上。

原理流程

  1. 识别参数注解为 Python 基本类型。
  2. 查表映射到 JSON Schema 基本类型。
  3. 补充默认值、描述与约束字段。

代码或图示

@mcp.tool
def register(name: str, age: int, score: float, active: bool) -> dict:
    return {"name": name, "age": age, "score": score, "active": active}

常见误区

  • 把 float 注解成 int:schema 类型错误,小数入参会被校验拒绝或强制转换。
  • 用字符串承载枚举取值:应改用 Enum/Literal 在 schema 中列出可选值。

追问

  • int 能传布尔值吗?答:strict_input_validation=False(默认)宽松模式下 Pydantic 做兼容转换;严格模式拒绝类型不匹配。
  • 字符串长度约束写在哪里?答:Field(min_length=..., max_length=...) 或模型校验器。
  • number 类型能区分整数吗?答:JSON Schema 中 integer 是 number 的子类型,按注解分别生成。

04.7.18.2-007 list/dict/Optional/Union 注解如何映射 schema?

一句话结论

list[T] 映射为数组并声明元素类型;dict 或 dict[K, V] 映射为对象,值类型按注解补充;Optional[T] 等价于 T | None,schema 允许类型或 null;Union[A, B] 生成联合类型约束,按 Pydantic 导出的 JSON Schema 联合关键字表达。

概念解释

  • 容器类型:外层 JSON 类型 + 内层元素/值类型都要写清楚。
  • Optional:表示可空,不等于可省略;是否可选由有无默认值决定。
  • Union:多类型取值,客户端按 schema 选择合法形态。

原理流程

  1. 解析注解的容器外层与内层类型。
  2. 递归映射元素/值类型到 schema。
  3. 组合外层类型约束与可空/联合标记。

代码或图示

@mcp.tool
def summarize(tags: list[str], meta: dict, label: str | None = None) -> dict:
    return {"tags": tags, "meta": meta, "label": label}

常见误区

  • 写裸 list/dict 不带内层类型:元素/值 schema 退化为宽松对象。
  • 混淆 Optional 与可选参数:Optional[str] 仍可必填,只是允许 null;无默认值才是必填。

追问

  • Union 类型在 schema 中怎么表达?答:按 Pydantic 导出的 JSON Schema 联合关键字(anyOf/oneOf)表达。
  • 嵌套 list 支持递归映射吗?答:支持,如 list[list[int]] 递归生成数组层级。
  • dict 值结构不明确怎么办?答:用 Pydantic 模型替换裸 dict 描述字段。

04.7.18.2-008 Enum 与 Literal 如何生成枚举约束?

一句话结论

Enum 子类与 Literal[...] 注解会在 schema 中生成枚举取值约束,客户端只能在列出的候选值中选择。枚举值类型与成员值对应;Literal 直接列出字面量字符串或数值,适合取值封闭的字段。

概念解释

  • Enum:定义命名成员,序列化为成员值;适合语义分组与代码内引用。
  • Literal:轻量枚举,直接在注解中写死可选字面量。
  • 枚举约束降低模型乱填概率,比自由文本字段更可控。

原理流程

  1. 识别注解为 Enum 或 Literal。
  2. 提取所有合法取值写入 schema 的 enum 字段。
  3. 调用时校验取值是否在枚举内,不在则参数错误。

代码或图示

from enum import Enum
from typing import Literal

class Priority(str, Enum):
    LOW = "low"
    HIGH = "high"

@mcp.tool
def create_ticket(title: str, priority: Priority, channel: Literal["web", "app"]) -> dict:
    return {"title": title, "priority": priority.value, "channel": channel}

常见误区

  • Enum 成员值与序列化值不一致:客户端看到的是值,成员名不进入 schema。
  • 用自由字符串代替枚举:取值不受约束,模型可能造出未定义分类。

追问

  • 枚举能包含数值吗?答:可以,成员值类型与 schema 类型保持一致。
  • 新增枚举值需要改 schema 吗?答:需要,取值清单在注册时生成,扩展成员后客户端清单随之更新。
  • 枚举校验失败返回什么?答:参数无效错误,提示合法取值范围。

04.7.18.2-009 Pydantic Field 描述如何影响 schema 字段说明?

一句话结论

参数或模型字段上的 Field(description=..., min_length=..., ge=..., le=...) 会进入对应 schema 条目:描述补充人类可读说明,数值/长度约束成为校验条件。Pydantic 2.x 使用 Field 与模型注解,框架按模型 schema 提取这些信息。

概念解释

  • description:字段用途说明,展示在客户端填参提示中。
  • 约束:ge/le/gt/lt 数值范围,min_length/max_length 字符串长度,pattern 正则等。
  • 约束在参数校验阶段生效,不满足即返回参数错误。

原理流程

  1. 在函数参数或 Pydantic 模型字段上声明 Field。
  2. 框架解析模型 schema,提取描述与约束写入输入 schema。
  3. 调用时按约束校验入参,失败返回无效参数错误。

代码或图示

from pydantic import BaseModel, Field

class Item(BaseModel):
    name: str = Field(description="商品名称", min_length=1, max_length=64)
    price: float = Field(gt=0, description="单价,必须大于 0")

@mcp.tool
def add_item(item: Item) -> dict:
    return {"item": item.model_dump()}

常见误区

  • 约束只写在函数文档字符串里:docstring 不参与校验,必须落到 Field 或校验器。
  • 用旧版 Pydantic 1 写法:Pydantic 2.x 应使用 model_config、Field 与 field_validator,不再用旧配置类。

追问

  • Field 约束会出现在 tools/list 里吗?答:会,作为 inputSchema 条目的关键字段。
  • 约束冲突如何处理?答:以模型定义为准,注册时框架可暴露校验错误;测试应覆盖边界值。
  • 能给基本类型参数直接加 Field 吗?答:可以用 Annotated[str, Field(...)] 直接标注参数;复杂结构约束更适合模型字段承载。

04.7.18.2-010 参数级 description 与约束如何落地?

一句话结论

参数说明可来自 docstring 的参数段落、Field 描述或装饰器显式描述;数值范围、长度、正则等硬约束必须落在 schema 可校验的位置(Field/模型校验器),仅写进文档字符串不会被强制校验。清晰的参数说明直接影响模型填参正确率。

概念解释

  • 说明来源:装饰器 description= 显式参数优先;未传时取 docstring 首段;字段级描述来自 Field(description=...)。
  • 硬约束:能机器校验的条件写成 schema 约束;业务规则在函数内校验。
  • 说明应写清单位、取值范围、格式与示例,避免模糊形容词。

原理流程

  1. 在签名/模型上补类型、Field 约束与说明文本。
  2. 框架生成带描述与约束的 inputSchema。
  3. 客户端展示说明并按约束校验;函数内补充领域规则校验。

代码或图示

from typing import Annotated

@mcp.tool
def estimate(days: Annotated[int, Field(ge=1, le=365, description="预估天数,1 到 365")]) -> dict:
    """按天数估算成本。"""
    return {"days": days}

常见误区

  • 描述写“大概”“相关”等模糊词:模型无法据此填参,应给具体范围与格式。
  • 把业务必填校验推给 schema:跨表存在性、状态合法等规则只能在函数内校验。

追问

  • docstring 参数段如何被解析?答:FastMCP 按约定格式提取参数名与说明;字段级描述建议同时写在 Field(description=...) 以保证稳定。
  • 约束失败的 data 里带什么?答:字段名、约束类型与实际值,便于客户端修正。
  • 参数说明过长有问题吗?答:过长占用客户端上下文,应简明分点。

04.7.18.2-011 docstring 如何成为工具 description?

一句话结论

函数 docstring 的首段摘要默认成为工具 description,进入 tools/list 的工具元数据,帮助模型理解工具用途。装饰器显式传入的描述可覆盖 docstring;description 应说明“做什么、适用场景、注意事项”,而不是复述函数名。

概念解释

  • 首段:通常取 docstring 第一个自然段作为工具描述。
  • 覆盖优先级:装饰器 description= 显式参数优先于 docstring。
  • 好的 description 包含动作对象、输入含义与返回预期,差的描述只写“处理数据”。

原理流程

  1. 注册函数时读取 docstring,提取摘要段落。
  2. 生成工具元数据时填入 description 字段。
  3. 客户端把描述展示给用户或并入模型上下文用于选工具。

代码或图示

@mcp.tool
def search_orders(keyword: str) -> list[dict]:
    """按关键字搜索工单,返回匹配的工单摘要列表。

    keyword: 工单标题或编号片段,不区分大小写。
    """
    return [{"keyword": keyword}]

常见误区

  • docstring 写成实现细节流水账:模型需要的是用途与边界,不是内部步骤。
  • 工具 description 与参数说明混写:工具级摘要与字段级说明分层放置。

追问

  • 没有 docstring 会怎样?答:description 为空或回退函数名,模型理解质量下降。
  • 描述能运行期改吗?答:注册后清单以注册时元数据为准,动态修改需框架支持。
  • 装饰器如何显式覆盖描述?答:装饰器 description= 参数传入描述字符串;显式传入时忽略 docstring。

04.7.18.2-012 docstring 中参数说明(Args 段)的解析规则是什么?

一句话结论

部分框架会解析 docstring 的参数段落(如 Args/Parameters 段),把每个参数的说明提取到对应 schema 字段描述;解析格式支持程度随版本不同,参数说明的可靠来源仍建议配合 Field 或模型描述。未被解析的段落只作为普通文本保留,不进 schema。

概念解释

  • 常见约定:参数名后跟冒号与说明文字,按行对应函数参数。
  • 解析依赖 docstring 格式规整:缩进、冒号、名称匹配不一致时可能落空。
  • 版本差异:旧版与新版解析器行为可能不同,关键描述不要只依赖 docstring 段。

原理流程

  1. 注册时解析 docstring 结构,识别参数段落。
  2. 按参数名匹配签名参数,写入字段描述。
  3. 无法匹配的段落忽略或保留在工具描述中。

代码或图示

@mcp.tool
def convert(amount: str, currency: str) -> dict:
    """换算金额。

    Args:
        amount: 待换算金额字符串,含千分位分隔符。
        currency: 目标货币代码,如 CNY、USD。
    """
    return {"amount": amount, "currency": currency}

常见误区

  • 参数名在 docstring 里写错:解析匹配不上,字段描述为空。
  • 把约束条件写进 Args 文字:文字不参与校验,硬约束仍需 Field/校验器。

追问

  • 解析格式支持 Google 风格还是 reST 风格?答:FastMCP 2.x 公开文档未明确 docstring 解析格式(待确认:验证点:docstring 解析测试用例)。
  • 多段 docstring 都进 description 吗?答:首段通常作为工具描述,后续段落按解析规则分配。
  • 如何确认字段描述已生成?答:调用 tools/list 检查 inputSchema 各字段 description。

04.7.18.2-013 Context 参数如何被框架自动注入而不进入 schema?

一句话结论

工具/资源/提示函数签名中类型标注为 Context 的参数由框架在调用时自动注入当前会话上下文,不作为客户端入参出现在 inputSchema。框架按类型注解识别注入参数,其余参数才生成客户端可见的 arguments 契约。

概念解释

  • 注入参数:携带日志、进度、资源读取、会话标识等服务端能力。
  • 识别方式:参数类型标注为 Context 即由框架注入并跳过 schema 生成;Depends 注入参数同样排除。
  • Context 参数位置通常不限定最后一个,但惯例放在最后便于阅读。

原理流程

  1. 注册解析签名时,识别 Context 类型参数并标记为注入项。
  2. 生成 schema 时排除注入参数。
  3. 调用阶段框架构造当前会话 Context 传入函数。

代码或图示

from fastmcp import Context, FastMCP

mcp = FastMCP("ctx-demo")

@mcp.tool
def echo(text: str, ctx: Context) -> str:
    """回显文本。"""
    return text

常见误区

  • 给 Context 参数写默认值或类型为其他对象:框架可能识别不到,导致它被当成普通入参。
  • 在模块作用域尝试取当前 Context:Context 是调用期对象,函数外不存在当前会话实例。

追问

  • Context 类型从哪里导入?答:FastMCP 2.x 可从 fastmcp 导入 Context;2.14 起也可用 from fastmcp.dependencies import CurrentContext 配合 ctx: Context = CurrentContext()。
  • 一个函数能注入多个 Context 吗?答:每个请求对应一个 Context 实例,函数注入一个会话上下文即可。
  • Context 会出现在资源或提示函数里吗?答:工具与资源函数可注入 Context;提示函数以参数填充为主。

04.7.18.2-014 Context 提供的日志方法与级别是什么?

一句话结论

Context 暴露 debug/info/warning/error 等级别日志方法,把消息作为日志通知推给客户端展示。日志走协议通知通道,与服务端本地结构化日志是两套体系;日志内容不得包含密钥、令牌或完整敏感参数。

概念解释

  • 级别:调试、信息、警告、错误,与常见日志级别对应。
  • 用途:对接排查时让客户端看到服务端执行过程;本地落盘仍应使用应用日志系统。
  • 方法通常为异步调用形式,调用后不阻塞业务流程。

原理流程

  1. 工具执行中调用 ctx.info(...) 等方法。
  2. 框架组装日志通知,按会话通道发给客户端。
  3. 客户端按级别展示或过滤;服务端本地日志另行记录。

代码或图示

@mcp.tool
async def process(uri: str, ctx: Context) -> str:
    await ctx.info(f"开始处理 {uri}")
    await ctx.warning("下游响应偏慢")
    return "done"

常见误区

  • 用协议日志代替本地日志:进程排障、聚合检索仍需本地结构化日志。
  • 在日志里打印完整请求体:可能含个人信息或凭据,应脱敏后记录。

追问

  • 日志级别能被客户端调整吗?答:可通过 logging/setLevel 协商级别,服务端按级别过滤通知。
  • 日志方法是同步还是异步?答:FastMCP 2.x 日志方法为协程方法,调用时 await ctx.info(...)。
  • 日志通知会阻塞返回结果吗?答:通知为轻量推送,不应在日志调用中做重 IO。

04.7.18.2-015 进度上报 report_progress 的参数与语义是什么?

一句话结论

ctx.report_progress(progress, total) 向客户端上报任务完成度:当前进度值与总量,可选附进度消息。长任务在循环或分阶段执行中定期调用,让客户端感知任务存活与推进;进度通知是单向消息,不等待客户端确认。

概念解释

  • progress:已完成进度,total:总量;总量未知时可省略 total。
  • 上报节奏:过密增加消息开销,过疏失去反馈意义,按任务阶段选择。
  • 进度与取消配合:检查点同时读取消状态,避免继续推进已取消任务。

原理流程

  1. 任务启动时确定总量与阶段划分。
  2. 每完成一段调用 report_progress 更新进度。
  3. 任务结束返回最终结果;客户端在流中看到进度推进。

代码或图示

@mcp.tool
async def batch(items: list[str], ctx: Context) -> dict:
    total = len(items)
    for i, item in enumerate(items, start=1):
        await ctx.report_progress(progress=i, total=total)
    return {"processed": total}

常见误区

  • 只在结束时上报一次:中途无反馈,客户端可能误判卡死。
  • 总量填无意义数字:进度显示失真,应尽量给可估计总量或采用阶段说明。

追问

  • 进度通知需要客户端回包吗?答:不需要,通知单向投递。
  • 进度能回退吗?答:进度值由服务端按阶段上报,重试或分段重置时可能下降。
  • 上报频率如何控制?答:按批大小或时间间隔节流,避免每处理一条就发通知。

04.7.18.2-016 通过 Context 读取本服务端资源 read_resource 是怎样的?

一句话结论

ctx.read_resource(uri) 让工具在执行过程中按 URI 读取本服务端已注册资源,返回资源内容供工具继续处理。它复用资源注册逻辑,避免在工具里重复实现数据读取;读取失败按资源错误返回。

概念解释

  • 用途:工具组合已有资源数据,如读取配置、记录详情后再加工。
  • 返回形态:资源内容结构,可能含文本或二进制条目,按资源 MIME 类型解析。
  • 与直接内部调用函数的区别:走资源读取契约,URI 与模板校验统一经过资源层。

原理流程

  1. 工具确定要读取的资源 URI。
  2. 调用 await ctx.read_resource(uri),框架路由到对应资源函数。
  3. 工具解析返回内容,进入后续处理或结果组装。

代码或图示

@mcp.tool
async def summary(uri: str, ctx: Context) -> str:
    contents = await ctx.read_resource(uri)
    content = contents[0].text if contents else ""
    return f"长度 {len(str(content))} 的摘要输入"

常见误区

  • 在工具内绕过资源层直连数据源:绕过了资源 URI 校验与订阅/缓存逻辑。
  • 假设 read_resource 一定返回文本:二进制资源需按内容类型解码。

追问

  • 能读取其他服务端的资源吗?答:Context 读取的是本服务端资源;跨服务端访问属于代理/客户端能力。
  • 资源不存在返回什么?答:资源读取错误,工具应捕获并转成业务错误或提示。
  • read_resource 是异步方法吗?答:是协程方法,调用时 await ctx.read_resource(uri),返回 list[ReadResourceContents]。

04.7.18.2-017 Context 上可获取的客户端与会话信息有哪些?

一句话结论

Context 可访问当前会话标识、客户端信息等会话级数据,并提供日志、进度、资源读取等能力:可读取 ctx.client_id、ctx.session_id、ctx.request_id;认证结果经 get_access_token() 取得 AccessToken(client_id、scopes、expires_at、claims)。会话信息按调用隔离,不跨会话共享。

概念解释

  • 会话标识:区分不同连接与客户端,用于日志关联与权限判断。
  • 认证结果:经 get_access_token() 读取令牌身份、scope 与 claims。
  • 能力入口:日志、进度、资源读取等通过 Context 方法调用。

原理流程

  1. 握手与鉴权完成后,框架把会话数据写入上下文。
  2. 工具函数经 Context 读取当前会话信息。
  3. 会话关闭后上下文释放,数据不残留到下一连接。

代码或图示

@mcp.tool
def whoami(ctx: Context) -> dict:
    return {"client_id": ctx.client_id}

常见误区

  • 把会话身份复制到全局变量:并发会话互相覆盖,身份判断串扰。
  • 依赖未文档化的内部字段:版本升级后字段可能移除,应只使用公开 API。

追问

  • Context 能拿到原始 HTTP 请求头吗?答:经 get_http_headers()、get_http_request() 依赖函数读取;get_access_token() 取令牌。
  • 会话信息能跨工具调用保留吗?答:同一会话内保留,新连接重新建立。
  • 如何查看 Context 公开方法清单?答:读当前版本类型定义与文档,不凭印象列举。

04.7.18.2-018 工具返回纯文本时如何包装成文本内容块?

一句话结论

工具返回字符串时,框架默认将其包装为文本内容块(type: text,text 字段承载字符串)。文本块是最常见的返回形态,适合直接展示给用户或并入模型上下文;多行文本、代码片段可保留换行与格式标记。

概念解释

  • 文本块:协议内容块数组中的一种,面向人类阅读与模型理解。
  • 字符串直返:无需手动构造内容对象,框架完成包装。
  • 纯文本不携带结构化字段,二次解析需自行约定格式。

原理流程

  1. 工具函数返回字符串。
  2. 结果序列化路径识别字符串,生成文本内容块。
  3. 响应 content 数组携带文本块返回客户端。

代码或图示

@mcp.tool
def greeting(name: str) -> str:
    return f"你好,{name}!"
{
  "content": [{"type": "text", "text": "你好,Ann!"}]
}

常见误区

  • 在字符串里塞 JSON 再让客户端解析:结构化数据应走结构化返回字段,不要伪装成纯文本。
  • 返回带敏感信息的长文本:返回前脱敏,避免凭据进入客户端上下文。

追问

  • 文本块能包含 Markdown 吗?答:可以携带 Markdown 文本,是否渲染取决于客户端。
  • 一个工具能返回多个文本块吗?答:可以,content 为数组,可追加多个条目。
  • 字符串中的换行如何保留?答:按文本原样保留,客户端按文本内容展示。

04.7.18.2-019 返回 dict/list 等结构化对象时的序列化行为是什么?

一句话结论

工具返回 dict、list 或 Pydantic 模型时,框架把序列化为可传输的结构化 JSON 对象,可与文本块并存于结果中。结构化保留字段层级,便于客户端二次处理;自定义对象、日期时间等非 JSON 原生类型需显式转换或自定义序列化。

概念解释

  • 结构化结果:字段名与类型清晰,不依赖解析自然语言文本。
  • 序列化路径:dict/list 直接 JSON 化;模型走模型导出;非原生类型需处理。
  • 自定义序列化:构造器 tool_serializer 可配置工具结果序列化方式。

原理流程

  1. 工具返回结构化对象。
  2. 框架按类型执行序列化:模型导出、dict/list 转 JSON。
  3. 结构化字段与文本内容块一并放入结果返回。

代码或图示

@mcp.tool
def stats(nums: list[int]) -> dict:
    return {"count": len(nums), "sum": sum(nums), "avg": sum(nums) / len(nums)}

常见误区

  • 返回含日期时间、自定义类的对象不做转换:JSON 序列化失败或变成不可读字符串。
  • 把结构化结果 json.dumps 成字符串再返回:丢失字段结构,客户端无法按字段取用。

追问

  • 结构化结果放在响应哪个字段?答:放在 structuredContent 字段,content 另放展示块。
  • 自定义序列化器如何配置?答:构造器 tool_serializer= 参数传入。
  • 模型返回需要 model_dump 吗?答:框架通常识别 Pydantic 模型自动导出;显式导出更稳妥。

04.7.18.2-020 二进制、图片、音频等媒体内容块如何返回?

一句话结论

媒体/二进制数据按协议媒体内容块返回:携带 MIME 类型与编码后的二进制数据(如 base64),常见类型包括图片、音频等;框架通常提供媒体辅助类型或内容块构造方式。返回前需控制大小,超大媒体应改为 URI 引用或分片返回。

概念解释

  • 媒体块:与文本块并列的内容类型,标注 mimeType 与二进制载荷。
  • 编码:二进制经文本安全编码后放入 JSON 报文,客户端按 MIME 类型解码。
  • 大小风险:图片/音频直接嵌入结果会撑大报文与客户端上下文,需评估上限。

原理流程

  1. 工具生成或读取媒体二进制数据。
  2. 包装为媒体内容块,标注 MIME 类型与编码。
  3. 随结果返回;客户端按类型展示或下载。

代码或图示

from fastmcp.utilities.types import Image

@mcp.tool
def chart(series: list[float]) -> Image:
    return ChartRender.render(series)

常见误区

  • 二进制不编码直接拼 JSON:报文非法,客户端无法解码。
  • 大图直接嵌入响应:报文体积与上下文占用失控,应提供文件/资源 URI 引用。

追问

  • 媒体块支持哪些类型?答:协议内容块含文本、图片(image)、音频(audio)与嵌入资源;FastMCP 提供 Image/Audio/File 辅助类型。
  • 音频/视频返回有大小建议吗?答:应设上限并评估客户端上下文,大文件走资源或外部链接。
  • 媒体数据需要鉴权保护吗?答:外部引用链接需控制访问权限,嵌入内容随会话返回。

04.7.18.2-021 Pydantic 模型作为工具入参时 schema 如何展开?

一句话结论

参数类型标注为 Pydantic BaseModel 时,框架把模型字段递归展开为 inputSchema 的对象属性:每个字段的类型、默认值、Field 约束与描述进入对应 properties。模型本身作为一层对象结构,客户端按字段嵌套填参;复杂入参优先用模型而不是裸 dict。

概念解释

  • 模型入参:schema 体现嵌套对象结构,字段约束集中在模型定义处。
  • 复用:同一模型可在多个工具间复用,参数契约保持一致。
  • 校验:Pydantic 在绑定参数时执行字段校验,错误可映射为参数无效。

原理流程

  1. 工具签名参数类型为模型类。
  2. 框架读取模型字段表,生成嵌套 object schema。
  3. 调用时按模型校验 arguments,校验通过后实例化模型传入函数。

代码或图示

from pydantic import BaseModel, Field

class Address(BaseModel):
    city: str = Field(description="城市")
    street: str = Field(min_length=1)

@mcp.tool
def ship(address: Address, weight: float) -> dict:
    return {"city": address.city, "weight": weight}

常见误区

  • 模型字段缺少类型注解:该字段 schema 退化为宽松类型,校验失效。
  • 在工具内重复校验模型已约束的规则:模型层负责字段校验,工具只处理领域规则。

追问

  • 模型实例化失败返回什么错误?答:参数无效错误,data 可带字段与校验原因。
  • 模型能继承复用字段吗?答:可以,继承字段随模型一并进入 schema。
  • 裸 dict 与模型入参怎么选?答:结构明确、需要校验时用模型;完全动态结构才用 dict。

04.7.18.2-022 Pydantic 模型作为出参与 output_schema 如何控制?

一句话结论

工具返回类型标注为模型时,框架按模型结构推断输出形态;FastMCP 2.x 可用装饰器 output_schema= 显式声明输出 schema,对象型返回(dict/Pydantic/dataclass)自动生成 structured content。

概念解释

  • 出参模型:定义返回字段与类型,避免工具随意返回松散 dict。
  • 输出 schema:客户端可据此理解结果结构,区分结构化字段与展示内容块。
  • 关闭/不生成输出 schema 的行为随版本变化,不要写死默认开关。

原理流程

  1. 工具返回类型标注为模型或结构化类型。
  2. 框架按模型生成输出结构描述(若版本支持)。
  3. 调用结果按模型导出为结构化数据,附文本/媒体内容块。

代码或图示

class OrderOut(BaseModel):
    order_id: str
    status: str

@mcp.tool
def get_order(order_id: str) -> OrderOut:
    return OrderOut(order_id=order_id, status="paid")

常见误区

  • 出参模型字段与实际返回不一致:模型校验导出时报错,应保持返回类型与实现一致。
  • 假定所有返回都自动生成 output_schema:对象型返回自动生成结构化输出;原始类型需返回注解配合,未声明 output_schema= 时不导出输出 schema。

追问

  • 输出 schema 在哪里查看?答:tools/list 工具条目的 outputSchema 字段。
  • 返回模型需要手动 model_dump 吗?答:框架通常自动识别;显式导出可避免兼容问题。
  • 出参能同时含文本和模型吗?答:可以,结构化字段与展示内容块并存于结果。

04.7.18.2-023 模型嵌套模型时 schema 如何递归展开?

一句话结论

模型字段类型仍是模型时,schema 按层级递归展开为嵌套对象:外层 properties 包含内层模型的字段结构。嵌套层级受框架与 schema 深度限制,过深结构应考虑拆分或扁平化;自引用递归模型的 schema 导出需按安装版本核实(待确认:验证点:自引用递归 Pydantic 模型的 schema 导出)。

概念解释

  • 递归映射:每个模型层生成 object,字段类型为模型则继续展开。
  • 可读性:嵌套过深的 schema 会让客户端填参困难,模型设计应控制层级。
  • 复用:内层模型被多处引用时 schema 可重复出现同一结构。

原理流程

  1. 从入参模型开始遍历字段。
  2. 字段类型为模型时递归生成子 object schema。
  3. 组装层级结构写入 inputSchema。

代码或图示

class Item(BaseModel):
    name: str

class Cart(BaseModel):
    items: list[Item]
    note: str | None = None

@mcp.tool
def checkout(cart: Cart) -> dict:
    return {"count": len(cart.items)}

常见误区

  • 嵌套模型字段未标注类型:内层结构丢失,schema 变成任意对象。
  • 设计无限递归模型:序列化与 schema 生成可能失败,需打破循环引用。

追问

  • 嵌套深度有限制吗?答:受 Pydantic 与 JSON Schema 处理能力约束,过深结构应拆分或扁平化并压测验证。
  • 内层模型可单独复用吗?答:可以,模型定义一次,多处参数引用。
  • 嵌套列表模型如何生成?答:list[Item] 映射为数组,元素为 Item 对象 schema。

04.7.18.2-024 联合类型与可选模型入参的 schema 如何处理?

一句话结论

ModelA | ModelB 或 Optional[Model] 注解映射为联合/可空类型:schema 描述允许的类型形态或 null。联合类型的客户端填参歧义较大,工程上优先用区分字段或单个模型替代宽联合;联合关键字按 Pydantic 导出的 JSON Schema(anyOf/oneOf)表达。

概念解释

  • 可空:类型后接 | None,表示允许 null,不代表参数可省略。
  • 联合:多模型选一,客户端需按 schema 判断合法形态。
  • 校验:实际值按候选模型依次校验,首个通过者生效。

原理流程

  1. 解析参数注解中的联合成员与 None 成员。
  2. 生成联合类型约束(schema 联合关键字表达)。
  3. 调用时按候选模型校验入参,匹配失败返回参数错误。

代码或图示

@mcp.tool
def dispatch(payload: OrderPayload | RefundPayload) -> dict:
    return {"kind": type(payload).__name__}

常见误区

  • 用宽联合掩盖模型设计问题:客户端难判断该传哪种结构,错误率上升。
  • 混淆可空与可选:Optional[Model] 无默认值仍是必填,只是允许 null。

追问

  • 联合类型校验顺序影响结果吗?答:两个候选都匹配时按 Pydantic 校验顺序取首个通过者。
  • 能用判别字段区分联合吗?答:在模型内加类型字段辅助区分,schema 与校验更清晰。
  • 联合出参支持吗?答:按输出 schema 支持范围判断,结构不清晰时建议拆分工具。

04.7.18.2-025 默认值、必填项与模型字段约束如何传递?

一句话结论

无默认值参数进入 required;有默认值参数为可选,default 写入 schema。模型字段的 Field 约束(范围、长度、正则)随模型进入 schema 并在绑定校验时执行。必填与可选由函数/模型默认值决定,与类型是否可空是两件事。

概念解释

  • 必填判定:参数无默认值且非注入参数。
  • 约束传递:Field 约束在模型实例化时生效,不满足即校验失败。
  • 默认值只在未传参时生效;显式传入 null 按可空类型处理。

原理流程

  1. 遍历签名与模型字段,记录默认值与约束。
  2. 无默认值写入 required;有默认值记录 default。
  3. 调用校验:缺失必填报错,可选参数取默认值,约束逐项检查。

代码或图示

class Query(BaseModel):
    keyword: str
    limit: int = Field(default=20, ge=1, le=100)

@mcp.tool
def search(q: Query) -> dict:
    return {"limit": q.limit}

常见误区

  • 给可选参数传 None 代替省略:语义不同,未传走默认值,传 None 是显式空值。
  • 把硬约束写进 docstring:文字不校验,必须落到 Field 或校验器。

追问

  • 必填参数缺失的错误 data 带什么?答:缺失字段名与必填说明。
  • 约束取值边界(如 ge=1)包含边界值吗?答:ge 含等于,gt 不含,按 Pydantic 语义。
  • 模型默认值会序列化进 schema 吗?答:通常写入 default 字段供客户端参考。

04.7.18.2-026 工具返回多内容块(文本加媒体)如何写法?

一句话结论

一个工具结果可包含多个内容块:文本块承载说明或摘要,媒体块承载图片/音频等二进制。框架允许返回混合内容组合:返回 list 时逐项转换为内容块,也可使用 Image/Audio/File 辅助类型;多块结果应明确各块角色,避免客户端混淆。

概念解释

  • 组合形态:文本块用于可读结论,媒体块用于可视化或原始数据。
  • 顺序:content 数组顺序通常即展示顺序,说明块在前、媒体块在后更自然。
  • 大小:多块累加体积需控制,媒体超大时改为 URI 引用。

原理流程

  1. 工具执行同时得到文本结论与媒体数据。
  2. 按返回列表逐项组装多个内容块。
  3. 结果随 content 数组返回,客户端逐块展示。

代码或图示

@mcp.tool
def render(series: list[float]) -> list:
    chart = ChartRender.render(series)
    return ["最近趋势图如下。", chart]

常见误区

  • 媒体数据再转成文本嵌入文本块:丢失二进制结构,应使用媒体内容块。
  • 返回过多小块:内容杂乱,客户端上下文占用增加,应合并或精简。

追问

  • 多块结果能只取其中一块吗?答:客户端按类型与顺序取用,工具无法指定哪块必选。
  • 文本与媒体块在结构化字段里怎么区分?答:按内容块类型字段识别,展示与结构化字段分层。
  • 混合返回需要声明输出 schema 吗?答:媒体类型由内容块标注;结构化输出按需用 output_schema= 声明。

04.7.18.2-027 工具名在服务端内的唯一性约束是什么?

一句话结论

同一服务端内工具名必须唯一,客户端按名称调用工具;重名注册按框架重复策略处理:报错、告警后替换或直接替换。FastMCP 2.x 默认策略:工具 "error"、资源 "warn"、提示 "replace",由构造器 on_duplicate_tools/on_duplicate_resources/on_duplicate_prompts= 配置。

概念解释

  • 名称空间:tools、resources、prompts 各自独立命名,工具名不与资源名冲突。
  • 冲突策略:构造实例时可配置重复注册行为,避免静默覆盖造成调用错工具。
  • 名称应稳定可读,包含动作与对象,避免运行期频繁改名。

原理流程

  1. 注册工具时检查名称是否已存在。
  2. 按重复策略处理:报错中断、告警保留或替换。
  3. 清单中每个工具对应唯一调用名称。

代码或图示

mcp = FastMCP("conflict-demo", on_duplicate_tools="error")

常见误区

  • 依赖“后注册覆盖先注册”且不检查:可能误覆盖已有工具,调用方拿到错误行为。
  • 工具名带环境后缀导致清单混乱:环境区分放在服务端 name,工具名保持稳定。

追问

  • 资源与提示重名也算冲突吗?答:分属独立命名空间,不互相冲突;同类组件内才检查唯一性。
  • 重名会在 tools/list 暴露两个同名条目吗?答:按策略报错中断或只保留一个,不会静默重复登记。
  • 改名后旧客户端调用会怎样?答:旧名称方法不存在,需兼容旧名或通知调用方升级。

04.7.18.2-028 @mcp.resource 静态资源的注册与返回类型是什么?

一句话结论

用 @mcp.resource("固定://uri") 注册静态资源:函数返回文本、dict、list 等可序列化数据,框架按返回类型与 MIME 类型包装为资源内容。静态资源 URI 固定,客户端可直接 resources/read 读取,语义为只读数据接入。

概念解释

  • 静态 URI:无占位符,一个函数对应一个固定地址。
  • 返回类型:字符串为文本,结构化对象按 JSON 类内容标注;二进制需媒体内容形态。
  • 只读纪律:资源函数不执行写入动作,重复读取语义稳定。

原理流程

  1. 装饰器绑定固定 URI 与资源函数。
  2. 框架登记资源到静态资源清单。
  3. 客户端 read 请求路由到函数,返回内容条目。

代码或图示

@mcp.resource("config://app-version")
def app_version() -> str:
    """返回应用版本号。"""
    return "2.1.0"

@mcp.resource("data://categories")
def categories() -> list[str]:
    return ["Electronics", "Books"]

常见误区

  • 资源函数里写库或调写入接口:违背只读语义,写入动作应归工具。
  • 返回不可序列化对象:资源内容包装失败,需转成 JSON 原生类型。

追问

  • 静态资源能带参数吗?答:静态 URI 不带占位符;按维度查询用模板资源。
  • 资源返回 dict 如何标注类型?答:未声明时 FastMCP 推断为 application/json;也可用 mime_type= 显式声明。
  • 资源函数可以异步吗?答:与工具一致,同步函数与 async def 都支持。

04.7.18.2-029 URI 模板 {占位符} 与函数参数如何绑定?

一句话结论

资源 URI 中用 {占位符} 定义模板,占位符名称与资源函数参数名一一绑定;客户端按模板填值构造具体 URI,read 时框架把 URI 段解析为参数传入函数。模板参数类型与校验规则通过函数签名与模型约束描述。

概念解释

  • 占位符:URI 路径段中的命名变量,如 users://{user_id}/profile。
  • 绑定:名称匹配函数参数,类型注解约束取值形态。
  • 模板清单:模板资源通过资源模板清单暴露,供客户端发现可查询维度。

原理流程

  1. 装饰器 URI 中写占位符,函数声明对应参数。
  2. 框架登记模板与参数绑定关系。
  3. 客户端填占位符生成 URI,read 时解析段值传入函数。

代码或图示

@mcp.resource("users://{user_id}/profile")
def get_profile(user_id: str) -> dict:
    """按用户 ID 读取档案。"""
    return {"user_id": user_id, "status": "active"}

常见误区

  • 占位符名与参数名不一致:框架无法绑定,注册或调用时报错。
  • 把模板参数当查询字符串处理:占位符在路径段,匹配按模板语法解析。

追问

  • 模板能有多个占位符吗?答:可以,按出现顺序与参数名绑定。
  • 占位符类型如何约束?答:由参数类型注解与校验规则约束,生成对应 schema 约束。
  • 非法 URI 返回什么?答:资源不存在或参数无效错误,需在函数内做存在性判断。

04.7.18.2-030 资源的 mime_type 与内容编码如何声明?

一句话结论

资源可显式声明 MIME 类型(如 text/plain、application/json、图片类型),框架按 MIME 与返回类型决定内容编码方式;未显式声明时按返回类型推断:str 为 text/plain,dict/list/模型为 application/json,bytes 为二进制 blob。二进制资源需标注编码,客户端据此解码展示。

概念解释

  • MIME 类型:告诉客户端内容是文本、JSON、图片还是其他二进制。
  • 编码:文本直接携带,二进制按文本安全编码后传输。
  • 结构化对象:常按 JSON 内容标注,避免被当成纯文本解析。

原理流程

  1. 注册资源时可配置 MIME 类型参数。
  2. 框架按返回值与 MIME 生成内容条目。
  3. 客户端按 MIME 选择解码与展示方式。

代码或图示

@mcp.resource("docs://readme", mime_type="text/markdown")
def readme() -> str:
    return "# 项目说明"

常见误区

  • JSON 内容不标注 MIME:客户端可能按纯文本展示,无法结构化解析。
  • 二进制资源只给文本 MIME:解码失败,必须匹配实际内容类型。

追问

  • MIME 类型能在函数返回时动态决定吗?答:mime_type= 在注册时静态声明;动态场景返回结构化对象由框架按类型推断。
  • 资源内容需要字符编码声明吗?答:按 MIME 与协议内容条目约定,具体字段以规范为准。
  • 同一资源返回多种类型怎么办?答:contents 数组可含多内容条目,分别标注 MIME。

04.7.18.2-031 资源订阅 subscribe 在资源函数中如何对应?

一句话结论

订阅是客户端对资源 URI 建立的更新通知关系:资源数据变化时服务端推送更新通知给已订阅客户端。资源函数本身负责读取当前内容,订阅关系与变更推送由框架会话层维护;订阅由服务端 resources 能力的 subscribe 子标志声明,变更通知为 notifications/resources/updated,params 携带 uri。

概念解释

  • 订阅目标:静态资源 URI 或模板匹配出的具体 URI。
  • 变更时机:数据更新后由服务端触发通知,资源函数不直接感知订阅者。
  • 会话绑定:订阅随会话存活,连接关闭后关系释放。

原理流程

  1. 客户端先 read 确认资源,再发起订阅请求。
  2. 框架在会话上下文记录订阅关系。
  3. 数据变更时框架推送更新通知;客户端取消订阅或会话结束时清理。

代码或图示

client -> server: resources/subscribe {uri}
server -> client: notifications/resources/updated {uri}

常见误区

  • 在资源函数里主动推送消息:读取函数只返回当前内容,推送由会话层按订阅关系处理。
  • 无状态模式下假设持久订阅:会话内推送受限,需降级为主动读取。

追问

  • 资源变更如何通知框架?答:FastMCP 2.x 增删启停资源后自动发送 notifications/resources/list_changed;主动更新通知经 Context 触发。
  • 订阅状态存哪里?答:会话上下文,进程内存;跨会话共享需框架支持。
  • 高频变更适合订阅吗?答:推送量大,需评估频率与客户端承受能力。

04.7.18.2-032 资源与工具在返回数据上的纪律差异是什么?

一句话结论

资源返回只读数据,重复读取语义稳定、无副作用;工具返回执行结果,允许计算与外部写入。资源内容偏向“可引用的数据”,工具结果偏向“一次动作的产出”。把写入动作放进资源、把纯数据读取做成工具,都会模糊调用语义。

概念解释

  • 资源:GET 语义,适合配置、文档、记录详情;可被订阅与重复引用。
  • 工具:动作语义,适合计算、转换、外部系统交互;结果通常不可重复引用。
  • 组合:工具可通过 Context 读取资源数据,再加工返回。

原理流程

  1. 判断能力本质:只读数据 → 资源;动作/计算 → 工具。
  2. 按原语注册并遵守返回纪律。
  3. 客户端按语义选择入口,调用预期与返回形态一致。

代码或图示

resource: 稳定只读数据, 可订阅, 可重复引用
tool:     一次执行, 可有副作用, 结果随动作产出

常见误区

  • 资源函数每次读取都触发随机或写入操作:违背只读语义,客户端无法缓存与引用。
  • 工具返回静态配置却不提供资源入口:清单粒度粗,模型选择能力时理解成本高。

追问

  • 查询接口两边都想挂怎么办?答:以主语义为准选一个原语,避免重复入口;需要组合时工具内部读资源。
  • 资源能返回计算结果吗?答:可以是轻量派生数据,但不应触发重副作用或长流程。
  • 纪律差异影响 schema 吗?答:入参出参结构类似,但调用预期与返回稳定性约定不同。

04.7.18.2-033 @mcp.prompt 参数化提示模板如何注册?

一句话结论

用 @mcp.prompt 装饰提示函数:函数参数即模板入参,返回字符串或消息对象列表;框架收集提示名、描述与参数 schema,客户端通过 prompts/get 填参取出消息序列。提示模板不执行外部动作,只组装对话内容。

概念解释

  • 注册方式与工具/资源一致,装饰器绑定提示元数据。
  • 参数由签名推导必填/可选与类型,描述来自 docstring 或字段说明。
  • 返回形态:单条文本、单条消息或多轮消息列表。

原理流程

  1. 定义提示函数,声明参数与返回内容。
  2. 装饰器注册到提示清单,生成参数 schema。
  3. 客户端 get 填参,框架填充模板返回消息序列。

代码或图示

@mcp.prompt
def code_review(code_snippet: str) -> str:
    """生成代码评审请求。"""
    return f"请评审以下代码的缺陷与风格:\n```python\n{code_snippet}\n```"

常见误区

  • 在提示函数里调用下游 API 或写库:模板只组装文本,动作应归工具。
  • 提示参数不加类型注解:参数 schema 宽松,客户端填参失去约束。

追问

  • 提示名与工具名冲突吗?答:独立命名空间,不互相冲突。
  • 提示可以无参数吗?答:可以,固定模板直接返回消息序列。
  • 装饰器能覆盖提示名与描述吗?答:@mcp.prompt(name=, description=, title=, tags=) 可显式覆盖;name 默认取函数名。

04.7.18.2-034 prompt 函数返回值形态:字符串与 Message 有什么区别?

一句话结论

提示函数可返回纯字符串(默认作为 user 消息文本)、单个消息对象或消息对象列表;多轮对话用列表组织 user/assistant 角色消息。FastMCP 2.x 消息类型从 fastmcp.prompts.prompt 导入 Message、PromptMessage;字符串返回自动包装为单条 user 消息。

概念解释

  • 字符串:最简形态,包装为单条用户消息。
  • Message:带角色与内容的消息对象,可显式指定 user/assistant。
  • 列表:多轮起点,按顺序组织对话上下文。

原理流程

  1. 提示函数按场景选择返回形态。
  2. 框架把返回值转换为协议消息序列。
  3. 客户端把消息并入对话上下文发送给模型。

代码或图示

from fastmcp.prompts.prompt import Message

@mcp.prompt
def debug_start(error_message: str) -> list[Message]:
    """开启排查会话。"""
    return [
        Message(f"我遇到错误:{error_message}", role="user"),
        Message("请提供完整堆栈与操作步骤。", role="assistant"),
    ]

常见误区

  • 版本迁移后仍导入旧消息类型:类型不兼容会注册或返回失败,需按当前版本导入。
  • 返回裸 dict 消息结构:部分版本不再接受 dict,应使用消息对象或字符串。

追问

  • Message 默认角色是什么?答:字符串返回默认包装为 user 消息;Message 建议显式传 role。
  • 提示能返回系统角色消息吗?答:MCP 规范 PromptMessage 角色为 user 或 assistant,不使用 system 角色。
  • 字符串返回会保留换行吗?答:按文本原样保留。

04.7.18.2-035 prompt 参数 schema 与 prompts/get 入参如何对应?

一句话结论

提示函数参数在 prompts/list 中以参数 schema 描述:类型、必填/可选、描述;prompts/get 的 arguments 按参数名传入取值。参数缺失时按默认值或校验错误处理,多余参数按 schema 策略忽略或拒绝;契约以参数 schema 为准。

概念解释

  • schema 来源:函数签名、类型注解、默认值与说明,与工具参数生成规则一致。
  • get 入参:键值对,键对应参数名。
  • 校验:类型与必填在模板填充前检查,非法参数返回参数错误。

原理流程

  1. 注册提示时生成参数 schema 并在 list 输出。
  2. 客户端按 schema 收集参数,get 时传入 arguments。
  3. 框架绑定参数、填充模板,返回消息序列。

代码或图示

{
  "method": "prompts/get",
  "params": {"name": "code_review", "arguments": {"code_snippet": "def add(a, b): return a + b"}}
}

常见误区

  • 提示参数不校验直接拼字符串:非法取值可能拼出无意义或危险文本,应在函数内校验。
  • get 传入未声明参数:行为随版本不同,清单契约以 schema 为准。

追问

  • 提示参数能给取值建议吗?答:可配合 completion 能力提供候选,注册方式见 052 题未核实项。
  • 必填参数缺失返回什么?答:参数无效错误,提示缺失字段。
  • 参数默认值会在 schema 标注吗?答:通常写入可选与默认值信息。

04.7.18.2-036 提示模板中多轮消息(user/assistant)如何组织?

一句话结论

多轮提示返回消息列表,按对话顺序排列 user 与 assistant 消息,作为模型对话起点。assistant 消息用于设定助手先前回应风格或引导后续方向;角色与顺序由返回结构决定,客户端按列表顺序并入上下文。

概念解释

  • 首轮 user:提出问题或任务背景。
  • 后续 assistant:模拟已有的助手回应,引导模型接续。
  • 多轮模板适合固化排查、评审、交接等重复对话流程。

原理流程

  1. 设计对话起点:背景消息、引导消息依次排列。
  2. 提示函数返回消息列表,标注各条角色。
  3. 客户端按顺序把消息加入会话上下文。

代码或图示

@mcp.prompt
def handover(task: str) -> list[Message]:
    return [
        Message(f"待交接任务:{task}", role="user"),
        Message("我先梳理现状、风险与待办。", role="assistant"),
    ]

常见误区

  • 多轮顺序写反:上下文角色错位,模型接续方向混乱。
  • 在 assistant 消息里塞工具调用指令:提示模板只组织对话文本,工具调用由模型决策。

追问

  • 多轮消息能包含媒体内容吗?答:可以,PromptMessage 内容块支持文本、图片、音频与嵌入资源。
  • 提示模板能引用资源内容吗?答:工具/资源侧可经 Context 读资源;提示函数以参数填充为主,Context 注入范围按框架支持。
  • 消息列表长度有限制吗?答:应控制轮次,避免占用过多客户端上下文。

04.7.18.2-037 动态注册 add_tool / remove_tool 的使用时机是什么?

一句话结论

框架支持运行期程序化添加或移除组件:适合按环境、权限、配置条件动态决定暴露集合,或在模块组装时批量挂载。动态变更后应通过清单变更通知告知客户端刷新。FastMCP 2.x 用 mcp.add_tool(...)、mcp.add_resource(...)、mcp.add_prompt(...) 添加;移除走 mcp.local_provider.remove_tool("name") 等方法。

概念解释

  • 程序化注册:不经装饰器,直接把函数或组件对象加入服务端。
  • 动态移除:从清单删除组件,客户端不再可调用。
  • 适用场景:多环境裁剪、按鉴权角色开放能力、插件式组装。

原理流程

  1. 服务端实例创建后,按条件调用添加 API 注册工具/资源/提示。
  2. 条件变化时调用移除 API 或重新注册集合。
  3. 框架更新内部清单,必要时推送 listChanged 通知。

代码或图示

mcp.add_tool(notify_tool)
mcp.local_provider.remove_tool("notify_tool")

常见误区

  • 在请求处理路径中频繁增删组件:清单变更成本高,应在启动或配置变更阶段完成。
  • 移除组件后不刷新客户端清单:旧客户端仍尝试调用已移除工具,收到方法不存在错误。

追问

  • 动态注册需要重启服务吗?答:框架支持运行期注册时不需要;不支持的版本需在启动期完成。
  • 批量挂载多个实例怎么做?答:用 mcp.mount(sub, prefix=...) 或 import_server 把子实例组件并入父实例。
  • 动态工具的 schema 何时生成?答:添加时解析签名生成,移除后从清单删除。

04.7.18.2-038 按环境或条件暴露工具的做法是什么?

一句话结论

条件暴露有三种常见方式:启动期按配置注册/跳过组件、用标签集合过滤可见组件、运行期按会话身份动态判断是否允许调用。前者控制清单可见性,后者控制单次调用授权;两者层次不同,可组合使用。

概念解释

  • 启动条件:环境变量、配置文件决定注册哪些组件。
  • 标签过滤:include_tags/exclude_tags 按标签集合裁剪清单。
  • 调用授权:工具内部或鉴权层按会话身份/scope 拒绝无权操作。

原理流程

  1. 加载环境配置,确定可见组件集合。
  2. 注册时打标签,按过滤规则生成对外清单。
  3. 调用时再做权限校验,清单不可见与调用被拒是两道防线。

代码或图示

import os

if os.environ.get("ENABLE_ADMIN_TOOLS") == "1":
    mcp.add_tool(admin_reset)

@mcp.tool(tags=["report"])
def daily_report(date: str) -> str:
    return "report"

常见误区

  • 只靠清单隐藏敏感工具,调用层不鉴权:知道工具名仍可直接调用,必须在调用侧授权。
  • 把环境判断写死在工具分支里:清单仍暴露该工具,应在注册层裁剪。

追问

  • 标签过滤在构造实例时配置吗?答:构造器 include_tags=/exclude_tags= 按标签集合裁剪清单。
  • 不同会话看到不同清单怎么做?答:清单可见性主要在注册/构造期裁剪;会话级差异用调用授权兜底。
  • 条件暴露需要文档化吗?答:需要,说明各环境开放哪些工具与权限边界。

04.7.18.2-039 tags 标签与 include_tags/exclude_tags 过滤如何工作?

一句话结论

组件注册时可打标签,服务端构造时按 include_tags(仅含匹配标签)或 exclude_tags(排除匹配标签)裁剪对外清单。标签用于分组治理:按环境、角色、模块划分组件集合,比逐组件硬编码开关更集中。

概念解释

  • 标签:附加在工具/资源/提示上的分组标记,不参与调用校验。
  • 包含过滤:只暴露至少带一个匹配标签的组件。
  • 排除过滤:隐藏带匹配标签的组件。

原理流程

  1. 注册组件时通过装饰器或参数打标签。
  2. 构造实例时配置标签集合过滤规则。
  3. 生成清单时按规则保留或排除组件。

代码或图示

mcp = FastMCP("tagged", include_tags=["report"], exclude_tags=["internal"])

@mcp.tool(tags=["report", "daily"])
def daily_report(date: str) -> str:
    return "report"

常见误区

  • 用标签做调用权限:标签只影响清单可见性,无权调用仍需在鉴权/工具内拒绝。
  • 标签集合互相冲突:同时命中包含与排除时,排除优先。

追问

  • 一个组件能打多个标签吗?答:可以,标签集合可含多个值。
  • 标签会出现在清单 meta 里吗?答:作为组件元数据随清单输出,是否纳入框架内部 _meta 由 include_fastmcp_meta 控制。
  • 过滤规则能运行期改吗?答:标签过滤在构造期固定;运行期可见性靠动态注册/移除调整。

04.7.18.2-040 重名工具/资源/提示的冲突处理策略是什么?

一句话结论

同类组件重名时按框架重复策略处理:报错中断、告警后保留或直接替换。FastMCP 2.x 默认:工具 "error"、资源 "warn"、提示 "replace",构造器 on_duplicate_*= 可覆盖。构造实例时可显式配置策略,避免静默覆盖导致调用错组件。

概念解释

  • 策略取值为 error、warn、replace、ignore;提示重复策略另以 "replace" 为默认。
  • 工具重名风险最高:调用方按名触发,覆盖后行为可能完全不同。
  • 注册阶段发现冲突优于运行期调用错工具。

原理流程

  1. 注册组件时检查同类名称是否已存在。
  2. 按配置策略处理:报错、告警记录或替换旧组件。
  3. 清单中保留策略决定后的唯一组件条目。

代码或图示

mcp = FastMCP("dup", on_duplicate_tools="error", on_duplicate_resources="warn")

常见误区

  • 默认静默替换且不检查日志:冲突被掩盖,排障时才发现工具行为不符预期。
  • 跨组件类型误认为冲突:工具、资源、提示各自独立命名空间。

追问

  • 策略为 warn 时保留哪个?答:告警后保留先注册组件,新组件不覆盖。
  • 重名在 tools/list 会暴露两条吗?答:按策略只保留一条或注册中断,不会重复登记。
  • 旧名称兼容怎么做?答:保留旧名工具并内部委托新实现,或通知调用方升级。

04.7.18.2-041 长任务在工具内的超时与协作式取消如何处理?

一句话结论

长任务应设置执行超时并支持协作式取消:在循环与 IO 等待点检查取消状态或超时截止时间,停止后续工作并释放资源。Python 无法安全强杀线程/协程,取消必须由函数内配合检查点响应;超时预算需与客户端、下游调用超时逐层对齐。

概念解释

  • 协作取消:读取取消信号,在检查点退出,而不是依赖框架中断执行。
  • 超时分层:客户端等待超时、工具执行超时、下游调用超时,预算逐级收敛。
  • 资源清理:退出路径关闭连接、文件句柄、临时对象,避免泄漏。

原理流程

  1. 工具记录任务开始时间与取消信号引用。
  2. 每个处理阶段检查超时与取消状态。
  3. 触发退出时清理资源,返回取消/超时错误或部分结果。

代码或图示

import time

@mcp.tool
async def long_task(ctx: Context) -> dict:
    deadline = time.monotonic() + 30
    for item in work_items():
        if time.monotonic() > deadline:
            return {"status": "timeout"}
        await ctx.report_progress(...)
    return {"status": "done"}

常见误区

  • 把阻塞调用一直挂住:不可中断的同步 IO 会让取消与超时都失效,应换异步驱动或加执行器超时。
  • 取消后不清理资源:连接与句柄泄漏,长时间运行后耗尽下游连接池。

追问

  • 取消信号从哪里读取?答:经 Context 或会话上下文获取取消状态;读取方法名见 042 题未核实项。
  • 部分结果能在取消时返回吗?答:可返回已完成部分并标注未完成,语义需在工具说明中约定。
  • 超时阈值写死还是配置?答:按环境配置,工具内默认值与下游超时对齐。

04.7.18.2-042 进度上报与取消信号如何配合长任务?

一句话结论

进度上报让客户端感知任务存活,取消信号让任务在检查点退出;两者在同一循环中配合:每处理一批既上报进度,又检查取消/超时状态。进度通知本身不传递取消意图,取消由独立通知或会话信号承载。

概念解释

  • 检查点:循环迭代、IO 返回后、批次边界都是检查取消的位置。
  • 节奏:进度按批上报,取消检查与进度上报放在同一检查点,避免重复遍历。
  • 状态一致性:退出时进度停在最后完成阶段,结果标注取消或超时。

原理流程

  1. 初始化总量、截止时间与取消引用。
  2. 循环中:处理一批 → 上报进度 → 检查取消/超时 → 继续或退出。
  3. 结束返回最终状态,资源在退出路径释放。

代码或图示

for i, item in enumerate(items, start=1):
    await ctx.report_progress(progress=i, total=len(items))
    if cancellation_requested:
        return {"status": "cancelled"}
    process(item)

常见误区

  • 只上报进度不检查取消:任务无法响应中止,客户端取消后仍占用资源。
  • 在不可中断的阻塞调用中间检查:检查点只在调用返回后生效,阻塞期间无法响应取消。

追问

  • Context 上取消状态方法名是什么?答:以当前版本公开 API 为准(待确认:验证点:Context 取消相关方法)。
  • 进度通知能携带取消请求吗?答:不能,取消是独立通知语义,进度只反映完成度。
  • 长任务需要心跳兜底吗?答:进度本身是存活信号;无阶段可上报时可配合 ping 或周期日志。

04.7.18.2-043 strict_input_validation 与宽松强制转换有什么区别?

一句话结论

严格输入校验模式按 schema 精确校验入参,类型不匹配即拒绝;宽松模式允许 Pydantic 做兼容转换(如字符串数字转整数)。FastMCP 2.x 构造器 strict_input_validation= 默认为 False(宽松);对外公开服务建议开启严格模式,减少隐式类型转换带来的歧义。

概念解释

  • 严格模式:按 JSON Schema 校验,拒绝额外类型与强制转换。
  • 宽松模式:利用 Pydantic 柔性转换,兼容客户端传入的邻近类型。
  • 取舍:宽松利于模型填参容错,严格利于契约清晰与安全。

原理流程

  1. 调用参数进入框架,按配置选择校验路径。
  2. 严格模式对照 schema 逐项检查;宽松模式尝试类型 coercion。
  3. 校验通过绑定函数;失败返回参数无效错误。

代码或图示

mcp = FastMCP("strict-demo", strict_input_validation=True)

常见误区

  • 依赖宽松转换接受错误类型:下游可能收到意料之外的转换结果,应在 schema 与文档中明确类型。
  • 公开服务关闭严格校验:字符串拼接、数值溢出等风险被隐式转换掩盖。

追问

  • 严格模式下多余字段如何处理?答:按 Pydantic 模型额外字段策略处理;输入对象模型未声明字段在严格校验下拒绝。
  • 转换失败返回什么错误?答:参数无效错误,data 带字段与原因。
  • 校验模式能按工具覆盖吗?答:strict_input_validation 为构造期全局开关,不按单工具覆盖。

04.7.18.2-044 schema 质量如何影响客户端调用成功率?

一句话结论

schema 是模型填参与客户端校验的契约:类型明确、约束清楚、描述具体时,模型能选出正确工具并填对参数;schema 宽松、描述模糊、缺类型时,选错工具、填错类型、漏填参数的概率显著上升。schema 质量直接决定工具被调用的成功率与返工次数。

概念解释

  • 类型明确:减少“该传字符串还是数字”的猜测。
  • 描述具体:说明用途、单位、范围与示例,辅助模型判断何时使用。
  • 约束完备:枚举、范围、长度把非法取值挡在调用前。

原理流程

  1. 注册时从签名、注解、Field、docstring 生成 schema。
  2. 客户端/模型依据 schema 选择工具、组装参数。
  3. schema 缺陷在调用期表现为选错工具、参数错误或结果不可用。

代码或图示

schema 清晰 -> 工具选择准 -> 参数一次填对 -> 调用成功
schema 宽松 -> 选错/填错 -> 参数错误 -> 重试或放弃

常见误区

  • 只写函数不补注解与描述:把填参判断完全交给模型猜测,成功率低。
  • schema 与实际实现不一致:校验通过但函数内报错,契约失去意义。

追问

  • 如何评估 schema 质量?答:检查 list 输出的类型、必填、枚举、描述是否齐全,并用调用用例验证填参。
  • 描述长度多长合适?答:说明用途与边界即可,过长占用上下文,过短无法判断。
  • 多个工具描述雷同会怎样?答:模型难以区分适用场景,容易选错入口。

04.7.18.2-045 描述不清、缺类型注解时模型端的典型失败表现是什么?

一句话结论

典型表现:工具被频繁选错或不用、参数类型乱填(数字填成字符串、对象填成数组)、必填项遗漏、返回结果无法解析。根因常在 schema:缺类型注解导致宽松 schema,docstring 缺失导致工具用途不明,约束缺失导致取值越界。

概念解释

  • 选错工具:描述雷同或空泛,模型按名字猜测用途。
  • 填错类型:schema 无类型约束,模型自由取值。
  • 解析失败:出参结构未约束,返回内容不可读。

原理流程

  1. 缺陷 schema 进入客户端清单。
  2. 模型选择工具与填参时缺少明确依据。
  3. 调用出现参数错误、类型错误或不可用结果,重试仍失败。

代码或图示

# 不推荐:无注解、无描述
@mcp.tool
def guess(a, b):
    return a + b

常见误区

  • 把调用失败归因于模型能力不足:很多情况是 schema 契约缺失,应先修注解、约束与描述。
  • 工具名起得含糊(如 handle):名称不表达动作对象,模型难以选择。

追问

  • 缺类型注解的参数在 schema 里长什么样?答:无确定 type 约束,schema 退化为宽松条目,校验不拦截类型错误。
  • 如何复现 schema 缺陷?答:内存内 client 调 tools/list 检查 schema,再按 schema 手工填参验证。
  • 出参不明确有什么后果?答:客户端无法结构化取用,只能解析文本,错误率上升。

04.7.18.2-046 资源 URI 模板参数校验与非法 URI 如何处理?

一句话结论

模板资源应对 URI 占位符取值做校验:类型、格式、存在性与权限在读取前检查;非法 URI、缺失占位符、资源不存在应返回明确资源错误,不拼接进下游查询。URI 校验与工具入参校验同样重要,防止路径穿越、注入与越权读取。

概念解释

  • 占位符校验:类型转换、格式匹配(如 ID 格式、合法字符集)。
  • 存在性与权限:资源是否属于当前会话可访问范围。
  • 错误映射:URI 不匹配模板、参数非法、资源不存在分别归类返回。

原理流程

  1. 客户端 URI 进入资源路由,匹配模板提取占位符。
  2. 校验取值类型与格式,转换为函数参数。
  3. 检查存在性与权限,失败返回资源错误;通过后读取内容。

代码或图示

@mcp.resource("files://{path:path}")
def read_file(path: str) -> str:
    if ".." in path:
        raise ValueError("非法路径")
    return load_safe(path)

常见误区

  • 占位符直接拼 SQL 或文件路径:未白名单/规范化导致注入与路径穿越。
  • 资源不存在返回空内容:应返回错误,便于客户端区分“无数据”与“URI 错误”。

追问

  • URI scheme 能自定义吗?答:可以,但需在服务端内部可解析并做好校验。
  • 模板参数类型如何约束?答:函数注解与校验器约束,生成对应 schema 约束。
  • 非法 URI 与未注册资源如何区分?答:模板不匹配/参数非法 vs 模板存在但记录缺失,错误 data 可区分。

04.7.18.2-047 提示模板参数缺失或多余时的行为是什么?

一句话结论

必填提示参数缺失时按参数校验失败处理,返回参数无效错误;可选参数使用默认值。传入未声明的多余参数,行为随版本不同:忽略或报错,契约以参数 schema 为准。提示函数内部仍应做领域校验,不能只依赖 schema 拦截。

概念解释

  • 必填/可选判定与工具参数一致:有无默认值决定。
  • 多余参数:schema 未声明,框架策略可能忽略或拒绝。
  • 领域校验:取值合法性、组合关系在函数内检查。

原理流程

  1. prompts/get 传入 arguments。
  2. 框架按参数 schema 绑定必填与可选参数。
  3. 缺失必填报错;多余参数按策略处理;函数内补充业务校验后填充模板。

代码或图示

@mcp.prompt
def reply(question: str, tone: str = "formal") -> str:
    if tone not in {"formal", "casual"}:
        raise ValueError("tone 非法")
    return f"以{tone}语气回答:{question}"

常见误区

  • 提示参数不做校验直接 f-string 拼接:非法取值拼出不当文本,甚至引入注入风险。
  • 依赖框架拒绝多余参数做安全边界:版本行为可能变化,业务校验不能省略。

追问

  • 提示参数缺失会返回消息吗?答:不会,校验失败走参数错误分支。
  • 默认参数在 list 清单可见吗?答:通常作为可选与默认值信息呈现。
  • 提示模板能校验参数组合关系吗?答:在函数内实现跨字段规则校验。

04.7.18.2-048 装饰器注册后的函数还能直接调用吗?可测试性如何?

一句话结论

装饰器返回值行为随版本不同:部分版本装饰后仍是原函数可直接调用,部分版本返回组件对象;测试时优先用内存内 client 经协议会话调用 call_tool,而不是依赖装饰后函数直连。需要直接复用函数逻辑时,应保留原函数引用或在组件内委托实现。

概念解释

  • 直连测试:绕过协议,适合纯函数单元测试。
  • 协议测试:经 client 会话调用,覆盖 schema 校验、序列化与错误映射。
  • 版本差异:装饰器返回原函数还是组件对象,测试以内存内 client 协议调用为准,不依赖装饰后返回类型。

原理流程

  1. 编写工具逻辑时把核心计算放在可独立调用的函数中。
  2. 装饰器包装注册,协议调用走框架路径。
  3. 测试分别覆盖纯函数直连与协议会话调用两条路径。

代码或图示

def _add(a: int, b: int) -> int:
    return a + b

@mcp.tool
def add(a: int, b: int) -> int:
    return _add(a, b)

常见误区

  • 测试依赖装饰后对象的内部属性:版本升级后返回类型变化,测试断裂。
  • 只测直连不测协议:schema 生成、序列化、错误映射等框架路径未覆盖。

追问

  • 协议测试用什么客户端?答:框架提供的内存内 client,经会话 call_tool 断言结果(见部署测试主题页)。
  • 装饰器返回原函数的版本如何判断?答:读 FastMCP 2.x 类型定义与迁移说明;核心逻辑拆内层函数即可规避该差异。
  • 核心逻辑为什么要拆出内层函数?答:便于直连复用与单元测试,不依赖框架包装。

04.7.18.2-049 组件 meta 元数据与 tags 的附加方式是什么?

一句话结论

标签与自定义元数据在注册组件时附加:标签用于分组过滤,meta 携带展示或治理信息。标签经装饰器 tags= 附加;框架内部 _meta 是否附带由构造器 include_fastmcp_meta(默认 True)控制。

概念解释

  • tags:注册参数中的标签集合,参与 include/exclude 过滤。
  • meta:组件级附加信息,随 list 清单与结果输出。
  • 内部命名空间:框架私有标记不应作为跨版本稳定契约依赖。

原理流程

  1. 装饰器/程序化注册时传入标签与元数据。
  2. 框架组装组件 meta,并入清单输出。
  3. 客户端按 meta 分组展示或过滤;外部系统只依赖约定的自定义字段。

代码或图示

@mcp.tool(tags=["report"])
def daily_report(date: str) -> str:
    """生成日报。"""
    return "report"

常见误区

  • 把必填业务参数塞进 meta:入参契约必须走 schema,meta 不参与校验。
  • 依赖框架内部 meta 键名做集成:命名空间可能重命名,升级需回归。

追问

  • meta 会在 initialize 响应出现吗?答:服务端身份在 serverInfo;组件 meta 在各 list 清单中。
  • 能关闭框架内部 meta 输出吗?答:构造器 include_fastmcp_meta=False 关闭。
  • 自定义 meta 需要客户端识别吗?答:未约定字段客户端可忽略,集成前双方对齐键名。

04.7.18.2-050 资源返回 dict 时的内容类型如何推断?

一句话结论

资源返回 dict/list 等结构化对象时,框架通常按 JSON 类内容推断 MIME 类型并包装为结构化内容;未显式声明时 FastMCP 按返回类型推断:dict/list/模型为 application/json。结构化资源应在需要时显式标注 MIME,避免客户端按纯文本解析。

概念解释

  • 推断依据:返回值类型与显式 MIME 声明。
  • JSON 内容:客户端可结构化解析;纯文本则需自行解析格式。
  • 二进制/媒体资源不走 dict 推断路径。

原理流程

  1. 资源函数返回结构化对象。
  2. 框架按返回类型与 MIME 配置生成内容条目。
  3. 客户端按 MIME 决定解析方式。

代码或图示

@mcp.resource("data://categories")
def categories() -> dict:
    return {"items": ["Electronics", "Books"]}

常见误区

  • dict 内混放不可序列化对象:内容包装失败,需先转为 JSON 原生类型。
  • 假定 dict 一定被标注为 JSON:未显式声明时默认推断为 JSON;需要固定类型时显式声明 MIME 更稳妥。

追问

  • 返回 list 与 dict 推断有区别吗?答:同为结构化对象,均推断为 application/json。
  • 结构化资源能订阅吗?答:可以,订阅按 URI 建立,与内容类型无关。
  • 如何确认实际 MIME?答:调 resources/read 检查返回内容条目的 MIME 字段。

04.7.18.2-051 同一函数同时注册为工具与资源是否可行?

一句话结论

技术上可把同一底层函数分别注册到工具与资源两个命名空间,但语义上不推荐:工具是动作入口,资源是只读数据入口,重复暴露会让客户端看到两套语义相近的入口,参数与结果难以对齐。更清晰的做法是按主语义选一个原语,需要复用时在内部委托同一实现函数。

概念解释

  • 命名空间独立:工具与资源重名不构成冲突,但调用路径与返回形态不同。
  • 语义冲突:资源要求只读稳定,工具允许副作用,同一实现难以同时满足两边纪律。
  • 复用方式:抽出内层纯函数,工具与资源分别包装调用。

原理流程

  1. 抽取可复用的核心实现函数。
  2. 按语义选择工具或资源装饰器包装,必要时另一原语内部委托。
  3. 清单中只保留符合语义的入口,避免重复暴露。

代码或图示

def _profile(user_id: str) -> dict:
    return {"user_id": user_id}

@mcp.resource("users://{user_id}/profile")
def profile_resource(user_id: str) -> dict:
    return _profile(user_id)

常见误区

  • 图省事双注册:客户端模型在两个入口间犹豫,调用预期不一致。
  • 资源包装了带副作用的实现:违背只读纪律,后续读取结果不可预期。

追问

  • 工具内部能读资源吗?答:可以,经 Context 读取本服务端资源,再加工返回。
  • 双注册会在清单出现两次吗?答:分属 tools/resources 两个清单,各出现一次。
  • 什么情况下可以双注册?答:仅当两边语义都成立且文档明确区分入口职责,否则应拆分。

04.7.18.2-052 提示模板参数如何与 completion 补全联动?

一句话结论

completion 能力可为提示或资源参数提供候选取值建议:客户端填写参数时请求补全,服务端按参数引用与前缀返回候选列表。提示模板可声明哪些参数支持补全及候选来源;FastMCP 2.x 中 completion 候选的注册 API 与参数引用格式需按安装版本核实(待确认:验证点:completion 候选注册 API 与参数引用格式)。

概念解释

  • 候选来源:枚举集合、数据库查询、前缀匹配的名称列表。
  • 补全只建议取值,不替代最终参数校验。
  • 适合取值封闭或可搜索的字段,自由文本参数不需要补全。

原理流程

  1. 注册提示/资源时标注参数补全能力与候选来源。
  2. 客户端在填参时发 completion 请求,带参数引用与前缀。
  3. 服务端过滤候选返回;用户选定后作为正式参数提交,仍走正常校验。

代码或图示

client -> server: completion/complete {ref, argument, prefix}
server -> client: {values: ["open", "closed"], total: 2}

常见误区

  • 把补全候选当白名单强约束:补全是建议,最终入参仍需服务端校验。
  • 补全接口返回全量数据:应按前缀限量分页,避免候选清单过长。

追问

  • 工具参数支持补全吗?答:completion 面向 prompts/resources;工具入参取值约束靠 schema 枚举(enum)。
  • 候选值需要分组吗?答:按客户端展示需要决定,协议只承载值与数量信息。
  • 补全失败影响调用吗?答:不阻断,用户可手动输入取值。

04.7.18.2-053 工具内部调用本服务端其他工具的方式与注意点是什么?

一句话结论

工具内部可复用其他工具的核心实现:推荐直接调用抽出的内层函数,避免走协议会话自调用;若框架提供内部调用入口,可经服务端实例或 Context 触发,但要注意上下文传递、异常处理与循环调用。跨工具复用应沉淀为共享函数或服务层,而不是在工具间互相套协议调用。

概念解释

  • 内层函数复用:纯函数/服务方法被多个工具委托调用,无协议开销。
  • 内部调用入口:需要复用已注册工具时,推荐调用抽出的内层函数;框架内部触发方式以实例方法为准。
  • 风险:循环依赖、会话上下文重复注入、异常被包装两层。

原理流程

  1. 把公共逻辑抽到共享函数或服务层。
  2. 工具 A 委托共享函数;需要触发工具 B 行为时调用其内层实现。
  3. 统一异常映射与日志,避免工具间循环调用。

代码或图示

def _lookup(user_id: str) -> dict:
    return repo.get(user_id)

@mcp.tool
def profile(user_id: str) -> dict:
    return _lookup(user_id)

@mcp.tool
def profile_with_orders(user_id: str) -> dict:
    base = _lookup(user_id)
    base["orders"] = repo.orders(user_id)
    return base

常见误区

  • 工具内再发起协议请求到自身:绕弯增加会话与序列化开销,易出循环调用。
  • 共享函数里依赖当前 Context:被多个工具复用时上下文来源不一致。

追问

  • 内部调用会经过参数 schema 校验吗?答:直接调内层函数不走协议校验;经实例内部调用入口才会经过参数绑定与校验。
  • 工具间能共享连接池吗?答:共享资源放 lifespan,不在工具函数内新建。
  • 循环调用如何排查?答:检查工具调用链,公共逻辑下沉到服务层打破环。

04.7.18.2-054 返回包含日期时间等非 JSON 原生类型时如何序列化?

一句话结论

JSON 原生类型只有字符串、数字、布尔、null、数组、对象;日期时间、UUID、枚举、自定义类等需显式转换为原生类型(字符串 ISO 格式、字符串 ID、导出字典)。框架对 Pydantic 模型有自动导出,其他自定义对象需在返回前转换,否则序列化失败或变成不可读结构。

概念解释

  • 日期时间:序列化为 ISO 8601 字符串,客户端按格式解析。
  • 枚举:取成员值而非成员名。
  • 自定义类:导出字典或字段值,不直接传实例。

原理流程

  1. 工具返回值进入序列化路径。
  2. 模型/已知类型按导出规则转换;未知类型手动转原生类型。
  3. 不可序列化对象在边界转换失败时返回内部错误并记日志。

代码或图示

from datetime import datetime

@mcp.tool
def snapshot() -> dict:
    now = datetime.now()
    return {"taken_at": now.isoformat(), "tag": "daily"}

常见误区

  • 直接返回 datetime 实例:JSON 编码报错或变成框架默认字符串,格式不可控。
  • 枚举返回成员名而非值:客户端拿到的标识与 schema 约定不一致。

追问

  • Pydantic 模型需要手动 dump 吗?答:框架通常自动识别;显式 model_dump() 更稳妥。
  • 日期反序列化在客户端怎么做?答:按 ISO 字符串解析为本地时间,注意时区标注。
  • 二进制对象怎么返回?答:走媒体内容块编码,不用 JSON 原生类型路径。

04.7.18.2-055 大列表、大对象返回对客户端上下文有什么影响?

一句话结论

工具结果会进入客户端模型上下文或展示区,超大列表/大对象会占用大量上下文窗口,挤压后续对话与工具调用空间,也可能撑大报文导致传输失败。大结果应分页、摘要化或改为资源 URI 引用,只返回当前决策所需字段。

概念解释

  • 上下文预算:模型上下文有限,全量返回长列表会挤占后续轮次。
  • 报文体积:JSON 序列化与传输有大小上限,超大响应可能被代理或通道截断。
  • 按需字段:只返回决策需要的列,避免冗余嵌套与原始明细。

原理流程

  1. 工具评估结果规模,必要时先计数或分页。
  2. 小结果直接返回;大结果分页、摘要或给资源 URI。
  3. 客户端按需读取后续页或引用资源,而不是一次全量塞入。

代码或图示

@mcp.tool
def list_items(page: int = 1, size: int = 20) -> dict:
    total = repo.count()
    return {"page": page, "size": size, "total": total, "items": repo.page(page, size)}

常见误区

  • 工具返回全表明细:上下文与报文双重失控,模型只能看到截断内容。
  • 嵌套对象保留全部原始字段:冗余字段放大体积,应投影出需要的字段。

追问

  • 大文件怎么返回?答:给资源 URI 或外部链接,按需读取,不嵌入响应。
  • 分页参数需要写进 schema 吗?答:需要,page/size 作为工具入参并约束范围。
  • 结果大小有硬性上限吗?答:上限取决于传输、代理与客户端;服务端应设阈值并压测,大结果分页或改 URI 引用。

04.7.18.2-056 装饰器参数 name/description/title 如何覆盖默认元数据?

一句话结论

装饰器可通过参数覆盖工具/资源/提示的名称、描述等元数据,覆盖函数名与 docstring 默认值。FastMCP 2.x 装饰器支持 name=、description=、tags=、meta=、enabled=、annotations= 等参数覆盖元数据。显式覆盖适合重命名内部函数为对外稳定工具名,或补充更面向使用方的描述。

概念解释

  • 名称覆盖:对外工具名稳定,不受内部函数改名影响。
  • 描述覆盖:补充用途、边界与示例,替代 docstring 首段。
  • 优先级:显式 description= 参数优先于 docstring。

原理流程

  1. 注册时读取装饰器参数,缺省回退函数名/docstring。
  2. 覆盖值写入组件元数据。
  3. list 清单输出覆盖后的名称与描述。

代码或图示

@mcp.tool(name="create_ticket", description="创建工单并返回工单号。")
def _make_ticket(title: str) -> dict:
    return {"ticket_id": "T-1"}

常见误区

  • 内部函数改名后对外工具名跟着变:应显式固定对外名称,避免调用方断裂。
  • 装饰器描述与 docstring 不一致:显式 description= 参数优先于 docstring,两处说法应保持一致。

追问

  • 资源 URI 能在装饰器覆盖吗?答:URI 是资源注册必填项,在装饰器首参传入。
  • 提示名覆盖同理吗?答:@mcp.prompt(name=, description=, title=) 同样支持显式覆盖。
  • 覆盖参数会进 schema 吗?答:名称描述进组件元数据,不进 inputSchema 字段约束。

04.7.18.2-057 组件清单的输出顺序可控吗?

一句话结论

清单通常按注册顺序输出:装饰器与程序化注册的先后决定 list 排列,FastMCP 2.x 按内部清单注册顺序输出;跨版本不承诺自定义排序键。需要稳定分组展示时,可按标签或模块顺序规划注册顺序,但不要依赖未承诺的排序约定做跨版本集成。

概念解释

  • 注册顺序:模块内装饰器执行顺序、批量添加顺序。
  • 展示顺序:客户端 UI 可能按清单顺序分组展示。
  • 稳定性:版本升级后排序规则可能变化,集成不应硬依赖位置。

原理流程

  1. 按规划顺序注册组件,同类组件集中登记。
  2. list 遍历内部清单按注册顺序输出。
  3. 客户端按标签分组或按清单顺序展示。

代码或图示

@mcp.tool
def alpha() -> str:
    return "a"

@mcp.tool
def beta() -> str:
    return "b"

常见误区

  • 用清单位置判断组件身份:身份应按名称匹配,位置仅用于展示。
  • 运行期动态增删后期望顺序保持:动态变更后顺序按实现规则重排。

追问

  • 能按名称或标签排序输出吗?答:框架不提供自定义排序键;分组展示由客户端按标签完成。
  • 清单顺序影响模型选择吗?答:模型主要依据名称与描述,顺序影响较小。
  • 多实例组合后顺序如何?答:按挂载/并入顺序追加到父实例清单。

04.7.18.2-058 工具异常如何转换为协议错误返回?

一句话结论

工具抛出的异常在框架边界被捕获:可识别的业务异常映射到自定义错误码与安全 message,未捕获异常兜底为内部错误并记录堆栈。异常不应裸冒泡到传输层,对外错误不泄露堆栈、密钥与内部路径。

概念解释

  • 业务异常:领域类型(未找到、冲突、权限不足)映射错误码与 data。
  • 未捕获异常:兜底内部错误,完整堆栈落服务端日志。
  • 错误脱敏:message 面向调用方,data 只放必要结构化细节。

原理流程

  1. 工具函数执行抛出异常。
  2. 框架边界按异常类型映射错误对象:code/message/data。
  3. 响应以 error 返回;未映射异常记日志后兜底内部错误。

代码或图示

class NotFoundError(Exception):
    pass

@mcp.tool
def get_order(order_id: str) -> dict:
    order = repo.find(order_id)
    if order is None:
        raise NotFoundError("订单不存在")
    return order

常见误区

  • 工具内吞掉异常返回空结果:调用方无法区分成功与失败,应显式报错。
  • 对外返回 traceback:泄露实现细节,可能含敏感路径与参数。

追问

  • 异常映射表写在哪里?答:框架边界或统一错误处理层,按异常类型集中配置。
  • 下游超时算哪类错误?答:业务/外部依赖错误,包装后返回,不当成内部崩溃。
  • 校验异常与业务异常区分吗?答:参数格式问题归协议参数错误,领域规则失败归业务错误。

04.7.18.2-059 类型映射中有哪些需要按实际版本验证的待确认项?

一句话结论

版本敏感点包括:装饰器返回值类型、构造器默认名与默认 version、输入/输出 schema 开关、联合类型 schema 表达、Context 方法清单与取消 API、资源 MIME 推断规则、动态注册 API 名称、重复策略默认值。这些不能凭印象写死,应在目标版本读类型定义、跑最小用例观察报文后固化结论。

概念解释

  • 版本敏感分类:API 命名、参数默认值、生成字段、行为开关。
  • 验证方法:文档迁移说明 → 源码类型定义 → 内存内 client 实跑 → 记录实际报文。
  • 真正未核实的项标注验证点,不编造确定行为。

原理流程

  1. 列出影响契约的版本敏感点清单。
  2. 在当前安装版本逐一核对文档、源码与运行报文。
  3. 把核实结论写入测试断言;未核实项保留标注。

代码或图示

文档/迁移说明 -> 类型定义 -> 最小用例实跑 -> 记录报文 -> 更新断言

常见误区

  • 照搬旧版示例到新版本:API 重命名、参数顺序、默认值都可能变。
  • 把未核实假设写成对外承诺:未验证行为不应出现在接口文档中。

追问

  • 如何查本地框架版本?答:pip show fastmcp 查依赖版本,对照该版本文档与类型定义。
  • 未核实项何时移除?答:在目标版本观察到确定报文并补充断言后移除标注。
  • 其他语言 SDK 能作为 Python API 依据吗?答:不能,各语言实现命名与默认值可能不同。

04.7.18.2-060 本章 schema 边界:哪些内容不属于工具/资源/提示注册范畴?

一句话结论

本页覆盖服务端组件注册与 schema 生成:签名到类型映射、描述约束、Context 注入、返回内容块、模型入出参、资源 URI 与提示模板、动态注册与冲突策略。模型调用、RAG 检索、Agent 编排、工具链规划与 LangChain 类集成不属于本页,归入 AI 应用开发分册。

概念解释

  • 本页职责:把 Python 函数变成协议可发现、可调用的组件,并保证 schema 契约清晰。
  • 非本页:选模型、拼上下文、知识库检索、多工具决策与多轮编排。
  • 边界价值:框架题库聚焦能力提供方,不混入应用编排逻辑。

原理流程

  1. 判断题目是“组件如何注册与契约如何生成”还是“模型如何决策编排”。
  2. 前者归入本页;后者归入 AI 应用开发分册。
  3. 跨边界话题只在服务端接口处提及,不展开编排细节。

代码或图示

本页: 注册装饰器, schema 生成, Context, 内容块, 模型参数, 资源/提示模板
非本页: 模型选择, RAG, Agent 规划, 编排框架

常见误区

  • 在工具里硬编码多步规划与模型提示:那是应用层职责,工具应保持单一动作粒度。
  • 把客户端上下文拼装写进服务端文档:上下文管理发生在客户端一侧。

追问

  • 工具能调外部 API 吗?答:可以,执行外部动作是工具正常职责;编排模型调用不属于本框架边界。
  • Context 的 sampling 怎么理解?答:协议允许的服务端反向请求客户端模型能力,具体编排仍在客户端。
  • 跨分册引用如何标注?答:说明调用方职责归属,不展开应用层实现。

本节高频题

  • @mcp.tool 注册与同步/异步函数(001、002)
  • 签名到 JSON Schema 生成流程(003、004、005)
  • 基本/集合/联合/枚举类型映射(006、007、008)
  • Field 约束与参数描述(009、010、025)
  • docstring 到工具描述(011、012)
  • Context 注入、日志、进度、资源读取(013、014、015、016、017)
  • 文本/结构化/媒体返回内容块(018、019、020、026)
  • Pydantic 模型入参出参与嵌套联合(021、022、023、024)
  • 资源静态/模板/MIME/订阅(028、029、030、031)
  • 提示模板、Message 返回与参数 schema(033、034、035、036)
  • 动态注册、条件暴露与标签过滤(037、038、039)
  • 重名冲突策略(027、040)
  • 长任务超时与取消配合(041、042)
  • 严格校验模式(043)
  • schema 质量与调用成功率(044、045)
  • 非原生类型序列化与大结果控制(054、055)
  • 异常转协议错误(058)
  • 版本敏感项与验证方法(059)