Django Ai Boost

🚀 Django AI Boost

Laravel Boostにインスパイアされた、Djangoアプリケーション開発用のModel Context Protocol (MCP)サーバーです。このサーバーは、MCPツールを通じてDjangoプロジェクトの情報を公開し、AIアシスタントがDjangoのコードベースをよりよく理解し、対話できるようにします。

🚀 クイックスタート

Django AI Boostは、Djangoアプリケーション開発において、AIアシスタントとの連携を強化するためのMCPサーバーです。以下の手順でインストールし、使用を開始できます。

✨ 主な機能

• プロジェクトの探索：モデル、URL、管理コマンドを一覧表示します。
• データベースの内省：スキーマ、マイグレーション、関係を表示します。
• 設定のアクセス：ドット表記でDjangoの設定を照会します。
• ログの閲覧：フィルタリング機能を使って最近のアプリケーションログにアクセスします。
• 読み取り専用：すべてのツールは安全な読み取り専用操作です。
• 高速：FastMCPをベースに構築されており、効率的な非同期操作を実現します。

📦 インストール

エンドユーザー向け

# uvを使用する場合（推奨）
uv pip install django-ai-boost

# またはpipを使用する場合
pip install django-ai-boost

開発用

開発に貢献したい場合や最新の開発バージョンを実行したい場合は、以下の手順を実行します。

# リポジトリをクローンする
git clone https://github.com/vinta/django-ai-boost.git
cd django-ai-boost

# uvがまだインストールされていない場合は、インストールする
# macOS/Linuxの場合:
curl -LsSf https://astral.sh/uv/install.sh | sh

# Windowsの場合:
powershell -c "irm https://astral.sh/uv/install.ps1 | iex"

# 依存関係をインストールする（自動的に仮想環境が作成されます）
uv sync --dev

# インストールを確認する
uv run django-ai-boost --help

💻 使用例

サーバーの実行

サーバーはDjangoプロジェクトの設定にアクセスする必要があります。

# Djangoの設定モジュールを設定する
export DJANGO_SETTINGS_MODULE=myproject.settings
django-ai-boost

# または設定を直接指定する
django-ai-boost --settings myproject.settings

# SSEトランスポートで実行する（デフォルトはstdioで、ネットワークポートを使用しません）
django-ai-boost --settings myproject.settings --transport sse

# カスタムポートでSSEトランスポートを使用する（デフォルトのポートは8000）
django-ai-boost --settings myproject.settings --transport sse --port 3000

# カスタムホストとポートでSSEトランスポートを使用する
django-ai-boost --settings myproject.settings --transport sse --host 0.0.0.0 --port 8080

⚠️ 重要提示

stdioトランスポート（デフォルト）は標準入出力を介して通信し、ネットワークポートを使用しません。--portと--hostオプションは--transport sseを使用する場合のみ適用されます。

AIツールの設定

Cursor

Cursorは、組み込みのMCPサポートを備えた人気のAIベースのコードエディターです。

1. Cursorの設定（Cmd/Ctrl + Shift + J）を開きます。
2. "Tools & MCP"セクションに移動します。
3. Django AI Boostサーバーの設定を追加します。

{
  "mcpServers": {
    "django-ai-boost": {
      "command": "django-ai-boost",
      "args": ["--settings", "myproject.settings"],
      "env": {
        "DJANGO_SETTINGS_MODULE": "myproject.settings",
        "PYTHONPATH": "/path/to/your/django/project"
      }
    }
  }
}

⚠️ 重要提示

/path/to/your/django/projectを実際のDjangoプロジェクトのルートディレクトリのパスに置き換えてください。 詳細については、Cursor MCPドキュメントを参照してください。

Claude Desktop

Claude Desktopの設定に追加します。

• macOS：~/Library/Application Support/Claude/claude_desktop_config.json
• Windows：%APPDATA%\Claude\claude_desktop_config.json
• Linux：~/.config/claude/claude_desktop_config.json

{
  "mcpServers": {
    "django": {
      "command": "django-ai-boost",
      "args": ["--settings", "myproject.settings"],
      "env": {
        "DJANGO_SETTINGS_MODULE": "myproject.settings",
        "PYTHONPATH": "/path/to/your/django/project"
      }
    }
  }
}

⚠️ 重要提示

/path/to/your/django/projectを実際のDjangoプロジェクトのルートディレクトリのパスに置き換えてください。

Github Copilot (VS Code拡張機能)

1. VS CodeマーケットプレイスからGithub Copilot Chat拡張機能をインストールします。
2. Djangoプロジェクトのルートに.vscode/mcp.jsonを作成または編集します。

{
"inputs": [
  // "inputs"セクションは、MCPサーバーの設定に必要な入力を定義します。
  {
    "type": "promptString"
  }
],
"servers": {
  // "servers"セクションは、使用するMCPサーバーを定義します。
  "django-ai-boost": {
    "command": "uv",
    "args": ["run", "django-ai-boost", "--settings", "myproject.settings"],
    "env": {
      "DJANGO_SETTINGS_MODULE": "myproject.settings"
    }
  }
 }
}

3. JSON内で"Start"をクリックします。
4. Github Copilot Codeは、"Agent"モードで会話を開始すると自動的にMCPサーバーに接続します。

Claude Code (VS Code拡張機能)

1. VS CodeマーケットプレイスからClaude Code拡張機能をインストールします。
2. Djangoプロジェクトのルートに.mcp.jsonを作成または編集します。

{
  "mcpServers": {
    "django-ai-boost": {
      "command": "uv",
      "args": ["run", "django-ai-boost", "--settings", "myproject.settings"],
      "env": {
        "DJANGO_SETTINGS_MODULE": "myproject.settings"
      }
    }
  }
}

3. VS Codeを再起動するか、Claude Code拡張機能を再読み込みします。
4. Claude Codeは、会話を開始すると自動的にMCPサーバーに接続します。

OpenAI ChatGPT Desktop with MCP

OpenAI ChatGPT DesktopはMCPサーバーをサポートしています。設定ファイルに追加します。

• macOS：~/Library/Application Support/OpenAI/ChatGPT/config.json
• Windows：%APPDATA%\OpenAI\ChatGPT\config.json

{
  "mcpServers": {
    "django": {
      "command": "django-ai-boost",
      "args": ["--settings", "myproject.settings"],
      "env": {
        "DJANGO_SETTINGS_MODULE": "myproject.settings"
      }
    }
  }
}

Cline (VS Code拡張機能)

1. VS CodeマーケットプレイスからCline拡張機能をインストールします。
2. Clineの設定（Cmd/Ctrl + Shift + P → "Cline: Open Settings"）を開きます。
3. MCPサーバーの設定をMCP Serversセクションに追加します。

{
  "django": {
    "command": "django-ai-boost",
    "args": ["--settings", "myproject.settings"],
    "env": {
      "DJANGO_SETTINGS_MODULE": "myproject.settings"
    }
  }
}

Zed Editor

ZedのMCP設定（~/.config/zed/mcp.json）に追加します。

{
  "servers": {
    "django": {
      "command": "django-ai-boost",
      "args": ["--settings", "myproject.settings"],
      "env": {
        "DJANGO_SETTINGS_MODULE": "myproject.settings"
      }
    }
  }
}

汎用MCPクライアント

MCP互換のクライアントでは、サーバーを手動で実行できます。

# 標準入出力トランスポート（デフォルト、ネットワークポートなし）
django-ai-boost --settings myproject.settings

# サーバー送信イベントトランスポート（デフォルト: 127.0.0.1:8000）
django-ai-boost --settings myproject.settings --transport sse

# カスタムポートでSSEトランスポートを使用する
django-ai-boost --settings myproject.settings --transport sse --port 3000

# カスタムホストとポートでSSEトランスポートを使用する
django-ai-boost --settings myproject.settings --transport sse --host 0.0.0.0 --port 8080

利用可能なツールとプロンプト

ツール

1. application_info

DjangoとPythonのバージョン、インストールされたアプリ、ミドルウェア、データベースエンジン、およびデバッグモードの状態を取得します。

2. get_setting

ドット表記を使用して任意のDjango設定を取得します（例：DATABASES.default.ENGINE）。

3. list_models

すべてのDjangoモデルを、フィールド、タイプ、max_length、null/blankの状態、および関係とともにリスト表示します。 引数:

• app_labels：フィルタリングするアプリラベルのオプションのリスト（例：["blog", "auth"]）。指定されない場合は、すべてのモデルが返されます。

⚠️ 重要提示

大規模なプロジェクトの場合、一部のMCPクライアント（PyCharmなど）は表示制限により出力を切り捨てる場合があります。切り捨てを避けるために、特定のアプリでフィルタリングするにはapp_labelsパラメーターを使用してください。詳細については、トラブルシューティングを参照してください。

4. list_urls

名前、パターン、およびビューハンドラー（ネストされたインクルードを含む）を含むすべてのURLパターンを表示します。

5. database_schema

テーブル、列、タイプ、インデックス、および外部キーを含む完全なデータベーススキーマを取得します。

6. list_migrations

各アプリのすべてのマイグレーションとその適用/未適用の状態を表示します。

7. list_management_commands

すべての利用可能なmanage.pyコマンドとそのソースアプリをリスト表示します。

8. get_absolute_url

特定のモデルインスタンスの絶対URLを取得します。モデルにget_absolute_url()メソッドが定義されている必要があります。 引数:

• app_label：Djangoアプリラベル（例："blog"）
• model_name：モデル名（例："Post"）
• pk：インスタンスの主キー

9. reverse_url

名前付きのURLパターンを逆引きして、実際のURLパスを取得します。位置引数とキーワード引数の両方をサポートします。 引数:

• url_name：URLパターン名（例："post_detail", "admin:index"）
• args：オプションの位置引数のリスト
• kwargs：オプションのキーワード引数の辞書

10. query_model

Django ORMマネージャーを使用して、読み取り専用操作でDjangoモデルをクエリします。このツールは、フィルタリング、並べ替え、およびページネーションを使用して、任意のDjangoモデルを安全にクエリできます。 引数:

• app_label：Djangoアプリラベル（例："blog"）
• model_name：モデル名（例："Post"）
• filters：オプションのフィールドルックアップの辞書（例：{"status": "published", "featured": true}）
• order_by：オプションの並べ替えるフィールドのリスト（例：["-created_at", "title"]）
• limit：返す最大結果数（デフォルト：100、最大：1000） 戻り値:
• 一致するオブジェクトの総数
• 返された結果の数
• すべてのフィールド値を持つ辞書としてのモデルインスタンスのリスト
• 外部キーの場合、IDと文字列表現の両方が含まれます クエリ例:
• すべての公開された投稿を取得する：filters={"status": "published"}
• 日付で並べ替えられた注目の投稿を取得する：filters={"featured": true}, order_by=["-created_at"]
• 制限付きで最近の投稿を取得する：order_by=["-created_at"], limit=10

11. read_recent_logs

ログレベル（DEBUG、INFO、WARNING、ERROR、CRITICAL）でオプションのフィルタリングを使用して、最近のログエントリを読み取ります。

プロンプト

MCPプロンプトは、AIアシスタントとの対話をガイドするための再利用可能なメッセージテンプレートを提供します。

1. search_django_docs

Djangoドキュメントで特定のトピックを検索するためのフォーマットされたプロンプトを生成します。 引数:

• topic：検索するDjangoのトピックまたは機能（例："models", "queryset", "migrations", "authentication"） 戻り値:
• 使用中の現在のDjangoバージョン
• 適切なバージョンのDjangoドキュメントへの直接リンク
• 探すべき情報に関するガイダンス
• ベストプラクティスとコード例の要求 を含むフォーマットされたプロンプト。 トピック例:
• "models" - DjangoモデルとORMについて学ぶ
• "queryset filtering" - クエリの最適化とフィルタリング
• "migrations" - データベーススキーマの管理
• "authentication" - ユーザー認証とパーミッション
• "middleware" - リクエスト/レスポンスの処理
• "forms" - フォームの処理と検証 このプロンプトは、ドキュメントの互換性を確保するために、Djangoバージョン（例：5.2、4.2）に自動的に適応します。

AIアシスタントとの使用例

設定が完了すると、AIアシスタントに以下のような質問をすることができます。

ツールの使用

• "このDjangoプロジェクトにはどのようなモデルがありますか？"
• "すべてのURLパターンを表示してください"
• "ユーザーテーブルのデータベーススキーマは何ですか？"
• "未適用のマイグレーションはありますか？"
• "DEBUG設定の値は何ですか？"
• "IDが5のブログ投稿のURLは何ですか？"
• "pk=10で'post_detail'のURLパターンを逆引きしてください"
• "すべての公開されたブログ投稿を表示してください"
• "作成日で並べ替えられた最近の10件の投稿を取得してください"
• "ブログ内のすべての注目の投稿を見つけてください"
• "最近のエラーログを表示してください"

プロンプトの使用

• "modelsについてのsearch_django_docsプロンプトを使用してください" - Djangoモデルのドキュメントを検索するのに役立ちます。
• "authenticationについてDjangoドキュメントを検索してください" - Djangoの認証について学びます。
• "migrationsに関するDjangoドキュメントを表示してください" - マイグレーションのベストプラクティスとガイドを参照します。

🔧 技術詳細

このプロジェクトには包括的なテストスイートと開発用のフィクスチャDjangoプロジェクトが含まれています。

# フィクスチャプロジェクトでMCPサーバーをテストする
uv run python test_server.py

# query_modelツールをテストする
uv run python test_query_model.py

# テストプロジェクトでMCPサーバーを実行する
export PYTHONPATH="${PYTHONPATH}:./fixtures/testproject"
uv run django-ai-boost --settings testproject.settings

# リンターを実行する
uv run ruff check .

# リントエラーを自動修正する
uv run ruff check --fix .

# コードをフォーマットする
uv run ruff format .

fixtures/testproject/ディレクトリには、すべてのMCPツールをテストするための完全なDjangoアプリケーションが含まれています。テストプロジェクトの構造の詳細については、fixtures/README.mdを参照してください。

トラブルシューティング

"Django is not configured"エラー

DJANGO_SETTINGS_MODULE環境変数を設定するか、--settingsフラグを使用していることを確認してください。

export DJANGO_SETTINGS_MODULE=myproject.settings
django-ai-boost

PYTHONPATHの問題

Djangoがプロジェクトモジュールを見つけられない場合は、プロジェクトディレクトリをPYTHONPATHに追加してください。

export PYTHONPATH="${PYTHONPATH}:/path/to/your/project"
django-ai-boost --settings myproject.settings

または、MCPクライアントの設定で：

{
  "env": {
    "PYTHONPATH": "/path/to/your/project",
    "DJANGO_SETTINGS_MODULE": "myproject.settings"
  }
}

MCPサーバーが接続されない

1. django-ai-boostコマンドがPATHに含まれていることを確認してください。
2. MCPクライアントの設定ファイルの構文が有効なJSONであることを確認してください。
3. AIツールのログを確認してください（通常は設定またはヘルプメニューにあります）。
4. エラーメッセージを確認するために、サーバーを手動で実行してみてください。

django-ai-boost --settings myproject.settings

データベース接続の問題

Djangoのデータベースが適切に構成され、アクセス可能であることを確認してください。MCPサーバーはDjangoアプリケーションと同じデータベースアクセスが必要です。

ポートが既に使用されている（SSEトランスポート）

SSEトランスポートを使用するときに"Address already in use"のようなエラーが表示される場合、デフォルトのポート8000が別のサービス（Django開発サーバーなど）によって使用されている可能性があります。別のポートを使用してください。

# MCPサーバーに別のポートを使用する
django-ai-boost --settings myproject.settings --transport sse --port 8001

⚠️ 重要提示

stdioトランスポート（デフォルト）はネットワークポートを使用せず、この問題は発生しません。

MCPクライアントでの出力の切り捨て

一部のMCPクライアントは、長いツールの出力を切り捨てる表示制限があります。 PyCharm：ツールの出力を2000行に制限します（典型的なフィールド数で約100のDjangoモデル） Claude Code：ターミナル表示で約700文字で切り捨てます。 症状:

• "output truncated due to length"というメッセージ
• list_modelsを呼び出したときに不完全なモデルリスト 解決策: app_labelsパラメーターを使用して、特定のDjangoアプリでモデルをフィルタリングします。

# すべてのモデルをリスト表示する代わりに（切り捨てる可能性があります）:
list_models()

# 特定のアプリでフィルタリングする:
list_models(app_labels=["blog"])
list_models(app_labels=["blog", "auth", "contenttypes"])

検証: 切り捨てはサーバーではなくクライアント側で発生しています。検証するには：

1. Djangoモデルの数を数えます：python manage.py shell -c "from django.apps import apps; print(len(apps.get_models()))"
2. 行数を見積もります：モデル数 × モデルあたり20行 ≈ 総出力行数
3. 2000行（PyCharm）より多い場合、または非常に大きい場合（Claude Code）は、アプリフィルタリングを使用してください。

必要条件

• Python 3.12以上
• Django 4.2以上
• FastMCP 2.12.4以上

📄 ライセンス

MITライセンス - 詳細については、LICENSEファイルを参照してください。

インスピレーション

このプロジェクトは、Laravelアプリケーションに同様のMCP機能を提供するLaravel Boostにインスパイアされています。

コントリビューション

はじめるに

1. GitHubでリポジトリをフォークします。
2. フォークをローカルにクローンします。

git clone https://github.com/YOUR_USERNAME/django-ai-boost.git
cd django-ai-boost

3. 開発用の依存関係をインストールします。

uv sync --dev

4. 変更用の新しいブランチを作成します。

git checkout -b feature/your-feature-name
# または
git checkout -b fix/your-bug-fix

開発ワークフロー

1. 機能ブランチで変更を加えます。
2. コードスタイルに従います。

# コードスタイルをチェックする
uv run ruff check .

# スタイルエラーを自動修正する
uv run ruff check --fix .

# コードをフォーマットする
uv run ruff format .

3. 変更をテストします。

# テストスイートを実行する
uv run python test_server.py

# フィクスチャプロジェクトでテストする
export PYTHONPATH="${PYTHONPATH}:./fixtures/testproject"
uv run django-ai-boost --settings testproject.settings

4. 変更をコミットします。

git add .
git commit -m "feat: add new feature" # または "fix: resolve bug"

Conventional Commitsに従っています：

• feat:：新機能
• fix:：バグ修正
• docs:：ドキュメントの変更
• chore:：メンテナンスタスク
• test:：テストの変更
• refactor:：コードのリファクタリング

5. フォークにプッシュします。

git push origin feature/your-feature-name

6. GitHubでフォークからメインリポジトリへのプルリクエストを作成します。

コントリビューションガイドライン

• コード品質：コードがリント（ruff check）とフォーマット（ruff format）を通過することを確認してください。
• テスト：新機能にテストを追加し、既存のテストが通過することを確認してください。
• ドキュメント：新機能についてREADMEと関連するドキュメントを更新してください。
• コミット：Conventional Commitsに従って、明確で説明的なコミットメッセージを使用してください。
• プルリクエスト：プルリクエストが何を行うか、およびその理由を明確に説明してください。
• 問題：新しい問題を作成する前に、既存の問題を確認してください。

コントリビュートする内容

特に興味があるのは：

• 新しいMCPツール：より多くのDjango機能を公開する新しいツールを追加する。
• バグ修正：GitHub Issuesで報告された問題を修正する。
• ドキュメント：セットアップガイドを改善し、例を追加し、または既存のドキュメントを明確にする。
• テスト：既存の機能のテストカバレッジを拡張する。
• パフォーマンス：低速な操作を最適化するか、メモリ使用量を削減する。
• 互換性：異なるDjangoバージョンとの互換性を確保する。

ヘルプが必要ですか？

• 既存のコードを例として見てください。
• 質問や議論のためにGitHub Issueを開いてください。
• 他の人がどのようにコントリビュートしたかを確認するには、閉じられたプルリクエストをレビューしてください。

行動規範

すべての対話で礼儀正しく建設的であるようにしてください。歓迎され、包括的なコミュニティを維持することを目指しています。

商用サポート

このプロジェクトはVinta Softwareによってメンテナンスされています。私たちのデザインと開発の専門家チームは、あなたの会社が成功したDjangoベースの製品を立ち上げるのを支援することができます。商用サポートが必要な場合は、お気軽にご連絡ください：contact@vinta.com.br