Django Ai Boost

🚀 Django AI Boost

Django AI Boost 是一個受 Laravel Boost 啟發而開發的 Model Context Protocol (MCP) 服務器，專為 Django 應用程序打造。該服務器通過 MCP 工具展示 Django 項目信息，使 AI 助手能夠更好地理解和與 Django 代碼庫進行交互。

🚀 快速開始

Django AI Boost 是一個強大的工具，可助力 AI 助手深入理解 Django 項目。首先，你需要安裝它，然後配置 AI 工具以連接到 MCP 服務器。完成這些步驟後，就能向 AI 助手詢問有關項目的各種問題，如模型信息、數據庫架構等。

✨ 主要特性

• 項目發現：列出模型、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 傳輸
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 是一款流行的由 AI 驅動的代碼編輯器，內置 MCP 支持。

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. 當你以“Agent”模式開始對話時，Github Copilot Code 將自動連接到 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 Servers 部分添加 MCP 服務器配置：

{
  "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

# 服務器發送事件（SSE）傳輸（默認：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 模型，包括字段、類型、最大長度、空/空白狀態和關係。
   • 參數：
     • 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 是什麼？"
• "反轉 'post_detail' URL 模式，主鍵為 10。"
• "給我展示所有已發佈的博客帖子。"
• "獲取按創建日期排序的最近 10 篇帖子。"
• "查找博客中的所有特色帖子。"
• "給我展示最近的錯誤日誌。"

使用提示

• "使用 'search_django_docs' 提示搜索 'models'" - 獲取有關查找 Django 模型文檔的幫助。
• "在 Django 文檔中搜索 'authentication'" - 瞭解 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/ 目錄包含一個完整的 Django 應用程序，用於測試所有 MCP 工具。有關測試項目結構的詳細信息，請參閱 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+

貢獻指南

我們歡迎社區的貢獻！無論是修復 bug、添加新功能、改進文檔還是報告問題，你的幫助都非常寶貴。

開始貢獻

1. 在 GitHub 上 fork 倉庫。
2. 克隆你的 fork 到本地：

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: 用於修復 bug。
• docs: 用於文檔更改。
• chore: 用於維護任務。
• test: 用於測試更改。
• refactor: 用於代碼重構。

5. 推送到你的 fork：

git push origin feature/your-feature-name

6. 在 GitHub 上從你的 fork 向主倉庫 創建一個 Pull Request。

貢獻準則

• 代碼質量：確保你的代碼通過代碼檢查（ruff check）和格式化（ruff format）。
• 測試：為新功能添加測試，並確保現有測試通過。
• 文檔：為新功能更新 README 和相關文檔。
• 提交信息：使用清晰、描述性的提交消息，遵循 Conventional Commits。
• Pull Request：提供清晰的描述，說明你的 PR 做了什麼以及為什麼。
• 問題：在創建新問題之前，先檢查現有問題。

貢獻方向

我們特別感興趣的貢獻包括：

• 新的 MCP 工具：添加新工具以暴露更多 Django 功能。
• 修復 bug：修復 GitHub Issues 中報告的問題。
• 文檔：改進設置指南、添加示例或澄清現有文檔。
• 測試：擴展現有功能的測試覆蓋範圍。
• 性能：優化緩慢的操作或減少內存使用。
• 兼容性：確保與不同的 Django 版本兼容。

需要幫助？

• 查看現有代碼以獲取示例。
• 打開一個 GitHub Issue 進行提問或討論。
• 查看已關閉的 PR，瞭解其他人是如何貢獻的。

行為準則

請在所有交互中保持尊重和建設性。我們致力於維護一個友好和包容的社區。

商業支持

本項目由 Vinta Software 維護。我們的設計和開發專家團隊可以幫助你的公司成功推出基於 Django 的產品。如果你需要任何商業支持，請隨時聯繫：contact@vinta.com.br

📄 許可證

本項目採用 MIT 許可證，詳情請參閱 LICENSE 文件。