MCP Tool Descriptions Visibility Fix (2026-05-09)

症状 (Symptoms)

AIエージェントの開発中、以下のような不可解な現象に遭遇することがあります。

• AIエージェントがMCPツールの説明（Description）を読み取れず、ツールの用途を正しく理解できない。
• クライアントUI（Claude Desktopや独自UI）上でツールの説明欄が空、または「This is a tool from...」といったデフォルトの定型文のみが表示される。
• サーバー側でdocstringを詳細に記述しているにもかかわらず、メタデータとして全く反映されない。

これは、エージェントがツールを選択する際の「判断材料」を失っている状態であり、エージェントの推論能力を著しく低下させます。

---

原因 (Causes)

徹底的なデバッグの結果、この問題には「SDKの仕様」と「OSレベルの挙動」の2つの側面があることが判明しました。

1. docstring抽出の不安定性

fastmcp または mcp SDKのバージョンにより、docstringのパース挙動が変化します。 特に、以下のようなケースで抽出結果が空になることがあります。

• 3連クォート (""") の直後が改行で始まっている。
• 型ヒントや複雑な引数構成により、パーサーがdocstringの開始位置を見失う。
• ビルド環境や実行環境による __doc__ 属性の不整合。

2. ゾンビプロセスの影響 (Windows特有)

Windows環境での開発において最も厄介なのが、**「古いプロセスの生存」**です。

• サーバーコードを修正して再起動したつもりでも、古いプロセスがポート（例: 8377）を占有し続け、古いコード（修正前）をサーブし続ける。
• Windowsの taskkill が権限やタイミングにより失敗し、サイレントに古いプロセスが生き残る。
• 結果として、「コードは直したはずなのに、エージェントには古い（説明がない）情報が伝わり続ける」という迷宮に陥ります。

---

解決策 (Resolution)

この問題を根絶するために、以下の対策を講じました。

1. 明示的なメタデータ定義

docstring に依存するのではなく、デコレータレベルで明示的に説明を流し込みます。

# 改善前
@mcp.tool()
def my_tool(param: str):
    """
    ここに説明を書いても抽出されないことがある
    """
    pass

# 改善後：description引数で直接指定
@mcp.tool(description="このツールは、指定されたパラメータに基づいて明確なアクションを実行します。")
def my_tool(param: str):
    pass

また、FastMCP() コンストラクタに instructions 引数を追加し、サーバー全体の役割を定義することも有効です。

2. プロセスの強制終了とクリーンな起動

Windowsでは、単なる終了ではなく「ポートを占有しているプロセスの確実な特定と終了」が必要です。

# ポート8377を占有しているPIDを特定し、強制終了
netstat -ano | findstr :8377
taskkill /F /PID <特定したPID>

3. SDKパッチとバリデーションの調整

内部的なJSON-RPCのバリデーションがメタデータの伝播を阻害していないか確認し、最新のSDK仕様に合わせた調整を行いました。

---

予防策 (Prevention)

今後の開発において、同様の「説明消失」を防ぐためのガイドラインを策定しました。

1. デコレータへの description 指定を必須化: docstringは開発者向け、description はAIエージェント向けとして分離管理する。
2. 起動ログの強化: サーバー起動時に instructions や登録されたツール数を出力し、最新のコードが正しく読み込まれているか視覚的に確認できるようにする。
3. Windows開発時の「ポート解放確認」の習慣化: サーバーが正しく入れ替わったか、netstat 等で明示的に確認する。

---

専門家からの視点

このトラブルシューティングは、MCPという「LLMとシステムを繋ぐ標準プロトコル」の実践において極めて重要です。エージェントが「何を、なぜ、どのように使うべきか」を理解するためのメタデータは、プロンプトエンジニアリングと同等、あるいはそれ以上にシステムの信頼性に直結します。

Ayato Studioでは、こうした微細な「情報の不整合」を徹底的に排除し、AIエージェントが真の能力を発揮できる環境を構築し続けます。