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 文件。