fastmcp-django

FastMCP 与 Django

使用 FastMCP 向 Agent 暴露小型、带类型的 Django 应用功能。 将认证、权限、验证、模型、事务和业务规则的唯一可信来源保留在 Django 中。将 FastMCP 视为现有应用服务外层的协议层。

工具选择

• 在 Django 中开展新的 Python MCP 工作时，优先使用独立的 fastmcp 包（from fastmcp import FastMCP）。
• 如果项目已统一使用官方 MCP Python SDK（from mcp.server.fastmcp import FastMCP）、需要更底层的协议控制，或宿主明确要求 SDK 行为，则使用该 SDK。
• 只有在项目需要可在 WSGI 中运行的 Django 原生包，或需要以声明方式暴露模型/DRF API 时，才考虑使用 django-mcp-server。暴露私有数据前，请审核生成的工具契约和权限。
• 如果应用已有明确设计的公共 OpenAPI 接口，生成或代理工具有助于快速起步。对于生产环境中的 Agent，优先采用精心设计的工具，提供用途明确的名称、架构、权限和受限输出。

FastMCP 文档跟踪项目的 main 分支，因此依赖近期新增的功能或版本徽章时，请重新查看最新文档。

资源路由

仅加载当前任务所需的文件：

需求	阅读
在现有 Django 应用中的分步实现	workflows/add-fastmcp-to-django.md
Stdio、HTTP sidecar、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 sidecar。
   • 如果应用已运行在 ASGI 下，且有意共享进程/域名，请将 FastMCP 挂载到 Django ASGI 进程中。
3. 将 MCP 服务注册代码放在小型模块中，例如 apps/core/mcp.py 或 project/mcp.py。
4. 保持工具主体精简。调用现有服务、选择器、表单、 序列化器、策略方法或领域函数。
5. 在接入传输方式前，通过 fastmcp.Client 添加测试。大多数行为 都应在内存中测试，无需运行 Web 服务。

核心规则

• 明确声明每项对外暴露的功能。避免通用 SQL、通用模型 浏览、任意导入、文件路径访问或“管理”工具，除非项目有明确的允许列表和授权方案。
• 使用带类型的参数、Pydantic 约束、返回类型注解、 文档字符串，以及规模较小且可序列化为 JSON 的返回值。
• 传递持久标识符，而不是 Django 模型实例、请求对象、惰性 查询集、打开的文件或超大载荷。
• 对列表/搜索工具进行分页和数量上限控制。返回稳定 ID 和摘要，而非完整模型转储。
• 从经过验证的认证上下文或可信依赖项中注入当前用户/账户。在生产环境中，绝不让模型提供特权身份字段。
• 对常规 Django ORM 操作，使用同步 def FastMCP 工具，除非项目有明确的异步设计。
• 对于长时间运行的 MCP 进程，在 ORM 操作前后调用 close_old_connections()，或将连接清理集中到精简的辅助函数中。
• 为耗时或依赖外部服务的工具添加超时。将长时间运行的工作放入队列，而不是让 MCP 请求一直保持打开状态。

验证

• 当工具契约很重要时，使用 fastmcp list 或 fastmcp inspect 检查工具名称、架构和描述。
• 对每个受权限控制的工具，测试获准用户和未获准用户。
• 测试无效输入、缺失对象、分页上限、破坏性操作确认、数据库状态变更，以及 transaction.on_commit 的副作用。
• 当 ASGI 挂载、身份验证标头、代理行为或 URL 路径发生变更时，添加一个 HTTP 传输冒烟测试。

参考资料

• 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/