【要約】MCP Python SDK 2.0 で自作サーバーが壊れた2つの原因（型ヒントが *args に潰れる話） [Zenn_Python] | Summary by TechDistill
> Source: Zenn_Python
Execute Primary Source
// Problem
PythonでMCPサーバーを開発するエンジニアが、SDKのバージョンアップやデコレータの実装において、予期せぬ動作に直面する。具体的には以下の問題が発生する。
- ・APIの仕様変更：旧来の
Serverクラスやlist_toolsを用いた実装が、SDK 2.0では動作しない。 - ・型ヒントの消失：例外処理等のためにデコレータを適用すると、関数のシグネチャが
*args, **kwargsに書き換わる。 - ・スキーマの不整合：SDKが書き換わったシグネチャを基にJSONスキーマを生成するため、本来の引数が認識されない。
- ・検知の困難さ：サーバーは正常に起動し、接続も可能であるため、実行時まで不具合に気づけない。
// Approach
開発者は、SDKの最新仕様への適応と、Pythonのメタプログラミングにおける適切な作法の適用によって問題を解決する。
- ・新APIへの移行：
MCPServerクラスと@server.tool()デコレータを使用し、ツールを個別に宣言する。 - ・functools.wrapsの活用：カスタムデコレータ内で
@functools.wraps(func)を記述し、元の関数のシグネチャを維持する。 - ・検証コードの導入：
inspect.signature()を用いて、実行時に引数リストが破壊されていないか自動チェックする仕組みを構築する。 - ・設計の分離：数値計算などの確定的な処理はLLMに任せず、サーバー側のPythonコードで完結させる。
// Result
適切な実装を行うことで、開発者はツール定義の正確性と、実行時の信頼性を確保できる。
- ・スキーマの整合性確保：デコレータ適用後も、LLMが正しく引数を認識できる状態を維持できる。
- ・デバッグコストの削減：
inspectを用いた自己診断により、スキーマ破壊を早期に検知可能となる。 - ・計算精度の向上：サーバー側で集計済みの値を返す設計により、LLMの計算ミスによる誤回答を防げる。
Senior Engineer Insight
> MCP SDK 2.0は型ヒントへの依存度が高く、デコレータによるメタデータの消失は「動くが、正しく動かない」という極めて危険な状態を招く。これは静的な型チェックでは検知できず、実行時のスキーマ不備として表面化する。大規模なツール群を運用する場合、
functools.wrapsの徹底と、inspectを用いたスキーマ検証の自動化をCI/CDパイプラインに組み込むことが、実戦投入における必須の防衛策である。