Q: FastMCP のパラメータなしツールの説明に Returns セクションが含まれるのはなぜですか？

これは FastMCP 3.4.7 における docstring パース処理のバグです。`parse_docstring()` は、パーサーが `parameters` セクションも検出した場合にのみ、抽出された説明を使用します。パラメータを持たないツールでは、パース処理が生の docstring にフォールバックするため、`Returns:`、`Yields:`、`Raises:` の各セクションがクライアントに表示される説明に混入してしまいます。この修正では、パラメータが見つからない場合でも、抽出された最適な説明を保持するようにパーサーが更新されています。issue #4952 の修正を含む FastMCP リリースにアップグレードしてください。回避策としては、説明を明示的に設定します： ```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:` セクションを削除してください。

Question 1

FastMCP で /tools/{name}/disable?version=v1 を呼び出した後に tools/list で発生する「'str' object has no attribute 'matches'」というエラーはどうすれば修正できますか?

Accepted Answer

これは、component-managerルートが生の`?version=`クエリ文字列を`Provider.enable/disable`に渡すことが原因です。このAPIは`VersionSpec`オブジェクトを期待しています。その壊れた文字列がvisibility変換で使用され、それ以降のすべての`tools/list`が失敗するようになります。

一時的な回避策:
1. クエリパラメータなしでルートを呼び出す:
   ```bash
   curl -X POST http://localhost:8000/tools/mytool/disable
   ```
2. 不正な状態がすでに保存されている場合は、FastMCPサーバーを再起動/再作成する。
3. バージョンを指定する必要がある場合は、HTTPルートを使用する代わりに、`VersionSpec`を使ってプロバイダーAPIを直接呼び出す。

恒久的な修正: component-managerの修正を含むFastMCPリリースにアップグレードするか、プロバイダーに渡す前にパラメータを変換するようにルートハンドラーにパッチを適用する:
   ```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に影響します。`client_supports_extension()`は`session.client_params`が`None`の場合に早期リターンしますが、リクエストごとのエンベロープでは`clientInfo`はオプションであるため、`session.client_capabilities.extensions`が設定されている場合でも`client_params`が存在しないことがあります。回避策として、`client_supports_extension()`を呼び出す代わりに、capabilitiesを直接確認してください:

```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_params`の存在を要求するのではなく、`session.client_capabilities`を使用するように修正する必要があります。その修正がリリースされたら、FastMCPをアップグレードしてください。

Question 3

FastMCPのタスク対応ツールが、引数が欠落している場合や不明な場合に、バリデーションエラーではなく汎用的な「Error calling tool」を返すのはなぜですか？

Accepted Answer

この問題は、タスク送信時に引数の型は検証されるものの、タスクをエンキューする前に呼び出し全体の形状が検証されなかったため、FastMCP 4.0.12.dev で発生します。必須引数の欠落や予期しない引数は、ワーカーが関数を実行した時点で初めて検出され、特に `mask_error_details=True` の場合、内容のわかりにくいタスクエラーが発生していました。

「Reject missing and unexpected arguments at task submission」という修正を含む FastMCP リリースにアップグレードしてください：

```bash
pip install -U fastmcp fastmcp-tasks
```

アップグレード後は、タスク対応ツールが送信時に引数を検証し、同期ツールと同じ Pydantic バリデーションエラー（`Missing required argument` や予期しない引数に関するエラーなど）を返します。

一時的な診断用の回避策として、`mask_error_details=False` を設定するか、タスク対応ツールを呼び出す前にツールのスキーマに対してペイロードを検証してください。

Question 4

SKILL.md ファイルが有効な UTF-8 ではない場合に発生する SkillsDirectoryProvider の UnicodeDecodeError を修正するにはどうすればよいですか？

Accepted Answer

FastMCP 4.0.11.dev では、無効な UTF-8 の `SKILL.md` が 1 つあるだけで、`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 パース処理のバグです。parse_docstring() は、パーサーが parameters セクションも検出した場合にのみ、抽出された説明を使用します。パラメータを持たないツールでは、パース処理が生の docstring にフォールバックするため、Returns:、Yields:、Raises: の各セクションがクライアントに表示される説明に混入してしまいます。この修正では、パラメータが見つからない場合でも、抽出された最適な説明を保持するようにパーサーが更新されています。issue #4952 の修正を含む FastMCP リリースにアップグレードしてください。回避策としては、説明を明示的に設定します：

@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: セクションを削除してください。

```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 プレビュー

FAQ (5)

同类型项目

tensorflow

superpowers

everything-claude-code

flutter