Deer-Flow 的 MCP 集成与多模型适配

Deer-Flow 的 MCP 集成与多模型适配

学习目标

• 理解 Deer-Flow 的 MCP 多服务器管理和 OAuth 认证
• 掌握反射式模型加载和 vLLM 本地部署适配
• 学会配置多模型路由和特性开关

前置知识

本章涉及 MCP 协议和多模型适配的通用原理，建议先阅读：

• MCP 多服务器管理：工具发现与 OAuth 集成
• 反射式模型加载：多 Provider 动态适配

下文假设你已理解上述概念，直接聚焦 Deer-Flow 的具体实现。

---

项目实践

MCP 多服务器管理

Deer-Flow 使用 langchain-mcp-adapters 的 MultiServerMCPClient 管理多个 MCP 服务器：

特性	实现
懒加载	工具在首次使用时加载，不阻塞启动
缓存失效	检测 extensions_config.json 的 mtime 变化
传输协议	stdio（本地）、SSE（远程）、HTTP（远程）
OAuth	HTTP/SSE 传输支持 client_credentials 和 refresh_token 流
运行时更新	Gateway API 保存到配置文件，LangGraph 通过 mtime 检测

MCP 服务器配置存储在 extensions_config.json 中，包含 mcpServers 和 skills 两个顶层键。

模型工厂（Model Factory）

create_chat_model(name, thinking_enabled) 通过反射机制动态加载 LLM Provider：

# Deer-Flow 支持的模型配置模式
models:
  # 标准 OpenAI 兼容
  - name: gpt-4o
    use: langchain_openai:ChatOpenAI

  # OpenRouter 网关
  - name: openrouter-gemini-2.5-flash
    use: langchain_openai:ChatOpenAI
    base_url: https://openrouter.ai/api/v1

  # OpenAI Responses API（/v1/responses）
  - name: gpt-5-responses
    use: langchain_openai:ChatOpenAI
    use_responses_api: true
    output_version: responses/v1

  # vLLM 本地部署
  - name: qwen3-32b-vllm
    use: deerflow.models.vllm_provider:VllmChatModel

  # CLI 后端 Agent
  - name: codex-cli
    use: deerflow.models.openai_codex_provider:CodexChatModel

  - name: claude-code
    use: deerflow.models.claude_provider:ClaudeChatModel

vLLM Provider 的特殊处理

VllmChatModel 继承 langchain_openai:ChatOpenAI，针对 vLLM 0.19.0 做了特殊处理：

• 保留 reasoning 字段：vLLM 的非标准 assistant reasoning 字段在多轮工具调用对话中保留和传递
• 思考模式兼容：支持 when_thinking_enabled.extra_body.chat_template_kwargs.enable_thinking（新版）和 thinking（旧版）两种配置，自动归一化
• 缺失模块提示：Provider 模块未安装时提供可操作的安装命令

CLI 后端 Agent（ACP）

Deer-Flow 支持通过 ACP 协议调用外部 CLI Agent（如 Codex CLI、Claude Code）：

• 每个 ACP Agent 使用 per-thread workspace（/mnt/acp-workspace/，只读）
• Docker 沙箱模式下通过 volume mount 挂载
• 缺失 ACP 可执行文件时返回可操作的错误消息

---

问题与规避

MCP 服务器不可用

MCP 服务器可能未启动或网络不可达。

Deer-Flow 的规避：懒加载 + 超时重试，失败时降级为不可用而非阻塞 Agent。

vLLM 思考模式与工具调用的协调

部分模型在思考模式下可能改变工具调用的行为。

Deer-Flow 的规避：在系统提示中明确工具调用的期望格式，通过 when_thinking_enabled 配置精确控制思考模式的请求体。

---

参考来源

• Deer-Flow CLAUDE.md — MCP System 和 Model Factory 章节
• packages/harness/deerflow/mcp/ — MCP 源码
• packages/harness/deerflow/models/ — 模型工厂源码