fastmcp-django

Django での FastMCP

FastMCP を使用して、小規模で型付けされた Django アプリケーションの機能をエージェントに公開します。 認証、権限、検証、モデル、トランザクション、ビジネスルールの信頼できる情報源として Django を維持します。既存のアプリケーションサービスを囲むプロトコル層として FastMCP を扱います。

ツールの選択

• Django で新たに Python MCP を実装する場合は、スタンドアロンの fastmcp パッケージ（from fastmcp import FastMCP）を優先します。
• プロジェクトですでに標準として採用されている場合、より低レベルのプロトコル制御が必要な場合、またはホストが SDK の動作を明示的に要求する場合は、公式の MCP Python SDK（from mcp.server.fastmcp import FastMCP）を使用します。
• WSGI 内で動作する Django ネイティブのパッケージや、モデル／DRF API を宣言的に公開するパッケージが必要な場合に限り、django-mcp-server を検討します。非公開データを公開する前に、生成されたツールのコントラクトと権限を監査してください。
• アプリに意図的に設計された公開 OpenAPI サーフェスがすでにある場合は、最初の段階で生成ツールやプロキシツールが役立つことがあります。本番環境のエージェントでは、目的に合わせて設計した名前、スキーマ、権限、上限付きの出力を備えた、手作業で厳選したツールを優先します。

FastMCP のドキュメントはプロジェクトの main ブランチを対象としているため、最近追加された機能やバージョンバッジを利用する場合は、最新のドキュメントを再確認してください。

リソースの案内

現在のタスクに必要なファイルだけを読み込みます。

必要な内容	参照先
既存の Django アプリへの段階的な実装手順	workflows/add-fastmcp-to-django.md
stdio、HTTP サイドカー、ASGI マウント、パスプレフィックスの例	references/transports.md
ツールのコントラクト設計、ORM の境界、非同期処理のルール、リソース、プロンプト	references/tool-design.md
認証、デプロイ、テスト、ローカルチェック、デバッグ時の症状	references/auth-deployment-testing.md

実装ワークフロー

1. まず既存の Django エントリーポイントを確認します。manage.py、設定、asgi.py、wsgi.py、URL ルーティング、認証ミドルウェア、API、バックグラウンドジョブ、デプロイファイルを確認してください。
2. トランスポートの境界を選択します。
   • アプリと並行して動作するローカルのデスクトップ／エディター用 MCP サーバーには、stdio を使用します。
   • Django が WSGI のみで動作する場合、または MCP を独立してスケールさせる場合は、FastMCP の HTTP サイドカーを分離して使用します。
   • アプリがすでに ASGI 上で動作し、プロセス／ドメインの共有が意図的な場合は、FastMCP を Django の ASGI プロセスにマウントします。
3. MCP サーバーの登録処理は、apps/core/mcp.py や project/mcp.py などの小さなモジュールに置きます。
4. ツールの本体は薄く保ちます。既存のサービス、セレクター、フォーム、シリアライザー、ポリシーメソッド、ドメイン関数を呼び出してください。
5. トランスポートを接続する前に、fastmcp.Client を使ってテストを追加します。ほとんどの動作は、Web サーバーを起動せずにメモリ内でテストできます。

基本ルール

• 公開する機能はすべて明示的にします。明確な許可リストと認可計画がない限り、汎用 SQL、汎用モデル閲覧、任意のインポート、ファイルパスへのアクセス、「管理者」ツールは避けてください。
• 型付きパラメーター、Pydantic の制約、戻り値の型アノテーション、ドックストリング、小さく JSON シリアライズ可能な戻り値を使用します。
• Django モデルインスタンス、リクエストオブジェクト、遅延評価されるクエリーセット、オープン中のファイル、大きなペイロードではなく、永続的な識別子を渡します。
• リスト／検索ツールにはページネーションと上限を設けます。モデルの全データではなく、安定した ID と要約を返します。
• 検証済みの認証コンテキストまたは信頼できる依存関係から現在のユーザー／アカウントを注入します。本番環境では、モデルに特権的な ID フィールドを指定させないでください。
• プロジェクトに明確な非同期設計がない限り、通常の Django ORM 処理には同期の def FastMCP ツールを使用します。
• 長時間稼働する MCP プロセスでは、ORM 処理の前後に close_old_connections() を呼び出すか、薄いヘルパーに接続のクリーンアップを集約します。
• 処理に時間がかかるツールや外部依存のツールにはタイムアウトを設定します。MCP リクエストを開いたままにせず、長時間かかる処理はキューに登録します。

検証

• ツールの契約が重要な場合は、fastmcp list または fastmcp inspect を使用してツール名、スキーマ、説明を確認します。
• アクセス制御されたすべてのツールについて、許可されたユーザーと拒否されたユーザーをテストします。
• 無効な入力、存在しないオブジェクト、ページネーションの上限、破壊的な操作の確認、データベースの状態変更、transaction.on_commit による副作用をテストします。
• ASGI のマウント、認証ヘッダー、プロキシの動作、URL パスを変更した場合は、HTTP トランスポートのスモークテストを 1 つ追加します。

参考資料

• FastMCP のドキュメント：https://gofastmcp.com/getting-started/welcome
• FastMCP の GitHub：https://github.com/PrefectHQ/fastmcp
• FastMCP の HTTP デプロイ：https://gofastmcp.com/deployment/http
• FastMCP のテスト：https://gofastmcp.com/development/tests
• FastMCP のツール：https://gofastmcp.com/servers/tools
• FastMCP の認証：https://gofastmcp.com/servers/auth/authentication
• FastMCP の依存性注入：https://gofastmcp.com/servers/dependency-injection
• Django の非同期サポート：https://docs.djangoproject.com/en/5.2/topics/async/
• Django の ASGI デプロイ：https://docs.djangoproject.com/en/5.2/howto/deployment/asgi/