django-telescope

Django AI Boost

一个用于开发 Django 应用的 Model Context Protocol（MCP）服务，灵感来自 Laravel Boost。此服务通过 MCP 工具公开 Django 项目信息，使 AI 助手能够更好地理解和操作 Django 代码库。

目录

• 功能
• 截图
• 安装
  • 面向最终用户
  • 面向开发者
• 用法
  • 运行服务
  • 身份验证
• AI 工具配置
  • Cursor
  • Claude Desktop
  • Github Copilot（VS Code）
  • Claude Code（VS Code）
  • OpenAI ChatGPT Desktop
  • Cline（VS Code）
  • Zed Editor
  • 通用 MCP 客户端
• 可用工具
• 使用示例
• 开发与测试
• 故障排查
• 要求
• 参与贡献
• 许可证

功能

• 项目发现：列出模型、URL 和管理命令
• 数据库内省：查看架构、迁移和关系
• 配置访问：使用点号表示法查询 Django 设置
• 日志读取：通过筛选访问近期应用日志
• 适用于生产环境的身份验证：通过 Bearer 令牌身份验证确保部署安全
• 只读：所有工具均为安全的只读操作
• 快速：基于 FastMCP 构建，支持高效的异步操作

截图

点击查看截图

Django AI Boost 实际运行效果

Django AI Boost MCP 服务通过 AI 助手提供 Django 项目内省功能（示例使用 OpenCode）

安装

面向最终用户

# Using uv (recommended)
uv pip install django-ai-boost

# Or with pip
pip install django-ai-boost

面向开发者

如果你想参与贡献或运行最新的开发版本：

# Clone the repository
git clone https://github.com/vinta/django-ai-boost.git
cd django-ai-boost

# Install uv if you haven't already
# On macOS/Linux:
curl -LsSf https://astral.sh/uv/install.sh | sh

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

# Install dependencies (creates virtual environment automatically)
uv sync --dev

# Verify installation
uv run django-ai-boost --help

用法

运行服务

服务需要访问 Django 项目的设置：

# Set the Django settings module
export DJANGO_SETTINGS_MODULE=myproject.settings
django-ai-boost

# Or specify settings directly
django-ai-boost --settings myproject.settings

# Run with SSE transport (default is stdio, which doesn't use network ports)
django-ai-boost --settings myproject.settings --transport sse

# Run with SSE transport on a custom port (default port is 8000)
django-ai-boost --settings myproject.settings --transport sse --port 3000

# Run with SSE transport on custom host and port
django-ai-boost --settings myproject.settings --transport sse --host 0.0.0.0 --port 8080

**注意：**stdio 传输（默认）通过标准输入/输出进行通信，不使用网络端口。--port 和 --host 选项仅适用于使用 --transport sse 的情况。

身份验证

Django AI Boost 支持在使用 SSE 传输时通过 Bearer 令牌身份验证来保障生产部署的安全。

快速开始

设置身份验证令牌（生产环境推荐）：

export DJANGO_MCP_AUTH_TOKEN="your-secret-token"
django-ai-boost --settings myproject.settings --transport sse

或使用 CLI 参数：

django-ai-boost --settings myproject.settings --transport sse --auth-token "your-secret-token"

工作原理

• 自动生产模式：当 Django 的 DEBUG=False 且使用 SSE 传输时，会自动要求进行身份验证
• 令牌优先级：出于安全考虑，环境变量的优先级高于 CLI 参数
• 传输支持：
  • ✅ SSE 传输：完整支持身份验证（基于 HTTP）
  • ❌ Stdio 传输：不进行身份验证（仅限本地、可信环境）
• 令牌不匹配时出错：如果在 --transport stdio 下提供 --auth-token，服务将退出并报错，以防产生错误的安全假设

生产环境部署

在生产环境（DEBUG=False）使用 SSE 传输时，必须提供身份验证令牌：

# This will fail without a token
django-ai-boost --settings myproject.production_settings --transport sse
# Error: Production mode detected but no authentication token provided

# This works
export DJANGO_MCP_AUTH_TOKEN="strong-secret-token"
django-ai-boost --settings myproject.production_settings --transport sse
# Authentication enabled with bearer token for SSE transport

安全最佳实践

1. 生成强令牌：

   python -c "import secrets; print(secrets.token_urlsafe(32))"
   

2. 切勿将令牌提交到版本控制系统

3. 在生产环境中使用环境变量（而非 CLI 参数）

4. 定期轮换令牌

5. 通过反向代理为外部访问启用 HTTPS

使用身份验证配置客户端

使用身份验证时，请配置 MCP 客户端，使其包含令牌：

Cursor / Claude Desktop：

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

使用 curl 测试：

# Without auth - fails
curl http://127.0.0.1:8000/sse

# With correct token - works
curl -H "Authorization: Bearer your-secret-token" http://127.0.0.1:8000/sse

身份验证故障排除

“检测到生产模式，但未提供身份验证令牌”

• 设置 DJANGO_MCP_AUTH_TOKEN 环境变量，或使用 --auth-token

“已提供身份验证令牌，但传输方式为 'stdio'”

• 现在这会导致错误，并阻止服务启动
• 身份验证仅适用于 --transport sse
• 请使用 --transport sse 并提供令牌，或在使用 stdio 时移除 --auth-token 参数

“在生产模式下使用 stdio 传输”

• 在本地／可信环境中这样做没问题，但 stdio 不具备身份验证功能
• 如需远程访问，请使用 --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": [
  // The "inputs" section defines the inputs required for the MCP server configuration.
  {
    "type": "promptString"
  }
],
"servers": {
  // The "servers" section defines the MCP servers you want to use.
  "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 与 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 的客户端，都可以手动运行服务：

# Standard I/O transport (default, no network port)
django-ai-boost --settings myproject.settings

# Server-Sent Events transport (default: 127.0.0.1:8000)
django-ai-boost --settings myproject.settings --transport sse

# SSE transport with custom port
django-ai-boost --settings myproject.settings --transport sse --port 3000

# SSE transport with custom host and port
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 模式及其名称、模式和视图处理程序（包括嵌套的 include）。

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. run_check

运行 Django 系统检查，以发现模型、设置和部署配置中的潜在问题。

参数：

• app_labels：可选的待检查应用标签列表
• tags：可选的检查标签列表（例如，“models”、“compatibility”）
• deploy：为 true 时，包含部署检查
• fail_level：最低严重级别（“CRITICAL”、“ERROR”、“WARNING”、“INFO”、“DEBUG”）
• databases：可选的待包含数据库别名列表

12. read_recent_logs

读取在 LOGGING.handlers 中配置的基于文件的日志处理器中的最新行。

参数：

• lines：每个文件返回的行数（默认值：100，可通过 DJANGO_MCP_MAX_LOG_LINES 环境变量配置）
• handler_name：可选的处理器名称，用于指定从单个文件处理器读取

注意： 此工具仅读取基于文件的处理器（*FileHandler 类）。如果项目仅将日志输出到控制台，请在 Django LOGGING 设置中配置 FileHandler，以便 AI 访问日志输出。示例：

LOGGING = {
    "version": 1,
    "handlers": {
        "file": {
            "class": "logging.FileHandler",
            "filename": "django.log",
        },
    },
    "root": {"handlers": ["file"], "level": "INFO"},
}

提示词

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 模式”
• “users 表的数据库架构是什么？”
• “有没有尚未应用的迁移？”
• “DEBUG 设置的值是什么？”
• “ID 为 5 的博客文章的 URL 是什么？”
• “使用 pk=10 反向解析 'post_detail' URL 模式”
• “显示所有已发布的博客文章”
• “按创建日期排序，获取最近的 10 篇文章”
• “查找博客中所有精选文章”
• “显示最近的错误日志”

使用提示词：

• “使用 search_django_docs 提示词搜索 ‘models’”——获取查找 Django 模型文档的帮助
• “搜索 Django 文档中的 ‘authentication’”——了解 Django 身份验证
• “显示有关 ‘migrations’ 的 Django 文档”——了解迁移最佳实践和指南

开发与测试

项目包含全面的测试套件和一个用于开发的 Django 测试项目：

# Run all tests with pytest
uv run pytest

# Run broad integration coverage
uv run pytest test_server.py

# Run focused MCP tool tests
uv run pytest test_auth_logic.py test_prompt.py test_query_model.py test_read_recent_logs.py test_run_check.py

# Run the MCP server with the test project
export PYTHONPATH="${PYTHONPATH}:./fixtures/testproject"
uv run django-ai-boost --settings testproject.settings

# Run linter
uv run ruff check .

# Auto-fix linting issues
uv run ruff check --fix .

# Format code
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 开发服务器）占用。请使用其他端口：

# Use a different port for the MCP server
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 应用筛选模型：

# Instead of listing all models (may truncate):
list_models()

# Filter by specific app(s):
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 3.2.4+

许可证

MIT 许可证 - 详情请参阅 LICENSE 文件。

灵感来源

本项目的灵感来自 Laravel Boost，它为 Laravel 应用提供类似的 MCP 功能。

参与贡献

我们欢迎社区贡献！无论是修复错误、添加新功能、改进文档还是报告错误，我们都非常感谢您的帮助。

开始

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
   # or
   git checkout -b fix/your-bug-fix
   

开发工作流

1. 在你的功能分支中进行更改
2. 遵循代码风格：

   # Check code style
   uv run ruff check .
   
   # Auto-fix style issues
   uv run ruff check --fix .
   
   # Format code
   uv run ruff format .
   

3. 测试你的更改：

    # Run the test suite
    uv run pytest
   

Run broad integration coverage

uv run pytest test_server.py

# Test with the fixture project
export PYTHONPATH="${PYTHONPATH}:./fixtures/testproject"

uv run django-ai-boost --settings testproject.settings

4. **提交你的更改**：
```bash
git add .
git commit -m "feat: add new feature" # or "fix: resolve bug"

我们遵循 Conventional Commits：

• feat: 用于新功能
• fix: 用于错误修复
• docs: 用于文档更改
• chore: 用于维护任务
• test: 用于测试更改
• refactor: 用于代码重构

5. 推送到你的 Fork：

   git push origin feature/your-feature-name
   

6. 在 GitHub 上从你的 Fork 向主仓库创建 Pull Request

贡献指南

• 代码质量：确保代码通过 lint 检查（ruff check）和格式化（ruff format）
• 测试：为新功能添加测试，并确保现有测试通过
• 文档：为新功能更新 README 和相关文档
• 提交：遵循 Conventional Commits，使用清晰、描述性的提交消息
• Pull Request：清楚说明 PR 的内容和原因
• 问题：创建新问题前，请先查看现有问题

可以贡献的内容

我们尤其欢迎：

• 新的 MCP 工具：添加新工具以提供更多 Django 功能
• 错误修复：修复 GitHub Issues 中报告的问题
• 文档：改进设置指南、添加示例或阐明现有文档
• 测试：扩展现有功能的测试覆盖率
• 性能：优化耗时操作或减少内存使用
• 兼容性：确保兼容不同的 Django 版本

需要帮助？

• 查看现有代码以获取示例
• 如有问题或想讨论，请创建 GitHub Issue
• 查看已关闭的 PR，了解其他人的贡献方式

行为准则

请在所有互动中保持尊重并提出建设性意见。我们致力于维护一个友好、包容的社区。

商业支持

本项目由 Vinta Software 维护。我们的设计和开发专家团队可帮助贵公司推出成功的 Django 产品。如需商业支持，欢迎联系我们：[email protected]