Question 1

如何修复在调用 /tools/{name}/disable?version=v1 之后 FastMCP tools/list 中出现的 "'str' object has no attribute 'matches'" 错误?

Accepted Answer

这是由 component-manager 路由将原始的 `?version=` 查询字符串传递给 `Provider.enable/disable` 导致的，而后者期望的是一个 `VersionSpec` 对象。随后，这个损坏的字符串被可见性转换（visibility transform）使用，导致之后每次 `tools/list` 调用都失败。

临时解决方法：
1. 调用路由时不带查询参数：
   ```bash
   curl -X POST http://localhost:8000/tools/mytool/disable
   ```
2. 如果错误状态已经被存储，请重启/重新创建 FastMCP 服务器。
3. 如果必须指定某个版本，请直接使用 `VersionSpec` 调用 provider API，而不是使用 HTTP 路由。

永久修复：升级到包含 component-manager 修复的 FastMCP 版本，或者修补路由处理器，在将参数传递给 provider 之前先进行转换：
   ```python
   raw_version = request.query_params.get("version")
   version = VersionSpec(eq=raw_version) if raw_version else None
   await provider.disable(name=name, version=version)
   ```
在对应的 enable 路由中应用相同的转换。该问题已在 FastMCP `4.0.11.dev1+0ebabc0c` 上复现。

Question 2

为什么当 client_capabilities.extensions 中包含该扩展时，FastMCP 的 client_supports_extension 却返回 False？

Accepted Answer

此问题影响使用 mcp 2.2.0 和协议版本 2026-07-28 的 fastmcp 4.0.5。当 session.client_params 为 None 时，client_supports_extension() 会提前返回，但 clientInfo 在每个请求的信封中是可选的，因此即使 session.client_capabilities.extensions 已被填充，client_params 也可能不存在。作为一种临时解决方法，请直接检查 capabilities，而不是调用 client_supports_extension()：

```python
from fastmcp.server.dependencies import get_context

ctx = get_context()
caps = ctx.session.client_capabilities
supported = bool(
    caps is not None
    and caps.extensions is not None
    and "io.modelcontextprotocol/ui" in caps.extensions
)
```

永久修复方法是让 client_supports_extension() 使用 session.client_capabilities，而不是要求 session.client_params 必须存在。待该修复发布后，请升级 FastMCP。

Question 3

为什么启用任务的 FastMCP 工具在参数缺失或未知时，返回通用的 "Error calling tool" 而不是验证错误？

Accepted Answer

在 FastMCP 4.0.12.dev 中会出现此问题，因为任务提交时仅校验了参数类型，而未在将任务加入队列之前校验完整的调用形式。缺少必需参数或传入意外参数的问题，只有在 worker 执行函数时才会被检测到，从而产生不透明的任务错误，尤其是在 mask_error_details=True 的情况下。

升级到包含 "Reject missing and unexpected arguments at task submission" 修复的 FastMCP 版本：

pip install -U fastmcp fastmcp-tasks

升级后，启用任务（task-enabled）的工具会在提交时校验参数，并返回与同步工具相同的 Pydantic 校验错误，例如 Missing required argument 或意外参数错误。

作为临时诊断变通方法，可设置 mask_error_details=False，或在调用启用任务的工具之前，根据该工具的 schema 校验 payload。

Question 4

当 SKILL.md 文件不是有效的 UTF-8 编码时，如何修复 SkillsDirectoryProvider UnicodeDecodeError？

Accepted Answer

在 FastMCP 4.0.11.dev 中，一个无效的 UTF-8 `SKILL.md` 文件就可能导致 `SkillsDirectoryProvider` 无法加载任何技能。请将有问题的文件转换为 UTF-8，或将其从技能目录中移除。对于 UTF-16 文件，请运行：`iconv -f UTF-16 -t UTF-8 bad/SKILL.md -o bad/SKILL.md.utf8 && mv bad/SKILL.md.utf8 bad/SKILL.md`。使用 Python 时，可以通过 `Path.read_text(encoding="utf-16").encode("utf-8")` 检测并重写该文件。转换完成后，重启提供程序；有效的技能应能正常加载。

Question 5

为什么 FastMCP 无参数工具的描述中会包含 Returns 部分？

Accepted Answer

这是 FastMCP 3.4.7 中的一个 docstring 解析 bug。`parse_docstring()` 只有在同时找到 `parameters` 部分时才会使用解析器提取的描述。对于没有参数的工具，解析会回退到原始 docstring，因此 `Returns:`、`Yields:` 和 `Raises:` 部分会泄漏到客户端可见的描述中。该修复更新了解析器，使其即使在没有找到任何参数时也能保留最佳提取描述；请升级到包含 issue #4952 修复的 FastMCP 版本。作为变通方法，可以显式设置 description：

```python
@mcp.tool(description="Return current status.")
async def status() -> dict[str, bool]:
    """Return current status.

Returns:
        A dict containing the current status.
    """
    return {"ok": True}
```

或者，在升级之前，从工具的 docstring 中移除 `Returns:`/`Yields:`/`Raises:` 部分。

fastmcp

项目简介

README 预览

常见问题 (5)

同类型项目

tensorflow

superpowers

everything-claude-code

flutter