Python MCP サーバーを生成

以下の仕様に従って、完全な Model Context Protocol (MCP) サーバーを Python で作成します:

要件

1. プロジェクト構造: uv を使用して適切な構造を持つ新しい Python プロジェクトを作成
2. 依存関係: uv で mcp[cli] パッケージをインクルード
3. トランスポートタイプ: stdio (ローカル用) または streamable-http (リモート用) から選択
4. ツール: 適切な型ヒント付きで、最低 1 つの有用なツールを作成
5. エラーハンドリング: 包括的なエラーハンドリングと入力検証をインクルード

実装の詳細

プロジェクトセットアップ

• uv init project-name で初期化
• MCP SDK を追加: uv add "mcp[cli]"
• メインサーバーファイルを作成 (例: server.py)
• Python プロジェクト用の .gitignore を追加
• if __name__ == "__main__" で直接実行できるように構成

サーバー構成

• mcp.server.fastmcp から FastMCP クラスを使用
• サーバー名と任意の指示を設定
• トランスポートを選択: stdio (デフォルト) または streamable-http
• HTTP の場合: ホスト、ポート、ステートレスモードをオプションで構成

ツール実装

• 関数に @mcp.tool() デコレータを使用
• 常に型ヒントをインクルード - スキーマを自動生成
• わかりやすいドキュメント文字列を記述 - ツールの説明になる
• 構造化されたアウトプットに Pydantic モデルまたは TypedDict を使用
• I/O バウンドなタスクの非同期操作をサポート
• 適切なエラーハンドリングをインクルード

リソース/プロンプト設定 (オプション)

• @mcp.resource() デコレータでリソースを追加
• 動的リソースに URI テンプレートを使用: "resource://{param}"
• @mcp.prompt() デコレータでプロンプトを追加
• プロンプトから文字列またはメッセージリストを返す

コード品質

• すべての関数パラメータと戻り値に型ヒントを使用
• ツール、リソース、プロンプトのドキュメント文字列を記述
• PEP 8 スタイルガイドに従う
• 非同期操作に async/await を使用
• リソースクリーンアップにコンテキストマネージャーを実装
• 複雑なロジックにはインラインコメントを追加

考慮するツールタイプの例

• データ処理と変換
• ファイルシステム操作 (読み込み、分析、検索)
• 外部 API インテグレーション
• データベースクエリ
• テキスト分析またはジェネレーション (サンプリング付き)
• システム情報取得
• 数学または科学計算

構成オプション

• stdio サーバーの場合:

  • シンプルな直接実行
  • uv run mcp dev server.py でテスト
  • Claude にインストール: uv run mcp install server.py

• HTTP サーバーの場合:

  • 環境変数によるポート構成
  • スケーラビリティのためのステートレスモード: stateless_http=True
  • JSON レスポンスモード: json_response=True
  • ブラウザクライアント向け CORS 構成
  • 既存の ASGI サーバー (Starlette/FastAPI) へのマウント

テストガイダンス

• サーバーの実行方法を説明:
  • stdio: python server.py または uv run server.py
  • HTTP: python server.py を実行し、http://localhost:PORT/mcp に接続
• MCP Inspector でテスト: uv run mcp dev server.py
• Claude Desktop にインストール: uv run mcp install server.py
• ツール呼び出しの例を含める
• トラブルシューティングのヒントを追加

考慮する追加機能

• ロギング、プログレス、通知のためのコンテキスト使用
• AI パワード ツール用の LLM サンプリング
• インタラクティブワークフロー向けのユーザー入力要求
• 共有リソース (データベース、接続) 向けのライフサイクル管理
• Pydantic モデルを使用した構造化アウトプット
• UI 表示用のアイコン
• Image クラスを使用した画像処理
• より優れた UX のための補完サポート

ベストプラクティス

• 型ヒントをあらゆる場所で使用 - オプションではない
• 可能な限り構造化されたデータを返す
• stderr にログ出力 (またはコンテキストロギングを使用) - stdout を汚さない
• リソースを適切にクリーンアップ
• 早期に入力を検証
• 明確なエラーメッセージを提供
• LLM インテグレーション前にツールを個別にテスト

完全で本番対応の MCP サーバーを、型安全性、適切なエラーハンドリング、包括的なドキュメント付きで生成します。